如何用 Docker 运行 9Router 官方镜像并把数据持久化到宿主机的 ~/.9router？-编程实验室

如何用 Docker 运行 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

这篇文章解决一个具体的部署任务：用 Docker 运行 9Router 官方镜像，让应用数据落在宿主机的~/.9router/目录，而不是随容器删除而丢失。完成后的结果是：docker run启动容器后访问http://localhost:20128能打开 9Router 面板，SQLite 主库持久化在宿主机的$HOME/.9router/db/data.sqlite。

官方文档见 DOCKER.md 与 README.md 的 Docker 章节；镜像发布在 Docker Hub 的decolua/9router（GHCR 上为ghcr.io/decolua/9router），是多平台镜像，支持linux/amd64和linux/arm64。

前置条件

宿主机已安装可用的 Docker（用于docker run/docker pull）。
宿主机 20128 端口未被占用，应用默认监听该端口。
宿主机上$HOME/.9router/目录可以不存在，直接执行挂载命令即可由 Docker 创建。

运行官方镜像并绑定宿主机数据目录

9Router 镜像内的数据目录由DATA_DIR环境变量决定。DOCKER.md明确说明：如果不设置DATA_DIR，应用会回退到~/.9router/（macOS/Linux）或%APPDATA%\9router\（Windows）；在容器里把DATA_DIR设为/app/data，绑定挂载才能生效。

因此最短可行的启动命令是DOCKER.md给出的 Quick start：

docker run -d \ -p 20128:20128 \ -v "$HOME/.9router:/app/data" \ -e DATA_DIR=/app/data \ --name 9router \ decolua/9router:latest

各部分的用途：

-p 20128:20128：把容器内应用端口映射到宿主机 20128；
-v "$HOME/.9router:/app/data"：把宿主机~/.9router挂载为容器内的/app/data，这是持久化的关键；
-e DATA_DIR=/app/data：告诉容器内应用数据写到挂载点，而不是容器可写层；
--name 9router：后续docker logs/docker stop等命令都依赖这个名字。

README.md的 Quick start 与上述命令参数相同，只是参数顺序不同，可以任选其一。

持久化后数据目录里有什么

数据落在$DATA_DIR/下，DOCKER.md给出的结构如下：

$DATA_DIR/ ├── db/ │ ├── data.sqlite # main SQLite database │ └── backups/ # auto backups └── ... # certs, logs, runtime configs

对应到宿主机与容器的具体路径：

宿主机：$HOME/.9router/db/data.sqlite
容器内：/app/data/db/data.sqlite

README.md的 Runtime Files and Storage 部分补充：data.sqlite是主应用状态（providers、combos、aliases、keys、settings、usage history），自动备份在${DATA_DIR}/db/backups/下。

关于~/.9router与/app/data的关系，两处文档说法略有出入，如实列出供核对：

README.md 说容器内${DATA_DIR}和~/.9router解析到同一位置，构建时创建符号链接/root/.9router -> /app/data；
Dockerfile 实际执行的RUN命令创建的是mkdir -p /app/data-home和ln -sf /app/data-home /root/.9router，另外镜像的 entrypoint 会在运行时对/app/data与/app/data-home执行chown（由su-exec以 node 用户启动）。

无论符号链接指向哪个中间目录，数据访问的正确路径都以DATA_DIR=/app/data为准，这也是 Quick start 命令显式传入该变量的原因。

验证数据确实写在宿主机上

用docker logs -f 9router查看日志，确认容器正常启动，没有启动阶段报错。
浏览器打开 http://localhost:20128 ，能访问 9Router 面板说明服务在监听 20128 端口。
在宿主机上确认持久化路径已生成，例如查看~/.9router/db/data.sqlite是否存在；在面板中保存过 provider、key 或设置等数据后，再检查该文件有更新，即可确认数据写入了宿主机而不是容器内部。

容器管理、更新与删除

DOCKER.md给出的日常管理命令：

docker logs -f 9router # view logs docker stop 9router # stop docker start 9router # start again docker rm -f 9router # remove

README.md还列出了等价的docker restart 9router与docker stop 9router && docker rm 9router写法。

更新到最新镜像的流程：

docker pull decolua/9router:latest docker rm -f 9router # re-run the quick start command

注意docker rm -f 9router只删除容器本身，不会删除宿主机上的~/.9router/目录；重新执行 quick start 命令后，原有数据照常可用。这是“数据持久化到宿主机”与直接用容器内存储的核心区别。

可选：额外环境变量

如果默认行为不满足，DOCKER.md列出了可选的docker run变体，可在此基础上追加：

docker run -d \ -p 20128:20128 \ -v "$HOME/.9router:/app/data" \ -e DATA_DIR=/app/data \ -e PORT=20128 \ -e HOSTNAME=0.0.0.0 \ -e DEBUG=true \ --name 9router \ decolua/9router:latest

PORT/HOSTNAME：Docker 环境默认就是20128与0.0.0.0，显式写入只是把默认值固定下来；
DEBUG=true：打开调试输出，排查启动或请求问题时使用。

README.md的环境变量表中与本场景相关的还有：JWT_SECRET（默认自动生成在~/.9router/jwt-secret）、INITIAL_PASSWORD（无已保存密码哈希时的首次登录密码，默认123456）、ENABLE_REQUEST_LOGS（设为true时在logs/下开启请求/响应日志）。完整的变量与默认值见 README.md 的 Environment Variables 一节。

另一个注意事项：.env不会被打进镜像（被.dockerignore排除），运行时的配置需要用--env-file或-e注入。

可选替代：仓库内的 docker-compose 写法

仓库根目录提供了 docker-compose.yml，它用 named volume 而不是宿主机绑定挂载：

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

与本文目标的两点差异：

数据落在 named volume9router-data，而不是宿主机~/.9router/；如果目标是“数据在~/.9router”，仍应使用上一节的docker run绑定挂载方式；
该文件引用了env_file: .env并带有一个 headroom sidecar 服务，直接照搬前需要自备.env文件；DOCKER.md也说明 9Router 镜像不捆绑 Python 或 Headroom，Headroom 需作为独立服务运行。

边界与限制

镜像默认端口是 20128，宿主机端口被占用时-p映射需要调整，但容器内应用监听端口由PORT决定。
若要把 9Router 暴露到公网，README.md建议设置REQUIRE_API_KEY=true对/v1/*路由强制 Bearer API key，并在 HTTPS 反向代理后设置AUTH_COOKIE_SECURE=true。
数据目录权限问题由镜像自身的 entrypoint 处理（启动时对/app/data执行chown），一般不需要额外干预；如果日志中出现权限相关报错，先按第 4 节的docker logs -f 9router查看具体信息。