Skip to content

常见问题 ​

按「你卡在哪一层」分组。每条都给了依据:能点的是知识库页面,反引号里的是代码位置,格式为 文件#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. 还是没解决 ​