启动 9Router 报 EADDRINUSE（端口 20128 被占用）怎么排查？

启动 9Router 报 EADDRINUSE端口 20128 被占用怎么排查【免费下载链接】9routerUnlimited FREE AI coding. Connect Claude Code, Codex, Cursor, Cline, Copilot, Antigravity to FREE Claude/GPT/Gemini via 40 providers. Auto-fallback, RTK -40% tokens, never hit limits.项目地址: https://gitcode.com/GitHub_Trending/9r/9router运行9router启动服务时终端抛出下面这个错误说明默认服务端口 20128 已经被别的进程或上一次没退干净的 9Router 实例占住了Error: listen EADDRINUSE: address already in use :::201289Router 的默认端口是20128控制面板和 OpenAI 兼容 APIhttp://localhost:20128/v1都挂在同一个端口上。本文只处理这一种报错定位占用 20128 的进程然后要么结束它、要么换一个端口启动最后用文档给出的健康检查确认服务真的起来了。排查依据来自 安装文档、本地部署文档 和 故障排除文档。先确认报错与端口EADDRINUSE的完整形式是listen EADDRINUSE: address already in use :::20128报错里的端口号直接告诉你冲突发生在 20128。如果端口号不是 20128说明你启动时改过端口下面的命令把20128换成实际报错中的端口即可。两条排查路径对应两种处理策略路径 A主路径20128 被残留的 9Router 进程或可安全终止的进程占用 → 找到 PID 并结束该进程再用原端口启动路径 B可选分支端口被其他服务长期占用、不方便动 → 换端口启动 9Router。路径 A找到占用进程并结束它macOS / Linux安装文档给出的步骤是先查、后杀# 找到占用 20128 端口的进程输出中会列出 PID lsof -i :20128 # 结束该进程PID 替换为上面 lsof 输出中的进程号 kill -9 PIDkill -9是强制终止。执行前先核对lsof输出确认这个 PID 是之前遗留的 9Router 实例或其他可以安全关掉的进程再执行避免误杀无关服务。Windows故障排除文档中针对 20128 的检查命令是netstat -ano | findstr :20128输出中最后一列是 PID用文档在进程清理场景中给出的 Windows 强杀命令结束它taskkill /PID PID /FPID替换为netstat输出里的进程号。注意强杀前同样先确认这个 PID 对应的进程可以终止。重新启动并确认数据未受影响结束进程后直接重新运行9router即可。配置、API keys 和 combos 都保存在数据目录~/.9router重启不会丢失这些内容。路径 B换端口启动可选如果 20128 被一个不方便终止的服务长期占用可以改用其他端口启动。安装文档给出的命令行方式9router --port 3000CLI 的--help也确认了这个参数-p, --port port Port to run the server (default: 20128)3000只是文档示例值可替换为任意空闲端口。文档还给出了通过环境变量PORT配置端口的方式见 安装文档“端口配置”一节。换端口有一个连带影响客户端配置里写的是http://localhost:20128/v1README 中 Cursor、Cline、Copilot 等集成示例都是这个地址端口换掉后这些 Base URL 要同步改成新端口否则客户端仍然连不上。验证服务已正常监听重启后按安装文档的验证方式确认curl http://localhost:20128/health文档给出的预期响应文档示例version以实际版本为准{ status: ok, version: 1.0.0 }返回status: ok即说明服务在 20128 上正常监听。如果走了路径 B把 URL 中的20128换成实际使用的端口再检查。另外可以用lsof -i :20128再确认一次此时输出里应当是当前的 9Router 进程而不是之前的冲突进程。两个需要注意的点文档间对“改端口”的描述不一致本地部署文档 提到 “API port (20128) and dashboard port (3000) are configured in the application. To change them, youll need to modify the source code or use environment variables if supported”没有提到命令行参数而 安装文档 和 CLI 自带的帮助文本都明确支持--port/-p。实际操作以安装文档和9router --help输出为准。区分 EADDRINUSE 与 ECONNREFUSED如果是客户端连不上并看到ECONNREFUSED/ “Cannot connect to localhost:20128”那通常是 9Router 根本没在运行或端口被防火墙挡住属于 故障排除文档 中 “Connection Refused” 一节的问题和端口被占用不是同一件事排查顺序是确认进程在跑、lsof -i :20128能看到监听、再检查防火墙。完成以上任一路径、/health返回ok后端口冲突即已解除如果lsof里 20128 反复出现新的陌生进程说明有别的服务在持续占用此时应改用路径 B 固定使用另一个端口而不是反复强杀。【免费下载链接】9routerUnlimited FREE AI coding. Connect Claude Code, Codex, Cursor, Cline, Copilot, Antigravity to FREE Claude/GPT/Gemini via 40 providers. Auto-fallback, RTK -40% tokens, never hit limits.项目地址: https://gitcode.com/GitHub_Trending/9r/9router创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考