Simon
206 lines
3.6 KiB
Markdown
206 lines
3.6 KiB
Markdown
# 智能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)
|