ZYT/zyt
2
0
Fork 0
Code Issues Actions Packages Projects Releases Wiki Activity

更新

Browse Source
This commit is contained in:
Your Name
2026-03-13 14:08:52 +08:00
parent 08dd9cd307
commit eb283f008b
667 changed files with 8425 additions and 27053 deletions
Download Patch File Download Diff File Expand all files Collapse all files
admin/TROUBLESHOOTING.md
+210 -356
View File
@@ -1,415 +1,269 @@
# 音视频通话功能 - 故障排查指南
# 故障排查指南
## 常见错误及解决方案
## 问题 1: 页面打不开或显示空白
### 1. 导入错误：does not provide an export named 'default'
### 症状
- 页面完全空白
- 控制台有 JavaScript 错误
- 应用无法加载
**错误信息**:
```
SyntaxError: The requested module '/admin/node_modules/.vite/deps/@tencentcloud_call-uikit-vue.js?v=xxx' does not provide an export named 'default'
```
### 排查步骤
**原因**: TUICallKit 不支持默认导入，需要使用命名导入。
**解决方案**:
```typescript
// ❌ 错误的导入方式
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` 方法初始化的。
**解决方案**:
```typescript
// ❌ 错误的使用方式
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. 检查后端配置
```bash
# 查看 .env 文件
cat server/.env | grep TRTC
# 应该看到：
# TRTC_SDK_APP_ID=1400000000
# TRTC_SECRET_KEY=your_secret_key
# TRTC_ENABLE=true
```
2. 测试 API 接口
```bash
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. 查看后端日志
```bash
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. 测试摄像头
```javascript
// 在浏览器控制台执行
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 打开开发者工具
1. **检查浏览器控制台**
- 打开 F12 开发者工具
- 查看 Console 标签页
- 查找红色错误信息
- 记录所有错误信息
---
2. **检查网络请求**
- 打开 Network 标签页
- 刷新页面
- 查看是否有 404 或 500 错误
- 检查 index.html 是否正确加载
### 6. 对方无法接听
3. **检查服务器日志**
```bash
# Nginx 错误日志
sudo tail -f /var/log/nginx/error.log
# 应用日志
tail -f /path/to/your/app.log
```
**可能原因**:
1. 对方未登录系统
2. 对方的 userId 不正确
3. 对方未集成 TUICallKit
4. **清除浏览器缓存**
- Ctrl+Shift+Delete (Windows) 或 Cmd+Shift+Delete (Mac)
- 选择"所有时间"
- 清除缓存和 Cookie
**解决方案**:
## 问题 2: TUIKit 相关错误
1. 确认对方 userId
```typescript
// 确保 userId 格式正确
const userId = `patient_${patientId}` // 例如: patient_10001
### 症状
```
Uncaught ReferenceError: Cannot access 't' before initialization
TypeError: Cannot read properties of null (reading 'getTRTCCloudInstance')
```
2. 检查对方是否在线
- 对方需要登录系统
- 对方需要初始化 TUICallKit
- 对方需要监听来电事件
### 原因
- TUIKit 库在初始化时出现问题
- WebRTC 环境不支持（HTTP 协议）
- 浏览器不支持 WebRTC
3. 测试环境
- 可以在两个浏览器窗口测试
- 使用不同的 userId 登录
### 解决方案
---
1. **确保使用 HTTPS**
```bash
# 检查当前协议
# 地址栏应该显示 https://
```
### 7. 通话中断/掉线
2. **检查浏览器兼容性**
- Chrome 60+
- Firefox 55+
- Safari 11+
- Edge 79+
**可能原因**:
1. 网络不稳定
2. 防火墙阻止
3. 服务器问题
3. **检查浏览器权限**
- 允许访问摄像头
- 允许访问麦克风
- 允许访问屏幕共享
**解决方案**:
4. **查看控制台日志**
```javascript
// 在浏览器控制台输入
console.log('[TUIKit] Status:', window.__TUIKIT_INITIALIZED__)
```
1. 检查网络质量
- 使用有线网络
- 关闭其他占用带宽的应用
- 测试网络延迟
## 问题 3: 视频通话无法连接
2. 配置防火墙
- 允许 UDP 端口
- 允许 WebRTC 连接
- 检查企业防火墙设置
### 症状
- 无法发起通话
- 无法接收通话
- 视频/音频无法传输
3. 查看 TRTC 控制台
- 登录腾讯云控制台
- 查看实时监控
- 检查用量和质量
### 排查步骤
---
1. **检查网络连接**
```bash
# 测试网络延迟
ping api.zzzhengyangtang.cn
# 测试 DNS 解析
nslookup api.zzzhengyangtang.cn
```
### 8. 初始化未完成错误
2. **检查防火墙**
```bash
# 检查 443 端口是否开放
sudo netstat -tlnp | grep 443
# 检查 UDP 端口（WebRTC 使用）
sudo ufw status
```
**错误信息**:
```
API<getDeviceList>: init or login is not complete, this API needs to be used after init.
TUICallEngine 初始化登录未完成，需要在 init 或 login 完成后使用此 API
<ERROR_INIT_FAIL: -1201>
```
3. **检查后端 API**
```bash
# 测试 API 连接
curl -I https://api.zzzhengyangtang.cn/api/health
# 检查签名获取
curl https://api.zzzhengyangtang.cn/api/tcm.diagnosis/getDoctorSignature
```
**原因**: TUICallKit 组件在初始化完成之前就被渲染了。
4. **查看浏览器控制台**
- 检查 TUICallKitAPI 初始化日志
- 查看网络请求状态
- 记录错误信息
**解决方案**:
## 问题 4: 性能问题
已在代码中修复，确保：
### 症状
- 页面加载缓慢
- 通话卡顿
- 内存占用过高
1. 初始化完成后再显示组件
```typescript
// 初始化
await TUICallKitServer.init({ ... })
### 优化方案
// 等待初始化完全完成
await new Promise(resolve => setTimeout(resolve, 500))
1. **启用 Gzip 压缩**
```nginx
# 在 Nginx 配置中添加
gzip on;
gzip_types text/plain text/css text/javascript application/javascript;
gzip_min_length 1000;
```
// 设置标志，显示组件
isInitialized.value = true
2. **启用浏览器缓存**
```nginx
# 在 Nginx 配置中添加
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
expires 1y;
add_header Cache-Control "public, immutable";
}
```
// 等待组件渲染
await new Promise(resolve => setTimeout(resolve, 300))
3. **使用 CDN**
- 将静态资源上传到 CDN
- 修改 vite.config.ts 中的 base 路径
// 发起通话
await TUICallKitServer.call({ ... })
```
4. **监控性能**
```javascript
// 在浏览器控制台查看性能指标
performance.getEntriesByType('navigation')[0]
```
2. 使用条件渲染
```vue
<!-- 只在初始化完成后显示组件 -->
<TUICallKit v-if="isInitialized" class="tui-call-kit" />
```
## 问题 5: SSL 证书问题
3. 添加状态提示
```vue
<div v-if="!isInitialized" class="call-waiting">
<p>{{ statusText }}</p>
<!-- 显示：正在获取签名... → 正在初始化... → 初始化完成 -->
</div>
```
### 症状
- 浏览器显示"不安全"警告
- 证书过期
- 证书不匹配
**验证修复**:
1. 点击"视频通话"按钮
2. 观察状态提示的变化
3. 等待初始化完成
4. 应该不再出现 ERROR_INIT_FAIL 错误
### 解决方案
---
1. **检查证书状态**
```bash
# 查看证书信息
sudo certbot certificates
# 检查证书有效期
openssl x509 -in /etc/letsencrypt/live/api.zzzhengyangtang.cn/fullchain.pem -noout -dates
```
### 9. 编译错误
2. **手动续期**
```bash
# 续期证书
sudo certbot renew
# 强制续期
sudo certbot renew --force-renewal
```
**错误信息**:
```
Module not found: Can't resolve '@tencentcloud/call-uikit-vue'
```
**解决方案**:
1. 安装依赖
```bash
cd admin
npm install @tencentcloud/call-uikit-vue
```
2. 清除缓存
```bash
rm -rf node_modules/.vite
npm run dev
```
3. 检查 package.json
```json
{
"dependencies": {
"@tencentcloud/call-uikit-vue": "^2.3.2"
}
}
```
---
### 9. 样式问题
**问题**: TUICallKit 组件样式不正常
**解决方案**:
1. 导入样式文件
```typescript
// 在 main.ts 中添加
import '@tencentcloud/call-uikit-vue/dist/style.css'
```
2. 设置容器尺寸
```vue
<TUICallKit style="width: 650px; height: 500px;" />
```
3. 检查 CSS 冲突
- 使用浏览器开发者工具检查元素
- 查看是否有样式被覆盖
- 调整 z-index
---
### 10. 性能问题
**问题**: 通话卡顿、延迟高
**解决方案**:
1. 优化视频参数
```typescript
await TUICallKitServer.call({
userID: 'target_user',
type: TUICallType.VIDEO_CALL,
// 可以添加更多配置
})
```
2. 降低视频质量
- 使用语音通话替代视频通话
- 降低视频分辨率
- 降低帧率
3. 优化网络
- 使用有线网络
- 关闭其他应用
- 选择就近的服务器
---
3. **重启 Nginx**
```bash
sudo systemctl restart nginx
```
## 调试技巧
### 1. 启用详细日志
在 main.ts 中添加：
```typescript
// 在初始化前设置
TUICallKitServer.setLogLevel(0) // 0-详细 1-普通 2-警告 3-错误
// 启用详细日志
if (process.env.NODE_ENV === 'development') {
window.__DEBUG__ = true
}
```
### 2. 监听所有事件
### 2. 使用浏览器开发者工具
```typescript
// 监听通话开始
TUICallKitServer.on('onCallBegin', () => {
console.log('通话开始')
})
// 监听通话结束
TUICallKitServer.on('onCallEnd', () => {
console.log('通话结束')
})
// 监听错误
TUICallKitServer.on('onError', (error) => {
console.error('通话错误', error)
```javascript
// 在控制台查看应用状态
console.log('App State:', {
tuikit: window.__TUIKIT_INITIALIZED__,
https: window.location.protocol === 'https:',
hostname: window.location.hostname
})
```
### 3. 使用浏览器开发者工具
### 3. 监控网络请求
1. 打开开发者工具 (F12)
2. 查看 Console 标签页
3. 查看 Network 标签页
4. 查看 Application → Local Storage
```javascript
// 拦截所有网络请求
const originalFetch = window.fetch
window.fetch = function(...args) {
console.log('[Fetch]', args[0])
return originalFetch.apply(this, args)
}
```
### 4. 查看后端日志
### 4. 查看 Nginx 访问日志
```bash
# 实时查看错误日志
tail -f server/runtime/log/error.log
# 实时查看访问日志
sudo tail -f /var/log/nginx/admin_https_access.log
# 查看最近的日志
tail -n 100 server/runtime/log/error.log
# 查看错误日志
sudo tail -f /var/log/nginx/admin_https_error.log
```
---
## 常见错误代码
| 错误代码 | 含义 | 解决方案 |
|---------|------|--------|
| 60006 | WebRTC 不支持 | 使用 HTTPS 或 localhost |
| 60007 | 摄像头/麦克风权限被拒 | 检查浏览器权限设置 |
| 60008 | 网络连接失败 | 检查网络和防火墙 |
| 60009 | 签名过期 | 重新获取签名 |
| 60010 | 用户不存在 | 检查用户 ID |
## 获取帮助
如果问题仍未解决，请收集以下信息：
1. **浏览器信息**
```javascript
console.log(navigator.userAgent)
```
2. **错误堆栈**
- 完整的错误信息
- 堆栈跟踪
3. **网络请求**
- 失败的请求 URL
- 响应状态码
- 响应内容
4. **服务器日志**
- Nginx 错误日志
- 应用日志
5. **系统信息**
- 操作系统
- 浏览器版本
- 网络环境（是否在公司网络）
## 联系支持
如果以上方法都无法解决问题，请提供以下信息：
1. 错误截图或日志
2. 浏览器版本和操作系统
3. 操作步骤
4. 配置信息（脱敏后）
5. 网络环境
联系方式：
- 技术支持邮箱: support@example.com
- 腾讯云工单: https://console.cloud.tencent.com/workorder
---
## 参考资料
- [TUICallKit 官方文档](https://cloud.tencent.com/document/product/647/78742)
- [TRTC 常见问题](https://cloud.tencent.com/document/product/647/43018)
- [WebRTC 调试指南](https://webrtc.org/getting-started/testing)
- 项目 GitHub Issues
- 腾讯云 TUIKit 文档：https://cloud.tencent.com/document/product/647
- 浏览器兼容性检查：https://caniuse.com/webrtc