425 lines
9.3 KiB
Markdown
425 lines
9.3 KiB
Markdown
# 常见问题FAQ
|
||
|
||
本章节整理了项目开发和部署过程中常见的问题及解决方案，帮助你快速定位和解决问题。
|
||
|
||
:::tip 温馨提示
|
||
遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。
|
||
:::
|
||
|
||
## 1. 端口被占用
|
||
|
||
**现象**
|
||
|
||
启动后端服务时报错：
|
||
|
||
```
|
||
OSError: [Errno 98] Address already in use
|
||
```
|
||
|
||
或：
|
||
|
||
```
|
||
ERROR: [Errno 10048] 通常每个套接字地址(协议/网络地址/端口)只允许使用一次
|
||
```
|
||
|
||
**原因**
|
||
|
||
端口 `8031`（或配置的其他端口）已被其他程序占用。
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# Windows 查看端口占用
|
||
netstat -ano | findstr 8031
|
||
# 找到 PID 后终止进程
|
||
taskkill /PID <进程ID> /F
|
||
|
||
# Linux / macOS 查看端口占用
|
||
lsof -i :8031
|
||
# 终止进程
|
||
kill -9 <进程ID>
|
||
```
|
||
|
||
或者修改 `.env` 中的端口号：
|
||
|
||
```bash
|
||
FASTAPI_PORT=8032
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
前端开发服务器端口冲突同理，修改 `ui/.env.development` 中的 `VITE_PORT` 即可。
|
||
:::
|
||
|
||
## 2. 数据库连接失败
|
||
|
||
**现象**
|
||
|
||
启动时报错：
|
||
|
||
```
|
||
pymysql.err.OperationalError: (2003, "Can't connect to MySQL server on '127.0.0.1'")
|
||
```
|
||
|
||
或：
|
||
|
||
```
|
||
sqlalchemy.exc.OperationalError: (pymysql.err.OperationalError) (1045, "Access denied")
|
||
```
|
||
|
||
**排查步骤**
|
||
|
||
```
|
||
1. 检查 MySQL 服务是否已启动
|
||
2. 检查 .env 中的 DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD 是否正确
|
||
3. 检查数据库用户是否有远程连接权限
|
||
4. 检查防火墙是否放行了数据库端口
|
||
```
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# 测试数据库连接
|
||
mysql -h127.0.0.1 -P3306 -uroot -p
|
||
|
||
# 如果是权限问题，授权用户
|
||
mysql -uroot -p
|
||
GRANT ALL PRIVILEGES ON `djangoadmin.fastapi.elevue`.* TO 'root'@'%' IDENTIFIED BY 'your_password';
|
||
FLUSH PRIVILEGES;
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
确认 `.env` 中的 `DB_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_AUTH 配置是否与 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 未设置密码，请将 `.env` 中的 `REDIS_AUTH` 设为 `False`。
|
||
:::
|
||
|
||
## 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
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
Windows 用户如果遇到 C 编译错误（如安装 `mysqlclient` 时），可尝试安装 Visual C++ Build Tools，或使用预编译的 wheel 包。
|
||
:::
|
||
|
||
## 5. JWT_SALT 未配置
|
||
|
||
**现象**
|
||
|
||
启动时报错：
|
||
|
||
```
|
||
ValueError: JWT_SALT must be set
|
||
```
|
||
|
||
或类似的安全配置错误。
|
||
|
||
**原因**
|
||
|
||
`.env` 文件中 `JWT_SALT` 变量为空或未设置。JWT 签名密钥是安全关键配置，应用在 fail-close 模式下会拒绝启动。
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# 生成 JWT 密钥
|
||
python -c "import secrets; print(secrets.token_urlsafe(48))"
|
||
|
||
# 将生成的密钥写入 .env
|
||
JWT_SALT=your_generated_secret_key_here
|
||
```
|
||
|
||
:::danger 重要提示
|
||
`JWT_SALT` 至少需要 32 字节的强随机值。请勿使用简单字符串（如 `123456` 或 `secret`）作为密钥。
|
||
:::
|
||
|
||
## 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
|
||
|
||
**现象**
|
||
|
||
调用接口时返回：
|
||
|
||
```json
|
||
{
|
||
"detail": "Not Found"
|
||
}
|
||
```
|
||
|
||
**原因**
|
||
|
||
可能是请求路径不正确，或后端路由未正确注册。
|
||
|
||
**排查步骤**
|
||
|
||
```
|
||
1. 检查请求路径是否以 /api/v1/ 开头
|
||
2. 检查 Swagger UI（http://127.0.0.1:8031/docs）中是否存在该接口
|
||
3. 检查前端代理配置中的后端地址是否正确
|
||
```
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# 测试后端服务是否正常
|
||
curl http://127.0.0.1:8031/api/v1/captcha
|
||
|
||
# 检查前端代理配置
|
||
# ui/.env.development
|
||
VITE_PROXY=[["/api","http://127.0.0.1:8031/api"]]
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
所有业务接口都在 `/api/v1/` 前缀下。登录和验证码接口在 `/api/v1/` 下无需认证，其他接口需要携带 JWT Token。
|
||
:::
|
||
|
||
## 8. 验证码图片不显示
|
||
|
||
**现象**
|
||
|
||
登录页面验证码图片区域空白，或显示加载失败图标。
|
||
|
||
**排查步骤**
|
||
|
||
```
|
||
1. 打开浏览器控制台（F12），查看 Network 标签中的请求状态
|
||
2. 检查 /api/v1/captcha 接口是否返回正常
|
||
3. 检查 Redis 服务是否正常（验证码存储在 Redis 中）
|
||
```
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# 1. 测试验证码接口
|
||
curl http://127.0.0.1:8031/api/v1/captcha
|
||
|
||
# 2. 测试 Redis 连接
|
||
redis-cli ping
|
||
# 应返回 PONG
|
||
|
||
# 3. 检查验证码字体文件是否存在
|
||
ls static/fonts/Vera.ttf
|
||
|
||
# 4. 如果字体文件缺失，检查 .env 中的 CAPTCHA_FONT_PATH 配置
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
验证码生成依赖 `Pillow` 库和字体文件。如果字体文件缺失，可从项目仓库重新拉取，或修改 `CAPTCHA_FONT_PATH` 指向系统字体。
|
||
:::
|
||
|
||
## 9. 接口返回 403 权限不足
|
||
|
||
**现象**
|
||
|
||
调用接口返回：
|
||
|
||
```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
|
||
}
|
||
```
|
||
|
||
或：
|
||
|
||
```
|
||
413 Request Entity Too Large
|
||
```
|
||
|
||
**排查步骤**
|
||
|
||
```
|
||
1. 检查上传文件扩展名是否在 ALLOWED_EXTS 白名单中
|
||
2. 检查文件大小是否超过 UPLOAD_MAX_SIZE_MB 限制
|
||
3. 检查上传目录是否有写入权限
|
||
4. 检查 .env 中的 FASTAPI_FILE_URL 配置是否正确
|
||
```
|
||
|
||
**解决方案**
|
||
|
||
```bash
|
||
# .env 中的上传配置
|
||
UPLOAD_ALLOWED_EXTS=.jpg,.jpeg,.png,.gif,.bmp,.ico,.txt,.pdf,.doc,.docx,.xls,.xlsx,.ppt,.pptx,.mp3,.mp4,.zip,.rar,.7z
|
||
UPLOAD_MAX_SIZE_MB=10
|
||
FASTAPI_FILE_URL=http://file.fastapi.elevue
|
||
```
|
||
|
||
:::tip 温馨提示
|
||
1. 如需上传更多文件类型，在 `UPLOAD_ALLOWED_EXTS` 中添加对应扩展名（带点号，逗号分隔）。
|
||
2. 如需上传更大文件，增大 `UPLOAD_MAX_SIZE_MB` 值。
|
||
3. 确保项目根目录下的 `uploads/` 目录存在且有写入权限。
|
||
:::
|
||
|
||
## 快速自检清单
|
||
|
||
遇到问题时，按以下清单逐项检查：
|
||
|
||
| 检查项 | 命令 | 期望结果 |
|
||
|:----|:----|:----|
|
||
| Python 版本 | `python --version` | 3.12+ |
|
||
| pip 依赖 | `pip list \| grep fastapi` | fastapi 已安装 |
|
||
| MySQL 服务 | `mysql -uroot -p -e "SELECT 1"` | 返回 1 |
|
||
| Redis 服务 | `redis-cli ping` | PONG |
|
||
| .env 文件 | `cat .env \| grep JWT_SALT` | 非空值 |
|
||
| 后端服务 | `curl http://127.0.0.1:8031/api/v1/captcha` | 返回 JSON |
|
||
| Node.js 版本 | `node -v` | v22+ |
|
||
| pnpm 版本 | `pnpm -v` | 11.x+ |
|
||
| 前端服务 | 浏览器访问 `http://localhost:8001` | 显示登录页 |
|
||
|
||
:::tip 温馨提示
|
||
如果以上检查项均正常但仍无法运行，建议查看完整错误日志：
|
||
|
||
```bash
|
||
# 后端日志
|
||
python src/main.py 2>&1 | tee backend.log
|
||
|
||
# 前端日志
|
||
cd ui && pnpm dev 2>&1 | tee frontend.log
|
||
```
|
||
:::
|
||
|
||
## 总结
|
||
|
||
本章节整理了项目开发中最常见的 10 个问题及其解决方案，涵盖环境配置、服务连接、依赖安装、权限控制和文件上传等方面。遇到问题时，建议先查看终端日志和浏览器控制台的错误信息，结合本章节的排查步骤逐一排除。如果问题仍未解决，可以查阅项目源码或联系开发团队获取支持。
|