Simon
157 lines
4.3 KiB
Markdown
157 lines
4.3 KiB
Markdown
# 智能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*
|