10.2 容器兼容性与跨环境部署

10.2 容器兼容性与跨环境部署

本节摘要：同一个部署包，在开发、预发、生产三台环境上行为可能完全不同：命名空间断代决定包能不能启动，容器实现差异决定细节行为，配置合并规则决定哪份声明说了算。本站把这三类暗礁逐一标出，交付一张兼容矩阵与一次三环境部署演练的完整记录——跨环境部署的安全感，来自演练而非祈祷。

同一个包，三台容器

第一道坎在 1.2 节埋过伏笔：命名空间断代。规范移交开源基金会后，包名前缀从 javax 逐步迁往 jakarta，断代两侧的容器与代码互不相认——javax 代码投到新一代容器，所有类加载失败；jakarta 代码投到老容器，同样全盘皆输。这不是配置问题，是物理断层，唯一的解法是配对：包的命名空间与容器的世代必须一致。青梧书肆全站 javax 世代，1.3 节选容器 9.x 的决策在这里兑现价值。

第二道坎是容器的"方言现象"。规范是蓝图，实现是建筑，各家容器在蓝图之上各有取舍：通用型容器以严格遵循规范著称，可移植性最好；轻量嵌入式容器模块化程度高、测试友好，但灵活性带来自由也带来依赖；全栈应用服务器集大成，连页面里都能直接注入容器托管的组件——代价是重量级与迁移成本。选型纪律在 1.3 节定过了，这里补的是认知纪律：用了哪家容器的私有能力，就在文档里记一笔"容器锁定债"，将来迁移时按单清偿。

三类容器与三代规范的匹配关系，画成矩阵最直观。

图10-2 容器兼容矩阵

配置的双刃：描述文件与注解

第二道坎藏在配置合并规则里。组件注册有两套并行体系：集中式部署描述文件（3.2 节的编译期配置是它的近亲）与标注在类上的注解。两套并存时，描述文件的声明覆盖注解——至少主流容器的裁决如此，但个别实现并非一致，这正是方言现象的一部分。风险场景很具体：某个控制器注解声明的地址在开发环境好好的，生产环境一份老描述文件里的同名映射把它静默覆盖，流量从此打到没人维护的旧实现上。

防这道坎的纪律有二。其一，一应用一套注册体系：老站既然靠描述文件活着，新组件注册也走描述文件，别两套混用；确实要用注解，先全站搜索描述文件确认无同名映射。其二，页面级全局设置（比如编码属性组、忽略开关）只有描述文件这一条路，注解体系里根本没有对应物——7.2 节的错误页映射同理。把这些"只有一条路"的配置项列成清单，跨环境排障时先查它们。

版本矩阵与部署纪律

跨环境的最后一道坎是配置漂移。代码相同、环境不同，行为差异的第一嫌疑人永远是配置：连接池参数、错误页映射、编码设置、容器自身的页面属性组。纪律是把"应用版本、容器版本、运行时版本、关键配置项"四元组写进一张版本矩阵表，随交接文档走；任何环境变更先改表、再动手。

案例：交接周的三环境演练。

背景：青梧书肆的部署链是开发、预发、生产三台环境。交接验收要求新同事独立完成一次从构建到预发的完整部署，你陪跑记录。

操作：新同事本地构建出部署包（10.1 节的声明式构建保证包一致），投向预发环境。第一次部署后预发异常：页面全部原样输出 EL——正是 1.2 节那出戏。按兼容矩阵排查：包世代无误、容器世代无误，最后发现预发容器为兼容另一个老应用，全局配置里开着忽略 EL 的属性组，按路径模式覆盖了整个应用。

结果：在部署描述文件里为本应用显式声明关闭该开关（应用级声明覆盖容器级默认），预发恢复正常；版本矩阵表上给预发环境补记这条特殊配置。

解读：这次演练完美演示了跨环境排障的固定套路：世代配对查断层，行为异常查方言，逐项排除后查环境私有配置。也验证了矩阵表的价值——预发这条特殊配置若早记录在案，十分钟就能定位；实际上它消耗了新同事两个小时。表格的成本是维护，收益是别人的两小时，这笔账怎么算都值。

变式：如果站点未来走向容器化部署，环境漂移会被镜像机制大幅压缩——环境定义本身成为版本化产物。但对 JSP 站点有个专门的坑要预警：页面编译依赖真实路径，某些打包形态下路径解析会失效，9.1 节的部署形态约束就是同一件事的另一面。容器化前先验证页面编译链路，别把这条坑带进新世界。

⚠️ 常见坑：把"开发环境没这问题"当成排障结论。三个环境的容器版本、配置文件、数据规模各不相同，开发环境的通过只证明代码无低级错误，不证明行为一致——环境间的一切差异都要落到版本矩阵表上，落不到纸面的差异迟早以故障形式显形。

灰度与回滚的部署纪律

三环境演练之上，还有两条部署纪律值得写进交接文档。其一，灰度顺序固定：任何部署先预发、再小流量、再全量，三级火箭不许跳级——跳级的诱因永远是"改动很小"，而事故记录里"改动很小"四个字出现频率最高。其二，回滚动作演练过：回滚不是"把旧包重新发一遍"这么想当然——数据库结构变更过的部署，旧包配新库可能直接瘫。青梧书肆的规矩是每次涉及结构变更的部署，回滚脚本随部署包一起准备，并在预发环境真演练一次回滚。没演练过的回滚方案等于没有回滚方案。这两条纪律与版本矩阵表共同构成部署安全的三角：矩阵管配对、灰度管节奏、回滚管退路。

部署核对单的诞生

三环境演练跑完，顺手产出一件比演练本身更持久的工具：部署核对单。它记录一次标准部署的全部动作与判定点——构建命令与预期产物、投递目标与路径、部署后的三个验证页面、日志里应出现的关键字、版本自述页面应显示的版本号。每一步都写成"动作加判定"的对仗格式：做了什么、看到什么才算成功。核对单的价值在两个场景：日常部署时照单走一遍，漏步骤的概率趋近于零；事故复盘时对照单查，哪一步的判定没满足一目了然。青梧书肆的核对单最初只有七行，两次事故后涨到十二行——每行背后都是一次踩坑。这份单子随交接文档移交，新同事第一次独立部署就照着它走，全流程零求助。部署纪律的演进史，就是核对单的生长史。

本节要点回顾

• 世代配对是第一道闸：javax 与 jakarta 两侧互不相认，包与容器的世代必须一致；
• 方言现象客观存在：通用容器保可移植、轻量容器重灵活、全栈服务器样样通但重，私有能力记账为锁定债；
• 一套注册体系：描述文件与注解并行时描述文件覆盖优先，新组件注册别混用两套；
• 版本矩阵表：应用、容器、运行时、关键配置四元组随文档走，变更先改表再动手；
• 三步排障套路：查断层、查方言、查环境私有配置，演练一次胜过文档十页。

部署线走完，最后是质量线：测试怎么分层、流水线怎么搭、规范墙挂到哪。下一站给全书收尾。