docs: 合并部署文档 - 创建01-部署指南、02-故障排查、03-版本记录

docs/09-部署运维/deploy/02-故障排查.md

@@ -0,0 +1,205 @@
+# 智能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)