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/`
@@ -0,0 +1,136 @@
+# 蓝绿部署指南
+
+## 概述
+
+蓝绿部署是一种零停机部署策略，通过维护两套完全相同的运行环境（Blue 和 Green），实现快速切换和回滚。
+
+## 架构
+
+```
+                    ┌─────────────────┐
+                    │   Nginx         │
+                    │  (流量入口)     │
+                    └────────┬────────┘
+                             │
+              ┌──────────────┴──────────────┐
+              │                             │
+              ▼                             ▼
+     ┌────────────────┐          ┌────────────────┐
+     │   Blue 环境    │          │  Green 环境    │
+     │  (当前活动)    │          │  (待验证)      │
+     │  backend:8000  │          │ backend_green: │
+     │                │          │     5002        │
+     └────────────────┘          └────────────────┘
+              │                             │
+              └──────────────┬──────────────┘
+                             │
+              ┌──────────────┴──────────────┐
+              │                             │
+              ▼                             ▼
+     ┌────────────────┐          ┌────────────────┐
+     │  PostgreSQL    │  ←──→   │    Redis      │
+     │  (共享)        │          │   (共享)      │
+     └────────────────┘          └────────────────┘
+```
+
+## 文件说明
+
+| 文件 | 位置 | 说明 |
+|------|------|------|
+| docker-compose-green.yml | /opt/wecom-it-desk/ | Green 环境配置 |
+| switch-blue-green.sh | /opt/wecom-it-desk/ | 切换脚本 |
+| nginx.conf | /opt/wecom-it-desk/nginx/ | Nginx 配置（包含 upstream） |
+
+## 部署步骤
+
+### 1. 部署 Green 环境
+
+```bash
+cd /opt/wecom-it-desk
+
+# 构建并启动 Green 环境
+docker-compose -f docker-compose-green.yml up -d
+
+# 验证 Green 环境健康
+curl http://localhost:5002/health
+```
+
+### 2. 测试 Green 环境
+
+通过端口 5080 访问 Green 环境进行测试：
+- H5: http://服务器IP:5080/itdesk/
+- 坐席: http://服务器IP:5080/itagent/
+- 管理后台: http://服务器IP:5080/itadmin/
+
+### 3. 切换流量到 Green
+
+```bash
+# 方法一：使用切换脚本
+./switch-blue-green.sh to-green
+
+# 方法二：手动修改 Nginx 配置
+sed -i 's/wecom_it_backend:8000/wecom_it_backend_green:8000/' /opt/wecom-it-desk/nginx/nginx.conf
+docker restart wecom_it_nginx
+```
+
+### 4. 验证切换
+
+```bash
+# 检查 Nginx upstream 配置
+grep -A1 'upstream backend_api' /opt/wecom-it-desk/nginx/nginx.conf
+
+# 测试 API
+curl https://itsupport.servyou.com.cn/api/v1/system/health
+```
+
+### 5. 回滚（如有问题）
+
+```bash
+# 方法一：使用切换脚本
+./switch-blue-green.sh to-blue
+
+# 方法二：手动修改
+sed -i 's/wecom_it_backend_green:8000/wecom_it_backend:8000/' /opt/wecom-it-desk/nginx/nginx.conf
+docker restart wecom_it_nginx
+```
+
+## 端口说明
+
+| 端口 | 服务 | 说明 |
+|------|------|------|
+| 80/443 | Nginx (Blue) | 生产入口 |
+| 5002 | Backend (Green) | Green 后端 API |
+| 5080 | Nginx (Green) | Green 测试入口 |
+| 5443 | Nginx (Green) | Green HTTPS |
+
+## 注意事项
+
+1. **数据库共享**：Blue 和 Green 共用同一个 PostgreSQL 和 Redis
+2. **文件上传**：上传的文件保存在挂载目录，不受切换影响
+3. **会话影响**：切换后用户可能需要重新登录
+4. **WebSocket**：切换后现有 WebSocket 连接会断开
+
+## 快速命令汇总
+
+```bash
+# 查看状态
+docker ps
+
+# 查看 Green 日志
+docker logs wecom_it_backend_green
+
+# 切换到 Green
+sed -i 's/wecom_it_backend:8000/wecom_it_backend_green:8000/' /opt/wecom-it-desk/nginx/nginx.conf
+docker restart wecom_it_nginx
+
+# 切换回 Blue
+sed -i 's/wecom_it_backend_green:8000/wecom_it_backend:8000/' /opt/wecom-it-desk/nginx/nginx.conf
+docker restart wecom_it_nginx
+
+# 停止 Green 环境
+docker-compose -f docker-compose-green.yml down
+```
+
+## 更新日志
+
+- 2026-07-05: 初始版本