# 运维与降级操作手册

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

---

## 1. 角色与职责

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

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

---

## 2. 日常巡检清单

| 时间频率 | 检查项 | 通过标准 | 指标/命令 |
|----------|--------|----------|-----------|
| 每 15 分钟 | WS 延迟 / 重连 | `pacifica_ws_reconnects_total` 无增长 | `curl /metrics | grep ws_reconnect` |
| 每小时 | 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 人工强制降级

```bash
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`
  ```json
  { "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 / 回归测试

在恢复前运行：

```bash
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。
