9Router 云端生产部署指南：VPS、Docker 与 Nginx 反向代理完整实战

9Router 云端生产部署指南VPS、Docker 与 Nginx 反向代理完整实战【免费下载链接】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/9router9Router 是面向 AI 编码工具的统一路由网关可把 Claude Code、Codex、Cursor、Cline、Copilot 等工具接入 40 免费/订阅模型提供方并提供自动故障回退与 RTK-40% token能力。本文基于仓库文档 gitbook/content/es/deployment/cloud.md系统讲解如何将 9Router 部署到 VPS 或 Docker 容器中实现远程访问与生产运行内容覆盖环境变量配置、PM2 进程守护、Nginx 反向代理与 SSL、安全加固、监控与故障排查。读完本文你将能够独立完成一台生产服务器的完整部署、加固与日常运维。1. 部署架构概览9Router 采用「Web 仪表盘 API 网关 内部 MITM 子进程」的分层结构Web 仪表盘Next.js 前端提供 Provider 管理、Combo 配置、用量统计等界面API 网关对外暴露 OpenAI 兼容的/v1接口供 Claude Code、Cursor 等工具接入数据存储核心状态持久化在${DATA_DIR}/db/data.sqliteSQLite自动备份位于${DATA_DIR}/db/backups/MITM 子进程由主进程派生负责部分代理链路的证书与转发逻辑参见 src/mitm/server.js。从仓库根目录的 package.json 可以看到运行时脚本约定scripts: { dev: next dev --port 20127, build: next build --webpack, start: next start --port 20127, start:bun: bun ./.next/standalone/server.js }生产环境通常通过PORT/HOSTNAME环境变量覆盖默认端口与绑定地址。官方容器镜像Dockerfile默认PORT20128、HOSTNAME0.0.0.0Docker Compose 编排docker-compose.yml也固定暴露20128端口并内置一个可选的 Headroomtoken 压缩辅助服务。版本说明本文命令与配置以当前仓库9router-app0.5.45为准。文档 cloud.md 中同时提到了仪表盘端口 3000 与 API 端口 20128 的双端口布局而从当前 package.json、README.md 与 Dockerfile 看官方默认已将整个应用仪表盘 API统一运行在20128端口。下文将同时给出两种布局的配置方法请根据你的实际部署方式选用。2. VPS 部署源码方式 PM22.1 前置要求Ubuntu 20.04 或同类 Linux 发行版Node.js 20仓库 package.json 要求 Next.js 16 运行在 Node 20 环境官方镜像选用node:22-alpineGitroot 或 sudo 权限2.2 克隆仓库并安装依赖git clone https://gitcode.com/GitHub_Trending/9r/9router.git cd 9router npm install原文档示例中写的是cd 9router/app但当前仓库的package.json、next.config.mjs等文件均位于仓库根目录因此克隆后直接进入仓库根目录即可无需再进入app子目录。2.3 编译应用npm run build该命令执行next build --webpack见 package.json产出生产构建产物。仓库还提供了 Bun 构建路径npm run build:bun需要更快的构建速度时可选用。2.4 配置环境变量创建.env文件或直接导出变量export JWT_SECRETyour-secure-secret-change-this-to-random-string export INITIAL_PASSWORDyour-secure-password export DATA_DIR/var/lib/9router export NODE_ENVproduction export PORT20128 export HOSTNAME0.0.0.0仓库根目录的 .env.example 给出了完整的运行时环境契约核心变量说明如下变量默认值说明JWT_SECRET自动生成${DATA_DIR}/jwt-secret生产环境必须修改用于签名仪表盘登录 JWT参见 src/lib/auth/dashboardSession.jsINITIAL_PASSWORD123456首次登录密码当数据库尚无密码哈希时使用参见 src/lib/auth/dashboardSession.jsDATA_DIR~/.9router数据库等主数据存储路径解析逻辑见 src/lib/dataDir.jsNODE_ENV运行时默认部署时设为productionPORT框架默认服务端口官方示例与容器均为20128HOSTNAME框架默认绑定地址Docker 下默认0.0.0.0ENABLE_REQUEST_LOGSfalse是否在logs/下输出请求/响应调试日志AUTH_COOKIE_SECUREfalse强制 auth cookie 携带Secure标记HTTPS 反代后建议设为trueREQUIRE_API_KEYfalse对/v1/*路由强制 Bearer API Key面向公网开放时强烈建议开启几个变量在源码中的实际作用JWT_SECRETdashboardSession.js的loadJwtSecret()会优先读取环境变量未设置时自动生成 32 字节随机 hex 并写入${DATA_DIR}/jwt-secret文件权限0600。多实例共享登录态时需显式设置为同一值。INITIAL_PASSWORD仅当本地设置库中不存在密码哈希时生效verifyDashboardPassword先比对 bcrypt 哈希无哈希才回退到环境变量因此登录后修改过密码的实例不受该变量影响。DATA_DIRsrc/lib/dataDir.js 中getDataDir()会尝试创建目录若目录不可写EACCES/EPERM则回退到~/.9router并打印告警。Windows 下遇到 Unix 风格绝对路径也会自动回退。ENABLE_REQUEST_LOGS开启后把请求/翻译日志写到repo/logs/...见 README.md。2.5 创建数据目录sudo mkdir -p /var/lib/9router sudo chown $USER:$USER /var/lib/9router2.6 启动应用npm run start生产环境推荐显式指定监听地址与端口PORT20128 HOSTNAME0.0.0.0 npm run start该启动方式与 README.md、CLAUDE.md 中的生产运行示例一致。2.7 使用 PM2 守护进程PM2 保证应用常驻并在崩溃后自动重启# 全局安装 PM2 npm install -g pm2 # 用 PM2 启动 9Router pm2 start npm --name 9router -- start # 保存进程列表 pm2 save # 配置开机自启按输出的提示执行对应命令 pm2 startup日常管理命令pm2 logs 9router # 查看日志 pm2 restart 9router # 重启 pm2 stop 9router # 停止 pm2 status # 查看状态 pm2 monit # 资源监控 pm2 env 9router # 查看进程环境变量3. Docker 部署3.1 使用仓库自带 Dockerfile方式一仓库根目录已提供生产级 Dockerfile多阶段构建无需像原文档那样手动创建。其关键设计构建阶段基于node:22-alpine安装python3 make g linux-headers以编译better-sqlite3等原生依赖npm install使用 BuildKit 缓存运行阶段复制.next/standalone独立产物 custom-server.js并单独复制src/mitm与node-forgeNext 文件追踪可能遗漏 MITM 子进程所需文件见 Dockerfile 内注释默认环境NODE_ENVproduction、PORT20128、HOSTNAME0.0.0.0、DATA_DIR/app/data数据目录构建时创建/app/data并软链/root/.9router - /app/dataREADME 中说明容器内两者指向同一位置入口脚本/entrypoint.sh在每次启动时修复挂载卷属主chown -R node:node后以node用户执行node custom-server.js。构建并运行docker build -t 9router . docker run -d \ --name 9router \ -p 20128:20128 \ -e JWT_SECRETyour-secure-secret-change-this \ -e INITIAL_PASSWORDyour-secure-password \ -e DATA_DIR/app/data \ -v 9router-data:/app/data \ 9router仓库还提供了 start.sh 脚本封装了「停止 → 删除 → 构建 → 运行」的完整流程供快速迭代使用。关于custom-server.js它包装了 Node 原生http.createServer从 TCP socket 取对端 IP 并剥离客户端伪造的x-forwarded-for仅当对端是本机回环反向代理时才信任转发头用于防止下游按 XFF 做限流时被攻击者伪造 IP见 custom-server.js。这解释了为何 Nginx 反代 Docker 部署是最推荐的组合。3.2 使用 Docker Compose方式二仓库自带 docker-compose.yml直接基于官方镜像decolua/9router:latest编排并包含可选的 Headroom 服务services: 9router: image: decolua/9router:latest container_name: 9router restart: always ports: - 20128:20128 volumes: - 9router-data:/app/data env_file: - .env environment: DATA_DIR: /app/data PORT: 20128 HOSTNAME: 0.0.0.0 NODE_ENV: production HEADROOM_URL: http://headroom:8787 depends_on: - headroom headroom: image: ghcr.io/chopratejas/headroom:latest container_name: headroom restart: always ports: - 8787:8787 volumes: 9router-data: name: 9router-data使用方式cp .env.example .env # 按需修改 docker-compose up -d docker-compose logs -f docker-compose down docker-compose up -d --build注意Compose 通过env_file: .env注入密钥且 .dockerignore 不会把.env打进镜像运行时密钥只存在于容器环境变量中。3.3 数据持久化容器内数据目录/app/data宿主机映射命名卷9router-data关键文件db/data.sqliteProvider、Combo、别名、API Key、设置与用量历史、db/backups/自动备份README 中的持久化对应关系为宿主机$HOME/.9router/db/data.sqlite↔ 容器/app/data/db/data.sqlite。升级容器docker pull decolua/9router:latest时数据不会丢失前提是挂载了同名卷。4. Nginx 反向代理4.1 为什么需要 NginxSSL/TLS 终结域名映射负载均衡多实例场景更安全的暴露面收敛4.2 安装 Nginxsudo apt update sudo apt install nginx4.3 站点配置创建/etc/nginx/sites-available/9routerserver { listen 80; server_name your-domain.com; # HTTP 强制跳转 HTTPS return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; # SSL 证书可用 certbot 生成 ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers HIGH:!aNULL:!MD5; ssl_prefer_server_ciphers on; # 仪表盘若应用整体运行在 20128将 proxy_pass 改为 http://localhost:20128 location / { proxy_pass http://localhost:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_cache_bypass $http_upgrade; # SSE 支持 —— 流式响应关键 proxy_buffering off; proxy_read_timeout 86400; } # API 端点 location /v1 { proxy_pass http://localhost:20128; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # SSE 支持 —— 流式响应关键 proxy_buffering off; proxy_read_timeout 86400; } }两点务必留意端口一致性若你的 9Router 按官方默认整体跑在20128npm run start未指定端口、或使用官方镜像请把location /的proxy_pass也改为http://localhost:20128与/v1一致文档中的双端口布局3000 20128适用于显式拆分运行仪表盘与 API 的部署。SSE 与真实 IPproxy_buffering off与长proxy_read_timeout是 AI 流式输出不中断的前提X-Real-IP/X-Forwarded-For会被 custom-server.js 在回环反代场景下信任用于正确的限流/审计。开启 HTTPS 反代后建议同步设置AUTH_COOKIE_SECUREtrue让登录 cookie 携带Secure标记dashboardSession.js 也会依据x-forwarded-proto: https自动决定。4.4 启用站点sudo ln -s /etc/nginx/sites-available/9router /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx4.5 申请 Lets Encrypt 证书sudo apt install certbot python3-certbot-nginx sudo certbot --nginx -d your-domain.com # 自动续期由系统定时任务完成 sudo certbot renew --dry-run5. 安全加固5.1 修改默认凭据最关键INITIAL_PASSWORD默认是123456JWT_SECRET不设置时是自动生成的本地密钥——公网部署前两者都必须显式覆盖# 生成强随机 JWT 密钥 openssl rand -base64 32 export JWT_SECRETgenerated-secret-here export INITIAL_PASSWORDyour-strong-password5.2 防火墙配置UFWsudo ufw allow 22/tcp # SSH # 若使用 Nginx 反代仅需放行 HTTP/HTTPS sudo ufw allow 80/tcp sudo ufw allow 443/tcp # 若不用反代才需要直接放行 9Router 端口 sudo ufw allow 3000/tcp sudo ufw allow 20128/tcp sudo ufw enable5.3 收敛仪表盘暴露面仅当需要远程 API 访问、仪表盘仅本机使用时可以拒绝外部对仪表盘端口的访问并通过 SSH 隧道访问sudo ufw deny 3000/tcp # 本机建立隧道 ssh -L 3000:localhost:3000 useryour-server.com # 然后浏览器打开 http://localhost:3000若仪表盘与 API 同端口运行此方法需结合 Nginx 按location区分与 IP 白名单实现。5.4 定期更新sudo apt update sudo apt upgrade -y cd /path/to/9router git pull npm install npm run build pm2 restart 9router5.5 备份策略# 手动备份数据目录 tar -czf 9router-backup-$(date %Y%m%d).tar.gz /var/lib/9router # crontab 每日自动备份 0 2 * * * tar -czf /backups/9router-$(date \%Y\%m\%d).tar.gz /var/lib/9router6. 监控# PM2 状态与日志 pm2 status pm2 logs 9router --lines 100 pm2 monit # Nginx 日志 sudo tail -f /var/log/nginx/access.log sudo tail -f /var/log/nginx/error.log # 系统资源 htop df -h netstat -tulpn | grep -E 3000|20128如需更细粒度的请求排障可开启ENABLE_REQUEST_LOGStrue让应用把请求/响应日志写入logs/目录详见 README.md。7. 故障排查症状排查步骤应用无法启动pm2 logs 9router查看日志sudo lsof -i :3000/sudo lsof -i :20128检查端口占用pm2 env 9router核对环境变量Nginx 502 Bad Gatewaypm2 status确认应用存活sudo tail -f /var/log/nginx/error.logsudo nginx -t校验配置核对proxy_pass端口与 9Router 实际监听端口一致SSE 流式输出不工作确认 Nginx 中proxy_buffering off已配置AI 流式响应被缓冲会表现为一直不出字/一次性吐出权限拒绝错误sudo chown -R $USER:$USER /var/lib/9router与chmod 755 /var/lib/9router修复数据目录属主容器部署时确认卷属主由/entrypoint.sh正确修复8. 部署后的下一步完成云端部署后可继续配置业务能力以下为仓库内对应文档路径以仓库根目录为起点连接 Provider 订阅 —— 绑定订阅型模型提供方配置 Combos 组合路由 —— 多 Provider 自动故障回退与配额轮转智能路由与配额跟踪集成 Cursor 等 CLI 工具将 API 端点指向你的 9Router/v1地址结语本文从 VPS 源码部署、PM2 守护、Docker/Compose 容器化到 Nginx 反代与 HTTPS、安全加固、监控排障完整覆盖了 9Router 云端生产化的全部环节。核心要点可总结为三句话先改JWT_SECRET与INITIAL_PASSWORD再对外暴露反代必须proxy_buffering off保 SSE数据全部落在DATA_DIR务必挂载持久卷并定时备份。结合仓库中的 .env.example、Dockerfile、docker-compose.yml 与 README.md 即可开箱落地。【免费下载链接】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），仅供参考