新增功能

2026-03-04 15:32:30 +08:00
parent a07e844c47
commit ab77f5488d
2266 changed files with 177942 additions and 3444 deletions
@@ -0,0 +1,324 @@
+# 诊断TUICallKit初始化失败问题
+
+## 当前错误
+
+```
+ERROR_INIT_FAIL: -1201
+API<getDeviceList>: init or login is not complete
+TUICallEngine 初始化登录未完成，需要在 init 或 login 完成后使用此 API
+```
+
+## 可能的原因
+
+### 1. UserSig无效（最可能）⭐
+
+**症状**：
+- init方法调用成功，但实际登录失败
+- 等待再久也没用
+- 控制台可能有IM登录失败的错误
+
+**原因**：
+- SDKAppID不正确（使用了TRTC的而非IM的）
+- SecretKey不正确
+- UserSig生成算法有误
+- IM服务未开通
+
+**解决方案**：运行测试脚本验证
+
+```bash
+cd server
+php test_usersig.php
+```
+
+### 2. SDKAppID类型错误
+
+**症状**：
+- 报错提示SDKAppID必须是Number
+
+**原因**：
+- 传递的是字符串而非数字
+
+**解决方案**：已修复，使用 `Number(res.sdkAppId)`
+
+### 3. 网络连接问题
+
+**症状**：
+- 长时间无响应
+- 控制台有网络错误
+
+**原因**：
+- 无法连接到腾讯云服务器
+- 防火墙阻止连接
+- HTTPS证书问题
+
+**解决方案**：
+- 检查网络连接
+- 使用HTTPS或localhost
+- 检查浏览器控制台的网络错误
+
+### 4. 等待时间不够
+
+**症状**：
+- 偶尔成功，偶尔失败
+
+**原因**：
+- 初始化需要时间，等待不够
+
+**解决方案**：已修复，等待4秒
+
+## 诊断步骤
+
+### 步骤1：验证配置是否正确
+
+运行测试脚本：
+
+```bash
+cd server
+php test_usersig.php
+```
+
+**预期输出**：
+```
+=== 腾讯云IM UserSig测试 ===
+
+SDKAppID: 1600127710
+SecretKey长度: 64
+SecretKey前10位: 8a6b3ce533...
+
+✅ UserSig生成成功！
+✅ UserSig验证成功！
+✅ IM账号导入成功！
+```
+
+**如果失败**：
+- 检查 `server/.env` 中的配置
+- 确认SDKAppID是IM应用的，不是TRTC应用的
+- 确认SecretKey正确
+
+### 步骤2：检查浏览器控制台
+
+打开浏览器开发者工具（F12），查看：
+
+#### Console标签
+
+查找以下错误：
+
+```javascript
+// ❌ UserSig错误
+Error: login failed, error code: 70003
+Error: UserSig is invalid
+
+// ❌ SDKAppID错误
+Error: SDKAppID must be Number
+
+// ❌ 网络错误
+Error: Failed to fetch
+Error: Network error
+```
+
+#### Network标签
+
+查找请求到 `tim.qq.com` 或 `trtc.io` 的请求：
+
+- 如果没有请求：网络被阻止
+- 如果请求失败：检查错误信息
+- 如果请求成功但返回错误：检查响应内容
+
+### 步骤3：检查IM登录状态
+
+在浏览器控制台执行：
+
+```javascript
+// 检查TUICallKit状态
+console.log('TUICallKit:', TUICallKitServer)
+
+// 尝试获取登录状态（如果有这个API）
+// 注意：这可能会报错，但能帮助诊断
+try {
+    const status = await TUICallKitServer.getLoginStatus()
+    console.log('登录状态:', status)
+} catch (e) {
+    console.error('获取状态失败:', e)
+}
+```
+
+### 步骤4：使用腾讯云官方工具验证
+
+访问：https://console.cloud.tencent.com/im/tool-usersig
+
+1. 输入SDKAppID
+2. 输入SecretKey
+3. 输入UserID（如：doctor_1）
+4. 点击"生成UserSig"
+
+**如果生成失败**：
+- SDKAppID或SecretKey错误
+- 需要在腾讯云控制台确认正确的值
+
+**如果生成成功**：
+- 复制生成的UserSig
+- 在浏览器控制台手动测试：
+
+```javascript
+await TUICallKitServer.init({
+    userID: 'doctor_1',
+    userSig: '从官方工具复制的UserSig',
+    SDKAppID: 1600127710
+})
+```
+
+如果这样能成功，说明后端生成的UserSig有问题。
+
+## 常见问题和解决方案
+
+### 问题1：ErrorCode 70003 - UserSig非法
+
+**原因**：
+- SDKAppID是TRTC的，不是IM的
+- SecretKey不匹配
+
+**解决**：
+1. 登录腾讯云控制台
+2. 进入：即时通信IM > 应用列表
+3. 确认SDKAppID（不是TRTC的）
+4. 进入应用详情 > 密钥管理
+5. 复制正确的SecretKey
+6. 更新 `server/.env`：
+
+```ini
+[TRTC]
+SDK_APP_ID = "正确的IM应用SDKAppID"
+SECRET_KEY = "正确的SecretKey"
+ENABLE = "true"
+```
+
+### 问题2：一直等待，没有任何错误
+
+**原因**：
+- 网络连接问题
+- 防火墙阻止
+
+**解决**：
+1. 检查是否使用HTTPS或localhost
+2. 检查浏览器控制台的Network标签
+3. 尝试禁用防火墙/代理
+
+### 问题3：偶尔成功，偶尔失败
+
+**原因**：
+- 等待时间不够
+- 网络不稳定
+
+**解决**：
+1. 增加等待时间到6秒
+2. 检查网络稳定性
+
+### 问题4：前端报错但后端测试成功
+
+**原因**：
+- 前端传递的参数有误
+- 类型转换问题
+
+**解决**：
+1. 检查前端传递的参数：
+
+```javascript
+console.log('传递给init的参数:', {
+    userID: res.userId,
+    userSig: res.userSig,
+    SDKAppID: Number(res.sdkAppId),
+    types: {
+        userID: typeof res.userId,
+        userSig: typeof res.userSig,
+        SDKAppID: typeof Number(res.sdkAppId)
+    }
+})
+```
+
+2. 确保所有参数正确：
+   - userID: 字符串，如 "doctor_1"
+   - userSig: 字符串，长度约200-300
+   - SDKAppID: 数字，如 1600127710
+
+## 临时解决方案
+
+如果无法立即解决，可以尝试：
+
+### 方案A：增加等待时间
+
+```typescript
+// 增加到6秒或更长
+await new Promise(resolve => setTimeout(resolve, 6000))
+```
+
+### 方案B：添加重试机制
+
+```typescript
+async function initWithRetry(maxRetries = 3) {
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            await TUICallKitServer.init({ ... })
+            await new Promise(resolve => setTimeout(resolve, 4000))
+            
+            // 尝试调用一个API验证是否初始化成功
+            await TUICallKitServer.call({ ... })
+            return true
+        } catch (e) {
+            console.log(`第${i + 1}次尝试失败:`, e)
+            if (i === maxRetries - 1) throw e
+            await new Promise(resolve => setTimeout(resolve, 2000))
+        }
+    }
+}
+```
+
+### 方案C：使用官方示例代码
+
+参考腾讯云官方文档的示例代码，确保实现方式正确。
+
+## 下一步行动
+
+### 立即执行
+
+1. ✅ 运行 `php server/test_usersig.php`
+2. ✅ 检查浏览器控制台错误
+3. ✅ 使用腾讯云官方工具验证UserSig
+
+### 如果测试脚本失败
+
+说明配置有问题，需要：
+1. 确认SDKAppID和SecretKey
+2. 更新 `server/.env`
+3. 重新测试
+
+### 如果测试脚本成功但前端失败
+
+说明前端传递参数有问题，需要：
+1. 检查前端传递的参数
+2. 添加详细的日志
+3. 对比后端生成的UserSig和前端收到的UserSig
+
+### 如果都成功但仍然失败
+
+可能是网络或浏览器问题，需要：
+1. 尝试不同的浏览器
+2. 检查网络连接
+3. 尝试使用HTTPS
+
+## 联系支持
+
+如果以上方法都无法解决，可以：
+
+1. 查看腾讯云IM控制台的日志
+2. 联系腾讯云技术支持
+3. 在腾讯云开发者社区提问
+
+提供以下信息：
+- SDKAppID
+- 错误信息截图
+- 浏览器控制台日志
+- 测试脚本输出
+
+---
+
+**关键要点**：先运行 `php server/test_usersig.php` 验证配置是否正确！🔍