wecom_it_smart_desk/docs/09-部署运维/deploy/12-问题修复记录-20260705.md

智能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 函数中添加参数：

   current_agent: Agent = Depends(get_current_agent),
   

2. 使用 sed 命令在容器中直接插入行：

   sudo docker exec wecom_it_backend sed -i '63i\    current_agent: Agent = Depends(get_current_agent),' /app/app/api/messages.py
   

3. 重启后端容器：

   sudo docker restart wecom_it_backend
   

验证结果：

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. 在容器中手动安装（临时修复）：

   sudo docker exec wecom_it_backend pip install wordfilter
   

验证结果：

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