# 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）之后运行，并自行提供锁、通知与失败监控；这正是本服务已经处理的部分。