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,120 @@
+# 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/`