QuantDingerQuantDingerv5.7.1 Docs 文档中心
English GitHub
查看 Markdown 源文件

QuantDinger 云服务器部署指南

本文说明当前版本 QuantDinger 在云服务器上的 Docker 部署方式，覆盖推荐的 GHCR 预构建镜像部署、可选源码部署、Nginx、HTTPS、升级和常见排错。

首次安装时如果遇到 Docker 拉镜像或 Postgres 启动问题，也请参考 安装排错指南。

推荐架构

推荐使用一个公网域名加宿主机 Nginx 反向代理：

  • Web 访问地址：https://app.example.com
  • 可选移动 H5 地址：https://m.example.com
  • 宿主机 Nginx 监听 80/443
  • Docker frontend 绑定到 127.0.0.1:8888
  • Docker mobile 绑定到 127.0.0.1:8889
  • Docker backend 绑定到 127.0.0.1:5000
  • Docker postgres、两类 Redis 与 Kafka 保持在 Docker 私网；如为排障映射到宿主机， 也只能绑定回环地址

公网只开放 80 和 443。不要把 5000、5432、6379、29092 暴露到公网。

1. 准备服务器

推荐配置：

  • Ubuntu 22.04 / 24.04 或 Debian 12
  • 轻量单机部署最低 4 核 8 GB 内存
  • 策略、AI 任务与回测同时运行时建议 8 核 16 GB 内存
  • 50 GB 以上磁盘，并为 PostgreSQL 备份与 Kafka 保留数据预留额外空间
  • 安全组或防火墙开放 22、80、443
  • 一个域名，例如 app.example.com

配置 DNS：

app.example.com -> 服务器公网 IP
m.example.com   -> 服务器公网 IP  # 可选移动 H5 域名

验证解析：

ping app.example.com

2. 安装 Docker

curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
newgrp docker
docker --version
docker compose version

请使用 Compose v2 命令：docker compose ...。

3. 选择部署模式

推荐：GHCR 预构建镜像部署

普通云服务器部署建议使用这个模式。后端、Web 前端、移动 H5 都从 GHCR 拉取镜像，不需要在服务器上本地构建 Python 或 Node 项目。

推荐直接使用一键安装程序。它会创建安装目录、生成随机本地凭据、要求设置初始管理员， 并启动服务：

curl -fsSL https://raw.githubusercontent.com/OpenByteInc/QuantDinger/main/install.sh | bash -s -- ~/quantdinger

如需手动管理下载的文件，请同时下载环境初始化脚本：

mkdir -p ~/quantdinger/scripts
cd ~/quantdinger
curl -O https://raw.githubusercontent.com/OpenByteInc/QuantDinger/main/docker-compose.ghcr.yml
curl -O https://raw.githubusercontent.com/OpenByteInc/QuantDinger/main/.env.example
curl -o scripts/bootstrap_env.py https://raw.githubusercontent.com/OpenByteInc/QuantDinger/main/scripts/bootstrap_env.py
python3 scripts/bootstrap_env.py --compose-file docker-compose.ghcr.yml

首次启动前编辑 .env：

ADMIN_USER=your_admin_user
ADMIN_PASSWORD=your_strong_password
FRONTEND_URL=https://app.example.com,https://m.example.com
ALLOW_LOCAL_DESKTOP_BROKERS=false

初始化脚本会生成 POSTGRES_PASSWORD、SECRET_KEY 和 CREDENTIAL_ENCRYPTION_KEY，且不会在终端输出密钥。不要重新生成正在使用的 PostgreSQL 密码；升级时再次运行同一命令会保留已有值，并在需要时从现有容器或旧 DATABASE_URL 安全恢复数据库密码。同一文件也保存 Compose 编排配置：

FRONTEND_HOST=127.0.0.1
FRONTEND_PORT=8888
MOBILE_HOST=127.0.0.1
MOBILE_PORT=8889
# 第一个地址是 OAuth 登录后的默认跳转目标
FRONTEND_URL=https://app.example.com,https://m.example.com
BACKEND_PORT=127.0.0.1:5000
DB_PORT=127.0.0.1:5432
REDIS_BIND=127.0.0.1:6379

# 固定版本，避免一直使用 latest，例如：
# IMAGE_TAG=5.5.1

# postgres/redis 拉取慢时可设置 Docker Hub 镜像前缀：
# IMAGE_PREFIX=docker.m.daocloud.io/library/

启动：

docker compose -f docker-compose.ghcr.yml pull
docker compose -f docker-compose.ghcr.yml up -d
docker compose -f docker-compose.ghcr.yml ps

宝塔面板 Docker 插件与端口修改

宝塔面板导入 Compose 项目后，容器详情页通常不能可靠地修改由 Compose 管理的端口。不要直接编辑已经创建好的容器端口；修改项目根目录 .env 后重新创建对应容器：

docker compose -f docker-compose.ghcr.yml up -d --force-recreate frontend mobile backend

backend 容器内部监听 5000 是应用协议的一部分，保持不变是正常的。BACKEND_PORT=127.0.0.1:5000 修改的是宿主机绑定；前端容器通过 Docker 网络访问 backend:5000。如需调整用户访问端口，只修改 FRONTEND_PORT / MOBILE_PORT，然后重新创建容器。

生产环境不要把 5000、5432、6379、29092 直接暴露到公网。宝塔或 1Panel 的 Nginx/OpenResty 应只对公网开放 80/443：页面请求转发到宿主机本地的 Web 前端端口（默认 127.0.0.1:8888），/api/ 请求直接转发到同样只绑定本机的后端端口 127.0.0.1:5000。这样仍保持浏览器同源，同时避免前端容器二次代理覆盖真实客户端 IP。

可选：完整源码部署

只有需要在服务器上基于本地源码构建后端时，才建议使用这个模式。

git clone https://github.com/OpenByteInc/QuantDinger.git
cd QuantDinger
python3 scripts/bootstrap_env.py

编辑 .env：

ADMIN_USER=your_admin_user
ADMIN_PASSWORD=your_strong_password
FRONTEND_URL=https://app.example.com,https://m.example.com
ALLOW_LOCAL_DESKTOP_BROKERS=false

启动：

docker compose pull
docker compose up -d --build
docker compose ps

4. 统一环境文件与升级同步

部署与应用配置统一使用项目根目录的一个文件：

文件 使用方 用途
.env Docker Compose 与全部后端进程 运行参数、凭据、端口、镜像 tag、数据库、Redis、Kafka 与 Worker 配置

拉取更新后，先运行 python3 scripts/bootstrap_env.py（GHCR 手动部署增加 --compose-file docker-compose.ghcr.yml），再执行任何 Compose 命令。初始化完成后， Compose 会运行一次性的 env-sync 服务，再启动数据库迁移和 Kafka 初始化。它会追加 新字段，并导入只存在于旧后端环境文件中的值，不替换当前值或注释；仅当 .env 确有变化时 才创建带时间戳的备份。以下手动命令仍可用于预检和维护：

python scripts/sync_env.py --env-file .env --template .env.example --backup

重新执行一键安装程序时也会自动做相同合并。手动执行旧版本首次迁移时可传入 --legacy backend.env 或 --legacy backend_api_python/.env；旧文件不会被删除。

升级前也可以再次执行 python3 scripts/bootstrap_env.py。它按顺序保留 .env 中的 POSTGRES_PASSWORD、从旧 DATABASE_URL 恢复，或从仍存在的 quantdinger-db 容器恢复。 如果检测到已有 PostgreSQL 数据卷但无法恢复密码，命令会停止而不是生成新密码，避免 让现有数据库失联。此时请从 .env 备份恢复原密码；不要删除数据卷。

5. 事件运行时与副本配置

默认服务栈现在会启动 Kafka、主题初始化器、Kafka 审计消费者、策略分发 Worker、 策略求值 Worker 和交易 Worker。Kafka 属于内部基础设施，端口 29092 只能绑定回环地址 或私网，不能直接暴露到公网。

单机副本数写在项目根目录 .env：

TRADING_WORKER_REPLICAS=1
STRATEGY_DISPATCHER_REPLICAS=1
STRATEGY_EVALUATOR_REPLICAS=1

首装默认采用每种角色一个副本，适合低负载单机并降低内存、数据库连接和运维复杂度。 单机也可以运行多个副本；完成压测后，再按 CPU、Kafka lag 和策略延迟逐步增加。

修改后只重建这些角色：

docker compose -f docker-compose.ghcr.yml up -d --force-recreate \
  trading-worker strategy-dispatcher-worker strategy-evaluator-worker

默认 Compose 不是多机集群定义。增加应用服务器前，应先把 PostgreSQL、两类 Redis 和 Kafka 迁移为共享的外部服务，并使用编排系统或等价部署层。发布顺序、所有权模型、回滚边界与十万策略 前置条件见分布式运行时部署与扩容。

6. 配置 Nginx

安装 Nginx：

sudo apt update
sudo apt install -y nginx

创建 /etc/nginx/sites-available/quantdinger.conf：

宿主机代理应在同一公网域名下拆分页面与 API：/api/ 直接进入只绑定本机的后端 5000，其余页面进入 Web 8888 或移动 H5 8889。不要把全部请求先送入前端容器再二次代理 API；新版后端会安全地验证代理来源，而二次代理可能把 X-Real-IP 覆盖为 Docker 网关地址。

server {
    listen 80;
    server_name app.example.com;

    client_max_body_size 20m;

    location = /api/ai/chat/message/stream {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        proxy_request_buffering off;
        proxy_connect_timeout 75s;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
        send_timeout 600s;
        add_header X-Accel-Buffering "no" always;
        add_header Cache-Control "no-cache, no-transform" always;
    }

    location ^~ /api/ {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";
        proxy_connect_timeout 75s;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }

    location / {
        proxy_pass http://127.0.0.1:8888;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

server {
    listen 80;
    server_name m.example.com;

    client_max_body_size 20m;

    location = /api/ai/chat/message/stream {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";
        proxy_buffering off;
        proxy_cache off;
        proxy_request_buffering off;
        proxy_connect_timeout 75s;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
        send_timeout 600s;
        add_header X-Accel-Buffering "no" always;
        add_header Cache-Control "no-cache, no-transform" always;
    }

    location ^~ /api/ {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Connection "";
        proxy_connect_timeout 75s;
        proxy_read_timeout 600s;
        proxy_send_timeout 600s;
    }

    location / {
        proxy_pass http://127.0.0.1:8889;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

如果不需要独立移动端域名，可以删除第二个 server 块。移动 H5 也可以通过你自己配置的端口、路径或域名访问。5000 仍只监听 127.0.0.1，由同机 Nginx/OpenResty 访问，不等于将后端端口暴露到公网。

启用站点：

sudo ln -s /etc/nginx/sites-available/quantdinger.conf /etc/nginx/sites-enabled/quantdinger.conf
sudo nginx -t
sudo systemctl reload nginx

如果使用 UFW：

sudo ufw allow OpenSSH
sudo ufw allow 'Nginx Full'
sudo ufw enable

7. 开启 HTTPS

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d app.example.com -d m.example.com
sudo certbot renew --dry-run

如果只配置了 app.example.com，证书申请命令里只保留这个域名即可。

访问：

https://app.example.com
https://m.example.com

8. 可选 API 子域名

推荐部署方式是在宿主机反向代理处保持同源并拆分流量：

Browser -> https://app.example.com -> 宿主机 Nginx -> /      -> frontend:8888
                                                    -> /api/ -> backend:5000

如果确实需要 api.example.com，只通过 Nginx 暴露宿主机本地后端端口：

server {
    listen 80;
    server_name api.example.com;

    client_max_body_size 20m;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

同时在后端运行时 env 中设置 FRONTEND_URL，包含所有用户实际访问的前端域名。

9. 常用运维

GHCR 部署：

docker compose -f docker-compose.ghcr.yml ps
docker compose -f docker-compose.ghcr.yml logs -f backend
docker compose -f docker-compose.ghcr.yml logs -f postgres
docker compose -f docker-compose.ghcr.yml logs -f kafka strategy-dispatcher-worker strategy-evaluator-worker trading-worker
docker compose -f docker-compose.ghcr.yml restart backend

更新 GHCR 镜像：

python3 scripts/bootstrap_env.py --compose-file docker-compose.ghcr.yml
docker compose -f docker-compose.ghcr.yml pull
docker compose -f docker-compose.ghcr.yml run --rm migration
docker compose -f docker-compose.ghcr.yml run --rm kafka-init
docker compose -f docker-compose.ghcr.yml up -d --remove-orphans

完整源码部署更新：

git pull --ff-only
python3 scripts/bootstrap_env.py
docker compose build backend
docker compose run --rm migration
docker compose run --rm kafka-init
docker compose up -d --remove-orphans

大版本升级前建议先备份 Postgres：

docker exec quantdinger-db pg_dump -U quantdinger quantdinger > quantdinger_backup.sql

10. Postgres 18 和已有数据

当前默认 Postgres 镜像是 postgres:18.3-alpine，PGDATA=/var/lib/postgresql/18/docker。

如果已有数据卷是 Postgres 16 初始化的，不要直接用 Postgres 18 启动。请选择：

  • 继续使用匹配的 Postgres 16 镜像，直到完成迁移；
  • 使用 pg_dump 和 pg_restore 导出导入；
  • 使用正式的 pg_upgrade 大版本迁移流程。

只有开发环境且数据库数据可以丢弃时，按你的部署模式选择命令。

GHCR 部署：

docker compose -f docker-compose.ghcr.yml down -v
docker compose -f docker-compose.ghcr.yml up -d

完整源码部署：

docker compose down -v
docker compose up -d

生产数据不要使用 down -v。

11. 常见问题

镜像拉取失败

如果 redis、postgres 或 Docker Hub 镜像拉取失败，可在项目根目录 .env 设置镜像前缀：

IMAGE_PREFIX=docker.m.daocloud.io/library/

然后重试：

docker compose -f docker-compose.ghcr.yml pull

如果 GHCR 镜像拉取失败：

docker pull ghcr.io/openbyteinc/quantdinger-backend:latest
docker pull ghcr.io/openbyteinc/quantdinger-frontend:latest
docker pull ghcr.io/openbyteinc/quantdinger-mobile:latest

常见原因包括网络阻断、包可见性不是 public、或者固定的 tag 不存在。

后端启动后立刻退出

查看日志：

docker compose -f docker-compose.ghcr.yml logs --tail=100 backend

常见原因：

  • 后端 env 文件语法错误；
  • 完整源码部署时 SECRET_KEY 仍是默认占位值；
  • 数据库没有健康启动；
  • 手动覆盖了错误的 DATABASE_URL。

Nginx 502 或页面空白

先检查本机服务：

curl http://127.0.0.1:8888/health
curl http://127.0.0.1:8889/health
curl http://127.0.0.1:5000/api/health
sudo nginx -t

再检查容器：

docker compose -f docker-compose.ghcr.yml ps
docker compose -f docker-compose.ghcr.yml logs --tail=100 frontend
docker compose -f docker-compose.ghcr.yml logs --tail=100 backend

注册或登录 IP 显示为 Docker 网关

如果审计记录中的客户端 IP 全部显示为 172.17.0.1、172.18.0.1、172.19.0.1 等私网地址，说明后端记录的是 Docker 网关，而不是真实访客地址。典型原因是宿主机代理先把全部请求送到 8888 或 8889，随后前端容器再次代理 /api/ 并覆盖 X-Real-IP。

使用第 6 节的拆分配置：

  • PC 和移动域名的 /api/ 都直接转发到 127.0.0.1:5000；
  • PC 页面 / 转发到 127.0.0.1:8888；
  • 移动 H5 页面 / 转发到 127.0.0.1:8889；
  • 每层受信代理都应覆盖 X-Real-IP，并使用 $proxy_add_x_forwarded_for 追加转发链；
  • 不要为了修复显示结果而让后端无条件信任来自公网的 X-Forwarded-For，否则客户端可以伪造审计 IP。

1Panel/OpenResty 经常把通用 location / 放在单独的 proxy/*.conf 中。改成完整站点配置时，不要同时保留另一个定义相同 location 的 include，否则 Nginx 会因重复 location 无法加载。历史记录不会自动修改；请在重载代理后用新登录或测试账号验证。

如果域名前还有 Cloudflare 或其他 CDN，宿主机看到的 $remote_addr 默认可能是 CDN 节点。应按照 CDN 官方公布的最新出口 CIDR 配置 Nginx real_ip 模块，并限制只有受信 CDN 可以访问源站；不要直接信任任意请求传入的 CF-Connecting-IP 或类似请求头。

AI 流式输出约 50～60 秒后中断

典型症状：

  • /api/ai/chat/message/stream 已返回部分内容，约 50～60 秒后在浏览器网络面板中变为失败；
  • 前端随后退回普通 /api/ai/chat/message 请求；
  • 后端容器没有重启、没有 OOM，后端日志也不一定出现 chat_message_stream failed。

这通常发生在宿主机 Nginx、1Panel OpenResty 等外层反向代理继续使用默认超时和响应缓冲时。即使 Docker 内部的前端代理已经配置 600 秒，外层代理仍可能先中断 SSE 连接。

在每个对外提供 AI 聊天的域名配置中，为 SSE 路径增加独立的精确匹配，并直接转发到只绑定宿主机本地的后端端口 5000：

location = /api/ai/chat/message/stream {
    proxy_pass http://127.0.0.1:5000;

    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header Connection "";

    proxy_buffering off;
    proxy_cache off;
    proxy_request_buffering off;

    proxy_connect_timeout 75s;
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
    send_timeout 600s;

    add_header X-Accel-Buffering "no" always;
    add_header Cache-Control "no-cache, no-transform" always;
}

1Panel OpenResty 的站点配置和日志通常挂载在：

/opt/1panel/www/sites/<域名>/proxy/
/opt/1panel/www/sites/<域名>/log/access.log
/opt/1panel/www/sites/<域名>/log/error.log

修改后先验证再重载；容器名以实际环境为准：

docker exec <openresty-container> /usr/local/openresty/nginx/sbin/nginx -t
docker exec <openresty-container> /usr/local/openresty/nginx/sbin/nginx -s reload

如果仍会中断，在错误日志中搜索 upstream timed out、upstream prematurely closed connection、499、502 和 504，同时检查后端容器的 RestartCount 与 OOMKilled。

交易所或 LLM 出网需要代理

后端运行时请求外网需要代理时，在 .env 设置 PROXY_URL。

在 Docker 容器内不要直接写宿主机的 127.0.0.1，除非代理就在同一个容器里。可以使用容器可访问的宿主机地址，例如：

PROXY_URL=socks5h://host.docker.internal:10808

Linux 服务器上可能需要把代理监听到内网地址，或配置 Docker host gateway。

公网端口

不要公开这些端口：

  • 5000
  • 5432
  • 6379

公网只开放：

  • 80
  • 443