📚 课程目录第4章开发环境准备

4. 开发环境准备

量化实盘服务对运行环境的要求比普通脚本高得多：它需要长期稳定运行、依赖版本可复现、行情与交易接口能稳定连通，还要能在不同机器上快速重建。因此本章的目标不是“把软件装上”，而是搭建一套可复现、可迁移、可加速的开发底座。我们分三步走：安装 Docker、配置国内镜像加速、搭建 Python 量化开发环境与依赖管理。

一、核心原理：为什么量化服务要用 Docker

量化系统通常由行情采集、策略计算、风控、下单执行、监控告警等多个进程组成，它们对 Python 版本、第三方库（如 pandas、numpy、TA-Lib、ccxt、vnpy）的版本非常敏感。传统“本机 pip 安装”方式容易出现三类问题：一是环境漂移，今天能跑明天升级了某个包就崩；二是依赖冲突，不同策略需要不同版本的库；三是迁移困难，换一台服务器要重新踩一遍坑。

Docker 通过镜像（Image）与容器（Container）把应用和依赖打包在一起。镜像相当于一份只读的“环境快照”，容器是它的运行实例。镜像分层（Layer）机制让基础系统、Python、依赖包、业务代码各占一层，构建时可复用缓存，传输时只传增量。这样我们就能做到：开发机、测试机、实盘服务器使用同一镜像，行为一致。

关键概念对照：镜像 = 类，容器 = 实例；Dockerfile = 构建镜像的配方；docker-compose = 多容器编排；Volume = 数据持久化；Registry = 镜像仓库。

二、安装 Docker 与配置国内镜像加速

以主流 Linux 服务器（Ubuntu/Debian 系）为例，推荐使用官方脚本或 apt 源安装。安装完成后必须做两件事：启动服务、配置国内镜像加速，否则拉取镜像会非常慢甚至超时。

# 1. 安装 Docker（Ubuntu 示例）
curl -fsSL https://get.docker.com | sh

# 2. 启动并设置开机自启
sudo systemctl enable --now docker

# 3. 将当前用户加入 docker 组，避免每次 sudo
sudo usermod -aG docker $USER
newgrp docker

# 4. 验证
docker version
docker run --rm hello-world

接下来配置镜像加速。编辑 /etc/docker/daemon.json，写入国内加速地址（可配置多个，Docker 会依次尝试）：

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com",
    "https://mirror.baidubce.com"
  ],
  "log-driver": "json-file",
  "log-opts": { "max-size": "100m", "max-file": "3" }
}

# 重载配置并重启
sudo systemctl daemon-reload
sudo systemctl restart docker

# 查看加速是否生效
docker info | grep -A 5 "Registry Mirrors"

加速地址会随时间变化，若某个镜像源失效，换用其他可用源即可。日志轮转配置（max-size/max-file）对长期运行的实盘服务非常重要，可防止日志撑爆磁盘。

三、搭建 Python 量化开发环境与依赖管理

不建议直接在宿主机装 Python 量化库，而是用 Dockerfile 定义环境。下面是一个面向量化开发的镜像示例，基于官方 Python 镜像，安装常用量化依赖，并使用国内 pip 源加速。

# Dockerfile
FROM python:3.11-slim

ENV PYTHONUNBUFFERED=1 \
    PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple \
    TZ=Asia/Shanghai

WORKDIR /app

# 系统依赖（编译 TA-Lib、数据库客户端等）
RUN apt-get update && apt-get install -y --no-install-recommends \
    build-essential gcc g++ make wget \
    libpq-dev && rm -rf /var/lib/apt/lists/*

# 先复制依赖清单，利用缓存
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD ["python", "-m", "strategy.main"]

依赖管理推荐使用 requirements.txt 锁定版本，或用 pip-tools、poetry 生成锁定文件。量化项目常见依赖如下：

类别	常用库	作用
数据处理	pandas、numpy、polars	行情清洗与因子计算
技术指标	TA-Lib、pandas-ta	均线、MACD、RSI 等
交易接口	ccxt、vnpy、ib_insync	对接交易所/券商
回测框架	backtrader、vectorbt	策略验证
服务与调度	fastapi、apscheduler、redis	API、定时任务、缓存
监控日志	loguru、prometheus-client	日志与指标采集

构建并运行：

docker build -t quant-dev:0.1 .
docker run -it --rm -v $(pwd):/app quant-dev:0.1 bash

下面这张图展示了从开发机到实盘服务器的环境一致性链路，以及镜像加速在其中的位置：

四、常见误区与复盘

误区一：把代码 COPY 进镜像后频繁重建。开发阶段应使用 Volume 挂载源码目录，镜像只承载依赖，代码改动无需重新构建。
误区二：不锁版本。只写 pandas 而不写版本，某天上游更新可能导致策略结果变化。务必锁定版本或使用锁定文件。
误区三：忽略时区。量化交易对时间极其敏感，容器默认 UTC，需设置 TZ=Asia/Shanghai 并确认行情时间戳口径。
误区四：容器内数据不持久化。行情缓存、日志、持仓状态必须挂载 Volume，否则容器重建即丢失。
误区五：镜像加速配了但没重启 Docker。修改 daemon.json 后必须 systemctl restart docker 才生效。

实盘服务器上不要使用 latest 标签，应使用明确版本号（如 quant-dev:0.1），避免某次拉取到不兼容的新镜像导致服务异常。上线前先在测试容器中跑通行情连接与下单链路。

完成本章后，你应当拥有一台可构建量化镜像的机器、一个配置了国内加速的 Docker 环境，以及一份可复现的 Python 依赖清单。这套底座是后续编写策略、回测、部署实盘服务的基础，环境越稳定，后面排障的成本就越低。