9Router Docker 部署指南

9Router 是开源 AI 网关，统一管理 60+ AI 提供商和 100+ 模型，支持三层回退（订阅→低价→免费）、RTK Token 节省器（省 20-40% 输入 token）、格式自动翻译（OpenAI↔Anthropic 互转）。

一、Docker 部署

1.1 宿主机要求

Docker ≥ 29.x
端口 20128（默认）
数据持久化目录 /www/docker/9router/

1.2 部署命令

# 创建数据目录
mkdir -p /www/docker/9router/{data,data-home}

# 启动容器（v0.5.40）
docker run -d \
  --name 9router \
  --restart unless-stopped \
  -p 20128:20128 \
  -v /www/docker/9router/data:/app/data \
  -v /www/docker/9router/data-home:/app/data-home \
  -e DATA_DIR=/app/data \
  decolua/9router:0.5.40

参数说明：

参数	值	说明
`--name`	`9router`	容器名
`--restart`	`unless-stopped`	崩溃/重启自动拉起
`-p`	`20128:20128`	映射端口
`-v`	`/www/docker/9router/data:/app/data`	持久化 SQLite 数据库和日志
`-v`	`/www/docker/9router/data-home:/app/data-home`	持久化用量统计和请求日志（`usage.json`、`request-details.sqlite`）
`-e`	`DATA_DIR=/app/data`	显式声明数据目录（镜像已内置此环境变量，不加也可）

1.3 持久化文件结构

/www/docker/9router/
├── data/
│   ├── db/
│   │   ├── data.sqlite     # 主数据库（配置、用量、用户）
│   │   └── backups/         # 自动备份
│   ├── logs/                # 运行时日志
│   └── jwt-secret           # JWT 密钥（自动生成，64 位 hex）
└── data-home/
    └── (用量/请求日志持久化)

1.4 验证部署

# 检查容器状态
docker ps --filter name=9router

# 检查 API 端点
curl -s -o /dev/null -w "%{http_code}" http://localhost:20128/v1/models
# 预期: 401（未认证，说明服务正常）

# 检查 Dashboard
curl -s -o /dev/null -w "%{http_code}" http://localhost:20128/dashboard
# 预期: 307（跳转到登录页）

# 查看日志
docker logs 9router

二、首次启动配置

2.1 访问面板

地址: http://<服务器IP>:20128
登录页: /login

2.2 默认登录密码

默认密码：123456
首次远程登录时面板会提示”Security risk: no password set. You will be asked to set one when logging in remotely”
输入默认密码后按引导设置新密码

2.3 开放防火墙

# ufw
ufw allow 20128/tcp comment '9router'

# firewall-cmd（CentOS）
firewall-cmd --permanent --add-port=20128/tcp
firewall-cmd --reload

安全提示： 面板默认走 HTTP，密码明文传输。建议：
设置强密码
生产环境配 Nginx 反代 + Let’s Encrypt HTTPS
或限制来源 IP 访问

三、核心功能

3.1 提供商接入

在 Dashboard → Providers 中添加：

类型	示例	说明
OAuth	Claude Code、Codex、GitHub Copilot、Cursor	浏览器登录授权
API Key	OpenRouter、GLM、Kimi、DeepSeek、OpenAI、Anthropic	直接填 Key
Free	Kiro AI（免费 Claude 无限量）、OpenCode Free（免认证）、Vertex AI（$300 额度）	零成本

3.2 三层回退

客户端 → 9Router
          ├─ [Tier 1: 订阅] Claude Code / Codex / Copilot
          │   ↓ 额度耗尽
          ├─ [Tier 2: 低价] GLM ($0.6/1M) / MiniMax ($0.2/1M)
          │   ↓ 预算超限
          └─ [Tier 3: 免费] Kiro AI / OpenCode Free / Vertex AI

3.3 RTK Token 节省器

默认开启，自动压缩 git diff、grep、ls、tree 等工具输出，节省 20-40% 输入 token。在 Dashboard → Endpoint → Token Saver 中配置。

3.4 客户端接入

所有兼容 OpenAI API 的工具均可直连：

Endpoint: http://<服务器IP>:20128/v1
API Key:  <从 Dashboard 复制>
Model:    kr/claude-sonnet-4.5（9Router 格式）

四、与 Hermes Agent 配合

将 Hermes 的 provider 指向 9Router：

# Hermes config.yaml
provider: custom:9router
models:
  - model: kr/claude-sonnet-4.5
    # 9Router 自动路由到实际提供商

优势：

统一入口：一个 endpoint 管所有模型，不用每个 profile 配不同的 fallback
自动回退：OpenRouter 429 → 9Router 自动切到免费/低价层
Token 省钱：RTK 压缩 tool 输出，减少 Hermes 的 token 消耗

五、更新

查看版本

# Docker Hub tag 列表
curl -s "https://hub.docker.com/v2/repositories/decolua/9router/tags?page_size=30" | python3 -c "
import json,sys
data = json.load(sys.stdin)
for t in data.get('results',[]):
    print(f'{t[\"name\"]:20s}  {t[\"last_updated\"][:19]}')
"

更新容器

docker pull decolua/9router:0.5.40
docker stop 9router
docker rm 9router
# 重新执行 docker run ...（数据在持久卷中不会丢失）

六、维护命令

# 查看日志
docker logs 9router
docker logs -f 9router   # 实时跟随

# 停止/启动
docker stop 9router
docker start 9router

# 备份数据库
cp /www/docker/9router/data/db/data.sqlite /www/docker/9router/data/db/data.sqlite.bak.$(date +%s)

七、注意事项

镜像大小：约 842MB（基于 Node.js 22），支持 linux/amd64 + linux/arm64
内存占用：约 100-200MB（轻量服务）
数据库：SQLite（better-sqlite3），无需额外数据库服务
GitHub Releases vs Docker Tags：GitHub Releases 可能晚于 Docker Tag 更新，面板提示升级时以 Docker Hub 实际 tag 为准
Headroom（可选）：9Router 镜像不内置，需作为 sidecar 单独容器运行
用量数据：usageDb.js 和 requestDetailsDb.js 默认写 ~/.9router/（即 /app/data-home），所以需额外挂载 data-home 目录才能完整持久化。不加的话容器重启后用量统计会清零，不影响核心配置
镜像仓库：Docker Hub decolua/9router | GHCR ghcr.io/decolua/9router

9Router容器部署使用