常见问题

本文汇总商业版后端启动、联调、权限、文件和部署中的高频问题，可作为开发和排查过程中的快速索引。

启动时报数据库连接错误

优先检查：

• DATABASE_URL
• PostgreSQL 是否已启动
• 用户名、密码、数据库名是否和容器配置一致

Swagger 打不开

优先检查：

• 服务是否真的启动在目标端口
• SWAGGER_ENABLED 是否开启
• 反向代理是否屏蔽了 /docs

前端登录成功但后端刷新令牌失败

优先检查：

• Refresh Token Cookie 是否成功写入
• Cookie 域名与 SameSite 配置
• 是否开启 HTTPS 且 Secure 策略匹配

文件上传失败

优先检查：

• 对象存储密钥和地域
• STORAGE_BUCKET
• 允许的 MIME 类型与扩展名
• 代理层请求体大小限制

角色已经给了，但用户还是看不到数据

优先检查是否还存在数据权限范围限制，而不仅仅是菜单权限。

执行脚本时报找不到 dist

部分脚本默认依赖 dist/scripts/*，执行前请先运行：

pnpm build

新增模块后前端仍然接不上

优先检查：

• AppModule 是否注册模块
• DTO 和接口前缀是否正确
• Swagger 是否已出现新接口
• 前端菜单和路由是否同步补齐

检查清单

如果 FAQ 中的问题已全部排除，建议再确认：

• 数据库、默认数据、管理员、角色权限和定时任务初始化状态正常。
• 登录、刷新令牌、菜单权限、API 权限和数据权限链路均可验证。
• 文件存储、健康检查、日志、CORS、Cookie 和生产安全配置已按部署环境记录。