simon/wecom_it_smart_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

WIP-CHECKPOINT[auth-refactor]: 固化工程师崩溃前部分成果 + 同树其他未提交WIP（仅源码，不含密钥/二进制）-- 待重激活工程师续作

Browse Source
This commit is contained in:
Simon
2026-07-07 21:52:11 +08:00
parent 242c1967ff
commit fab75760e0
203 changed files with 21504 additions and 3345 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/09-部署运维/00-标准故障排查手册.md
+211
View File
@@ -0,0 +1,211 @@
# 00 · 标准故障排查手册
> **版本**: v1.0 | **日期**: 2026-07-07 | **维护人**: 宋献 / 助理
> **定位**: 所有故障排查前**首先查看本手册**。本手册整合了原先散落的快速诊断、服务器端诊断、故障排查指南、4 份修复记录、通讯链路诊断、deploy/02 手册、调试验证指南。
> **前置阅读**: [运维手册（部署/回滚/备份/应急）](../01-项目总览/01-智能IT服务系统运维手册-20260704.md) · [SOP-04 应急响应](../10-项目管理/SOPs-标准流程/SOP-04-应急响应.md)
---
## 0 文档说明与版本
### 0.1 为什么要有这本手册
原先"故障排查"主题散落在 9 份文档中（500 诊断、服务器端诊断、故障排查指南、4 份修复记录、通讯链路、deploy/02 手册、调试验证指南），内容重复且存在断链。任何故障都应**先翻这一本**，按决策树定位，再查案例库。
### 0.2 ⛔ 验证完成硬规则（最重要）
**宣布"已修复 / 已完成"之前，必须提供真实可验证证据**，不得仅凭 curl / 日志 / "我认为"：
- **前端 / 登录类问题**：真实浏览器登录或操作截图（用真实 Chromium / Playwright 打开页面、输入凭据、完成动作、进入目标页的截图）。
- **API / 后端类问题**：端到端调用证据（curl 真实返回 + 必要时代码层拦截响应体）。
- **禁止**：只因 `docker logs` 无报错就断言修复；只因"我认为应该好了"就宣布完成。
### 0.3 版本历史
| 版本 | 日期 | 变更 |
|------|------|------|
| v1.0 | 2026-07-07 | 整合 9 份散落文档 + 新增 CASE-20260707-01（Redis urlparse 挂起）|
---
## 1 快速诊断决策树
### 1.1 三步隔离法（通用）
任何"页面打不开 / 网络连接失败 / 接口无响应 / 422"都先用三步隔离，定位是 nginx、后端、还是依赖（DB / Redis）的问题：
```bash
# 第1步：nginx 层可达性（在服务器执行；浏览器走 HTTPS，故用 https 而非 localhost）
curl -ksI https://itsupport.servyou.com.cn/itadmin/ | head -5
curl -ksI https://itsupport.servyou.com.cn/api/health | head -5
# 第2步：直连后端（绕过 nginx，确认后端本身）
docker compose exec backend curl -s http://localhost:8000/health
# 或容器外：
docker exec wecom_it_backend curl localhost:8000/health
# 第3步：依赖可达性
docker compose exec redis redis-cli ping # 期望 PONG
docker compose exec postgres pg_isready -U wecom # 期望 accepting
```
**判定矩阵**：
| 现象 | 第1步 | 第2步 | 第3步 | 定位 |
|------|------|------|------|------|
| 浏览器"网络连接失败"、curl 永远不返回 | ✅200 | ✅200 | ❌挂起 | **依赖挂起**（如 Redis 连到错误 host）|
| 全站 500 | ❌500 | ✅/❌ | — | 后端异常，看 backend 日志 |
| 某端点 502 | ❌502 | ❌后端 down | — | 后端未起 / 缺 `PYTHONPATH=/app` |
| /itdesk/ 200 但 /api/... 404 | ✅ | — | — | nginx 代理路径不匹配 |
| 422 | ✅ | API 校验失败 | — | 请求体缺字段（见 §2）|
### 1.2 关键陷阱：URL 特殊字符导致依赖"静默挂起"
详见案例 **CASE-20260707-01**。密码含 `@` `#` 时，`urlparse` 把它们当 URL 分隔符，连到不存在的 host，连接**无限挂起**（浏览器表现为"网络连接失败"，curl 永远等不到返回）。这是最隐蔽的一类故障——容器全 Up、nginx 全 200、唯独业务接口卡死。
### 1.3 在服务器跑诊断的 3 种方式（经堡垒机）
公司服务器只能经堡垒机（`sxn@10.212.189.210:2222` → `ssh sxn@10.90.5.110`）操作，无法本地 scp。推荐用 jumpserver-ops 工具自动执行：
```powershell
# 本地（Windows）用 jumpserver-ops 跑（自动复用会话，~2-3s/条）：
python jms_ops.py exec -c "docker compose ps" -c "curl -ksI https://itsupport.servyou.com.cn/api/health" --reuse
```
> 原"服务器端跑诊断"的 3 种手工方式（PuTTY 跳堡垒机 / scp 上传 / 服务器下载）已不推荐，统一用上述 jumpserver-ops 自动化。
---
## 2 常见错误码速查（E5xx）
| 错误码 | 含义 | 首选排查 |
|--------|------|---------|
| **E500** | 后端未捕获异常 / 缺列 / 缺依赖 | `docker compose logs backend --tail=200 \| grep -i error`；查数据库缺列 / 缺 Python 依赖 |
| **E502** | nginx 连不到后端 | 后端容器 `unhealthy`？`docker logs wecom_it_backend`；是否缺 `PYTHONPATH=/app` |
| **E503** | 服务过载 / 维护 | `docker stats`；`docker inspect ... Health` |
| **E403** | IP 白名单 / 无权限 | `grep allow /opt/wecom-it-desk/nginx/nginx.conf`；admin 角色不足 |
| **E422** | 请求体校验失败（Pydantic）| 确认必填字段齐全（如登录需 `user_id`+`name`）|
| **网络失败 / 连接挂起** | 依赖不可达（最常见 Redis 配置错）| 见 §1.2 / CASE-20260707-01 |
### 2.1 E500 常见根因速查
- 数据库缺列 → `ALTER TABLE ... ADD COLUMN IF NOT EXISTS ...`
- 缺 Python 依赖 → `requirements.txt` 补依赖后重构建（如 `wordfilter`）
- 代码签名不匹配（如缺 `current_agent` 参数）→ 修函数签名
- `import aioredis` 与 Python 3.12 冲突 → 改 `redis.asyncio`，设 `PYTHONPATH=/app`
### 2.2 E422 登录场景
登录端点 `/api/agents/login` 要求 `user_id`(必填) + `name`(必填)；缺字段直接 422。前端 `admin.ts` 用 `name: inputUserId` 发送。
---
## 3 诊断脚本与命令
### 3.1 一键系统状态
```bash
#!/bin/bash
echo "==== 容器状态 ===="; docker compose ps
echo "==== 端口 ===="; netstat -tlnp | grep -E "80|443|5432|6379|8000"
echo "==== 前端文件 ===="; ls -la /opt/wecom-it-desk/html/itdesk/ 2>/dev/null | head
echo "==== backend 错误 ===="; docker compose logs --tail=20 backend 2>&1 | grep -i error
echo "==== Redis ===="; docker compose exec redis redis-cli ping
echo "==== PG ===="; docker compose exec postgres pg_isready -U wecom
```
### 3.2 500 错误快速对照
| 现象 | 诊断 |
|------|------|
| `ls .../frontend-h5/dist/` No such file | 部署包未含 dist |
| nginx 容器内 `ls /usr/share/nginx/html/itdesk/` 失败 | 挂载路径错 |
| curl /itdesk/ 返回 500 | 后端代理或 SPA 内部错 |
| /itportal/ 200 但 /itdesk/ 500 | H5 端特定问题 |
| nginx 日志有 `proxy_pass` 错 | 后端未起 / 端口不通 |
| nginx 日志 `rewrite ... cycle` | try_files 死循环，修 nginx 配置 |
### 3.3 通讯链路检查点（用户 ↔ 坐席 ↔ 企微）
- 用户→系统：企微回调 `/wecom/callback` → `message_router` → 消息入库 → 坐席 WS / 轮询
- 系统→用户：坐席 POST `/conversations/{id}/messages` → `wecom_service.send_text_message()`（errcode=0）→ 用户收到
- 已知风险：非文本消息（图片/文件）不推送；`dev_mode` 跳过企微推送；企微 API 失败静默（仅日志）
- 检查点文件：`wecom_callback.py` / `message_router.py` / `messages.py` / `wecom_service.py` / `ws_manager.py`
### 3.4 WebSocket 失败
```bash
grep -r 'websocket' /opt/wecom-it-desk/nginx/nginx.conf # 需 proxy_http_version 1.1 + Upgrade/Connection
docker logs wecom_it_backend | grep -i websocket
```
---
## 4 案例库（倒序，编号 CASE-YYYYMMDD-序号）
### CASE-20260707-01 · 管理后台登录"网络连接失败"（Redis 密码 URL 解析挂起）⭐
- **现象**：浏览器登录 `/itadmin/` 一直转圈 / "网络连接失败"；API 永远不返回；curl 超时。
- **根因**：`REDIS_URL=redis://:R3d!s@2026#Secure@redis:6379/0`，密码含 `@` 和 `#`。`urlparse()` 把 `#` 当 fragment、`@` 当 host 分隔符 → 解析出 host=`2026`、password=`R3d!s` → 连到不存在的 host → **无限挂起**。后端 `token_service.create_token()` 调 `redis.setex` 时卡死。
- **修复**：
1. `docker-compose.yml` 后端 `REDIS_URL` 改为 URL-encoded：`redis://:R3d%21s%402026%23Secure@redis:6379/0`
2. `backend/app/config.py` 的 `create_redis_client` 增加 `unquote()` 解码 + `socket_connect_timeout=5` / `socket_timeout=5`
3. redis 服务 `--requirepass` 与 healthcheck **保持明文** `R3d!s@2026#Secure`（与后端解码后的明文一致）
4. 重建 backend + redis 容器
- **验证**：Redis `PING→PONG`；`curl` 登录 `/api/agents/login` 返回 `HTTP 200, 0.64s, role:admin`；**真实浏览器登录截图进入 dashboard 成功**（见 §5）。
- **⚠️ 同类复发防护**：本项目 Redis 密码含特殊字符，**改 docker-compose 密码时两处必须一致**（后端 `REDIS_URL` 用 encoded，redis `--requirepass` 用明文）；且 `config.py` 必须 `unquote`。
### CASE-20260705-01 · 502 Bad Gateway（后端启动失败 / aioredis + PYTHONPATH）
- **现象**：坐席端登录失败 `502`，后端容器 `unhealthy`。
- **根因**：旧镜像 `import aioredis` 与 Python 3.12 冲突（`TypeError: duplicate base class TimeoutError`）；且未设 `PYTHONPATH=/app` 致 `ModuleNotFoundError: No module named 'app.core'`。
- **修复**：Dockerfile 改 `import redis.asyncio as aioredis`；`docker-compose.yml` 设 `PYTHONPATH=/app`；重建后端。
### CASE-20260705-02 · 坐席端 4 个问题（消息列表 500 / 页面抖动 / 发送失败 / 文档缺失）
- #1 消息列表 500：`list_messages()` 缺 `current_agent: Agent = Depends(get_current_agent)` 参数。修 `messages.py` + 重启。
- #2 页面短暂不可用：容器重启波动，自愈。
- #3 发送失败 `ModuleNotFoundError: wordfilter`：`requirements.txt` 缺 `wordfilter==0.2.7`，容器内 `pip install` 临时修 + 同步 requirements。
- #4 文档补"Python 依赖管理"章节（服务器部署手册）。
### CASE-20260613-01 · H5 消息 500（缺列 + AIHandler 签名）
- **现象**：`POST /api/h5/.../messages` 500：`column conversations.impact_scope does not exist` + `AIHandler.__init__() missing 'ai_service'`。
- **根因**：DB 缺 4 列（`impact_scope`/`is_blocking`/`emotion_state`/`dify_conversation_id`）；`dependencies.py` 两处 `AIHandler()` 未传 `ai_service`。
- **修复**：`ALTER TABLE` 补列；`dependencies.py` 改 `AIHandler(ai_service=AIService())`。
### 附：企微工作台"加载失败 / 无限加载"（2026-07-04）
- 根因1：nginx 未正确挂载 `nginx.conf` → API 404，重建 nginx 容器。
- 根因2：后端 `h5.py` 存在 `NameError: _require_wework_ua` → 代码未同步最新，复制最新 `h5.py` + 重启。
---
## 5 端到端验证完成标准（原《调试验证指南》整合）
> 宣布完成前，按 §0.2 提供真实证据。
### 5.1 管理后台验证（最常见）
| 步骤 | 操作 | 预期 |
|------|------|------|
| 1 | 浏览器开 `https://itsupport.servyou.com.cn/itadmin/` | 登录页 |
| 2 | 输入 `sxn` / `test123` 登录 | 进入 dashboard，右上角显示"宋" |
| 3 | 仪表盘数据渲染 | 在线坐席 / 今日会话 / 平均响应 / AI 命中率 有值 |
| 4 | API 拦截 `POST /api/agents/login` | HTTP 200 + `role:admin` + token |
### 5.2 通用验证清单（P0 必须通过）
- [ ] H5 登录流程正常（企微 OAuth 跳转 → 回跳 → 欢迎）
- [ ] 坐席登录正常，可接单
- [ ] 消息收发双向正常（文本 / 图片 / 文件）
- [ ] 邀请功能闭环
- [ ] 管理后台可访问且数据正常
### 5.3 真实浏览器证据获取（推荐 Playwright）
本机 Windows 可直接访问服务器（TCP 443 通）。用 `playwright-core` 驱动已安装的 Chromium（路径 `~/.agent-browser/browsers/chrome-*/chrome.exe`），拦截 API 响应作为证据，避免 CLI 工具 IPC 不稳。
---
## 6 升级与应急（交叉引用，不重复）
- **回滚方案** → 见 [运维手册·第六章](../01-项目总览/01-智能IT服务系统运维手册-20260704.md#六回滚方案)
- **备份恢复** → 见 [运维手册·第七章](../01-项目总览/01-智能IT服务系统运维手册-20260704.md#七备份恢复)
- **应急响应（P0/P1 分级、止血、通知）** → 见 [SOP-04 应急响应](../10-项目管理/SOPs-标准流程/SOP-04-应急响应.md)
- 本手册只负责"定位 + 修复"，变更管理与事故流程以上述文档为准。
---
## 7 参考文档索引
| 文档 | 说明 |
|------|------|
| `01-项目总览/01-智能IT服务系统运维手册-20260704.md` | 部署 / 回滚 / 备份 / 应急（故障排查章已并入本手册）|
| `10-项目管理/SOPs-标准流程/SOP-04-应急响应.md` | 应急响应 SOP |
| `09-部署运维/deploy/01-部署指南.md` | 部署操作 |
| `09-部署运维/deploy/03-版本记录.md` | 版本与修复记录索引 |
| `09-部署运维/deploy/服务器部署手册.md` | 服务器部署细节 |
| `06-测试质量/testing-测试/E2E-CHECKLIST-v0.7.0.md` | E2E 验收清单 |
---
> **维护说明**: 本手册为故障排查唯一入口。新增案例请按 `CASE-YYYYMMDD-序号` 倒序追加到 §4；改动需同步本文件版本号与日期。
docs/09-部署运维/deploy/03-RELEASE-NOTES-v0.7.1-20260623.md → docs/09-部署运维/03-RELEASE-NOTES-v0.7.1-20260623.md
View File
docs/09-部署运维/deploy/05-版本更新说明-v1.1.0-20260614.md → docs/09-部署运维/05-版本更新说明-v1.1.0-20260614.md
View File
docs/09-部署运维/deploy/06-OTP二次验证实现.md → docs/09-部署运维/06-OTP二次验证实现.md
View File
docs/09-部署运维/deploy/07-扫码登录OTP部署指南-v0.7.0.md → docs/09-部署运维/07-扫码登录OTP部署指南-v0.7.0.md
View File
docs/09-部署运维/deploy/08-NAS部署指南-预生产.md → docs/09-部署运维/08-NAS部署指南-预生产.md
View File
docs/09-部署运维/deploy/10-一键部署操作包-v0.7.0.md → docs/09-部署运维/10-一键部署操作包-v0.7.0.md
View File
docs/09-部署运维/deploy/11-堡垒机运维工具.md → docs/09-部署运维/11-堡垒机运维工具.md
View File
docs/09-部署运维/deploy/DEPLOY-GUIDE.md → docs/09-部署运维/DEPLOY-GUIDE.md
View File
docs/09-部署运维/deploy/HOTFIX-ROLLBACK-PLAN.md → docs/09-部署运维/HOTFIX-ROLLBACK-PLAN.md
View File
docs/09-部署运维/deploy/NGINX-DOMAIN-ROUTING.md → docs/09-部署运维/NGINX-DOMAIN-ROUTING.md
+16 -8
View File
@@ -58,11 +58,15 @@ server {
# ========================================================================
# 3. 管理后台
# ========================================================================
# IP 白名单(临时方案,v1.0 前收窄 — 见 ip-whitelist-trust-proxies-todo.md)
# IP 白名单(2026-07-06 更新 — 添加办公网IP)
location /itadmin/ {
allow 0.0.0.0/0; # ⚠️ 临时全开
# allow 10.90.0.0/16; # TODO 收窄到内网
# allow 115.236.188.3; # 公网入口 IP
# 允许的IP列表（按需求添加）
allow 10.90.0.0/16; # 内网段 - 税友内网
allow 10.240.0.0/16; # 内网段 - 办公网
allow 117.147.35.138; # 办公网出口IP
allow 218.75.34.87; # 办公网出口IP
allow 127.0.0.1; # 本地
deny all; # 其他拒绝
alias /opt/wecom-it-desk/frontend-admin/dist/;
try_files $uri $uri/ /itadmin/index.html;
@@ -83,11 +87,15 @@ server {
# 5. 后端 API(4 个端共用)
# ========================================================================
location /api/ {
# 管理端 API 严格白名单
# 管理端 API 严格白名单(与/itadmin/一致)
location /api/admin/ {
allow 0.0.0.0/0; # ⚠️ 临时全开
# allow 10.90.0.0/16; # TODO 收窄
# allow 115.236.188.3;
# 允许的IP列表（按需求添加）
allow 10.90.0.0/16; # 内网段 - 税友内网
allow 10.240.0.0/16; # 内网段 - 办公网
allow 117.147.35.138; # 办公网出口IP
allow 218.75.34.87; # 办公网出口IP
allow 127.0.0.1; # 本地
deny all; # 其他拒绝
proxy_pass http://wecom_it_backend;
}
docs/09-部署运维/guides-用户指南/USER-GUIDE-QRCODE-MFA.md → docs/09-部署运维/USER-GUIDE-QRCODE-MFA.md
View File
docs/09-部署运维/deploy/01-部署指南.md
+3 -5
View File
@@ -124,11 +124,11 @@ docker restart wecom_it_nginx
#### 500 错误
详见 [快速诊断-500-错误.md](./快速诊断-500-错误.md)
详见 [标准故障排查手册](../00-标准故障排查手册.md)
#### 通讯链路问题
详见 [通讯链路诊断方案.md](./通讯链路诊断方案.md)
详见 [标准故障排查手册](../00-标准故障排查手册.md)
### 3.2 健康检查
@@ -179,6 +179,4 @@ docker run -d --name wecom_it_backend wecom-it-desk-backend:<版本>
- [10-一键部署操作包-v0.7.0.md](./10-一键部署操作包-v0.7.0.md)
- [蓝绿部署指南.md](./蓝绿部署指南.md)
- [快速诊断-500-错误.md](./快速诊断-500-错误.md)
- [通讯链路诊断方案.md](./通讯链路诊断方案.md)
- [12-问题修复记录-20260705.md](./12-问题修复记录-20260705.md)
- [标准故障排查手册](../00-标准故障排查手册.md)
docs/09-部署运维/deploy/02-故障排查.md
-205
View File
@@ -1,205 +0,0 @@
# 智能IT服务台 - 故障排查手册
> **最后更新**：2026-07-05
---
## 目录
1. [常见错误码](#一常见错误码)
2. [网络问题](#二网络问题)
3. [服务问题](#三服务问题)
4. [数据问题](#四数据问题)
---
## 一、常见错误码
### 1.1 502 Bad Gateway
**原因**：Nginx 无法连接到后端服务
**排查步骤**：
1. 检查后端容器状态
```bash
docker ps | grep backend
```
2. 检查后端是否健康
```bash
docker exec wecom_it_backend curl localhost:8000/health
```
3. 检查后端日志
```bash
docker logs wecom_it_backend --tail 100
```
4. 检查 Nginx upstream 配置
```bash
grep -A2 'upstream' /opt/wecom-it-desk/nginx/nginx.conf
```
**解决方案**：
- 重启后端：`docker restart wecom_it_backend`
- 检查端口：`docker port wecom_it_backend`
- 检查网络：`docker network inspect wecom-it-desk_it-desk-internal`
### 1.2 500 Internal Server Error
**原因**：后端代码错误或异常
**排查步骤**：
```bash
# 查看后端错误日志
docker logs wecom_it_backend --tail 200 | grep -i error
# 查看具体请求错误
docker logs wecom_it_backend --tail 500
```
详见 [快速诊断-500-错误.md](./快速诊断-500-错误.md)
### 1.3 503 Service Unavailable
**原因**：服务过载或维护中
**排查步骤**：
```bash
# 检查容器资源
docker stats
# 检查健康检查状态
docker inspect wecom_it_backend | grep -A10 Health
```
### 1.4 403 Forbidden
**原因**：IP 白名单限制
**排查步骤**：
```bash
# 检查 Nginx 配置中的白名单
grep 'allow' /opt/wecom-it-desk/nginx/nginx.conf
```
---
## 二、网络问题
### 2.1 通讯链路诊断
详见 [通讯链路诊断方案.md](./通讯链路诊断方案.md)
### 2.2 DNS 解析问题
```bash
# 测试 DNS 解析
nslookup itsupport.servyou.com.cn
# 测试内网解析
nslookup itsupport.servyou.com.cn 10.212.1.1
```
### 2.3 端口连通性
```bash
# 测试端口开放
nc -zv 10.90.5.110 80
nc -zv 10.90.5.110 443
# 测试内部网络
docker exec wecom_it_nginx curl http://wecom_it_backend:8000/health
```
---
## 三、服务问题
### 3.1 容器启动失败
```bash
# 查看容器日志
docker logs <容器名>
# 查看详细错误
docker events --since '10m'
# 检查资源限制
docker inspect <容器名> | grep -A5 Memory
```
### 3.2 数据库连接失败
```bash
# 检查 PostgreSQL
docker exec wecom_it_postgres pg_isready
# 检查 Redis
docker exec wecom_it_redis redis-cli ping
```
### 3.3 WebSocket 连接失败
```bash
# 检查 WebSocket 配置
grep -r 'websocket' /opt/wecom-it-desk/nginx/nginx.conf
# 检查后端 WebSocket 日志
docker logs wecom_it_backend | grep -i websocket
```
---
## 四、数据问题
### 4.1 数据不一致
```bash
# 检查数据库连接
docker exec wecom_it_backend python -c "from app.database import get_db; print('OK')"
# 检查 Redis 连接
docker exec wecom_it_backend python -c "import redis; r = redis.from_url('redis://:password@redis:6379/0'); print(r.ping())"
```
### 4.2 磁盘空间不足
```bash
# 检查磁盘
df -h
# 检查 Docker 磁盘使用
docker system df
```
---
## 快速命令汇总
```bash
# 一键健康检查
docker ps --format '{{.Names}}\t{{.Status}}'
# 查看所有日志
docker logs -f wecom_it_backend
# 重启所有服务
docker compose restart
# 查看实时错误
docker logs --tail 100 -f wecom_it_backend 2>&1 | grep -i error
```
---
## 相关文档
- [快速诊断-500-错误.md](./快速诊断-500-错误.md)
- [通讯链路诊断方案.md](./通讯链路诊断方案.md)
- [WAF转发配置异常排查协助.md](./WAF转发配置异常排查协助.md)
docs/09-部署运维/deploy/03-版本记录.md
+2 -2
View File
@@ -45,14 +45,14 @@
- Nginx upstream 配置修复
- 蓝绿部署流程完善
详见 [12-问题修复记录-20260705.md](./12-问题修复记录-20260705.md)
详见 [标准故障排查手册](../00-标准故障排查手册.md)
### 2026-06-13
- H5 用户端报错修复
- 后端启动问题修复
详见 [04-部署修复记录-20260613.md](./04-部署修复记录-20260613.md)
详见 [标准故障排查手册](../00-标准故障排查手册.md)
---
docs/09-部署运维/deploy/04-部署修复记录-20260613.md
-185
View File
@@ -1,185 +0,0 @@
# 智能IT支持服务台 - 部署修复记录
**日期**：2026-06-13
**负责人**：宋献
**状态**：待部署验证
---
## 一、问题概述
### 1.1 部署后 H5 用户端报错
```
POST /api/h5/conversations/current/messages 返回 500 错误：
- 错误1：column conversations.impact_scope does not exist
- 错误2：AIHandler.__init__() missing 1 required positional argument: 'ai_service'
```
### 1.2 影响范围
| 系统 | 影响 | 说明 |
|------|------|------|
| H5 用户端 | 阻塞 | 无法发送消息触发 AI 回复 |
| Dify AI | 无法测试 | 依赖 H5 消息发送 |
| 管理后台 | 已修复 | admin001 已设为管理员 |
---
## 二、根因分析
### 2.1 数据库缺列
服务器上数据库 `conversations` 表缺少4个新增列：
- `impact_scope` — 影响范围
- `is_blocking` — 是否阻塞
- `emotion_state` — 情绪状态
- `dify_conversation_id` — Dify 会话ID
### 2.2 AIHandler 初始化错误
代码重构后 `AIHandler.__init__` 需要传入 `AIService` 实例，但 `dependencies.py` 中两处调用仍使用无参构造函数：
```python
# 错误代码
return AIHandler()
# 正确代码
return AIHandler(ai_service=AIService())
```
---
## 三、修复内容
### 3.1 数据库修复（已完成）
```sql
ALTER TABLE conversations ADD COLUMN IF NOT EXISTS impact_scope VARCHAR(50);
ALTER TABLE conversations ADD COLUMN IF NOT EXISTS is_blocking BOOLEAN DEFAULT false;
ALTER TABLE conversations ADD COLUMN IF NOT EXISTS emotion_state VARCHAR(50);
ALTER TABLE conversations ADD COLUMN IF NOT EXISTS dify_conversation_id VARCHAR(255);
```
### 3.2 代码修复
**文件**：`backend/app/dependencies.py`
**修复内容**：2处 AIHandler 调用补上 ai_service 参数
| 位置 | 修复前 | 修复后 |
|------|--------|--------|
| get_shared_ai_handler() | `return AIHandler()` | `return AIHandler(ai_service=AIService())` |
| dep_ai_handler() | `return AIHandler()` | `return AIHandler(ai_service=AIService())` |
---
## 四、部署步骤
### 4.1 本地打包
```powershell
cd D:\资料\03-项目开发\wecom_it_smart_desk\deploy-server
.\打包部署.bat
```
生成文件：
- `it-smart-desk-server-deploy.zip` — 前端+nginx+docker-compose
- `deploy-backend.tar` — 后端 Docker 镜像（含修复）
### 4.2 上传服务器
通过堡垒机将文件上传到服务器 `/tmp/`：
- `it-smart-desk-server-deploy.zip`
- `deploy-backend.tar`
### 4.3 服务器部署
```bash
# 1. 加载后端镜像
docker load -i /tmp/deploy-backend.tar
# 2. 重启后端容器
docker stop wecom_it_backend && docker rm wecom_it_backend
docker run -d --name wecom_it_backend ... (原启动命令)
# 3. 验证后端健康
curl https://itsupport.servyou.com.cn/health
```
---
## 五、验证检查项
### 5.1 后端健康检查
```bash
curl https://itsupport.servyou.com.cn/health
# 预期返回：{"status":"ok"}
```
### 5.2 H5 消息发送测试
1. H5 Mock 登录：`POST /api/h5/mock-login`
2. 发送消息：`POST /api/h5/conversations/current/messages`
3. 预期：返回 AI 回复（调用 Dify 成功）
### 5.3 Dify AI 集成状态
管理后台 → 集成配置 → Dify AI 状态应为 `connected`
---
## 六、相关配置
### 6.1 服务器信息
| 项目 | 值 |
|------|------|
| 服务器 IP | 10.90.5.110 |
| 域名 | itsupport.servyou.com.cn |
| WAF | 115.236.188.3 |
### 6.2 企微配置
| 项目 | 值 |
|------|------|
| CorpID | wwa8c87970b2011f41 |
| AgentID | 1000133 |
| Token | wAqMCP |
| EncodingAESKey | KQY3cEsBc3rdi3xua9rPd5WxH8kYOhyASzWZQf75aJS |
### 6.3 Dify 配置
| 项目 | 值 |
|------|------|
| API URL | http://yw-dify.dc.servyou-it.com/dify2openai/v1/chat/completions |
| API Key | http://yw-dify.dc.servyou-it.com/v1\|app-UaTWYdBSwN6VktKQlbh5YN5H\|Chat |
### 6.4 数据库配置
| 项目 | 值 |
|------|------|
| 数据库 | PostgreSQL |
| 库名 | wecom_it_desk |
| 用户 | wecom |
| 密码 | wecom_secret_2026 |
---
## 七、相关文件
| 文件路径 | 说明 |
|---------|------|
| `backend/app/dependencies.py` | 修复后的代码 |
| `deploy-server/build-and-deploy.ps1` | 打包部署脚本 |
| `deploy-server/打包部署.bat` | 一键执行入口 |
| `docs/IT服务台PRDv1.0.md` | 产品需求文档 |
---
**更新历史**
| 日期 | 更新内容 |
|------|---------|
| 2026-06-13 | 初始记录，数据库修复 + 代码修复 + 打包脚本 |
docs/09-部署运维/deploy/12-问题修复记录-20260705.md
-156
View File
@@ -1,156 +0,0 @@
# 智能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*
docs/09-部署运维/deploy/502-BadGateway-后端启动失败-20260705.md
-120
View File
@@ -1,120 +0,0 @@
# 502 Bad Gateway - 后端启动失败
> 日期：2026-07-05
> 问题：坐席端登录失败，返回 502 Bad Gateway
---
## 一、问题现象
用户访问 `https://itsupport.servyou.com.cn/itagent/` 时提示登录失败：
```
Failed to load resource: the server responded with a status of 502 (Bad Gateway)
AxiosError: Request failed with status code 502
```
---
## 二、诊断过程
### 2.1 检查容器状态
```bash
docker ps -a
```
发现后端容器状态为 `unhealthy`：
```
CONTAINER ID IMAGE STATUS
656f7696d4e5 wecom-it-desk-backend:latest Up 8 minutes (unhealthy)
```
### 2.2 检查后端日志
```bash
docker logs 656f7696d4e5 --tail 30
```
发现错误：
```
ModuleNotFoundError: No module named 'aioredis'
```
### 2.3 原因分析
- 旧版镜像中代码使用 `import aioredis`
- 但 `aioredis` 包与 Python 3.12 不兼容
- 报错：`TypeError: duplicate base class TimeoutError`
---
## 三、解决方案
### 3.1 尝试修复（失败）
尝试在容器内安装 `aioredis` 包，但发现：
- `aioredis` 与 Python 3.12 不兼容
- 安装后仍报错：`TypeError: duplicate base class TimeoutError`
### 3.2 最终方案
删除旧容器，使用正确的环境变量重新启动：
```bash
# 1. 删除旧容器
docker stop 656f7696d4e5
docker rm 656f7696d4e5
# 2. 使用正确的 PYTHONPATH 重新启动
cd /opt/wecom-it-desk
PYTHONPATH=/app docker compose up -d backend
```
关键点：**必须设置 `PYTHONPATH=/app`**，否则会报错 `ModuleNotFoundError: No module named 'app.core'`
---
## 四、验证结果
```bash
# 检查容器状态
docker ps
# 输出：
# 2ec80dee024c wecom-it-desk-backend:latest Up 5 minutes (healthy)
# e147524342fa redis:7-alpine Up 11 hours (healthy)
# 8a2265864f34 nginx:1.27-alpine Up 11 hours
# 433ef922c8d8 postgres:16-alpine Up 11 hours (healthy)
# 测试 API
curl http://localhost:8000/health
# 输出：{"status":"ok"}
# 测试页面
curl -sk https://localhost/itdesk/
# 输出：HTML 页面正常返回
```
---
## 五、根因总结
| 问题 | 原因 |
|------|------|
| 后端容器 unhealthy | 旧镜像使用 `import aioredis`，与 Python 3.12 不兼容 |
| 启动失败 | 需要设置 `PYTHONPATH=/app` 环境变量 |
---
## 六、预防措施
1. **更新镜像**：在 Dockerfile 中将所有 `import aioredis` 改为 `import redis.asyncio as aioredis`
2. **环境变量**：确保 docker-compose.yml 中设置 `PYTHONPATH=/app`
3. **健康检查**：定期检查容器健康状态
---
## 七、相关文件
- 部署配置：`/opt/wecom-it-desk/docker-compose.yml`
- Nginx 配置：`/opt/wecom-it-desk/nginx/nginx.conf`
- 后端代码：`/opt/wecom-it-desk/backend/`
docs/09-部署运维/deploy/WAF转发配置异常排查协助.md
-114
View File
@@ -1,114 +0,0 @@
# WAF 转发配置申请
## 问题描述
`itsupport.servyou.com.cn` 域名无法访问，浏览器超时。需 WAF 配置转发规则。
---
## 证据链
### 1. 服务器本地 — 服务正常 ✅
```
# HTTP 已强制跳转 HTTPS（nginx 配置 301 重定向）
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# curl http://localhost/itdesk/health
<html><head><title>301 Moved Permanently</title></head>...nginx/1.27.5</html>
# HTTPS 正常响应
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# curl -k https://127.0.0.1/itdesk/health -H "Host: itsupport.servyou.com.cn"
healthy
```
### 2. SSL 证书 — 有效 ✅
```
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# echo | openssl s_client -connect 127.0.0.1:443 -servername itsupport.servyou.com.cn
CONNECTED(00000003)
depth=2 C=US, O=DigiCert Inc, CN=DigiCert Global Root G2
depth=1 C=US, O=DigiCert, Inc., CN=GeoTrust G2 TLS CN RSA4096 SHA256 2022 CA1
depth=0 C=CN, ST=浙江省, L=杭州市, O=税友软件集团股份有限公司, CN=*.servyou.com.cn
Verification: OK
Protocol: TLSv1.3, Cipher: TLS_AES_256_GCM_SHA384
Verify return code: 0 (ok)
```
证书信息：
- 主体：`CN=*.servyou.com.cn`（通配符证书）
- 颁发者：`GeoTrust G2 TLS CN RSA4096 SHA256 2022 CA1`
- 有效期：2025-12-23 ~ 2027-01-12
### 3. DNS 解析 — 指向 WAF ✅
```
# 服务器 DNS 解析到 WAF 公网 IP
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# ping -c 1 itsupport.servyou.com.cn
PING itsupport.servyou.com.cn (115.236.188.3): 56(84) bytes of data.
--- itsupport.servyou.com.cn ping statistics ---
1 packets transmitted, 0 received, 100% packet loss
```
- 解析结果：`115.236.188.3`（WAF 公网 IP）
- ping 100% 丢失（WAF 禁 ICMP，正常）
### 4. WAF 转发 — 不通 ❌
```
# 从服务器通过域名访问 HTTP（超时）
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# curl -v http://itsupport.servyou.com.cn/itdesk/health
* Trying 115.236.188.3:80...
^C（超时无响应）
# 从服务器通过域名访问 HTTPS（超时）
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# curl -v https://itsupport.servyou.com.cn/itdesk/health
* Trying 115.236.188.3:443...
^C（超时无响应）
```
### 5. 服务器外网连通性 — 正常 ✅
```
# 企微 API 可达
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# curl -s https://qyapi.weixin.qq.com/cgi-bin/gettoken
{"errcode":41004,"errmsg":"corpsecret missing", "from ip": "218.75.34.87"}
# PyPI 镜像可达
[root@hz-oa-ai-g-dataquery-90-5-110 ~]# curl -s https://pypi.tuna.tsinghua.edu.cn/
<html><head><title>302 Found</title></head>...nginx/1.22.1</html>
```
---
## 结论
| 环节 | 状态 |
|------|------|
| 服务器（10.90.5.110） | ✅ HTTP/HTTPS 服务正常 |
| SSL 证书（*.servyou.com.cn） | ✅ 有效，TLSv1.3 |
| DNS 解析 | ✅ 指向 WAF（115.236.188.3） |
| 服务器外网连通性 | ✅ 企微 API / PyPI 均可达 |
| **WAF 转发到后端** | **❌ 未配置 — 流量未到达 10.90.5.110** |
---
## 需要配置
请 WAF/网络团队配置转发规则：
```
域名：itsupport.servyou.com.cn
源端口：80（HTTP）/ 443（HTTPS）
转发目标：10.90.5.110:80
```
---
## 服务器信息
| 项目 | 值 |
|------|-----|
| 服务器 IP | 10.90.5.110 |
| 服务端口 | 80（HTTP→HTTPS 重定向）+ 443（HTTPS） |
| 域名 | itsupport.servyou.com.cn |
| SSL 证书 | *.servyou.com.cn（DigiCert，有效期至 2027-01-12） |
| 系统 | Linux（Docker 部署，nginx 反向代理） |
docs/09-部署运维/deploy/快速诊断-500-错误.md
-81
View File
@@ -1,81 +0,0 @@
# 快速诊断 /itdesk/ 500 错误
**Claude 无法直接 SSH(Windows known_hosts 权限 + 堡垒机交互登录限制),需你跑下面命令并把输出贴回。**
---
## 🚀 一键跑法(推荐)
**完整脚本已写到** `D:\资料\03-项目开发\wecom_it_smart_desk-claude\diagnose-500.sh`(3484 字节)
**步骤**:
1. **上传脚本到服务器**(`/tmp/`):
```powershell
# 你在 PowerShell(堡垒机后的 Windows)跑:
scp "D:\资料\03-项目开发\wecom_it_smart_desk-claude\diagnose-500.sh" user@10.90.5.110:/tmp/
# (用你自己的文件传输方式,因为堡垒机禁 scp ProxyJump)
```
2. **PuTTY 登录**:
- Host:`10.212.189.210`,Port:`2222`,SSH → Open
- 用户 `sxn` + 密码
- 堡垒机内 `ssh sxn@10.90.5.110` 跳目标机
3. **在服务器上跑**:
```bash
sudo cp /tmp/diagnose-500.sh /opt/wecom-it-desk/
cd /opt/wecom-it-desk
bash diagnose-500.sh > /tmp/diag.log 2>&1
cat /tmp/diag.log
```
4. **把 /tmp/diag.log 的内容贴回 Claude**
---
## 🛠️ 或者手敲(精简版)
```bash
# 1. 容器状态
docker compose ps
# 2. dist 目录在不在
ls /opt/wecom-it-desk/frontend-h5/dist/
ls /opt/wecom-it-desk/frontend-h5/dist/assets/
# 3. nginx 容器内能看到 dist 吗
docker compose exec nginx ls /usr/share/nginx/html/itdesk/
docker compose exec nginx ls /usr/share/nginx/html/itdesk/assets/
# 4. SSL 证书
docker compose exec nginx ls /etc/nginx/ssl/
# 5. 直接 curl 测试
curl -ksI https://itsupport.servyou.com.cn/itdesk/ | head -10
curl -ksI https://itsupport.servyou.com.cn/itportal/ | head -10
curl -ksI https://itsupport.servyou.com.cn/itagent/ | head -10
curl -ksI https://itsupport.servyou.com.cn/itadmin/ | head -10
# 6. nginx 日志
docker compose logs --tail=20 nginx
docker compose logs --tail=20 backend
```
---
## 🎯 我会关注
| 现象 | 诊断 |
|---|---|
| `ls /opt/wecom-it-desk/frontend-h5/dist/` 显示 **No such file** | 部署包没含 H5 dist(nginx 会 404 → 但一般不会 500) |
| `docker compose exec nginx ls /usr/share/nginx/html/itdesk/` 失败 | nginx 容器挂载路径错了,或 dist 没拷贝进去 |
| `curl -ksI https://itsupport.servyou.com.cn/itdesk/` 返回 **HTTP/1.1 500** | 后端代理或 SPA 内部错误 |
| `curl -ksI https://itsupport.servyou.com.cn/itportal/` 也 500 | **全站问题**,看 nginx 日志 |
| `curl -ksI https://itsupport.servyou.com.cn/itportal/` 200 但 /itdesk/ 500 | **H5 端特定问题**,看 nginx 容器内的文件 |
| nginx 错误日志有 **proxy_pass 错误** | 后端没启动或端口不通 |
| nginx 错误日志有 **"rewrite ... cycle"** | try_files 死循环,需修 nginx 配置 |
---
> 把输出贴回 Claude 后,我会精确定位 500 根因并给出最小修复。
docs/09-部署运维/deploy/手敲-6段命令.md
-54
View File
@@ -1,54 +0,0 @@
# 手敲 6 段命令(脚本上传失败时用)
**PuTTY 登录**:
- Host:`10.212.189.210`,Port:`2222`,SSH → Open
- 用户 `sxn` + 密码
- 堡垒机内再 `ssh sxn@10.90.5.110` 跳目标机
**逐段跑(每段贴回输出)**:
```bash
# === 段 1: 容器 + dist 目录 ===
docker compose ps
echo "--- H5 dist ---"
ls -la /opt/wecom-it-desk/frontend-h5/dist/ 2>&1
echo "--- H5 dist/assets ---"
ls -la /opt/wecom-it-desk/frontend-h5/dist/assets/ 2>&1
# === 段 2: nginx 容器内挂载 ===
docker compose exec nginx ls -la /usr/share/nginx/html/ 2>&1
echo "--- nginx 容器内 itdesk ---"
docker compose exec nginx ls -la /usr/share/nginx/html/itdesk/ 2>&1
echo "--- nginx 容器内 SSL ---"
docker compose exec nginx ls -la /etc/nginx/ssl/ 2>&1
# === 段 3: 各路径 curl 头(用主机端口绕开 nginx 容器内)===
echo "--- /itdesk/ ---"
curl -ksI https://itsupport.servyou.com.cn/itdesk/ 2>&1 | head -8
echo "--- /itportal/ ---"
curl -ksI https://itsupport.servyou.com.cn/itportal/ 2>&1 | head -8
echo "--- /itagent/ ---"
curl -ksI https://itsupport.servyou.com.cn/itagent/ 2>&1 | head -8
echo "--- /itadmin/ ---"
curl -ksI https://itsupport.servyou.com.cn/itadmin/ 2>&1 | head -8
echo "--- /itdesk/index.html(直接抓 index)---"
curl -ks https://itsupport.servyou.com.cn/itdesk/ 2>&1 | head -20
# === 段 4: 容器内 curl 443 测 ===
docker compose exec nginx curl -ksI https://localhost/itdesk/ 2>&1 | head -8
echo "---"
docker compose exec nginx curl -ksI https://localhost/itportal/ 2>&1 | head -8
# === 段 5: nginx + backend 日志 ===
echo "--- nginx 日志 ---"
docker compose logs --tail=30 nginx 2>&1
echo "--- backend 日志 ---"
docker compose logs --tail=30 backend 2>&1
# === 段 6: 容器内 nginx 错误日志 ===
docker compose exec nginx tail -30 /var/log/nginx/error.log 2>&1
echo "--- access.log ---"
docker compose exec nginx tail -30 /var/log/nginx/access.log 2>&1
```
**把全部输出贴回 Claude。**
docs/09-部署运维/deploy/服务器端跑诊断.md
-101
View File
@@ -1,101 +0,0 @@
# 3 种方法在服务器上跑诊断脚本
**目标**:在 10.90.5.110 服务器上跑 diagnose-500.sh,把输出粘回给我
---
## 方法 1(推荐):PuTTY 连进去,一行命令恢复 + 跑
**步骤 1**:PuTTY 客户端
- Host:`10.212.189.210`,Port:`2222`,SSH → Open
- 用户 `sxn` + 密码
- 堡垒机内再 `ssh sxn@10.90.5.110` 跳目标机
**步骤 2**:服务器内贴这一行(整段一次性):
```bash
cat > /tmp/diag.sh << 'ENDOFSCRIPT'
#!/bin/bash
docker compose ps
echo "---"
ls -la /opt/wecom-it-desk/frontend-h5/dist/ 2>&1 | head -10
echo "--- assets ---"
ls -la /opt/wecom-it-desk/frontend-h5/dist/assets/ 2>&1 | head -10
echo "--- nginx 容器内 ---"
docker compose exec nginx ls -la /usr/share/nginx/html/itdesk/ 2>&1 | head -10
echo "--- nginx 容器内 assets ---"
docker compose exec nginx ls -la /usr/share/nginx/html/itdesk/assets/ 2>&1 | head -10
echo "--- SSL ---"
docker compose exec nginx ls -la /etc/nginx/ssl/ 2>&1 | head -10
echo "--- /itdesk/ 头 ---"
curl -ksI https://itsupport.servyou.com.cn/itdesk/ 2>&1 | head -8
echo "--- /itportal/ 头 ---"
curl -ksI https://itsupport.servyou.com.cn/itportal/ 2>&1 | head -8
echo "--- /itagent/ 头 ---"
curl -ksI https://itsupport.servyou.com.cn/itagent/ 2>&1 | head -8
echo "--- /itadmin/ 头 ---"
curl -ksI https://itsupport.servyou.com.cn/itadmin/ 2>&1 | head -8
echo "--- /itdesk/ 完整 body 前 20 行 ---"
curl -ks https://itsupport.servyou.com.cn/itdesk/ 2>&1 | head -20
echo "--- nginx 错误日志 ---"
docker compose exec nginx tail -30 /var/log/nginx/error.log 2>&1
echo "--- nginx 访问日志 ---"
docker compose exec nginx tail -20 /var/log/nginx/access.log 2>&1
echo "--- backend 日志 ---"
docker compose logs --tail=20 backend 2>&1
ENDOFSCRIPT
bash /tmp/diag.sh 2>&1
```
**步骤 3**:把输出整段粘回给我
---
## 方法 2:用 scp 上传本地脚本
**前提**:你能 scp 到 10.90.5.110(堡垒机后的方式)
```bash
scp "C:\Users\simon\Downloads\diagnose-500 (1).sh" sxn@10.90.5.110:/tmp/
# (如果直连 scp 不通,可能要用堡垒机的文件传输功能)
```
然后 PuTTY 连进去跑:
- Host:`10.212.189.210`,Port:`2222`,SSH → Open
- 堡垒机内 `ssh sxn@10.90.5.110` 跳目标机
```bash
sudo cp /tmp/diagnose-500.sh /opt/wecom-it-desk/
cd /opt/wecom-it-desk
bash diagnose-500.sh > /tmp/diag.log 2>&1
cat /tmp/diag.log
```
把 `cat /tmp/diag.log` 的输出粘回
---
## 方法 3:服务器直接下载(若服务器能上外网)
```bash
# PuTTY 连:Host 10.212.189.210 Port 2222 → 堡垒机内 ssh sxn@10.90.5.110
cd /tmp
# 如果服务器能访问 GitHub raw / Gitea
curl -O https://你的存放点/diagnose-500.sh
bash diagnose-500.sh > /tmp/diag.log 2>&1
cat /tmp/diag.log
```
---
## 最简版(只要 5 行输出)
如果方法 1 太长,**只要这 5 行**就够我定位:
```bash
docker compose ps 2>&1
ls -la /opt/wecom-it-desk/frontend-h5/dist/assets/ 2>&1
docker compose exec nginx ls -la /usr/share/nginx/html/itdesk/ 2>&1
docker compose exec nginx tail -10 /var/log/nginx/error.log 2>&1
curl -ksI https://itsupport.servyou.com.cn/itdesk/ 2>&1 | head -8
```
**把这 5 段输出粘回,我能立刻定位 500 原因。**
docs/09-部署运维/deploy/通讯链路诊断方案.md
-138
View File
@@ -1,138 +0,0 @@
# 通讯链路诊断方案
> 日期：2026-07-03
> 目标：诊断当前系统通讯问题，无论结果启动重构方案
---
## 一、通讯链路架构
```
┌─────────────────────────────────────────────────────────────────────────┐
│ 完整通讯链路 │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 【用户 → 坐席】 │
│ ┌──────────┐ 企微回调 ┌──────────┐ 路由 ┌─────────┐ │
│ │ 用户发送 │ ──────────────→ │ 后端API │ ──────────→ │ Message │ │
│ │ 消息 │ /wecom/ │ 回调入口 │ │ Router │ │
│ └──────────┘ callback └──────────┘ └────┬────┘ │
│ │ │ │
│ │ ▼ │
│ │ ┌───────────┐ │
│ │ │ 消息入库 │ │
│ │ │ (DB存储) │ │
│ │ └───────────┘ │
│ │ │ │
│ │ ┌────────────────┘ │
│ │ ▼ │
│ │ ┌──────────┐ │
│ │ │ 坐席收到 │ │
│ │ │(WS/轮询) │ │
│ │ └──────────┘ │
│ │ │
│ 【坐席 → 用户】 │
│ ┌──────────┐ API调用 ┌──────────┐ 企微API ┌────────┐ │
│ │ 坐席发送 │ ──────────────→ │ 后端API │ ──────────→ │企微 │ │
│ │ 消息 │ POST │ 发送消息 │ /message │服务器 │ │
│ └──────────┘ /conversations└──────────┘ /send └────┬───┘ │
│ │ /{id}/messages │ │ │
│ │ ▼ ▼ │
│ │ ┌──────────┐ ┌────────┐ │
│ │ │ 消息入库 │ │用户收到 │ │
│ │ │(DB存储) │ │消息 │ │
│ │ └──────────┘ └────────┘ │
│ │ │
└─────────────────────────────────────────────────────────────────┘
```
---
## 二、诊断检查点
### 2.1 企微回调链路（用户 → 系统）
| 检查点 | 文件位置 | 检查内容 | 预期结果 |
|--------|---------|---------|---------|
| C-01 | `wecom_callback.py` GET `/wecom/callback` | 企微URL验证 | 返回解密后的echostr |
| C-02 | `wecom_callback.py` POST `/wecom/callback` | 消息解密 | 正确解析XML并解密 |
| C-03 | `message_router.py` | 消息路由 | 正确分配会话/坐席 |
| C-04 | 数据库 `messages` 表 | 消息存储 | 消息正确写入 |
### 2.2 坐席发送链路（系统 → 用户）
| 检查点 | 文件位置 | 检查内容 | 预期结果 |
|--------|---------|---------|---------|
| C-05 | `messages.py` POST `/conversations/{id}/messages` | API入口 | 正确接收坐席消息 |
| C-06 | `wecom_service.py` `send_text_message()` | 企微API调用 | errcode=0 |
| C-07 | 企微客户端 | 用户收到消息 | 正常展示 |
### 2.3 H5 实时推送
| 检查点 | 文件位置 | 检查内容 | 预期结果 |
|--------|---------|---------|---------|
| C-08 | `ws_manager.py` | WS连接管理 | 坐席WS连接 |
| C-09 | `frontend-agent` | WS接收 | 消息实时展示 |
| C-10 | `frontend-h5` | 轮询/WebSocket | 新消息实时更新 |
---
## 三、已发现的问题
### 问题1：非文本消息不推送（messages.py:210-233）
```python
# 只有 text 类型消息才调用企微 API 推送给员工
if body.msg_type == "text":
# 调用企微API
```
**影响**：图片、文件等消息无法推送到用户微信端
### 问题2：dev_mode 短路（messages.py:215-216）
```python
if getattr(settings, 'dev_mode', False):
logger.debug(f"[DEV] 跳过企微推送: msg_id={message.id}")
```
**影响**：测试环境下消息不会推送到用户
### 问题3：企微API错误处理（messages.py:231-233）
```python
except Exception as e:
# 企微 API 调用失败不阻塞消息存储
logger.warning(f"企微消息发送失败（消息已存储）: {e}")
```
**影响**：企微API失败时仅记录日志，用户实际未收到消息
---
## 四、诊断执行记录
| 时间 | 检查项 | 结果 | 说明 |
|------|--------|------|------|
| 2026-07-03 | 代码审查 | ✅ | 完成链路分析 |
| - | C-01 企微回调 | ⏳ | 待部署环境验证 |
| - | C-05 坐席发送 | ⏳ | 待部署环境验证 |
| - | C-07 用户收到 | ⏳ | 待实际测试 |
---
## 五、结论
**当前系统通讯链路代码完整**，但存在以下已知风险：
1. 非文本消息（图片/文件）无法推送
2. dev_mode 会跳过企微推送
3. 企微API失败时静默失败
这些问题可通过系统重构进一步优化消息通讯能力。
---
## 六、下一步
**下一步**：根据诊断结果优化现有通讯链路
docs/09-部署运维/deploy/overview.md → docs/09-部署运维/overview.md
View File
docs/09-部署运维/deploy/set-real-ip-patch.md → docs/09-部署运维/set-real-ip-patch.md
View File
docs/09-部署运维/一键部署AI服务脚本.md
+64
View File
@@ -0,0 +1,64 @@
# Dify 一键部署脚本（简化版）
由于完整版 Dify 依赖较多服务，提供一个简化版本
## 使用说明
### 方式1：使用官方一键部署（推荐）
```bash
# Linux/Mac
curl -L https://dify.ai/install.sh | bash
# Windows (使用 PowerShell)
irm https://dify.ai/install.ps1 | iex
```
### 方式2：手动部署简化版
创建一个简化版的 docker-compose.yml：
```yaml
version: '3'
services:
api:
image: langgenius/dify-api:latest
ports:
- "8081:8081"
environment:
- SECRET_KEY=dify-secret-key
- DB_USERNAME=postgres
- DB_PASSWORD=dify123
- DB_HOST=10.0.0.1 # 远程 PostgreSQL
- REDIS_HOST=10.0.0.2 # 远程 Redis
web:
image: langgenius/dify-web:latest
ports:
- "8080:3000"
```
### 方式3：使用在线 Dify 服务
生产环境已有 Dify 服务（内网可访问）：
- 地址：http://yw-dify.dc.servyou-it.com/
---
## 本地开发建议
由于本地部署 AI 服务资源需求大，建议：
1. **开发测试时**：使用 Mock 数据（已实现）
2. **集成测试时**：连接生产 Dify（需内网）
3. **完整部署时**：在服务器上部署
---
## 快速验证 Dify API
```powershell
# 测试生产 Dify
curl -X GET 'http://yw-dify.dc.servyou-it.com/console/api/workspaces' \
-H 'Authorization: Bearer YOUR-API-KEY'
```
docs/09-部署运维/deploy/服务器部署手册.md → docs/09-部署运维/服务器部署手册.md
View File
docs/09-部署运维/本地AI服务部署指南.md
+100
View File
@@ -0,0 +1,100 @@
# 本地 AI 服务部署指南（Dify + RAGFlow）
> 更新日期：2026-07-06
## 系统要求
| 服务 | 最低内存 | 推荐内存 |
|------|----------|----------|
| Dify (CPU) | 8GB | 16GB |
| RAGFlow (CPU) | 8GB | 16GB |
| 两者同时 | 16GB | 32GB |
**当前可用内存：约 7.4GB**
---
## 方案一：仅部署 Dify（推荐）
### 步骤1：停止本地不需要的容器
```powershell
# 停止开发环境（如果不需要）
docker stop dev_wecom_backend dev_wecom_postgres dev_wecom_redis
```
### 步骤2：部署 Dify (CPU版)
```powershell
cd D:\资料\03-项目开发\wecom_it_smart_desk
mkdir dify && cd dify
# 下载 Docker Compose
curl -o docker-compose.yml https://github.com/langgenius/dify/raw/main/docker/docker-compose.middleware.yaml
# 启动
docker compose up -d
```
### 步骤3：访问
- Web UI: http://localhost:8080
- API: http://localhost:8081
- 默认管理员: admin@dify.local / admin
---
## 方案二：仅部署 RAGFlow（CPU版）
### 步骤1：停止本地不需要的容器
```powershell
docker stop dev_wecom_backend dev_wecom_postgres dev_wecom_redis
```
### 步骤2：部署 RAGFlow
```powershell
cd D:\资料\03-项目开发\wecom_it_smart_desk
mkdir ragflow && cd ragflow
# 下载配置
curl -o docker-compose.yml https://raw.githubusercontent.com/infiniflow/ragflow/main/docker/docker-compose.yml
curl -o .env https://raw.githubusercontent.com/infiniflow/ragflow/main/docker/.env
# 启动（使用 CPU profile）
docker compose --profile cpu up -d
```
### 步骤3：访问
- Web UI: http://localhost:9380
- API: http://localhost:9380/api
- 默认管理员: root / infiniflow
---
## 方案三：同时部署（需要16GB+内存）
1. 先停止开发容器
2. 部署 Dify（会占用约 4-6GB）
3. 等待稳定后部署 RAGFlow（会占用约 4-6GB）
---
## 生产环境已配置
| 服务 | 地址 | 用途 |
|------|------|------|
| Dify 生产 | http://yw-dify.dc.servyou-it.com/ | AI 对话、工作流 |
| RAGFlow 生产 | http://10.80.0.85:8080/ | 知识库管理 |
---
## 本地配置后端连接
修改 `backend/.env.dev`：
```bash
# Dify
DIFY_BASE_URL=http://localhost:8081
DIFY_API_KEY=your-api-key
# RAGFlow
RAGFLOW_BASE_URL=http://localhost:9380
RAGFLOW_API_KEY=your-api-key
```
docs/09-部署运维/本地AI服务部署记录.md
+40
View File
@@ -0,0 +1,40 @@
# 本地 AI 服务部署记录
> 日期: 2026-07-05
## 当前状态
### 拉取中的镜像
| 镜像 | 大小 | 预计时间 |
|------|------|----------|
| ollama/ollama:latest | ~2GB | 5-10分钟 |
| langgenius/dify-api:latest | ~5-10GB | 30-60分钟 |
### 部署方案
#### 方案1: Ollama (轻量)
```bash
docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama:latest
# 然后运行模型
docker exec ollama ollama run llama3:8b
```
#### 方案2: Dify (完整)
需要完整的 docker-compose，包含:
- dify-api
- dify-web
- dify-worker
- postgres
- redis
- minio
- nginx
## 本地开发环境
| 服务 | 地址 |
|------|------|
| H5 端 | http://localhost:5176/itdesk/ |
| 坐席端 | http://localhost:5175/itagent/ |
| 管理后台 | http://localhost:5175/itadmin/ |
| 后端 API | http://localhost:8000 |
docs/09-部署运维/deploy/蓝绿部署指南.md → docs/09-部署运维/蓝绿部署指南.md
View File