技术选型报告只会写收益，真正的学费单都在事后复盘里。这篇把团队五年里踩过、且有普遍性的坑盘点成册：按升级、Liquibase、JWT、前端、协作、K8s 与部署六类共 14 个，每个坑按”现象 → 根因 → 解法 → 预防”四段写，能对应到系列前文的会给出链接。发布前请对照第 28 篇的 checklist——那份清单就是从这些坑里长出来的。
升级篇
坑 1：手改生成代码，升级时一夜回到解放前
现象：JHipster 7→8 升级，UserResource、SecurityConfiguration 等十几个文件大面积冲突，三向合并的结果没法编译，最终花了四天手工比对，比预估多出整整三天。
根因：早期把业务逻辑直接写进生成文件，生成器再也无法干净重演这些文件（第 22、23 篇的理论根源）。
解法：那次升级时顺手做了”生成代码回归出厂”重构——手写逻辑搬到 biz 层，升级完成后生成文件零手改。
预防：第 23 篇的 CUSTOM 标记 + GENERATED-OVERRIDES.md 登记，CI 守卫拦截无标记的生成文件改动。
坑 2：.jhipster/*.json 丢失，实体没法再生
现象：同事重命名实体后删了旧 JSON，新成员想加字段时发现 jhipster entity 报”实体配置不存在”，只能手写全套分层代码，JDL 与代码从此各说各话。
根因：没把 .jhipster/ 当事实源对待——有人以为它只是生成缓存（早期某些教程确实教人 gitignore 它）。
解法：从 JDL 反向重建——幸好团队后来坚持维护 myapp.jdl，jhipster jdl myapp.jdl --with-entities 整体重生成恢复了对齐。
预防：.yo-rc.json、.jhipster/、*.jdl 强制入库；实体变更流程固定为”改 JDL → 重生成”，review 检查（第 23 篇清单第 3 项）。
Liquibase 篇
坑 3：改了历史 changeset，全环境 checksum 报警
现象：测试环境起不来，日志 Validation Failed Error: checksum mismatch，生产还没升到这版——如果先上了生产，就是三级事故。
根因：有人觉得半年前某 changeset 的 NOT NULL 约束写错了，直接改了历史文件——Liquibase 的核心契约是 changeset 不可变，改一个字，所有已执行环境全部失配。
解法：还原历史文件，新增一个修正 changeset；已污染的环境单独处理（比对确认后 clear-checksums）。
预防：CR 规则”diff 里出现历史 changelog 文件一律打回”；修正一律走新 changeset（第 7 篇）。
坑 4：大表加索引，锁表三十分钟
现象：发布窗口数据库 CPU 飙满，订单表写入全部超时，上游 Kafka 消费堆积，被迫延长发布窗口。
根因：CREATE INDEX（非 CONCURRENTLY）对千万行表持锁，PostgreSQL 上阻塞所有写入；且 changeSet 默认跑在事务里，即使写了 CONCURRENTLY 也会失效。
解法：等发布结束（别中途杀，会留 INVALID 索引）；事后用 CREATE INDEX CONCURRENTLY 重建，changeSet 配 runInTransaction="false"（第 26 篇有完整代码）。
预防：DDL 变更走”生产量级副本演练”（第 28 篇 D2/D3）；大表索引/加列全部 CONCURRENTLY 起手。
坑 5：Liquibase 与 Hibernate validate 互相打架
现象：加了字段，Liquibase 明明跑成功了，启动仍报 Schema-validation: missing column，dev 环境却一切正常。
根因：实体是 --single-entity 重生成的，但 changelog 忘了带；本地 dev 用 H2 时 Hibernate 自动建表掩盖了问题。
解法：补 changeset；把本地 dev 也切到”Liquibase 管全部 DDL”模式。
预防：dev 就用与生产同构的 PostgreSQL + Testcontainers（第 17 篇），让”漏 changelog”在本地第一次启动就炸，而不是在生产。
JWT 篇
坑 6：弱 secret 被扫描器伪造令牌
现象：安全团队通报：我们对外演示环境的 JWT secret 是单词短语（早期图省事），被离线爆破后伪造了 admin 令牌，登录进了后台。
根因：HS512 的安全性完全系于 secret 熵值；占位符默认值没改 + 入了 git 仓库，全员可见。
解法：全员换 openssl rand -base64 192 生成的 secret，走 K8s Secret 注入；泄漏环境的处理是轮换密钥——签名一换，存量令牌全部失效，用户重登即可。
预防：第 21 篇三道防线 + CI 扫描；第 28 篇 S1 项。
坑 7：token 过期后前端不跳转，用户卡死
现象：用户挂机两小时后回来，页面所有按钮点了没反应也不报错，刷新才回登录页；客服收到一波”系统坏了”的工单。
根因：早期版本 API 拦截器对 401 的处理有遗漏——静默吞掉了过期响应；JHipster 生成的拦截器本来处理正确（401 → 清 storage → 跳转），是被我们手改坏的。
解法：恢复生成器出厂的 auth.interceptor 逻辑，401 统一走 logout 流程。
预防：生成代码的安全链路（拦截器、守卫）默认不改（第 23 篇哲学的安全版）；e2e 补”令牌过期”场景（第 17 篇）。
坑 8：多实例时钟漂移，偶发 401
现象：扩到 3 个实例后，随机出现”刚登录就 401”，重启某个实例后消失一阵，极难复现。
根因：某节点 NTP 没同步，时钟快了几十秒，签发与校验落在不同节点时 notBefore/issuedAt 判断失败。
解法：修复节点 NTP；网关层统一签发令牌（第 25 篇鉴权下沉后此问题结构性消失）。
预防：节点时钟偏移监控纳入告警；K8s 节点镜像统一 chrony 配置。
前端篇
坑 9：node 版本不对，构建玄学失败
现象：新人第一天 npm install 直接报一堆 ERESOLVE 与 node-gyp 错误；另一台机器却好好的，同样的代码同样的命令。
根因：JHipster 9.x 要求 Node 22，新机器装的是 18 或其他版本，依赖树里部分包对运行时版本敏感。
解法：统一 nvm/asdf 管理版本，.nvmrc 写明 22 提交进仓库。
预防：项目根维护 .nvmrc 与 package.json 的 engines 字段；CI 用与本地同版本的 node 镜像（第 18 篇）。
坑 10：localStorage 残留旧数据，升级后白屏
现象：8→9 升级后部分老用户页面白屏，控制台报 undefined；新用户或无痕模式一切正常——“我这里没问题”的经典现场。 根因：前端把令牌与用户信息存 localStorage，升级后存储结构变了，旧结构反序列化炸在应用启动期，发生在登录页之前，用户没有”重新登录”的机会来刷新数据。 解法：启动期加 storage 版本检查，结构不符静默清空并跳登录页；补发兼容版本。 预防：凡是 localStorage/IndexedDB 持久化结构，都带版本号与启动校验；升级测试矩阵加”带旧数据的浏览器 profile”用例。
坑 11：升级后路由冲突，懒加载页 404
现象：8→9 升级后 dashboard 路由 404，控制台 Cannot match any routes，且只有深链进入才复现。
根因：我们早年手改过生成的路由注册（把 lazy 路由改成了急加载），9.x 路由结构变化后，手改代码引用的模块路径已不存在。
解法：按第 23 篇原则恢复生成路由结构，定制页面放 features 目录自己注册 lazy 路由。
预防：手改生成文件的每一处都会变成升级的债——这条坑和坑 1 是同一枚硬币的两面，前端版。
协作篇
坑 12：两人同时生成实体，JSON 与 changelog 双冲突
现象：两个分支各自跑了 jhipster entity，合并时 .jhipster/ 的 JSON 好合，但 Liquibase master.xml 的 include 列表和 changelog 文件名冲突，启动报 checksum 不匹配，两个人对着合并结果排查了一下午。
根因：changeset id 含时间戳序号，并行生成必然撞号；include 顺序合并后错乱；两人也都没提交生成前的干净基线。
解法：约定 changeset id 手工规范化（YYYYMMDD-HHMM-作者缩写-描述），冲突时重排 id 再 clear-checksums；此后规定结构性生成前先 rebase 最新 main。
预防：实体建模这类”结构性提交”走串行约定（别在周五下午两人同时建模）；JDL 集中维护，改 JDL 文件而不是各自跑交互式生成，JDL 的合并远比 JSON 加 changelog 好处理；CI 上对 .jhipster/ 目录的并发改动（同一 PR 改动数 > 3）提示 reviewer 重点看 include 顺序与 changeset id 规范。
顺带一个协作细则：团队里生成器版本必须对齐（坑 9 的团队版）。某次两位同事本地分别是 9.0 与 9.1，生成的同一实体文件有细微格式差异，review 时 diff 噪音掩盖了真正的逻辑改动。此后 .nvmrc 之外我们连 generator 版本都写进了 README 的”开发环境”一节，新成员入职脚本一键校验。
K8s 与部署篇
坑 13：liveness 探针查数据库，节点抖动引发连环重启
现象：数据库主从切换的 90 秒里，全部业务 Pod 被逐出重启，一个可控的小故障放大成全站不可用。
根因：liveness 探针配成了带 DB 依赖的深度检查——DB 抖动 → 探针失败 → kubelet 杀 Pod → 重启风暴（重启潮又加重 DB 压力，恶性循环）。
解法：liveness 只探进程存活（/management/health/liveness，JHipster 生成的 health group 天然分离依赖）；依赖健康放 readiness，DB 故障时摘流量但不杀进程。
预防：第 19、28 篇探针原则；把”依赖中断 2 分钟”场景纳入混沌演练。
坑 14：容器时区与日志路径想当然，排障多绕三圈
现象：两起连环小事故：日志时间戳与本地差 8 小时，跨服务排障时对时间线全对不上；某次挂载卷权限变更后应用启动失败，报错是晦涩的 Disk full 假象。
根因：容器默认 UTC 时区，Date.toString 进日志后与北京时间的监控指标错位（第 27 篇提过的一半）；application-prod.yml 里日志路径写死 /var/log/myapp，卷只读或权限不足时 Logback 初始化失败，异常信息有误导性。
解法：统一 -Duser.timezone=UTC 且日志与监控全部 UTC（要改就全改，混用比单用 UTC 更糟）；日志路径改为环境变量注入并对挂载卷做启动前写探测。
预防：基础镜像统一时区与 locale 配置；第 28 篇 checklist 加”日志落盘验证”一行，用一次 kubectl logs + 文件比对确认。
（附赠一个几乎每个团队都遇过的：镜像 tag 用 latest，导致”回滚”回了寂寞——deployment 的 imagePullPolicy 与节点缓存让同一 tag 拉到过不同内容。解法与预防在第 19 篇：一律版本化 tag，见第 28 篇 K1。）
如何使用本篇
三种用法，对应三种读者：
- 新接手 JHipster 的团队：把 14 个坑当”风险预告片”通读一遍，重点看每条的”预防”，直接抄进你们的 CI 规则与发布清单——这些预防项我们全部落地过，没有一条是纸面建议；
- 正在排查问题的工程师：按”现象”关键词检索，每个坑的”根因”与”解法”都给出了可操作的处置步骤，多数解法附了对应专篇链接；
- 团队负责人：重点看结尾的”共性复盘”三分类——它决定你们该先补哪类纪律：生成器契约类靠流程评审，数据契约类靠 CR 规则，默认值类靠 checklist 与 CI。
另外说明取样偏差：能写进这篇的都是”有普遍性”的坑，那些一次性的运维手滑（端口冲突、证书过期忘续）没有收录——它们属于通用运维常识，不属于 JHipster 工程的特异性风险。
写作顺序也即处置优先级：升级与 Liquibase 两篇的坑破坏力最大（直接导致不可部署/锁表），建议新团队优先消化。
坑的共性复盘
14 个坑摊开看，根因只有三类：
| 根因类别 | 坑编号 | 对应纪律 |
|---|---|---|
| 违反”生成代码可再生”契约 | 1、2、11、12 | 第 23 篇隔离哲学 |
| 破坏数据演进的不可变契约 | 3、4、5 | 第 7 篇 Liquibase 纪律 |
| 生产环境的默认值想当然 | 6、7、8、9、10、13、14 | 第 21、28 篇 checklist |
好消息是这些坑几乎全部可以用流程和清单预防，没有一个需要黑科技。这也是我们敢把这套体系推荐给别的团队的原因：学费单虽然长，但每一笔都能转化成 CI 规则或 checklist 的某一行。复盘的固定动作：每季度把当季事故对照本篇归类，新坑补条目，老坑的”预防”项没生效的改写它。
最后给个量化参照：按三类根因统计，第一类（生成代码契约）占了我们早期 60% 的返工，纪律建立后降到接近零；第三类（默认值想当然）至今仍占大头——环境类问题只能靠 checklist 长期压制，无法一劳永逸。这也是第 28 篇被我们称为”活文档”的原因：它和本篇是一对，一个记录学费，一个收缴学费。
系列导航
- 上一篇：生产上线 Checklist
- 下一篇：复盘——JHipster 三年使用总结
- 相关阅读：本文是全系列坑的汇总篇——升级篇呼应第 22 篇与第 23 篇；Liquibase 篇呼应第 7 篇；JWT 篇呼应第 8 篇与第 14 篇；K8s 篇呼应第 19 篇