im_server/docs/IM-Kafka接入范围识别.md

IM Kafka 接入范围识别

日期：2026-08-26
依据：IM 前后端逐图对接协议
目标：从前后端对接文档逐章识别适合接入 Kafka 的链路，明确 Kafka 与 WebSocket、Redis、MySQL、OSS 的边界。

1. 总体边界

Kafka 主要用于跨系统异步事件、削峰落库、可靠重试、失败补偿、后台操作通知 C 端和审计流水；不替代 WebSocket 的在线实时连接，不替代 Redis 的短状态和热读缓存，也不替代 MySQL 的最终状态。

类型	建议承载	说明
在线实时消息投递	Redis Pub/Sub/Stream + WebSocket	低延迟 fanout，节点收到后直接写 WS。
异步落库、重试、补偿	Kafka	适合消息持久化、通知、Push、审核、审计等可重放任务。
短状态、限流、验证码、在线状态	Redis	TTL 明确，不需要 Kafka。
最终业务状态	MySQL	Kafka 消费成功后写入或更新最终状态。
文件对象存储	OSS	Kafka 只处理文件元数据、安全检测和生命周期事件。

2. 推荐 Topic

Topic	用途	典型生产方	典型消费方
im.message.persist	私聊、群聊消息异步落库	IM WS 节点	消息持久化消费者
im.message.push	离线 Push 提醒	消息落库消费者、业务事件生产方	极光/厂商 Push 消费者
im.business.event	好友、群、会议、工作台等 C 端业务事件	IM HTTP、Admin 后台	IM 节点事件投递消费者
im.group.admin.event	Admin 后台群操作投递到 C 端	Admin 后台	IM 节点 WS 投递消费者
im.cache.invalidate	跨节点缓存失效	业务写接口、后台配置	IM 节点缓存消费者
im.file.security	文件内容安全和恶意文件检测	上传完成链路	阿里云安全检测消费者
im.file.lifecycle	孤立文件回收、引用绑定、合规删除	文件服务、业务写接口	文件生命周期消费者
im.audit.event	审计日志	所有敏感写链路	审计消费者
im.workbench.event	工作台模块红点、会议、日报、月报、信箱事件	工作台业务服务、Admin 后台	IM WS 投递、系统通知消费者
im.dead.letter	失败事件归档	各消费者	运维补偿任务

3. 幂等与重试

Kafka 消息统一携带 event_id、trace_id、tenant_code、biz_type、biz_id、action、version、occurred_at 和 payload。消费端按 event_id + consumer_group 做幂等记录，业务表也必须保留唯一键兜底。

消息发送链路使用 x-im-client-mid 或 HTTP Idempotency-Key 作为业务幂等来源；Kafka 只负责可靠投递，不能作为唯一幂等判断。消费者失败按指数退避重试，超过上限写 im.dead.letter 或失败表，由后台补偿。

4. 逐章识别

章节	适合 Kafka 的范围	不建议 Kafka 的范围
0. 公共对接约定	产品业务事件 outbox 可改为 Kafka 投递；消息异步落库、系统通知、离线 Push、跨节点缓存失效使用 Kafka；x-im-client-mid 幂等结果可作为生产 Kafka 前置校验。	WebSocket 建连、hi/login/sub/get/note 本身不走 Kafka；在线状态继续 Redis。
1. 账号注册、登录与身份安全	企业注册申请、企业入口反馈、实名提交、密码重置成功、账号封禁/解封、管理员重置密码、审核结果通知、审计日志可走 Kafka。营业执照和反馈截图上传完成后投 im.file.security。	登录鉴权、验证码校验、Action Token、限流不走 Kafka；这些必须同步返回或走 Redis。
2. 消息首页、全局导航与系统通知	系统通知创建、已读异步统计、入口红点变更、离线 Push 提醒、消息摘要更新可走 Kafka。	首页查询、会话列表拉取、客户端断线重连流程不走 Kafka。
3. 单聊会话、会话建立与消息状态	私聊消息异步落库、好友申请/通过/拒绝/删除事件、P2P 订阅建立后的通知、媒体消息文件绑定事件、离线 Push 可走 Kafka。	在线 P2P 实时投递主链路不建议 Kafka；关系判断和发送权限校验必须同步完成。
4. 消息输入、媒体内容与消息操作	@提醒 Push、消息撤回/编辑事件、收藏批量创建、转发任务、forward bundle 生成、消息搜索索引更新、附件 ACL 绑定可走 Kafka。	输入框、草稿、录音状态、上传进度和客户端 pending 队列不走 Kafka。
5. 通讯录、好友关系与黑名单	好友申请事件、好友关系变更、黑名单变更、二维码使用审计、资料快照更新、搜索索引更新、系统通知生成可走 Kafka。	好友列表查询、用户搜索同步结果、二维码解析鉴权不走 Kafka。
6. 群聊创建、资料维护与成员治理	群创建、成员加入/退出、邀请/审批、公告更新、资料更新、角色变更、禁言、群主转让、解散、群文件登记/删除、Admin 后台群操作投递到 C 端都适合 Kafka。Admin 后台写库后生产 im.group.admin.event，IM 节点消费后用 WS 下发给在线客户端。	群内在线消息 fanout 主链路继续 Redis + WS；群成员权限校验、成员数上限校验必须同步事务完成。
7. 文件下载、收藏管理与聊天记录检索	文件安全检测、恶意文件扫描、文件生命周期、收藏快照异步补全、收藏转发、搜索索引更新、合规删除事件可走 Kafka。文件下载本身不走 Kafka。	OSS 上传/下载字节流、Range 续传、下载进度不走 Kafka；这些走文件服务和客户端任务管理。
8. 实时语音与视频通话	通话记录落库、未接来电 Push、通话结束审计、后台计费或统计、异常通话风控可走 Kafka。	WebRTC offer/answer/ICE、接听、挂断等实时信令不建议 Kafka 主链路；仍走 WS。
9. 企业工作台与办公协同	工作台红点更新、会议创建/更新/取消/提醒/响应、日报/月报提交和催办、总经理信箱提交、工作台系统通知、后台配置变更、审计都适合 Kafka。	工作台模块列表、组织架构查询、报表详情查询不走 Kafka；普通查询走 MySQL/Redis 缓存。
10. 个人资料、通用设置、隐私与青少年模式	资料变更事件、隐私配置变更、青少年模式开启/关闭、多设备退出、Push Token 变更审计、App 发布配置缓存失效可走 Kafka。头像上传后走文件安全检测。	本地清缓存、系统权限引导、密码验证、Action Token 不走 Kafka。
11. 反诈安全、举报与意见反馈	风控确认审计、举报受理、证据文件安全检测、意见反馈、诊断包处理、后台审核通知、合规处置事件可走 Kafka。	风险弹窗同步拦截结果、举报原因查询、反馈配置查询不走 Kafka。
12. 联调实施清单	Kafka 需要覆盖消息幂等、系统事件可信生产、文件安全检测、后台群操作到 C 端、离线 Push、失败重试和死信补偿验收。	前端基础联调请求不直接依赖 Kafka，除非该接口声明为异步任务。

5. 文件链路结论

文件上传、下载、Range、ETag、OSS 对象读写不走 Kafka。Kafka 只接入文件完成后的业务事件：

1. 上传完成后投递 im.file.security，调用阿里云内容安全和恶意文件检测。
2. 安全检测完成后更新文件审核状态，并通过 im.business.event 或系统通知告知相关用户。
3. 消息发送、收藏、群文件登记、日报/月报/反馈/举报提交成功后投递 im.file.lifecycle，建立业务引用和 ACL。
4. 业务撤回、删除、合规处置或临时文件 TTL 到期后投递 im.file.lifecycle，执行引用释放、禁用下载或 OSS 删除。

6. 工作台链路结论

工作台“查询类接口”不需要 Kafka，但工作台“状态变化和提醒类事件”适合 Kafka：

1. 会议创建、更新、取消、提醒、参会响应生产 im.workbench.event，消费者生成系统通知、红点并通过 WS 通知在线客户端。
2. 日报/月报提交、撤回、重开、管理员催办生产 im.workbench.event，用于红点、催办 Push 和审计。
3. 总经理信箱提交生产 im.workbench.event 和 im.audit.event，后台处理结果再回推 C 端。
4. 工作台模块配置变更生产 im.cache.invalidate，IM 节点刷新进程内配置缓存。

7. 已补充：缓存失效与 Admin 配置查询

1. im.cache.invalidate 已接入 IM 消费端，支持租户、注册短信、第三方配置、字典配置、Redis 对象缓存、群热消息缓存失效。
2. IM 已增加 Admin 内部配置查询客户端，开启 admin_internal_api.enabled=true 后优先通过 Admin 查询 hotgo 侧配置，旧数据库读取作为灰度兜底。
3. Admin 侧需要补齐 /internal/im-config/* 只读接口，并与 IM 使用同一套 HMAC 签名密钥。
4. Kafka 死信已补齐查询、忽略、解决、重放闭环：查询走 IM 内部 API，处理走 im.admin.command。
5. 用户治理类后台动作已接入 im.admin.command：封禁/解封、冻结/恢复、踢指定设备、全端登出、注销/删除账号。

8. 首批建议实现

1. 先实现 Kafka 基础生产者、消费者、配置、健康检查和消费幂等表。
2. 接入 im.group.admin.event，解决 Admin 后台群操作通过 Kafka 投递到 C 端。
3. 接入 im.message.persist，将消息异步落库和幂等重试闭环。
4. 接入 im.file.security，把 OSS 上传完成后的文件安全检测异步化。
5. 接入 im.workbench.event，先覆盖会议提醒、日报/月报催办、总经理信箱提交通知。