# 智能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)