9Router 本地部署完全指南：安装、启动、配置与运维-开发者社区

9Router 本地部署完全指南：安装、启动、配置与运维

【免费下载链接】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 的本地部署展开，面向需要在开发环境或个人机器上独立运行 9Router 网关的开发者。9Router 是一个把 Claude Code、Codex、Cursor、Cline、Copilot、Antigravity 等 AI 编码工具连接到 40+ 免费或订阅制模型提供商的统一网关，本地部署是它的默认运行方式。读完本文，你将掌握npm全局安装、单命令启动、DATA_DIR与端口等关键配置、优雅停止/重启、版本更新、常见故障排查，以及数据目录的备份恢复，并了解这些操作背后的 CLI 源码实现。

📦 安装：环境要求与 npm 全局安装

9Router 通过 npm 以全局方式安装，一条命令即可完成：

npm install -g 9router

环境要求：

Node.js 20 或更高版本
npm 9 或更高版本

从源码看，发布包由 cli/package.json 定义：bin字段将全局9router命令映射到cli/cli.js，安装时还会执行postinstall钩子（cli/hooks/postinstall.js），预先把 SQLite 运行时依赖写入数据目录，避免首次启动时联网等待。

需要注意：engines字段中声明的最低 Node.js 版本为>=18.0.0，但官方文档建议使用 Node.js 20+，以匹配 Next.js 16 与最新运行时的要求。如果命令输出提示 Node 版本过旧，请先升级 Node.js。

安装后可验证版本与可执行文件是否就绪：

# 查看全局安装的 9router 版本 npm list -g 9router # 查看 CLI 自带版本号（等价于 -v） 9router --version

安装权限问题的两种解法

如果在全局安装时遇到EACCES权限错误，文档给出两种处理方式：

方式一：使用 sudo（不推荐）

sudo npm install -g 9router

方式二：修正 npm 全局目录权限（推荐）——把 npm 全局包安装到用户目录，避免对系统目录的写权限依赖：

mkdir ~/.npm-global npm config set prefix '~/.npm-global' echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc source ~/.bashrc

配置完成后重新执行npm install -g 9router即可。

🚀 启动服务器：一条命令跑起完整网关

安装完成后，在任意终端执行：

9router

启动时发生了什么

从 cli/cli.js 的启动流程可以看到，9router命令不只是简单拉起进程，而是一套完整的生命周期管理：

自愈运行时依赖：调用ensureSqliteRuntime()与ensureTrayRuntime()，把sql.js（必需）与better-sqlite3（可选加速项）装进数据目录的runtime/node_modules，失败仅告警不阻塞（见 cli/hooks/sqliteRuntime.js）。
清理旧进程：通过killAllAppProcesses()与killProcessOnPort()结束残留的 9router 进程并释放目标端口——进程白名单只匹配node ...9router...cli.js与next-server，不会误杀编辑器等其他程序。
并行检查更新：checkForUpdate()以 8 秒安全超时异步查询 npm registry，不影响服务启动的关键路径。
拉起服务进程：用独立 Node 进程运行打包好的 Next.js standalone 服务器（优先custom-server.js），并注入PORT、HOSTNAME与NODE_PATH环境变量。
探活后进入界面菜单：waitServerReady()每 150ms 探测一次端口（15 秒超时），就绪后弹出交互菜单，提供Web UI（浏览器打开）、Terminal UI（终端交互界面）、Hide to Tray（后台托盘）、Exit（退出）四个选项，以及可选的"更新到新版本"入口。

默认绑定地址为0.0.0.0。启动时若检测到局域网 IP，CLI 会打印黄色警告提示服务已暴露到网络：

⚠ Network-exposed: reachable at http://<LAN-IP>:20128 (bound 0.0.0.0). Use --host 127.0.0.1 for local-only.

默认配置速览

项目	默认值
控制台/API 端口	`20128`（CLI 默认`DEFAULT_PORT`，见 cli/cli.js）
控制台地址	`http://localhost:20128/dashboard`（服务端口 +`/dashboard`路径）
OpenAI 兼容 API 端点	`http://localhost:20128/v1`
数据目录	`~/.9router`（macOS/Linux）；Windows 为`%APPDATA%\9router`

兼容性说明：部署文档中标注的控制台端口为3000，而当前源码默认端口统一为20128，控制台与 API 同端口、以路径区分。请以当前版本的9router --help输出为准。

启动后浏览器通常会自动打开控制台（各平台分别使用open、start、xdg-open）。如果自动打开失败，终端会提示手动访问地址。

🔧 配置：数据目录、端口与更多 CLI 参数

自定义数据目录

通过环境变量DATA_DIR指定数据存放位置：

DATA_DIR=/path/to/data 9router

其底层实现在 src/lib/dataDir.js：设置DATA_DIR时会递归创建该目录；在 Windows 上如果传入的是 Unix 风格绝对路径（如来自 Linux 环境的.env或 Docker 配置），会回退到默认目录；如果目录不可写（EACCES/EPERM），同样回退到~/.9router并打印告警。因此DATA_DIR适合在多实例、多环境或需要将数据放在独立磁盘的场景下使用。

自定义端口与主机

CLI 原生支持通过参数覆盖默认端口和绑定地址，这是比改源码更推荐的配置方式：

# 指定 API/控制台端口 9router --port 8080 # 等价于 -p 8080 # 仅绑定本机回环地址（不暴露到局域网） 9router --host 127.0.0.1 # 等价于 -H 127.0.0.1

完整的 CLI 参数（来自 cli/cli.js 的--help输出）：

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

端口冲突时 CLI 会先尝试自动释放；--host 127.0.0.1可关闭网络暴露，适用于仅本机使用的安全场景。

🛑 停止与 🔄 重启

优雅停止

在运行9router的终端中按Ctrl+C：

# 在运行 9router 的终端中 ^C # 按下 Ctrl+C

CLI 监听了SIGINT/SIGTERM/SIGHUP信号，退出前会依次清理托盘、MITM 代理进程（通过 PID 文件优雅终止）以及隧道进程（cloudflared/tailscale），最后强制结束服务子进程并退出，保证数据落盘。

重启

重启只需再次执行启动命令：

9router

所有配置、API 密钥、Combo（组合路由）都持久化在数据目录中，重启后自动恢复，无需重新配置。

📊 更新 9Router

更新到最新版本：

npm update -g 9router

查看当前安装的版本：

npm list -g 9router

CLI 在启动时会自动比对 npm registry 上的最新版本（仅在--skip-update未指定时），若发现新版本会在交互菜单顶部提供 "Update to vX.Y.Z" 选项；选择后 CLI 会提示退出并执行npm i -g 9router@latest --prefer-online。此外，CLI 内置了崩溃自愈逻辑：服务进程异常退出后最多自动重启 2 次（重启间隔 1s → 2s），若运行稳定超过 30 秒则重置计数；连续崩溃时会自动禁用 MITM 相关设置后再次拉起，降低环境兼容问题导致的启动失败率。

🔍 故障排查

端口已被占用

当20128或3000端口被其他进程占用时，可用lsof定位并结束占用进程（macOS/Linux）：

# 查找占用端口的进程 lsof -i :20128 lsof -i :3000 # 结束该进程 kill -9 <PID>

Windows 下可用netstat -ano | findstr :20128配合taskkill /F /PID <PID>。实际上，CLI 启动时会先执行killProcessOnPort()自动尝试释放端口（macOS/Linux 用lsof -ti:<port>，Windows 用netstat+taskkill），多数场景无需手动处理；上述命令适用于服务未启动但仍需清理端口的情况。

权限错误

安装阶段权限问题的处理见上文"安装权限问题"一节。若服务运行时出现数据目录不可写，检查目录权限：

ls -la ~/.9router chmod 755 ~/.9router

数据目录问题

DATA_DIR指向的目录不存在或不可写时，程序会自动回退到默认目录并打印告警（见上文"自定义数据目录"）。若~/.9router本身异常，可备份后重建：

ls -la ~/.9router # 检查权限与内容

服务器反复崩溃

若服务启动后频繁退出，CLI 会打印最近 50 行崩溃日志便于定位，并在连续崩溃 2 次后尝试禁用 MITM 相关配置重启。可结合-l/--log参数在前台观察完整服务日志。

📁 数据目录结构与备份

数据目录（默认~/.9router）的核心结构如下：

~/.9router/ ├── db.json # 主数据库（提供商、Combo、设置） ├── logs/ # 应用日志 ├── cache/ # 临时缓存文件 └── runtime/ # 运行时依赖（sql.js / better-sqlite3 等）

其中db.json是配置的中枢（提供商、Combo、全局设置），由数据库层读写；runtime/存放运行时自愈安装的 SQLite 引擎，保证better-sqlite3原生模块位于用户可写目录，避免全局更新 CLI 时在 Windows 上出现文件占用（EBUSY）问题。

备份与恢复：

# 备份 cp -r ~/.9router ~/.9router.backup # 恢复 cp -r ~/.9router.backup ~/.9router

若使用了DATA_DIR自定义目录，将命令中的~/.9router替换为实际路径即可。迁移到新机器时，复制整个数据目录并在新机器上执行DATA_DIR=/path/to/data 9router即可无缝接管原有配置。

🔗 下一步

本地部署就绪后，可以继续阅读以下指南完成实际使用配置：

连接提供商：配置订阅型提供商与 API 密钥
创建 Combo：组合多个提供商实现自动切换与容灾
与 CLI 工具集成：将 Cursor、Claude Code 等工具接入 9Router 网关

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

9Router 本地部署完全指南：安装、启动、配置与运维