拓冰网站定制 
9Router Localhost Deployment在本机安装、启动与运维 AI Router 的完整指南【免费下载链接】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 是一个面向 AI 编程工具的本地网关它把 Claude Code、Codex、Cursor、Cline、Copilot 等 CLI 工具连接到 40 提供商含免费模型并提供自动回退、配额跟踪与 RTK 令牌压缩能力。本指南以官方 Localhost 部署文档为核心讲解如何在个人电脑上用 npm 安装 9Router、单命令启动网关、配置数据目录、升级版本、排查常见故障并结合仓库源码说明端口、数据目录与进程管理背后的实现原理。读完本文你将能够独立完成 9Router 的本机部署、日常运维与故障恢复。环境要求与安装9Router 的 Localhost 部署方式是通过 npm 全局安装官方 CLI 包npm install -g 9router官方文档给出的环境要求如下Node.js 20 或更高版本npm 9 或更高版本说明npm 包 cli/package.json 的engines字段声明的最低版本为node 18.0.0但官方部署文档建议使用 Node.js 20以保证运行时行为与文档一致。安装完成后的包结构对应 cli/package.json 的bin配置{ name: 9router, bin: { 9router: ./cli.js }, engines: { node: 18.0.0 } }即全局命令9router会直接映射到 CLI 启动器 cli/cli.js。除主程序外CLI 包还通过postinstall钩子cli/hooks/postinstall.js在首次运行时按需补齐 SQLite 运行时依赖详见下文“数据目录与存储引擎”一节。也可以不安装、直接用npx 9router启动效果等价。启动服务器单命令拉起完整网关安装完成后在终端执行9routerCLI 会完成以下启动流程实现于 cli/cli.js 的startServer运行时自愈调用ensureSqliteRuntime与ensureTrayRuntime确保 SQLite 引擎与系统托盘运行时可用清理旧进程先killAllAppProcesses再killProcessOnPort释放端口并行检查更新checkForUpdate查询 npm registry不阻塞服务器启动拉起服务器以子进程方式启动 bundled standalone 服务优先使用 custom-server.js它负责从 TCP 套接字解析真实客户端 IP 并剥离伪造的转发头就绪探测waitServerReady以 150ms 间隔轮询端口 TCP 连通性超时 15s避免固定等待打开浏览器并展示交互式菜单。默认配置项默认值DashboardWeb 管理界面http://localhost:20128/dashboardAPI EndpointOpenAI 兼容http://localhost:20128/v1数据目录macOS/Linux~/.9router数据目录Windows%APPDATA%\9router注意官方文档中 Dashboard 端口写作3000但当前仓库的 CLI 实现cli/cli.js以DEFAULT_PORT 20128为唯一默认端口Dashboard 与 API 均服务于此端口。CLI 的 READMEcli/README.md同样明确 Dashboard 地址为http://localhost:20128/dashboard。本机调试时请以20128为准若你看到的界面端口不同请以实际运行的 CLI 版本输出为准。启动成功后把 AI 编程工具的 Endpoint 指向http://localhost:20128/v1填入 Dashboard 中复制的 API Key 与模型名例如kr/claude-sonnet-4.5即可开始使用免费模型。CLI 启动参数9router命令支持以下参数9router --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显示版本号—常用组合示例# 自定义端口 不自动打开浏览器 9router --port 8080 --no-browser # 仅本机访问不暴露到局域网 9router --host 127.0.0.1 # 后台托盘模式 9router --tray值得注意的是CLI 默认绑定0.0.0.0即监听所有网卡。源码中对此有专门提示当绑定所有接口时启动日志会打印黄色警告⚠ Network-exposed: reachable at http://LAN-IP:20128 (bound 0.0.0.0). Use --host 127.0.0.1 for local-only.。如果你只在本机使用建议显式加上--host 127.0.0.1避免网关暴露到局域网。启动后的交互式界面服务器就绪后CLI 会显示一个交互菜单包含四个选项Web UI (Open in Browser)在浏览器中打开 DashboardTerminal UI (Interactive CLI)进入终端交互界面实现于 cli/src/terminalUI.jsHide to Tray (Background)切换到系统托盘后台运行Windows 使用 PowerShell 托盘图标macOS/Linux 使用 systray并自动注册开机自启Exit退出。如果检测到新版本菜单顶部还会出现 “Update to vX.Y.Z” 选项。配置数据目录与端口自定义数据目录9Router 支持通过环境变量DATA_DIR指定数据存放位置DATA_DIR/path/to/data 9router数据目录的解析逻辑位于 src/lib/dataDir.js未设置DATA_DIR时macOS/Linux 使用~/.9routerWindows 使用%APPDATA%\9router设置后会自动mkdirSync递归创建两个边界处理值得了解Windows 上的 Unix 路径防护如果DATA_DIR是以/开头的 Unix 风格绝对路径例如来自 Linux 目标的.env或 Docker 配置会被视为无效并回退到默认目录权限回退如果目标目录不可写EACCES/EPERM会打印警告并回退到~/.9router而不是直接崩溃。CLI 端cli/cli.js 的getAppDataDir遵循同样的平台约定用于定位 PID 文件、MITM 与隧道进程文件。自定义端口官方文档指出 API 端口与 Dashboard 端口在应用中配置。结合当前源码端口修改有两种方式CLI 参数9router -p 8080见上表Dashboard 与 API 会一并切换到新端口源码层面修改DEFAULT_PORT常量后重新构建npm run build——适用于自行从源码打包的场景。停止与重启优雅停止在运行9router的终端中按下CtrlC# 在运行 9router 的终端中 ^C # 按 CtrlCCLI 注册了SIGINT、SIGTERM、SIGHUP三个信号的清理处理器见 cli/cli.js 的cleanup停止时会依次结束系统托盘进程通过 PID 文件终止 MITM 代理进程先发 SIGTERM 让其清理 hosts 条目再兜底强杀终止 cloudflared / tailscale 隧道进程强杀服务器子进程及其进程组。官方文档强调“服务器会优雅关闭并保存所有数据”这得益于 SQLite 持久化所有提供商连接、Combo 组合、模型别名与设置都会写入数据文件无需手动导出。重启重新执行启动命令即可9router所有配置、API Key 与 Combo 组合都保存在数据目录中重启后自动恢复。补充CLI 内置了崩溃自动重启机制。服务器异常退出后会在 1s/2s 递增延迟后自动拉起最多 2 次MAX_RESTARTS若进程存活超过 30 秒则重置计数连续崩溃 3 次时会自动禁用 MITM 后再次重启并将最近 50 行崩溃日志打印到终端便于排查。升级与版本管理检查当前安装版本npm list -g 9router升级到最新版npm update -g 9routerCLI 每次启动还会自动向 npm registry 发起版本检查cli/cli.js 的checkForUpdate带 8 秒安全超时并在交互菜单中提示可用的新版本号。执行升级命令前建议先退出正在运行的实例npm i -g 9routerlatest --prefer-online故障排查端口被占用官方文档提供了 macOS/Linux 下的通用排查方式# 查找占用端口的进程macOS/Linux lsof -i :20128 lsof -i :3000 # 结束该进程 kill -9 PIDWindows 替代方案netstat -ano | findstr :20128 taskkill /F /PID PID补充实际上 9Router 启动时会自动执行killProcessOnPortmacOS/Linux 用lsof -ti:portkill -9Windows 用netstattaskkill清理残留进程并会在 30 秒窗口内自动重启已崩溃的服务器。因此大多数“端口被占用”场景在重新执行9router后即可自愈上述手动命令用于极端情况。安装权限错误官方文档给出的两种处理方式# 方式一使用 sudo不推荐 sudo npm install -g 9router # 方式二修正 npm 全局目录权限推荐 mkdir ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc方式二的思路是把 npm 全局安装位置从系统目录移到用户目录从而避免EACCES权限问题。数据目录异常如果数据目录不可访问# 查看权限 ls -la ~/.9router # 修复权限 chmod 755 ~/.9router结合源码9Router 对数据目录的异常有较强的自愈能力DATA_DIR不可写时会自动回退到~/.9routerSQLite 原生模块better-sqlite3安装失败时会回退到纯 WASM 的sql.js不会因依赖缺失而拒绝启动。数据目录结构从 JSON 到 SQLite官方文档描述的数据目录结构为~/.9router/ ├── db.json # 主数据库providers、combos、settings ├── logs/ # 应用日志 └── cache/ # 临时缓存当前仓库已把存储层迁移到 SQLite实际结构如下依据 src/lib/db/paths.js 与 src/lib/db/ 目录~/.9router/ ├── db/ │ ├── data.sqlite # 主数据库当前版本的核心数据文件 │ └── backups/ # 数据库自动备份目录 ├── runtime/ # 运行时依赖better-sqlite3 / sql.js 安装于此 │ └── node_modules/ ├── mitm/ # MITM 代理 PID 与状态文件 ├── tunnel/ # 隧道进程 PID 文件cloudflared / tailscale ├── logs/ # 应用日志 ├── cache/ # 临时缓存 └── db.json 等 # 旧版本遗留 JSON迁移兼容用几点源码级说明SQLite 多驱动适配数据库层src/lib/db/driver.js按环境选用better-sqlite3、node:sqlite、bun:sqlite或sql.js见 src/lib/db/adapters/核心数据统一落在data.sqlite首次运行自动安装原生依赖CLI 启动时通过 cli/hooks/sqliteRuntime.js 把better-sqlite3可选加速与sql.js必选回退安装到~/.9router/runtime/node_modules并通过NODE_PATH注入子进程。这样设计是为了避免全局包更新时 Windows 上原生.node文件被锁定的问题旧 JSON 兼容src/lib/localDb.js 是旧接口的 shim重新导出 SQLite 层的全部仓储方法providers、combos、aliases、pricing、apiKeys 等LEGACY_FILES记录了db.json、usage.json、request-details.json等旧文件的迁移路径。备份与恢复官方文档提供的备份/恢复方式同样适用于 SQLite 版本# 备份 cp -r ~/.9router ~/.9router.backup # 恢复 cp -r ~/.9router.backup ~/.9router执行备份前建议先停止 9Router避免复制过程中数据库处于写入状态。部署后的下一步完成本机部署后可以参考仓库 GitBook 文档继续深入连接提供商订阅额度创建 Combo 组合集成 CLI 工具Cursor 示例仓库中还有更多语言版本的部署文档如 中文版、日语版以及 CLI 快速上手说明 cli/README.md可作为后续参考。小结本机部署只需两步npm install -g 9router与9router默认 Dashboard 与 OpenAI 兼容 API 均位于http://localhost:20128通过-p、-H、-n、-t等参数可灵活控制端口、绑定地址与运行形态DATA_DIR环境变量可重定向数据目录存储层基于 SQLite~/.9router/db/data.sqlite配置、API Key 与 Combo 全部持久化CtrlC优雅退出、重启即恢复CLI 内置更新检查、端口自清理、崩溃自动重启含 MITM 自动降级等多层自愈机制多数故障可通过重新执行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 Localhost Deployment：在本机安装、启动与运维 AI Router 的完整指南
9Router Localhost Deployment在本机安装、启动与运维 AI Router 的完整指南【免费下载链接】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 是一个面向 AI 编程工具的本地网关它把 Claude Code、Codex、Cursor、Cline、Copilot 等 CLI 工具连接到 40 提供商含免费模型并提供自动回退、配额跟踪与 RTK 令牌压缩能力。本指南以官方 Localhost 部署文档为核心讲解如何在个人电脑上用 npm 安装 9Router、单命令启动网关、配置数据目录、升级版本、排查常见故障并结合仓库源码说明端口、数据目录与进程管理背后的实现原理。读完本文你将能够独立完成 9Router 的本机部署、日常运维与故障恢复。环境要求与安装9Router 的 Localhost 部署方式是通过 npm 全局安装官方 CLI 包npm install -g 9router官方文档给出的环境要求如下Node.js 20 或更高版本npm 9 或更高版本说明npm 包 cli/package.json 的engines字段声明的最低版本为node 18.0.0但官方部署文档建议使用 Node.js 20以保证运行时行为与文档一致。安装完成后的包结构对应 cli/package.json 的bin配置{ name: 9router, bin: { 9router: ./cli.js }, engines: { node: 18.0.0 } }即全局命令9router会直接映射到 CLI 启动器 cli/cli.js。除主程序外CLI 包还通过postinstall钩子cli/hooks/postinstall.js在首次运行时按需补齐 SQLite 运行时依赖详见下文“数据目录与存储引擎”一节。也可以不安装、直接用npx 9router启动效果等价。启动服务器单命令拉起完整网关安装完成后在终端执行9routerCLI 会完成以下启动流程实现于 cli/cli.js 的startServer运行时自愈调用ensureSqliteRuntime与ensureTrayRuntime确保 SQLite 引擎与系统托盘运行时可用清理旧进程先killAllAppProcesses再killProcessOnPort释放端口并行检查更新checkForUpdate查询 npm registry不阻塞服务器启动拉起服务器以子进程方式启动 bundled standalone 服务优先使用 custom-server.js它负责从 TCP 套接字解析真实客户端 IP 并剥离伪造的转发头就绪探测waitServerReady以 150ms 间隔轮询端口 TCP 连通性超时 15s避免固定等待打开浏览器并展示交互式菜单。默认配置项默认值DashboardWeb 管理界面http://localhost:20128/dashboardAPI EndpointOpenAI 兼容http://localhost:20128/v1数据目录macOS/Linux~/.9router数据目录Windows%APPDATA%\9router注意官方文档中 Dashboard 端口写作3000但当前仓库的 CLI 实现cli/cli.js以DEFAULT_PORT 20128为唯一默认端口Dashboard 与 API 均服务于此端口。CLI 的 READMEcli/README.md同样明确 Dashboard 地址为http://localhost:20128/dashboard。本机调试时请以20128为准若你看到的界面端口不同请以实际运行的 CLI 版本输出为准。启动成功后把 AI 编程工具的 Endpoint 指向http://localhost:20128/v1填入 Dashboard 中复制的 API Key 与模型名例如kr/claude-sonnet-4.5即可开始使用免费模型。CLI 启动参数9router命令支持以下参数9router --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显示版本号—常用组合示例# 自定义端口 不自动打开浏览器 9router --port 8080 --no-browser # 仅本机访问不暴露到局域网 9router --host 127.0.0.1 # 后台托盘模式 9router --tray值得注意的是CLI 默认绑定0.0.0.0即监听所有网卡。源码中对此有专门提示当绑定所有接口时启动日志会打印黄色警告⚠ Network-exposed: reachable at http://LAN-IP:20128 (bound 0.0.0.0). Use --host 127.0.0.1 for local-only.。如果你只在本机使用建议显式加上--host 127.0.0.1避免网关暴露到局域网。启动后的交互式界面服务器就绪后CLI 会显示一个交互菜单包含四个选项Web UI (Open in Browser)在浏览器中打开 DashboardTerminal UI (Interactive CLI)进入终端交互界面实现于 cli/src/terminalUI.jsHide to Tray (Background)切换到系统托盘后台运行Windows 使用 PowerShell 托盘图标macOS/Linux 使用 systray并自动注册开机自启Exit退出。如果检测到新版本菜单顶部还会出现 “Update to vX.Y.Z” 选项。配置数据目录与端口自定义数据目录9Router 支持通过环境变量DATA_DIR指定数据存放位置DATA_DIR/path/to/data 9router数据目录的解析逻辑位于 src/lib/dataDir.js未设置DATA_DIR时macOS/Linux 使用~/.9routerWindows 使用%APPDATA%\9router设置后会自动mkdirSync递归创建两个边界处理值得了解Windows 上的 Unix 路径防护如果DATA_DIR是以/开头的 Unix 风格绝对路径例如来自 Linux 目标的.env或 Docker 配置会被视为无效并回退到默认目录权限回退如果目标目录不可写EACCES/EPERM会打印警告并回退到~/.9router而不是直接崩溃。CLI 端cli/cli.js 的getAppDataDir遵循同样的平台约定用于定位 PID 文件、MITM 与隧道进程文件。自定义端口官方文档指出 API 端口与 Dashboard 端口在应用中配置。结合当前源码端口修改有两种方式CLI 参数9router -p 8080见上表Dashboard 与 API 会一并切换到新端口源码层面修改DEFAULT_PORT常量后重新构建npm run build——适用于自行从源码打包的场景。停止与重启优雅停止在运行9router的终端中按下CtrlC# 在运行 9router 的终端中 ^C # 按 CtrlCCLI 注册了SIGINT、SIGTERM、SIGHUP三个信号的清理处理器见 cli/cli.js 的cleanup停止时会依次结束系统托盘进程通过 PID 文件终止 MITM 代理进程先发 SIGTERM 让其清理 hosts 条目再兜底强杀终止 cloudflared / tailscale 隧道进程强杀服务器子进程及其进程组。官方文档强调“服务器会优雅关闭并保存所有数据”这得益于 SQLite 持久化所有提供商连接、Combo 组合、模型别名与设置都会写入数据文件无需手动导出。重启重新执行启动命令即可9router所有配置、API Key 与 Combo 组合都保存在数据目录中重启后自动恢复。补充CLI 内置了崩溃自动重启机制。服务器异常退出后会在 1s/2s 递增延迟后自动拉起最多 2 次MAX_RESTARTS若进程存活超过 30 秒则重置计数连续崩溃 3 次时会自动禁用 MITM 后再次重启并将最近 50 行崩溃日志打印到终端便于排查。升级与版本管理检查当前安装版本npm list -g 9router升级到最新版npm update -g 9routerCLI 每次启动还会自动向 npm registry 发起版本检查cli/cli.js 的checkForUpdate带 8 秒安全超时并在交互菜单中提示可用的新版本号。执行升级命令前建议先退出正在运行的实例npm i -g 9routerlatest --prefer-online故障排查端口被占用官方文档提供了 macOS/Linux 下的通用排查方式# 查找占用端口的进程macOS/Linux lsof -i :20128 lsof -i :3000 # 结束该进程 kill -9 PIDWindows 替代方案netstat -ano | findstr :20128 taskkill /F /PID PID补充实际上 9Router 启动时会自动执行killProcessOnPortmacOS/Linux 用lsof -ti:portkill -9Windows 用netstattaskkill清理残留进程并会在 30 秒窗口内自动重启已崩溃的服务器。因此大多数“端口被占用”场景在重新执行9router后即可自愈上述手动命令用于极端情况。安装权限错误官方文档给出的两种处理方式# 方式一使用 sudo不推荐 sudo npm install -g 9router # 方式二修正 npm 全局目录权限推荐 mkdir ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc方式二的思路是把 npm 全局安装位置从系统目录移到用户目录从而避免EACCES权限问题。数据目录异常如果数据目录不可访问# 查看权限 ls -la ~/.9router # 修复权限 chmod 755 ~/.9router结合源码9Router 对数据目录的异常有较强的自愈能力DATA_DIR不可写时会自动回退到~/.9routerSQLite 原生模块better-sqlite3安装失败时会回退到纯 WASM 的sql.js不会因依赖缺失而拒绝启动。数据目录结构从 JSON 到 SQLite官方文档描述的数据目录结构为~/.9router/ ├── db.json # 主数据库providers、combos、settings ├── logs/ # 应用日志 └── cache/ # 临时缓存当前仓库已把存储层迁移到 SQLite实际结构如下依据 src/lib/db/paths.js 与 src/lib/db/ 目录~/.9router/ ├── db/ │ ├── data.sqlite # 主数据库当前版本的核心数据文件 │ └── backups/ # 数据库自动备份目录 ├── runtime/ # 运行时依赖better-sqlite3 / sql.js 安装于此 │ └── node_modules/ ├── mitm/ # MITM 代理 PID 与状态文件 ├── tunnel/ # 隧道进程 PID 文件cloudflared / tailscale ├── logs/ # 应用日志 ├── cache/ # 临时缓存 └── db.json 等 # 旧版本遗留 JSON迁移兼容用几点源码级说明SQLite 多驱动适配数据库层src/lib/db/driver.js按环境选用better-sqlite3、node:sqlite、bun:sqlite或sql.js见 src/lib/db/adapters/核心数据统一落在data.sqlite首次运行自动安装原生依赖CLI 启动时通过 cli/hooks/sqliteRuntime.js 把better-sqlite3可选加速与sql.js必选回退安装到~/.9router/runtime/node_modules并通过NODE_PATH注入子进程。这样设计是为了避免全局包更新时 Windows 上原生.node文件被锁定的问题旧 JSON 兼容src/lib/localDb.js 是旧接口的 shim重新导出 SQLite 层的全部仓储方法providers、combos、aliases、pricing、apiKeys 等LEGACY_FILES记录了db.json、usage.json、request-details.json等旧文件的迁移路径。备份与恢复官方文档提供的备份/恢复方式同样适用于 SQLite 版本# 备份 cp -r ~/.9router ~/.9router.backup # 恢复 cp -r ~/.9router.backup ~/.9router执行备份前建议先停止 9Router避免复制过程中数据库处于写入状态。部署后的下一步完成本机部署后可以参考仓库 GitBook 文档继续深入连接提供商订阅额度创建 Combo 组合集成 CLI 工具Cursor 示例仓库中还有更多语言版本的部署文档如 中文版、日语版以及 CLI 快速上手说明 cli/README.md可作为后续参考。小结本机部署只需两步npm install -g 9router与9router默认 Dashboard 与 OpenAI 兼容 API 均位于http://localhost:20128通过-p、-H、-n、-t等参数可灵活控制端口、绑定地址与运行形态DATA_DIR环境变量可重定向数据目录存储层基于 SQLite~/.9router/db/data.sqlite配置、API Key 与 Combo 全部持久化CtrlC优雅退出、重启即恢复CLI 内置更新检查、端口自清理、崩溃自动重启含 MITM 自动降级等多层自愈机制多数故障可通过重新执行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），仅供参考