本文档由 g2rain-cms 的 docs/operations/troubleshooting.md 自动同步生成。

# 故障排查

现象	检查项
服务启动失败	JDK 25、MySQL/Nacos 可达性、Profile、外部配置导入和配置凭据
Gateway 404/服务不可用	Nacos 服务名 g2rain-cms、namespace/group、Gateway 路由和健康状态
查询跨组织或无数据	数据隔离开关、DAO 注解、可信 PrincipalContext 与 organId 一致性
文章列表变大或变慢	当前列表/分页是否返回正文、正文筛选、分页大小和 SQL 执行计划
批量标签出现重复	数据库是否有有效关系唯一约束、并发请求与事务冲突处理
删除后编码无法重建	当前普通唯一键永久占位；先确认领域语义，再设计增量迁移
生成器覆盖手写代码	停止生成，使用 Git Diff 恢复/合并；下次在干净工作树和临时分支验证
Jib 镜像成功但功能未验证	build.sh 跳过测试，补跑完整 verify、数据库集成和 Gateway/App 联调