feat: add agora rtc token join endpoint

2026-09-02 01:05:15 +08:00
parent 318ce04f7d
commit dc5e09f2ae
9 changed files with 624 additions and 11 deletions
@@ -2068,9 +2068,12 @@ X-MeetingIM-APIKey: <预置的普通 API Key>
 | --- | --- | --- |
 | WebSocket 发起通话 | `{"pub":{"id":"call-1","topic":"p2p...","head":{"mime":"application/json","webrtc":"started","x-im-type":"call"},"content":{"callId":"call_1","callType":"audio","audio":true,"video":false}}}` | `{"ctrl":{"id":"call-1","code":202,"params":{"seq":12}}}` |
 | WebSocket 通话事件 | `{"note":{"topic":"p2p...","what":"call","event":"accept","seq":12,"payload":{"callId":"call_1"}}}` | 对端收到 `{"info":{"topic":"p2p...","what":"call","event":"accept","seq":12,"payload":{"callId":"call_1"}}}` |
+| `POST /v1/im/calls/rtc-join` | `{"topic":"p2p...","call_id":"call_1","seq":12,"call_type":"audio","role":"caller"}` | `{"provider":"agora","auth_mode":"token","app_id":"声网 App ID","channel_name":"call_call_1","uid":"usr...","token":"007eJx...","token_expires_at":"2026-09-02T10:00:00Z","call_id":"call_1","topic":"p2p...","seq":12,"call_type":"audio","role":"caller"}` |
 | `GET /v1/im/calls?limit=20&cursor=` | Query only | `{"items":[{"call_id":"call_1","topic":"p2p...","seq":12,"call_type":"audio","status":"finished","started_at":"2026-08-20T09:00:00Z","duration_ms":60000,"peer":{"user_id":"usr...","display_name":"张三"}}],"next_cursor":""}` |
 | `GET /v1/im/calls/{topic}?cursor=` | Path topic | `{"topic":"p2p...","items":[{"call_id":"call_1","seq":12,"status":"missed","call_type":"video","created_at":"2026-08-20T09:00:00Z"}],"next_cursor":""}` |

+声网模式下，新客户端在发起方收到 `ctrl.params.seq` 后、被叫方点击接听后，分别调用 `POST /v1/im/calls/rtc-join` 获取 `app_id/channel_name/uid/token`。当前按正式 `token` 模式接入，后端使用 `im_shengwang` 分组中的 `agora_app_certificate` 生成 RTC Token。客户端不接触 `app_certificate`、`customer_id`、`customer_secret`，也不再通过 IM WebSocket 交换 SDP/ICE，音视频媒体协商和传输由声网 RTC SDK 完成。
+
 ## 9. 企业工作台与办公协同

 ### 9.1 工作台.png
@@ -33,10 +33,10 @@
 | 配置项 | 示例 | 说明 |
 | --- | --- | --- |
 | `agora_enabled` | `true` | 是否启用声网音视频。 |
-| `agora_auth_mode` | `app_id` | 调试模式，客户端入会不需要 Token。 |
+| `agora_auth_mode` | `token` | 正式模式，服务端生成 RTC Token。 |
 | `agora_app_id` | `xxxxxxxx` | 声网项目 App ID，允许返回给客户端。 |
 | `agora_channel_prefix` | `call_` | 服务端生成声网频道名前缀。 |
-| `agora_uid_mode` | `int` | 首期建议使用数字 UID。 |
+| `agora_uid_mode` | `string` | 建议使用 `usr...` 作为声网 user account，避免 BIGINT 用户 ID 超过声网数字 UID 范围。 |

 ### 3.2 正式模式

@@ -306,13 +306,12 @@ Content-Type: application/json

 ## 10. 联调顺序建议

-1. 后台配置 `agora_enabled=true`、`agora_auth_mode=app_id`、`agora_app_id`。
-2. 客户端集成声网 RTC SDK，并支持后端返回的空 Token 入会。
+1. 后台配置 `agora_enabled=true`、`agora_auth_mode=token`、`agora_app_id`、`agora_app_certificate`。
+2. 客户端集成声网 RTC SDK，并使用后端返回的 RTC Token 入会。
 3. A 发起语音通话，确认 B 能收到 IM 来电信令。
 4. A、B 分别调用 `/v1/im/calls/rtc-join`，确认返回同一个 `channel_name`。
 5. A、B 使用各自 `uid` 加入声网频道，确认音频可通。
 6. 切换视频通话，确认视频流可通。
 7. 测试取消、拒接、挂断、超时、网络断开。
-8. 正式环境启用 App 证书，切换 `agora_auth_mode=token`。
-9. 验证 Token 入会和 Token 续期。
-10. 后续再接入声网控制台 REST API 的项目管理能力。
+8. 验证 Token 入会和 Token 续期。
+9. 后续再接入声网控制台 REST API 的项目管理能力。
@@ -25,9 +25,9 @@
 | 配置 | 说明 |
 | --- | --- |
 | `agora_app_id` | 声网项目 App ID，客户端初始化 RTC SDK 使用。 |
-| `agora_auth_mode` | 首期填 `app_id`，表示仅 App ID 鉴权。 |
+| `agora_auth_mode` | 当前建议填 `token`，由服务端生成 RTC Token。 |
 | `agora_enabled` | 是否启用声网通话，建议测试环境先设为 `true`。 |
-| `agora_uid_mode` | 建议先用 `int`，客户端加入频道时使用数字 UID。 |
+| `agora_uid_mode` | 建议用 `string`，客户端加入频道时使用 `usr...` 作为声网 user account，避免 BIGINT 用户 ID 超过声网数字 UID 范围。 |
 | `agora_channel_prefix` | 建议 `call_`，最终频道名为 `call_{call_id}`。 |

 ### 3.2 正式模式后续准备
@@ -41,7 +41,7 @@
 | `agora_rest_primary_domain` | 国内建议 `https://api.sd-rtn.com`。 |
 | `agora_rest_backup_domain` | 备用建议 `https://api.agora.io`。 |

-配置建议继续存放在 HotGo `hg_sys_config` 的 `im_third_party` 分组，IM Server 通过现有 `store.ThirdPartyConfig.Get("im_third_party", ...)` 读取，并受 Kafka `third_party.updated` 或 `cache.third_party.invalidate` 事件清理进程内缓存。
+配置建议存放在 HotGo `hg_sys_config` 的 `im_shengwang` 分组，IM Server 通过 `store.ThirdPartyConfig.Get("im_shengwang", ...)` 读取，并受 Kafka `third_party.updated` 或 `cache.third_party.invalidate` 事件清理进程内缓存。

 ## 4. 后端与声网 API 对接

@@ -286,7 +286,7 @@ Content-Type: application/json

 | 编号 | 场景 | 预期 |
 | --- | --- | --- |
-| AGORA-01 | 后台只配置 `agora_app_id` 和 `agora_auth_mode=app_id` | `/v1/im/calls/rtc-join` 返回 App ID、频道名、UID，Token 为空。 |
+| AGORA-01 | 后台配置 `agora_app_id`、`agora_app_certificate` 和 `agora_auth_mode=token` | `/v1/im/calls/rtc-join` 返回 App ID、频道名、UID 和 RTC Token。 |
 | AGORA-02 | A 发起语音通话，B 接听 | 双方使用同一 `channel_name` 加入声网频道，IM 通话状态变为 `accepted`。 |
 | AGORA-03 | A 发起视频通话，B 接听 | 双方可看到/听到媒体流，IM 通话记录为 `video`。 |
 | AGORA-04 | B 拒接 | IM 替换原通话消息为 `declined`，双方退出声网频道。 |
@@ -33,6 +33,21 @@ INSERT INTO hg_sys_dict_type
 SELECT 0, 'IM 文件审核状态', 'im_file_review_status', 240, 'IM 文件审核任务状态字典', 1, NOW(), NOW()
 WHERE NOT EXISTS (SELECT 1 FROM hg_sys_dict_type WHERE `type` = 'im_file_review_status');

+INSERT INTO hg_sys_dict_type
+    (`pid`, `name`, `type`, `sort`, `remark`, `status`, `created_at`, `updated_at`)
+SELECT 0, 'IM RTC 服务商', 'im_rtc_provider', 250, 'IM 音视频通话 RTC provider 字典', 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_dict_type WHERE `type` = 'im_rtc_provider');
+
+INSERT INTO hg_sys_dict_type
+    (`pid`, `name`, `type`, `sort`, `remark`, `status`, `created_at`, `updated_at`)
+SELECT 0, 'IM RTC 鉴权模式', 'im_rtc_auth_mode', 260, 'IM 音视频通话 RTC 鉴权模式字典', 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_dict_type WHERE `type` = 'im_rtc_auth_mode');
+
+INSERT INTO hg_sys_dict_type
+    (`pid`, `name`, `type`, `sort`, `remark`, `status`, `created_at`, `updated_at`)
+SELECT 0, 'IM RTC UID 模式', 'im_rtc_uid_mode', 270, 'IM 音视频通话 RTC UID 模式字典', 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_dict_type WHERE `type` = 'im_rtc_uid_mode');
+
 -- 2. 后台字典数据
 INSERT INTO hg_sys_dict_data
    (`label`, `value`, `value_type`, `type`, `list_class`, `is_default`, `sort`, `remark`, `status`, `created_at`, `updated_at`)
@@ -84,6 +99,31 @@ INSERT INTO hg_sys_dict_data
 SELECT '失败', 'failed', 'string', 'im_file_review_status', 'warning', 1, 50, '不可重试失败或超过重试次数', 1, NOW(), NOW()
 WHERE NOT EXISTS (SELECT 1 FROM hg_sys_dict_data WHERE `type` = 'im_file_review_status' AND `value` = 'failed');

+INSERT INTO hg_sys_dict_data
+    (`label`, `value`, `value_type`, `type`, `list_class`, `is_default`, `sort`, `remark`, `status`, `created_at`, `updated_at`)
+SELECT '声网 RTC', 'agora', 'string', 'im_rtc_provider', 'success', 1, 10, '声网实时音视频 RTC', 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_dict_data WHERE `type` = 'im_rtc_provider' AND `value` = 'agora');
+
+INSERT INTO hg_sys_dict_data
+    (`label`, `value`, `value_type`, `type`, `list_class`, `is_default`, `sort`, `remark`, `status`, `created_at`, `updated_at`)
+SELECT '仅 App ID', 'app_id', 'string', 'im_rtc_auth_mode', 'warning', 1, 10, '调试模式，客户端入会 Token 为空', 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_dict_data WHERE `type` = 'im_rtc_auth_mode' AND `value` = 'app_id');
+
+INSERT INTO hg_sys_dict_data
+    (`label`, `value`, `value_type`, `type`, `list_class`, `is_default`, `sort`, `remark`, `status`, `created_at`, `updated_at`)
+SELECT 'RTC Token', 'token', 'string', 'im_rtc_auth_mode', 'success', 0, 20, '正式模式，后端使用 App Certificate 生成 Token', 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_dict_data WHERE `type` = 'im_rtc_auth_mode' AND `value` = 'token');
+
+INSERT INTO hg_sys_dict_data
+    (`label`, `value`, `value_type`, `type`, `list_class`, `is_default`, `sort`, `remark`, `status`, `created_at`, `updated_at`)
+SELECT '数字 UID', 'int', 'string', 'im_rtc_uid_mode', 'success', 1, 10, '客户端使用数字 UID 加入 RTC 频道', 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_dict_data WHERE `type` = 'im_rtc_uid_mode' AND `value` = 'int');
+
+INSERT INTO hg_sys_dict_data
+    (`label`, `value`, `value_type`, `type`, `list_class`, `is_default`, `sort`, `remark`, `status`, `created_at`, `updated_at`)
+SELECT '字符串 UID', 'string', 'string', 'im_rtc_uid_mode', 'info', 0, 20, '客户端使用字符串 UID 加入 RTC 频道', 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_dict_data WHERE `type` = 'im_rtc_uid_mode' AND `value` = 'string');
+
 -- 3. 第三方配置项。配置真值存 hg_sys_config；字典只提供 UI 选项。
 INSERT INTO hg_sys_config
    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
@@ -175,6 +215,66 @@ INSERT INTO hg_sys_config
 SELECT 'im_third_party', '阿里云 AccessKey Secret', 'string', 'aliyun_access_key_secret', '', '', 91, '内容安全和恶意文件检测共用的敏感配置，后台和日志必须脱敏展示', 1, 1, NOW(), NOW()
 WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_third_party' AND `key` = 'aliyun_access_key_secret');

+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_shengwang', '声网启用状态', 'bool', 'agora_enabled', '0', '0', 100, '是否启用声网 RTC 音视频通话', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_shengwang' AND `key` = 'agora_enabled');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_shengwang', 'RTC 服务商', 'string', 'agora_provider', 'agora', 'agora', 101, '取值来自字典 im_rtc_provider，当前支持 agora', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_shengwang' AND `key` = 'agora_provider');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_shengwang', '声网鉴权模式', 'string', 'agora_auth_mode', 'token', 'token', 102, '取值来自字典 im_rtc_auth_mode；调试 app_id，正式 token', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_shengwang' AND `key` = 'agora_auth_mode');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_shengwang', '声网 App ID', 'string', 'agora_app_id', '', '', 103, '声网项目 App ID，可返回客户端', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_shengwang' AND `key` = 'agora_app_id');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_shengwang', '声网 App Certificate', 'string', 'agora_app_certificate', '', '', 104, '敏感配置，仅后端生成 RTC Token 使用，禁止下发客户端', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_shengwang' AND `key` = 'agora_app_certificate');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_shengwang', '声网 Token TTL', 'int', 'agora_token_ttl_seconds', '3600', '3600', 105, 'RTC Token 有效秒数，正式 token 模式使用', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_shengwang' AND `key` = 'agora_token_ttl_seconds');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_shengwang', '声网频道名前缀', 'string', 'agora_channel_prefix', 'call_', 'call_', 106, '服务端生成频道名时使用，最终为 prefix + call_id', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_shengwang' AND `key` = 'agora_channel_prefix');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_shengwang', '声网 UID 模式', 'string', 'agora_uid_mode', 'string', 'string', 107, '取值来自字典 im_rtc_uid_mode；BIGINT 用户 ID 建议 string', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_shengwang' AND `key` = 'agora_uid_mode');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_shengwang', '声网 REST Customer ID', 'string', 'agora_rest_customer_id', '', '', 108, '声网控制台 REST API 客户 ID，禁止下发客户端', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_shengwang' AND `key` = 'agora_rest_customer_id');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_shengwang', '声网 REST Customer Secret', 'string', 'agora_rest_customer_secret', '', '', 109, '声网控制台 REST API 客户密钥，必须脱敏展示', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_shengwang' AND `key` = 'agora_rest_customer_secret');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_shengwang', '声网 REST 主域名', 'string', 'agora_rest_primary_domain', 'https://api.sd-rtn.com', 'https://api.sd-rtn.com', 110, '国内控制台 REST API 主域名', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_shengwang' AND `key` = 'agora_rest_primary_domain');
+
+INSERT INTO hg_sys_config
+    (`group`, `name`, `type`, `key`, `value`, `default_value`, `sort`, `tip`, `is_default`, `status`, `created_at`, `updated_at`)
+SELECT 'im_shengwang', '声网 REST 备用域名', 'string', 'agora_rest_backup_domain', 'https://api.agora.io', 'https://api.agora.io', 111, '控制台 REST API 备用域名', 1, 1, NOW(), NOW()
+WHERE NOT EXISTS (SELECT 1 FROM hg_sys_config WHERE `group` = 'im_shengwang' AND `key` = 'agora_rest_backup_domain');
+
 USE tinode;

 -- 4. 文件安全审核任务表