pro/im_server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
085a48c3d9f3ab3e29c7b1efd3c9a2bbd29a93f9
im_server/docs/IM-Kafka接入联调测试文档.md
T

1128 lines
46 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# IM Kafka 接入联调测试文档
> 关联文档：[IM Kafka 接入方案](./IM-Kafka接入方案.md)、[IM Kafka 接入范围识别](./IM-Kafka接入范围识别.md)、[IM Kafka 基础表 SQL](./sql/IM-Kafka基础表SQL.sql)
> 适用范围：Admin/HotGo 与 IM Server 通过 Kafka 和内部只读 API 联调。
> 当前约定：Admin 只访问 `hotgo`，IM Server 只访问租户库；跨系统写操作走 Kafka，跨系统查询走内部只读 API。
## 1. 联调目标
1. 验证 Kafka 基础生产、消费、幂等、重试、死信能正常工作。
2. 验证 Admin 后台操作通过 `im.admin.command` 投递到 IM Server，并通过 `im.admin.command.result` 返回最终状态。
3. 验证 IM Server 私聊/群聊消息异步落库、缓存失效、死信处理、用户治理命令全部可用；文件生命周期和工作台事件同步落库。
4. 验证 Admin 与 IM Server 不跨库直连：Admin 查询租户业务数据走 IM 内部 API；IM 查询 hotgo 配置走 Admin 内部 API。
5. 验证 Kafka 异常情况下不会产生重复业务结果，且失败可重试、可进入死信、可人工重放。
## 2. 环境准备
### 2.1 服务与依赖
| 组件 | 要求 |
| --- | --- |
| MySQL | `hotgo` 控制库、租户库如 `tinode` 已创建并可连接。 |
| Redis | IM Server 已配置 Redis，用于在线状态、短状态、热缓存和跨节点 fanout。 |
| Kafka | Topic 已创建或允许自动创建；建议测试环境显式创建。 |
| OSS | 文件上传下载仍走 OSS，文件元数据和生命周期小流量动作同步处理。 |
| Admin/HotGo | 已接入 Kafka producer/consumer、outbox、内部配置查询接口。 |
| IM Server | 已启用 Kafka、内部 Admin Query API、Admin Internal Config Client。 |
### 2.2 Kafka Topic
| Topic | 方向 | 用途 |
| --- | --- | --- |
| `im.admin.command` | Admin -> IM | 后台群治理、用户治理、死信处理命令。 |
| `im.admin.command.result` | IM -> Admin | 后台命令执行结果。 |
| `im.config.event` | Admin -> IM | 租户配置、字典、第三方配置变更通知。 |
| `im.cache.invalidate` | Admin/IM -> IM | 跨节点缓存失效。 |
| `im.message.persist` | IM -> IM | 私聊消息异步落库。 |
| `im.group.message.persist` | IM -> IM | 群聊消息异步落库。 |
| `im.audit.event` | IM -> Admin/HotGo | 跨系统审计事件。 |
| `im.dead.letter` | IM -> Admin/告警 | 消费失败死信。 |
说明：`im.message.push` 已规划但本轮不联调，离线 Push Kafka 化仍在增强项中。
### 2.3 数据库准备
租户库必须执行：
```sql
SOURCE docs/sql/IM-Kafka基础表SQL.sql;
```
重点确认租户库存在：
| 表 | 用途 |
| --- | --- |
| `im_kafka_consume_log` | 消费幂等、重试状态。 |
| `im_kafka_dead_letters` | 死信记录与人工处理状态。 |
| `im_messages` | 私聊消息存储。 |
| `im_group_messages` | 群聊消息存储。 |
| `im_filemsglinks` | 私聊附件引用。 |
| `im_group_files` | 群文件和群附件引用。 |
| `im_system_notifications` | 工作台等系统通知。 |
| `im_business_events_outbox` | WS 业务事件投递队列。 |
Admin/HotGo 侧需具备：
| 表/能力 | 用途 |
| --- | --- |
| `im_admin_commands` | Admin 操作单，记录后台操作 `pending/running/succeeded/failed/dead`。 |
| `im_admin_outbox` | Admin outbox，与操作单同事务写入，可靠发送 Kafka。 |
| `im_kafka_dead_letter_events` | Admin 消费 `im.dead.letter` 后落 HotGo，用于告警和排障。 |
| Admin 配置表/字典表 | 为 `/internal/im-config/*` 提供数据源。 |
Admin/HotGo 侧需执行：
```sql
SOURCE server/storage/data/generate/im_kafka_admin_tables.sql;
SOURCE server/storage/data/generate/im_kafka_event_tables.sql;
SOURCE server/storage/data/generate/im_kafka_command_menu.sql;
SOURCE server/storage/data/generate/im_dead_letter_menu.sql;
SOURCE server/storage/data/generate/im_kafka_audit_menu.sql;
```
### 2.4 IM Server 配置
`tinode.conf` 或 Docker 环境变量：
```json
{
"kafka": {
"enabled": true,
"brokers": ["127.0.0.1:9092"],
"client_id": "im-server",
"consumer_group": "im-server",
"allow_auto_topic_creation": false,
"max_retry_count": 3
},
"internal_api": {
"enabled": true,
"time_window_seconds": 300,
"services": {
"hotgo-admin": {
"secret": "same-secret",
"allow": ["admin_query"]
}
}
},
"admin_internal_api": {
"enabled": true,
"base_url": "http://hotgo-admin:8080",
"service_name": "im-server",
"secret": "same-secret",
"timeout_ms": 3000
}
}
```
### 2.5 Admin/HotGo 配置
Admin 需要：
1. Kafka producer 发送 `im.admin.command`、`im.config.event`、`im.cache.invalidate`。
2. Kafka consumer 消费 `im.admin.command.result`、`im.dead.letter`。
3. 内部接口客户端调用 IM `/internal/admin-query/*`。如果 IM API 前缀为 `/v1`，Admin 配置 `imInternalApi.baseUrl` 应包含 `/v1`，例如 `http://im-server:6060/v1`。
4. 内部接口服务端提供 IM `/internal/im-config/*`。
5. 内部接口签名与 IM 一致。
HMAC 签名请求头：
| Header | 说明 |
| --- | --- |
| `X-Service-Name` | 调用方服务名，如 `hotgo-admin` 或 `im-server`。 |
| `X-Timestamp` | Unix 秒级时间戳。 |
| `X-Nonce` | 一次性随机串。 |
| `X-Signature` | HMAC-SHA256 hex 签名。 |
签名文本：
```text
METHOD + "\n" + RequestURI + "\n" + BodySHA256Hex + "\n" + Timestamp + "\n" + Nonce
```
### 2.6 Admin 与 IM Server 分工
| 模块 | Admin/HotGo 负责 | IM Server 负责 |
| --- | --- | --- |
| 库访问边界 | 只访问 `hotgo` 控制库，不直连租户库。 | 只访问租户库，不直连 `hotgo`。 |
| 后台写操作 | 写 Admin 操作单和 Admin outbox，生产 `im.admin.command`。 | 消费命令、执行租户业务、回传 `im.admin.command.result`。 |
| 后台查询 | 通过 IM `/internal/admin-query/*` 查询租户业务数据。 | 提供白名单只读查询接口，统一 HMAC 鉴权。 |
| IM 配置读取 | 提供 `/internal/im-config/*`。 | 通过 Admin 内部配置接口读取租户、注册、第三方配置。 |
| Kafka 死信 | 消费 `im.dead.letter`，展示告警和处理入口。 | 记录死信，提供查询接口，消费处理命令。 |
| 审计 | 消费 `im.audit.event` 并同步落 HotGo 审计表。 | 关键业务动作生产跨系统审计事件，不在 IM 内部消费落库。 |
### 2.7 IM 内部查询接口矩阵
Admin 调用以下接口时统一使用 `GET /v1/internal/admin-query/tenants/{tenant_code}/...`，如果部署未配置 `/v1` 前缀，则以实际 IM HTTP 前缀为准。
P0 核心页面：
| 接口 | 用途 |
| --- | --- |
| `/users` | 用户列表。 |
| `/users/{user_id}` | 用户详情。 |
| `/users/{user_id}/devices` | 用户设备列表。 |
| `/groups` | 群列表。 |
| `/groups/{topic}` | 群详情和治理配置。 |
| `/groups/{topic}/members` | 群成员分页列表。 |
| `/groups/{topic}/join-requests` | 入群申请列表。 |
| `/groups/{topic}/invitations` | 群邀请列表。 |
| `/groups/{topic}/announcements` | 群公告列表。 |
| `/groups/{topic}/mutes` | 群禁言列表。 |
| `/groups/{topic}/admin-logs` | 群管理日志。 |
| `/groups/{topic}/files` | 群文件列表。 |
| `/files` | 文件列表。 |
| `/files/{file_id}` | 文件详情。 |
| `/files/{file_id}/links` | 文件引用列表。 |
| `/kafka/dead-letters` | Kafka 死信列表。 |
| `/kafka/dead-letters/{dead_id}` | Kafka 死信详情。 |
P1/P2 运营和完整隔离页面：
| 接口 | 用途 |
| --- | --- |
| `/audit-logs`、`/audit-logs/{id}` | 审计日志列表和详情。 |
| `/realname-verifications`、`/realname-verifications/{id}` | 实名审核列表和详情。 |
| `/abuse-reports`、`/abuse-reports/{id}` | 举报工单列表和详情。 |
| `/reports/abuse/{report_id}/target` | 举报目标快照。 |
| `/feedback-submissions`、`/feedback-submissions/{id}` | 意见反馈列表和详情。 |
| `/outbox/business-events`、`/outbox/group-events` | 业务 Outbox 和群 Outbox 列表。 |
| `/outbox/business-events/{id}`、`/outbox/group-events/{id}` | Outbox 详情。 |
| `/org/departments`、`/org/members` | 组织部门和组织成员。 |
| `/workbench/apps` | 工作台应用配置。 |
| `/dashboard/summary` | 租户任务看板摘要。 |
| `/feedback-config`、`/mailbox-config` | 反馈配置、总经理信箱配置。 |
| `/abuse-reasons`、`/app-releases` | 举报原因、App 发布策略。 |
列表接口统一验收 `items/total/page/per_page`，详情接口统一验收 `code=0,data={...}`。用户 ID、雪花 ID、`seq_id`、`dead_id` 等大整数或长 ID 建议按字符串处理，避免前端丢精度。
### 2.8 Admin 内部配置接口矩阵
IM Server 调 Admin 时统一使用 HMAC 签名，Admin 需提供：
| 接口 | 用途 |
| --- | --- |
| `GET /internal/im-config/tenants/by-code/{tenant_code}` | 按租户编码查询租户。 |
| `GET /internal/im-config/tenants/by-id/{tenant_id}` | 按租户 ID 查询租户。 |
| `GET /internal/im-config/tenants?state=active&limit=1000` | 拉取启用租户列表。 |
| `GET /internal/im-config/registration/sms` | 读取注册短信配置。 |
| `GET /internal/im-config/third-party/{group}?keys=a,b` | 读取 OSS、文件安全、声网、极光等第三方配置。 |
联调时需要特别确认 OSS 和文件安全配置已经从 Admin 字典项返回，IM 不再依赖本地硬编码。
### 2.9 Admin Command 事件矩阵
| 事件类型 | 业务 |
| --- | --- |
| `group.profile.update` | 后台修改群资料。 |
| `group.governance.update` | 后台修改群治理配置。 |
| `group.admin.set`、`group.admin.remove` | 设置或取消群管理员。 |
| `group.member.mute`、`group.member.unmute` | 成员禁言或解禁。 |
| `group.member.remove` | 移除群成员。 |
| `group.owner.transfer` | 转让群主。 |
| `user.ban`、`user.unban` | 用户封禁和解封。 |
| `user.freeze`、`user.unfreeze` | 用户冻结和恢复。 |
| `user.device.kick` | 踢指定设备。 |
| `user.logout_all` | 全端登出。 |
| `user.account.cancel`、`user.account.delete` | 注销或删除账号。 |
| `kafka.dead_letter.ignore` | 忽略死信。 |
| `kafka.dead_letter.resolve` | 标记死信已解决。 |
| `kafka.dead_letter.replay` | 重放死信。 |
所有 Admin Command 都必须带 `event_id`、`tenant_code`、`event_type`、`biz_type`、`biz_id`、`payload.command_id`、`payload.actor_user_id`。Admin 不应把 Kafka 投递成功当成业务成功，最终状态以 `im.admin.command.result` 为准。
## 3. 通用验收规则
每个 Kafka 用例都必须检查：
1. Kafka 原始事件 `event_id` 全局唯一，同一事件重复投递不会重复产生业务副作用。
2. `tenant_code` 能正确路由到目标租户库。
3. 消费成功后 `im_kafka_consume_log.status=succeeded`。
4. 消费失败后 `retry_count` 增加，并按 `retry_backoff_ms` 重试。
5. 超过上限后写入 `im_kafka_dead_letters`，并投递 `im.dead.letter`。
6. Admin Command 成功、失败、死信都必须回传 `im.admin.command.result`。
7. 业务结果、审计事件、日志里的 `trace_id/event_id/biz_id` 可串联排查。
## 4. 联调用例
### TC-KAFKA-001 基础启动与 Topic 连通
目标：验证 Admin 和 IM 都能连接 Kafka，IM 消费者全部启动。
步骤：
1. 启动 Kafka、Redis、MySQL。
2. 启动 Admin/HotGo。
3. 启动 IM Server。
4. 查看 IM 日志应出现 Kafka enabled，且无 consumer 启动错误。
5. Admin 在「IM管理 -> Kafka命令」点击「发送缓存失效测试」，或调用 `POST /admin/imKafkaCommand/cacheInvalidate`，发送一条无业务副作用的测试 `im.cache.invalidate` 事件。
预期：
1. IM 成功消费测试事件。
2. `im_kafka_consume_log` 写入一条 succeeded 记录。
3. 无死信。
### TC-KAFKA-002 内部接口鉴权成功
目标：验证 Admin 调 IM 内部查询接口签名通过。
请求：
```http
GET /v1/internal/admin-query/tenants/default/users/usrxxx
X-Service-Name: hotgo-admin
X-Timestamp: <unix_seconds>
X-Nonce: <random>
X-Signature: <hmac_sha256_hex>
```
预期：
1. HTTP 200。
2. 响应 `code=0`。
3. 返回用户基础资料。
### TC-KAFKA-003 内部接口鉴权失败
目标：验证内部接口拒绝错误签名、过期时间戳、重复 nonce。
步骤：
1. 使用错误 secret 调用 `/internal/admin-query/*`。
2. 使用超过时间窗的 timestamp 调用。
3. 使用同一 nonce 重复调用两次。
预期：
1. 错误 secret 返回 401。
2. 过期 timestamp 返回 401。
3. 重复 nonce 第二次返回 401。
4. 业务数据不泄露。
### TC-KAFKA-004 IM 调 Admin 配置查询
目标：验证 IM 通过 Admin `/internal/im-config/*` 获取 hotgo 配置。
步骤：
1. 开启 IM `admin_internal_api.enabled=true`。
2. Admin 提供以下接口：
- `GET /internal/im-config/tenants/by-code/default`
- `GET /internal/im-config/tenants/by-id/1`
- `GET /internal/im-config/tenants?state=active&limit=1000`
- `GET /internal/im-config/registration/sms`
- `GET /internal/im-config/third-party/im_third_party?keys=...`
3. 重启 IM。
4. 执行登录、上传、文件安全配置读取等动作。
预期：
1. IM 优先请求 Admin 内部配置接口。
2. Admin 验签通过并返回必要字段。
3. IM 本地功能正常。
4. Admin 接口异常时，IM 可回落旧 DB 适配器，日志有 warn。
说明：Admin `/internal/im-config/*` 是内部服务接口，不带 `/admin` 后台前缀。
### TC-KAFKA-005 Admin 群资料修改命令
目标：验证后台群资料修改通过 Kafka 到 IM。
Admin 发送：
```json
{
"event_id": "admin:group:profile:update:001",
"tenant_code": "default",
"source_service": "hotgo-admin",
"target_service": "im-server",
"event_type": "group.profile.update",
"biz_type": "group_admin",
"biz_id": "grpxxx",
"payload": {
"command_id": "cmd-group-profile-001",
"actor_user_id": "usrAdmin",
"topic": "grpxxx",
"version": 1,
"profile": {
"name": "新群名称",
"description": "新群描述",
"avatar_file_id": "file_xxx"
}
}
}
```
预期：
1. IM 更新群业务表。
2. `im.admin.command.result` 返回 `status=succeeded`。
3. C 端在线群成员收到业务刷新事件或可重新拉取看到新资料。
4. 消费日志 succeeded。
5. 审计事件已投递。
### TC-KAFKA-006 Admin 群治理配置
目标：验证后台修改入群审批、全员禁言、成员上传、私聊、邀请开关。
事件类型：`group.governance.update`
Payload：
```json
{
"command_id": "cmd-group-govern-001",
"actor_user_id": "usrAdmin",
"topic": "grpxxx",
"version": 2,
"governance": {
"join_approval": true,
"mute_all": true,
"member_upload_files": false,
"member_private_chat": false,
"member_invite": false
}
}
```
预期：
1. 群设置版本递增或与业务规则一致。
2. 新配置对成员发送、上传、邀请等入口生效。
3. Admin 收到成功结果。
### TC-KAFKA-007 Admin 群成员治理
目标：验证管理员设置、取消、禁言、解禁、移除成员、转让群主。
事件类型：
| 命令 | 预期 |
| --- | --- |
| `group.admin.set` | 成员角色变为 admin。 |
| `group.admin.remove` | 成员角色恢复 member。 |
| `group.member.mute` | 成员禁言生效。 |
| `group.member.unmute` | 成员禁言解除。 |
| `group.member.remove` | 成员离群，不能继续收发该群消息。 |
| `group.owner.transfer` | 群主变更，旧群主权限调整。 |
每条命令都检查：
1. 租户库业务表状态正确。
2. 在线 C 端收到状态变化。
3. Admin 操作单从 running 变为 succeeded。
4. 重复发送同一 `event_id` 不重复执行。
### TC-KAFKA-008 用户封禁与解封
目标：验证 Admin 可通过 Kafka 封禁/解封用户。
封禁事件：
```json
{
"event_id": "admin:user:ban:001",
"tenant_code": "default",
"event_type": "user.ban",
"biz_type": "user_governance",
"biz_id": "usrxxx",
"payload": {
"command_id": "cmd-user-ban-001",
"actor_user_id": "usrAdmin",
"user_id": "usrxxx",
"reason": "违规"
}
}
```
步骤：
1. 目标用户保持在线。
2. Admin 发送 `user.ban`。
3. 目标用户尝试继续发消息。
4. 目标用户重新登录。
5. Admin 发送 `user.unban`。
6. 目标用户重新登录。
预期：
1. 封禁后用户状态为 `susp`。
2. 在线会话被踢下线。
3. 封禁期间登录被拒绝。
4. 解封后状态为 `ok`，可正常登录。
5. 两条命令均回传 result。
### TC-KAFKA-009 用户冻结与恢复
目标：验证冻结/恢复账号命令。
事件类型：`user.freeze`、`user.unfreeze`
预期：
1. `user.freeze` 设置用户状态 `susp` 并踢下线。
2. `user.unfreeze` 恢复用户状态 `ok`。
3. 重复投递同一 `event_id` 不重复产生额外副作用。
### TC-KAFKA-010 踢指定设备
目标：验证只踢指定设备，不影响同账号其他设备。
前置：
1. 同一用户使用两个设备登录，设备 ID 分别为 `device-a`、`device-b`。
事件：
```json
{
"event_id": "admin:user:device:kick:001",
"tenant_code": "default",
"event_type": "user.device.kick",
"biz_type": "user_governance",
"biz_id": "usrxxx:device-a",
"payload": {
"command_id": "cmd-device-kick-001",
"actor_user_id": "usrAdmin",
"user_id": "usrxxx",
"device_id": "device-a",
"reason": "后台踢设备"
}
}
```
预期：
1. `device-a` 对应会话被踢。
2. `device-b` 保持在线。
3. `device-a` 推送设备记录被删除。
4. Admin 收到 `evicted_sessions` 数量。
### TC-KAFKA-011 全端登出
目标：验证后台让用户所有设备退出登录。
事件类型：`user.logout_all`
预期：
1. 用户所有在线会话被踢。
2. 用户状态不改变。
3. 用户可重新登录。
### TC-KAFKA-012 注销与删除账号
目标：验证 Admin 可注销或删除租户内账号。
事件类型：
| 命令 | 预期 |
| --- | --- |
| `user.account.cancel` | 默认软删除，`hard=true` 时硬删除。 |
| `user.account.delete` | 按硬删除处理。 |
步骤：
1. 目标用户在线。
2. Admin 发送注销命令。
3. 查询用户状态。
4. 尝试重新登录。
预期：
1. 用户会话被踢。
2. 用户相关 Topic 被停止。
3. 用户被删除或标记 `del`。
4. 登录失败。
5. Admin 收到 result。
### TC-KAFKA-013 私聊消息异步落库
目标：验证 Kafka 开启时私聊消息通过 `im.message.persist` 落库。
步骤：
1. 用户 A 与用户 B 建立私聊。
2. A 发送带 `x-im-client-mid` 的私聊消息。
3. 查询 Kafka `im.message.persist`。
4. 查询租户库 `im_messages`。
5. A 使用同一 `x-im-client-mid` 重复发送。
预期：
1. A 立即收到服务端 ack 和 `seq_id`。
2. `seq_id` 为 BIGINT/int64。
3. 消费成功后 `im_messages` 有一条记录。
4. 重复发送不重复落库。
5. 消费日志 succeeded。
### TC-KAFKA-014 群聊消息异步落库
目标：验证群消息写入 `im_group_messages`，不混入私聊表。
步骤：
1. 创建群并加入至少两个成员。
2. 成员发送群消息。
3. 查询 `im_group_messages`。
4. 查询 `im_messages`。
5. 重连客户端按 Topic seq 拉取消息。
预期：
1. 群消息只写 `im_group_messages`。
2. `seq_id` 单调增长，类型为 BIGINT/int64。
3. 客户端补偿拉取成功。
4. 24 小时热消息可进入 Redis 热缓存。
### TC-KAFKA-015 消息消费失败重试
目标：验证 `im.message.persist` 消费失败可重试并最终成功。
步骤：
1. 临时制造租户库写入失败，如锁表或停止库连接。
2. 发送消息。
3. 恢复数据库。
4. 等待重试。
预期：
1. `im_kafka_consume_log.retry_count` 增加。
2. 未超过重试上限时不进入死信。
3. 数据库恢复后消息最终落库。
4. 状态变为 succeeded。
### TC-KAFKA-016 文件上传完成事件
目标：验证文件上传完成后不再产生 `im.file.lifecycle` Kafka 事件。
步骤：
1. 客户端上传文件到 OSS。
2. 上传完成后查询租户库文件记录。
3. 确认 Kafka topic 中没有 `im.file.lifecycle` 依赖。
预期：
1. 文件字节流只进入 OSS。
2. 上传完成后的文件记录已同步落库。
### TC-KAFKA-017 消息附件绑定
目标：验证消息落库后附件引用同步绑定。
步骤：
1. 上传图片或文件。
2. 发送带附件的私聊消息。
3. 发送带附件的群聊消息。
4. 查询附件引用表。
预期：
1. 私聊附件写入 `im_filemsglinks`。
2. 群聊附件写入 `im_group_files`。
3. 重复消费不重复绑定。
4. 文件 ACL 与业务引用可追踪。
### TC-KAFKA-018 群文件登记与删除
目标：验证群文件业务由 HTTP 接口同步落库。
步骤：
1. 群内登记文件。
2. 查询 `im_group_files`。
3. 删除群文件。
4. 检查生命周期事件和审计事件。
预期：
1. 群文件登记成功。
2. 删除状态正确。
3. 文件事件可用于后续回收/合规删除。
### TC-KAFKA-019 工作台会议事件
目标：验证会议创建、更新、取消、提醒、参会响应产生工作台事件。
步骤：
1. 创建会议。
2. 修改会议。
3. 发送提醒。
4. 参会人响应。
5. 取消会议。
预期：
1. 每个动作同步写 `im_system_notifications`。
2. 同步写 `im_business_events_outbox`。
3. 在线 C 端收到系统通知或红点刷新。
Admin 连通性补充：工作台事件不再走 Kafka，真实会议、日报/月报、信箱业务结果以 IM Server 对应业务用例为准。
### TC-KAFKA-020 日报/月报事件
目标：验证日报、月报提交和催办事件。
步骤：
1. 创建日报草稿。
2. 保存并提交日报。
3. 管理员催办日报。
4. 创建、提交、重开月报。
预期：
1. 通知目标用户正确。
2. 工作台红点或系统通知可被客户端看到。
### TC-KAFKA-021 总经理信箱事件
目标：验证总经理信箱提交事件和审计。
步骤：
1. 用户提交信箱内容。
2. 检查同步生成的通知/业务事件。
3. Admin 后台生成处理单。
预期：
1. 提交成功后有工作台事件。
2. 审计事件包含用户、租户、业务 ID。
3. Admin 可基于事件处理。
### TC-KAFKA-022 配置事件失效
目标：验证 Admin 配置变更后 IM 清理进程内缓存。
事件类型：
| 事件 | 预期 |
| --- | --- |
| `tenant.updated` | 清租户缓存。 |
| `tenant.status.changed` | 清租户缓存。 |
| `tenant.limits.updated` | 清租户配置缓存。 |
| `tenant.features.updated` | 清租户功能缓存。 |
| `dictionary.updated` | 清字典/第三方配置缓存。 |
| `third_party.updated` | 清第三方配置缓存。 |
| `registration.config.updated` | 清注册短信配置缓存。 |
步骤：
1. Admin 修改配置。
2. 发送 `im.config.event`。
3. IM 再次读取对应配置。
预期：
1. IM 消费成功。
2. 下次读取不使用旧缓存。
3. 可从 Admin 内部配置接口重新获取新值。
### TC-KAFKA-023 通用缓存失效
目标：验证 `im.cache.invalidate` 可按 namespace 删除缓存。
示例事件：
```json
{
"event_id": "cache:user:001",
"tenant_code": "default",
"event_type": "cache.redis_object.invalidate",
"biz_type": "cache",
"biz_id": "user:usrxxx",
"payload": {
"tenant_code": "default",
"tenant_id": 1,
"namespace": "user",
"keys": ["usrxxx"]
}
}
```
预期：
1. 用户 Redis 对象缓存被删除。
2. 后续查询重新读 MySQL 或 Admin 内部配置接口。
3. 消费幂等。
### TC-KAFKA-024 群热消息缓存失效
目标：验证群热消息可按 Topic 或 seq range 失效。
事件：
```json
{
"event_id": "cache:group-hot:001",
"tenant_code": "default",
"event_type": "cache.group_hot_messages.invalidate",
"biz_type": "cache",
"biz_id": "grpxxx",
"payload": {
"tenant_id": 1,
"namespace": "group_hot_messages",
"topic": "grpxxx",
"ranges": [{"low": 100, "hi": 120}]
}
}
```
预期：
1. 指定群热消息范围失效。
2. 客户端再次拉取时能从最终存储补偿。
### TC-KAFKA-025 死信生成
目标：验证不可恢复错误进入死信。
步骤：
1. Admin 发送不存在用户或非法 payload 的命令。
2. 或临时制造持续失败直到超过最大重试。
3. 查询 `im_kafka_dead_letters`。
4. 消费 `im.dead.letter`。
预期：
1. 死信表出现记录。
2. 死信 Topic 有 `kafka.dead_letter.created`。
3. Admin 操作单收到 `status=dead` 的 result。
4. 死信记录包含原始 envelope、reason、error、retry_count。
### TC-KAFKA-026 死信查询
目标：验证 Admin 可通过 IM 内部 API 查询死信。
请求：
```http
GET /v1/internal/admin-query/tenants/default/kafka/dead-letters?status=dead&limit=50
GET /v1/internal/admin-query/tenants/default/kafka/dead-letters/{dead_id}
```
预期：
1. 列表返回摘要，不返回超大 envelope。
2. 详情返回原始 envelope。
3. 支持 `status/biz_type/biz_id/event_type/cursor/limit` 过滤。
### TC-KAFKA-027 死信忽略与解决
目标：验证 Admin 可通过 Kafka 命令处理死信状态。
事件类型：
```json
{
"event_type": "kafka.dead_letter.ignore",
"payload": {
"command_id": "cmd-dead-ignore-001",
"actor_user_id": "usrAdmin",
"dead_id": "evt_dead_xxx",
"note": "测试死信忽略"
}
}
```
预期：
1. `ignore` 后死信状态为 `ignored`。
2. `resolve` 后死信状态为 `resolved`。
3. Admin 收到 result。
4. 审计事件已投递。
### TC-KAFKA-028 死信重放
目标：验证死信可人工重放。
步骤：
1. 修复导致死信的业务数据或配置。
2. Admin 发送 `kafka.dead_letter.replay`。
3. 观察原 Topic 是否重新收到 envelope。
4. 查询死信记录和消费日志。
预期：
1. IM 将死信改为 `pending_replay`。
2. 删除原 `im_kafka_consume_log`。
3. 按原 `source_topic` 重投 envelope。
4. 重投成功后死信状态为 `replayed`，`replay_count` 增加。
5. 原业务消费者重新处理并成功。
### TC-KAFKA-029 审计事件
目标：确认 IM Server 对跨系统审计仍生产 `im.audit.event`，由 Admin/HotGo 消费后同步落审计表。
覆盖：
1. 群治理命令。
2. 用户治理命令。
3. 文件生命周期。
4. 工作台状态变化。
5. 死信生成和处理。
预期：
1. IM Server 生产 `im.audit.event`。
2. Kafka consumer 启动日志中没有 IM 侧审计事件 consumer。
3. Admin/HotGo 消费审计事件并同步写入审计表。
### TC-KAFKA-030 IM 侧 Kafka 生产失败
目标：验证 IM 侧 Kafka 直接生产失败时不会产生 DB outbox，调用方收到发送失败。
预期：
1. Kafka 停止时 IM 不写 `im_kafka_outbox`，消息发送返回失败。
2. 恢复后客户端可重新发送。
3. 重复发送依赖 `client_mid` 和消费日志保持幂等。
4. 不重复产生业务副作用。
## 5. Admin 侧联调检查清单
| 检查项 | 验收标准 |
| --- | --- |
| 操作单 | 每个后台写操作先写 hotgo 操作单。 |
| Admin outbox | 操作单与 outbox 同事务写入。 |
| Command 生产 | `event_id/idempotency_key/tenant_code/biz_id` 稳定可追踪。 |
| Result 消费 | `im.admin.command.result` 能更新操作单状态。 |
| 死信消费 | `im.dead.letter` 能生成告警或待处理记录。 |
| 审计 | 消费 `im.audit.event`，同步落 HotGo 审计表。 |
| 配置接口 | `/internal/im-config/*` 支持 IM HMAC 调用。 |
| 查询客户端 | 调 IM `/internal/admin-query/*` 带签名并处理 401/403/404/5xx。 |
| 页面状态 | 后台页面显示 pending/running/succeeded/failed/dead，不把 Kafka 发送成功当业务成功。 |
## 6. IM Server 侧联调检查清单
| 检查项 | 验收标准 |
| --- | --- |
| Kafka 启动 | producer、consumer 正常启动，IM 侧无 DB outbox worker。 |
| 租户路由 | `tenant_code` 能路由到正确租户库。 |
| 消费幂等 | 重复 `event_id` 不重复执行业务。 |
| 重试 | 可重试错误按退避时间重试。 |
| 死信 | 超过上限或不可重试错误进入死信并回 result。 |
| Admin Query API | 内部接口验签、鉴权、nonce 防重放生效。 |
| Admin Config Client | 可从 Admin 拉租户、注册、第三方配置。 |
| 用户治理 | 封禁/冻结踢下线，解封/恢复可登录，设备踢出只影响指定设备。 |
| 群治理 | 群资料、角色、禁言、移除、转让群主全部生效。 |
| 消息落库 | 私聊写 `im_messages`，群聊写 `im_group_messages`。 |
| 文件生命周期 | 文件记录、附件引用、群文件同步落到正确业务表。 |
| 工作台事件 | 同步生成系统通知和 WS 业务事件。 |
| 审计 | IM 生产 `im.audit.event` 给 Admin/HotGo，IM 本地不消费审计 topic。 |
## 7. 回归用例
1. Kafka 关闭时，IM 基础登录、私聊、群聊、文件上传下载仍可用。
2. Redis 异常时，Kafka 消费不应 panic；允许热缓存和 nonce 校验降级按配置表现。
3. Admin 内部配置接口不可用时，IM 本地旧 DB 读取兜底可用。
4. IM 内部查询接口关闭时，Admin 查询应收到 404，不泄露数据。
5. 同一用户在多端登录，`user.device.kick` 只踢指定设备，`user.logout_all` 踢全部设备。
6. 同一 Admin Command 重复发送 3 次，业务只成功一次，结果可重复查询。
7. 群消息高并发发送时 `seq_id` 单调递增且无重复。
8. 文件上传后未发送消息，不应产生错误附件引用。
9. 工作台事件目标用户为空时，不应产生错误通知。
10. 死信重放失败后应再次进入死信，不覆盖原处理痕迹。
## 8. 联调问题定位
| 现象 | 优先排查 |
| --- | --- |
| Admin 操作一直 pending | Admin outbox 是否成功投递；`queue.driver` 是否为 `kafka`；Kafka broker 是否可用。 |
| Admin 操作一直 running | Admin 是否消费 `im.admin.command.result`；IM 是否收到 command；`event_id` 是否重复卡在 processing。 |
| IM 消费失败 | 查 `im_kafka_consume_log.last_reason/last_error` 和 IM 日志 `event_id`。 |
| 进入死信 | 查 `im_kafka_dead_letters.envelope/last_error`，修复后用重放命令。 |
| 用户没有被踢下线 | 查目标 `user_id` 是否是 IM 用户 ID；是否连接在当前 IM 节点；跨节点踢人是否需要后续 Redis fanout 扩展。 |
| 群治理未生效 | 查 `topic/version/actor_user_id` 是否正确，目标用户是否为群成员。 |
| 消息未落库 | 私聊查 `im.message.persist`，群聊查 `im.group.message.persist` 是否消费成功，以及 `im_kafka_consume_log.last_reason/last_error`。 |
| 附件未绑定 | 查消息是否带附件，以及同步绑定逻辑是否返回错误。 |
| 内部 API 401 | 查 secret、签名文本、RequestURI、timestamp、nonce 是否一致。 |
| 配置没有刷新 | 查是否发送 `im.config.event` 或 `im.cache.invalidate`，IM 是否清理了对应 namespace。 |
## 9. 联调完成标准
1. 本文所有 P0/P1 用例通过：Kafka 基础、Admin Command、用户治理、群治理、消息异步落库、文件生命周期同步处理、工作台同步处理、缓存失效、死信。
2. Admin 操作单状态闭环可视化：pending -> running -> succeeded/failed/dead。
3. IM 租户库无重复业务记录，Kafka 消费日志无异常堆积。
4. 死信可查询、可忽略、可解决、可重放。
5. Admin 与 IM 均不跨库直连，内部查询接口鉴权通过。
6. 离线 Push Kafka 化未纳入本次验收，继续按增强项跟进。
## 10. 本地 Docker 联调记录
### 10.1 2026-08-27 冒烟联调
本轮不是全量联调，只完成本地 Docker 环境启动和 Kafka/内部接口主链路冒烟。后续仍需按第 4 章逐条补齐。
联调环境：
| 组件 | 地址/容器 | 结果 |
| --- | --- | --- |
| MySQL | `relaxed_cori:3306`，宿主机 `127.0.0.1:3306` | 已连接，本地库包含 `hotgo`、`tinode`。 |
| Redis | `brave_blackburn:6379`，宿主机 `127.0.0.1:6379` | 已连接。 |
| Kafka | `im-local-kafka:9092`，宿主机 `127.0.0.1:19092` | 已创建联调 Topic。 |
| IM Server | `im-local-im:6060`，宿主机 `127.0.0.1:6060` | healthy，Kafka consumer 已启动。 |
| Admin/HotGo | `im-local-admin:8000`，宿主机 `127.0.0.1:8000` | healthy，Kafka consumer 已启动。 |
说明：本地已有 Kafka 容器 `kafka:9092` 的 `advertised.listeners=localhost:9092`，Docker 内服务会回连自身 localhost，故本轮单独启动 `im-local-kafka` 用于容器联调。
本轮已测：
| 用例/链路 | 测试内容 | 结果 | 证据 |
| --- | --- | --- | --- |
| TC-KAFKA-001 | Kafka Topic 创建，IM consumer 启动。 | 通过 | IM 日志显示 `im.admin.command`、`im.config.event`、`im.cache.invalidate`、`im.message.persist`、`im.group.message.persist` consumer started。 |
| TC-KAFKA-002 | Admin -> IM 内部查询 HMAC。 | 通过 | `GET /internal/admin-query/tenants/default/users?page=1&per_page=1` 返回 `code=0`，`total=29`。 |
| TC-KAFKA-004 | IM -> Admin 内部配置 HMAC。 | 通过 | `GET /internal/im-config/tenants?limit=1000&state=active` 返回 `code=0` 和 default 租户。 |
| TC-KAFKA-008/011 | `user.logout_all` 后台用户治理命令。 | 通过 | `tinode.im_kafka_consume_log` 中 `local-logout-fixed-*` 状态为 `succeeded`。 |
| TC-KAFKA-023 | `im.cache.invalidate` 通用缓存失效。 | 通过 | `local-cache-*` 写入 `im_kafka_consume_log`，状态 `succeeded`，IM 日志显示 `kafka cache invalidate applied`。 |
| TC-KAFKA-025 | 非法 `user.logout_all` 进入死信。 | 通过 | `local-logout-*` 状态为 `dead`，`im_kafka_dead_letters` 写入 `MALFORMED_COMMAND`。 |
| TC-KAFKA-029 | 用户治理审计事件。 | 通过 | IM 生产 `im.audit.event`，Admin/HotGo 消费后同步落审计表。 |
本轮发现并处理：
| 问题 | 现象 | 处理 |
| --- | --- | --- |
| Admin Docker 前端构建失败 | `pnpm run build` 非 TTY 环境报 `ERR_PNPM_ABORTED_REMOVE_MODULES_DIR_NO_TTY`。 | Admin `Dockerfile` 增加 `ENV CI=true`。 |
| Admin Kafka 版本配置不兼容 | Admin 启动时报 `invalid version 2.0.0.0`。 | 本地联调配置临时改为 `version: "2.0.0"`。 |
| IM 启动缺少 UID key | IM 报 `crypto/xtea: invalid key size 0`。 | Docker 启动显式传入 `UID_ENCRYPTION_KEY`、`API_KEY_SALT`、`AUTH_TOKEN_KEY`。 |
| HotGo 表前缀不一致 | Admin 内部配置接口错误查询 `hg_im_tenant`，但 IM 业务/配置表正式表名应保持 `im_tenant`。 | 联调时暴露的是 Admin 查询/ORM 表名前缀问题；正式方案必须修 Admin 侧表名映射或 DAO 前缀逻辑，不能新增 `hg_im_*` 兼容表。 |
| Admin result 消费格式不兼容 | Admin 消费 `im.admin.command.result` 报 `IM命令结果缺少command_id`。 | Admin consumer 已兼容 Kafka Envelope + payload 格式。 |
| Admin 审计表前缀不一致 | Admin 消费 `im.audit.event` 后错误查询 `hg_im_audit_events`，正式表名应保持 `im_audit_events`。 | Admin/HotGo 同步写审计表时，仍需保证所有 `im_*` 业务表不加 `hg_` 前缀。 |
本轮未覆盖，后续继续：
| 范围 | 待测内容 |
| --- | --- |
| 群治理 | 群资料、治理配置、管理员设置/取消、成员禁言/解禁、移除成员、转让群主。 |
| 用户治理完整集 | `user.ban`、`user.unban`、`user.freeze`、`user.unfreeze`、`user.device.kick`、注销/删除账号。 |
| 消息异步落库 | 私聊 `im_messages`、群聊 `im_group_messages`、`seq_id` BIGINT、重复 `client_mid` 幂等。 |
| 文件生命周期 | 上传完成、附件绑定、群文件登记/删除、OSS 元数据和引用表。 |
| 工作台事件 | 会议、日报/月报、总经理信箱、红点/系统通知投递。 |
| 死信闭环 | 死信查询、忽略、解决、重放，以及重放后二次成功/失败。 |
| Kafka 生产失败 | Kafka 停止/恢复时，确认 IM 不写 `im_kafka_outbox`，接口/WS 返回发送失败，恢复后可重新发送。 |
| Admin 页面 | 操作单状态从 pending/running 到 succeeded/failed/dead 的页面联调。 |
### 10.2 2026-08-27 完整后端链路联调
本轮在本地 Docker 环境继续补齐 Kafka 后端链路联调。覆盖方式以 Kafka 直接投递、内部 HTTP HMAC 调用、MySQL 业务表/消费日志核验为主；Admin 前端页面点击未做浏览器人工验收，页面层需要后续按菜单再走一遍。
联调环境延续 10.1：
| 组件 | 地址/容器 | 结果 |
| --- | --- | --- |
| MySQL | `relaxed_cori:3306` | 正常。 |
| Redis | `brave_blackburn:6379` | 正常。 |
| Kafka | `im-local-kafka:9092`，宿主机 `127.0.0.1:19092` | 正常；Outbox 用例中曾停止并恢复。 |
| IM Server | `im-local-im:6060` | 已重建为包含本轮修复的 `im-local-server:dev`，当前 healthy。 |
| Admin/HotGo | `im-local-admin:8000` | 当前 healthy；Kafka 断开时曾 fatal 退出，见问题记录。 |
本轮通过项：
| 用例/范围 | 覆盖内容 | 结果 | 证据 |
| --- | --- | --- | --- |
| TC-KAFKA-003 | IM 内部查询接口未签名访问。 | 通过 | `GET /internal/admin-query/...` 未带签名返回 401 `AUTH_REQUIRED`。 |
| TC-KAFKA-004 | Admin 内部配置接口签名成功/失败。 | 通过 | 未签名返回 401；签名访问 `/internal/im-config/tenants?limit=1&state=active` 返回 default 租户。 |
| TC-KAFKA-005 | 后台群资料修改。 | 通过 | `group.profile.update` 消费 `succeeded`，`im_group_settings.name/description/version` 更新。 |
| TC-KAFKA-006 | 后台群治理配置。 | 通过 | `group.governance.update` 消费 `succeeded`，`join_approval/mute_all/member_*` 更新。 |
| TC-KAFKA-007 | 群管理员、禁言、移除、转让群主。 | 通过 | `group.admin.set/remove`、`group.member.mute/unmute/remove`、`group.owner.transfer` 均有成功消费记录；`im_group_members/im_group_mutes` 状态变更正确。 |
| TC-KAFKA-008 | 用户封禁与解封。 | 通过 | `user.ban/user.unban` 消费 `succeeded`，用户最终恢复 `state=0`。 |
| TC-KAFKA-009 | 用户冻结与恢复。 | 通过 | `user.freeze/user.unfreeze` 消费 `succeeded`，用户最终恢复 `state=0`。 |
| TC-KAFKA-010 | 踢指定设备。 | 通过 | `user.device.kick` 消费 `succeeded`，不存在设备按幂等成功处理。 |
| TC-KAFKA-011 | 全端登出。 | 通过 | `user.logout_all` 消费 `succeeded`。 |
| TC-KAFKA-012 | 注销与删除账号。 | 通过 | `user.account.cancel/user.account.delete` 使用本地测试账号验证，消费 `succeeded`。 |
| TC-KAFKA-013 | 私聊消息异步落库。 | 通过 | `message.persist.p2p` 消费 `succeeded`，`im_messages` 写入测试消息。 |
| TC-KAFKA-014 | 群聊消息异步落库。 | 通过 | `im.group.message.persist` 消费 `message.persist.group`，`im_group_messages` 写入测试群消息。 |
| TC-KAFKA-016 | 文件上传完成事件。 | 通过 | 文件上传完成不再走 Kafka。 |
| TC-KAFKA-017 | 消息附件绑定。 | 通过 | 群聊附件绑定写入 `im_group_files`；私聊附件绑定修复后写入 `im_filemsglinks`。 |
| TC-KAFKA-018 | 群文件登记与删除生命周期。 | 通过 | 群文件登记/删除同步落库。 |
| TC-KAFKA-019 | 工作台会议事件。 | 通过 | 同步写入 `im_system_notifications` 和 `im_business_events_outbox`。 |
| TC-KAFKA-022 | 配置事件失效。 | 通过 | `dictionary.updated` 消费 `succeeded`。 |
| TC-KAFKA-023 | 通用缓存失效。 | 通过 | `cache.redis_object.invalidate` 消费 `succeeded`。 |
| TC-KAFKA-024 | 群热消息缓存失效。 | 通过 | `cache.group_hot_messages.invalidate` 消费 `succeeded`。 |
| TC-KAFKA-025 | 死信生成。 | 通过 | 故意发送非法 `user.logout_all`，消费状态 `dead`，写入 `im_kafka_dead_letters`。 |
| TC-KAFKA-026 | 死信查询。 | 通过 | `/internal/admin-query/tenants/default/kafka/dead-letters` 和详情接口返回 200。 |
| TC-KAFKA-027 | 死信忽略与解决。 | 通过 | `kafka.dead_letter.ignore/resolve` 消费 `succeeded`，死信状态变为 `ignored/resolved`。 |
| TC-KAFKA-028 | 死信重放。 | 通过 | `kafka.dead_letter.replay` 消费 `succeeded`，死信状态变为 `replayed`，`replay_count=1`。 |
| TC-KAFKA-029 | 审计事件。 | 通过 | `im.audit.event` 投递给 Admin/HotGo，消费侧同步落审计表。 |
| TC-KAFKA-030 | IM Kafka Outbox 可靠投递。 | 通过 | Kafka 停止时 outbox `pending -> failed`；Kafka 恢复并重启 IM 后 `failed -> sent`，下游消费成功。 |
本轮消费统计：
| 口径 | 数量 |
| --- | ---: |
| `codex_it_*` 和本轮修复验证事件总数 | 38 |
| 成功消费 | 35 |
| 故意制造死信 | 3 |
| 修复后仍卡 processing | 0 |
代表性事件：
| 类型 | Event ID |
| --- | --- |
| 用户治理批次 | `codex_it_110224_*` |
| 群成员移除复测 | `codex_it_remove_110302_271b2ff6` |
| 私聊/群聊消息落库 | `codex_it_msg_110432_*`、`codex_it_msg_110434_*` |
| 私聊附件修复验证 | `codex_it_fix_p2p_attach_b93a9a4b` |
| 工作台事件 | `codex_it_evt_110730_workbench_meeting_created_b764faa3` |
| Outbox 断 Kafka 恢复 | `codex_it_outbox_7f52e221` |
| 死信处理 | `codex_it_dead_111524_*`、`codex_it_dead_111528_*`、`codex_it_dead_111531_*` |
本轮发现并处理：
| 问题 | 影响 | 处理结果 |
| --- | --- | --- |
| 私聊附件绑定触发 IM panic | `file.attachments.bind` 对私聊消息调用 `store.Files.LinkAttachments(tenantID, "", msgId, attachments)` 时，空 topic 进入 `types.GetTopicCat(topic)` 导致 `slice bounds out of range`，IM 退出。 | 已修复 `server/store/store.go`：仅当 `topic != ""` 时判断 `TopicCatMe`；重建 IM 后复测私聊附件绑定成功，`im_filemsglinks` 写入。 |
| Kafka 停止时 Admin 进程 fatal 退出 | Outbox 断 Kafka 用例中停止 `im-local-kafka` 后，Admin consumer 报 `client has run out of available brokers` 并 `FATA` 退出。 | 已记录为 Admin 侧待修复问题：Kafka consumer 断 broker 不应 fatal，应退避重连。 |
| Kafka 停止/恢复后 IM consumer 自动恢复不稳定 | Kafka 恢复后，IM 仍 healthy，但消费端未立即消费新探针；重启 IM 后积压事件被补偿消费。 | 已记录为 IM 侧增强/修复项：Kafka reader 断 broker 后需要自动重建 reader 并继续消费。 |
| 备用群业务快照不一致 | 对 `grpEC7ddYMoI5s` 执行 `group.member.remove` 返回 `RESOURCE_NOT_FOUND` 并进入死信。 | 换用业务表已确认成员的 `grpgvTd1mFvM2M` 后移除成功；前一次作为死信生成用例保留。 |
未做或需要人工补充：
| 范围 | 说明 |
| --- | --- |
| Admin 前端页面点击 | 本轮验证了后端接口、Kafka 生产消费和数据库状态；未使用浏览器逐个菜单点选操作单页面、死信页面、审计页面。 |
| 真实客户端 WS 在线通知 | 后台命令会生成业务事件/系统通知；本轮未启动真实 C 端 WebSocket 客户端观察 UI 实时刷新。 |
| Admin 查询迁移状态 | 本轮验证 IM Server 内部查询接口可用，但 Admin 查询侧尚未全部切换到内部查询 API，页面查询隔离需要后续迁移。 |
| 离线 Push | 按既定范围仍放在未实现增强项，本轮不验收。 |
### 10.3 2026-08-27 内部查询 API 双向联调
本轮在本地 Docker 环境重建 `im-local-server:dev` 和 `im-local-admin:dev` 后，对 Admin 查询 IM Server、IM Server 查询 Admin 两个方向做 HMAC 内部接口联调。IM Server 使用本地 MySQL `tinode`，Admin 使用本地 MySQL `hotgo`；Admin 本地联调容器为了避开队列消费者 Kafka 版本解析退出问题，临时使用 `disk` 队列驱动，不影响本节 HTTP 内部接口结论。
双向接口结果：
| 方向 | 接口/范围 | 结果 | 证据 |
| --- | --- | --- | --- |
| Admin -> IM Server | `/internal/admin-query/tenants/default/users?page=1&per_page=3` | 通过 | 返回 200，首条 `user_id=1565659909440147456`，JSON 类型为 number。 |
| Admin -> IM Server | `/internal/admin-query/tenants/default/users/{user_id}` | 通过 | 使用数据库 BIGINT 用户 ID 查询详情返回 200。 |
| Admin -> IM Server | `/internal/admin-query/tenants/default/users?user_id={user_id}` | 通过 | 使用数据库 BIGINT 用户 ID 过滤列表返回 200。 |
| Admin -> IM Server | `/internal/admin-query/tenants/default/groups/grpgvTd1mFvM2M` | 通过 | 返回 200，`owner_id=1565659909045882880`，JSON 类型为 number。 |
| Admin -> IM Server | `/internal/admin-query/tenants/default/groups/grpgvTd1mFvM2M/members` | 通过 | 返回 200，成员 `user_id/joined_by` 均为数据库 BIGINT number。 |
| Admin -> IM Server | `/internal/admin-query/tenants/default/kafka/dead-letters?limit=1` | 通过 | 返回 200。 |
| Admin -> IM Server | 未签名请求 | 通过 | 返回 401，提示 `internal signature required`。 |
| IM Server -> Admin | `/internal/im-config/tenants?limit=1&state=active` | 通过 | 返回 200，租户 `default`，业务库 `tinode`。 |
| IM Server -> Admin | `/internal/im-config/tenants/by-code/default` | 通过 | 返回 200，租户 `default`，业务库 `tinode`。 |
| IM Server -> Admin | `/internal/im-config/registration/sms` | 通过 | 返回 200，`enabled=true`。 |
| IM Server -> Admin | `/internal/im-config/third-party/oss?keys=endpoint,bucket,access_key_id` | 通过 | 返回 200，配置 map 正常返回。 |
| IM Server -> Admin | 未签名请求 | 通过 | 返回 401。 |
运行时链路也已确认：`im-local-im` 启动后持续通过 Docker 网络访问 `im-local-admin:8000/internal/im-config/tenants?limit=1000&state=active`，Admin 日志显示每 2 秒一次返回 200，说明不是只通过脚本单独打通。
本轮发现并处理：
| 问题 | 影响 | 处理结果 |
| --- | --- | --- |
| Admin `/internal/im-config/registration/sms` HTTP 200 但业务 `code=53` | IM Server 查询注册短信开关时会拿到业务失败响应。 | 已修复 Admin 控制器扫描目标，将 `g.Map` 改为 `*entity.SysConfig`，重建 Admin 后复测返回 `code=0`。 |
| Admin 本地容器入口模板缺少新增内部接口配置 | 使用默认入口脚本会覆盖完整 `config.yaml`，导致内部接口密钥配置丢失。 | 本地联调改为挂载完整临时配置并直接启动 `./hotgo`；正式镜像建议同步补齐 `config.template`。 |
| Admin 本地 Kafka 队列版本解析退出 | Admin 启动队列消费者时 `invalid version 2.0.0.0`，进程 fatal。 | 本地 HTTP 联调临时切到 `disk` 队列驱动；Kafka consumer 退避重连和版本配置仍按增强项跟进。 |
| Admin 租户表查询仍出现 `hg_im_tenant` | 默认数据库前缀 `hg_` 会污染 `im_tenant/im_tenant_config` 这类 IM 公共表查询。 | 已修复 Admin `imtenant.RegistryDB()`：自动建立/使用 `Prefix` 为空的 `imRegistry` 连接；重建 Admin 后日志确认查询 `hotgo.im_tenant`，不再访问 `hg_im_tenant`。 |
ID 口径结论：IM Server 外部聊天协议仍使用 `usr...`；Admin 内部管理/查询接口统一使用数据库 BIGINT/int64，查询返回和写命令入参不再混用 Tinode `usr...` 格式。
Reference in New Issue View Git Blame Copy Permalink