Become a sponsor
常见问题汇总
说明
本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。遇到问题时可先查阅本页，再深入各章节详细文档。
快速入门
| 问题 | 说明 | 详细文档 |
|---|---|---|
| 端口被占用 | 8031 或 8001 端口被其他进程占用 | 快速入门 FAQ |
| 数据库连接失败 | MySQL 未启动或配置错误 | 快速入门 FAQ |
| Redis 连接失败 | Redis 未启动或密码配置错误 | 快速入门 FAQ |
| pip install 安装失败 | 网络问题或依赖冲突 | 快速入门 FAQ |
| JWT_SALT 未配置 | 环境变量缺失 | 快速入门 FAQ |
| pnpm install 安装失败 | Node.js 版本或网络问题 | 快速入门 FAQ |
| API 请求返回 404 | 路由未注册或代理配置错误 | 快速入门 FAQ |
| 验证码图片不显示 | Pillow 依赖或字体问题 | 快速入门 FAQ |
| 接口返回 403 权限不足 | 权限节点未配置 | 快速入门 FAQ |
| 文件上传失败 | 扩展名不在白名单或大小超限 | 快速入门 FAQ |
后端开发
| 问题 | 说明 | 详细文档 |
|---|---|---|
| 字段类型不匹配 | 模型字段与 Schema 类型不一致 | 模块开发 FAQ |
| 唯一性校验遗漏 | 未配置 unique_fields | 模块开发 FAQ |
| 软删除过滤缺失 | filter() 不自动过滤软删除 | 模块开发 FAQ |
| 分页参数命名不一致 | pageNo/pageSize 命名规范 | 分页规范 |
| 权限节点未配置 | 后端装饰器与前端指令不匹配 | 权限节点联动 |
前端开发
| 问题 | 说明 | 详细文档 |
|---|---|---|
| 开发环境 API 请求 404 | VITE_PROXY 配置错误 | 前端构建 |
| 构建后页面空白 | VITE_PUBLIC_PATH 不一致 | 前端构建 |
| 环境变量不生效 | 变量名未以 VITE_ 开头 | 前端构建 |
| 热更新不工作 | 修改了 vite.config.ts 需重启 | 前端构建 |
| 上传组件不显示 | FLASK_FILE_URL 配置错误 | 文件上传联调 |
运维部署
| 问题 | 说明 | 详细文档 |
|---|---|---|
| 502 Bad Gateway | 后端服务未启动 | Nginx 反向代理 |
| 413 Request Entity Too Large | 上传文件超过限制 | Nginx 反向代理 |
| 刷新页面 404 | 缺少 try_files 配置 | Nginx 反向代理 |
| Supervisor 启动失败 | 配置文件路径错误 | Supervisor |
| Docker 容器启动失败 | 环境变量或网络配置错误 | Docker 容器化 |
| 数据库迁移失败 | 数据类型不兼容 | 数据库迁移 |
代码生成器
| 问题 | 说明 | 详细文档 |
|---|---|---|
| 模块已存在 | 目标目录已有同名模块 | 代码生成器 FAQ |
| 生成代码报错 | 模板语法或配置问题 | 代码生成器 FAQ |
| 字段识别不准确 | 注释或类型推断问题 | 代码生成器 FAQ |
工具模块
| 问题 | 说明 | 详细文档 |
|---|---|---|
| IP 地理位置显示"未知" | xdb 文件不存在或 IP 格式问题 | IP/UA 解析 |
| 限流不生效 | RATE_LIMIT_ENABLED 未开启 | IP/UA 解析 |
| 富文本 XSS 被过滤 | bleach 清洗规则过严 | 富文本过滤 |
| 文件上传被拒绝 | 扩展名不在白名单 | 上传配置 |
排查思路
遇到问题时，按以下顺序排查：
1. 查看后端日志（终端输出或 logs/ 目录）
2. 查看浏览器 Network 面板（请求 URL、状态码、响应体）
3. 查看 Swagger 文档（http://127.0.0.1:8031/docs）
4. 检查 .env 配置（环境变量是否正确）
5. 检查 Redis/MySQL 连接（服务是否启动）
6. 查阅对应模块的详细文档总结
常见问题主要集中在环境配置、权限节点、文件上传、部署配置四个方面。遇到问题时优先查看后端日志和浏览器 Network 面板，大部分问题可通过检查 .env 配置和 Swagger 文档定位原因。