1.2 源码部署

1.2 源码部署

本节摘要：一键安装适合「用系统」，源码部署适合「改系统」。本节先给选择标准：当你想改代码、学架构、调试问题或向上游贡献时，就到了走这条路的时候；日常运行仍建议容器形态。然后按「克隆 ──▶ Python 3.12 虚拟环境 ──▶ 安装依赖 ──▶ 准备配置 ──▶ 初始化数据库 ──▶ 启动应用与 worker」给出完整步骤（写法示意，以官方文档为准）。再介绍最常用的混合形态：数据库与队列用容器、应用进程跑源码，兼顾开发体验与生产形态。最后用一张模块职责表导读仓库的主要目录，为第 2 章的架构拆解铺路。

学习目标

• 用四个判据决定走一键安装还是源码部署。
• 在 Python 3.12 虚拟环境里完成依赖安装与配置初始化。
• 搭出「基础设施容器化 + 应用跑源码」的混合开发形态。
• 建立仓库主要模块的职责地图，知道去哪里找什么。

一、什么时候选源码

经验法则：运行用容器，开发用源码。两者不冲突——本书后续章节的代码阅读与调试均以源码形态为准，长期运行则以容器形态为准。

二、源码部署步骤

# bash —— 克隆与虚拟环境（命令形态示意，以官方文档为准）
git clone https://github.com/OpenByteInc/QuantDinger.git
cd QuantDinger
python -m venv .venv
source .venv/bin/activate      # Windows PowerShell 用 .venv\Scripts\Activate.ps1
python --version               # 期望：3.12.x（官方技术栈口径）
​

# bash —— 依赖与配置（示意；文件名以仓库实际为准）
pip install -r requirements.txt
cp .env.example .env
# 编辑 .env：数据库与 Redis 连接串、密钥类变量；
# 混合形态下指向你为开发准备的容器化基础设施
​

# bash —— 初始化数据库并启动（示意；初始化命令以官方文档为准）
# 数据库迁移：等价于一键安装里 migration 容器做的事
python -m <migration 入口命令>
# 启动 HTTP API（开发模式，示意）
python <backend 入口命令>
# 另开终端：启动 trading-worker / celery-worker 等进程
python <worker 入口命令>
​

三个注意点：第一，数据库迁移永远先于应用启动，顺序错了应用会连不上表结构；第二，开发模式下 worker 与 backend 是独立进程，各开各的终端，日志才分得开；第三，配置里任何口令都不要沿用模板默认值（1.3 节展开）。

三、混合形态：基础设施容器化，应用跑源码

这是日常开发的推荐形态——数据库与队列有容器管生命周期，应用进程裸跑便于断点与热改：

# docker-compose.dev.yml —— 开发用基础设施（节选示意，以官方仓库模板为准）
services:
  postgres:
    image: postgres:18
    environment:
      POSTGRES_PASSWORD: "改成你自己的强口令"
    ports:
      - "127.0.0.1:5432:5432"     # 只绑定本机回环地址
    volumes:
      - pgdata_dev:/var/lib/postgresql/data
  redis:
    image: redis:8
    ports:
      - "127.0.0.1:6379:6379"
volumes:
  pgdata_dev:
​

# bash —— 混合形态启动顺序（示意）
docker compose -f docker-compose.dev.yml up -d   # 起 PostgreSQL 与 Redis
python -m <migration 入口命令>                     # 迁移
python <backend 入口命令>                          # API
python <worker 入口命令>                           # worker（另开终端）
​

注意端口映射写法：127.0.0.1:5432:5432 只把服务暴露给本机，去掉 127.0.0.1 前缀则会监听所有网卡——开发机尤其不要犯这个错（1.3 节的安全基线之一）。

四、仓库模块导读

（目录名以仓库当前版本为准，此处按官方口径的功能模块划分。）

读源码的入口建议：从进程入口文件读起（每个进程一个入口），顺着启动流程读到主循环——第 2 章会替你把这条路走一遍。

本节要点回顾

• 判据一句话：运行用容器，开发用源码；改代码、学架构、调试、贡献走源码路径。
• 步骤骨架：克隆 ──▶ venv ──▶ 依赖 ──▶ 配置 ──▶ 迁移 ──▶ 启动，迁移永远先于应用。
• 混合形态是开发日常：PostgreSQL 与 Redis 容器化，backend 与 worker 跑源码。
• 端口映射带 127.0.0.1 前缀，开发机也不裸暴露。
• 模块职责表是源码导航图，从进程入口文件读起最省力。

至此系统有两种形态可供驱使，但「跑起来」和「跑得安全」之间还差一节功课。下一节处理部署后必须立刻做的三件事：改默认口令、管住 API key、把端口从公网上收回来。