23 KiB
IM Server 改造文档：支撑鸽达达管理后台复刻
本文面向 /Users/youshunlai/go_workspace/im_server 的现状改造，目标是为 Admin Server 复刻鸽达达后台提供准确、稳定、可审计的数据与治理能力。当前 IM Server 已有 Tinode 风格实时链路、产品 HTTP API、独立租户库、Kafka 命令消费、配置事件消费、内部 Admin Query，但鸽达达 20 个后台页面仍需要补充若干查询资源、审计日志、风控策略与消息处置能力。
1. 当前实现现状
核心架构：
| 能力 | 现状 |
|---|---|
| 实时链路 | Session -> Hub -> Topic -> Store。 |
| 客户端入口 | WebSocket /v0/channels，产品 HTTP /v1/im/...。 |
| 后台只读入口 | /internal/admin-query/tenants/{tenant_code}/...，要求内部签名与 capability。 |
| 后台写操作 | Kafka Admin Command 消费器 startKafkaAdminCommandConsumer。 |
| 配置同步 | Kafka config event、cache invalidate consumer 已存在。 |
| 消息转发 | /v1/im/messages/forward 已存在。 |
| 音视频入会 | /v1/im/calls/rtc-join 已存在。 |
本地 tinode 库观察：im_users 有数据、im_topics 有群/会话、im_subscriptions 有订阅、im_messages 有大量单聊或通用消息、im_group_messages 有群消息、im_feedback_submissions、im_abuse_reports、im_kafka_dead_letters 等表已存在；im_audit_logs 本地为空，im_devices 和 im_group_files 数据不足，不能直接满足后台登录历史、设备历史和群文件验收。
已有内部查询资源：
| 资源 | 已支持字段/场景 |
|---|---|
users |
用户 ID、账号、手机号、状态、资料、凭证摘要、最后在线。 |
user_devices |
用户设备列表。 |
groups |
Topic、群名、群主、群状态、治理开关、成员数。 |
groups/{topic}/members |
群成员。 |
group_join-requests、group_invitations、group_announcements、group_mutes、group_admin-logs、group_files |
群治理专题资源。 |
messages/{topic}/{seq} |
单条消息详情。 |
files、files/{id}、files/{id}/links |
文件列表、详情、链接关系。 |
feedback-submissions、abuse-reports、realname-verifications、audit-logs |
用户反馈、举报、实名、审计。 |
dashboard/summary |
当前只返回待办类指标，不足以覆盖鸽达达首页统计。 |
已有 Kafka Admin Command：
| 命令 | 用途 |
|---|---|
user.ban、user.unban |
用户封禁/解封。 |
user.freeze、user.unfreeze |
用户冻结/解冻。 |
user.device.kick、user.logout_all |
设备踢下线、全端登出。 |
user.account.cancel、user.account.delete、user.password.reset |
注销、删除、重置密码。 |
group.profile.update |
群资料更新。 |
group.governance.update |
群治理开关更新。 |
group.admin.set、group.admin.remove、group.owner.transfer |
群角色管理。 |
group.member.mute、group.member.unmute、group.member.remove |
群成员治理。 |
kafka.dead_letter.replay、ignore、resolve |
死信处理。 |
2. 改造原则
IM Server 只负责租户业务库的数据查询、业务状态变更、实时生效与审计事件产生，不直接依赖 HotGo 后台表。Admin Server 下发的配置、策略和治理命令必须具备幂等性，并通过事件结果回传 Admin。所有 internal query 必须保持只读、分页、最大 per_page=200、内部签名鉴权、字段脱敏。
响应协议继续沿用现有 imHTTPResponse：code、data、reason、message、details、request_id、server_time。写请求继续要求 Idempotency-Key，避免后台重复点击导致重复处置。
3. 支撑 20 个后台页面的 IM 改造
3.1 数据概览
现有 dashboard/summary 只覆盖死信、待处理 outbox、待实名、待举报、待反馈、活跃群、封禁用户等运营待办。需要新增统计字段以匹配鸽达达首页。
新增 internal query：
| 路径 | 方法 | 说明 |
|---|---|---|
/internal/admin-query/tenants/{tenant}/dashboard/overview |
GET | 返回总用户、活跃用户、总群组、总会话、总消息、今日消息。 |
/internal/admin-query/tenants/{tenant}/dashboard/trends |
GET | 返回最近 N 天用户增长与消息增长。 |
字段口径：
| 字段 | 计算建议 |
|---|---|
total_users |
im_users 有效用户数。 |
active_users |
last_seen 在指定窗口内或当天有消息/登录行为的用户数。 |
total_groups |
im_group_settings.group_status='active' 或有效群 topic 数。 |
total_conversations |
有效 P2P topic + group topic 数。 |
total_messages |
im_messages + im_group_messages，按最终存储口径去重。 |
today_messages |
当天创建的消息数，按租户时区对齐。 |
date、user_count、message_count |
趋势表行字段。 |
3.2 用户管理
现有 users、users/{id}、users/{id}/devices 基本可支撑。需要补足鸽达达页面要求的筛选和字段脱敏。
改造点：
| 项 | 内容 |
|---|---|
| 查询筛选 | 增加 phone、public_account、state、created_at_start/end、last_seen_start/end。 |
| 字段补充 | 返回 nickname、头像文件 ID、性别、地区、签名、认证方式摘要、设备数、最近登录 IP。 |
| 状态映射 | 将 Tinode state 转换为 Admin 字典所需状态；保留原始值 raw_state 便于排错。 |
| 治理命令 | 继续使用已有 user.ban/unban/freeze/unfreeze/device.kick/logout_all/account.cancel/account.delete/password.reset。 |
| 审计 | 每次状态变更、重置密码、踢设备必须写 im_audit_logs 并产出 Kafka command result。 |
枚举建议：user_state 包含正常、封禁、冻结、注销、删除；device_platform 包含 ios、android、web、desktop、unknown。
3.3 用户分组
当前 IM Server 没有看到独立的后台用户策略分组执行层。Admin 将新增策略分组后，IM Server 需要消费配置事件并在运行时执行。
新增能力：
| 能力 | 说明 |
|---|---|
| 策略缓存 | 按租户缓存 policy_group、成员关系、优先级与规则。 |
| 匹配入口 | 登录、注册、加好友、建群、入群、发消息、上传文件、发起音视频前匹配策略。 |
| 配置事件 | 消费 user_policy_group.updated、user_policy_group.deleted，刷新缓存。 |
| 命中审计 | 命中 deny、challenge 或高风险规则时写审计与风控日志。 |
策略动作枚举：allow 放行、deny 拦截、challenge 二次验证、audit_only 仅记录。
好友策略需要在后端覆盖所有移动端入口。禁止加好友时，IM Server 不能只让客户端隐藏按钮，而要在搜索用户、查看个人名片、群成员资料、二维码解析、好友申请、邀请注册自动加好友、推荐联系人等入口统一拦截或返回脱敏数据。策略字段建议包含 allow_add_friend、direct_add_friend、max_friend_count、allow_qrcode_add_friend、allow_group_member_profile、hide_profile_when_friend_disabled。
3.4 群组管理
已有 groups 查询与群治理命令可复用。需要补鸽达达群状态语义和可能的群封停动作。
改造点：
| 项 | 内容 |
|---|---|
| 字段 | 确保 topic、group_name、owner_id、group_status、business_member_count、join_approval、mute_all、created_at 可稳定返回。 |
| 状态 | 明确 group_status 值：active、muted、suspended、dissolved。 |
| 命令 | 已有资料更新、治理设置、角色与成员治理；若需求要求群封停/解封，新增 group.suspend、group.unsuspend。 |
| 审计 | 群资料、治理开关、解散、禁言、成员操作均写 im_group_admin_logs 与 im_audit_logs。 |
3.5 群成员管理
现有 groups/{topic}/members 与成员命令可支撑。需要确保成员列表返回群角色、禁言状态与入群时间。
字段建议：topic、user_id、nickname、display_name、role、status、muted_until、joined_at、last_seen。role 枚举为 owner、admin、member；status 枚举为 active、muted、removed。
按钮对应命令：设管理员 group.admin.set、取消管理员 group.admin.remove、转让群主 group.owner.transfer、成员禁言 group.member.mute、解除禁言 group.member.unmute、移除成员 group.member.remove。
3.6 邀请码管理
IM Server 注册链路已在 user.go 中记录邀请码使用，RecordUse 已存在。需要解决邀请码格式冲突：鸽达达需求为 6 位数字，既有 IM 文档曾要求 5 位 ASCII 字母。若严格复刻鸽达达，应将 IM 注册校验、错误提示、唯一性检查、大小写处理统一改为 6 位数字。
改造点：
| 项 | 内容 |
|---|---|
| 校验 | 仅允许 ^[0-9]{6}$，不做大小写转换。 |
| 使用记录 | 注册成功后写 im_registration_invite_uses，包含 code、user_id、request_id、used_at。 |
| 并发 | 使用事务或唯一约束防止超发。 |
| 状态 | unused、used、expired、revoked。 |
3.7 单聊消息
当前只有单条消息 detail 查询，不足以支撑后台列表。需要新增 internal message list resource。
新增 internal query：
| 路径 | 方法 | 查询参数 |
|---|---|---|
/internal/admin-query/tenants/{tenant}/private-messages |
GET | topic、from_user_id、to_user_id、content_type、status、keyword、created_at_start/end、page、per_page。 |
/internal/admin-query/tenants/{tenant}/messages/{topic}/{seq} |
GET | 已有，继续作为详情。 |
返回字段：topic、seq_id、from_user_id、to_user_id、head、content_type、content_excerpt、status、created_at、updated_at。全文内容只在详情返回，并根据 Admin 权限决定是否脱敏。
新增 Kafka 命令建议：message.hide、message.unhide、message.delete、message.restore。如果只允许软删除，命令语义必须明确为后台不可见还是客户端不可见。
3.8 群聊消息
新增 internal group message list resource。可读取 im_group_messages 或统一消息表，但需要确保与客户端可见状态一致。
路径：/internal/admin-query/tenants/{tenant}/group-messages。
筛选：topic、sender_user_id、content_type、status、keyword、created_at_start/end。返回字段在单聊基础上增加 group_name、reply_to_seq、at_users。
处置命令复用消息命令，审计动作记录为 message.hidden、message.deleted、message.restored。
3.9 敏感词库
IM Server 需要新增敏感词运行时，而词库主数据由 Admin 控制库维护。IM Server 只消费配置事件和执行匹配。
改造点：
| 项 | 内容 |
|---|---|
| 缓存 | 按租户加载敏感词，支持分组、场景、优先级、状态。 |
| 匹配场景 | 消息发送、编辑消息、用户昵称/签名、群名/公告、反馈/举报内容。 |
| 动作 | block 拦截、replace 替换、review 进入审核、audit_only 仅审计。 |
| 审计 | 命中记录写 im_sensitive_word_hits 或统一 im_audit_logs。 |
| 性能 | 正常词库用 AC 自动机或等价高效结构；正则词单独限量执行。 |
3.10 文件管理
已有 internal files、files/{id}、files/{id}/links 与文件生命周期 Kafka 基础。需要补后台预览、下载和处置一致性。
改造点：
| 项 | 内容 |
|---|---|
| 文件状态 | normal、quarantined、deleted、orphan。 |
| 审核状态 | 复用 pending、running、clean、risky、failed。 |
| 预览下载 | 提供短期签名 URL 或代理下载，禁止返回永久存储地址。 |
| 隔离删除 | 后台命令应更新文件状态、断开消息/群文件链接、写审计。 |
| 安全审核 | 接入内容安全/恶意文件检测结果，并可重试审核。 |
3.11 用户反馈
已有 feedback-submissions 资源可查询。需要补处理状态回写能力和状态审计。
新增能力：
| 能力 | 说明 |
|---|---|
| 状态更新 | 提供 Kafka 命令或内部写接口：feedback.status.update。 |
| 附件 | 通过文件链接查询反馈附件，并返回签名预览 URL。 |
| 分类 | 分类来自 im_feedback_config.categories，Admin 配置后 IM bootstrap 同步。 |
| 审计 | 处理人、处理备注、前后状态写入审计。 |
状态枚举：received、processing、resolved、closed。
3.12 操作日志
IM Server 需要补充业务侧审计完整性。当前本地 im_audit_logs 为空，不能支撑后台多页面审计。
写入场景：用户状态变更、群治理、消息处置、文件处置、反馈处理、敏感词命中、登录成功/失败、配置热更新、Kafka 命令执行结果。
字段：request_id、actor_user_id、action、target_type、target_id、ip、user_agent、detail、created_at。detail 中敏感值必须脱敏或存 hash。
3.13 用户账号审计
新增或扩展 internal resource user-account-audit，按用户聚合账号生命周期事件。
路径：/internal/admin-query/tenants/{tenant}/user-account-audit。
筛选：user_id、action、operator_id、ip、created_at_start/end。返回：event_id、user_id、action、operator_type、operator_id、before_state、after_state、reason、ip、device_id、created_at。
动作枚举：registered、login_success、logout、login_failed、password_changed、password_reset、banned、unbanned、frozen、unfrozen、device_kicked、cancelled、deleted。
3.14 群事件审计
已有 im_group_admin_logs 与 group outbox，可新增 internal resource group-event-audit 或复用 group_admin-logs 扩展为全局查询。
路径：/internal/admin-query/tenants/{tenant}/group-event-audit。
筛选：topic、operator_id、target_user_id、action、created_at_start/end。返回：event_id、topic、operator_id、target_user_id、action、object_type、object_id、before_data、after_data、created_at。
3.15 管理员登录历史
该页面主要由 Admin Server 的 HotGo 登录日志提供，IM Server 无需改造。若以后要展示 Admin 调用 IM internal API 的访问审计，可在 internal API 层增加 internal_api_access_logs，但不作为复刻 P0。
3.16 用户登录历史
当前缺少完整登录历史表与查询。需要在认证成功、token 刷新、主动/被动登出时记录日志。
新增表建议：im_user_login_logs。
字段：id、user_id、login_type、device_id、platform、ip、region、user_agent、request_id、result、login_at、logout_at、created_at。
新增 internal query：/internal/admin-query/tenants/{tenant}/user-login-logs，支持按 user_id、phone/account、ip、platform、login_at_start/end 查询。
3.17 IP 账号统计
新增聚合查询，来源为注册、登录成功、登录失败、风控命中日志。
路径：/internal/admin-query/tenants/{tenant}/ip-account-stats。
字段：ip、region、user_count、register_count、login_count、failure_count、first_seen_at、last_seen_at、risk_level。该接口可以实时聚合，也可以由定时任务写入快照表以降低查询成本。
3.18 登录失败日志
新增表建议：im_login_failure_logs。
字段：id、account、user_id、failure_type、reason、ip、region、device_id、platform、user_agent、request_id、attempt_at。
新增 internal query：/internal/admin-query/tenants/{tenant}/login-failure-logs。失败类型枚举：password_error、code_error、account_not_found、account_disabled、rate_limited、risk_blocked。
3.19 私域设置
IM Server 需要确保客户端 /v1/im/bootstrap 使用 Admin 发布后的配置，并支持热更新。
配置来源：
| 配置 | 使用位置 |
|---|---|
| 注册/邀请码/短信 | 注册、验证码、密码找回。 |
| 上传/文件审核 | 上传、预览、消息附件。 |
| 反馈/邮箱/通知 | 客户端入口与提交表单。 |
| 版本/工作台 | bootstrap、app release、workbench。 |
| 声网/音视频 | /v1/im/calls/rtc-join。 |
| 好友功能 | /v1/im/bootstrap 返回 global_friend_enabled、入口隐藏建议和提示文案；实际拦截由后端完成。 |
| 消息宵禁 | /v1/im/bootstrap 返回当前宵禁摘要和提示文案；发送消息时仍以后端实时校验为准。 |
改造点：配置事件必须带版本号；IM 缓存应支持按租户回滚到上一发布版本；bootstrap 返回的配置只包含客户端需要的非敏感字段。
3.20 安全策略
IM Server 是安全策略的执行层。需要将 Admin 发布的策略接入登录、验证码、消息、文件、群、好友、实名、音视频等关键入口。全局禁止加好友和宵禁必须后端强制执行，客户端展示仅作为体验优化。
策略项：
| 策略 | 执行点 |
|---|---|
| 密码强度 | 注册、改密、重置密码。 |
| 登录限频 | 登录、验证码校验、密码找回。 |
| IP 黑白名单 | 登录、注册、发消息、上传文件。 |
| 敏感词 | 消息、资料、群资料、反馈。 |
| 文件审核 | 上传完成、消息发送前后、后台重审。 |
| 实名要求 | 加好友、建群、入群、发起音视频等敏感能力。 |
| 风控挑战 | 登录异常、IP 异常、设备异常。 |
| 全局好友功能 | 用户搜索、好友申请、二维码解析、群成员资料、个人名片、推荐联系人、邀请注册自动加好友。 |
| 消息宵禁 | 单聊/私聊发送消息入口，默认拦截 P2P topic 的 {pub}；如产品确认群聊也管控，可扩展到 group topic。 |
动作枚举统一为 allow、challenge、block、audit_only。
全局禁止加好友执行规则：
| 入口 | 后端行为 |
|---|---|
用户搜索 /v1/im/users/search |
可直接返回空列表，或返回脱敏结果但不允许发起好友申请。 |
用户详情 /v1/im/users/{id} |
非好友场景隐藏手机号、账号、二维码、个人扩展资料，只保留必要公开字段。 |
好友申请 /v1/im/friend-requests |
返回业务错误 reason，例如 FRIEND_DISABLED。 |
二维码解析 /v1/im/qrcodes/resolve |
禁止解析出可加好友目标，或返回脱敏提示。 |
| 群成员资料 | 群成员列表可保留昵称/头像用于群聊展示，但点击个人信息时返回脱敏资料并禁止添加。 |
| 邀请注册自动加好友 | 注册成功后跳过自动加好友并写审计，或按策略直接拒绝该邀请码能力。 |
宵禁执行规则：
| 项 | 说明 |
|---|---|
| 配置 | message_curfew_enabled、message_curfew_rules，规则包含时区、日期类型、开始时间、结束时间、scope、白名单、提示文案。 |
| 判断时机 | P2P topic 发布消息前校验；HTTP 消息发送、转发、草稿转发送等入口也要校验。 |
| 拦截结果 | 返回明确 reason，例如 MESSAGE_CURFEW_ACTIVE，并记录 im_audit_logs 或风控日志。 |
| 白名单 | 支持用户、系统账号、特定会话豁免。 |
| 跨天 | 支持如下班后 18:00-09:00 的跨天时间段。 |
4. Internal Admin Query 新增清单
建议在 server/internal_admin_query_resources.go 增补资源，并在 server/internal_api.go 路由分发中注册：
| 资源 | 必要性 | 说明 |
|---|---|---|
dashboard/overview、dashboard/trends |
P0 | 首页统计。 |
private-messages、group-messages |
P0 | 消息管理列表。 |
user-login-logs、login-failure-logs |
P0 | 登录审计。 |
ip-account-stats |
P1 | IP 风险聚合。 |
user-account-audit、group-event-audit |
P1 | 专题审计。 |
sensitive-word-hits |
P1 | 敏感词命中查询。 |
所有列表接口返回现有结构：items、total、page、per_page。时间筛选继续使用 created_at_start、created_at_end 等字段，UID 参数继续支持数字 ID 与 usr... 编码。
5. Kafka 命令新增清单
已有用户与群治理命令保留。为复刻后台补充以下命令：
| 命令 | 说明 |
|---|---|
message.hide |
后台隐藏消息，客户端不可见或后台标记隐藏。 |
message.unhide |
恢复隐藏消息。 |
message.delete |
后台删除消息，建议软删除。 |
message.restore |
恢复误删消息。 |
file.quarantine |
文件隔离。 |
file.delete |
文件删除。 |
feedback.status.update |
反馈处理状态更新。 |
group.suspend、group.unsuspend |
如产品确认需要群封停/解封，则新增。 |
security.policy.reload |
强制刷新安全策略缓存。 |
friend.policy.reload |
强制刷新好友入口策略缓存，可与 security.policy.reload 合并实现。 |
curfew.policy.reload |
强制刷新宵禁策略缓存，可与 security.policy.reload 合并实现。 |
命令 payload 必须包含 command_id、actor_user_id、reason、目标 ID、version 或 expected_version。执行后发布 result，状态为 success、failed、dead。
6. 数据库改造建议
配套建表与兼容迁移脚本见 sql/IM-Server改造.sql。脚本默认使用本地 tinode，上线时必须对每个独立租户数据库分别执行，租户业务表不增加 tenant_id。
租户库新增或补强表：
| 表 | 用途 |
|---|---|
im_user_login_logs |
用户登录成功、登出、刷新等历史。 |
im_login_failure_logs |
登录失败与风控拦截历史。 |
im_message_admin_actions |
后台消息处置记录，可与消息表状态解耦。 |
im_sensitive_word_hits |
敏感词命中记录。 |
im_ip_account_stats_daily |
IP 账号统计快照，可选。 |
已有表需补数据写入：im_audit_logs 当前本地为空，需要在关键业务入口统一写；im_devices 本地为空，需要确认设备绑定/解绑路径是否完整；im_group_files 本地为空，需要验证群文件写入链路。
索引建议：消息列表按 (topic, created_at)、(from, created_at)；登录日志按 (user_id, login_at)、(ip, login_at)；失败日志按 (account, attempt_at)、(ip, attempt_at)；敏感词命中按 (scene, created_at)、(user_id, created_at)。
7. 验收要求
- Admin 20 个页面的查询按钮均能通过 internal query 返回真实数据或标准空态。
- 用户、群、消息、文件、反馈的后台写操作均通过 Kafka 命令，具备幂等、结果回传、死信处理。
- 登录历史、失败日志、账号审计、群事件审计不再依赖空表，关键入口可产生真实审计数据。
- 敏感词与安全策略变更可热更新，无需重启 IM Server。
- 所有 internal query 均保持只读、分页、鉴权、脱敏和错误 reason 规范。
- 邀请码格式在 Admin 与 IM 注册链路完全一致，避免后台生成后客户端无法使用。