LuckyColor SaaS Docs

Appearance

部署排查清单 ​

这页怎么用 ​

当 LuckyColor 在本地、测试环境或生产环境“能启动但不能用”时，最容易浪费时间的不是修问题，而是不知道先查哪里。

这页按常见现象给出排查顺序，尽量让你先查最可能的点。

现象一：后端起不来 ​

优先检查：

  1. .env 是否存在
  2. DATABASE_URL 是否正确
  3. REDIS_URL 是否可连接
  4. JWT_SECRET 是否为空
  5. 端口 3001 是否被占用

如果启动日志里出现环境变量校验错误，先解决环境变量，再继续排查业务问题。

现象二：pnpm db:setup 失败 ​

优先检查：

  • MySQL 是否已经启动
  • luckycolor_admin 数据库是否可访问
  • DATABASE_URL 中的用户名、密码、端口是否正确
  • 当前 MySQL 是否允许连接

常见误区：

  • Docker 里 MySQL 启了，但宿主机端口映射没成功
  • 改了数据库密码，却忘了同步到 .env

现象三：Swagger 打不开 ​

优先检查：

  • 后端是否真的启动成功
  • 如果是 NestJS：SWAGGER_ENABLED 是否为 true
  • 如果是 Spring Boot：http://127.0.0.1:3001/api/docs 是否能直接访问
  • 如果是 NestJS：http://127.0.0.1:3002/docs 是否能直接访问
  • 如果有 Nginx，/docs/ 代理是否正确

现象四：前端能打开，但接口全部失败 ​

优先检查：

  • 前端 VITE_API_PROXY_TARGET 是否正确
  • 后端是否监听当前模式对应端口
  • 后端接口是否都带 /api
  • 浏览器请求是走开发代理，还是走线上 Nginx

开发环境常见原因：

  • 前端代理仍指向旧环境
  • 后端没启动，但前端静态页面仍能打开

现象五：登录失败 ​

按这个顺序查：

  1. 是否先完成验证码验证
  2. 默认账号是否存在
  3. Redis 是否可用
  4. 当前租户是否正确
  5. 用户、角色、租户状态是否正常

特别注意：

  • LuckyColor 默认启用了登录验证码
  • 前端开发环境默认会带 x-tenant-id: tenant_001

现象六：登录成功，但菜单为空 ​

优先检查：

  • /api/auth/access 是否返回了 menuTree
  • 当前角色是否绑定了菜单
  • 菜单是否被停用或隐藏
  • 当前租户是否正确

这类问题通常不是前端样式问题，而是权限或租户上下文问题。

现象七：页面能进，但按钮不显示 ​

优先检查：

  • /api/auth/button-permissions 返回是否包含对应权限码
  • 当前角色是否有按钮权限
  • 页面是否使用了权限控制逻辑

现象八：接口返回 403 ​

403 在 LuckyColor 里通常不只是“没登录”，还可能是：

  • 菜单权限不足
  • 按钮权限不足
  • 数据权限不足
  • 当前租户已禁用、冻结或过期
  • 当前账号不能访问该租户

建议先看返回的业务错误码，再查对应角色、菜单、租户状态。

现象九：列表数据不对或比预期少 ​

优先检查：

  • 当前租户是否正确
  • 当前角色的 data_scope
  • 是否存在自定义部门数据范围
  • 查询条件是否把数据过滤掉了

尤其是用户、角色、部门这类接口，很容易被数据权限影响。

现象十：生产环境刷新页面 404 ​

原因几乎总是 Nginx 没有做 SPA 回退。

正确配置：

nginx
location / {
    try_files $uri $uri/ /index.html;
}

现象十一：前端正常，接口 502 ​

如果有 Nginx，优先检查：

  • Nginx 代理的目标地址是否正确
  • 后端进程或容器是否仍在运行
  • 宿主机和容器网络是否连通
  • /api/ 的 proxy_pass 是否写对

现象十二：上传文件失败 ​

优先检查：

  • 后端文件目录是否有写权限
  • Nginx 是否限制了 client_max_body_size
  • 容器部署时文件目录是否已挂载持久化
  • 多实例时文件是否共享

现象十三：Docker Compose 启动失败 ​

优先检查：

  • 构建上下文路径是否和服务器实际目录一致
  • Dockerfile 路径是否正确
  • Nginx 配置挂载路径是否存在
  • 证书路径是否真实存在
  • MySQL、Redis、server、admin 依赖关系是否正确

当前示例文件中有很多相对路径占位，复制到新环境后必须手工调整。

现象十四：HTTPS 配好了但页面异常 ​

优先检查：

  • 域名是否已经正确解析
  • 证书是否有效且可被 Nginx 读取
  • 前端是否还有 HTTP 资源，导致浏览器拦截混合内容
  • server_name 是否与访问域名一致

推荐的最小排查顺序 ​

不论遇到什么问题，都建议先走这条最小链路：

  1. GET /api/health 是否正常
  2. Swagger 是否能打开
  3. 登录页是否能打开
  4. 是否能成功登录
  5. /api/auth/access 是否有菜单树
  6. 用户管理和租户管理是否能正常列表

如果这六步都能通过，说明系统主体已经跑通。

适合重点看日志的位置 ​

位置适合看什么
后端控制台日志环境变量、数据库连接、启动异常
Nginx 日志反代失败、404、502、证书问题
浏览器 Network代理路径、错误码、请求头、返回结构
Swagger 调试DTO 和接口契约是否一致

一句话建议 ​

LuckyColor 最常见的问题并不是“代码逻辑错了”，而是：

  • 环境变量没对齐
  • 租户上下文没对齐
  • 权限没配齐
  • 反向代理没配全

排查时先查这四类，效率会高很多。

Built with VitePress for LuckyColor SaaS.

Copyright © 2026 LuckyColor