# 常见问题汇总

:::tip 说明
本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。遇到问题时可先查阅本页，再深入各章节详细文档。
:::

## 快速入门

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 端口被占用 | 8021 或 8001 端口被其他进程占用 | [快速入门 FAQ](/zh/volume1/faq) |
| 数据库连接失败 | MySQL 未启动或配置错误 | [快速入门 FAQ](/zh/volume1/faq) |
| Redis 连接失败 | Redis 未启动或密码配置错误 | [快速入门 FAQ](/zh/volume1/faq) |
| pip install 安装失败 | 网络问题或依赖冲突 | [快速入门 FAQ](/zh/volume1/faq) |
| JWT_SALT 未配置 | 环境变量缺失 | [快速入门 FAQ](/zh/volume1/faq) |
| pnpm install 安装失败 | Node.js 版本或网络问题 | [快速入门 FAQ](/zh/volume1/faq) |
| API 请求返回 404 | 路由未注册或代理配置错误 | [快速入门 FAQ](/zh/volume1/faq) |
| 验证码图片不显示 | Pillow 依赖或字体问题 | [快速入门 FAQ](/zh/volume1/faq) |
| 接口返回 403 权限不足 | 权限节点未配置 | [快速入门 FAQ](/zh/volume1/faq) |
| 文件上传失败 | 扩展名不在白名单或大小超限 | [快速入门 FAQ](/zh/volume1/faq) |

## 后端开发

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 字段类型不匹配 | 模型字段与 Schema 类型不一致 | [模块开发 FAQ](/zh/volume2/faq) |
| 唯一性校验遗漏 | Schema 中未定义 validate_ 方法 | [模块开发 FAQ](/zh/volume2/faq) |
| 软删除过滤缺失 | filter() 不自动过滤软删除 | [模块开发 FAQ](/zh/volume2/faq) |
| 分页参数命名不一致 | pageNo/pageSize 命名规范 | [分页规范](/zh/volume7/pagination) |
| 权限节点未配置 | 后端装饰器与前端指令不匹配 | [权限节点联动](/zh/volume4/integration/perm-sync) |

## 前端开发

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 开发环境 API 请求 404 | VITE_PROXY 配置错误 | [前端构建](/zh/volume4/frontend/build) |
| 构建后页面空白 | VITE_PUBLIC_PATH 不一致 | [前端构建](/zh/volume4/frontend/build) |
| 环境变量不生效 | 变量名未以 VITE_ 开头 | [前端构建](/zh/volume4/frontend/build) |
| 热更新不工作 | 修改了 vite.config.ts 需重启 | [前端构建](/zh/volume4/frontend/build) |
| 上传组件不显示 | FLASK_FILE_URL 配置错误 | [文件上传联调](/zh/volume4/integration/upload-sync) |

## 运维部署

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 502 Bad Gateway | 后端服务未启动 | [Nginx 反向代理](/zh/volume6/nginx) |
| 413 Request Entity Too Large | 上传文件超过限制 | [Nginx 反向代理](/zh/volume6/nginx) |
| 刷新页面 404 | 缺少 try_files 配置 | [Nginx 反向代理](/zh/volume6/nginx) |
| Supervisor 启动失败 | 配置文件路径错误 | [Supervisor](/zh/volume6/supervisor) |
| Docker 容器启动失败 | 环境变量或网络配置错误 | [Docker 容器化](/zh/volume6/docker) |
| 数据库迁移失败 | 数据类型不兼容 | [数据库迁移](/zh/volume6/db-migrate) |

## 代码生成器

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| 模块已存在 | 目标目录已有同名模块 | [代码生成器 FAQ](/zh/volume5/faq) |
| 生成代码报错 | 模板语法或配置问题 | [代码生成器 FAQ](/zh/volume5/faq) |
| 字段识别不准确 | 注释或类型推断问题 | [代码生成器 FAQ](/zh/volume5/faq) |

## 工具模块

| 问题 | 说明 | 详细文档 |
|------|------|----------|
| IP 地理位置显示"未知" | xdb 文件不存在或 IP 格式问题 | [IP/UA 解析](/zh/volume4/tools/ip-ua) |
| 富文本 XSS 被过滤 | bleach 清洗规则过严 | [富文本过滤](/zh/volume4/tools/rich-text) |
| 文件上传被拒绝 | 扩展名不在白名单 | [上传配置](/zh/volume4/tools/upload-guide) |

## 排查思路

遇到问题时，按以下顺序排查：

```
1. 查看后端日志（终端输出或 logs/ 目录）
2. 查看浏览器 Network 面板（请求 URL、状态码、响应体）
3. 使用 Postman / Apifox 测试接口
4. 检查 .env 配置（环境变量是否正确）
5. 检查 Redis/MySQL 连接（服务是否启动）
6. 查阅对应模块的详细文档
```

## 总结

常见问题主要集中在环境配置、权限节点、文件上传、部署配置四个方面。遇到问题时优先查看后端日志和浏览器 Network 面板，大部分问题可通过检查 `.env` 配置和接口文档定位原因。