djangoadmin-wiki/DjangoAdmin_Django_EleVue/zh/volume6/troubleshooting.md

故障排查手册

概述

本文列出常见故障及排查方案，帮助运维和开发人员快速定位和解决问题。

:::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

排查：

# 查看端口占用
lsof -i :8000
# 或
netstat -tlnp | grep 8000

# 杀掉占用进程
kill -9 <PID>

:::tip 常见原因

• 上次启动未正常退出，进程残留
• 其他服务占用了 8000 端口
• Supervisor 或 Docker 重复启动 :::

2. 启动失败：数据库连接失败

现象：启动时报 OperationalError: (2003, "Can't connect to MySQL server")

排查：

# 1. 检查数据库服务是否运行
systemctl status mysql

# 2. 检查网络连通性
telnet 127.0.0.1 3306

# 3. 检查 .env 配置
cat .env | grep DATABASE_

# 4. 检查数据库用户权限
mysql -u root -p -e "SELECT user, host FROM mysql.user;"

:::tip 常见原因

• MySQL 服务未启动
• .env 中 DATABASE_HOST/DATABASE_PORT 配置错误
• 数据库用户密码错误
• 防火墙阻止连接 :::

3. 启动失败：Redis 连接失败

现象：启动时报 redis.exceptions.ConnectionError

排查：

# 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. Django 环境初始化失败

现象：代码生成器报错 Django环境初始化失败

排查：

# 1. 检查是否在项目根目录
pwd

# 2. 检查虚拟环境是否激活
which python

# 3. 检查依赖是否安装
pip list | grep Django

# 4. 检查 settings.py 是否存在
ls application/settings.py

5. 401 未认证错误

现象：API 返回 {"code": 1, "msg": "未登录或token已过期", "ok": false}

排查：

# 1. 检查 token 是否正确传递
curl -H "Authorization: Bearer <token>" http://127.0.0.1:8000/index/getUserInfo

# 2. 检查 Redis 中 token 黑名单
redis-cli GET "djangoadmin:token:blacklist:<token>"

:::tip 常见原因

• token 已过期
• token 被加入黑名单（用户已退出登录）
• 前端未正确传递 Authorization 头 :::

6. 403 无权限错误

现象：API 返回 {"code": 1, "msg": "暂无权限访问", "ok": false}

排查：

# 1. 检查用户角色配置
# 登录后台 -> 系统管理 -> 用户管理 -> 查看用户角色

# 2. 检查角色权限配置
# 系统管理 -> 角色管理 -> 查看角色菜单权限

# 3. 检查菜单权限标识
# 系统管理 -> 菜单管理 -> 查看权限标识（如 sys:example:page）

:::tip admin 用户 用户 ID 为 1 的管理员账号跳过所有权限检查。排查权限问题时，先用 admin 账号确认功能正常。 :::

7. 验证码不显示或校验失败

现象：验证码图片加载失败或提交后提示验证码错误

排查：

# 1. 检查验证码接口
curl http://127.0.0.1:8000/captcha/image/ -o captcha.png

# 2. 检查 Redis 连接（验证码存储在 Redis）
redis-cli GET "djangoadmin:captcha:<uuid>"

# 3. 检查 Pillow 依赖
pip show Pillow

:::tip 常见原因

• Pillow 未安装或版本不兼容
• Redis 连接异常
• 验证码过期（默认 1 分钟）
• 前端传递的验证码 UUID 不匹配 :::

8. 文件上传失败

现象：上传文件返回 500 错误或文件大小为 0

排查：

# 1. 检查上传目录权限
ls -la /data/apps/DjangoAdmin_Django_EleVue/public/uploads/
chmod 755 /data/apps/DjangoAdmin_Django_EleVue/public/uploads/

# 2. 检查磁盘空间
df -h

# 3. 检查 Nginx 上传限制
grep client_max_body_size /etc/nginx/nginx.conf

:::tip 常见原因

• 上传目录不存在或无写权限
• 磁盘空间不足
• Nginx client_max_body_size 限制过小
• 文件大小超过后端限制 :::

9. 慢查询导致接口超时

现象：列表接口响应时间超过 3 秒

排查：

# 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 django_example WHERE status = 1;"

:::tip 优化建议

• 为 WHERE/ORDER BY 字段添加索引
• 避免 SELECT *，只查需要的字段
• 大分页使用游标分页
• 热点数据使用 Redis 缓存 :::

10. Docker 容器启动失败

现象：docker-compose up 后容器立即退出

排查：

# 1. 查看容器日志
docker-compose logs djangoadmin

# 2. 进入容器调试
docker run -it --rm djangoadmin bash

# 3. 检查 .env 文件
cat .env

# 4. 检查 Docker 网络
docker network ls

:::tip 常见原因

• .env 文件未正确挂载或配置错误
• 容器内无法访问宿主机的 MySQL/Redis
• 依赖安装失败（网络问题）
• Python 版本不兼容 :::

快速排查命令速查

场景	命令
查看服务日志	tail -f logs/supervisor.out.log
查看 Docker 日志	docker-compose logs -f
检查端口占用	lsof -i :8000
检查进程状态	ps aux | grep gunicorn
检查磁盘空间	df -h
检查内存使用	free -h
测试数据库连接	mysql -u root -p -e "SELECT 1"
测试 Redis 连接	redis-cli ping
检查 Nginx 配置	nginx -t
重启应用	supervisorctl restart djangoadmin

总结

故障排查的核心思路：先看日志定位错误，再检查配置排除低级问题，最后逐步深入分析。本文覆盖了启动失败、认证授权、验证码、文件上传、慢查询、Docker 等 10 类常见故障，每类均提供排查步骤和常见原因。建议收藏本文作为运维应急参考。