1.1 一键安装
1.1 一键安装
本节摘要：本节走部署主路径：Docker Compose 一键安装。先列系统要求（操作系统、Docker 版本、内存与磁盘预算，均标注口径），再按「装 Docker ──▶ 获取仓库 ──▶ 准备配置 ──▶ compose up ──▶ 首启验证」五步给出完整命令（写法示意，以官方仓库 README 为准）。部署完成后，用一张容器角色表回答「我刚才到底启动了什么」：六个应用进程加 PostgreSQL、Redis、Prometheus、Grafana 各司其职。最后给首启常见问题排查表——migration 未完成就访问、端口占用、镜像拉取失败，并以「部署后的第一小时」观察清单收尾。本节结束时你应该能打开 Web UI 并看到空空如也但健康运行的系统。
学习目标
- 按五步完成一键部署并通过首启验证。
- 说出首次启动后每个容器的角色与相互依赖。
- 用容器角色表定位「哪个容器出问题会影响什么」。
- 独立排查三个最常见的首启故障。
一、系统要求
| 项 | 要求 | 口径 |
|---|---|---|
| 操作系统 | 任意能稳定运行 Docker 的 64 位系统（Linux 为佳） | 通用建议 |
| Docker 与 Compose | 近期稳定版，含 compose 子命令 | 以 Docker 官方文档为准 |
| 内存 | 8 GB 起（含数据库、队列、行情存储的整机预算） | 示意值 |
| 磁盘 | 20 GB 余量起（行情数据随时间增长） | 示意值 |
| 网络 | 能访问镜像仓库与目标交易所接口 | 部署前提 |
官方技术栈为 Python 3.12、PostgreSQL 18、Redis 8、Flask/Gunicorn、Celery（官方 README/文档口径）——一键安装路径下这些全部由容器承担，宿主机不需要预装。
二、五步部署
# bash —— 第一步：环境自检（示意） docker --version docker compose version
# bash —— 第二步：获取仓库（命令形态示意，以官方仓库 README 为准） git clone https://github.com/OpenByteInc/QuantDinger.git cd QuantDinger
# bash —— 第三步：准备配置（示意；变量名以官方模板为准） cp .env.example .env # 编辑 .env：至少检查数据库口令、初始管理员口令等安全相关项， # 不要使用模板默认口令（详见 1.3 节）
# bash —— 第四步：拉取并启动（示意） docker compose pull docker compose up -d
# bash —— 第五步：首启验证（示意） docker compose ps # 期望：核心服务陆续进入运行状态 docker compose logs -f migration # 期望：迁移执行完毕、无报错后退出或保持健康
首启验证的判据：docker compose ps 里应用与基础设施服务为运行或健康状态；migration 日志没有循环报错；随后浏览器访问 Web UI（默认地址与端口以官方文档为准）能出现登录页。第一次启动要等数据库迁移与初始化完成，耐心是排查的第一工具。
首启通过后，再做一轮主动核验（示意命令，服务名以官方 compose 文件为准）：
# bash —— 部署后核验（示意） docker compose ps # 全部服务处于运行或健康状态 docker compose logs --tail 50 backend # 抽查：无循环报错 docker compose logs --tail 50 trading-worker # 抽查：交易循环正常启动 docker system df # 记录磁盘占用基线，留作增长对照
最后一行不是多余的：把部署完成当天的磁盘占用记下来，三个月后你才能回答「行情数据到底长了多大、要不要扩盘」——第 11 章的容量规划从这一行开始。
三、你启动了什么：容器角色表
| 容器 | 类别 | 角色 | 出问题时的影响 |
|---|---|---|---|
| migration | 应用 | 首启执行数据库建表与版本迁移（一次性） | 库结构未就绪，其余服务反复重连失败 |
| backend | 应用 | HTTP API 与 Web UI 后端，只读写数据库与队列 | 页面打不开、接口全挂；交易循环仍在 worker 里跑 |
| trading-worker | 应用 | 交易长循环：驱动策略、订单生命周期 | 策略停摆、订单状态不再推进 |
| scheduler-worker | 应用 | 调度循环：周期性任务的编排 | 定时数据同步、对账类任务停摆 |
| celery-worker | 应用 | 异步任务执行：回测、数据处理等重活 | 回测提交后无响应、任务积压 |
| celery-beat | 应用 | 定时任务节拍器：按计划投递任务 | 周期任务不再按时触发 |
| PostgreSQL | 基础设施 | 唯一事实源：状态、订单、行情落库 | 全系统不可用 |
| Redis | 基础设施 | 队列与缓存 | 任务投递中断、backend 大面积报错 |
| Prometheus | 基础设施 | 指标采集与存储 | 监控断档，交易不受影响 |
| Grafana | 基础设施 | 指标可视化面板 | 看不到图表，其余正常 |
（进程职责的详细拆解见第 2.1 节；这里只需要建立「一张 ps 输出的心智地图」。）
把角色表压成分层图，排查顺序一目了然：
容器依赖分层（自底向上看） [ PostgreSQL Redis ] 基础设施：一切的地基 ▲ ▲ └[ migration ] 闸门：库结构就绪才放行上层 ▲ [ backend trading-worker scheduler-worker ] 应用：库结构就绪后并行启动 ▲ [ celery-worker celery-beat ] 异步：队列可达后启动
这张图和第 2.1 节的启动顺序表是同一件事的两种视角：表格回答「谁等谁」，分层图回答「挂了下层为什么上层全痛」。第 1.3 节的端口排查与第四部分的故障表，走的都是这张图的自底向上路径。
四、首启常见问题
| 症状 | 常见原因 | 处理（示意） |
|---|---|---|
| 访问 Web UI 报数据库错误 | migration 尚未完成就访问 | 看 migration 日志，等其完成再刷新 |
| 某容器反复重启 | 配置项缺失或口令不含法字符 | docker compose logs <服务名> 定位缺失变量 |
| 端口被占用 | 宿主机已有服务占用同端口 | 停占用方或在配置中改端口映射（以官方文档为准） |
| 镜像拉取失败或缓慢 | 网络到镜像仓库不畅 | 配置可用的镜像源后重拉；勿来路不明的第三方镜像 |
| 磁盘迅速吃紧 | 日志或行情数据增长超预期 | 检查磁盘预算与日志级别（第 11 章展开） |
排查总原则：先看 migration 与 PostgreSQL，再看 backend，最后看各 worker——依赖链自底向上，底层健康才有上层症状可解。
五、部署后的第一小时
部署成功的标准不是「页面能打开」，而是你对系统建立了基线认知。第一小时按这张清单观察（全部动作只读不写）：
| 序 | 观察项 | 期望 | 异常时 |
|---|---|---|---|
| 1 | docker compose ps 全量状态 |
无反复重启的行 | 记下服务名，查其日志 |
| 2 | Web UI 登录与页面巡览 | 能登录、各页面可打开 | 回看第四部分排查表 |
| 3 | 监控面板 | 指标曲线在动 | 检查采集服务是否健康 |
| 4 | 日志抽样（backend 与两个 worker） | 无循环报错 | 记录报错原文，查 issue 或回退版本 |
| 5 | 磁盘与内存占用 | 记录基线数值 | 超出预算先扩资源再谈业务 |
第一小时里最重要的一条纪律：不要急着接交易所、不要急着跑策略。系统此刻空空如也但健康运行——这正是做基线记录的最佳状态；等数据和策略都进来之后再想拿到「干净的基线」，就要费劲得多。
本节要点回顾
- 五步主路径：装 Docker ──▶ 获取仓库 ──▶ 准备配置 ──▶ compose up ──▶ 首启验证。
- 首启验证盯两处：ps 的健康状态、migration 的日志。
- 容器角色表是运维心智地图：六应用进程 + 四基础设施，各管一段。
- 排查自底向上：数据库 ──▶ API ──▶ worker。
- 部署完成后的第一件事是观察（ps、日志、监控面板），不是交易。
- 部署后第一小时做基线观察：状态、页面、日志、磁盘，只读不写。
系统已经跑起来，但一 键安装把所有细节封在了镜像里。下一节给需要打开引擎盖的读者：源码部署——什么时候值得走这条路，以及完整的克隆、依赖、配置与初始化步骤。