docs: 移动蓝绿部署指南到 troubleshooting 目录

2026-07-05 17:03:36 +08:00
parent ab90db3d3d
commit ca7c6d937a
91 changed files with 4841 additions and 406 deletions
@@ -0,0 +1,156 @@
+# 智能IT支持服务台 - 问题修复记录
+
+**日期**：2026-07-05
+**负责人**：宋献
+**状态**：✅ 已完成
+
+---
+
+## 一、问题概述
+
+### 1.1 当日问题汇总
+
+| 序号 | 问题 | 影响范围 | 严重程度 | 状态 |
+|------|------|---------|---------|------|
+| #1 | 坐席端消息列表 500 错误 | 坐席端 | 🔴 高 | ✅ 已修复 |
+| #2 | 页面短暂无法访问 | 全端 | 🟡 中 | ✅ 已自愈 |
+| #3 | 坐席端消息发送失败 | 坐席端 | 🔴 高 | ✅ 已修复 |
+| #4 | 文档缺失 wordfilter 依赖说明 | 文档 | 🟢 低 | ✅ 已补充 |
+
+---
+
+## 二、问题详情
+
+### 2.1 #1 坐席端消息列表 500 错误
+
+**发现时间**：03:27
+
+**问题现象**：
+- 坐席端报错：`获取消息列表失败: Error: 服务器内部错误，请稍后重试或联系管理员`
+- WebSocket 连接失败：`wss://itsupport.servyou.com.cn/ws/sxn`
+
+**根因分析**：
+- 后端日志：`TypeError: list_messages() got an unexpected keyword argument 'current_user'`
+- 原因：`/api/conversations/{id}/messages` 端点使用了 `@require_permission` 装饰器，但函数签名缺少 `current_agent` 参数
+
+**修复步骤**：
+1. 在 `backend/app/api/messages.py` 的 `list_messages` 函数中添加参数：
+   ```python
+   current_agent: Agent = Depends(get_current_agent),
+   ```
+2. 使用 sed 命令在容器中直接插入行：
+   ```bash
+   sudo docker exec wecom_it_backend sed -i '63i\    current_agent: Agent = Depends(get_current_agent),' /app/app/api/messages.py
+   ```
+3. 重启后端容器：
+   ```bash
+   sudo docker restart wecom_it_backend
+   ```
+
+**验证结果**：
+```bash
+curl "https://itsupport.servyou.com.cn/api/conversations/xxx/messages" -H "Authorization: Bearer xxx"
+# 返回 200 OK，消息列表正常
+```
+
+---
+
+### 2.2 #2 页面短暂无法访问
+
+**发现时间**：10:29
+
+**问题现象**：
+- 用户报告坐席端和员工端页面打不开
+
+**根因分析**：
+- 可能是之前容器重启导致的服务波动
+
+**修复步骤**：
+- 服务自动恢复（无需人工干预）
+
+**验证结果**：
+- H5 端：`/itdesk/` → 200 OK
+- 坐席端：`/itagent/` → 200 OK
+- API：`/api/health` → 200 OK
+
+---
+
+### 2.3 #3 坐席端消息发送失败
+
+**发现时间**：10:44
+
+**问题现象**：
+- 坐席端发送消息失败：`{"code":1005,"message":"服务器内部错误，请稍后重试或联系管理员"}`
+
+**根因分析**：
+- 后端日志：`ModuleNotFoundError: No module named 'wordfilter'`
+- `content_moderation_service.py` (v0.6.0 内容审核功能) 依赖 `wordfilter` 库，但 `requirements.txt` 中未声明
+
+**修复步骤**：
+1. 在 `backend/requirements.txt` 中添加依赖：
+   ```
+   wordfilter==0.2.7
+   ```
+2. 在容器中手动安装（临时修复）：
+   ```bash
+   sudo docker exec wecom_it_backend pip install wordfilter
+   ```
+
+**验证结果**：
+```bash
+curl -X POST "https://itsupport.servyou.com.cn/api/conversations/xxx/messages" \
+  -H "Authorization: Bearer xxx" \
+  -H "Content-Type: application/json" \
+  -d '{"content":"测试","msg_type":"text"}'
+# 返回 {"code":0,"message":"success"}
+```
+
+---
+
+### 2.4 #4 文档缺失 wordfilter 依赖说明
+
+**发现时间**：10:50
+
+**问题现象**：
+- 部署文档中未说明 Python 依赖管理流程
+- `requirements.txt` 未包含 `wordfilter` 依赖
+
+**修复步骤**：
+1. 更新 `backend/requirements.txt`，添加 `wordfilter==0.2.7`
+2. 更新 `docs/09-部署运维/deploy/服务器部署手册.md`，新增"六、Python 依赖管理"章节：
+   - 依赖说明
+   - 新增依赖处理流程
+   - 常见依赖问题及解决方法
+
+**验证结果**：
+- ✅ requirements.txt 已更新
+- ✅ 部署文档已补充
+
+---
+
+## 三、后续建议
+
+1. **依赖管理流程化**：
+   - 每次新增 Python 依赖，必须同步更新 `requirements.txt`
+   - 部署前确保依赖已包含在 requirements.txt 中
+
+2. **监控告警**：
+   - 建议配置后端错误监控（如 Sentry），及时发现生产环境异常
+
+3. **文档同步**：
+   - 重要修复完成后，同步更新相关文档
+
+---
+
+## 四、相关文件
+
+| 文件 | 说明 |
+|------|------|
+| `backend/requirements.txt` | Python 依赖声明 |
+| `backend/app/api/messages.py` | 消息 API |
+| `backend/app/services/content_moderation_service.py` | 内容审核服务 |
+| `docs/09-部署运维/deploy/服务器部署手册.md` | 部署手册 |
+
+---
+
+*最后更新：2026-07-05 10:52*