grid_skeleton/docs/OPERATIONS_PLAYBOOK.md

运维与降级操作手册

提供日常巡检、故障响应、降级策略及人工干预流程，确保系统在异常环境下可控可退。

---

1. 角色与职责

角色	主要任务
值班工程师 (On-call)	监控报警、执行降级/恢复、记录 incident
策略负责人	审核参数、决策策略切换或停机
SRE / DevOps	维护基础设施、日志、告警渠道

所有关键操作需在 Slack #trading-ops 频道同步，并在 incident log 记录。

---

2. 日常巡检清单

时间频率	检查项	通过标准	指标/命令
每 15 分钟	WS 延迟 / 重连	pacifica_ws_reconnects_total 无增长	`curl /metrics
每小时	Delta 风险	delta_abs < max_base_abs * 0.5	Grafana 面板
每小时	Hedge 成功率	hedge_success_rate > 0.95，latency_p99 < 2s	Grafana
每 4 小时	资金费率相关性	funding_rate_correlation > 0.8	Funding 面板
每日	PnL 汇总	Intraday PnL 不超过 -0.5%	pnpm reports:daily
每小时	网格自适应状态	grid_step_bps 梯度平滑、grid_pending_hedges=0	/metrics -> grid_*

异常时立即记录：时间、指标、上下文。

---

3. 常见故障场景与操作

3.1 对冲连续失败

• 触发条件：hedge_failure_count >= 3 或报警 hedge_success_rate < 0.9
• 操作步骤：
  1. POST /api/override-degradation {"mode":"REDUCE_ONLY","reason":"hedge_fail"}；
  2. 检查对冲账户余额、API 状态；
  3. 手动对冲库存（/api/manual-hedge?symbol=BTC&size=0.3）；
  4. 恢复前执行回归测试（见第 5 节）。

3.2 行情数据断流

• 触发条件：pacifica_ws_gaps_total 提升或 data_gap_sec > 3
• 操作：
  1. OrderRouter.cancelAll(symbol)（API: POST /api/cancel-all）；
  2. POST /api/halt 暂停策略；
  3. 联系交易所确认网络状态；
  4. 数据恢复后执行金丝雀再上线。

3.3 Delta 失控

• 触发条件：delta_abs > max_base_abs 告警
• 操作：
  1. POST /api/override-degradation {"mode":"REDUCE_ONLY","reason":"delta_high"}；
  2. 触发 HedgeEngine.enqueueDelta，必要时人工平仓；
  3. 调整 grid.max_layers、grid_step_bps 或暂时关闭策略。

3.4 资金费率同向支付

• 触发条件：funding_same_sign_ratio > 0.2
• 操作：
  1. 减少持仓：grid.base_clip_usd 下调 30%，或禁用网格；
  2. 与策略负责人讨论是否关闭某个 venue；
  3. 记录 incident，跟踪资金费率走势。

3.5 API 认证失败 / 签名错误

• 症状：REST 返回 401 / WS AUTH_FAILED
• 操作：
  1. 立即 HALT (POST /api/halt)；
  2. 检查 .env 是否过期、时间同步 (ntp)；
  3. 更新密钥后重启 Runner；
  4. 验证签名测试通过 (pnpm test --filter contract。

---

4. 降级与恢复流程

4.1 自动降级矩阵回顾

场景	Action	触发方式
对冲失败	REDUCE_ONLY	风控自动
数据断流	HALT	降级策略
STP 率过高	DISABLE_SCALPER	降级策略
高波动	ADAPTIVE (grid.max_layers=1)	Adaptive Mode

4.2 人工强制降级

curl -X POST http://localhost:4000/api/override-degradation \
  -H 'Content-Type: application/json' \
  -d '{"mode":"HALT","reason":"manual_intervention"}'

• 支持模式：HALT, REDUCE_ONLY, NORMAL.
• 请求会记录 audit log（操作者、原因、时间）。

4.3 恢复流程

1. 完成根因确认；
2. 确认指标恢复正常（延迟、Delta、WS 状态）；
3. POST /api/override-degradation {"mode":"NORMAL"}；
4. 在 canary 模式跑 10 分钟；
5. 恢复生产，发布 incident 总结。

📣 Kill-switch 通知：Runner 会在触发时向 KILL_SWITCH_WEBHOOK（若配置）发送 JSON 负载，包含 status、gridStatus、source 等字段，用于集成 Slack / PagerDuty。默认日志位于 logs/runner-*.log。

---

5. 手动对冲与下单

• 手动对冲 API：POST /api/manual-hedge

  { "symbol": "BTC", "size": 0.25, "side": "sell", "reason": "manual_adjustment" }
  

  • 使用 hedger 账户 IOC 下单，记录 manual=true。

• 临时挂单：POST /api/manual-order → 仅在 reduce-only 模式下允许。

所有手动操作需记录：

• 操作人
• 触发指标
• 结果与后续动作

---

6. 日志与排障

日志文件	内容	查看命令
logs/runner-*.log	主流程、策略、Risk/Kill-switch、Grid 自适应事件	tail -f logs/runner-*.log
logs/execution.log	下单、撤单、错误码	less +F logs/execution.log
logs/metrics.log	指标采集快照	grep hedge_latency logs/metrics.log
logs/events.log	WS 事件 (JSONL)	jq '.' logs/events.log

排障流程：

1. 获取 traceId (grep traceId=<id> logs/app.log)
2. 追踪相关日志 (策略 → 下单 → 成交 → 对冲)
3. 如需回放，在 data/replay/incidents/ 保存事件序列。

---

7. Incident 记录模板

Incident ID: YYYYMMDD-HHMM-<short>
Severity: SEV2/SEV3
Start Time:
Detection Method: (Alert / Manual)
Primary Symptoms: (Delta spike / Hedge fail / WS gap)
Actions Taken:
  - 00:01 Set mode=REDUCE_ONLY
  - 00:03 Manual hedge 0.4 BTC
Resolution Time:
Root Cause:
Follow-up Tasks:

• 记录存放在 docs/incidents/，并在每周复盘会议回顾。

---

8. Goldens / 回归测试

在恢复前运行：

pnpm test --filter integration
pnpm backtest --config backtest/regression.yaml --from yesterday --to today

• 确保策略行为与基线一致，避免携带隐患。

---

9. 指标报警建议

指标	阈值	动作
hedge_success_rate < 0.9 (5 分钟)	Slack SEV2	触发 reduce-only
delta_abs > max_base_abs (1 分钟)	Slack SEV2	手动对冲
pacifica_ws_reconnects_total >= 3 (5 分钟)	Slack SEV3	检查网络/交易所
funding_rate_correlation < 0.8 (1 小时)	邮件	评估撤标的

---

10. 版本控制与回滚

• 所有策略、配置版本在 Git tag 中保留：strategy-vX.Y.Z.
• 回滚步骤：
  1. git checkout strategy-vX.Y.Z
  2. pnpm install && pnpm run build
  3. pnpm run live -- --config config/config.yaml --rollback
  4. 验证指标正常后发布公告。

---

11. 手册维护

• 更新流程：任何新报警、降级策略或 API 变更需 PR 更新本文件。
• 每季度复审一次，结合最新 incident 调整 SOP。