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。启动时若检测到局域网 IPCLI 会打印黄色警告提示服务已暴露到网络⚠ Network-exposed: reachable at http://LAN-IP:20128 (bound 0.0.0.0). Use --host 127.0.0.1 for local-only.默认配置速览项目默认值控制台/API 端口20128CLI 默认DEFAULT_PORT见 cli/cli.js控制台地址http://localhost:20128/dashboard服务端口 /dashboard路径OpenAI 兼容 API 端点http://localhost:20128/v1数据目录~/.9routermacOS/LinuxWindows 为%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的终端中按CtrlC# 在运行 9router 的终端中 ^C # 按下 CtrlCCLI 监听了SIGINT/SIGTERM/SIGHUP信号退出前会依次清理托盘、MITM 代理进程通过 PID 文件优雅终止以及隧道进程cloudflared/tailscale最后强制结束服务子进程并退出保证数据落盘。重启重启只需再次执行启动命令9router所有配置、API 密钥、Combo组合路由都持久化在数据目录中重启后自动恢复无需重新配置。 更新 9Router更新到最新版本npm update -g 9router查看当前安装的版本npm list -g 9routerCLI 在启动时会自动比对 npm registry 上的最新版本仅在--skip-update未指定时若发现新版本会在交互菜单顶部提供 Update to vX.Y.Z 选项选择后 CLI 会提示退出并执行npm i -g 9routerlatest --prefer-online。此外CLI 内置了崩溃自愈逻辑服务进程异常退出后最多自动重启 2 次重启间隔 1s → 2s若运行稳定超过 30 秒则重置计数连续崩溃时会自动禁用 MITM 相关设置后再次拉起降低环境兼容问题导致的启动失败率。 故障排查端口已被占用当20128或3000端口被其他进程占用时可用lsof定位并结束占用进程macOS/Linux# 查找占用端口的进程 lsof -i :20128 lsof -i :3000 # 结束该进程 kill -9 PIDWindows 下可用netstat -ano | findstr :20128配合taskkill /F /PID PID。实际上CLI 启动时会先执行killProcessOnPort()自动尝试释放端口macOS/Linux 用lsof -ti:portWindows 用netstattaskkill多数场景无需手动处理上述命令适用于服务未启动但仍需清理端口的情况。权限错误安装阶段权限问题的处理见上文安装权限问题一节。若服务运行时出现数据目录不可写检查目录权限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 网关【免费下载链接】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），仅供参考
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。启动时若检测到局域网 IPCLI 会打印黄色警告提示服务已暴露到网络⚠ Network-exposed: reachable at http://LAN-IP:20128 (bound 0.0.0.0). Use --host 127.0.0.1 for local-only.默认配置速览项目默认值控制台/API 端口20128CLI 默认DEFAULT_PORT见 cli/cli.js控制台地址http://localhost:20128/dashboard服务端口 /dashboard路径OpenAI 兼容 API 端点http://localhost:20128/v1数据目录~/.9routermacOS/LinuxWindows 为%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的终端中按CtrlC# 在运行 9router 的终端中 ^C # 按下 CtrlCCLI 监听了SIGINT/SIGTERM/SIGHUP信号退出前会依次清理托盘、MITM 代理进程通过 PID 文件优雅终止以及隧道进程cloudflared/tailscale最后强制结束服务子进程并退出保证数据落盘。重启重启只需再次执行启动命令9router所有配置、API 密钥、Combo组合路由都持久化在数据目录中重启后自动恢复无需重新配置。 更新 9Router更新到最新版本npm update -g 9router查看当前安装的版本npm list -g 9routerCLI 在启动时会自动比对 npm registry 上的最新版本仅在--skip-update未指定时若发现新版本会在交互菜单顶部提供 Update to vX.Y.Z 选项选择后 CLI 会提示退出并执行npm i -g 9routerlatest --prefer-online。此外CLI 内置了崩溃自愈逻辑服务进程异常退出后最多自动重启 2 次重启间隔 1s → 2s若运行稳定超过 30 秒则重置计数连续崩溃时会自动禁用 MITM 相关设置后再次拉起降低环境兼容问题导致的启动失败率。 故障排查端口已被占用当20128或3000端口被其他进程占用时可用lsof定位并结束占用进程macOS/Linux# 查找占用端口的进程 lsof -i :20128 lsof -i :3000 # 结束该进程 kill -9 PIDWindows 下可用netstat -ano | findstr :20128配合taskkill /F /PID PID。实际上CLI 启动时会先执行killProcessOnPort()自动尝试释放端口macOS/Linux 用lsof -ti:portWindows 用netstattaskkill多数场景无需手动处理上述命令适用于服务未启动但仍需清理端口的情况。权限错误安装阶段权限问题的处理见上文安装权限问题一节。若服务运行时出现数据目录不可写检查目录权限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 网关【免费下载链接】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），仅供参考