Docker 部署

不要将数据写入容器临时层

Docker 适合用于演示、测试、标准化交付和云服务器部署。RTKHUB 本身仍然需要稳定的数据源、持久化目录和清晰的网络边界，生产环境不要把配置、日志和结果文件放在容器临时层里。容器销毁后临时层数据将永久丢失。

适用场景云服务器、实验环境、内网统一部署、需要快速迁移的测网服务。

必须持久化conf/、database/、log/、result/ 应挂载到宿主机目录。

不适合直接容器化强依赖 Windows 工具链、物理串口直连、特殊 USB 设备或未验证驱动的场景。

必须挂载的持久化目录

以下目录必须挂载到宿主机，否则容器销毁或重启后数据将丢失：

conf/ — 测网和基线配置
数据库文件 — 用户、权限、设置、任务
log/ — 运行日志和审计日志
result/ — POS 结果文件

Docker 不适合的场景

以下场景不建议使用 Docker 部署 RTKHUB：

强依赖 Windows 工具链的环境
物理串口直连或特殊 USB 设备
未验证驱动的嵌入式平台

这些场景建议使用原生 Windows 或 Linux 部署。

目录	用途	建议
`conf/`	测网、基线和 RTKLIB 配置	变更前备份
`database/`	SQLite 数据库和运行状态	持久化，不随容器删除
`log/`	程序日志、审计日志	定期归档
`result/`	POS 结果文件	放在空间充足的磁盘

docker run 示例

当前主项目提供 Dockerfile，默认在 Debian 13 slim 中构建 RTKHUB，运行镜像暴露 5426，并设置 RTKHUB_WEB_BIND=0.0.0.0。先在主项目根目录构建本地镜像：

docker build -t rtkhub:latest .

然后启动容器：

docker run -d \
  --name rtkhub \
  --restart unless-stopped \
  -p 127.0.0.1:5426:5426 \
  -v /opt/rtkhub/conf:/app/conf \
  -v /opt/rtkhub/database:/app/database \
  -v /opt/rtkhub/log:/app/log \
  -v /opt/rtkhub/result:/app/result \
  rtkhub:latest

启动后访问：

http://127.0.0.1:5426

端口映射安全

-p 127.0.0.1:5426:5426 只允许宿主机本机访问。生产环境建议再通过 Nginx、Cloudflare Tunnel 或 VPN 暴露；不要把 5426 直接映射到公网。

Docker Compose

推荐生产环境使用 Compose 管理启动参数和挂载目录：

services:
  rtkhub:
    build:
      context: .
      dockerfile: Dockerfile
    image: rtkhub:latest
    container_name: rtkhub
    restart: unless-stopped
    ports:
      - "127.0.0.1:5426:5426"
    volumes:
      - ./conf:/app/conf
      - ./database:/app/database
      - ./result:/app/result
      - ./log:/app/log

启动：

docker compose up -d

查看日志：

docker compose logs -f rtkhub

停止：

docker compose down

主项目 Dockerfile 默认命令是 ["./rtkhub", "-nc", "-k", "conf/rtkhub.list"]。升级本地镜像：

docker compose build --pull
docker compose up -d

配置文件

容器内路径建议统一使用相对路径，避免宿主机路径和容器路径混用。

conf/rtkhub.list 示例：

[DemoNet]
dir=./result/%Y/%n/
netllh=34.23247305,108.95249131,399.012
./conf/test.conf,TEST01,34.235,108.909,384,34.235,108.909,384

基线配置中的输出路径也建议指向挂载目录：

outstr1-type    = file
outstr1-path    = ./result/%Y/%n/%r_%Y%m%d.pos

串口和设备

如果数据源来自物理串口，容器需要显式映射设备：

docker run -d \
  --name rtkhub \
  --restart unless-stopped \
  --device /dev/ttyUSB0:/dev/ttyUSB0 \
  -p 127.0.0.1:5426:5426 \
  -v /opt/rtkhub/conf:/app/conf \
  -v /opt/rtkhub/database:/app/database \
  -v /opt/rtkhub/log:/app/log \
  -v /opt/rtkhub/result:/app/result \
  rtkhub:latest

串口部署前检查：

宿主机能否读取 /dev/ttyUSB0。
容器运行用户是否有串口权限。
串口重插后设备名是否会变化。
是否需要使用 /dev/serial/by-id/ 这样的稳定路径。

反向代理

如果需要 HTTPS，建议在宿主机或网关层做反向代理，不建议 RTKHUB 容器直接暴露到公网。

Nginx 示例：

server {
    listen 443 ssl;
    server_name rtkhub.example.com;

    ssl_certificate /etc/nginx/certs/fullchain.pem;
    ssl_certificate_key /etc/nginx/certs/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:5426;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

如果服务器不方便开放公网端口，可以使用 Cloudflare Tunnel：

rtkhub.example.com -> http://127.0.0.1:5426

备份和升级

升级前先备份宿主机目录：

cd /opt
tar czf rtkhub-backup-$(date +%Y%m%d_%H%M%S).tar.gz rtkhub/conf rtkhub/database rtkhub/log rtkhub/result

升级步骤：

停止或暂停关键基线。
备份 conf/、database/、log/、result/。
重新构建或拉取新镜像。
重新启动容器。
检查 Web 控制台、API、关键基线和结果文件。

排查命令

docker ps
docker logs --tail 200 rtkhub
docker exec -it rtkhub sh
docker inspect rtkhub
curl http://127.0.0.1:5426

常见问题：

现象	可能原因	处理
Web 打不开	端口未映射或服务未启动	检查 `docker ps` 和日志
配置未生效	挂载目录错误	检查容器内 `/app/conf`
无结果文件	输出路径未指向挂载目录	检查 `outstr1-path`
串口不可用	未映射设备或权限不足	检查 `--device` 和宿主机权限
容器重启后数据丢失	数据写入容器临时层	持久化 `database/`、`log/`、`result/`

生产检查清单

镜像版本固定，不长期使用未知 latest。
conf/、database/、log/、result/ 都已挂载。
不把 NTRIP 密码、账号或内网地址写入镜像层。
Web 端口只对可信网络开放。
已配置备份任务和恢复演练。
升级前能回滚到旧镜像和旧配置。

推荐目录​

docker run 示例​

Docker Compose​

配置文件​

串口和设备​

反向代理​

备份和升级​

排查命令​

生产检查清单​

推荐目录