first commit

2026-09-08 11:40:15 +08:00
commit a5353f7eb5
9568 changed files with 1646214 additions and 0 deletions
@@ -0,0 +1,269 @@
+# 故障排查指南
+
+## 问题 1: 页面打不开或显示空白
+
+### 症状
+- 页面完全空白
+- 控制台有 JavaScript 错误
+- 应用无法加载
+
+### 排查步骤
+
+1. **检查浏览器控制台**
+   - 打开 F12 开发者工具
+   - 查看 Console 标签页
+   - 记录所有错误信息
+
+2. **检查网络请求**
+   - 打开 Network 标签页
+   - 刷新页面
+   - 查看是否有 404 或 500 错误
+   - 检查 index.html 是否正确加载
+
+3. **检查服务器日志**
+   ```bash
+   # 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**
+   ```bash
+   # 检查当前协议
+   # 地址栏应该显示 https://
+   ```
+
+2. **检查浏览器兼容性**
+   - Chrome 60+
+   - Firefox 55+
+   - Safari 11+
+   - Edge 79+
+
+3. **检查浏览器权限**
+   - 允许访问摄像头
+   - 允许访问麦克风
+   - 允许访问屏幕共享
+
+4. **查看控制台日志**
+   ```javascript
+   // 在浏览器控制台输入
+   console.log('[TUIKit] Status:', window.__TUIKIT_INITIALIZED__)
+   ```
+
+## 问题 3: 视频通话无法连接
+
+### 症状
+- 无法发起通话
+- 无法接收通话
+- 视频/音频无法传输
+
+### 排查步骤
+
+1. **检查网络连接**
+   ```bash
+   # 测试网络延迟
+   ping api.zzzhengyangtang.cn
+   
+   # 测试 DNS 解析
+   nslookup api.zzzhengyangtang.cn
+   ```
+
+2. **检查防火墙**
+   ```bash
+   # 检查 443 端口是否开放
+   sudo netstat -tlnp | grep 443
+   
+   # 检查 UDP 端口（WebRTC 使用）
+   sudo ufw status
+   ```
+
+3. **检查后端 API**
+   ```bash
+   # 测试 API 连接
+   curl -I https://api.zzzhengyangtang.cn/api/health
+   
+   # 检查签名获取
+   curl https://api.zzzhengyangtang.cn/api/tcm.diagnosis/getDoctorSignature
+   ```
+
+4. **查看浏览器控制台**
+   - 检查 TUICallKitAPI 初始化日志
+   - 查看网络请求状态
+   - 记录错误信息
+
+## 问题 4: 性能问题
+
+### 症状
+- 页面加载缓慢
+- 通话卡顿
+- 内存占用过高
+
+### 优化方案
+
+1. **启用 Gzip 压缩**
+   ```nginx
+   # 在 Nginx 配置中添加
+   gzip on;
+   gzip_types text/plain text/css text/javascript application/javascript;
+   gzip_min_length 1000;
+   ```
+
+2. **启用浏览器缓存**
+   ```nginx
+   # 在 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. **监控性能**
+   ```javascript
+   // 在浏览器控制台查看性能指标
+   performance.getEntriesByType('navigation')[0]
+   ```
+
+## 问题 5: SSL 证书问题
+
+### 症状
+- 浏览器显示"不安全"警告
+- 证书过期
+- 证书不匹配
+
+### 解决方案
+
+1. **检查证书状态**
+   ```bash
+   # 查看证书信息
+   sudo certbot certificates
+   
+   # 检查证书有效期
+   openssl x509 -in /etc/letsencrypt/live/api.zzzhengyangtang.cn/fullchain.pem -noout -dates
+   ```
+
+2. **手动续期**
+   ```bash
+   # 续期证书
+   sudo certbot renew
+   
+   # 强制续期
+   sudo certbot renew --force-renewal
+   ```
+
+3. **重启 Nginx**
+   ```bash
+   sudo systemctl restart nginx
+   ```
+
+## 调试技巧
+
+### 1. 启用详细日志
+
+在 main.ts 中添加：
+```typescript
+// 启用详细日志
+if (process.env.NODE_ENV === 'development') {
+    window.__DEBUG__ = true
+}
+```
+
+### 2. 使用浏览器开发者工具
+
+```javascript
+// 在控制台查看应用状态
+console.log('App State:', {
+    tuikit: window.__TUIKIT_INITIALIZED__,
+    https: window.location.protocol === 'https:',
+    hostname: window.location.hostname
+})
+```
+
+### 3. 监控网络请求
+
+```javascript
+// 拦截所有网络请求
+const originalFetch = window.fetch
+window.fetch = function(...args) {
+    console.log('[Fetch]', args[0])
+    return originalFetch.apply(this, args)
+}
+```
+
+### 4. 查看 Nginx 访问日志
+
+```bash
+# 实时查看访问日志
+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. **浏览器信息**
+   ```javascript
+   console.log(navigator.userAgent)
+   ```
+
+2. **错误堆栈**
+   - 完整的错误信息
+   - 堆栈跟踪
+
+3. **网络请求**
+   - 失败的请求 URL
+   - 响应状态码
+   - 响应内容
+
+4. **服务器日志**
+   - Nginx 错误日志
+   - 应用日志
+
+5. **系统信息**
+   - 操作系统
+   - 浏览器版本
+   - 网络环境（是否在公司网络）
+
+## 联系支持
+
+- 项目 GitHub Issues
+- 腾讯云 TUIKit 文档：https://cloud.tencent.com/document/product/647
+- 浏览器兼容性检查：https://caniuse.com/webrtc