zyt/admin/TROUBLESHOOTING.md

音视频通话功能 - 故障排查指南

常见错误及解决方案

1. 导入错误：does not provide an export named 'default'

错误信息:

SyntaxError: The requested module '/admin/node_modules/.vite/deps/@tencentcloud_call-uikit-vue.js?v=xxx' does not provide an export named 'default'

原因: TUICallKit 不支持默认导入，需要使用命名导入。

解决方案:

// ❌ 错误的导入方式
import TUICallKit from '@tencentcloud/call-uikit-vue'

// ✅ 正确的导入方式
import { TUICallKit, TUICallKitServer, TUICallType } from '@tencentcloud/call-uikit-vue'

---

2. 类型错误：Property 'init' does not exist

错误信息:

Property 'init' does not exist on type 'typeof import(...)'

原因: TUICallKit 是一个组件，不是通过 init 方法初始化的。

解决方案:

// ❌ 错误的使用方式
const tuiCallKit = TUICallKit.init({ ... })

// ✅ 正确的使用方式
// 1. 在模板中使用组件
<TUICallKit class="tui-call-kit" />

// 2. 使用 TUICallKitServer 进行初始化和调用
await TUICallKitServer.init({
  userID: 'user_123',
  userSig: 'xxx',
  SDKAppID: 1400000000
})

await TUICallKitServer.call({
  userID: 'target_user',
  type: TUICallType.VIDEO_CALL
})

---

3. 获取签名失败

错误信息:

获取签名失败

可能原因:

1. 后端配置错误
2. SDKAppID 或 SecretKey 不正确
3. 网络请求失败

排查步骤:

1. 检查后端配置

# 查看 .env 文件
cat server/.env | grep TRTC

# 应该看到：
# TRTC_SDK_APP_ID=1400000000
# TRTC_SECRET_KEY=your_secret_key
# TRTC_ENABLE=true

2. 测试 API 接口

curl -X POST http://localhost/adminapi/tcm.diagnosis/getCallSignature \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"diagnosis_id": 1, "patient_id": 10001}'

3. 查看后端日志

tail -f server/runtime/log/error.log

---

4. 摄像头/麦克风权限被拒绝

错误信息:

NotAllowedError: Permission denied

解决方案:

1. 检查浏览器权限设置

   • Chrome: 地址栏左侧 → 网站设置 → 摄像头/麦克风
   • Edge: 同 Chrome
   • Safari: Safari → 偏好设置 → 网站 → 摄像头/麦克风

2. 确保使用 HTTPS 或 localhost

   ✅ https://your-domain.com
   ✅ http://localhost:5173
   ❌ http://192.168.1.100:5173
   

3. 重新授权

   • 刷新页面
   • 清除浏览器缓存
   • 重新点击"允许"

---

5. 通话无画面

可能原因:

1. 摄像头被其他应用占用
2. 摄像头驱动问题
3. 网络连接问题

排查步骤:

1. 测试摄像头

// 在浏览器控制台执行
navigator.mediaDevices.getUserMedia({ video: true, audio: true })
  .then(stream => {
    console.log('摄像头正常', stream)
    stream.getTracks().forEach(track => track.stop())
  })
  .catch(err => console.error('摄像头错误', err))

2. 检查网络连接

   • 打开浏览器开发者工具 → Network
   • 查看是否有请求失败
   • 检查 WebSocket 连接状态

3. 查看控制台错误

   • F12 打开开发者工具
   • 查看 Console 标签页
   • 查找红色错误信息

---

6. 对方无法接听

可能原因:

1. 对方未登录系统
2. 对方的 userId 不正确
3. 对方未集成 TUICallKit

解决方案:

1. 确认对方 userId

// 确保 userId 格式正确
const userId = `patient_${patientId}` // 例如: patient_10001

2. 检查对方是否在线

   • 对方需要登录系统
   • 对方需要初始化 TUICallKit
   • 对方需要监听来电事件

3. 测试环境

   • 可以在两个浏览器窗口测试
   • 使用不同的 userId 登录

---

7. 通话中断/掉线

可能原因:

1. 网络不稳定
2. 防火墙阻止
3. 服务器问题

解决方案:

1. 检查网络质量

   • 使用有线网络
   • 关闭其他占用带宽的应用
   • 测试网络延迟

2. 配置防火墙

   • 允许 UDP 端口
   • 允许 WebRTC 连接
   • 检查企业防火墙设置

3. 查看 TRTC 控制台

   • 登录腾讯云控制台
   • 查看实时监控
   • 检查用量和质量

---

8. 初始化未完成错误

错误信息:

API<getDeviceList>: init or login is not complete, this API needs to be used after init.
TUICallEngine 初始化登录未完成，需要在 init 或 login 完成后使用此 API
<ERROR_INIT_FAIL: -1201>

原因: TUICallKit 组件在初始化完成之前就被渲染了。

解决方案:

已在代码中修复，确保：

1. 初始化完成后再显示组件

// 初始化
await TUICallKitServer.init({ ... })

// 等待初始化完全完成
await new Promise(resolve => setTimeout(resolve, 500))

// 设置标志，显示组件
isInitialized.value = true

// 等待组件渲染
await new Promise(resolve => setTimeout(resolve, 300))

// 发起通话
await TUICallKitServer.call({ ... })

2. 使用条件渲染

<!-- 只在初始化完成后显示组件 -->
<TUICallKit v-if="isInitialized" class="tui-call-kit" />

3. 添加状态提示

<div v-if="!isInitialized" class="call-waiting">
  <p>{{ statusText }}</p>
  <!-- 显示：正在获取签名... → 正在初始化... → 初始化完成 -->
</div>

验证修复:

1. 点击"视频通话"按钮
2. 观察状态提示的变化
3. 等待初始化完成
4. 应该不再出现 ERROR_INIT_FAIL 错误

---

9. 编译错误

错误信息:

Module not found: Can't resolve '@tencentcloud/call-uikit-vue'

解决方案:

1. 安装依赖

cd admin
npm install @tencentcloud/call-uikit-vue

2. 清除缓存

rm -rf node_modules/.vite
npm run dev

3. 检查 package.json

{
  "dependencies": {
    "@tencentcloud/call-uikit-vue": "^2.3.2"
  }
}

---

9. 样式问题

问题: TUICallKit 组件样式不正常

解决方案:

1. 导入样式文件

// 在 main.ts 中添加
import '@tencentcloud/call-uikit-vue/dist/style.css'

2. 设置容器尺寸

<TUICallKit style="width: 650px; height: 500px;" />

3. 检查 CSS 冲突
   • 使用浏览器开发者工具检查元素
   • 查看是否有样式被覆盖
   • 调整 z-index

---

10. 性能问题

问题: 通话卡顿、延迟高

解决方案:

1. 优化视频参数

await TUICallKitServer.call({
  userID: 'target_user',
  type: TUICallType.VIDEO_CALL,
  // 可以添加更多配置
})

2. 降低视频质量

   • 使用语音通话替代视频通话
   • 降低视频分辨率
   • 降低帧率

3. 优化网络

   • 使用有线网络
   • 关闭其他应用
   • 选择就近的服务器

---

调试技巧

1. 启用详细日志

// 在初始化前设置
TUICallKitServer.setLogLevel(0) // 0-详细 1-普通 2-警告 3-错误

2. 监听所有事件

// 监听通话开始
TUICallKitServer.on('onCallBegin', () => {
  console.log('通话开始')
})

// 监听通话结束
TUICallKitServer.on('onCallEnd', () => {
  console.log('通话结束')
})

// 监听错误
TUICallKitServer.on('onError', (error) => {
  console.error('通话错误', error)
})

3. 使用浏览器开发者工具

1. 打开开发者工具 (F12)
2. 查看 Console 标签页
3. 查看 Network 标签页
4. 查看 Application → Local Storage

4. 查看后端日志

# 实时查看错误日志
tail -f server/runtime/log/error.log

# 查看最近的日志
tail -n 100 server/runtime/log/error.log

---

联系支持

如果以上方法都无法解决问题，请提供以下信息：

1. 错误截图或日志
2. 浏览器版本和操作系统
3. 操作步骤
4. 配置信息（脱敏后）
5. 网络环境

联系方式：

• 技术支持邮箱: support@example.com
• 腾讯云工单: https://console.cloud.tencent.com/workorder

---

参考资料

• TUICallKit 官方文档
• TRTC 常见问题
• WebRTC 调试指南