290 lines
6.7 KiB
Markdown
290 lines
6.7 KiB
Markdown
# 故障排查手册
|
||
|
||
## 概述
|
||
|
||
本文列出 常见故障及排查方案，帮助运维和开发人员快速定位和解决问题。
|
||
|
||
:::tip 排查思路
|
||
1. 查看日志：`tail -f logs/supervisor.out.log` 或 `docker-compose logs -f`
|
||
2. 检查配置：`.env` 文件、数据库连接、Redis 连接
|
||
3. 检查依赖：Python 包版本、系统服务状态
|
||
4. 逐步排除：从最简单的可能性开始
|
||
:::
|
||
|
||
## 1. 启动失败：端口被占用
|
||
|
||
**现象**：启动时报 `OSError: [Errno 98] Address already in use`
|
||
|
||
**排查**：
|
||
|
||
```bash
|
||
# 查看端口占用
|
||
lsof -i :8031
|
||
# 或
|
||
netstat -tlnp | grep 8031
|
||
|
||
# 杀掉占用进程
|
||
kill -9 <PID>
|
||
```
|
||
|
||
:::tip 常见原因
|
||
- 上次启动未正常退出，进程残留
|
||
- 其他服务占用了 8031 端口
|
||
- Supervisor 或 Docker 重复启动
|
||
:::
|
||
|
||
## 2. 启动失败：数据库连接失败
|
||
|
||
**现象**：启动时报 `OperationalError: (pymysql.err.OperationalError) (2003, "Can't connect to MySQL server")`
|
||
|
||
**排查**：
|
||
|
||
```bash
|
||
# 1. 检查数据库服务是否运行
|
||
systemctl status mysql
|
||
|
||
# 2. 检查网络连通性
|
||
telnet 127.0.0.1 3306
|
||
|
||
# 3. 检查 .env 配置
|
||
cat .env | grep DB_
|
||
|
||
# 4. 检查数据库用户权限
|
||
mysql -u root -p -e "SELECT user, host FROM mysql.user;"
|
||
```
|
||
|
||
:::tip 常见原因
|
||
- MySQL 服务未启动
|
||
- `.env` 中 DB_HOST/DB_PORT 配置错误
|
||
- 数据库用户密码错误
|
||
- 防火墙阻止连接
|
||
:::
|
||
|
||
## 3. 启动失败：Redis 连接失败
|
||
|
||
**现象**：启动时报 `redis.exceptions.ConnectionError`
|
||
|
||
**排查**：
|
||
|
||
```bash
|
||
# 1. 检查 Redis 服务
|
||
systemctl status redis
|
||
|
||
# 2. 测试连接
|
||
redis-cli -h 127.0.0.1 -p 6379 ping
|
||
|
||
# 3. 检查 Redis 密码
|
||
redis-cli -h 127.0.0.1 -p 6379 -a <password> ping
|
||
```
|
||
|
||
## 4. 401 未认证错误
|
||
|
||
**现象**：API 返回 `{"code": 401, "msg": "未登录或 token 已过期"}`
|
||
|
||
**排查**：
|
||
|
||
```bash
|
||
# 1. 检查 token 是否正确传递
|
||
curl -H "Authorization: Bearer <token>" http://127.0.0.1:8031/api/v1/user/info
|
||
|
||
# 2. 检查 token 是否过期（解码 JWT）
|
||
python -c "
|
||
import jwt
|
||
token = '<your-token>'
|
||
payload = jwt.decode(token, options={'verify_signature': False})
|
||
print(payload)
|
||
"
|
||
|
||
# 3. 检查 Redis 中 token 黑名单
|
||
redis-cli GET "token:blacklist:<token>"
|
||
```
|
||
|
||
:::tip 常见原因
|
||
- token 已过期（JWT_EXPIRE_MINUTES 到期）
|
||
- token 被加入黑名单（用户已退出登录）
|
||
- 前端未正确传递 Authorization 头
|
||
- JWT_SALT 配置变更导致旧 token 失效
|
||
:::
|
||
|
||
## 5. 403 无权限错误
|
||
|
||
**现象**：API 返回 `{"code": 403, "msg": "暂无权限访问"}`
|
||
|
||
**排查**：
|
||
|
||
```bash
|
||
# 1. 检查用户角色配置
|
||
# 登录后台 → 系统管理 → 用户管理 → 查看用户角色
|
||
|
||
# 2. 检查角色权限配置
|
||
# 系统管理 → 角色管理 → 查看角色菜单权限
|
||
|
||
# 3. 检查菜单权限标识
|
||
# 系统管理 → 菜单管理 → 查看权限标识（如 sys:position:page）
|
||
|
||
# 4. 清除权限缓存
|
||
redis-cli KEYS "perm:*" | xargs redis-cli DEL
|
||
```
|
||
|
||
:::tip admin 用户
|
||
用户 ID 为 1 的管理员账号跳过所有权限检查。排查权限问题时，先用 admin 账号确认功能正常。
|
||
:::
|
||
|
||
## 6. 验证码不显示或校验失败
|
||
|
||
**现象**：验证码图片加载失败或提交后提示验证码错误
|
||
|
||
**排查**：
|
||
|
||
```bash
|
||
# 1. 检查验证码接口
|
||
curl http://127.0.0.1:8031/api/v1/captcha -o captcha.png
|
||
|
||
# 2. 检查 Redis 连接（验证码存储在 Redis）
|
||
redis-cli GET "captcha:<uuid>"
|
||
|
||
# 3. 检查 Pillow 依赖
|
||
pip show Pillow
|
||
```
|
||
|
||
:::tip 常见原因
|
||
- Pillow 未安装或版本不兼容
|
||
- Redis 连接异常
|
||
- 验证码过期（默认 5 分钟）
|
||
- 前端传递的验证码 UUID 不匹配
|
||
:::
|
||
|
||
## 7. 文件上传失败
|
||
|
||
**现象**：上传文件返回 500 错误或文件大小为 0
|
||
|
||
**排查**：
|
||
|
||
```bash
|
||
# 1. 检查上传目录权限
|
||
ls -la /data/apps/uploads/
|
||
chmod 755 /data/apps/uploads/
|
||
|
||
# 2. 检查磁盘空间
|
||
df -h
|
||
|
||
# 3. 检查 Nginx 上传限制
|
||
grep client_max_body_size /etc/nginx/nginx.conf
|
||
|
||
# 4. 检查上传接口请求
|
||
curl -X POST -F "file=@test.jpg" \
|
||
-H "Authorization: Bearer <token>" \
|
||
http://127.0.0.1:8031/api/v1/upload/file
|
||
```
|
||
|
||
:::tip 常见原因
|
||
- 上传目录不存在或无写权限
|
||
- 磁盘空间不足
|
||
- Nginx `client_max_body_size` 限制过小
|
||
- 文件大小超过后端限制
|
||
:::
|
||
|
||
## 8. 慢查询导致接口超时
|
||
|
||
**现象**：列表接口响应时间超过 3 秒
|
||
|
||
**排查**：
|
||
|
||
```bash
|
||
# 1. 开启 MySQL 慢查询日志
|
||
mysql -u root -p -e "
|
||
SET GLOBAL slow_query_log = ON;
|
||
SET GLOBAL long_query_time = 1;
|
||
"
|
||
|
||
# 2. 查看慢查询
|
||
tail -f /var/log/mysql/slow.log
|
||
|
||
# 3. 分析查询计划
|
||
mysql -u root -p -e "EXPLAIN SELECT * FROM fastapi_article WHERE status = 1;"
|
||
|
||
# 4. 检查索引
|
||
mysql -u root -p -e "SHOW INDEX FROM fastapi_article;"
|
||
```
|
||
|
||
:::tip 优化建议
|
||
- 为 WHERE/ORDER BY 字段添加索引
|
||
- 避免 `SELECT *`，只查需要的字段
|
||
- 大分页使用游标分页
|
||
- 热点数据使用 Redis 缓存
|
||
:::
|
||
|
||
## 9. 内存持续增长（内存泄漏）
|
||
|
||
**现象**：进程内存持续增长，最终 OOM
|
||
|
||
**排查**：
|
||
|
||
```bash
|
||
# 1. 监控内存变化
|
||
watch -n 5 'ps aux | grep uvicorn'
|
||
|
||
# 2. 查看进程内存
|
||
cat /proc/<PID>/status | grep VmRSS
|
||
|
||
# 3. 使用 memory_profiler 分析
|
||
pip install memory_profiler
|
||
python -m memory_profiler src/main.py
|
||
```
|
||
|
||
:::tip 常见原因
|
||
- 全局变量不断累积数据
|
||
- 数据库连接未正确释放
|
||
- 大文件读入内存未释放
|
||
- 日志 Handler 积累
|
||
|
||
解决方案：使用 `--max-requests` 参数定期重启 Worker。
|
||
:::
|
||
|
||
## 10. Docker 容器启动失败
|
||
|
||
**现象**：`docker-compose up` 后容器立即退出
|
||
|
||
**排查**：
|
||
|
||
```bash
|
||
# 1. 查看容器日志
|
||
docker-compose logs fastapi_elevue
|
||
|
||
# 2. 进入容器调试
|
||
docker run -it --rm fastapi_elevue bash
|
||
|
||
# 3. 检查 .env 文件
|
||
cat .env
|
||
|
||
# 4. 检查 Docker 网络
|
||
docker network ls
|
||
docker network inspect host
|
||
```
|
||
|
||
:::tip 常见原因
|
||
- `.env` 文件未正确挂载或配置错误
|
||
- 容器内无法访问宿主机的 MySQL/Redis（host 网络模式需检查）
|
||
- 依赖安装失败（网络问题）
|
||
- Python 版本不兼容
|
||
:::
|
||
|
||
## 快速排查命令速查
|
||
|
||
| 场景 | 命令 |
|
||
|------|------|
|
||
| 查看服务日志 | `tail -f logs/supervisor.out.log` |
|
||
| 查看 Docker 日志 | `docker-compose logs -f` |
|
||
| 检查端口占用 | `lsof -i :8031` |
|
||
| 检查进程状态 | `ps aux \| grep uvicorn` |
|
||
| 检查磁盘空间 | `df -h` |
|
||
| 检查内存使用 | `free -h` |
|
||
| 测试数据库连接 | `mysql -u root -p -e "SELECT 1"` |
|
||
| 测试 Redis 连接 | `redis-cli ping` |
|
||
| 检查 Nginx 配置 | `nginx -t` |
|
||
| 重启应用 | `supervisorctl restart djangoadmin-fastapi` |
|
||
|
||
## 总结
|
||
|
||
故障排查的核心思路：先看日志定位错误，再检查配置排除低级问题，最后逐步深入分析。本文覆盖了启动失败、认证授权、验证码、文件上传、慢查询、内存泄漏、Docker 等 10 类常见故障，每类均提供排查步骤和常见原因。建议收藏本文作为运维应急参考。
|