feat: shard group messages by month

2026-09-15 23:53:51 +08:00
parent b7c2536527
commit 139681fadb
25 changed files with 1718 additions and 247 deletions
@@ -0,0 +1,55 @@
+# IM 群消息按月分表本地验收报告
+
+## 验收环境
+
+- 时间：2026-09-15
+- IM Server：`http://127.0.0.1:6060`
+- WebSocket：`ws://127.0.0.1:6060/v0/channels`
+- MySQL：`127.0.0.1:3306`，租户库 `tinode`
+- Redis：`127.0.0.1:6379`
+- Kafka：`127.0.0.1:9092`
+
+## 验收结果
+
+| 项目 | 结果 | 说明 |
+| --- | --- | --- |
+| 编译、定向单测、Go Vet | 通过 | MySQL、Store、Server 本次变更相关用例全部通过 |
+| WebSocket 协议审计 | 通过 | 29/29，覆盖注册、登录、P2P、群聊、文件、回执、通话与异常鉴权 |
+| HTTP 接口审计 | 通过 | 98/98，未发现非预期失败或非预期 404 |
+| Kafka 群消息异步落库 | 通过 | 消费成功，消费组 LAG 为 0 |
+| 群消息分月写入 | 通过 | 新消息写入 `im_group_messages_202609`，未写入旧表 `im_group_messages` |
+| Kafka 重放幂等 | 通过 | 同一消息使用新事件 ID 重放后仍只有一行，路由计数不重复增加 |
+| Redis Seq | 通过 | 群 Topic Seq 原子增长，键 TTL 为 `-1` |
+| Redis 月份路由 | 通过 | 路由和元数据完整，键 TTL 为 `-1` |
+| 服务重启后历史拉取 | 通过 | 清除进程内 Topic 后，客户端可从分表恢复历史消息 |
+| 跨月合并查询 | 通过 | 构造 202608、202609 两个月份数据后，一次订阅正确返回两个分表的消息 |
+| 并发注册与群消息冒烟 | 通过 | 3 组并发、每组 29/29；账号编号无重复，群消息全部落入月表 |
+| Manager 内部接口 | 通过 | 56/56，覆盖列表、详情、分页、筛选、用户创建及回读 |
+| Manager HMAC 安全 | 通过 | 未签名、错签名、过期签名均返回 401，重复 Nonce 第二次返回 401 |
+
+## 测试中修复
+
+1. 注册写入未生成 `im_users.account_no`，第二个新用户会命中唯一键冲突。现改为租户库单行序列表原子分配。
+2. Kafka 群消息生产前未分配持久化 `message_id`，消费者会判定消息格式不完整。现由生产端生成并随事件固定传递。
+3. HTTP 审计工具过早执行退出登录，导致后续接口误报 401。现将退出登录移到整轮审计末尾。
+4. WebSocket 审计工具并发运行时可能生成相同手机号。现将进程 ID 纳入测试数据后缀。
+5. 个人资料刷新错误地向订阅表写入不存在的 `public` 字段。现改为清理好友订阅缓存并在下次读取时重新投影。
+6. `Uid` 零值序列化为空字符串后无法反序列化，导致群配置缓存持续回源。现已补齐零值 JSON 往返支持及单测。
+7. Manager 的看板和群消息查询仍只统计历史总表。现已按分片元数据合并月表与未迁移历史数据。
+8. 群消息历史表与月表 collation 不一致，`UNION` 查询返回 500。现已在历史分支显式统一 collation。
+9. Manager 群消息详情、文件详情和审计日志仍使用旧表或旧字段口径。现已支持月表详情、19 位数字文件 ID，并完成审计字段映射。
+10. Manager 群列表混入 `p2p` 和 `slf` Topic。现已在数据源层限定仅返回 `grp` Topic。
+11. Manager 内部查询输出的用户相关 ID 已统一为数据库 `BIGINT/int64`，不再转换为 `usr...`。
+
+## Manager 内部接口验收
+
+- 基础查询：用户、群组、私聊消息、群消息、文件、登录日志、审计、实名、举报、反馈、配置、工作台、组织架构和看板均返回 200。
+- 群治理查询：群详情、成员、入群申请、邀请、公告、禁言、管理日志和群文件均通过。
+- 运维查询：业务 Outbox、群 Outbox、Kafka 死信列表及详情均通过。
+- 写入冒烟：`POST /internal/admin-query/tenants/default/users` 创建成功，返回数字型 `user_id`，随后详情回读成功。
+- 协议口径：`user_id`、`owner_id`、`from_user_id`、`file_id` 和 `seq_id` 均按 JSON number 返回；群列表仅包含 `grp` Topic。
+- 安全边界：HMAC 签名覆盖 GET/POST，`X-Nonce` 为一次性值，防重放状态由 Redis 保持。
+
+## 结论
+
+本次群消息按月分表相关的写入、读取、重启恢复、跨月查询、Kafka 幂等、Redis 路由及并发链路均已通过本地验收；Manager 内部接口 56/56 及 HMAC 安全用例也已全部通过，可以进入测试环境验证。外部 OSS、内容安全、Push 和真实音视频媒体质量不属于本轮本地验收范围。