【Python量化系统工程实战 #08】从脚本到生产：量化系统上线 checklist 的最小闭环

系列完结篇：前 7 篇我们解决了「数据怎么存、自动怎么跑、挂了怎么知道、缺口怎么补」。本篇把脚本变成生产系统的最后 1 公里——环境隔离、日志轮转、数据备份、灰度对比、回滚预案，每一项都是「出事时不至于半夜爬起来」的兜底。

一、从个人脚本到生产系统的差距

很多量化代码跑完回测就上线，结果第一周就出各种事故：

• 环境：同事用的 Python 3.12，自己机器是 3.9，pandas API 行为不一致 → 报错
• 日志：脚本跑了两周，logs/app.log 已经 8 GB，tail 命令打不开 → 排错要等 5 分钟
• 数据：升级版 SQLite schema 后忘了备份，旧版本数据没了 → 重新拉 3 天
• 灰度：新策略直接替换旧策略，3 天后收益率掉 30% → 不知道该不该回滚
• 回滚：出问题想回滚，但没提前准备备份，也不知道回滚要多久

上线 checklist 的目标：任何动作都有预演，任何事故都有兜底。

二、本文你将得到什么

1. 环境隔离自检脚本：5 行检测 venv / 依赖 / 磁盘，避免「在我机器能跑」问题
2. 日志轮转：1 MB × 5 个文件自动切换，避免日志膨胀
3. 数据备份：一行 shutil.copy2 给 SQLite 打时间戳快照
4. 灰度对比：新旧策略并行跑一次，差异阈值报警
5. 回滚预案：3 步从「出问题」恢复到「上次能用」

三、上线 checklist 总表

按重要性排序，前 3 项是「不做立马翻车」，后 2 项是「做了才稳」：

#	项目	风险	兜底
1	环境隔离	依赖冲突 / Python 版本错位	venv + 依赖版本锁
2	日志轮转	日志爆炸 / 排错难	RotatingFileHandler
3	数据备份	数据丢失 / 升级翻车	时间戳 .bak 副本
4	灰度对比	新策略不稳定	v1 vs v2 并行观察
5	回滚预案	出问题没法恢复	备份覆盖 + 二次回滚

四、环境隔离：5 行自检脚本

「在我机器能跑，到服务器就崩」的根因就是环境没隔离。生产环境必须用虚拟环境（venv 或 conda env），且依赖版本要钉死。

import sys, shutil

def check_env_isolation():
    is_venv = (
        sys.prefix != sys.base_prefix
        or "envs" in sys.executable.lower()
        or ".venv" in sys.executable.lower()
    )
    print(f"Python: {sys.executable}")
    print(f"隔离环境: {'✅' if is_venv else '❌'}")
    for pkg in ["mairui", "pandas", "numpy", "apscheduler"]:
        try:
            mod = __import__(pkg)
            print(f"{pkg}: ✅ v{getattr(mod, '__version__', '?')}")
        except ImportError:
            print(f"{pkg}: ❌")
    du = shutil.disk_usage(".")
    free_mb = round(du.free / 1024 / 1024, 1)
    print(f"磁盘剩余: {free_mb} MB {'✅' if free_mb > 500 else '⚠️'}")

实测：

Python: <your_python>
隔离环境: ✅
mairui: ✅ v1.0.0
pandas: ✅ v2.2.3
numpy: ✅ v2.0.2
apscheduler: ✅ v3.10.4
磁盘剩余: 58760.6 MB ✅

额外动作：

• requirements.txt 钉死版本（mairui==1.0.0 不要写 mairui）
• pyproject.toml 或 Pipfile.lock 锁整个依赖图
• 生产环境加 pip-audit 跑漏洞扫描
• Docker 化可直接跳过 Python 版本问题（但 Dockerfile 本身也要版本锁）

五、日志轮转：RotatingFileHandler

策略跑一个月，logs/app.log 单文件能从 0 涨到 10 GB，tail 都打不开，必须轮转：

import logging
from logging.handlers import RotatingFileHandler
import os

def setup_logging(log_path: str = "logs/app.log"):
    os.makedirs(os.path.dirname(log_path), exist_ok=True)
    root = logging.getLogger()
    root.setLevel(logging.INFO)
    root.handlers.clear()  # 重要：避免重复挂载
    fmt = logging.Formatter("%(asctime)s [%(levelname)s] %(message)s")
    # 1 MB 切一次，保留 5 个历史文件
    fh = RotatingFileHandler(
        log_path, maxBytes=1024 * 1024, backupCount=5, encoding="utf-8"
    )
    fh.setFormatter(fmt)
    root.addHandler(fh)
    # 同时输出 console 便于调试
    sh = logging.StreamHandler()
    sh.setFormatter(fmt)
    root.addHandler(sh)

实测：

2026-09-11 10:06:26 [INFO] [test] 第 1 条测试日志
2026-09-11 10:06:26 [INFO] [test] 第 2 条测试日志
2026-09-11 10:06:26 [INFO] [test] 第 3 条测试日志
2026-09-11 10:06:26 [INFO] [test] 第 4 条测试日志
2026-09-11 10:06:26 [INFO] [test] 第 5 条测试日志

已写入 logs/app.log (440 bytes)

轮转策略选择：

• RotatingFileHandler：按文件大小切（适合写日志频率稳定的场景）
• TimedRotatingFileHandler：按时间切（每天/每小时一个文件，适合审计）
• 生产建议两个都上：大小轮转保底 + 时间轮转便于合规审计

六、数据备份：一行 shutil.copy2

升级 schema 前、出问题想回滚前，先备份再说。SQLite 单文件数据库备份成本最低：

import shutil, os
from datetime import datetime

def backup_database(db_path: str, backup_dir: str = "backups") -> str:
    if not os.path.exists(db_path):
        return ""
    os.makedirs(backup_dir, exist_ok=True)
    ts = datetime.now().strftime("%Y%m%d_%H%M%S")
    backup_path = os.path.join(backup_dir, f"{os.path.basename(db_path)}.{ts}.bak")
    shutil.copy2(db_path, backup_path)
    return backup_path

实测：

备份成功: backups\history_kline.db.20260911_100626.bak (24576 bytes)

生产备份三重门：

1. 本地快照（每次升级 / 重大操作前）—— 上节代码
2. 每日定时全量：cron 0 2 * * * python backup.py，保留 7 天 / 4 周 / 6 月滚动
3. 异地容灾：每天 rsync 到另一台机器或对象存储（OSS / COS / S3）

copy2 会保留原文件的 mtime + permission，比 copy 更适合做备份（出问题一眼看出哪个是旧的）。

七、灰度对比：新旧策略并行跑一次

新策略不能「直接替换上线」。标准做法是保留旧版 + 新版并行跑 1 周，对比夏普 / 收益 / 最大回撤：

def gray_release_compare(stocks, licence):
    """v1 vs v2 各跑一次，对比结果（演示证用同一价格代替真实策略差异）。"""
    results = {"v1": {}, "v2": {}, "diff": 0}
    for stock in stocks:
        from mairui import Client
        cli = Client(licence)
        raw = cli.stock_history(
            code=stock, st="2025-12-01", et="2025-12-01",
            period="d", dividend="f"
        )
        price = float(raw[-1].get("c", 0.0)) if raw else 0.0
        results["v1"][stock] = price   # 旧策略结果
        results["v2"][stock] = price   # 新策略结果（演示证同价）
        print(f"  {stock}: v1={price:.2f} v2={price:.2f}")
    results["diff"] = sum(
        abs(results["v1"][s] - results["v2"][s]) for s in stocks
    )
    return results

实测：

600519: v1=11.33 v2=11.33 ✅
000001: v1=11.33 v2=11.33 ✅
300750: v1=11.33 v2=11.33 ✅
累计绝对偏差: 0.0000

真实部署的对比维度：

• 收益曲线：日收益、夏普、最大回撤
• 稳定性：连续亏损天数、最大单日亏损
• 延迟：从拿到数据到信号产生的时间
• 资源占用：CPU / 内存峰值

灰度期间任一关键指标恶化超过阈值（如夏普下降 30%），立即停止灰度、回滚到 v1。

八、回滚预案：3 步恢复

回滚的关键是「回滚本身不出错」。三个关键动作：

import shutil, os

def rollback(db_path: str, backup_path: str) -> bool:
    if not (backup_path and os.path.exists(backup_path)):
        return False
    # 1. 备份当前主库（万一回滚失败还能再回滚一次）
    pre_rollback = db_path + ".pre_rollback.bak"
    shutil.copy2(db_path, pre_rollback)
    # 2. 用备份覆盖主库
    shutil.copy2(backup_path, db_path)
    # 3. 健康检查（连接 + 必要表存在）
    import sqlite3
    try:
        conn = sqlite3.connect(db_path)
        conn.execute("SELECT COUNT(*) FROM kline").fetchone()
        conn.close()
        return True
    except Exception:
        return False

实测：

回滚成功: history_kline.db ← backups\history_kline.db.20260911_100626.bak
(回滚前快照保留: history_kline.db.pre_rollback.bak)

回滚操作 SOP：

1. 停服务：kill 进程（避免回滚瞬间被新数据污染）
2. 备份当前状态：放 .pre_rollback.bak 防回滚本身出错
3. 执行覆盖：shutil.copy2(backup_path, db_path)
4. 健康检查：连接 DB + 必要表 + 行数对账
5. 重启服务：先 dry-run，再 open
6. 监控盯盘：5 / 15 / 60 分钟分阶段确认

九、上线 checklist 操作清单

顺序	动作	命令 / 代码
1	拉最新代码	git pull
2	创建新 venv	python -m venv venv && source venv/bin/activate
3	装依赖	pip install -r requirements.txt
4	环境自检	python main.py env
5	备份主库	python backup.py
6	灰度上线（v1 + v2 并行）	python run_gray.py
7	24h 后对比指标	python compare.py
8	通过 → 全量切换	python run.py --version v2
9	失败 → 立即回滚	python rollback.py
10	写上线报告	release_notes.md

十、常见坑

1. 「直接覆盖生产代码」：永远不要跳过灰度直接换版本。即使是「一行小修改」，都可能引入逻辑变化。
2. 回滚忘了停服务：回滚瞬间，旧服务的进程还在跑、可能写新数据 → 把回滚覆盖的目标文件又污染了。先 stop、再 copy、再 start。
3. 备份文件不清理：每天都跑备份，一个月后 1000 个 .bak 文件。保留策略——7 天 / 4 周 / 6 个月滚动，cron 自动删老文件。
4. 日志没分级：DEBUG / INFO 一起写，生产环境日志几小时内几个 G。生产用 WARNING 级，DEBUG 仅测试环境开。
5. **「在我机器能跑」**永远是上线前要避免的。Docker 化或 requirements.txt 钉死 + 同一 Python 版本，三者至少占其一。
6. 没有「回滚预算」：每次上线都准备 30 分钟回滚窗口；超过 30 分钟还没回滚成功 = 二次事故，先应急止血（暂停服务）再继续排查。

十一、小结（系列完结）

整套「数据 → 调度 → 监控 → 一致性 → 补采 → 上线」的工程体系，8 篇走完：

#	主题
#01	数据存储选型：CSV / SQLite / MySQL
#02	APScheduler 自动采集流水线
#03	监控告警：异常检测 + 推送
#04	数据一致性校验与版本管理
#05	多策略并行与进程隔离
#06	项目骨架与最小可运行架构
#07	历史数据补采与回填
#08	上线 checklist（本文）

读者画像升级路径：

• 看完 #01–#04：从「能跑回测」到「数据自动跑、出了问题能发现」
• 看完 #05–#07：从「单策略」到「多策略协同、缺口可补」
• 看完 #08：从「脚本」到「生产系统」—— 上线有 checklist、出问题有兜底

「量化系统的工程能力 = 策略 × 100 后的稳定性」。 同样一套策略，工程差距可以让年化收益 ± 30% 甚至更多。把工程做扎实，才能让策略的预期收益在生产环境真实兑现。

---

免责声明：本文仅供技术学习交流，不构成任何投资建议。量化策略回测表现不代表未来收益，投资有风险，决策需谨慎。

代码与文档：github.com/MaiRuiApi