9Router 安装部署指南：全局安装、源码构建、Docker 与常见问题排查

9Router 是一个开源的 AI 路由网关，通过一条本地 HTTP 服务将 Claude Code、Codex、Cursor、Cline 等编码工具接入 40+ 模型供应商，并提供自动故障转移（Auto-fallback）、配额跟踪与 RTK 令牌压缩等能力。本文以官方西班牙语文档《Instalación》（gitbook/content/es/getting-started/installation.md）为主体，结合仓库源码，完整讲解从环境准备、三种安装方式、首次启动初始化、安装验证、环境变量配置，到故障排查、生产部署与卸载清理的全流程。读完本文，你将能够在本地、VPS 与 Docker 三种环境中正确安装并运维 9Router 网关，并能独立定位端口占用、权限不足、供应商连接失败等常见问题。

---

安装前准备：环境需求与版本检查

系统需求

在安装前，请先确认运行环境满足以下最低要求：

项目	要求
Node.js	20.0.0 或更高版本
npm	10.0.0 或更高版本（随 Node.js 一起安装）
操作系统	macOS、Linux、Windows（推荐使用 WSL）
磁盘空间	约 200MB（用于安装）

说明：仓库中 cli/package.json 的 engines 字段声明的是 node >= 18.0.0，这是 CLI 包可以运行的最低版本；官方文档建议使用 Node.js 20+ 以获得更稳定的体验，尤其是运行 Web Dashboard 与生产构建时（根目录 package.json 基于 Next.js 16 构建）。

验证当前版本

打开终端执行以下命令，确认 Node.js 与 npm 版本：

node --version
# 应显示 v20.x.x 或更高

npm --version
# 应显示 10.x.x 或更高

如果尚未安装 Node.js，请从 Node.js 官网下载对应平台的安装包（Windows 用户也可通过 WSL 环境使用包管理器安装）。

---

三种安装方式

9Router 提供全局安装、项目内本地安装、源码构建三种方式，分别对应"个人快速使用"、"项目隔离"与"开发调试/二次开发"三种场景。

方式一：全局安装（推荐）

全局安装后，9router 命令可以在任意目录下直接使用：

npm install -g 9router

启动网关：

9router

优点：

• ✅ 可从任意目录直接运行，无需切换到特定项目
• ✅ 命令简洁：9router
• ✅ 升级方便：npm update -g 9router

从源码看，cli/package.json 中通过 bin 字段将 9router 命令映射到 cli/cli.js，npm 全局安装后会自动在 PATH 中注册该命令；CLI 在启动时会向 npm registry 发起版本检查（对应 cli.js 的 checkForUpdate），发现新版本后会在交互菜单中提示你执行 npm i -g 9router@latest --prefer-online 完成升级。

方式二：项目内本地安装

如果希望把网关与某个具体项目绑定、避免污染全局命名空间，可以在项目内安装：

mkdir my-9router
cd my-9router
npm install 9router

启动网关（本地安装需要用 npx 调用）：

npx 9router

优点：

• ✅ 依赖与项目隔离，不同项目可以使用不同版本
• ✅ 版本可精确控制
• ✅ 不污染全局命名空间

方式三：从源码构建（开发模式）

如果想体验最新开发特性、参与贡献或进行自定义修改，可以从源码构建：

git clone https://gitcode.com/GitHub_Trending/9r/9router.git
cd 9router
npm install
npm run build
npm start

关于仓库结构与文档差异的说明： 原文档中的源码构建步骤为 cd 9router/app，但当前仓库的实际结构是：仓库根目录即为 Next.js Web 应用（根 package.json 的 name 为 9router-app），而 CLI 启动器位于 cli/ 子目录（cli/package.json 的 name 为 9router，bin 指向 cli.js）。因此从源码运行时需注意：

• 根目录执行 npm install && npm run build && npm start 启动的是 Web Dashboard 应用本身（开发端口为 20127，见根 package.json 的 dev/start 脚本）；
• 若要从源码构建 CLI 发布包，可在 cli/ 目录执行 npm install && npm run build（构建脚本为 node scripts/build-cli.js），产物用于 npm pack 或本地发布调试。

优点：

• ✅ 可获取最新开发特性
• ✅ 便于参与上游开发与提交 PR
• ✅ 可做个性化定制修改

---

首次启动与初始化

启动服务器

9router

启动过程会依次发生以下事情：

1. 服务器在 http://localhost:20128 启动
2. Dashboard 自动在浏览器中打开
3. 在 ~/.9router 创建数据目录（Windows 下为 %APPDATA%\9router）
4. 自动生成 API key

从 cli/cli.js 的实现看，启动流程是：先通过 killAllAppProcesses 与 killProcessOnPort 清理残留的 9Router 进程与端口占用，再以子进程方式拉起 standalone 服务器（设置 PORT、HOSTNAME 环境变量），并通过 waitServerReady 每 150ms 轮询 TCP 端口直到就绪，之后弹出交互式菜单（Web UI / Terminal UI / 隐藏到系统托盘 / 退出）。服务器默认绑定 0.0.0.0，若本机存在非回环 IPv4 地址，CLI 会提示网络暴露警告，建议局域网或公网环境下使用 --host 127.0.0.1 收紧监听范围。

常用 CLI 参数

除直接运行 9router 外，CLI 支持以下参数（与 cli/cli.js 中的参数解析逻辑一一对应）：

参数	简写	说明	默认值
--port <port>	-p	服务器监听端口	20128
--host <host>	-H	绑定地址	0.0.0.0
--no-browser	-n	不自动打开浏览器	关闭
--log	-l	在前台显示服务器日志（默认隐藏）	关闭
--tray	-t	以系统托盘后台模式运行	关闭
--skip-update	—	跳过启动时的自动更新检查	关闭
--help	-h	显示帮助信息	—
--version	-v	显示版本号	—

此外还提供了 xai video 子命令，用于通过正在运行的网关调用 Grok Imagine 视频生成接口（详见 9router xai video --help）。

Dashboard 登录

默认凭据：

• 密码：123456

⚠️ 请立即修改默认密码：

1. 登录 Dashboard
2. 进入 Settings → Change Password
3. 使用强密码替换默认密码

登录认证逻辑在仓库 src/app/api/auth/login/route.js 中实现，生产环境部署时务必同时通过环境变量设置强密码（见下文"环境变量配置"）。

获取你的 API key

Dashboard → Settings → API Keys
→ 复制你的 API key
→ 在 CLI 工具中使用

API key 示例格式：

9r_1234567890abcdef1234567890abcdef

---

验证安装是否成功

服务器启动后，建议依次执行以下三个验证步骤，确认网关核心链路（健康检查 → 模型列表 → Chat 补全）全部可用。

1. 验证服务器状态

curl http://localhost:20128/health

预期响应：

{
  "status": "ok",
  "version": "1.0.0"
}

2. 列出可用模型

curl http://localhost:20128/v1/models \
  -H "Authorization: Bearer your-api-key"

预期响应：

{
  "object": "list",
  "data": [
    {
      "id": "cc/claude-opus-4-5-20251101",
      "object": "model",
      "created": 1234567890,
      "owned_by": "claude-code"
    }
  ]
}

模型 ID 采用"供应商前缀/模型名"的命名格式（如 cc/ 对应 Claude Code、glm/ 对应 GLM），供应商与模型注册逻辑位于 src/models 与 open-sse/providers/registry 目录。

3. 测试 Chat Completion

curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "cc/claude-opus-4-5-20251101",
    "messages": [
      {"role": "user", "content": "Hello!"}
    ]
  }'

返回包含 choices 的 OpenAI 兼容响应即表示请求已成功路由到上游模型供应商。

---

配置详解

环境变量配置

可以创建 .env 文件或直接导出环境变量来配置网关：

# 安全（生产环境必填）
export JWT_SECRET="your-secure-secret-change-this"
export INITIAL_PASSWORD="your-password"

# 存储
export DATA_DIR="~/.9router"

# 服务器
export PORT="20128"
export NODE_ENV="production"

# 日志
export ENABLE_REQUEST_LOGS="false"

各变量的作用：

变量	作用	说明
JWT_SECRET	Dashboard 会话签名的密钥	生产环境必填，需使用足够长的随机字符串
INITIAL_PASSWORD	首次启动时的初始登录密码	覆盖默认密码 123456，生产环境必填
DATA_DIR	数据存储目录	默认 ~/.9router
PORT	服务器监听端口	默认 20128
NODE_ENV	运行环境标识	生产部署设置为 production
ENABLE_REQUEST_LOGS	是否记录请求日志	默认 false，开启后日志写入数据目录下的 logs/

从源码看，数据目录的解析逻辑位于 src/lib/dataDir.js：getDataDir() 优先读取 DATA_DIR 环境变量；在 Windows 平台上会忽略 Unix 风格绝对路径（如来自 Linux 目标 .env 的 /var/lib/...）并回退到默认目录；当配置的目录不可写（EACCES/EPERM）时也会自动回退到 ~/.9router。

数据目录结构

默认位置： ~/.9router

目录内容：

~/.9router/
  ├── db.json           # 数据库（providers、combos、usage）
  ├── api-keys.json     # API keys
  └── logs/             # 请求日志（启用后生成）

补充：在 Windows 平台，数据目录实际位于 %APPDATA%\9router（即 C:\Users\<用户>\AppData\Roaming\9router），这一平台差异在 cli/cli.js 的 getAppDataDir() 与 src/lib/dataDir.js 的 defaultDir() 中均有体现。

修改数据目录位置：

export DATA_DIR="/custom/path"
9router

端口配置

默认端口： 20128

通过环境变量修改：

export PORT="3000"
9router

通过命令行参数修改：

9router --port 3000

命令行参数与 PORT 环境变量取其一即可；从 cli/cli.js 可知 CLI 解析 --port 后会在启动子进程时以 PORT 环境变量传递给服务器。若使用 --host 127.0.0.1，服务器将只监听本机回环地址，外部设备无法访问——这在公网环境是推荐的安全实践。

---

故障排查

端口已被占用

错误信息：

Error: listen EADDRINUSE: address already in use :::20128

方案一：终止占用端口的进程

# 找到占用 20128 端口的进程
lsof -i :20128

# 终止该进程
kill -9 <PID>

方案二：改用其他端口

9router --port 3000

补充说明：CLI 在每次启动时本身就会尝试清理残留的 9Router 进程与端口占用（见 cli/cli.js 的 killAllAppProcesses 与 killProcessOnPort），因此若反复出现 EADDRINUSE，通常是其他程序占用了该端口，可用 lsof -i :20128 确认占用者后处理。

权限不足（EACCES）

错误信息：

Error: EACCES: permission denied, mkdir '/usr/local/lib/node_modules/9router'

方案：修复 npm 全局安装目录权限（推荐），而不是使用 sudo

# 将 npm 全局安装目录指向用户目录
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# 重新安装
npm install -g 9router

Node.js 版本过旧

错误信息：

Error: The engine "node" is incompatible with this module

方案：升级 Node.js

# 使用 nvm 升级（推荐）
nvm install 20
nvm use 20

# 或从 Node.js 官网下载新版安装包

Dashboard 无法自动打开

问题： 运行 9router 后浏览器没有自动打开 Dashboard。

方案一：手动访问

http://localhost:20128

方案二：检查防火墙

# macOS：在系统设置 → 安全性与隐私中允许 Node.js 接受入站连接
# Linux：检查 iptables 规则
# Windows：检查 Windows 防火墙放行规则

（CLI 支持用 --no-browser / -n 主动关闭自动打开行为，见上文 CLI 参数表。）

无法连接模型供应商

问题： OAuth 登录失败，或提示 API key 无效。

方案一：检查网络连通性

ping google.com

方案二：查看上游供应商服务状态

• Claude Code：查看 Anthropic 官方状态页
• OpenAI：查看 OpenAI 官方状态页
• Gemini：查看 Google Cloud 状态页

方案三：重新连接供应商

Dashboard → Provider → Disconnect → Reconnect

内存占用过高

问题： 9Router 进程占用内存过多。

方案：重启服务器

# 停止
pkill -f 9router

# 启动
9router

或使用 PM2 实现自动重启：

npm install -g pm2
pm2 start 9router --name 9router
pm2 save

补充：从 cli/cli.js 的实现看，服务器子进程以 --max-old-space-size=6144 启动（即上限约 6GB 堆内存），当服务器崩溃时会自动重试重启（最多 2 次，若 30 秒内再次崩溃将自动禁用 MITM 后重启）。对内存敏感的环境，可通过合理重启或减少并发连接控制占用。

---

部署选项

本地开发环境

npm install -g 9router
9router

适用场景： 个人编码、功能试用与本地调试。

VPS / 云服务器

# 安装
npm install -g 9router

# 配置生产环境变量
export JWT_SECRET="your-secure-secret"
export INITIAL_PASSWORD="your-password"
export NODE_ENV="production"

# 用 PM2 守护进程
npm install -g pm2
pm2 start 9router --name 9router
pm2 save
pm2 startup

适用场景： 团队共享访问、远程编码。

Docker 部署

docker pull 9router/9router:latest

docker run -d \
  -p 20128:20128 \
  -e JWT_SECRET="your-secure-secret" \
  -e INITIAL_PASSWORD="your-password" \
  -v 9router-data:/root/.9router \
  --name 9router \
  9router/9router:latest

适用场景： 容器化部署、Kubernetes 集群。

仓库证据：仓库根目录提供了完整的容器化支持——Dockerfile 基于 node:22-alpine 多阶段构建，将 PORT 默认设为 20128、DATA_DIR 设为 /app/data 并 EXPOSE 20128，以非 root 用户运行入口脚本后执行 node custom-server.js；docker-compose.yml 则编排了 9router 与 headroom（令牌压缩服务）两个服务，通过 9router-data 命名卷持久化数据；仓库根目录的 start.sh 展示了使用 .env 文件注入环境变量的 Docker 运行方式。此外 custom-server.js 会在反向代理场景下从 TCP socket 提取真实客户端 IP 并剥离外部伪造的 X-Forwarded-For 头，避免限流逻辑被伪造头绕过。

Nginx 反向代理

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:20128;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;

        # 支持流式输出（SSE）
        proxy_buffering off;
        proxy_read_timeout 86400;
    }
}

适用场景： 启用 HTTPS、绑定自定义域名、负载均衡。

注意：由于 9Router 的流式响应基于 SSE（Server-Sent Events），Nginx 配置中必须关闭代理缓冲（proxy_buffering off）并将读取超时调大（proxy_read_timeout 86400，即 24 小时），否则流式输出会被 Nginx 缓冲导致前端长时间无响应。

---

卸载

移除全局安装

npm uninstall -g 9router

删除数据目录

rm -rf ~/.9router

Windows 平台对应删除 %APPDATA%\9router 目录。

清理环境变量配置

# 编辑 shell 配置文件
nano ~/.bashrc   # 或 ~/.zshrc
# 删除其中与 9router 相关的 export 行

---

下一步

完成安装与验证后，可以继续阅读以下文档深化使用：

• 快速开始（Empezar） —— 5 分钟连接供应商并开始路由 AI 请求
• 功能特性 —— 配额跟踪、智能 Combos（自动故障转移）、部署相关能力
• 故障排查（Troubleshooting） —— 解决日常使用中的常见问题
• FAQ —— 常见问题与解答

安装完成后的核心动作是：立即修改默认密码 → 在 Dashboard 中连接供应商（OAuth / API Key / 免费供应商）→ 获取 API key 并配置到 Cursor、Claude Code、Cline 等工具 → 按需创建 Combos 实现自动故障转移。至此，9Router 网关即可正式接入你的编码工作流。