主题
常见问题
按「你卡在哪一层」分组。每条都给了依据:能点的是知识库页面,反引号里的是代码位置,格式为 文件#L行号,可直接在 IDE 里跳。
先记住三个总开关:默认 profile 是
local(application.yaml#L6);外部接口统一前缀/admin-api;未启用模块由DefaultController兜底返回 501,而不是 404。
1. 上手与本地运行
Q1. 本地启动报数据库连不上,先查什么?
答:local 默认连 127.0.0.1:3306/pmforge-jdk8,账号 root/123456。先确认 MySQL 已启动、库已建、sql/mysql/pmforge.sql 已导入,再改配置而不是改代码。
依据:pmforge-server/src/main/resources/application-local.yaml#L51、#L60-L61;DDL 见 sql/mysql/pmforge.sql。
排查:① 用客户端直连同一账号;② 看启动日志第一条 Cannot create PoolableConnectionFactory 的 cause;③ 确认不是连了从库(#L70-L74 的 slave 默认 lazy: true)。
Q2. 启动时报 Redis 连接失败,能先跳过吗?
答:不能整体跳过。验证码、缓存、限流、会话都依赖 Redis(默认 127.0.0.1:6379)。本地至少起一个 Redis;只想临时登录,可把验证码开关关掉,但缓存仍会用到。
依据:application-local.yaml#L85-L87;验证码配置 application.yaml#L103-L118。
Q3. 端口 48080 被占用 / 接口访问 404,是路径写错了吗?
答:服务端口是 48080;所有后台接口在 Controller 的 @RequestMapping 之外还有一层 /admin-api 前缀(由 PmforgeWebAutoConfiguration 注册)。所以 UserController 的 /system/user/create 实际是 POST /admin-api/system/user/create。
依据:application-local.yaml#L2;pmforge-framework/pmforge-spring-boot-starter-web/.../PmforgeWebAutoConfiguration.java#L45-L81。
Q4. 前端请求跨域 / iframe 嵌不进来?
答:跨域由 CORS Filter 处理,顺序在最前;iframe 受 frame-ancestors 限制,local 已放行 localhost:48080。换端口或域名时两边都要改。
依据:WebFilterOrderEnum#L12-L34;application-local.yaml#L170。
2. 账号与权限
Q5. 接口返回 code=401 账号未登录,但 HTTP 是 200?
答:这是设计如此。未登录由 AuthenticationEntryPointImpl 直接写 JSON,HTTP 状态不变,前端按 body.code 判断。检查请求头有没有带令牌(默认 Authorization),以及令牌是否过期。
依据:AuthenticationEntryPointImpl#L32;GlobalErrorCodeConstants#L22。
Q6. 明明登录了,调接口却返回 403?
答:403 是「已登录、无权限」。依次查:① 接口上的 @PreAuthorize 权限点;② 该权限点是否登记在 system_menu.permission;③ 当前用户角色是否勾了该菜单;④ 是否超管(超管直接放行)。权限点没登记菜单,即使角色给了也判 403。
依据:PermissionServiceImpl#L62-L84(超管旁路在 #L83)、#L93-L111(严格模式在 #L96-L98);AccessDeniedHandlerImpl#L37-L40。
Q7. 登录成功但左侧菜单是空的 / 少了很多?
答:菜单来自 GET /system/auth/get-permission-info:先取用户启用角色,再取角色菜单,最后过滤禁用菜单。常见原因:角色被禁用(会被 removeIf 掉)、角色没勾菜单、租户套餐没包含这些菜单。
依据:AuthController#L93-L118;套餐模型见 TenantPackageDO。
Q8. 新建的用户登录不了?
答:先看三处:状态是否为启用(创建时强制 ENABLE)、密码是否经过 passwordEncoder 加密入库、初始化密码配置是否被改。手工插库的用户密码是明文,必然登录失败。
依据:AdminUserServiceImpl#L95-L124(#L112 状态、#L113 加密)、#L64 初始化密码配置键。
3. 数据与租户
Q9. 明明有数据,为什么跨租户取不到?
答:请求必须带 tenant-id 头;TenantContextWebFilter 把它放进 TenantContextHolder,MyBatis 拦截器再给 SQL 加 tenant_id。没有上下文时,要么 400「请求的租户标识未传递」,要么 403「您无权访问该租户的数据」(登录租户 ≠ 请求租户)。
依据:TenantSecurityWebFilter#L67-L87;多租户 的排错清单 #L128-L138。
Q10. 新建的表查出来不带 tenant_id,或者串租户?
答:DO 要继承 TenantBaseDO,拦截器才会拼租户条件;真正的全局表(配置、任务、文件等)才标 @TenantIgnore。两者选错,一个会串数据,一个会多出 tenant_id 导致 SQL 报错。
依据:TenantDatabaseInterceptor#L46-L65;多租户 常见坑 #L113、#L136。
Q11. 新建一张表后,到底要改哪些地方?
答:本仓有固定 7 步:建表(含审计字段与 tenant_id)→ DO + Mapper → Service(+Impl) → Controller + VO → 权限点并登记菜单 SQL → 跨模块 api(需要时)→ 补功能卡并跑 npm run docs:gen。
依据:系统管理模块 的「扩展点」#L119-L129。
Q12. 数据被逻辑删除了,怎么恢复?
答:本仓删除默认是逻辑删除(deleted 置 1),查询自动过滤。恢复就是把这行的 deleted 改回 0;没有内置回收站,生产上建议先备份再改。
依据:BaseDO#deleted;表结构见 sql/mysql/pmforge.sql#L5040。
Q13. 为什么有的 SQL 多出 tenant_id 直接报错?
答:全局表被误当租户表。给对应 DO 标 @TenantIgnore(如 ConfigDO、JobDO),或把表名加入 pmforge.tenant.ignore-tables。
依据:多租户 #L136;TenantDatabaseInterceptor#L46-L65。
4. 开发与调试
Q14. 调一个接口返回 404,是模块没启用吗?
答:要分清两种。未启用模块的路径由 DefaultController 兜底,返回的是 501「功能未实现/未开启」,并提示改根 pom 与 server pom;真正的 404 通常是漏了 /admin-api 前缀、路径拼错、方法不对。先看响应体 code,再看映射日志。
依据:DefaultController#L15、#L24-L28;GlobalErrorCodeConstants#L32;PmforgeWebAutoConfiguration.java#L45-L81。
Q15. 定时任务在本地就是不执行?
答:local 把 QuartzAutoConfiguration 排除掉了,所以没有 Scheduler Bean;任务框架仍会装配,但只打一行「定时任务 - 已禁用」,调用管理接口会抛 501。要在本地验证,去掉 application-local.yaml 里的 exclude,并确认 spring.quartz 配置与 Quartz 表就绪。
依据:application-local.yaml#L10、#L95-L118;starter-job #L42、#L70。
Q16. 上传文件报「客户端(master) 不能为空」或「上传文件过大」?
答:前者是没配主文件客户端:到「文件配置」里建一条并设为主配置(infra_file_config)。后者受 max-file-size=16MB、max-request-size=32MB 限制,超限由全局异常处理返回「上传文件过大,请调整后重试」。
依据:FileServiceImpl#L96-L97;application.yaml#L15-L16;GlobalExceptionHandler#L217-L220。
Q17. 代码生成后,文件目录和本仓对不上?
答:生成器按上游「多模块 + 多前端」布局产出路径(pmforge-module-xxx-server/...、pmforge-ui-xxx-vue3/...),本仓是扁平模块 + 单个 pmforge-ui/。不要直接解压覆盖:手工移动到对应包,改 basePackage 与前端目录。另有三个固定收尾:errorcode.vm 片段并入 ErrorCodeConstants、菜单 SQL 手工执行、生成后先编译。
依据:基础设施模块 已知坑 #L159-L160。
Q18. 第三方服务的密钥存在哪里?
答:短信、邮件、支付、对象存储的密钥都在数据库配置里(system_sms_channel、system_mail_account、pay_app、infra_file_config 等表),由 mybatis-plus.encryptor.password 对应的 AES 加密器落库加密;仓库里的 application*.yaml 不保存这些业务密钥。
依据:apps/pmforge-server/src/main/resources/application.yaml(mybatis-plus.encryptor);基础设施模块。
Q19. 任务保存成功,执行时报 NoSuchBeanDefinitionException?
答:handler_name 必须是 Spring Bean 名,不是类名。createJob 只校验 cron,updateJob 才去容器里取 Bean;所以「保存成功、执行失败」很常见。把 @Component("demoJob") 的名字和页面上的 handler 名对齐。
依据:基础设施模块 #L156;starter-job #L68。
5. 部署与运维
Q20. 上生产要改哪些配置?
答:至少五类:profile(默认 local 必须换)、数据库主从、Redis、租户开关与忽略名单、上传大小与安全响应头。密钥类的(OAuth2、短信、邮件、模型)走环境变量或配置中心,不要提交到仓库。
依据:application.yaml#L6、#L311-L328;application-local.yaml#L51-L87。
Q21. 健康检查与监控指标在哪看?
答:Actuator 根路径是 /actuator;指标由 Micrometer 采集,micrometer-registry-prometheus 已在 monitor starter 中引入;Spring Boot Admin 客户端也在这个 starter 里。生产建议只暴露 health/info。
依据:application-local.yaml#L148-L159;PmforgeMetricsAutoConfiguration。
Q22. 多实例部署后,WebSocket 推送有时收不到?
答:默认 sender-type: local 只在当前 JVM 内广播。多实例要改成 redis / rabbitmq / kafka 等共享通道,并确认每个实例的会话表与租户上下文一致。
依据:application.yaml#L282-L294;消息与实时推送 #L79。
Q23. 集群里定时任务重复执行 / 只跑一个租户?
答:重复执行看 Quartz 是否用 jdbc 存储(本仓默认配了),以及是否给 Job 加了并发限制;只跑一个租户看有没有 @TenantJob。注意重试是「立即 refire」,会占用同一个 Quartz 线程。
依据:application-local.yaml#L95-L118;starter-job #L69、#L71;定时任务与异步 #L113。
Q24. 数据库版本管理用 Flyway 还是 Liquibase?
答:都没用。本仓没有引入 Flyway/Liquibase,DDL 集中在 sql/mysql/pmforge.sql,由人工执行;改表要同时改 SQL 与 DO,并在 PR 里说明执行顺序。
依据:sql/mysql/pmforge.sql(system_users 在 #L5021);依赖清单见 依赖与版本。
6. 文档与知识库
Q25. 首页的「328 个接口 / 48 张表」怎么更新?
答:这些数字来自生成物,不要手改。改完代码后跑 npm run docs:gen 重新扫描;npm run docs:check 只做校验,生成物过期会让 CI 失败。
依据:package.json#L10-L11;系统管理模块 #L129。
Q26. 生成物(接口索引、功能卡)能直接改吗?
答:不能。顶部有 <!-- auto-generated --> 的文件由脚本产出,手改会被下次生成覆盖。要改内容,改模板或扫描脚本;要改功能卡叙事,改卡片模板后重新生成。
依据:如何使用本知识库;script/docs/scan-knowledge.mjs。
Q27. 新写的 guide 页面在侧边栏看不到?
答:/guide/ 侧边栏是按目录自动生成的,新文件会被扫到;但站点根侧边栏是硬编码的,只列了 00/01/02。新增页面想出现在根侧边栏,需要改 .vitepress/config.mts(本次不涉及)。
依据:docs/.vitepress/config.mts;如何使用本知识库。
7. 还是没解决
- 先回 术语表 对齐概念,很多「报错」其实是叫法不同。
- 再按 阅读路径 的路线 C 走一遍横切机制。
- 需要看真实链路:SYS-USER-01 与 请求处理链路。
- 想自己动手复现:练习与自测。