86 lines
4.5 KiB
Markdown
86 lines
4.5 KiB
Markdown
# 常见问题汇总
|
||
|
||
:::tip 说明
|
||
本页汇总了项目各模块的常见问题及解决方案，按场景分类索引。遇到问题时可先查阅本页，再深入各章节详细文档。
|
||
:::
|
||
|
||
## 快速入门
|
||
|
||
| 问题 | 说明 | 详细文档 |
|
||
|------|------|----------|
|
||
| 端口被占用 | 8041 或 8001 端口被其他进程占用 | [快速入门 FAQ](/zh/volume1/faq) |
|
||
| 数据库连接失败 | MySQL 未启动或配置错误 | [快速入门 FAQ](/zh/volume1/faq) |
|
||
| Redis 连接失败 | Redis 未启动或密码配置错误 | [快速入门 FAQ](/zh/volume1/faq) |
|
||
| pip install 安装失败 | 网络问题或依赖冲突 | [快速入门 FAQ](/zh/volume1/faq) |
|
||
| JWT_SECRET 未配置 | 环境变量缺失 | [快速入门 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) |
|
||
| 唯一性校验遗漏 | 未配置 unique_fields | [模块开发 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-region) |
|
||
| 限流不生效 | RATE_LIMIT_ENABLED 未开启 | [IP/UA 解析](/zh/volume4/tools/ip-region) |
|
||
| 富文本 XSS 被过滤 | bleach 清洗规则过严 | [富文本过滤](/zh/volume4/tools/rich-text) |
|
||
| 文件上传被拒绝 | 扩展名不在白名单 | [上传配置](/zh/volume4/tools/upload-guide) |
|
||
|
||
## 排查思路
|
||
|
||
遇到问题时，按以下顺序排查：
|
||
|
||
```
|
||
1. 查看后端日志（终端输出或 logs/ 目录）
|
||
2. 查看浏览器 Network 面板（请求 URL、状态码、响应体）
|
||
3. 查看 Swagger 文档（http://127.0.0.1:8041/docs）
|
||
4. 检查 .env 配置（环境变量是否正确）
|
||
5. 检查 Redis/MySQL 连接（服务是否启动）
|
||
6. 查阅对应模块的详细文档
|
||
```
|
||
|
||
## 总结
|
||
|
||
常见问题主要集中在环境配置、权限节点、文件上传、部署配置四个方面。遇到问题时优先查看后端日志和浏览器 Network 面板，大部分问题可通过检查 `.env` 配置和 Swagger 文档定位原因。
|