Docker 部署

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

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

必须持久化conf/、数据库、logs/、result/ 应挂载到宿主机目录。

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

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

docker run 示例

镜像地址后续可替换为正式发布地址。下面以 ghcr.io/apkpai/rtkhub:latest 作为示例：

docker run -d \
  --name rtkhub \
  --restart unless-stopped \
  -p 5426:5426 \
  -v /opt/rtkhub/conf:/app/conf \
  -v /opt/rtkhub/data:/app/data \
  -v /opt/rtkhub/logs:/app/logs \
  -v /opt/rtkhub/result:/app/result \
  ghcr.io/apkpai/rtkhub:latest \
  ./rtkhub -s -k conf/rtkhub.list

启动后访问：

http://服务器IP:5426

生产环境建议只在内网访问，或通过 Nginx、Cloudflare Tunnel、VPN 暴露。

Docker Compose

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

services:
  rtkhub:
    image: ghcr.io/apkpai/rtkhub:latest
    container_name: rtkhub
    restart: unless-stopped
    working_dir: /app
    command: ["./rtkhub", "-s", "-k", "conf/rtkhub.list"]
    ports:
      - "5426:5426"
    volumes:
      - ./conf:/app/conf
      - ./data:/app/data
      - ./logs:/app/logs
      - ./result:/app/result

启动：

docker compose up -d

查看日志：

docker compose logs -f rtkhub

停止：

docker compose down

升级镜像：

docker compose pull
docker compose up -d

配置文件

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

conf/rtkhub.list 示例：

[network]
name=DemoNet
dir=./result/%Y/%n/

[channels]
./conf/demo/base-rover.conf,BASE-ROVER,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 5426:5426 \
  -v /opt/rtkhub/conf:/app/conf \
  -v /opt/rtkhub/logs:/app/logs \
  -v /opt/rtkhub/result:/app/result \
  ghcr.io/apkpai/rtkhub:latest \
  ./rtkhub -s -k conf/rtkhub.list

串口部署前检查：

宿主机能否读取 /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/data rtkhub/logs rtkhub/result

升级步骤：

停止或暂停关键基线。
备份 conf/、data/、logs/、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` 和宿主机权限
容器重启后数据丢失	数据写入容器临时层	持久化 `data/`、`logs/`、`result/`

生产检查清单

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

推荐目录​

docker run 示例​

Docker Compose​

配置文件​

串口和设备​

反向代理​

备份和升级​

排查命令​

生产检查清单​

推荐目录