# 运维手册

## 日常检查

```powershell
docker compose ps
docker compose logs --since=30m api
docker compose logs --since=30m whatsapp-gateway
Invoke-RestMethod http://127.0.0.1:8088/health
docker compose exec api node -e "fetch('http://127.0.0.1:3100/health/ready').then(async r=>{console.log(await r.text());process.exit(r.ok?0:1)})"
```

重点关注：API 错误率、Webhook 延迟与死信数、出站队列深度、WebSocket 在线数、AI 延迟/限流、数据库连接与磁盘、渠道断线数。

## 常见故障

### 页面“加载失败”

1. 检查 `web` 与 `api` 健康状态。
2. 检查浏览器请求的 HTTP 状态和 API 日志。
3. `401` 重新登录；`403` 检查角色；`5xx` 检查数据库和外部依赖。
4. 不要通过清库或删除持久卷解决普通错误。

### 渠道显示已连接但无消息

1. 验证渠道最近心跳、Webhook 状态和投递日志。
2. 检查 Webhook 地址是否能从网关容器访问。
3. 检查签名密钥是否一致、渠道 ID 是否属于当前租户。
4. 触发安全的状态对账；不要反复解绑账号。

### WebSocket 不实时

1. 确认反向代理允许 Upgrade。
2. 检查短期票据是否过期以及客户端是否自动重连。
3. 断线期间通过 REST 游标补齐，不依赖丢失的内存事件。

### AI 变慢或失败

1. 查看模型响应状态、超时和限流。
2. 确认高优先级实时队列未被历史补齐占满。
3. 暂停历史补齐而不是暂停消息接收。
4. 原始消息应照常展示，待模型恢复后重试增强任务。

## 变更与事件处理

- 配置、密钥、数据库和网关升级都先备份并记录操作人。
- 重大故障先止损：暂停高风险发送、保留日志、不要破坏现场。
- 恢复后补做根因、影响租户、时间线、数据一致性和预防措施记录。

## 告警建议

- 健康检查连续 3 次失败。
- 5 分钟 API 5xx 比例超过 2%。
- Webhook 最老未处理任务超过 60 秒或死信新增。
- WhatsApp/Telegram 渠道离线超过 2 分钟。
- PostgreSQL 磁盘超过 75%、连接超过 80%。
- AI P95 超过目标或 `429` 持续出现。
- 备份任务失败或超过 24 小时未成功。