9Router Docker 部署完全指南镜像运行、数据持久化与 Headroom 侧车配置【免费下载链接】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 提供了官方容器镜像decolua/9router多架构支持linux/amd64与linux/arm64本文将围绕 DOCKER.md 的完整内容结合仓库内 Dockerfile、docker-compose.yml、custom-server.js 及数据目录/Headroom 相关源码系统讲解如何在容器中运行 9Router、挂载持久化数据、配置环境变量、接入 Headroom 侧车、升级镜像以及面向开发者的本地构建与 CI 发布流程。读完本文你可以独立完成 9Router 的容器化部署、数据迁移与二次开发构建。快速启动一条命令跑起 9Router9Router 默认监听20128端口。拉取镜像并启动容器的最简方式如下docker run -d \ -p 20128:20128 \ -v $HOME/.9router:/app/data \ -e DATA_DIR/app/data \ --name 9router \ decolua/9router:latest启动后打开 http://localhost:20128 即可访问 Web 控制台。这里有几个关键设计点端口-p 20128:20128将容器的 20128 端口映射到宿主机Dockerfile 中设置了ENV PORT20128、ENV HOSTNAME0.0.0.0容器内监听所有网卡地址方便外部访问。数据目录-v $HOME/.9router:/app/data将宿主机目录挂载到容器内/app/data配合-e DATA_DIR/app/data让应用把数据写入挂载卷详见下文“数据持久化”。入口进程Dockerfile 的CMD [node, custom-server.js]表明容器实际运行的是定制后的 Next.js standalone 服务器custom-server.js 会在启动时包装http.createServer从 TCP socket 提取真实客户端 IP 并剔除客户端伪造的x-forwarded-for、x-real-ip头再以x-9r-real-ip头传给下游防止基于 IP 的限流被攻击者伪造头部绕过。容器生命周期管理docker logs -f 9router # 查看日志 docker stop 9router # 停止 docker start 9router # 重新启动 docker rm -f 9router # 删除容器注意docker stop只停止容器不会删除数据。只要卷$HOME/.9router存在重新docker start或重建容器后数据仍然保留。数据持久化理解 DATA_DIR 与挂载机制为什么必须同时设置挂载与 DATA_DIRDocker 运行方式中同时出现两个参数-v $HOME/.9router:/app/data \ -e DATA_DIR/app/data其含义为不设置DATA_DIR时应用默认使用~/.9router/macOS/Linux或%APPDATA%\9router\Windows容器内若不显式指定DATA_DIR数据会写入容器可写层容器删除即丢失DATA_DIR/app/data的作用就是把数据固定到挂载卷对应的路径上让 bind mount 真正生效。这一逻辑在源码中有明确对应。仓库 src/lib/dataDir.js 的getDataDir()实现为优先读取process.env.DATA_DIR未设置时在 Windows 上取%APPDATA%\9router其他平台取~/.9router并且在 Windows 上如果传入的是 Unix 风格绝对路径例如来自 Linux 部署的 .env会回退到默认目录若目录创建遇到 EACCES/EPERM 权限错误同样回退到~/.9router。另外Dockerfile 在镜像内创建/app/data并做了ln -sf /app/data-home /root/.9router软链接运行时入口 entrypoint.sh 还会先对/app/data、/app/data-home执行chown -R node:node再降权运行以兼容挂载卷的属主差异。数据目录结构$DATA_DIR/下的典型布局如下$DATA_DIR/ ├── db/ │ ├── data.sqlite # 主 SQLite 数据库 │ └── backups/ # 自动备份 └── ... # 证书、日志、运行时配置对应到本部署方式宿主机路径$HOME/.9router/db/data.sqlite容器内路径/app/data/db/data.sqliteSQLite 是 9Router 的主要持久化存储package.json 显示运行时优先使用better-sqlite3在无编译工具链的环境回退到纯 JS 的sql.js这保证了容器镜像的跨平台可移植性。除数据库外该目录还会存放证书、日志与运行时配置因此备份整个$DATA_DIR目录即可完整迁移 9Router 配置与数据。可选环境变量PORT、HOSTNAME、DEBUGdocker run -d \ -p 20128:20128 \ -v $HOME/.9router:/app/data \ -e DATA_DIR/app/data \ -e PORT20128 \ -e HOSTNAME0.0.0.0 \ -e DEBUGtrue \ --name 9router \ decolua/9router:latestPORT20128应用监听端口需与-p映射一致HOSTNAME0.0.0.0绑定所有网卡便于容器外部访问DEBUGtrue开启调试日志排查问题时使用其他如HEADROOM_URL见下文侧车配置。从源码看settingsRepo.js 中DEFAULT_HEADROOM_URL process.env.HEADROOM_URL || http://localhost:8787说明 9Router 支持通过环境变量注入默认配置并可在数据库中覆盖。Headroom 侧车Sidecar部署为什么需要侧车9Router 的官方镜像不内置 Python 与 Headroom。Headroom 是用于 Token Saver 的压缩代理可显著节省 token 消耗需要作为独立服务运行再让 9Router 指向它。这既是镜像瘦身的设计选择也避免了在 Alpine 容器内捆绑 Python 生态的复杂度。docker-compose 双服务编排推荐用 docker-compose 同时编排 9Router 与 Headroomservices: 9router: image: decolua/9router:latest ports: - 20128:20128 volumes: - $HOME/.9router:/app/data environment: DATA_DIR: /app/data HEADROOM_URL: http://headroom:8787 depends_on: - headroom headroom: image: ghcr.io/chopratejas/headroom:latest ports: - 8787:8787要点9Router 通过HEADROOM_URL: http://headroom:8787指向 compose 网络内的 Headroom 服务名headroom仓库自带的 docker-compose.yml 还包含restart: always、命名卷9router-data、.env文件注入等增强配置可在此基础上扩展启动后在控制台进入Endpoint → Token Saver → Headroom确认 URL 为http://headroom:8787重新检查状态后启用 Headroom 即可。Headroom 跑在宿主机上的情况如果 Headroom 运行在 Docker 宿主机而非容器内macOS/Windows 可直接使用http://host.docker.internal:8787Linux 需要在启动参数中加--add-hosthost.docker.internal:host-gateway或使用 compose 的extra_hosts等价配置。从源码理解 Headroom 探测逻辑src/lib/headroom/detect.js 揭示了 9Router 与 Headroom 的交互细节DEFAULT_HEADROOM_URL process.env.HEADROOM_URL || http://localhost:8787第 49 行环境变量是默认 URL 的注入点与上文settingsRepo.js一致probeProxyRunning()第 124-133 行通过请求{url}/health并设置 1.5 秒超时来探测 Headroom 是否存活这就是控制台“重新检查状态”按钮背后的实现isLoopbackHeadroomUrl()第 135-142 行判断 URL 是否为 localhost/127.0.0.1/::1 等回环地址决定是否允许 9Router 在本地拉起 Headroom 进程canStart标志HEADROOM_COMPRESSION_EXTRAS [code, ml]第 8 行通过pip list --formatjson检测 tree-sitter、torch 等标记包判断已安装的压缩增强组件。同时 settingsRepo.js 中headroomEnabled: false、headroomUrl属于默认设置项说明启用 Headroom 需要先在控制台显式打开开关。升级到最新版本docker pull decolua/9router:latest docker rm -f 9router # 重新执行快速启动命令由于数据存放在宿主机卷$HOME/.9router中删除并重建容器不会丢失配置、数据库与证书。若使用 compose直接docker compose pull docker compose up -d即可完成滚动升级。开发者本地构建与发布本地构建镜像测试仓库根目录的 Dockerfile 采用多阶段构建builder → runnercd app docker build -t 9router . docker run --rm -p 20128:20128 \ -v $HOME/.9router:/app/data \ -e DATA_DIR/app/data \ 9router构建细节值得注意基础镜像为node:22-alpineDockerfilebuilder 阶段安装python3 make g linux-headers以满足原生依赖编译runner 阶段只拷贝public、.next/static、.next/standalone、custom-server.js、open-sse、src/mitm等必要产物Dockerfile其中 MITM 子进程及其依赖node-forge、next是显式补齐的——注释说明 Next 的 tracing 可能遗漏这些旁路文件这属于镜像瘦身与运行完备性之间的权衡入口脚本 entrypoint.sh 先修复挂载卷权限再以su-exec node降权运行避免以 root 常驻仓库还附带 start.sh 脚本封装了“停旧容器 → 删旧容器 → 构建 → 带.env与命名卷启动”的完整流程可直接参考。CI 自动发布推送形如v*的 git tag 后GitHub Actions 工作流app/.github/workflows/docker-publish.yml会自动构建多架构镜像amd64arm64并推送至两个镜像仓库ghcr.io/decolua/9router:v{version}:latestdecolua/9router:v{version}:latest推荐使用仓库内的发布脚本node scripts/release.js Release title Notes或手动打标签git tag v0.4.x git push origin v0.4.x常见问题排查思路容器内数据不持久化确认同时设置了-v挂载与-e DATA_DIR/app/data二者缺一不可端口被占用修改PORT环境变量与-p映射为同一新端口Headroom 状态一直显示不可用检查HEADROOM_URL是否指向 Headroom 实际监听地址在容器内用curl http://headroom:8787/health验证连通性权限问题导致启动失败挂载卷属主与容器内node用户不一致时入口脚本会自动chown若宿主目录只读可检查宿主机挂载点权限跨平台迁移直接拷贝$DATA_DIR含db/data.sqlite到新宿主机对应路径即可注意 Windows 上不要配置 Unix 风格绝对路径的DATA_DIR源码会自动回退。通过以上步骤你已经可以完成 9Router 在 Docker 环境下的完整部署、数据管理、Headroom 侧车接入与自定义镜像构建。【免费下载链接】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），仅供参考