# ZIPFORCE Hub 应急响应预案（IR · Incident Response）

> 版本 1.0 · 2026-09-24 · 本文档 = 生产事故的唯一操作手册
> 位置：`zipforce-hub/incident-response-2026-09-24.md`（changelog /audit/ 在线可查）
> 原则：**先止血、再根因、后复盘**——不知道原因时先恢复服务，原因分析在服务恢复之后

---

## 一、联系链与角色

| 角色 | 谁 | 职责 |
|---|---|---|
| 值班（On-call） | 当前部署会话 | 第一响应：执行止血命令、确认影响范围 |
| 决策人 | 用户（老板） | 批准影响数据的操作（回滚 DB/删除数据/对外通知） |
| 服务器 | mars（本机生产）/ mercury（源库）/ venus | 见部署地图 `/audit/registry-architecture-2026-09-24.md` 第八章 |

**通知升级**：
- 服务不可用 > 5 分钟 → 通知用户
- 数据泄露疑似 → 立即通知用户
- 单租户投诉 → 30 分钟内响应

---

## 二、第一响应五步（任何事故都先做）

```bash
# 1. 确认现状（30 秒）
docker ps --format '{{.Names}} {{.Status}}' | grep -v Up     # 非运行的容器
curl -s -o /dev/null -w "%{http_code}" --resolve zipforce.zipforcehub.com:443:127.0.0.1 https://zipforce.zipforcehub.com/api/auth/registration-status
docker logs zipforce-saas-api-1 --since 5m 2>&1 | grep -iE "error|traceback|5[0-9][0-9]" | tail -20

# 2. 截取证据（改动前先拍快照）
docker logs zipforce-saas-api-1 --since 30m > /tmp/incident-$(date +%H%M).log 2>&1
docker exec zipforce-saas-db-1 pg_dump -U saas_admin -d saas_registry -Fc -f /tmp/incident-$(date +%H%M).dump

# 3. 判定场景（选下方对应预案）

# 4. 执行止血

# 5. 记录到 changelog + 长期档案
```

---

## 三、场景 A：服务不可用（API 5xx / 页面白屏）

### A1 容器挂了
```bash
docker compose ps                          # 看哪个挂了
docker compose restart api worker web      # 先重启
# 重启不行 → 回滚到版本锚点
cat VERSION                                 # 当前版本和回滚命令
docker tag zipforce-saas-api:v2026.09.24-registry-mcp zipforce-saas-api:latest
docker compose up -d api worker web
```

### A2 DB 连不上
```bash
docker exec zipforce-saas-db-1 pg_isready -U saas_admin -d saas_registry
# DB 本身挂了 → 检查磁盘/内存
df -h / && free -h
docker compose restart db
# 数据损坏 → 从备份恢复（版本锚点 dump 或每日备份）
ls -lt backups/*.dump | head -3            # 最新备份
docker exec -i zipforce-saas-db-1 pg_restore -U saas_admin -d saas_registry --clean backups/<最新>.dump
```

### A3 网关（Caddy）问题
```bash
docker logs zipforce-saas-caddy-1 --since 5m
docker compose restart caddy               # 记住 admin off, 只有 restart 没有 reload
```

### A4 源库（mercury）断流
```bash
ssh 222 "sudo -u postgres psql -d amazon_analytics -Atc 'SELECT max(purchase_date) FROM zipforce_amazon.zipforce_amazon_spapi_orders'"
# 源头断 → 出需求单给 mercury 管理员; SaaS 侧数据不动（只影响新鲜度）
python3 tools/four_layer_audit.py 2>&1 | grep FAIL   # 跑审计看影响面
```

---

## 四、场景 B：数据错误（图表不对/数字错了）

### B1 确认影响范围
```bash
# 跑四层审计（L1-L4 全检）
python3 tools/four_layer_audit.py 2>&1 | grep -E "FAIL|WARN"
# 跑图表值对账（81 图双视图）
python3 tools/chart_value_audit.py 2>&1 | grep FAIL
# 两表 diff
python3 tools/pipe_audit.py 2>&1 | tail -5
```

### B2 单表数据坏了（清洗层可重灌）
```bash
# cleaned 表 → 重跑清洗（从 raw 重建）
docker exec zipforce-saas-worker-1 python3 -c "from clean_audit import run; ..."
```

### B3 raw 数据错了（ingest 层）
```bash
# 重跑 ingest（幂等 UPSERT）
docker exec zipforce-saas-worker-1 python3 -c "
from sync_mercury import ingest_all
r = ingest_all(full_orders=True)
print(r)"
```

### B4 全库回滚（最后手段，需用户批准）
```bash
# 版本锚点回滚
cat VERSION    # 里面有回滚命令
pg_restore -d saas_registry --clean backups/saas_registry-v*.dump
```

---

## 五、场景 C：安全事件（泄露/入侵/凭证被盗）

### C1 API key / MCP key 泄露
```bash
# 立即撤销
docker exec zipforce-saas-db-1 psql -U saas_admin -d saas_registry -c \
  "UPDATE mcp_keys SET revoked_at=now() WHERE id=<ID>"
# 或全部撤销（核弹选项）
docker exec zipforce-saas-db-1 psql -U saas_admin -d saas_registry -c \
  "UPDATE mcp_keys SET revoked_at=now() WHERE revoked_at IS NULL"
# 通知受影响租户重新生成
```

### C2 源库凭证（LWA token / 代理凭证）泄露
```bash
# 采集凭证在 /collection/secrets/ — 泄露时联系 Amazon 卖家后台撤销授权
# 代理凭证在 config.PROXIES — 联系 Decodo 换密码
```

### C3 RLS 被绕过疑似（跨租户数据泄露）
```bash
# 立即隔离：暂停 API
docker compose stop api
# 查审计日志找异常访问
docker exec zipforce-saas-db-1 psql -U saas_admin -d saas_registry -Atc \
  "SELECT * FROM audit_log WHERE created_at > now()-interval '1 hour' ORDER BY id DESC LIMIT 50"
# 修复后重启
docker compose start api
```

### C4 恶意请求/暴力破解
```bash
# 限速已自动拦截(429)；如需手动封 IP:
# Caddy 层（需编辑 Caddyfile + restart）
# 查 Redis 限速键看攻击源
docker exec zipforce-saas-api-1 python3 -c "
import redis
r = redis.Redis.from_url('redis://redis:6379/0', decode_responses=True)
for k in sorted(r.keys('rl:*'))[-20:]: print(k, r.get(k))"
```

---

## 六、场景 D：定时任务 / 数据管道故障

```bash
# 每日 07:25 机器人报告（在哪看）
cat logs/cron-audit/latest.txt
# worker 任务日志
docker logs zipforce-saas-worker-1 --since 1h
# 手动补跑任何任务
curl -X POST "https://zipforce.zipforcehub.com/api/pipeline/run/<func_name>" -H "Cookie: <登录>"
# 或直接在 worker 容器执行
docker exec zipforce-saas-worker-1 python3 -c "from tasks import <func_name>; ..."
```

---

## 七、恢复验证清单（每次止血后必跑）

```bash
# 1. 容器全绿
docker ps --format '{{.Names}} {{.Status}}' | grep -c "Up"
# 2. API 探活
curl -s -o /dev/null -w "%{http_code}" https://zipforce.zipforcehub.com/api/auth/registration-status
# 3. 四层审计（FAIL ≤ 1 即恢复）
python3 tools/four_layer_audit.py 2>&1 | grep "^══"
# 4. pen_tests
python3 tools/pen_tests.py 2>&1 | tail -1
# 5. 前端探活
python3 tools/frontend_e2e.py 2>&1 | tail -3
```

---

## 八、事后复盘（每次 P1/P2 事故后 24h 内）

1. **时间线**：什么时候发现、什么时候止血、什么时候恢复
2. **根因**：五问法（为什么×5）到根因
3. **影响面**：哪些租户/品牌/页面/数据受影响
4. **行动项**：
   - 立即修复（当天）
   - 防复发（加审计项/加监控/改流程）
   - 写入 changelog + memory-longterm.md
5. **更新本文档**：如果发现预案缺失某个场景，补充

---

## 九、资产清单（快速定位）

| 资产 | 位置 | 恢复方式 |
|---|---|---|
| 版本锚点 | `saas/VERSION` 文件 | 里面有完整回滚命令 |
| 代码快照 | `saas/backups/code-*/` | tar 解压 |
| DB 备份 | `saas/backups/*.dump`（本机）+ `mercury:/opt/backups/saas/`（异地 14 天） | `pg_restore --clean` |
| 镜像 tag | `docker images \| grep zipforce-saas` | `docker tag <tag> latest` |
| crontab 清单 | `saas/host-crontab.txt` | `bash install-host-crontab.sh` |
| mercury 源库备份 | `mercury:/opt/backups/pg/` | 需求单走 mercury 管理员 |
| 审计日志 | DB `audit_log` 表 | 只追加不可改 |
| 四层审计结果 | DB `audit_results` 表 | 每日 06:35 + 手动 |
