签入版本

2026-09-12 23:12:15 +08:00
commit 91998056ca
1841 changed files with 341325 additions and 0 deletions
@@ -0,0 +1,261 @@
+# 故障排查手册
+
+## 概述
+
+本文列出常见故障及排查方案，帮助运维和开发人员快速定位和解决问题。
+
+:::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 :8000
+# 或
+netstat -tlnp | grep 8000
+
+# 杀掉占用进程
+kill -9 <PID>
+```
+
+:::tip 常见原因
+- 上次启动未正常退出，进程残留
+- 其他服务占用了 8000 端口
+- Supervisor 或 Docker 重复启动
+:::
+
+## 2. 启动失败：数据库连接失败
+
+**现象**：启动时报 `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 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`
+
+**排查**：
+
+```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. Django 环境初始化失败
+
+**现象**：代码生成器报错 `Django环境初始化失败`
+
+**排查**：
+
+```bash
+# 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}`
+
+**排查**：
+
+```bash
+# 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}`
+
+**排查**：
+
+```bash
+# 1. 检查用户角色配置
+# 登录后台 -> 系统管理 -> 用户管理 -> 查看用户角色
+
+# 2. 检查角色权限配置
+# 系统管理 -> 角色管理 -> 查看角色菜单权限
+
+# 3. 检查菜单权限标识
+# 系统管理 -> 菜单管理 -> 查看权限标识（如 sys:example:page）
+```
+
+:::tip admin 用户
+用户 ID 为 1 的管理员账号跳过所有权限检查。排查权限问题时，先用 admin 账号确认功能正常。
+:::
+
+## 7. 验证码不显示或校验失败
+
+**现象**：验证码图片加载失败或提交后提示验证码错误
+
+**排查**：
+
+```bash
+# 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
+
+**排查**：
+
+```bash
+# 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 秒
+
+**排查**：
+
+```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 django_example WHERE status = 1;"
+```
+
+:::tip 优化建议
+- 为 WHERE/ORDER BY 字段添加索引
+- 避免 `SELECT *`，只查需要的字段
+- 大分页使用游标分页
+- 热点数据使用 Redis 缓存
+:::
+
+## 10. Docker 容器启动失败
+
+**现象**：`docker-compose up` 后容器立即退出
+
+**排查**：
+
+```bash
+# 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 类常见故障，每类均提供排查步骤和常见原因。建议收藏本文作为运维应急参考。