小蚂蚁云

Appearance

Become a sponsor
企业级中台解决方案
企业级中台解决方案

常见问题FAQ ​

本章节整理了项目开发和部署过程中常见的问题及解决方案，帮助你快速定位和解决问题。

温馨提示

遇到问题时，建议先查看终端日志输出和浏览器控制台（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

温馨提示

前端开发服务器端口冲突同理，修改 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;

温馨提示

确认 .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

温馨提示

如果 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

温馨提示

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

重要提示

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

温馨提示

如果网络环境受限，可以尝试使用 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"]]

温馨提示

所有业务接口都在 /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 配置

温馨提示

验证码生成依赖 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. 在系统管理 > 角色管理中，确认角色已分配该权限

温馨提示

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

温馨提示

  1. 如需上传更多文件类型，在 UPLOAD_ALLOWED_EXTS 中添加对应扩展名（带点号，逗号分隔）。
  2. 如需上传更大文件，增大 UPLOAD_MAX_SIZE_MB 值。
  3. 确保项目根目录下的 uploads/ 目录存在且有写入权限。

快速自检清单 ​

遇到问题时，按以下清单逐项检查：

检查项命令期望结果
Python 版本python --version3.12+
pip 依赖pip list | grep fastapifastapi 已安装
MySQL 服务mysql -uroot -p -e "SELECT 1"返回 1
Redis 服务redis-cli pingPONG
.env 文件cat .env | grep JWT_SALT非空值
后端服务curl http://127.0.0.1:8031/api/v1/captcha返回 JSON
Node.js 版本node -vv22+
pnpm 版本pnpm -v11.x+
前端服务浏览器访问 http://localhost:8001显示登录页

温馨提示

如果以上检查项均正常但仍无法运行，建议查看完整错误日志：

bash
# 后端日志
python src/main.py 2>&1 | tee backend.log

# 前端日志
cd ui && pnpm dev 2>&1 | tee frontend.log

总结 ​

本章节整理了项目开发中最常见的 10 个问题及其解决方案，涵盖环境配置、服务连接、依赖安装、权限控制和文件上传等方面。遇到问题时，建议先查看终端日志和浏览器控制台的错误信息，结合本章节的排查步骤逐一排除。如果问题仍未解决，可以查阅项目源码或联系开发团队获取支持。

小蚂蚁云团队 · 提供技术支持

Copyright © 2020~2026 www.djangoadmin.cn. All rights reserved.