421 lines
9.7 KiB
Markdown
421 lines
9.7 KiB
Markdown
# 常见问题FAQ
|
||
|
||
本章节整理了项目开发和部署过程中常见的问题及解决方案，帮助你快速定位和解决问题。
|
||
|
||
:::tip 温馨提示
|
||
遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。
|
||
:::
|
||
|
||
## 1. 端口被占用
|
||
|
||
**现象**
|
||
|
||
启动后端服务时报错：
|
||
|
||
```
|
||
OSError: [Errno 98] Address already in use
|
||
```
|
||
|
||
或：
|
||
|
||
```
|
||
ERROR: [Errno 10048] 通常每个套接字地址(协议/网络地址/端口)只允许使用一次
|
||
```
|
||
|
||
**原因**
|
||
|
||
端口 `8000`（或配置的其他端口）已被其他程序占用。
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# Windows 查看端口占用
|
||
netstat -ano | findstr 8000
|
||
# 找到 PID 后终止进程
|
||
taskkill /PID <进程ID> /F
|
||
|
||
# Linux / macOS 查看端口占用
|
||
lsof -i :8000
|
||
# 终止进程
|
||
kill -9 <进程ID>
|
||
```
|
||
|
||
或者使用其他端口启动：
|
||
|
||
```bash
|
||
python manage.py runserver 8080
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
前端开发服务器端口冲突同理，修改 `ui/.env.development` 中的 `VITE_PORT` 即可。
|
||
:::
|
||
|
||
## 2. 数据库连接失败
|
||
|
||
**现象**
|
||
|
||
启动时报错：
|
||
|
||
```
|
||
pymysql.err.OperationalError: (2003, "Can't connect to MySQL server on '127.0.0.1'")
|
||
```
|
||
|
||
或：
|
||
|
||
```
|
||
django.db.utils.OperationalError: (1045, "Access denied for user 'root'@'localhost'")
|
||
```
|
||
|
||
**排查步骤**
|
||
|
||
```
|
||
1. 检查 MySQL 服务是否已启动
|
||
2. 检查 .env 中的 DATABASE_HOST、DATABASE_PORT、DATABASE_USER、DATABASE_PASSWORD 是否正确
|
||
3. 检查数据库用户是否有远程连接权限
|
||
4. 检查防火墙是否放行了数据库端口
|
||
```
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# 测试数据库连接
|
||
mysql -h127.0.0.1 -P3306 -uroot -p
|
||
|
||
# 如果是权限问题，授权用户
|
||
mysql -uroot -p
|
||
GRANT ALL PRIVILEGES ON `djangoadmin.django.antdvue`.* TO 'root'@'%' IDENTIFIED BY 'your_password';
|
||
FLUSH PRIVILEGES;
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
确认 `.env` 中的 `DATABASE_PASSWORD` 没有多余的空格或引号。密码中的特殊字符可能需要转义。
|
||
:::
|
||
|
||
## 3. Redis 连接失败
|
||
|
||
**现象**
|
||
|
||
启动时报错：
|
||
|
||
```
|
||
redis.exceptions.ConnectionError: Error connecting to 127.0.0.1:6379
|
||
```
|
||
|
||
或：
|
||
|
||
```
|
||
redis.exceptions.AuthenticationError: Authentication required
|
||
```
|
||
|
||
**排查步骤**
|
||
|
||
```
|
||
1. 检查 Redis 服务是否已启动
|
||
2. 检查 .env 中的 REDIS_HOST、REDIS_PORT、REDIS_PASSWORD 是否正确
|
||
3. 检查 Redis 是否设置了密码
|
||
```
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# 测试 Redis 连接
|
||
redis-cli -h 127.0.0.1 -p 6379 -a your_password ping
|
||
|
||
# Windows 启动 Redis 服务
|
||
net start Redis
|
||
|
||
# Linux 启动 Redis 服务
|
||
sudo systemctl start redis
|
||
|
||
# macOS 启动 Redis 服务
|
||
brew services start redis
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
Redis 用于存储验证码和 JWT 令牌黑名单，是项目正常运行的必需服务。确保 `.env` 中的 `REDIS_PASSWORD` 与 Redis 实际配置的密码一致。
|
||
:::
|
||
|
||
## 4. pip install 安装失败
|
||
|
||
**现象**
|
||
|
||
执行 `pip install -r requirements.txt` 时报错：
|
||
|
||
```
|
||
ERROR: Could not find a version that satisfies the requirement xxx
|
||
```
|
||
|
||
或：
|
||
|
||
```
|
||
ERROR: Failed building wheel for xxx
|
||
```
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# 方案一：使用国内镜像源
|
||
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
|
||
|
||
# 方案二：升级 pip 后重试
|
||
python -m pip install --upgrade pip
|
||
pip install -r requirements.txt
|
||
|
||
# 方案三：配置全局镜像源
|
||
pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
|
||
pip config set global.trusted-host mirrors.aliyun.com
|
||
```
|
||
|
||
:::danger requirements.txt 编码问题
|
||
`requirements.txt` 文件为 `UTF-16LE` 编码，部分系统可能无法正确解析。如果 `pip install` 报编码错误，请先将文件转换为 `UTF-8`：
|
||
|
||
```bash
|
||
# Windows (PowerShell)
|
||
Get-Content requirements.txt -Encoding Unicode | Set-Content -Encoding UTF8 requirements_utf8.txt
|
||
pip install -r requirements_utf8.txt
|
||
|
||
# Linux / macOS
|
||
iconv -f UTF-16LE -t UTF-8 requirements.txt > requirements_utf8.txt
|
||
pip install -r requirements_utf8.txt
|
||
```
|
||
:::
|
||
|
||
## 5. mysqlclient 安装失败
|
||
|
||
**现象**
|
||
|
||
Windows 系统安装 `mysqlclient` 时报错：
|
||
|
||
```
|
||
error: Microsoft Visual C++ 14.0 or greater is required
|
||
```
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# 方案一：安装 Visual C++ Build Tools
|
||
# 下载地址：https://visualstudio.microsoft.com/visual-cpp-build-tools/
|
||
|
||
# 方案二：使用预编译的 wheel 包
|
||
# 访问 https://www.lfd.uci.edu/~gohlke/pythonlibs/#mysqlclient
|
||
# 下载对应版本的 .whl 文件后安装
|
||
|
||
# 方案三：使用 pymysql 作为替代（不推荐用于生产）
|
||
pip install pymysql
|
||
```
|
||
|
||
## 6. pnpm install 安装失败
|
||
|
||
**现象**
|
||
|
||
执行 `pnpm install` 时报错：
|
||
|
||
```
|
||
ERR_PNPM_NO_MATCHING_VERSION
|
||
```
|
||
|
||
或：
|
||
|
||
```
|
||
GET https://registry.npmjs.org/xxx error
|
||
```
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# 方案一：切换淘宝镜像源
|
||
pnpm config set registry https://registry.npmmirror.com
|
||
pnpm install
|
||
|
||
# 方案二：清除缓存后重试
|
||
pnpm store prune
|
||
rm -rf node_modules
|
||
pnpm install
|
||
|
||
# 方案三：使用 --shamefully-hoist 模式
|
||
pnpm install --shamefully-hoist
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
如果网络环境受限，可以尝试使用 VPN 或配置代理：
|
||
|
||
```bash
|
||
pnpm config set proxy http://127.0.0.1:7890
|
||
pnpm config set https-proxy http://127.0.0.1:7890
|
||
```
|
||
:::
|
||
|
||
## 7. API 请求返回 404
|
||
|
||
**现象**
|
||
|
||
调用接口时返回：
|
||
|
||
```html
|
||
<h1>Page not found (404)</h1>
|
||
```
|
||
|
||
**原因**
|
||
|
||
可能是请求路径不正确，或后端路由未正确注册。
|
||
|
||
**排查步骤**
|
||
|
||
```
|
||
1. 检查请求路径是否正确（如 /login/captcha、/example/page）
|
||
2. 检查 application/urls.py 中是否注册了对应模块的路由
|
||
3. 检查前端代理配置中的后端地址是否正确
|
||
```
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# 测试后端服务是否正常
|
||
curl http://127.0.0.1:8000/login/captcha
|
||
|
||
# 检查前端代理配置
|
||
# ui/.env.development
|
||
VITE_PROXY=[["/api","http://127.0.0.1:8000/"]]
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
前端所有以 `/api` 开头的请求会被代理到后端的 `8000` 端口。例如：
|
||
- 前端请求 `http://localhost:8001/api/login/captcha`
|
||
- 会被代理到 `http://127.0.0.1:8000/login/captcha`
|
||
:::
|
||
|
||
## 8. 验证码图片不显示
|
||
|
||
**现象**
|
||
|
||
登录页面验证码图片区域空白，或显示加载失败图标。
|
||
|
||
**排查步骤**
|
||
|
||
```
|
||
1. 打开浏览器控制台（F12），查看 Network 标签中的请求状态
|
||
2. 检查 /login/captcha 接口是否返回正常
|
||
3. 检查 Redis 服务是否正常（验证码存储在 Redis 中）
|
||
```
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# 1. 测试验证码接口
|
||
curl http://127.0.0.1:8000/login/captcha
|
||
|
||
# 2. 测试 Redis 连接
|
||
redis-cli -h 127.0.0.1 -p 6379 -a your_password ping
|
||
# 应返回 PONG
|
||
|
||
# 3. 检查 Django 验证码配置是否正常
|
||
python manage.py shell
|
||
>>> from captcha.models import CaptchaStore
|
||
>>> CaptchaStore.objects.count()
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
验证码生成依赖 `django-simple-captcha` 库和 `Pillow` 库。如果验证码接口报错，请确认这两个库已正确安装。
|
||
:::
|
||
|
||
## 9. 接口返回权限不足
|
||
|
||
**现象**
|
||
|
||
调用接口返回：
|
||
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"data": null,
|
||
"msg": "权限不足",
|
||
"ok": false
|
||
}
|
||
```
|
||
|
||
**原因**
|
||
|
||
当前登录用户没有该接口的访问权限。项目采用 RBAC 权限模型，每个接口对应一个权限字符串（如 `sys:user:list`）。
|
||
|
||
**解决方案**
|
||
|
||
```
|
||
1. 使用 admin 账号登录（ID=1 的管理员绕过所有权限检查）
|
||
2. 检查当前用户的角色是否包含该接口的权限
|
||
3. 在系统管理 > 菜单管理中，确认接口对应的权限节点已正确配置
|
||
4. 在系统管理 > 角色管理中，确认角色已分配该权限
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
`admin` 用户（ID=1）是超级管理员，拥有全部权限，不受权限检查限制。开发调试时建议使用 `admin` 账号。
|
||
:::
|
||
|
||
## 10. 文件上传失败
|
||
|
||
**现象**
|
||
|
||
上传文件时返回错误：
|
||
|
||
```json
|
||
{
|
||
"code": 1,
|
||
"data": null,
|
||
"msg": "文件上传失败",
|
||
"ok": false
|
||
}
|
||
```
|
||
|
||
**排查步骤**
|
||
|
||
```
|
||
1. 检查上传目录是否存在且有写入权限
|
||
2. 检查 .env 中的 DJANGO_UPLOAD_DIR 配置是否正确
|
||
3. 检查 .env 中的 DJANGO_FILE_URL 配置是否正确
|
||
4. 检查文件大小是否超过 Django 的 FILE_UPLOAD_MAX_MEMORY_SIZE 限制
|
||
```
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# .env 中的上传配置
|
||
DJANGO_UPLOAD_DIR="E:\DjangoAdmin_Django_AntdVue\public\uploads"
|
||
DJANGO_FILE_URL='http://file.django.antdvue'
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
1. 确保 `public/uploads/` 目录存在且有写入权限。
|
||
2. 如需上传更大文件，可在 `application/settings.py` 中调整 `FILE_UPLOAD_MAX_MEMORY_SIZE` 和 `DATA_UPLOAD_MAX_MEMORY_SIZE` 配置。
|
||
:::
|
||
|
||
## 快速自检清单
|
||
|
||
遇到问题时，按以下清单逐项检查：
|
||
|
||
| 检查项 | 命令 | 期望结果 |
|
||
|:----|:----|:----|
|
||
| Python 版本 | `python --version` | 3.12+ |
|
||
| pip 依赖 | `pip list \| grep django` | Django 6.0+ |
|
||
| MySQL 服务 | `mysql -uroot -p -e "SELECT 1"` | 返回 1 |
|
||
| Redis 服务 | `redis-cli -h 127.0.0.1 -p 6379 -a 123456 ping` | PONG |
|
||
| .env 文件 | 确认 DATABASE_PASSWORD 和 REDIS_PASSWORD 正确 | 非空值 |
|
||
| 后端服务 | `curl http://127.0.0.1:8000/login/captcha` | 返回 JSON |
|
||
| Node.js 版本 | `node -v` | v18+ |
|
||
| pnpm 版本 | `pnpm -v` | 12.x+ |
|
||
| 前端服务 | 浏览器访问 `http://localhost:8001` | 显示登录页 |
|
||
|
||
:::tip 温馨提示
|
||
如果以上检查项均正常但仍无法运行，建议查看完整错误日志：
|
||
|
||
```bash
|
||
# 后端日志
|
||
python manage.py runserver 2>&1 | tee backend.log
|
||
|
||
# 前端日志
|
||
cd ui && pnpm dev 2>&1 | tee frontend.log
|
||
```
|
||
:::
|
||
|
||
## 总结
|
||
|
||
本章节整理了项目开发中最常见的 10 个问题及其解决方案，涵盖环境配置、服务连接、依赖安装、权限控制和文件上传等方面。遇到问题时，建议先查看终端日志和浏览器控制台的错误信息，结合本章节的排查步骤逐一排除。如果问题仍未解决，可以查阅项目源码或联系开发团队获取支持。
|