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
@@ -475,6 +475,8 @@ im:{tenant_id}:...

 当前代码将 Redis 配置挂在 `store_config.redis` 下；不配置则不启用 Redis 群消息发号和唯一 key，群消息仍兼容旧的本机 `lastID + 1` 发号。

+群消息物理表按自然月拆分时，落库路由、跨月查询、幂等和迁移方案见：[IM-群消息按月分表改造方案](./IM-群消息按月分表改造方案.md)。
+
 配置示例：

 ```json
@@ -0,0 +1,555 @@
+# IM 群消息按月分表改造方案
+
+## 1. 背景与目标
+
+当前每个租户库使用单表 `im_group_messages` 保存全部群消息。随着群数量、消息量和保留时间增长，单表会出现索引膨胀、查询抖动、DDL 风险升高和归档困难等问题。
+
+本方案将群消息正文按自然月拆分为物理表：
+
+```text
+im_group_messages_202609
+im_group_messages_202610
+im_group_messages_202611
+```
+
+目标：
+
+1. 每个租户库独立分表，消息表不增加 `tenant_id`。
+2. Topic 的 `seqid` 继续由 Redis 原子递增，跨月不重置。
+3. Kafka 异步落库稳定路由到首次确定的月表。
+4. 客户端继续按 `topic + seq` 拉取，不感知月份。
+5. 支持跨月分页、补拉、指定消息、搜索、撤回、编辑和删除。
+6. 旧单表平滑迁移，不停服、不丢失、不重复。
+7. Redis 保留 24 小时热消息，MySQL 月表仍是最终数据源。
+
+## 2. 核心原则
+
+### 2.1 分表粒度
+
+- 一个租户库每月一张群消息表，不按单个群建表。
+- 表名固定为 `im_group_messages_YYYYMM`。
+- 月份统一使用 UTC，但最终写入月份由 Redis 全局 `active_month` 决定，避免多节点在月初产生交叠。
+- Redis Lua 一次性返回 `seqid + shard_month`；生产端把结果固化到 Kafka，重试、补偿不得重算。
+
+### 2.2 Seq 规则
+
+- `seqid` 在 Topic 内全生命周期单调递增，跨月不归零。
+- Redis `topic:last_seq` 是唯一发号源。
+- 月表只保存已分配的 Seq，不通过 `MAX(seqid)` 发号。
+- 客户端游标继续使用 `before/since/seq`。
+
+### 2.3 分层职责
+
+| 层级 | 职责 |
+| --- | --- |
+| Redis | 原子 Seq、全局活动月份、长期 Topic 月段路由、短期发送幂等、24 小时热消息、在线状态、实时推送 |
+| Kafka | 异步落库、削峰、重试、死信、消费幂等 |
+| MySQL 月表 | 群消息正文最终存储 |
+| MySQL 路由镜像 | 月表目录、Topic 月段路由持久化镜像；Redis 丢失时用于重建，不进入正常查询热路径 |
+| `im_dellog` | 用户视角删除范围，每张月表查询时继续过滤 |
+
+## 3. 表结构
+
+### 3.1 月表模板
+
+第一阶段保持当前字段兼容，降低 Store 层改造范围。
+
+```sql
+CREATE TABLE IF NOT EXISTS im_group_messages_202609 (
+  message_id BIGINT NOT NULL COMMENT 'Snowflake 全局消息 ID',
+  topic VARCHAR(64) NOT NULL COMMENT '群 Topic',
+  group_id BIGINT NOT NULL COMMENT '业务群 ID',
+  seqid BIGINT NOT NULL COMMENT 'Topic 内递增，跨月不重置',
+  from_user BIGINT NOT NULL,
+  client_msg_id VARCHAR(64) NULL,
+  msg_type VARCHAR(32) NOT NULL DEFAULT 'text',
+  status VARCHAR(32) NOT NULL DEFAULT 'normal',
+  content JSON NULL,
+  head JSON NULL,
+  mentioned_user_ids JSON NULL,
+  mention_all TINYINT(1) NOT NULL DEFAULT 0,
+  reply_seqid BIGINT NULL,
+  root_seqid BIGINT NULL,
+  file_count INT NOT NULL DEFAULT 0,
+  content_size INT NOT NULL DEFAULT 0,
+  has_risk TINYINT(1) NOT NULL DEFAULT 0,
+  audit_status VARCHAR(32) NOT NULL DEFAULT 'pass',
+  version INT NOT NULL DEFAULT 1,
+  recalled_at DATETIME(3) NULL,
+  recalled_by BIGINT NULL,
+  deleted_at DATETIME(3) NULL,
+  expires_at DATETIME(3) NULL,
+  created_at DATETIME(3) NOT NULL,
+  updated_at DATETIME(3) NOT NULL,
+  PRIMARY KEY (message_id),
+  UNIQUE KEY uk_topic_seq (topic, seqid),
+  UNIQUE KEY uk_topic_sender_client_mid (topic, from_user, client_msg_id),
+  KEY idx_group_seq (group_id, seqid),
+  KEY idx_topic_created (topic, created_at),
+  KEY idx_topic_from_seq (topic, from_user, seqid),
+  KEY idx_audit_created (audit_status, created_at),
+  KEY idx_expires (expires_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+```
+
+说明：
+
+1. `message_id` 使用 Snowflake 全局唯一 ID，作为月表物理主键和跨表引用 ID。
+2. 聊天协议定位、补拉和已读水位仍统一使用 `topic + seqid`，不向客户端暴露物理主键。
+3. 单表唯一索引不能覆盖跨月重试，跨月幂等由 Redis、消费日志和幂等表共同保证。
+4. 文件二进制仍在 OSS，月表仅保存消息和文件元数据。
+
+### 3.2 月表目录
+
+```sql
+CREATE TABLE IF NOT EXISTS im_group_message_shards (
+  shard_month CHAR(6) NOT NULL COMMENT 'UTC 月份 YYYYMM',
+  table_name VARCHAR(64) NOT NULL,
+  shard_start DATETIME(3) NOT NULL,
+  shard_end DATETIME(3) NOT NULL,
+  status VARCHAR(16) NOT NULL DEFAULT 'prepared'
+    COMMENT 'prepared/writable/sealing/sealed/archived',
+  row_count BIGINT NOT NULL DEFAULT 0,
+  min_created_at DATETIME(3) NULL,
+  max_created_at DATETIME(3) NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3)
+    ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (shard_month),
+  UNIQUE KEY uk_table_name (table_name)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+```
+
+表名只允许由服务端根据月份生成，并且必须存在于目录表，禁止使用请求参数直接拼接 SQL。
+
+### 3.3 Redis Topic 月段路由
+
+在线查询使用 Redis 路由，路由 Key 长期不过期：
+
+```text
+# 当前可写月份
+im:{tenant_id}:groupmsg:active_month
+  STRING = 202610
+
+# Topic 月份段，score 为该月首条 seq
+im:{tenant_id}:groupmsg:route:{topic}
+  ZSET: 202609 => 1
+        202610 => 10087
+
+# 月段完整范围，field 为 YYYYMM
+im:{tenant_id}:groupmsg:route_meta:{topic}
+  HASH: 202609 => min_seq=1,max_seq=10086,count=10086
+        202610 => min_seq=10087,max_seq=12000,count=1914
+```
+
+路由规则：
+
+1. `route` 和 `route_meta` 不设置 TTL，只在群物理删除或对应消息保留期结束后清理。
+2. 精确 Seq 定位使用 `ZREVRANGEBYSCORE route seq -inf LIMIT 0 1`，找到最大 `min_seq <= seq` 的月份，再校验 Hash 中的 `max_seq`。
+3. 倒序分页通过 `ZREVRANGE` 按月段倒序读取，正向补拉通过 `ZRANGE` 读取。
+4. 路由 Key 使用 Redis Cluster hash tag，保证 Lua 和 Pipeline 访问同一槽位。
+5. Redis 开启 AOF everysec、主从复制和持久化备份；同时保留 MySQL 镜像作为灾备重建来源。
+
+活动月份和 Seq 必须在同一个 Lua 脚本中读取/分配，两个 Key 使用相同的租户 hash tag：
+
+```lua
+local shard_month = redis.call('GET', KEYS[1])
+if not shard_month or shard_month < ARGV[1] then
+  redis.call('SET', KEYS[1], ARGV[1])
+  shard_month = ARGV[1]
+end
+
+local seq_id = redis.call('INCR', KEYS[2])
+return {seq_id, shard_month}
+```
+
+其中 `KEYS[1]` 是租户活动月份，`KEYS[2]` 是 Topic Seq，`ARGV[1]` 来自 Redis `TIME` 转换后的 UTC 月份。业务节点不得根据本机时间计算月份；首次写入可初始化活动月份，之后 Lua 只允许月份单向推进，旧节点不能回拨。
+
+### 3.4 MySQL 路由镜像
+
+```sql
+CREATE TABLE IF NOT EXISTS im_group_message_topic_shards (
+  topic VARCHAR(64) NOT NULL,
+  shard_month CHAR(6) NOT NULL,
+  min_seq BIGINT NOT NULL,
+  max_seq BIGINT NOT NULL,
+  message_count BIGINT NOT NULL DEFAULT 0,
+  min_created_at DATETIME(3) NOT NULL,
+  max_created_at DATETIME(3) NOT NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3)
+    ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (topic, shard_month),
+  KEY idx_topic_max_seq (topic, max_seq),
+  KEY idx_month_topic (shard_month, topic)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+```
+
+该表不参与正常消息查询，只用于 Kafka 事务持久化、Redis 路由重建、历史迁移、数据核对和归档。Redis 与镜像不一致时，以月表实际数据和 MySQL 镜像修复 Redis。
+
+路由一致性规则：
+
+1. Kafka 消费事务同时提交消息和 MySQL 路由镜像，保证最终数据与镜像一致。
+2. MySQL 提交成功后再更新 Redis `route/route_meta`；Redis 更新失败不回滚消息，进入路由修复重试队列。
+3. 查询发现 Redis 路由 Key 不存在时，从 MySQL 镜像加载该 Topic 全部有效月段并回填 Redis，然后重试查询。
+4. Shard Manager 启动时可按租户增量重建路由，并定时抽样核对 Redis、MySQL 镜像和月表实际 Seq 范围。
+5. Redis 路由不设置 TTL；只有群被物理删除，或消息保留策略确认清除对应月份后，才同步删除相应月段。
+
+### 3.5 跨月幂等表
+
+```sql
+CREATE TABLE IF NOT EXISTS im_group_message_dedup (
+  topic VARCHAR(64) NOT NULL,
+  from_user BIGINT NOT NULL,
+  client_msg_id VARCHAR(64) NOT NULL,
+  seqid BIGINT NOT NULL,
+  shard_month CHAR(6) NOT NULL,
+  message_id BIGINT NULL,
+  status VARCHAR(16) NOT NULL DEFAULT 'pending',
+  expires_at DATETIME(3) NOT NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3)
+    ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (topic, from_user, client_msg_id),
+  KEY idx_expires (expires_at),
+  KEY idx_topic_seq (topic, seqid)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
+```
+
+- Redis `SET NX` 是入口快速幂等。
+- Kafka 消费日志按 `event_id` 防止同一事件重复消费。
+- 该表防止月末发送、月初重试时同一 `client_msg_id` 落入两张表。
+- 建议保留 7 至 30 天后清理，不作为永久消息索引。
+
+## 4. 建表和月切换
+
+每个租户库运行统一 Shard Manager：
+
+1. 每天巡检上月、当月和未来两个月。
+2. 缺表时根据固定模板创建，成功后登记目录。
+3. 使用 Redis 分布式锁和 Redis `TIME` 判断月界，确认新月表可写后再原子更新 `active_month`。
+4. 当月设置为 `writable`，所有节点通过 Redis 读取同一个活动月份。
+5. 上月进入 `sealing`，建议继续接受 7 天延迟 Kafka 消息。
+6. 确认没有积压和死信后改为 `sealed`。
+7. 建表失败立即告警，不切换 `active_month`，禁止在业务写入事务中临时执行 DDL。
+
+月切换示例：
+
+```text
+2026-09-30 23:59:59 UTC seq=10086 -> im_group_messages_202609
+2026-10-01 00:00:00 UTC seq=10087 -> im_group_messages_202610
+```
+
+Kafka 事件必须固定路由信息：
+
+```json
+{
+  "topic": "grp_xxx",
+  "seq_id": 10087,
+  "created_at": "2026-10-01T00:00:00.123Z",
+  "shard_month": "202610",
+  "client_msg_id": "client_mid_xxx"
+}
+```
+
+## 5. 群消息落库
+
+### 5.1 生产端
+
+1. 校验群成员、禁言、群状态和内容策略。
+2. 使用 Redis 幂等 Key 抢占 `client_msg_id`。
+3. 使用 Redis Lua 原子获取 Topic 下一个 `seqid` 和全局 `active_month`。
+4. 生成服务端 UTC `created_at`，并把 Lua 返回的月份作为 `shard_month`。
+5. 把 `shard_month` 写入 Kafka；所有重试沿用原值。
+6. Kafka 生产成功后按现有策略向客户端返回 Seq。
+7. 写入 Redis 热消息并执行实时推送。
+
+### 5.2 Kafka 消费端
+
+消费端按 `tenant + shard_month` 分组批量写入：
+
+1. 校验月份格式和允许范围。
+2. 从目录确认目标表已存在。
+3. 开启事务。
+4. 插入或确认 `im_group_message_dedup`。
+5. 插入目标月表。
+6. 在同一事务中 UPSERT MySQL 路由镜像的最小/最大 Seq、时间和消息数。
+7. 更新消费幂等状态并提交事务。
+8. 提交成功后更新 Redis `route/route_meta`，并把 Redis 幂等状态改为 `done`。
+
+路由 UPSERT：
+
+```sql
+INSERT INTO im_group_message_topic_shards
+  (topic, shard_month, min_seq, max_seq, message_count,
+   min_created_at, max_created_at)
+VALUES (?, ?, ?, ?, 1, ?, ?)
+ON DUPLICATE KEY UPDATE
+  min_seq = LEAST(min_seq, VALUES(min_seq)),
+  max_seq = GREATEST(max_seq, VALUES(max_seq)),
+  message_count = message_count + 1,
+  min_created_at = LEAST(min_created_at, VALUES(min_created_at)),
+  max_created_at = GREATEST(max_created_at, VALUES(max_created_at));
+```
+
+### 5.3 异常处理
+
+- 目标月表不存在：消费失败、进入重试并高优告警。
+- `sealing` 月表：允许携带原 `shard_month` 的延迟事件写入。
+- `sealed` 月表：进入补偿队列，人工确认后临时开放或补写。
+- 重复 `event_id`：消费日志直接判定成功。
+- 重复 `client_msg_id`：返回原 `seqid/shard_month`，不新增消息。
+- 超过最大重试次数：进入死信队列，不能静默丢弃。
+- Redis 热缓存失败不回滚 MySQL，客户端按 Seq 回源补拉。
+- Redis 路由更新失败：进入独立修复重试；查询侧可从 MySQL 镜像重建，不影响已提交消息。
+
+## 6. 消息查询
+
+### 6.1 总流程
+
+```text
+客户端 Topic Seq 请求
+  -> ACL/成员身份校验
+  -> Redis 24 小时热消息
+  -> Redis 是否完整覆盖请求范围
+  -> Redis Topic 月段路由
+  -> 月表逐张查询
+  -> 按 seqid 合并、去重、排序、截断
+  -> 应用 im_dellog 用户视角过滤
+  -> 返回客户端
+```
+
+Redis 只有完整覆盖整页时才能直接返回；有缺口必须回源 MySQL。
+
+### 6.2 最新消息倒序分页
+
+请求 `topic=grp_xxx&before=10088&limit=50`：
+
+1. 从 Redis Topic 月段路由找出 `min_seq < before` 的月份，按月倒序。
+2. 先查最新候选月：
+
+```sql
+SELECT ...
+FROM im_group_messages_202610 AS m
+LEFT JOIN im_dellog AS d
+  ON d.topic = m.topic
+ AND m.seqid BETWEEN d.low AND d.hi - 1
+ AND d.deletedfor = ?
+WHERE m.topic = ?
+  AND m.seqid < ?
+  AND m.status != 'deleted'
+  AND d.deletedfor IS NULL
+ORDER BY m.seqid DESC
+LIMIT ?;
+```
+
+3. 数量不足时继续查前一个月。
+4. 服务层按 `seqid DESC` 合并并截取 `limit`。
+5. 下一页游标仍是本页最小 `seqid`，客户端不感知月份。
+
+禁止对所有历史表执行无上限 `UNION ALL`。
+
+### 6.3 Since 正向补拉
+
+1. 从 Redis Topic 月段路由查找 `max_seq > since_seq` 的月份。
+2. 按月升序执行 `seqid > since_seq ORDER BY seqid ASC LIMIT N`。
+3. 合并后按 Seq 升序返回。
+4. 达到上限后返回最后一条 Seq，客户端继续请求。
+
+### 6.4 指定消息
+
+撤回、回复预览、举报取证按 `topic + seqid` 定位：
+
+```text
+ZREVRANGEBYSCORE im:{tenant_id}:groupmsg:route:{topic} {seqid} -inf LIMIT 0 1
+HGET im:{tenant_id}:groupmsg:route_meta:{topic} {shard_month}
+```
+
+先找到最大 `min_seq <= seqid` 的月份，再校验该月段 `max_seq >= seqid`，随后执行 `WHERE topic=? AND seqid=? LIMIT 1`。Redis 路由 Key 缺失时读取 MySQL 镜像并回填 Redis；镜像也缺失时，仅降级扫描当前月和最近若干月并记录修复任务，不允许扫描全部历史表。
+
+### 6.5 上下文和范围
+
+查询目标消息前后各 20 条时：
+
+1. 定位目标所在月。
+2. 在本月分别查询目标前后消息。
+3. 任一方向不足时继续查询相邻月份。
+4. 合并、去重后按 Seq 正序返回。
+
+### 6.6 搜索和统计
+
+- 短期搜索必须带起止时间，最多覆盖 3 个月，逐月查询后归并。
+- 中长期通过 Kafka 建独立搜索索引；结果只返回 `topic + seqid`，服务端回源月表并重新校验 ACL。
+- Admin 统计使用按日/月汇总表，不实时扫描所有月表执行 `COUNT(*)`。
+
+## 7. 撤回、编辑和删除
+
+撤回、编辑流程：
+
+1. 根据 `topic + seqid` 定位目标月表。
+2. 在目标月表事务中 `SELECT ... FOR UPDATE`。
+3. 校验版本、权限和状态。
+4. 更新目标月表并写修订记录、业务事件。
+5. 提交后更新或删除 Redis 热消息。
+
+修订记录建议增加月份：
+
+```sql
+ALTER TABLE im_message_revisions
+  ADD COLUMN shard_month CHAR(6) NULL AFTER topic;
+```
+
+用户侧删除继续使用 `im_dellog` 的 Topic Seq 范围，每张月表查询都应用相同过滤。全局删除或合规处置先定位月表，再更新 `status/deleted_at/content/head`；OSS 附件仍走文件生命周期任务。
+
+## 8. Store 层设计
+
+所有动态表访问统一经过路由组件：
+
+```go
+type GroupMessageShardRouter interface {
+    WriteTable(createdAt time.Time, shardMonth string) (string, error)
+    CandidateTablesBySeq(topic string, seq int64) ([]string, error)
+    TablesBefore(topic string, before int64) ([]string, error)
+    TablesSince(topic string, since int64) ([]string, error)
+}
+```
+
+改造范围：
+
+- `TenantGroupMessageSave`：按事件 `shard_month` 写入。
+- `TenantGroupMessageGetOne`：路由后查询目标月。
+- `TenantGroupMessageGetAll`：逐月查询并归并。
+- `TenantGroupMessageGetByClientID`：先查 Redis/幂等表，再查询目标月。
+- `TenantGroupMessageRecall/Edit`：定位目标月后执行事务。
+- `TenantMessageSearch`：按时间选月，或转独立搜索。
+- Admin 内部消息查询、举报、收藏、回复和群文件引用同步改造。
+
+动态表名必须满足 `^im_group_messages_[0-9]{6}$` 且月份已登记。SQL 参数不能绑定表名，必须严格白名单。
+
+## 9. 旧表迁移
+
+原 `im_group_messages` 先保留，不删除。
+
+推荐步骤：
+
+1. 上线路由表、幂等表和 Shard Manager。
+2. 预建历史月份、当月和未来两个月表。
+3. 先发布支持“旧表 + 月表”双读的代码，写入仍走旧表。
+4. 记录切换水位 `cutover_seq/cutover_time`。
+5. 切换新消息只写月表，Kafka 开始携带 `shard_month`。
+6. 按 `created_at` 分批把旧表数据迁入对应月表。
+7. 每批使用 `INSERT IGNORE`，校验 `topic + seqid`、数量和内容哈希。
+8. 回填 MySQL Topic 月段路由镜像，并由重建任务写入 Redis 路由。
+9. 双读期间按 `topic + seqid` 去重。
+10. 全量校验通过后停止读取旧表。
+11. 旧表改名 `im_group_messages_legacy`，只读保留。
+12. 观察至少一个完整保留周期后再单独审批清理。
+
+不建议长期双写旧表和月表，否则两个写目标部分成功会扩大一致性问题。
+
+迁移批次要求：
+
+- 使用主键或 `created_at + id` 游标，禁止 OFFSET 深分页。
+- 单批 1,000 至 5,000 条，根据线上延迟调整。
+- 每批独立事务，记录开始/结束游标和成功/失败数。
+- 支持暂停、续跑和重复执行。
+
+## 10. 归档与保留
+
+状态流转：
+
+```text
+prepared -> writable -> sealing -> sealed -> archived
+```
+
+- `writable`：当月正常写。
+- `sealing`：月末后接受延迟消息，默认 7 天。
+- `sealed`：在线 MySQL 只读。
+- `archived`：转对象存储或低成本库，在线查询走归档服务。
+
+归档前确认 Kafka 无积压/死信、路由完整、消息数量和 Seq 范围一致，并确认举报、审计、收藏和群文件引用仍可定位。
+
+## 11. 监控与告警
+
+| 指标 | 说明 |
+| --- | --- |
+| `group_message_persist_total{month,status}` | 各月落库成功/失败 |
+| `group_message_persist_latency` | Kafka 到 MySQL 提交耗时 |
+| `group_message_shard_missing_total` | 目标月表不存在 |
+| `group_message_query_tables` | 单次请求扫描表数 |
+| `group_message_query_latency{source}` | Redis、单月、跨月耗时 |
+| `group_message_dedup_hit_total` | 幂等命中 |
+| `group_message_route_miss_total` | Redis 路由缺失 |
+| `group_message_route_rebuild_total{status}` | 从 MySQL 镜像重建 Redis 路由 |
+| `group_message_route_repair_backlog` | Redis 路由修复积压 |
+| `group_message_dead_letter_total` | 落库死信 |
+
+未来月表未创建、当月不可写、`active_month` 缺失、Kafka 延迟超限、单次扫描超过 3 张表、Redis 路由缺失或修复积压增长时必须告警。
+
+## 12. 验收测试
+
+1. 月末和月初消息落入正确表，Seq 连续。
+2. Kafka 次月才消费时仍写事件指定月份。
+3. 同一 `client_msg_id` 跨月重试只保留一条。
+4. 最新 50 条跨两个月时数量、顺序、游标正确。
+5. `since_seq` 跨月补拉无遗漏、无重复。
+6. `topic + seq` 可定位历史消息。
+7. 回复上下文可跨月读取。
+8. 撤回、编辑、举报、收藏、群文件引用可定位旧月。
+9. 用户删除范围跨月时过滤正确。
+10. Redis 热消息不完整时正确回源。
+11. 月表缺失时进入重试/死信并告警。
+12. 迁移双读无重复，迁移任务可暂停、续跑。
+13. 万人群高并发时 Seq 唯一且落库稳定。
+14. 非法月份和非法动态表名被拒绝。
+15. 多节点跨月并发时 Lua 返回同一活动月份，Seq 不重号且月段不交叠。
+16. 删除 Redis 路由后可从 MySQL 镜像自动重建，查询结果不缺失。
+
+## 13. 实施阶段
+
+### 第一阶段：基础设施
+
+- 建月表模板、目录、MySQL 路由镜像和跨月幂等表。
+- 实现 Shard Manager，预建未来两个月。
+- 建立长期不过期的 Redis Topic 月段路由和原子 `seqid + active_month` Lua。
+- Kafka 群消息事件增加 `shard_month`。
+
+### 第二阶段：写入切换
+
+- 消费者按月落库。
+- 完成幂等、重试、死信、MySQL 镜像和 Redis 路由更新。
+- Redis 热消息与实时推送保持不变。
+
+### 第三阶段：查询切换
+
+- 完成精确查询、倒序分页、Since 补拉和上下文跨月查询。
+- 改造撤回、编辑、删除、举报及 Admin 内部查询。
+- 增加跨月查询监控。
+
+### 第四阶段：历史迁移
+
+- 上线旧表/月表双读。
+- 回填历史消息与 MySQL 路由镜像，重建 Redis Topic 路由。
+- 校验后把旧表改为只读保留。
+
+### 第五阶段：搜索和归档
+
+- 消息搜索切换独立索引或限制时间范围。
+- 建立 `sealed/archived` 生命周期和历史恢复机制。
+
+## 14. 结论
+
+群消息按月分表不能只改写入表名，必须一起实现固定 `shard_month`、Redis Topic 月段路由、MySQL 路由镜像、跨月幂等、逐月游标查询、历史消息定位和旧表迁移。
+
+最终链路：
+
+```text
+发送：Redis Lua 原子分配 Seq 和 active_month -> Kafka 固定 shard_month -> MySQL 月表
+实时：Redis Pub/Sub/Stream -> WebSocket
+热读：Redis 24 小时消息
+冷读：Redis Topic 月段路由 -> MySQL 月表逐月查询
+容灾：MySQL 路由镜像 -> 重建长期 Redis 路由
+补偿：客户端按 Topic Seq 拉取
+```
+
+客户端协议无需增加月份字段，月表路由完全由服务端处理。
@@ -0,0 +1,15 @@
+-- 在每个租户业务库执行。用于并发安全地生成 im_users.account_no。
+CREATE TABLE IF NOT EXISTS im_user_account_sequences (
+    id TINYINT UNSIGNED NOT NULL,
+    next_value INT UNSIGNED NOT NULL,
+    updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3)
+        ON UPDATE CURRENT_TIMESTAMP(3),
+    PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
+
+-- 兼容已有用户数据，从当前最大账号编号继续递增，账号编号最小为 1000。
+INSERT INTO im_user_account_sequences (id, next_value)
+SELECT 1, GREATEST(COALESCE(MAX(account_no), 999), 999)
+FROM im_users
+ON DUPLICATE KEY UPDATE
+    next_value = GREATEST(next_value, VALUES(next_value));
@@ -1,3 +1,6 @@
+-- Legacy single-table baseline. New deployments must also run
+-- IM-群消息按月分表SQL.sql; this table remains only for migration-time dual reads.
+
 CREATE TABLE IF NOT EXISTS im_group_messages (
  id BIGINT NOT NULL AUTO_INCREMENT,
  topic VARCHAR(64) NOT NULL COMMENT '群 Topic，如 grp_xxx',
@@ -0,0 +1,107 @@
+-- IM group-message monthly sharding, baseline month: 2026-09 (UTC).
+-- Run in each tenant database. The application pre-creates subsequent months.
+
+CREATE TABLE IF NOT EXISTS im_group_message_shards (
+  shard_month CHAR(6) NOT NULL,
+  table_name VARCHAR(64) NOT NULL,
+  shard_start DATETIME(3) NOT NULL,
+  shard_end DATETIME(3) NOT NULL,
+  status VARCHAR(16) NOT NULL DEFAULT 'prepared',
+  row_count BIGINT NOT NULL DEFAULT 0,
+  min_created_at DATETIME(3) NULL,
+  max_created_at DATETIME(3) NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (shard_month),
+  UNIQUE KEY uk_im_group_message_shards_table (table_name),
+  KEY idx_im_group_message_shards_status (status, shard_month)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
+
+CREATE TABLE IF NOT EXISTS im_group_message_topic_shards (
+  topic VARCHAR(64) NOT NULL,
+  shard_month CHAR(6) NOT NULL,
+  min_seq BIGINT NOT NULL,
+  max_seq BIGINT NOT NULL,
+  message_count BIGINT NOT NULL DEFAULT 0,
+  min_created_at DATETIME(3) NOT NULL,
+  max_created_at DATETIME(3) NOT NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (topic, shard_month),
+  KEY idx_im_group_message_topic_shards_seq (topic, max_seq),
+  KEY idx_im_group_message_topic_shards_month (shard_month, topic)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
+
+CREATE TABLE IF NOT EXISTS im_group_message_dedup (
+  topic VARCHAR(64) NOT NULL,
+  from_user BIGINT NOT NULL,
+  client_msg_id VARCHAR(64) NOT NULL,
+  seqid BIGINT NOT NULL,
+  shard_month CHAR(6) NOT NULL,
+  message_id BIGINT NULL,
+  status VARCHAR(16) NOT NULL DEFAULT 'pending',
+  expires_at DATETIME(3) NOT NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (topic, from_user, client_msg_id),
+  KEY idx_im_group_message_dedup_expires (expires_at),
+  KEY idx_im_group_message_dedup_topic_seq (topic, seqid)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
+
+CREATE TABLE IF NOT EXISTS im_group_messages_202609 (
+  message_id BIGINT NOT NULL,
+  topic VARCHAR(64) NOT NULL,
+  group_id BIGINT NOT NULL,
+  seqid BIGINT NOT NULL,
+  from_user BIGINT NOT NULL,
+  client_msg_id VARCHAR(64) NULL,
+  msg_type VARCHAR(32) NOT NULL DEFAULT 'text',
+  status VARCHAR(32) NOT NULL DEFAULT 'normal',
+  content JSON NULL,
+  head JSON NULL,
+  mentioned_user_ids JSON NULL,
+  mention_all TINYINT(1) NOT NULL DEFAULT 0,
+  reply_seqid BIGINT NULL,
+  root_seqid BIGINT NULL,
+  file_count INT NOT NULL DEFAULT 0,
+  content_size INT NOT NULL DEFAULT 0,
+  has_risk TINYINT(1) NOT NULL DEFAULT 0,
+  audit_status VARCHAR(32) NOT NULL DEFAULT 'pass',
+  version INT NOT NULL DEFAULT 1,
+  recalled_at DATETIME(3) NULL,
+  recalled_by BIGINT NULL,
+  deleted_at DATETIME(3) NULL,
+  expires_at DATETIME(3) NULL,
+  created_at DATETIME(3) NOT NULL,
+  updated_at DATETIME(3) NOT NULL,
+  PRIMARY KEY (message_id),
+  UNIQUE KEY uk_202609_group_seq (group_id, seqid),
+  UNIQUE KEY uk_202609_topic_seq (topic, seqid),
+  UNIQUE KEY uk_202609_sender_client (topic, from_user, client_msg_id),
+  KEY idx_202609_group_status_seq (group_id, status, seqid),
+  KEY idx_202609_topic_created (topic, created_at),
+  KEY idx_202609_topic_from_seq (topic, from_user, seqid),
+  KEY idx_202609_audit_created (audit_status, created_at),
+  KEY idx_202609_expires (expires_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci;
+
+CREATE TABLE IF NOT EXISTS im_group_messages_202608 LIKE im_group_messages_202609;
+CREATE TABLE IF NOT EXISTS im_group_messages_202610 LIKE im_group_messages_202609;
+CREATE TABLE IF NOT EXISTS im_group_messages_202611 LIKE im_group_messages_202609;
+
+INSERT INTO im_group_message_shards
+  (shard_month,table_name,shard_start,shard_end,status)
+VALUES
+  ('202608','im_group_messages_202608','2026-08-01 00:00:00.000','2026-09-01 00:00:00.000','sealing'),
+  ('202609','im_group_messages_202609','2026-09-01 00:00:00.000','2026-10-01 00:00:00.000','writable'),
+  ('202610','im_group_messages_202610','2026-10-01 00:00:00.000','2026-11-01 00:00:00.000','prepared'),
+  ('202611','im_group_messages_202611','2026-11-01 00:00:00.000','2026-12-01 00:00:00.000','prepared')
+ON DUPLICATE KEY UPDATE
+  table_name=VALUES(table_name),
+  shard_start=VALUES(shard_start),
+  shard_end=VALUES(shard_end),
+  status=IF(status IN ('sealed','archived'),status,VALUES(status));
+
+-- Historical migration is deliberately separate from schema deployment.
+-- Backfill im_group_messages into the matching month table in bounded batches,
+-- then populate im_group_message_topic_shards before removing legacy reads.
@@ -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 和真实音视频媒体质量不属于本轮本地验收范围。