zyt/admin/TROUBLESHOOTING.md

故障排查指南

问题 1: 页面打不开或显示空白

症状

• 页面完全空白
• 控制台有 JavaScript 错误
• 应用无法加载

排查步骤

1. 检查浏览器控制台

   • 打开 F12 开发者工具
   • 查看 Console 标签页
   • 记录所有错误信息

2. 检查网络请求

   • 打开 Network 标签页
   • 刷新页面
   • 查看是否有 404 或 500 错误
   • 检查 index.html 是否正确加载

3. 检查服务器日志

   # Nginx 错误日志
   sudo tail -f /var/log/nginx/error.log
   
   # 应用日志
   tail -f /path/to/your/app.log
   

4. 清除浏览器缓存

   • Ctrl+Shift+Delete (Windows) 或 Cmd+Shift+Delete (Mac)
   • 选择"所有时间"
   • 清除缓存和 Cookie

问题 2: TUIKit 相关错误

症状

Uncaught ReferenceError: Cannot access 't' before initialization
TypeError: Cannot read properties of null (reading 'getTRTCCloudInstance')

原因

• TUIKit 库在初始化时出现问题
• WebRTC 环境不支持（HTTP 协议）
• 浏览器不支持 WebRTC

解决方案

1. 确保使用 HTTPS

   # 检查当前协议
   # 地址栏应该显示 https://
   

2. 检查浏览器兼容性

   • Chrome 60+
   • Firefox 55+
   • Safari 11+
   • Edge 79+

3. 检查浏览器权限

   • 允许访问摄像头
   • 允许访问麦克风
   • 允许访问屏幕共享

4. 查看控制台日志

   // 在浏览器控制台输入
   console.log('[TUIKit] Status:', window.__TUIKIT_INITIALIZED__)
   

问题 3: 视频通话无法连接

症状

• 无法发起通话
• 无法接收通话
• 视频/音频无法传输

排查步骤

1. 检查网络连接

   # 测试网络延迟
   ping api.zzzhengyangtang.cn
   
   # 测试 DNS 解析
   nslookup api.zzzhengyangtang.cn
   

2. 检查防火墙

   # 检查 443 端口是否开放
   sudo netstat -tlnp | grep 443
   
   # 检查 UDP 端口（WebRTC 使用）
   sudo ufw status
   

3. 检查后端 API

   # 测试 API 连接
   curl -I https://api.zzzhengyangtang.cn/api/health
   
   # 检查签名获取
   curl https://api.zzzhengyangtang.cn/api/tcm.diagnosis/getDoctorSignature
   

4. 查看浏览器控制台

   • 检查 TUICallKitAPI 初始化日志
   • 查看网络请求状态
   • 记录错误信息

问题 4: 性能问题

症状

• 页面加载缓慢
• 通话卡顿
• 内存占用过高

优化方案

1. 启用 Gzip 压缩

   # 在 Nginx 配置中添加
   gzip on;
   gzip_types text/plain text/css text/javascript application/javascript;
   gzip_min_length 1000;
   

2. 启用浏览器缓存

   # 在 Nginx 配置中添加
   location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
       expires 1y;
       add_header Cache-Control "public, immutable";
   }
   

3. 使用 CDN

   • 将静态资源上传到 CDN
   • 修改 vite.config.ts 中的 base 路径

4. 监控性能

   // 在浏览器控制台查看性能指标
   performance.getEntriesByType('navigation')[0]
   

问题 5: SSL 证书问题

症状

• 浏览器显示"不安全"警告
• 证书过期
• 证书不匹配

解决方案

1. 检查证书状态

   # 查看证书信息
   sudo certbot certificates
   
   # 检查证书有效期
   openssl x509 -in /etc/letsencrypt/live/api.zzzhengyangtang.cn/fullchain.pem -noout -dates
   

2. 手动续期

   # 续期证书
   sudo certbot renew
   
   # 强制续期
   sudo certbot renew --force-renewal
   

3. 重启 Nginx

   sudo systemctl restart nginx
   

调试技巧

1. 启用详细日志

在 main.ts 中添加：

// 启用详细日志
if (process.env.NODE_ENV === 'development') {
    window.__DEBUG__ = true
}

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

// 在控制台查看应用状态
console.log('App State:', {
    tuikit: window.__TUIKIT_INITIALIZED__,
    https: window.location.protocol === 'https:',
    hostname: window.location.hostname
})

3. 监控网络请求

// 拦截所有网络请求
const originalFetch = window.fetch
window.fetch = function(...args) {
    console.log('[Fetch]', args[0])
    return originalFetch.apply(this, args)
}

4. 查看 Nginx 访问日志

# 实时查看访问日志
sudo tail -f /var/log/nginx/admin_https_access.log

# 查看错误日志
sudo tail -f /var/log/nginx/admin_https_error.log

常见错误代码

错误代码	含义	解决方案
60006	WebRTC 不支持	使用 HTTPS 或 localhost
60007	摄像头/麦克风权限被拒	检查浏览器权限设置
60008	网络连接失败	检查网络和防火墙
60009	签名过期	重新获取签名
60010	用户不存在	检查用户 ID

获取帮助

如果问题仍未解决，请收集以下信息：

1. 浏览器信息

   console.log(navigator.userAgent)
   

2. 错误堆栈

   • 完整的错误信息
   • 堆栈跟踪

3. 网络请求

   • 失败的请求 URL
   • 响应状态码
   • 响应内容

4. 服务器日志

   • Nginx 错误日志
   • 应用日志

5. 系统信息

   • 操作系统
   • 浏览器版本
   • 网络环境（是否在公司网络）

联系支持

• 项目 GitHub Issues
• 腾讯云 TUIKit 文档：https://cloud.tencent.com/document/product/647
• 浏览器兼容性检查：https://caniuse.com/webrtc