update service

docs/deployment.md

@@ -0,0 +1,74 @@
+# 8H 预测服务部署
+
+## 方案对比
+
+| 方案 | 适用场景 | 本项目的限制 |
+| --- | --- | --- |
+| cron | 单机、只需固定时间执行一条命令 | 需要额外处理 K 线入库延迟、重启后重复运行、互斥锁、通知失败重试和结构化日志。 |
+| Python 常驻服务 | 需要状态、通知和后续扩展 | 需要由 systemd 或其他进程管理器守护。 |
+
+当前实现选择 Python 常驻服务。它每 `poll_seconds` 秒检查一次，但只会在 UTC 的 `00:00`、`08:00`、`16:00` 后经过 `grace_seconds`，针对刚结束的 8H K 线执行一次。成功状态只会在预测和全部通知都成功后写入；通知或预测失败时，下一次轮询会重试同一根 K 线，进程异常退出时由 systemd 重启。
+
+## 配置
+
+复制 [`config/prediction-service.yml.example`](../config/prediction-service.yml.example) 到 `/etc/cbpred/prediction-service.yml`，填写实际路径、Webhook 和 SMTP 参数。字符串中的 `${NAME}` 会在进程启动时从环境变量读取；缺失的变量会使服务启动失败，避免把空密钥发送到外部服务。
+
+例如，`/etc/cbpred/prediction-service.env`：
+
+```text
+CBPRED_WEBHOOK_TOKEN=replace-with-webhook-token
+CBPRED_SMTP_PASSWORD=replace-with-smtp-password
+```
+
+将其设为仅服务账户可读，例如 `chmod 600 /etc/cbpred/prediction-service.env`。不要把密钥提交到仓库。
+
+HTTP 通知默认发送 `event`、K 线结束时间、`report.json` 摘要和全部 CSV 行；可在各个目标上设置 `include_predictions: false` 或 `max_rows`。邮件会包含摘要并默认附加 `predictions.csv`。HTTP 或邮件任一失败，状态文件不会推进，因此会重试。
+
+## 验证和安装
+
+先执行一次只读调度检查。若当前不在 K 线完成后的宽限期内，它会正常退出且不执行预测：
+
+```bash
+/data/quant/cbpred/.venv/bin/python -m cbpred.prediction_service \
+  --config /etc/cbpred/prediction-service.yml --once
+```
+
+将 [`scripts/cbpred-prediction.service`](../scripts/cbpred-prediction.service) 安装为 systemd unit：
+
+```bash
+sudo install -d -m 755 /etc/cbpred
+sudo install -d -o ctyun -g ctyun -m 750 /var/lib/cbpred
+sudo install -o root -g ctyun -m 640 config/prediction-service.yml.example /etc/cbpred/prediction-service.yml
+sudo install -o root -g ctyun -m 640 config/prediction-service.env.example /etc/cbpred/prediction-service.env
+sudo install -m 644 scripts/cbpred-prediction.service /etc/systemd/system/cbpred-prediction.service
+sudo systemctl daemon-reload
+sudo systemctl enable --now cbpred-prediction.service
+sudo systemctl status cbpred-prediction.service
+```
+
+查看运行日志：
+
+```bash
+journalctl -u cbpred-prediction.service -f
+```
+
+服务使用状态文件锁避免并发重复运行。不要为同一套输出目录同时启用 `update_and_predict.sh` 的 cron 作业和该服务。
+
+没有系统管理员权限时，可使用已启用 linger 的用户级 systemd。它使用同一套服务逻辑，但配置与状态文件放在当前用户目录：
+
+```bash
+install -d -m 700 ~/.config/cbpred ~/.local/state/cbpred ~/.config/systemd/user
+install -m 600 config/prediction-service.user.yml.example ~/.config/cbpred/prediction-service.yml
+install -m 600 config/prediction-service.env.example ~/.config/cbpred/prediction-service.env
+install -m 644 scripts/cbpred-prediction.user.service ~/.config/systemd/user/cbpred-prediction.service
+systemctl --user daemon-reload
+systemctl --user enable --now cbpred-prediction.service
+```
+
+查看用户服务日志：
+
+```bash
+journalctl --user -u cbpred-prediction.service -f
+```
+
+如果只需 cron，可将 `scripts/update_and_predict.sh` 安排在 `2 0,8,16 * * *`（UTC）之后运行，并自行提供锁、通知与失败监控；这正是本服务已经处理的部分。