第 9 章 · 02 定时任务与生产部署
文档摘要
第 9 章 · 02 定时任务与生产部署 本节摘要：本节讲 Sequoia-X 「从开发机到生产机」的最后一步——定时任务与生产部署。Sequoia-X 设计目标是「每天收盘后 23 分钟自动跑完」——这个目标只有挂上 crontab 才能实现。本节会先讲「为什么需要定时任务」（人不可能每天手动跑）+「为什么是 crontab」（Linux/macOS 通用、最轻量）；再讲「推荐的时间点」——19:00（收盘后 4 小时给 baostock 数据汇总留缓冲）；然后讲「完整的 crontab 配置」——虚拟环境、日志重定向、错误通知；最后讲「部署检查清单」——上线前必查的 6 件事。学完本节，你就能把 Sequoia-X 装到服务器上「挂着跑」。
第 9 章 · 02 定时任务与生产部署
本节摘要：本节讲 Sequoia-X 「从开发机到生产机」的最后一步——定时任务与生产部署。Sequoia-X 设计目标是「每天收盘后 2~3 分钟自动跑完」——这个目标只有挂上 crontab 才能实现。本节会先讲「为什么需要定时任务」（人不可能每天手动跑）+「为什么是 crontab」（Linux/macOS 通用、最轻量）；再讲「推荐的时间点」——19:00（收盘后 4 小时给 baostock 数据汇总留缓冲）；然后讲「完整的 crontab 配置」——虚拟环境、日志重定向、错误通知；最后讲「部署检查清单」——上线前必查的 6 件事。学完本节，你就能把 Sequoia-X 装到服务器上「挂着跑」。
内容来源：原项目说明文档 + 通用 Linux 部署实践。
💡 核心心法：好的「自动化」不是「让脚本能跑」，而是「让脚本在对的时刻自动跑」——cron + 日志重定向 + 异常通知三件套是 Linux 服务的「入门套装」。
学习目标
阅读完本章，你应当能够：
- 讲清「为什么需要 crontab」的产品理由与工程理由。
- 配置一个完整的 crontab 项让 Sequoia-X 自动跑。
- 知道「为什么 19:00」是推荐时间点。
- 列出「部署检查清单」——上线前必查的 6 件事。
一、为什么需要定时任务
最朴素的问题：「为什么不每天收盘后手动跑一次？」答案有三层：
| 理由 | 解释 |
|---|---|
| 人会忘记 | 一年 250 个交易日，手动跑 1 次都不能漏——不现实 |
| 人会拖延 | 「等下跑」变成「明天跑」——选股信号错过最佳时机 |
| 人会出错 | 环境配错、命令敲错、Web 钩子复制错——自动化避免 |
「自动化」的本质是「把人的不可靠因素排除」——让脚本在对的时刻自动跑。
二、为什么是 crontab
Linux 系统自带多个定时任务方案：
| 方案 | 优势 | 劣势 | Sequoia-X 的选择 |
|---|---|---|---|
| crontab | 简单、通用、最轻量 | 无复杂调度 | ✅ |
| systemd timer | 现代、支持依赖 | 配置复杂 | ❌ |
| Airflow | 强大调度（DAG） | 重量级、需要额外服务 | ❌ |
| 第三方 cron（Celery 等） | 分布式 | 引入新组件 | ❌ |
Sequoia-X 选 crontab——**「够用就好」**的工程哲学。
三、推荐时间点：每个交易日 19:00
0 19 * * 1-5 cd <项目根目录> && <虚拟环境>/python <主程序入口> >> <日志文件> 2>&1
时间点分析：
| 节点 | 时间 | 原因 |
|---|---|---|
| 收盘 | 15:00 | A 股交易结束 |
| 数据汇总 | 15:00~18:00 | baostock 等数据源需要约 2~3 小时完成汇总 |
| 跑任务 | 19:00 | 4 小时缓冲——数据已就绪 |
| 推送到达 | 19:00~19:05 | 用户晚上看手机——及时收到 |
为什么是 19:00 而非 15:30？
- 15:30 跑很可能拉到尚未汇总的当日数据——有缺失；
- 19:00 跑数据已稳定——信号可靠。
「晚 4 小时跑」是数据完整性与用户体验的平衡——早跑可能漏信号，晚跑用户可能睡了。
四、完整 crontab 配置
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ # Sequoia-X V2 - A 股量化选股系统 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ # 每个交易日 19:00 自动跑 # 工作目录：/root/Sequoia-X # 虚拟环境：/root/Sequoia-X/.venv # 日志文件：/root/Sequoia-X/log/cron.log # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ # 环境变量（crontab 不会自动加载 .bashrc） SHELL=/bin/bash PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin PROJECT_DIR=/root/Sequoia-X PYTHON=/root/Sequoia-X/.venv/bin/python 0 19 * * 1-5 cd $PROJECT_DIR && $PYTHON <主程序入口> >> $PROJECT_DIR/log/cron.log 2>&1
配置要点：
4.1 cd $PROJECT_DIR && 前置
cd $PROJECT_DIR && <command>
为什么？crontab 的工作目录是 $HOME——不是项目目录——cd 把工作目录切到项目——./data/sequoia_v2.db 路径才正确。
4.2 <虚拟环境>/python
/root/Sequoia-X/.venv/bin/python
为什么用绝对路径的 venv python？crontab 不加载 shell 的 PATH——直接用系统 python 可能找不到包。绝对路径保证用的是 venv 里的 python。
4.3 >> 与 2>&1 日志重定向
>> $PROJECT_DIR/log/cron.log 2>&1
>>追加（保留历史日志）——vs>覆盖；2>&1把错误输出也重定向到同一文件——所有输出都有记录。
没有日志重定向，crontab 会把输出发邮件——用 Linux 自带 postfix 会导致本地邮件堆积。
4.4 1-5 星期一到星期五
0 19 * * 1-5
A 股交易只在周一到周五——周末跑没有意义——白浪费系统资源。
五、推荐目录结构
生产环境推荐用这个目录结构：
/root/Sequoia-X/ ← 项目根 ├── .venv/ ← Python 虚拟环境 ├── <项目源码> ← Sequoia-X 源码 ├── data/sequoia_v2.db ← SQLite 数据库 ├── log/ ← 日志目录 │ ├── cron.log ← crontab 输出（每日追加） │ └── sequoia_2024-06-15.log ← 单次运行的详细日志（可选） ├── <本地配置文件> ← 含飞书 Webhook 等 └── ...
为什么把日志分目录？
cron.log持续追加——反映长期健康度；- 单次运行日志按日期分文件——问题排查方便。
简单场景下，只用
cron.log也够——单一文件胜过复杂目录。
六、异常通知：让失败可见
crontab 默认不会通知失败——失败时只在 cron.log 里写错误。生产环境推荐加异常通知：
方案 1：把日志推送到飞书
# 在 crontab 末尾追加：错误时推送到飞书 0 19 * * 1-5 cd $PROJECT_DIR && $PYTHON <主程序入口> >> $PROJECT_DIR/log/cron.log 2>&1 || \ curl -X POST "https://open.feishu.cn/open-apis/bot/v2/hook/<失败通知的 token>" \ -H "Content-Type: application/json" \ -d '{"msg_type":"text","content":{"text":"🚨 Sequoia-X 运行失败，请查 log"}}'
失败时额外发一条飞书消息——让运维「秒级感知」**。
方案 2：用系统 mail
# 让 cron 把失败信息发邮件 0 19 * * 1-5 cd $PROJECT_DIR && $PYTHON <主程序入口> || echo "Sequoia-X failed" | mail -s "🚨 Sequoia-X alert" admin@example.com
简单场景可用——需要系统装 postfix/sendmail。
方案 3：直接用 loguru 推送到 Slack/Discord
在主程序里直接集成异常通知——比 cron 层更可靠（失败时 cron 自身可能没机会发通知）。
实际生产环境推荐方案 1 或 3——与现有监控系统集成。
七、部署检查清单
上线前必查的 6 件事：
| 检查项 | 检查方式 | 失败怎么办 |
|---|---|---|
| ① 虚拟环境创建 | which python 应返回 venv 内 |
uv venv 或 python -m venv |
| ② 依赖安装 | python -c "import baostock, akshare, pandas" |
uv sync 或 pip install -e . |
| ③ 数据库存在 | ls data/sequoia_v2.db |
跑 python <主程序入口> --backfill |
| ④ 配置正确 | cat <环境变量文件> 检查 FEISHU_WEBHOOK_URL |
填入真实 token |
| ⑤ 手动跑通 | python <主程序入口> 看输出 |
修复日志中的错误 |
| ⑥ crontab 已加 | crontab -l |
重新 crontab -e |
部署的「六必查」——每件都不能漏——漏一件就埋雷。
八、典型部署时间线
首次部署 Sequoia-X 到生产机的标准步骤：
# 第 1 步：拉取项目 cd /root git clone <项目仓库> Sequoia-X cd Sequoia-X # 第 2 步：创建虚拟环境并装依赖 uv venv source .venv/bin/activate uv sync # 第 3 步：配置环境变量 cp <环境变量模板> <本地配置> # 编辑本地配置，填入 FEISHU_WEBHOOK_URL # 第 4 步：回填全市场数据（首次约 12 分钟） python <主程序入口> --backfill # 第 5 步：手动跑一次日常模式（验证配置） python <主程序入口> # 检查飞书群是否收到消息 # 第 6 步：配置 crontab crontab -e # 添加：0 19 * * 1-5 cd /root/Sequoia-X && /root/Sequoia-X/.venv/bin/python <主程序入口> >> /root/Sequoia-X/log/cron.log 2>&1 # 第 7 步：验证 crontab crontab -l # 等下一个交易日 19:00 后检查 cron.log
「七步部署」——从克隆代码到自动运行——约 30 分钟。
九、生产环境监控
部署完不是「一劳永逸」——Sequoia-X 作为长期运行的服务，需要基本监控：
| 监控项 | 工具 | 频率 |
|---|---|---|
| cron.log 大小 | du -h log/cron.log |
每周 |
| 数据库大小 | du -h data/sequoia_v2.db |
每周 |
| 选股结果数量 | grep "选出" log/cron.log | tail |
每天 |
| 错误日志 | grep -i "error" log/cron.log |
每天 |
| 飞书消息到达 | 看飞书群 | 每天 |
每天花 1 分钟看 log——比「半年不查、出问题再查」好得多。
十、本节在全景图的位置
定时任务与生产部署 ✅ ← 本节 │ ▼ 最后一节（第 03 节）扩展方向与架构反思
本节要点回顾
- 为什么需要 crontab：避免「人会忘记 / 拖延 / 出错」——自动化排除不可靠因素。
- 为什么是 19:00：A 股 15:00 收盘 + 4 小时缓冲——数据已就绪、用户还醒着。
- 完整 crontab 配置：
cd、venv 绝对路径、>> 追加 + 2>&1、1-5交易日。 - 异常通知：飞书 / 邮件 / loguru——让失败秒级可见。
- 六必查清单：虚拟环境、依赖、数据库、配置、手动跑、crontab——每件不能漏。
- 七步部署：克隆 → venv → 依赖 → 配置 → 回填 → 手动跑 → crontab——30 分钟。
- 每日监控：cron.log 大小、选股数量、错误日志——每天 1 分钟。
下一节是全教程的最后一节——讲「Sequoia-X 的扩展方向与架构反思」。