docs: add outbox governance summary
This commit is contained in:
zhx
parent
0aef70ecd7
commit
e1a5457ee2
308
docs/Outbox统一治理说明.md
Normal file
308
docs/Outbox统一治理说明.md
Normal file
@ -0,0 +1,308 @@
|
||||
# Outbox 统一治理说明
|
||||
|
||||
更新时间：2026-06-01
|
||||
|
||||
## 背景
|
||||
|
||||
生产 MySQL CPU 打满的直接触发点是多个 worker 高频轮询 outbox 表，尤其是 `wallet_outbox` 数据量已经到百万级后，部分查询没有完整匹配索引、带 `OR` 分支、缺少 `app_code` 过滤或由下游服务直扫 owner 表，导致 MySQL 需要持续扫描大量历史 outbox 行。
|
||||
|
||||
这次治理目标是：
|
||||
|
||||
- owner service 只允许自己扫描自己的 outbox，并发布 MQ。
|
||||
- 下游 projection 不再直接扫描 owner outbox。
|
||||
- 所有 outbox claim 查询必须带 `app_code + status/event_type + retry/lock + created_at` 匹配索引。
|
||||
- 所有 `OR` claim 分支拆成独立查询。
|
||||
- `delivered/done` 历史 outbox 建立归档机制。
|
||||
|
||||
## 修改前
|
||||
|
||||
### 运行方式
|
||||
|
||||
- `wallet-service` 扫 `wallet_outbox` 发布 `hyapp_wallet_outbox` MQ。
|
||||
- `room-service` 扫 `room_outbox` 发布 `hyapp_room_outbox` MQ。
|
||||
- `activity-service`、`game-service`、`user-service` 也各自有 outbox worker。
|
||||
- `notice-service` 仍保留直扫 `wallet_outbox`、`room_outbox` 的历史 worker 能力。
|
||||
- `wallet-service` 内部的礼物墙和 badge projection worker 也在轮询扫描 `wallet_outbox`。
|
||||
- 部分 claim SQL 把 `pending/retryable/locked expired` 写在同一个 `OR` 条件里。
|
||||
- 部分 outbox 索引缺少 `app_code`、`next_retry_at_ms`、`lock_until_ms/locked_until_ms`、`event_id` 这样的匹配列。
|
||||
- `game_outbox`、`user_outbox` 缺少完整的 worker lock/retry 字段。
|
||||
- 历史 `delivered/done` 数据没有统一归档脚本。
|
||||
|
||||
### 主要风险
|
||||
|
||||
- outbox 表越大，高频轮询越容易退化成大范围扫描。
|
||||
- 下游服务直接读 owner outbox，会把 owner 表变成跨服务共享查询热点。
|
||||
- `OR` 查询很容易让优化器放弃最优索引路径。
|
||||
- delivered 历史数据留在热表中，会持续抬高索引体积和扫描成本。
|
||||
- projection、通知、MQ 发布混用 outbox 状态，后续排障边界不清晰。
|
||||
|
||||
## 修改后
|
||||
|
||||
### 运行方式
|
||||
|
||||
- owner service 继续负责自己的 outbox claim 和 MQ 发布：
|
||||
- `wallet-service` 发布 `hyapp_wallet_outbox`
|
||||
- `room-service` 发布 `hyapp_room_outbox`
|
||||
- `activity-service` 发布 activity / broadcast 相关 MQ
|
||||
- `game-service` 发布 game 相关 MQ
|
||||
- `user-service` 发布 `hyapp_user_outbox`
|
||||
- `notice-service` 不再启动直扫 `wallet_outbox` / `room_outbox` 的 worker，改为消费 MQ。
|
||||
- `wallet-service` 内部礼物墙和 badge projection 不再轮询扫描 `wallet_outbox`，改为消费 `hyapp_wallet_outbox` MQ。
|
||||
- claim 查询拆成多段：
|
||||
- `pending`
|
||||
- `retryable`
|
||||
- `delivering/running expired lock`
|
||||
- claim 查询全部显式带 `app_code`，并匹配对应索引。
|
||||
- delivered/done 历史 outbox 通过归档脚本搬到 archive 表。
|
||||
|
||||
## 修复掉的问题
|
||||
|
||||
### 1. 下游直扫 owner outbox
|
||||
|
||||
之前：
|
||||
|
||||
- `notice-service` 可以直接扫描 `wallet_outbox`、`room_outbox`。
|
||||
- `wallet-service` 内部 projection worker 轮询扫描 `wallet_outbox` 做礼物墙和 badge 投影。
|
||||
|
||||
现在：
|
||||
|
||||
- `notice-service` runtime 配置禁止直扫 wallet/room outbox，只消费 MQ。
|
||||
- `wallet-service` 的礼物墙和 badge projection 改为消费 `hyapp_wallet_outbox` MQ。
|
||||
- 生产验证中，`wallet_projection_events / idx_wallet_outbox_event_created / idx_wallet_outbox_asset_event_created` 相关直扫进程数为 `0`。
|
||||
|
||||
实现位置：
|
||||
|
||||
- `services/notice-service/internal/config/config.go`
|
||||
- `services/notice-service/internal/app/app.go`
|
||||
- `services/notice-service/internal/modules/walletnotice/service.go`
|
||||
- `services/notice-service/internal/modules/walletnotice/mysql_repository.go`
|
||||
- `services/wallet-service/internal/app/app.go`
|
||||
- `services/wallet-service/internal/service/wallet/service.go`
|
||||
- `services/wallet-service/internal/storage/mysql/gift_wall_projection.go`
|
||||
- `services/wallet-service/internal/storage/mysql/badge_projection_relay.go`
|
||||
|
||||
### 2. claim 查询中 `OR` 导致索引不可控
|
||||
|
||||
之前：
|
||||
|
||||
- 多个 outbox claim SQL 用一个查询覆盖 pending、retryable、锁过期重试。
|
||||
- SQL 里有 `OR` 分支，优化器在大表上不稳定，容易扫描过多行。
|
||||
|
||||
现在：
|
||||
|
||||
- claim 查询按状态拆成独立分支。
|
||||
- 每个分支只走自己的索引条件。
|
||||
- 必要位置使用 `FORCE INDEX` 固定索引路径。
|
||||
|
||||
实现位置：
|
||||
|
||||
- `services/wallet-service/internal/storage/mysql/repository.go`
|
||||
- `services/room-service/internal/storage/mysql/repository.go`
|
||||
- `services/activity-service/internal/storage/mysql/broadcast_repository.go`
|
||||
- `services/game-service/internal/storage/mysql/repository.go`
|
||||
- `services/user-service/internal/storage/mysql/user_outbox.go`
|
||||
|
||||
### 3. 缺少 app_code 和匹配索引
|
||||
|
||||
之前：
|
||||
|
||||
- 部分 claim 查询没有完整 `app_code + status + retry/lock + created_at` 索引。
|
||||
- 部分索引没有 `event_id` 尾列，排序和稳定分页不够完整。
|
||||
|
||||
现在：
|
||||
|
||||
- wallet、room、activity、game、user、notice 相关 outbox 都补了 claim/retention 索引。
|
||||
- 生产库已验证目标索引存在，关键 `EXPLAIN` 都命中指定索引。
|
||||
|
||||
关键索引形态：
|
||||
|
||||
```sql
|
||||
app_code, status, next_retry_at_ms, created_at_ms, event_id
|
||||
app_code, status, lock_until_ms, created_at_ms, event_id
|
||||
app_code, status, updated_at_ms, event_id
|
||||
```
|
||||
|
||||
部分表字段名不同：
|
||||
|
||||
- `im_broadcast_outbox` 使用 `locked_until_ms`
|
||||
- `notice_delivery_events` 使用 `source_name, app_code, channel, status, next_retry_at_ms/lock_until_ms, updated_at_ms`
|
||||
|
||||
### 4. game/user outbox 缺少标准锁字段
|
||||
|
||||
之前：
|
||||
|
||||
- `game_outbox`、`user_outbox` 没有完整的 `worker_id`、`lock_until_ms`、`retry_count`、`next_retry_at_ms`、`last_error` 字段。
|
||||
- worker 失败和过期接管能力不统一。
|
||||
|
||||
现在：
|
||||
|
||||
- 两张表都补齐标准 worker claim 字段。
|
||||
- claim 逻辑统一为 pending/retryable/running expired 三段。
|
||||
|
||||
实现位置：
|
||||
|
||||
- `services/game-service/internal/storage/mysql/repository.go`
|
||||
- `services/user-service/internal/storage/mysql/user_outbox.go`
|
||||
- `services/game-service/internal/storage/mysql/repository.go` 的 schema/migrate 逻辑
|
||||
- `services/user-service/deploy/mysql/initdb/001_user_service.sql`
|
||||
|
||||
### 5. delivered/done 热表历史数据无归档
|
||||
|
||||
之前：
|
||||
|
||||
- delivered/done 历史 outbox 一直留在业务热表。
|
||||
- 表越大，索引越大，后续即使查询优化了也会逐步增加维护成本。
|
||||
|
||||
现在：
|
||||
|
||||
- 新增统一归档脚本：
|
||||
|
||||
`scripts/mysql/archive_delivered_outbox.sql`
|
||||
|
||||
- 归档目标是同库 archive 表：
|
||||
- `hyapp_wallet.wallet_outbox_archive`
|
||||
- `hyapp_room.room_outbox_archive`
|
||||
- `hyapp_activity.activity_outbox_archive`
|
||||
- `hyapp_activity.im_broadcast_outbox_archive`
|
||||
- `hyapp_game.game_outbox_archive`
|
||||
- `hyapp_game.game_level_event_outbox_archive`
|
||||
- `hyapp_user.user_outbox_archive`
|
||||
- `hyapp_notice.notice_delivery_events_archive`
|
||||
|
||||
## 归档方式
|
||||
|
||||
归档脚本逻辑：
|
||||
|
||||
1. 默认归档 30 天以前的数据：
|
||||
|
||||
```sql
|
||||
SET @outbox_archive_cutoff_ms := IFNULL(
|
||||
@outbox_archive_cutoff_ms,
|
||||
UNIX_TIMESTAMP(DATE_SUB(UTC_TIMESTAMP(3), INTERVAL 30 DAY)) * 1000
|
||||
);
|
||||
```
|
||||
|
||||
2. 每张表先创建同结构 archive 表：
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS hyapp_wallet.wallet_outbox_archive LIKE hyapp_wallet.wallet_outbox;
|
||||
```
|
||||
|
||||
3. 先 `INSERT IGNORE` 到 archive 表：
|
||||
|
||||
```sql
|
||||
INSERT IGNORE INTO hyapp_wallet.wallet_outbox_archive
|
||||
SELECT * FROM hyapp_wallet.wallet_outbox
|
||||
WHERE status IN ('delivered', 'done') AND updated_at_ms < @outbox_archive_cutoff_ms
|
||||
ORDER BY updated_at_ms ASC
|
||||
LIMIT 10000;
|
||||
```
|
||||
|
||||
4. 确认 archive 表存在对应记录后，再删除源表：
|
||||
|
||||
```sql
|
||||
DELETE FROM hyapp_wallet.wallet_outbox
|
||||
WHERE status IN ('delivered', 'done') AND updated_at_ms < @outbox_archive_cutoff_ms
|
||||
AND EXISTS (
|
||||
SELECT 1 FROM hyapp_wallet.wallet_outbox_archive a
|
||||
WHERE a.app_code = wallet_outbox.app_code AND a.event_id = wallet_outbox.event_id
|
||||
)
|
||||
ORDER BY updated_at_ms ASC
|
||||
LIMIT 10000;
|
||||
```
|
||||
|
||||
每张表每次最多处理 `10000` 行，避免一次归档造成长事务和复制压力。
|
||||
|
||||
生产执行结果：
|
||||
|
||||
- 脚本已执行。
|
||||
- 本次 30 天前 `delivered/done` 候选行为 `0`。
|
||||
- archive 表已通过脚本创建。
|
||||
|
||||
## 本次提交
|
||||
|
||||
- `60b7277 fix: govern outbox polling and archiving`
|
||||
- `bd0ed78 fix: add game outbox retention index`
|
||||
- `0aef70e fix: consume wallet projections from mq`
|
||||
|
||||
生产部署：
|
||||
|
||||
- `wallet-service`: `main-0aef70e-outbox-governance`
|
||||
- `room-service/activity-service/game-service/user-service/notice-service`: `main-bd0ed78-outbox-governance`
|
||||
|
||||
## 当前方案的优点
|
||||
|
||||
- 明确服务边界：owner outbox 只由 owner service 扫描和发布 MQ。
|
||||
- 降低 MySQL CPU 风险：下游 projection 不再对 owner 大表做高频轮询。
|
||||
- 查询路径稳定：claim SQL 拆分后，索引选择更可控。
|
||||
- 支持多实例并发：继续使用 lock 字段和 `FOR UPDATE SKIP LOCKED`。
|
||||
- 支持失败重试：通过 `retryable`、`next_retry_at_ms`、`lock_until_ms` 做指数退避和过期接管。
|
||||
- 历史数据可控：delivered/done 可以按批归档，热表不会无限增长。
|
||||
- 保留幂等语义：下游消费通过各自投影表或 delivery 表做去重，不依赖 MQ exactly-once。
|
||||
|
||||
## 当前方案的缺点
|
||||
|
||||
- MQ 成为关键依赖：MQ 故障时，下游 projection 会延迟。
|
||||
- 归档现在是脚本，不是定时任务；需要接入 cron 或运维调度。
|
||||
- 仍保留部分离线/测试用直扫方法，虽然 runtime 不启动，但后续要避免误开配置。
|
||||
- range 查询因为 `next_retry_at_ms <= now` 或 `lock_until_ms <= now`，`EXPLAIN` 里仍可能出现 `Using filesort`；目前扫描行数已被前缀索引压住，但极端积压下仍要关注。
|
||||
- MQ message 只覆盖被成功发布后的事件；如果历史 projection 已有缺口，需要单独跑一次离线修复或重放。
|
||||
- archive 表目前与源表同库同实例，能降低热表成本，但不能降低整个 MySQL 实例总存储压力。
|
||||
|
||||
## 还需要补足
|
||||
|
||||
### 1. 固化归档调度
|
||||
|
||||
建议把 `scripts/mysql/archive_delivered_outbox.sql` 接入定时任务：
|
||||
|
||||
- 每天或每小时执行一次。
|
||||
- 每次每表限制 `10000` 行。
|
||||
- 归档窗口默认 30 天，可通过 `@outbox_archive_cutoff_ms` 覆盖。
|
||||
- 执行前后记录每张表归档行数。
|
||||
|
||||
### 2. 增加 outbox 指标和告警
|
||||
|
||||
建议增加以下指标：
|
||||
|
||||
- 每张 outbox 各状态数量：`pending/retryable/delivering/running/delivered/dead`
|
||||
- 最老 pending 时间
|
||||
- retryable 积压数量
|
||||
- dead 数量
|
||||
- MQ 发布失败数
|
||||
- MQ 消费失败数
|
||||
- projection duplicate / skipped / failed 数量
|
||||
|
||||
### 3. 增加配置保护
|
||||
|
||||
现在 notice 已经禁止 runtime 直扫 wallet/room outbox。后续建议继续收紧：
|
||||
|
||||
- 对所有下游服务保留的 legacy direct scan worker 增加启动保护。
|
||||
- 生产配置中直接删除或禁用直扫配置。
|
||||
- CI 增加 SQL lint，检查 outbox claim 是否缺 `app_code` 或含 `OR`。
|
||||
|
||||
### 4. 历史 projection 缺口修复
|
||||
|
||||
对于已经 `delivered` 但下游 projection 没处理到的历史事件，建议单独做一次离线 backfill：
|
||||
|
||||
- 从 owner outbox 按时间窗口导出缺口事件。
|
||||
- 写入对应 projection/delivery 幂等表。
|
||||
- 或重新投递 MQ，但要控制速率。
|
||||
|
||||
### 5. 更彻底的数据生命周期治理
|
||||
|
||||
中长期可以考虑：
|
||||
|
||||
- outbox 热表只保留未完成和近期完成数据。
|
||||
- delivered/done 进入 archive 库或对象存储，而不是同库 archive 表。
|
||||
- 按 `created_at_ms` 或 `updated_at_ms` 做分区表，归档时按分区迁移或 drop partition。
|
||||
- 大流量 outbox 拆成 pending 表和 history 表，避免热冷数据混在同一张表。
|
||||
|
||||
## 最终状态
|
||||
|
||||
当前生产已验证：
|
||||
|
||||
- 目标服务均健康。
|
||||
- outbox claim 索引已存在且 `EXPLAIN` 命中指定索引。
|
||||
- notice 不再直扫 wallet/room outbox。
|
||||
- wallet 内部 projection 不再轮询扫描 `wallet_outbox`。
|
||||
- MySQL processlist 中 wallet projection 相关 outbox 直扫检查结果为 `0`。
|
||||
Loading…
x
Reference in New Issue
Block a user