# 常见问题FAQ 本章节整理了项目开发和部署过程中常见的问题及解决方案，帮助你快速定位和解决问题。 :::tip 温馨提示 遇到问题时，建议先查看终端日志输出和浏览器控制台（F12）的错误信息，通常能快速定位问题原因。 ::: ## 1. 端口被占用 **现象** 启动后端服务时报错： ``` OSError: [Errno 98] Address already in use ``` 或： ``` ERROR: [Errno 10048] 通常每个套接字地址(协议/网络地址/端口)只允许使用一次 ``` **原因** 端口 `8021`（或配置的其他端口）已被其他程序占用。 **解决方案** ```bash # Windows 查看端口占用 netstat -ano | findstr 8021 # 找到 PID 后终止进程 taskkill /PID <进程ID> /F # Linux / macOS 查看端口占用 lsof -i :8021 # 终止进程 kill -9 <进程ID> ``` 或者修改 `.env` 中的端口号： ```bash FLASK_PORT=8022 ``` :::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.flask.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` 至少需要 16 字符的强随机值。请勿使用简单字符串（如 `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. 检查后端服务是否正常启动 3. 检查前端代理配置中的后端地址是否正确 ``` **解决方案** ```bash # 测试后端服务是否正常 curl http://127.0.0.1:8021/api/v1/captcha # 检查前端代理配置 # ui/.env.development VITE_PROXY=[["/api","http://127.0.0.1:8021/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:8021/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. 检查上传文件扩展名是否在 UPLOAD_ALLOWED_EXTS 白名单中 2. 检查文件大小是否超过 UPLOAD_MAX_SIZE_MB 限制 3. 检查上传目录是否有写入权限 4. 检查 .env 中的 FLASK_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 FLASK_FILE_URL=http://file.flask.elevue ``` :::tip 温馨提示 1. 如需上传更多文件类型，在 `UPLOAD_ALLOWED_EXTS` 中添加对应扩展名（带点号，逗号分隔）。 2. 如需上传更大文件，增大 `UPLOAD_MAX_SIZE_MB` 值。 3. 确保项目根目录下的 `uploads/` 目录存在且有写入权限。 ::: ## 快速自检清单 遇到问题时，按以下清单逐项检查： | 检查项 | 命令 | 期望结果 | |:----|:----|:----| | Python 版本 | `python --version` | 3.10+ | | pip 依赖 | `pip list \| grep flask` | flask 已安装 | | 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:8021/api/v1/captcha` | 返回 JSON | | Node.js 版本 | `node -v` | v22+ | | pnpm 版本 | `pnpm -v` | 11.x+ | | 前端服务 | 浏览器访问 `http://localhost:8001` | 显示登录页 | :::tip 温馨提示 如果以上检查项均正常但仍无法运行，建议查看完整错误日志： ```bash # 后端日志 python app.py 2>&1 | tee backend.log # 前端日志 cd ui && pnpm dev 2>&1 | tee frontend.log ``` ::: ## 总结 本章节整理了项目开发中最常见的 10 个问题及其解决方案，涵盖环境配置、服务连接、依赖安装、权限控制和文件上传等方面。遇到问题时，建议先查看终端日志和浏览器控制台的错误信息，结合本章节的排查步骤逐一排除。如果问题仍未解决，可以查阅项目源码或联系开发团队获取支持。