一、起源:部署对象从主机变成编排系统

1.1 迁移中被同时替换的前提

Java 应用传统的部署形态是虚拟机或物理机上的一份发布包:进程由 systemd 或启动脚本拉起,运行在整机资源视图下,进程存活时间以周或月计,发布节奏由人工决定。迁移到容器编排后,同一份制品被包装为镜像,由编排系统决定在何处运行、开多少实例、何时替换。

变化的实质不是"多了一层封装",而是若干前提被同时替换:

维度 虚拟机部署 容器编排部署
资源视图 进程看到整机 CPU 与内存 进程受 cgroup 限额约束,但部分接口仍呈现宿主视角
生命周期 由运维与启动脚本掌握 由编排层的探针与控制器掌握,进程无法自定
实例身份 主机名与 IP 固定,可长期存在 实例名与地址随重建变化,默认不被依赖
重建频率 低,故障时人工替换 高,扩缩容、发布、节点回收都触发重建
交付物 发布包加环境配置 不可变镜像加外部注入配置
部署耗时 主要消耗在包分发与启动 还包含镜像拉取、解包与就绪判定

前四项属于原理层面的差异,后两项属于工程层面的差异。二者叠加得到一条贯穿全篇的结论:原本"启动一次、长期调整"的过程,变成"反复启动、每次都要正确"的过程。

1.2 资源视图的变化

容器的资源约束由 cgroup 实施,作用对象是进程组而非"机器"。虚拟机上的容量判断依据(总内存、核数、负载)在容器内不再直接可用:

  1. 部分接口反映宿主机而非限额。 在容器内执行 free、nproc、读取 /proc/meminfo,得到的是宿主视角的数据。以这些数值做容量规划会高估可用资源,典型后果是把堆上限设为"宿主内存的一半"而远超容器限额。
  2. JVM 的默认推导已改为读取 cgroup 限额。 JDK 10 起容器感知默认开启(JDK 8u191 之后版本回移),默认堆上限由限额按比例推导。但默认比例偏保守(MaxRAMPercentage 默认 25%),不显式设置会浪费限额;显式设置时又必须为堆外部分留出空间。
  3. CPU 限额以周期配额形式生效,表现是节流而非"变慢一点"。 超出配额的任务被强制推迟到下一个周期,外部表现为周期性延迟毛刺;容器内看到的可用核数可能大于配额,按可见核数推导的线程数会与配额失配。

1.3 生命周期由编排层接管

探针与控制器把进程生命周期拆成三段,每段由不同机制判定:

  • 启动期:由启动探针判定是否完成启动,未完成前不执行存活与就绪判定。
  • 运行期:就绪探针决定是否接收流量,存活探针决定是否重启容器。
  • 终止期:收到终止信号后进入宽限期,宽限期内进程应自行完成清理,超时被强制终止。

这三段的判定条件一旦写错,后果不是"检测不到问题",而是主动制造问题:把下游依赖状态写进存活探针,下游抖动会导致本服务全量重启;就绪探针检查项过重,会导致实例在流量高峰期反复摘除与引入。

1.4 实例频繁重建带来的新约束

编排系统默认把实例当作可随时替换的单元。副本被驱逐、节点被回收、镜像被升级、配置被更新,都会以"删旧建新"的方式完成。这一模型对 Java 应用提出三项额外要求:

  1. 状态不能留在进程内。 本地会话、本地缓存、本地文件在重建后消失,多实例之间也不共享。
  2. 启动必须可重复且可判定。 启动过程不能依赖人工介入,且必须有一个明确的"可以接流量"的信号。
  3. 启动与镜像获取时间进入体验指标。 扩容、故障转移、发布推进的速度都受这两项制约。启动慢的应用在滚动发布中表现为发布长时间不推进,在故障转移中表现为容量恢复滞后。

1.5 本文定位

本篇讨论 Java 应用在容器编排环境中的部署实现:镜像如何构建、JVM 参数如何与限额配比、探针与优雅上下线如何配置、资源与调度如何设定、发布与回滚如何执行,以及部署阶段的常见问题如何排查。

线上故障发生后的取证、判读与调优流程,以及容器内存与 CPU 视图差异的判定方法,已在 Java 应用诊断与部署调优 中完整给出,本篇只在其基础上补充部署侧的衔接说明,不重复诊断方法本身。容器与编排的平台机制、命令与平台侧排障见 Kubernetes 集群运维 与 容器排障与命名空间诊断。


二、原理

2.1 容器中的资源视图

2.1.1 cgroup 限额的生效路径

容器的资源限制由 cgroup 实施,与 JVM 相关的两条链路是:

memory.max(cgroup v2) / memory.limit_in_bytes(cgroup v1)
    → 进程组内存总量超过上限
    → 触发 cgroup 内 OOM,内核选择并终止进程
    → 容器退出码 137,OOMKilled 标记为真

cpu.max(cgroup v2) / cpu.cfs_quota_us + cpu.cfs_period_us(cgroup v1)
    → 每个周期内可运行的时间片用尽
    → 进程组内全部任务被强制推迟到下一周期
    → 表现为延迟毛刺,而非使用率下降

两条链路的差异决定了现象差异:内存超限是"被杀",CPU 超限是"被拖慢"。 前者进程直接消失,日志可能无任何输出;后者进程仍在运行,只是响应时间出现周期性抖动。

2.1.2 JVM 可见资源与真实限额的差异

JVM 在容器中读取的内存与 CPU 信息有三类来源,取值口径并不一致:

来源 反映的内容 偏差风险
/proc/meminfo、free 宿主机内存 容器内仍可能读到宿主总量,高估可用内存
/proc/cpuinfo、nproc 宿主机(或 cgroup 可见)核数 可能大于 CPU 配额,导致 GC 与 JIT 线程数超标
cgroup 限额文件 容器限额 容器感知开启时,默认堆容量按此推导

容器感知解决的是默认堆容量的推导,没有解决线程数与堆外上限的推导。因此显式设置 -XX:ActiveProcessorCount、-XX:ParallelGCThreads、-XX:MaxMetaspaceSize、-XX:MaxDirectMemorySize、-XX:ReservedCodeCacheSize 在容器中是常规做法,而非优化选项。

2.1.3 进程内存与容器限额的关系

容器的内存限额约束的是整个进程组,而不是堆。二者的关系是:

进程内存总量 =
      堆(-Xmx)
    + 元空间(-XX:MaxMetaspaceSize)
    + 压缩类空间(-XX:CompressedClassSpaceSize)
    + 线程栈(-Xss × 线程数)
    + 直接内存(-XX:MaxDirectMemorySize)
    + 代码缓存(-XX:ReservedCodeCacheSize)
    + JVM 自身结构与 GC 辅助结构
    + JNI 与本机库占用

容器限额必须覆盖以上总和,且需留出余量。

由此得到三条部署侧的判据:

  1. 堆上限不能按限额的高比例设置。 按限额的 90% 设置堆,堆内正常时容器仍可能因堆外部分超限而被终止。
  2. 堆外各项必须显式设上限。 元空间、直接内存、代码缓存的默认值在部分版本中接近无上限,泄漏会直接耗尽本地内存。堆外构成可借助 NMT 观察,方法见 linux: 内存管理 的 Java 堆外内存章节。
  3. 判断"堆内还是堆外"的顺序是先比三项数值。 容器限额、进程 RSS、堆用量三项数值对比之后,才能确定方向。堆内尚有余量而进程已被终止,说明问题在堆外或限额设置。

容器内 OOM 的字段判读(State.OOMKilled、memory.events 中的 oom_kill 计数、内核日志中的 Memory cgroup out of memory)以及宿主全局 OOM 的区分方式,见 容器排障与命名空间诊断 的资源限制一节;堆容量本身的推导依据与堆外构成的完整清单见 JVM 内存结构与垃圾回收 的生产调优一节。

2.1.4 CPU 配额导致的节流表现

CPU 配额不足的现象具有辨识性,判读依据集中在三个计数器:

字段 含义 判读
nr_periods 已过去的调度周期总数 分母
nr_throttled 被节流的周期数 与 nr_periods 的比值反映节流频率
throttled_usec 累计被强制等待的时间 观测窗口内持续增长说明配额是瓶颈

典型表现是:容器监控中的 CPU 使用率稳定贴在配额上限附近,接口延迟呈周期性毛刺,GC 停顿与堆占用均正常,线程转储中工作线程处于可运行状态但推进缓慢。

此时的处理方向是降低并发度或提高配额,而不是增加线程数。线程数增加只会让更多任务在同一周期的配额内争抢,加剧排队与上下文切换。相关字段的采集命令与处置方式见 容器排障与命名空间诊断。

2.2 镜像分层与启动时间

2.2.1 镜像层与缓存命中

镜像由只读层堆叠而成,容器运行时在最上方叠加一个可写层。每一条构建指令生成一层,层的身份由自身内容与父层共同决定。缓存命中的条件是该指令文本未变且其输入内容未变,同时所有父层均命中缓存。

这一规则解释了 Java 项目构建顺序的意义:

FROM ...                      第 1 层
COPY pom.xml .                第 2 层,依赖声明
RUN mvn dependency:go-offline 第 3 层,依赖产物,仅在第 1、2 层未变时命中
COPY src ./src                第 4 层,业务代码
RUN mvn package               第 5 层,仅在第 1 至 4 层均未变时命中

若把源码与依赖声明一起复制(COPY . .),业务代码的任意一次修改都会使第 2 层之后全部失效,依赖需重新下载。把二者分开后,日常提交只会在第 4、5 层产生新层。

2.2.2 依赖层与业务层分离的收益边界

分层带来的收益仅限于构建与分发,不影响运行:

  1. 构建阶段:依赖下载在大多数提交中命中缓存,构建时间主要由业务代码编译决定。
  2. 分发阶段:节点已存在基础层与依赖层时,拉取只传输新增的业务层。镜像大小的绝对值不变,但增量传输量下降。
  3. 运行阶段:所有层都会被解包到本地存储,启动耗时与镜像总大小相关,分层不改变这一点。

因此"分层优化"与"镜像瘦身"是两件不同的事:前者优化增量分发,后者优化全量分发与解包。

2.2.3 大体积镜像的代价

镜像体积通过三条路径影响部署:

  1. 拉取时间。 首次调度到某个节点、节点缓存被回收或镜像标签指向新摘要时,需要完整拉取。拉取时间与镜像大小成正比,与节点到仓库的带宽成反比。
  2. 扩缩容与故障转移速度。 扩容与节点故障后的迁移都需要在新节点拉取镜像,镜像越大,容量恢复越慢。
  3. 节点磁盘占用。 每台节点保留多个历史层,镜像偏大会加速节点 imagefs 的驱逐阈值触达。节点驱逐信号与预留关系见 Kubernetes 集群运维 的调度机制一节。

基础镜像的选择、精简镜像的兼容性代价与构建缓存技巧见 镜像优化实践,本篇只说明部署侧的取舍依据。

2.2.4 启动阶段的耗时构成

一次容器启动的端到端耗时由四段构成,各段的优化手段不同:

阶段 内容 主要影响因素
调度与拉取 选择节点、拉取与解包镜像 镜像大小、节点缓存、仓库带宽
容器初始化 创建命名空间、挂载卷、注入环境变量、执行入口命令 卷类型、挂载数量、入口脚本复杂度
JVM 初始化 堆映射与预触碰、GC 与 JIT 线程创建、元空间与代码缓存初始化 堆上限、AlwaysPreTouch、核数感知
应用初始化 类加载与校验、容器启动、Bean 装配、连接池与缓存预热 类数量、框架规模、预热逻辑

区分四段的意义在于定位手段不同:前两段的证据在平台侧(kubectl describe pod 的事件流、ImagePullBackOff 与 ContainerCreating 的持续时间),后两段的证据在应用侧(-Xlog:class+load、JFR 启动事件、应用自身的就绪时间戳)。JVM 侧的测量参数见 JDK 内置工具详解。

2.3 生命周期与流量

2.3.1 三种探针的语义差别

探针 判定对象 失败后果 不可包含的内容
启动探针(startupProbe) 启动是否完成 在通过前不执行存活与就绪判定,反复失败则重启 业务依赖
就绪探针(readinessProbe) 是否可接收新流量 从 Endpoints 摘除,不重启 非必要的下游依赖
存活探针(livenessProbe) 进程是否仍可工作 重启容器 下游依赖可用性

三者的关键区分点是失败后果不同:就绪失败只影响流量,存活失败会终止进程。把"暂时不能服务"的判断写进存活探针,等价于把一次可自愈的抖动升级为一次重启。

一个必须遵守的约束是探针超时要大于应用的最长合法停顿。若一次 Full GC 停顿、一次全量缓存加载或一次长事务提交的耗时超过探针超时与失败阈值的乘积,探针会在应用仍正常工作时判定失败。对于停顿敏感的应用,存活探针的 timeoutSeconds × failureThreshold 应显著大于最坏停顿。

2.3.2 就绪判定与流量引入的关系

就绪状态通过 Endpoints 或 EndpointSlice 影响流量,链路是:

就绪探针通过
    → Pod 被加入 Endpoints / EndpointSlice
    → kube-proxy 依据地址集合生成转发规则
    → 入口组件与 Service 开始向该实例转发请求

反向链路同样存在:探针失败 → 移出地址集合 → 转发规则更新 → 停止接收新请求。两条链路都存在传播延迟,这就是摘流量与停进程之间必须留等待时间的原因。

需要明确的边界是:端口可连接不等于业务就绪。 使用 tcpSocket 探针时,只要进程已监听端口就判定成功,此时应用可能仍在装配 Bean 或建立连接池。对 Java 应用,就绪探针应指向应用暴露的就绪端点,而不是端口探测;就绪端点的暴露与相关指标埋点、实例标签的组织方式见 Java 应用可观测性埋点。

2.3.3 优雅下线的时序

一次正确的下线包含四个阶段,缺任一段都会产生请求失败:

1. 摘流量
   就绪状态转为未就绪,实例移出 Endpoints
   目的:让入口与调用方停止把新请求发往该实例

2. 等待存量流量窗口
   时长需大于「调用方实例列表缓存刷新周期 + 单请求最长处理时间」
   目的:使已发出但尚未到达的请求不再落到该实例

3. 停止接收新请求,处理在途请求
   停止监听或拒绝新连接,等待已接收的请求执行完成
   目的:避免请求执行到一半被中断

4. 释放资源并退出
   关闭线程池与连接池,刷写缓冲日志,注销注册中心
   目的:避免连接被对端判定为异常断开,避免日志丢失

编排层的终止流程在平台侧提供了部分能力:Pod 被标记为 Terminating 后从 Endpoints 摘除,随后执行 preStop 钩子,再向主进程发送 SIGTERM,等待 terminationGracePeriodSeconds,超时后发送 SIGKILL。摘除 Endpoints 与发送 SIGTERM 是两条并行的链路,前者完成不代表后者已延迟发送,因此惯例是在 preStop 中等待一小段时间,为转发规则更新留出窗口。

平台的终止流程、参数含义与滚动参数对可用性的影响见 Kubernetes 集群运维 的探针与优雅终止一节。

2.3.4 强杀的后果

宽限期结束时进程收到 SIGKILL,无法捕获、无法清理:

  1. 在途请求失败。 已接收但未完成的请求返回 5xx 或连接重置,上游表现为超时。滚动发布期间这类失败量不大但稳定出现,常被误判为网络抖动。
  2. 写入未落盘。 缓冲中的日志与未提交的本地写入丢失,故障现场随之消失。
  3. 资源未正常释放。 与下游的长连接不会发送关闭帧,对端需等待超时才能感知,占用对端连接资源。
  4. 状态不一致。 正在执行的批处理或消息消费任务被中断,任务状态停留在执行中。

处理方向是让应用侧与平台侧的等待时间对齐:应用侧的最长处理时间要小于 terminationGracePeriodSeconds,同时 preStop 的等待时间要从宽限期中扣除,不能占满全部余额。

2.4 类数据共享与启动加速

2.4.1 类加载在校验与解析上的固定开销

JVM 启动阶段需要把应用与框架的类逐个加载、链接与校验。类数量在中等规模的 Spring 应用中通常以万计,这部分工作是每次启动都要重复的固定成本,且随依赖规模增长。

类数据共享(CDS,Class Data Sharing)的思路是:把一次运行中完成加载与校验的类元数据归档为文件,后续启动直接映射归档中的元数据,跳过重复的解析与校验。

2.4.2 CDS 与 AppCDS 的使用方式

# 1. 首次运行,导出被加载的类列表
java -XX:DumpLoadedClassList=app.lst -jar app.jar

# 2. 基于类列表生成共享归档(类路径需与运行时一致)
java -Xshare:dump -XX:SharedClassListFile=app.lst \
     -XX:SharedArchiveFile=app.jsa -jar app.jar

# 3. 运行时使用归档
java -XX:SharedArchiveFile=app.jsa -jar app.jar

# 4. JDK 12 起的动态归档:退出时自动生成
java -XX:ArchiveClassesAtExit=app.jsa -jar app.jar

使用约束:

  1. 归档与 JDK 版本、类路径、启动参数强相关。 三者中任一变化都可能导致归档失效,JVM 静默退回普通启动,不报错。
  2. 归档需随镜像一起构建与更新。 归档在构建阶段生成,随镜像发布,并在镜像升级时重新生成,否则优化效果在升级后消失且不易察觉。
  3. 归档文件本身占用镜像体积。 典型的应用归档在数十兆量级,需与镜像瘦身目标权衡。
  4. 验证归档是否生效的方式是查看启动日志中的 CDS 相关输出,或对比开启前后的启动耗时分布。

2.4.3 原生镜像的定位与限制

原生镜像(Native Image)走的是另一条路线:在构建阶段完成提前编译,把应用编译为本地可执行文件,运行时不再包含传统 JVM 的类加载与即时编译过程。

它的优势明确:启动时间从秒级降到更小量级,常驻内存显著下降,适合快速扩缩容与按请求计费的场景。

代价同样明确,且大部分与 Java 的运行时特性相关:

维度 限制
动态特性 反射、动态代理、资源加载、序列化框架需在构建时提供配置或元数据,缺失则在运行时报错
JNI 与第三方库 依赖本地库或运行时生成字节码的库可能不支持
构建 构建过程耗时较长,且需在构建环境准备原生编译工具链
峰值性能 缺少运行期即时编译的优化,长时间运行的峰值吞吐通常低于 JIT 路径
可观测与诊断 传统 attach 类诊断工具与部分 JFR 能力受限,排查手段发生变化

因此原生镜像的适用判断取决于两点:启动时间与常驻内存是否构成瓶颈,以及应用的动态特性是否可被静态配置覆盖。 对长驻的、依赖大量反射与动态代理的服务,常规 JVM 加 CDS 的组合通常是更省代价的选择。原生镜像的构建流程、反射与资源配置以及诊断手段的变化见 GraalVM 与原生镜像。

2.5 配置与密钥

2.5.1 外部化配置的注入方式与优先级

容器化部署的前提是镜像不可变:同一构建产物在所有环境使用同一镜像,环境差异只能来自外部注入的配置。常用的注入方式与覆盖关系:

注入方式 载体 变更后是否生效 典型用途
命令行参数 容器启动命令 需重建实例 少量关键参数
环境变量 容器环境 需重建实例 JVM 参数、环境标识、连接地址
配置文件挂载 ConfigMap 卷 卷内容同步,应用是否重读取决于实现 应用配置文件
配置中心 远程配置服务 支持动态刷新,仅对声明了刷新作用域的 Bean 生效 业务配置、开关
密钥对象 Secret 卷或环境变量 卷同步,环境变量需重建 凭据、证书

优先级通常遵循"越靠近运行时的来源优先级越高":命令行参数高于环境变量,环境变量高于外部配置文件,外部配置文件高于镜像内打包的默认配置。这一顺序使紧急处置可以用更高优先级的来源临时覆盖,而不必重新构建镜像。

2.5.2 环境变量与配置中心的取舍

维度 环境变量 配置中心
变更生效 需重建实例 可动态刷新,但仅覆盖刷新作用域内的 Bean
审计与回滚 依赖部署记录的版本对比 有配置历史与版本回滚
敏感信息 会出现在进程信息、崩溃转储与诊断接口中 可单独控制可见权限与加密
规模适配 配置项增多后难以维护 按命名空间与分组组织
启动依赖 无外部依赖 需要处理配置中心不可用时的启动策略

取舍依据是配置的变更频率与是否需要审计:几乎不变且与实例规格绑定的内容(监听端口、JVM 参数、时区)适合环境变量;需要按业务节奏调整、需要留痕的内容适合配置中心。二者并非互斥,常见组合是环境变量承载启动期必需的最小配置,配置中心承载业务配置。

需要特别注意的是,配置中心中需要动态生效的配置项,其绑定的 Bean 必须声明刷新作用域;未声明的 Bean 在刷新后仍持有旧值,而修改连接池、线程池、注册中心地址这类配置的实际效果是重建 Bean 与底层资源,可能伴随连接中断。机制细节与全量刷新的影响范围见 Spring Cloud 微服务 的配置中心一节。

2.5.3 密钥不落镜像的原则

密钥处理遵循三条原则:

  1. 不写入镜像的任何一层。 镜像层可被任何有拉取权限的主体解包,写入层的凭据等同于公开。构建阶段使用凭据应通过构建参数或挂载临时凭据,且不留在最终层。
  2. 不进入版本控制与日志。 密码类配置不应出现在应用日志、配置快照接口、异常堆栈与审计日志的可检索字段中。
  3. 与配置分离管理。 承载密钥的对象应与普通配置分开授权,读取权限限定到必要的服务账号,并支持独立轮换而不触发全量配置变更。

平台侧的实现边界同样需要了解:Secret 对象中的内容是编码存储而非加密,集群的键值存储默认可能以明文保存,需要显式启用静态加密;密钥对象的读取权限应通过授权策略限定。相关风险清单见 Kubernetes 集群运维 的配置与密钥一节。

2.6 发布模型

2.6.1 三种发布方式在 Java 应用上的差异

方式 实现机制 资源开销 Java 应用上的特点
滚动更新 逐批替换副本,受 maxSurge 与 maxUnavailable 约束 低,复用现有容量 新旧版本长期共存,需保证接口与数据格式兼容;实例启动慢会拖慢发布推进
灰度(金丝雀) 新增少量副本共享同一 Service,或在入口按权重分流 中,需要额外副本或入口能力 可按副本比例或按请求特征分流;长连接场景下实际流量比例与副本比例偏差较大
蓝绿 两套完整环境,切换入口指向 高,需要双份资源 切换与回滚都是一次指向变更;两套环境共用数据层,版本差异必须被数据层兼容

对 Java 应用,选择发布方式时有一项特有因素:新实例在启动后的一段时间内性能低于稳定状态,因为热点方法尚未完成即时编译。这使得灰度阶段的新旧指标对照需要留出编译收敛的窗口,否则新版本会因预热不足而被误判为性能劣化。预热策略的用法见 3.3.3。

2.6.2 实例数与会话状态的关系

副本数大于 1 时,请求可能落到任意实例。Java Web 应用的传统会话模型把状态保存在实例内存中,一旦实例被替换或请求被转发到其他实例,会话即丢失或被要求粘滞。

处理方式有两类,对应不同的改造边界:

方式 做法 边界与代价
会话粘滞 入口按会话标识固定转发到同一实例 无需改造,但使负载不均;实例下线时会话仍丢失;扩容无法分摊已有会话的压力
会话外置 会话写入共享存储或改为无状态令牌 需要改造;引入对共享存储的依赖与网络开销
无状态化 身份与状态随请求携带,服务端不保存 彻底的方案;需要重新设计登录态、幂等与流程状态的管理

2.6.3 无状态化改造的边界

"无状态"在工程上是一个程度问题,而不是非此即彼。需要区分三类状态:

  1. 必须外置的状态:用户会话、流程中间态、幂等记录。留在实例内会使重建即丢数据。
  2. 可以本地化但需要重建机制的状态:本地缓存、预热数据、连接池中的长连接。可以在实例内保存,但必须有重建路径,且不能成为正确性的唯一来源。
  3. 不能简单外置的状态:定时任务与批处理的执行权、本地文件锁、只允许单实例执行的动作。这类状态需要选主或分布式协调,而不是简单外置。

第三类是多实例部署中最容易被忽略的一类:副本数从 1 提升到 2 之后,原本"只有一个实例在跑"的定时任务会同时执行两次,产生重复处理。部署前的实例数变更应同时核对定时任务的执行模型。


三、实现

3.1 镜像构建实践

3.1.1 多阶段构建与目录组织

多阶段构建的语法与各场景模板见 多阶段构建,编译、测试与制品产出阶段的流水线组织见 Gradle 与 Java 构建流水线,本节只给出 Java 项目的组织要点:

# 阶段一:构建(含编译工具链,不进入最终镜像)
FROM maven:3.9-eclipse-temurin-17 AS builder
WORKDIR /build

# 依赖声明单独一层:业务代码变更不使其失效
COPY pom.xml .
RUN mvn -B -q dependency:go-offline

# 业务代码与其构建产物
COPY src ./src
RUN mvn -B -q clean package -Dmaven.test.skip=true

# 阶段二:运行镜像(只含运行时与产物)
FROM eclipse-temurin:17-jre-jammy AS runtime

# 时区与字符编码在镜像内固定,避免依赖运行环境
ENV TZ=Asia/Shanghai \
    LANG=C.UTF-8

# 应用与数据目录分离:数据目录单独挂载,不写入容器可写层
WORKDIR /app
RUN mkdir -p /app/logs /data/dump \
    && groupadd -r app && useradd -r -g app appuser

COPY --from=builder --chown=appuser:app /build/target/*.jar /app/app.jar

USER appuser
EXPOSE 8080

# 入口使用 exec 形式,使主进程直接接收信号
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

组织要点:

  1. 依赖声明与业务代码分两个复制步骤。 这是构建缓存命中率的决定因素,收益体现在构建与增量分发,见 2.2.2。
  2. 最终镜像只保留运行时与产物。 编译工具、源码、构建缓存留在构建阶段,--chown 在复制时一并设置归属,避免额外一层。
  3. 应用目录与数据目录分离。 容器可写层的写入随容器销毁而消失,且会占用节点磁盘;日志与转储文件应挂载到卷。
  4. 入口使用 exec 形式。 若使用 shell 包装且未正确转发信号,SIGTERM 无法到达 JVM,进程会在宽限期结束时被强制终止。指令形式差异见 Dockerfile 指令详解。
  5. 非 root 用户运行。 同时需确保挂载目录对该用户可写,否则应用启动即失败,表现为权限错误。

3.1.2 基础镜像的选择

镜像类型 体积量级 适用 代价
完整 JDK 大 构建阶段、需要现场编译或诊断的场景 体积大、组件多、需修补的面积大
JDK slim 中 需要运行期使用 JDK 工具的场景 比 JRE 镜像大
JRE slim 小 常规生产的默认选择 无编译与部分诊断工具
JRE alpine(musl) 最小 对体积敏感且依赖兼容的场景 musl libc 与部分本地库不兼容;时区数据需额外安装

选择依据是三项,而不是体积单项:

  1. 是否需要在容器内使用 JDK 工具。 若线上诊断依赖容器内的 jcmd、jstack,JRE 镜像将不具备这些能力,需要改为通过平台侧或旁路方式采集。
  2. 依赖是否包含本地库。 使用 musl 基础镜像时,依赖 glibc 的本地库会加载失败,典型报错是找不到共享库。切换到精简镜像应在测试环境验证全部功能路径,而不只是启动成功。
  3. 镜像来源与补丁策略。 基础镜像需要明确来源与更新节奏,操作系统层与 JDK 层的安全修补都依赖基础镜像的重新构建。

各语言基础镜像的体积对照与切换注意事项见 镜像优化实践。

3.1.3 体积与启动时间的取舍

手段 对体积 对启动时间 需要权衡的点
多阶段构建 显著减小 无明显影响 构建脚本复杂度上升
依赖层分离 不改绝对值 无明显影响 优化的是增量传输
JRE 替代 JDK 减小 略快(类更少) 容器内失去 JDK 工具
精简基础镜像 显著减小 略快(解包更快) 本地库兼容性与调试工具
裁剪 JDK(jlink) 减小 略快 裁剪后需验证全部功能,且工具链更复杂
CDS 归档 略微增大 明显缩短 归档与版本、类路径绑定
原生镜像 通常更大 大幅缩短 动态特性适配成本

取舍的判断标准是部署链路中哪一段构成瓶颈:若瓶颈在节点拉取(首次调度慢、扩容慢),优先减小体积;若瓶颈在 JVM 与应用初始化,优先 CDS 与预热;若两者都不是瓶颈,不引入额外复杂度。

3.1.4 镜像标签规范

镜像标签直接决定回滚能力与可追溯性,采用三类标签组合:

标签类型 示例 作用
语义化版本 v1.4.2 表达兼容性语义,供人工沟通与发布记录引用
提交标识 20260923-a1b2c3d 与代码提交一一对应,用于定位具体来源
环境别名 staging、prod 便于流水线引用,需记录其当前指向的摘要

规范要点:

  1. 同一构建产物同时打语义化版本与提交标识标签,二者指向同一摘要。
  2. 生产不使用 latest。 该标签不具备"最新"的语义保证,多次推送会覆盖,导致回滚目标不可确定、不同节点在不同时间拉取到不同内容。
  3. 对内容一致性有强要求时按摘要部署。 以 @sha256: 形式引用,标签漂移不再影响运行时结果。
  4. 对已发布版本启用标签不可变规则。 规则启用后匹配模式的推送会被拒绝,需在规则上线前确认流水线的推送行为。
  5. 删除标签前核对引用。 部署编排文件、流水线变量与发布模板中硬编码的标签需先停用,再删除标签,最后执行垃圾回收。

标签规范、不可变规则的影响面与清理顺序见 镜像仓库与治理 的标签规范一节。

3.2 JVM 参数实践

3.2.1 参数组合示例

# 容器感知与内存上限
-XX:+UseContainerSupport              # JDK 10+ 默认开启,显式声明避免被上游参数覆盖
-XX:MaxRAMPercentage=70               # 堆上限占容器限额比例
-XX:InitialRAMPercentage=70           # 初始堆与上限一致,避免运行期扩缩
-XX:MaxMetaspaceSize=512m             # 元空间硬上限,防止类加载器泄漏耗尽本地内存
-XX:MaxDirectMemorySize=256m          # 直接内存上限,未设置时按与堆上限相同推导
-XX:ReservedCodeCacheSize=256m        # 代码缓存上限,写满会导致退回解释执行

# 收集器与停顿目标
-XX:+UseG1GC
-XX:MaxGCPauseMillis=200

# CPU 配额感知
-XX:ActiveProcessorCount=4            # 按限额核数推导 GC 与 JIT 线程数

# 现场保留
-Xlog:gc*:file=/app/logs/gc.log:time,uptime:filecount=10,filesize=50M
-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/data/dump/
-XX:StartFlightRecording=name=base,settings=default,maxsize=256m,maxage=24h

各参数的含义与取值依据见 JVM 内存结构与垃圾回收 的生产调优一节,本节只补充容器场景下的配比与分环境管理方式。

3.2.2 内存配比示例

堆上限按容器限额的比例设定时,比例取值由堆外需求决定。以常见的容器限额为例:

容器限额 堆上限比例 堆上限 堆外余量 适用说明
2Gi 60%~65% 约 1.2Gi~1.3Gi 约 0.7Gi~0.8Gi 小规格实例,堆外相对占比更高
4Gi 65%~75% 约 2.6Gi~3Gi 约 1Gi~1.4Gi 通用 Web 服务
8Gi 70%~80% 约 5.6Gi~6.4Gi 约 1.6Gi~2.4Gi 堆外需求不随堆线性增长,比例可略高
16Gi 及以上 75%~85% 按比例 建议不少于 2Gi 线程数多、直接内存用量大的服务应下调比例

配比的三条约束:

  1. 堆外余量的绝对值不能过小。 线程栈随线程数线性增长,直接内存随 NIO、Netty、文件映射用量增长,元空间随类与类加载器数量增长。余量按比例给小规格实例时容易不足。
  2. 线程数需要单独核算。 线程栈占用等于 -Xss 乘以线程数,线程池规模较大的服务需要把这一项计入余量,必要时降低 -Xss。
  3. 比例与限额变更需同步。 限额调整后必须重新核算堆上限,运行中修改限额不会改变已启动 JVM 的堆配置。

3.2.3 CPU 限制下的线程数调整

CPU 配额影响三类线程的规模:

线程类别 默认推导依据 调整参数 调整依据
GC 线程 可见处理器数 -XX:ParallelGCThreads、-XX:ConcGCThreads 按配额核数设定;线程数超过配额会导致 GC 线程互相争抢时间片,拉长停顿
JIT 编译线程 可见处理器数 -XX:CICompilerCount 编译线程与业务线程争抢配额时下调
业务线程池 由应用配置决定 应用侧参数 并发度应与配额匹配,配额不足时增加并发只会加剧排队

核数感知偏差的通用解法是显式指定 -XX:ActiveProcessorCount,使 JVM 按配额核数推导上述默认值。

3.2.4 参数的分环境管理

参数按"是否与实例规格绑定"分两层管理:

  1. 与规格绑定的参数(堆上限、GC 线程数、活跃处理器数)随实例规格变化,应通过部署清单中的环境变量注入,与资源限额写在同一个文件中,使二者在同一处被审阅和修改。
  2. 与环境无关的参数(收集器选择、日志配置、转储开关)可以在镜像内设置默认值,由部署清单覆盖。
env:
  - name: JAVA_TOOL_OPTIONS
    value: >-
      -XX:+UseContainerSupport
      -XX:MaxRAMPercentage=70
      -XX:InitialRAMPercentage=70
      -XX:ActiveProcessorCount=4
      -XX:+UseG1GC
      -XX:MaxGCPauseMillis=200
      -XX:MaxMetaspaceSize=512m
      -XX:MaxDirectMemorySize=256m
      -XX:ReservedCodeCacheSize=256m
      -XX:+HeapDumpOnOutOfMemoryError
      -XX:HeapDumpPath=/data/dump/

使用 JAVA_TOOL_OPTIONS 而非写在入口脚本中,好处是参数可随部署清单变更、可被审计、不随镜像固定;代价是环境变量会出现在进程信息与诊断接口中,不应承载凭据类内容。

高危 修改 JVM 参数并重启进程(-Xmx、收集器、-XX:MaxMetaspaceSize、-XX:MaxDirectMemorySize 等)

  • 影响范围:启动参数在进程启动时读取,修改必须重启,重启期间该实例不接收流量;参数与限额不匹配会直接引入故障——堆上限超过容器限额余量会导致进程被终止,堆上限过小会导致回收频繁,切换收集器会使停顿特征与日志格式同时变化,既有告警阈值与看板可能失效;错误的参数在低峰期可能不显现,在峰值才暴露。
  • 回滚方式:保留变更前的完整参数值与镜像版本,出现异常时按原参数与原版本回退;变更采用滚动或灰度方式,先在一个实例或一个分组验证,观察 GC 日志与业务指标后再推广;参数变更纳入发布流程管理,具备量化的回滚触发条件。
  • 配套要求:变更前后各采集一段 GC 日志与业务基线,用同一压测模型对照,方法见 linux: 压测与性能基线。

3.3 探针与优雅下线实践

3.3.1 探针配置示例

spec:
  terminationGracePeriodSeconds: 60          # 覆盖 preStop 等待与在途请求处理
  containers:
    - name: app
      ports:
        - name: http
          containerPort: 8080
      startupProbe:                          # 启动期:覆盖最慢启动,失败不摘流量只重启
        httpGet:
          path: /actuator/health/liveness
          port: http
        periodSeconds: 5
        failureThreshold: 36                 # 最长容忍 5 × 36 = 180 秒
      readinessProbe:                        # 就绪期:决定是否接收流量
        httpGet:
          path: /actuator/health/readiness
          port: http
        periodSeconds: 5
        timeoutSeconds: 3
        failureThreshold: 3
        successThreshold: 1
      livenessProbe:                         # 存活期:只在进程无法恢复时失败
        httpGet:
          path: /actuator/health/liveness
          port: http
        periodSeconds: 10
        timeoutSeconds: 5
        failureThreshold: 3                  # 最长容忍 5 × 3 = 15 秒,需大于最坏停顿
      lifecycle:
        preStop:
          exec:
            command: ["/bin/sh", "-c", "sleep 10"]   # 为转发规则更新留出窗口

3.3.2 阈值设置的依据

参数 设定依据
startupProbe.failureThreshold failureThreshold × periodSeconds 应大于最慢启动耗时,且要覆盖冷启动(节点缓存未命中、依赖初始化慢)的情况
readinessProbe.periodSeconds 越小则摘除与引入越及时,代价是探测请求更频繁;对流量敏感的服务取较小值
readinessProbe.failureThreshold 决定从异常到摘除的延迟;取值过小会因偶发失败抖动而频繁摘挂流量
livenessProbe.timeoutSeconds 必须大于应用的最长合法停顿,包括最坏 GC 停顿与长时间不可中断的执行段
livenessProbe.failureThreshold 与超时相乘得到容忍窗口;与业务超时时间对齐,避免重启比上游超时更早或更晚发生
terminationGracePeriodSeconds 大于 preStop 等待时间与最长在途请求处理时间之和

一个常见的配置错误是让就绪与存活探针指向同一端点、使用同一组阈值。两者语义不同:就绪失败只是暂时不接流量,允许宽松;存活失败会重启进程,必须严格。

高危 调整运行中工作负载的探针阈值或探针路径

  • 影响范围:探针参数变更会触发实例重建(部分平台对探针字段的修改会滚动重建),等价于一次发布;放宽存活探针会使真正无响应的实例长期保留在服务中并持续接收流量;收紧就绪探针会使实例被频繁摘除,若同时摘除的实例数超过容量冗余,剩余实例将过载;修改探针路径后若端点不存在,实例会永久处于未就绪状态,表现为服务整体不可用;放宽存活探针还会使故障进程不再被自动重启,故障从"自动恢复"变为"人工介入"。
  • 回滚方式:恢复原探针配置并触发一次滚动重建;若因误改路径导致实例未就绪,可先临时切回原路径恢复流量,再排查端点问题;变更前后记录各探针的失败计数与摘除次数,作为判断依据。防护要求:探针变更与发布同等对待,先在单个实例或测试环境验证判定行为,再全量应用。
  • 替代做法:需要临时停止某个实例接收流量时,优先调整就绪状态(应用侧提供开关)或摘除实例,而不是修改全局探针配置。

3.3.3 就绪延迟与预热

对新实例,从"进程启动完成"到"性能达到稳定状态"之间存在一段区间。这段区间的长度由类加载与即时编译决定,可通过三种手段压缩:

  1. CDS 归档:减少类加载与校验的重复工作,见 2.4.2。
  2. 应用侧预热:在流量接入前主动调用核心接口,触发类加载与即时编译。预热请求应与真实调用路径一致,覆盖核心接口与序列化、加解密、模板渲染等重路径;预热逻辑放在就绪判定之前执行,使实例在预热完成前保持未就绪。
  3. 入口侧延迟引入:利用 minReadySeconds 让实例在就绪后保持观察一段时间才计入可用副本,过滤"就绪后立即崩溃"的版本,同时给预热留出窗口。参数含义见 Kubernetes 集群运维。

预热的效果需用与生产一致的压测模型验证,避免"预热了但关键路径未被覆盖"。

3.3.4 优雅停机的应用侧配置

# Spring Boot 应用侧优雅停机
server:
  shutdown: graceful                        # 收到终止信号后停止接受新请求,等待在途请求完成
spring:
  lifecycle:
    timeout-per-shutdown-phase: 25s         # 单个关闭阶段的最长等待,需小于宽限期减去 preStop 等待

# 暴露存活与就绪端点
management:
  endpoint:
    health:
      probes:
        enabled: true
  health:
    livenessstate:
      enabled: true
    readinessstate:
      enabled: true

需要按序完成的三件事:

  1. 先让就绪判定失败。 由平台摘除流量,或由应用在收到终止信号后主动切换就绪状态,使调用方停止发新请求。
  2. 再等待存量流量窗口。 调用方的实例列表缓存需要一个刷新周期,窗口时长应大于"缓存刷新周期加单请求最长处理时间"。
  3. 最后处理在途请求并释放资源。 等待进行中的请求完成,关闭线程池与连接池,刷写日志,向注册中心注销。

时间预算的核算关系是:

terminationGracePeriodSeconds
    > preStop 等待时间(存量流量窗口)
    + 应用侧关闭阶段等待时间(在途请求处理)
    + 资源释放余量

任一项缺失都会产生"流量已摘除但进程被强杀"或"进程已退出但调用方仍在转发"的半完成状态。平台侧的终止流程与参数含义见 Kubernetes 集群运维 的探针与优雅终止一节,应用侧的注册与摘流顺序见 Spring Cloud 微服务 的部署与运维一节。

3.4 资源与调度实践

3.4.1 requests 与 limits 的设置依据

字段 作用 设置依据 不设置的后果
requests.memory 调度依据与驱逐排序依据 按稳态 RSS 加上一定余量 按 0 参与调度,节点超卖,资源紧张时优先被驱逐
limits.memory cgroup 内存上限 按峰值 RSS 加上余量,且必须覆盖 3.2.2 的堆外核算 不限制,单实例可耗尽节点内存,最终触发整机 OOM
requests.cpu 调度依据与权重 按稳态 CPU 用量 按 0 参与调度,节点上容器密度过高
limits.cpu cgroup CPU 配额 按峰值用量,或与 requests 相等 不限制,突发时与其他容器争抢;设置过低会引入节流
resources:
  requests:
    cpu: "1"
    memory: "3Gi"       # 稳态 RSS,参与调度
  limits:
    cpu: "4"            # 配额上限,需与 -XX:ActiveProcessorCount 对齐
    memory: "4Gi"       # 容器限额,需覆盖堆 + 堆外余量

两项判读要点:

  1. 内存 limits 必须设置,其他字段按场景决定。 内存是不可压缩资源,超限的后果是进程被终止;CPU 是可压缩资源,超限的后果只是被节流。
  2. 内存 requests 与 limits 的差距不宜过大。 差距过大会使节点按较小的 requests 超卖内存,在整体压力上升时集中触发驱逐。

不同 requests 与 limits 组合对应不同的服务质量等级,等级决定节点资源紧张时的驱逐优先级,判定条件与驱逐顺序见 Kubernetes 集群运维 的调度机制一节。

3.4.2 内存与 CPU 的配比

配比由应用的资源画像决定,常见三类:

画像 内存:CPU(request 层面) 判断依据 调度注意
计算密集 较小,如 1Gi 对 1 核 CPU 使用率高、GC 压力小 关注 CPU 节流,limits.cpu 与 requests.cpu 宜接近
内存密集(缓存、大堆) 较大,如 4Gi 对 1 核 堆占用高、CPU 使用率低 关注节点内存总量与驱逐,requests.memory 应接近实际稳态
均衡型 Web 服务 中等,如 2Gi 对 1 核~2 核 有稳定 QPS 与堆占用 两项都需留余量,配合滚动参数核算容量

配比失调的典型表现是:内存配比过小时容器因堆外空间不足被终止;CPU 配比过小时 GC 线程与业务线程争抢配额,表现为延迟毛刺而 CPU 使用率贴顶。

3.4.3 副本数与滚动参数

副本数的下限由两项共同决定:

最小可用副本数 ≥ 峰值流量 / 单实例承载能力

发布期间最小可用副本数 = replicas - maxUnavailable
    (或 replicas - 分批数量,取较小者)

因此副本数偏小、maxUnavailable 偏大时,发布期间的容量不足以承载峰值流量,发布过程本身即构成一次容量事故。经验做法是:核心服务用 maxUnavailable: 0 配合 maxSurge: 1,保证发布期间可用副本不减少;副本数为 2 的服务需明确"发布期间仅剩 1 个实例"是否可接受。

progressDeadlineSeconds 需要覆盖单批实例的启动与就绪时间,否则慢启动应用会被判定为发布失败。revisionHistoryLimit 决定可回滚的版本数,取值过小会失去回滚目标。

3.4.4 节点资源碎片与调度失败

调度失败的排查方向按出现频率排列:

现象 排查方向
实例长期 Pending kubectl describe pod 的事件中会给出原因:Insufficient cpu、Insufficient memory、node(s) had taint、didn't match node selector/affinity
显示资源充足但仍不调度 单个节点的剩余资源无法满足该实例的 requests(碎片),需检查 Allocatable 与已分配量,而非节点总量
拓扑约束无法满足 反亲和或拓扑分布约束要求的分布方式在当前副本数下不可达
卷未绑定 存储类为延迟绑定模式时,卷绑定的前提是先完成调度,二者互相等待的表现需结合事件判断
端口冲突 使用主机端口的实例在同一节点上端口不可重复

碎片问题的处理方向有三条:降低单实例的 requests 使实例能被更小的剩余空间容纳;调整工作负载的分布约束;或在节点层面做整理。需要避免的做法是通过不设置 requests 来"绕开"调度失败,那会把问题推迟到运行期的驱逐阶段。

高危 修改运行中工作负载的资源限额(resources.requests、resources.limits)

  • 影响范围:内存 limits 多数版本不支持原地更新,修改会触发实例滚动重建,等价于一次发布;下调内存限额会立即收紧 cgroup 上限,若当前占用已超过新上限,进程可能被直接终止;下调 CPU 限额会立即引入节流,延迟上升;上调限额通常需要重新调度,节点资源不足时实例会停在 Pending,容量不升反降;修改 requests 还会改变调度结果,可能使实例迁移到其他节点并触发镜像重新拉取;运行中修改限额不会改变已启动 JVM 的堆配置,堆与限额会失去配比关系。
  • 回滚方式:改回原限额值并恢复原调度结果;因限额下调被终止的实例按原规格重建,重建期间确认剩余副本足以承载流量;限额变更记录变更前后的数值、时间点与触发原因,并与同期的 JVM 参数复核。
  • 替代做法:优先通过临时扩容副本、限流降级或摘除异常实例分担压力;确需调整限额时按发布流程执行,同步核对 -XX:MaxRAMPercentage 或 -Xmx 是否仍与新限额匹配。

3.5 配置与密钥实践

3.5.1 注入方式对照与生效方式

注入方式 配置载体 变更生效方式 适用内容
环境变量(env) 部署清单 重建实例 环境标识、JVM 参数、连接地址
环境变量(envFrom) ConfigMap 或 Secret 重建实例 批量注入的键值对
卷挂载整个目录 ConfigMap 或 Secret 卷内容周期性同步,应用是否重读由实现决定 配置文件
卷挂载(subPath) ConfigMap 或 Secret 不自动同步,内容为挂载时快照 需要固定路径的单文件
配置中心 远程配置服务 动态刷新,仅覆盖刷新作用域内的 Bean 业务配置与开关
启动参数 容器入口命令 重建实例 少量关键参数

判读要点:以卷方式挂载的配置,卷内容会更新,但已启动的进程是否读取到新内容取决于应用是否重新打开文件。 多数应用在启动时读取一次并缓存,因此卷挂载的配置更新后仍然需要触发实例重建才能真正生效。这类"配置已更新但行为未变"的现象排查成本较高,应在变更流程中明确每种配置的生效方式。

需要额外注意的是,除业务配置之外,缓存管理器、调度线程池、异步执行器等基础设施组件的可调参数同样集中在配置中。这类参数的变更不是"改一个数值",而是触发底层资源重建:连接被重建、线程池被替换、已缓存的调度状态被清空。配置组织方式与各组件在配置缺失时的默认行为,见 Spring 生态组件。

配置项更新后触发的实例重建属于破坏性动作:

高危 强制重建实例(kubectl rollout restart、删除实例、批量重建)

  • 影响范围:重建按滚动策略逐批进行,期间可用副本数下降,若容量冗余不足则剩余实例过载;重建会清空实例内的本地缓存与会话,缓存类应用重建后存在一段性能低谷;若重建由配置变更触发而新配置有误,所有实例会在重建后进入同一故障状态,故障范围从单实例扩大到全量;重建还会使新实例重新拉取镜像与重新预热,冷启动压力集中在短时间内。
  • 回滚方式:回滚配置到变更前的版本并再次触发重建;配置对象应支持版本回滚或事先导出当前值留存;重建期间保持观察错误率、延迟与就绪实例数,未达标立即停止推进。防护要求:先在单个实例或一个分组验证新配置,确认容器正常启动且应用日志中的配置版本与预期一致后再全量。
  • 替代做法:对不需要改变注入方式的配置,优先使用配置中心的动态刷新能力,避免以重建换取配置生效。

3.5.2 密钥的注入与轮换

密钥注入按安全等级选择方式:

方式 特点 适用
平台密钥对象(卷挂载) 支持后续更新,内容同步到卷 证书、需要轮换的凭据
平台密钥对象(环境变量) 使用方便,但会出现在进程环境与崩溃信息中 低敏感度配置
密钥管理服务 应用启动时拉取,权限与审计集中 高安全要求场景
加密配置项 密文与密钥分离存放 配置中心托管的敏感项

轮换流程需要覆盖三个环节:

  1. 双写过渡。 新凭据生效前,被访问方应同时接受新旧凭据,避免轮换期间出现拒绝。
  2. 分批注入。 按实例或分组更新密钥对象,避免全部实例在同一时刻使用新凭据。
  3. 验证与回退。 确认新凭据可用后再停用旧凭据;停用前保留可回退的旧凭据,并记录停用时间点。

需要明确的一点是,环境变量形式的密钥在实例重建前不会更新,因此轮换这类密钥必然伴随实例重建;卷形式的密钥虽然内容会同步,但应用是否重新加载取决于实现,多数情况下同样需要重启才能生效。密钥的授权与风险清单见 Kubernetes 集群运维 的配置与密钥一节。

3.6 发布与回滚实践

变更分级、窗口选择、可逆性设计与复盘闭环的通用要求见 linux: 变更与发布管理,本节只给出 Java 应用部署相关的具体项。

3.6.1 发布前检查清单

类别 检查项
制品 镜像已推送且标签指向预期摘要;旧版本镜像仍在仓库中且可拉取;镜像标签未被不可变规则之外的推送覆盖
依赖 基础镜像与 JDK 版本的变更已记录;依赖库的安全修补状态已确认
配置 新增配置项在目标环境的配置对象中已存在;密钥对象键名与格式与应用预期一致;配置的生效方式已确认(重启或动态刷新)
参数 JVM 参数与资源限额配比已复核;限额变更后的堆上限已重新核算
探针 探针路径与端口与实际暴露一致;启动探针阈值覆盖最慢启动;存活探针阈值大于最坏停顿
容量 副本数与滚动参数核算后的最小可用副本数可承载峰值流量
数据 数据库结构变更已按"先扩展后收缩"拆分;新旧版本共存的兼容性已确认
观察 关键指标基线已采集;回滚触发条件已量化写成;回滚步骤已核对可执行
现场 日志目录与转储目录已挂载卷且有足够空间;GC 日志与 JFR 归档已开启

清单中与本篇关系最密切的三项是探针阈值、参数与限额配比、容量核算,这三项错误的后果都在发布过程中或发布后短期内显现。

3.6.2 发布中的观察指标

维度 观察内容 异常指向
可用性 错误率、超时率、就绪实例数、发布进度是否推进 就绪失败、启动超时、配置错误
延迟 关键接口的分位延迟,新实例与旧实例分别观察 预热不足、CPU 节流、下游劣化
内存 进程 RSS 与容器限额的比值、堆使用曲线 堆外超限、堆上限与限额失配
GC 回收次数与停顿分布,与发布前基线对照 堆配置变更、分配速率变化
线程池 活跃线程数、队列长度、拒绝次数 并发度与配额不匹配、下游变慢
连接池 活跃连接数、等待获取连接的线程数 下游连接未释放、池上限不足
日志 新增异常类型、错误级别日志条数 配置缺失、依赖不可用
事件 实例重启次数、OOMKilled 标记、镜像拉取失败事件 限额不足、探针误判、仓库不可达

新实例的延迟指标需要与旧实例分开看,并留出即时编译收敛的窗口,否则会把预热阶段的表现误判为版本劣化。

3.6.3 回滚触发条件与步骤

触发条件应在上线前量化为可判定的表达式:

关键接口 P99 超过发布前基线的一定倍数,且持续超过约定时长
错误率超过发布前基线的一定倍数
出现新的高优先级告警,且定位指向本次变更
就绪实例数低于容量下限,且发布进度在约定时长内未推进
实例重启次数或 OOMKilled 计数在观察窗口内持续增加
核心功能验证失败,或出现数据不一致

回滚步骤:

# 1. 暂停发布推进(如处于分批放量状态)
kubectl rollout pause deploy/<name> -n <ns>

# 2. 查看发布历史与目标版本
kubectl rollout history deploy/<name> -n <ns>
kubectl rollout history deploy/<name> -n <ns> --revision=<n>

# 3. 回滚到指定版本
kubectl rollout undo deploy/<name> -n <ns> --to-revision=<n>

# 4. 观察回滚进度与就绪状态
kubectl rollout status deploy/<name> -n <ns>
kubectl get pods -n <ns> -l app=<name> -o wide

回滚的三项前置核对:

  1. 目标版本的镜像仍可拉取,且其依赖的配置对象与密钥的键名仍然存在。
  2. 期间是否存在不可逆变更。 数据库结构变更、消息格式变更、缓存数据结构变更无法通过回滚部署撤销,需要按数据层的兼容处理方案执行。
  3. 回滚范围是否完整。 回滚部署模板不会回滚配置中心中的配置与下游的接口契约,发布失败时需同时核对配置版本。平台侧的回滚命令与前置检查见 Kubernetes 集群运维 的发布与回滚一节。

3.6.4 数据库变更与发布的顺序

多组件发布的顺序错误本身即构成故障,Java 应用的顺序约束是:

1. 数据库结构扩展(新增表、新增列、新增索引)
      新结构对旧代码无影响,可在发布前完成
2. 应用发布(新代码开始使用新结构)
      此时新旧代码并存,双方的读写都必须被兼容
3. 数据回填与双写校验(新结构中的数据补齐)
      在旧代码仍可能写入旧结构期间保持双向兼容
4. 旧结构收缩(删除旧列、旧表、旧索引)
      需确认已无旧版本实例读取之后执行

对应的约束是:删除类变更必须晚于应用发布,且要晚于最后一个旧实例退出。 若删除与发布同时进行,回滚将失去数据基础。变更顺序的一般规则与静态资源发布顺序见 linux: 变更与发布管理 的发布方式落地一节。

高危 变更发布策略(滚动、灰度、蓝绿的切换,maxSurge、maxUnavailable、minReadySeconds 的修改)

  • 影响范围:发布策略决定发布期间的最小可用容量与新旧版本共存时长。把 maxUnavailable 放宽会降低发布期间的容量下限,峰值期可能直接过载;把 maxSurge 放宽会瞬时占用额外资源,节点余量不足时新实例停留在 Pending,发布停滞;把 minReadySeconds 调小会使"就绪后立即崩溃"的版本被计入可用副本,故障版本得以继续推进;从滚动改为蓝绿会要求双份资源与数据层兼容,资源不足时新环境无法就绪;灰度比例与分流维度的修改会改变受影响用户范围。
  • 回滚方式:恢复原发布策略参数并重新核对容量核算;已按新策略推进的发布需先确认当前可用副本数,再决定是继续推进还是回滚版本;策略变更前后记录副本数、就绪实例数与发布耗时,作为后续调整依据。防护要求:策略变更在预发环境验证一次完整发布流程,确认发布进度、容量下限与回滚路径均符合预期后再应用于生产。
  • 替代做法:需要降低发布风险时,优先通过减小分批规模、延长批次间隔、增加灰度维度实现,而不是修改全局发布策略。

3.7 常见部署问题与排查

3.7.1 容器内 OOMKilled

现象:实例在运行中突然重启,容器事件中 Reason: OOMKilled,应用日志无异常输出或在中途中断。

判据:先比三项数值——容器限额、进程 RSS、堆用量。堆占用明显低于限额而进程被终止,说明是堆外部分超限或限额设置过低;堆占用接近限额,说明堆上限与限额配比不当或存在泄漏。

排查方向:

  1. 核对 -Xmx 或 MaxRAMPercentage 得到的堆上限与容器限额,确认堆外余量是否足够覆盖元空间、线程栈、直接内存与代码缓存。
  2. 确认堆外各项是否显式设了上限,未设上限的项可能持续增长。
  3. 堆外构成用 NMT 观察,方法见 linux: 内存管理。
  4. 确认限额是否被并发约束,例如同 Pod 内的其他容器共享了内存限额。
  5. 排除宿主全局 OOM:内核日志中无 cgroup 字样的终止记录指向宿主机内存不足,扩大单容器限额无效。

字段判读与宿主侧的区分方法见 容器排障与命名空间诊断 的资源限制一节,堆内成因的判读见 Java 应用诊断与部署调优。

3.7.2 启动超时被杀

现象:实例反复重启,事件中出现启动探针失败或存活探针失败,日志显示应用启动到中途被打断。

排查方向:

  1. 启动探针阈值是否覆盖最慢启动。 failureThreshold × periodSeconds 需大于冷启动(节点无镜像缓存、依赖初始化慢)的最慢耗时。
  2. 是否存在启动期的强外部依赖。 启动时同步调用下游、等待注册中心、加载全量数据,都会把下游的响应时间计入启动时间。启动路径不应包含强依赖,相关处理方式见 Spring Cloud 微服务 的部署与运维一节。
  3. 启动脚本是否阻塞。 入口脚本中的等待、重试、串行初始化会延长启动时间。
  4. 资源是否不足导致启动变慢。 CPU 配额过低时类加载与即时编译进度缓慢,启动时间显著延长。
  5. 是否被存活探针误杀。 未配置启动探针时,存活探针会在启动期执行,慢启动应用会被反复重启。

3.7.3 就绪探针反复失败

现象:实例在 Running 状态但长期处于未就绪,Endpoints 中无该实例,或实例在就绪与未就绪之间反复切换。

排查方向:

  1. 端点本身是否可用。 在容器内手工请求探针路径,核对返回码与响应体;探针路径要求认证或返回非 2xx 时会判定失败。
  2. 端口是否一致。 探针端口与实际监听端口不一致是常见配置错误;使用命名端口时需确认端口名在容器中已声明。
  3. 检查项是否过重。 就绪探针包含了下游依赖检查时,下游抖动会导致实例被反复摘除与引入。
  4. 阈值是否过紧。 timeoutSeconds 小于端点正常响应时间、或 failureThreshold 过小,会使偶发抖动被判为失败。
  5. 触发是否与资源相关。 内存压力下的停顿、CPU 节流造成的响应变慢都会使探针偶发超时,此时探针失败是症状而非根因。

容器层健康检查反复失败的定位方式(取出探针命令手工执行、对照实际监听、对照日志时间线)见 容器排障与命名空间诊断 的健康检查一节。

3.7.4 CPU 节流导致接口变慢

现象:接口延迟出现周期性毛刺,容器 CPU 使用率稳定贴在限额附近,GC 与堆指标正常。

判据:读取 cgroup 的 CPU 统计,nr_throttled 与 nr_periods 的比值明显大于零且 throttled_usec 持续增长,即可判定配额不足。

排查方向:

  1. 核对该实例的 limits.cpu 与 -XX:ActiveProcessorCount 是否一致,JVM 是否按可见核数(大于配额)推导了 GC 与编译线程数。
  2. 核对业务线程池的并发度是否超过配额可承载的范围。
  3. 确认是否由同一节点上的其他容器争抢导致,requests.cpu 与 limits.cpu 的差距过大时更容易出现。
  4. 判断提高配额与降低并发度哪个更符合成本约束,注意配额不足时增加线程数无效。

3.7.5 镜像拉取失败

现象:实例停留在 ImagePullBackOff 或 ErrImagePull,容量无法补齐。

排查方向:

原因 表现 处理方向
标签不存在或已被清理 事件中提示 manifest unknown 核对保留策略与流水线推送的标签;确认标签未被不可变规则拦截后覆盖
仓库凭据失效 事件中提示 unauthorized 或认证失败 更新拉取凭据对象;核对凭据的有效期与作用范围
网络或仓库不可达 事件中提示连接超时 核对节点到仓库的网络路径与解析
节点磁盘不足 事件中提示写入失败 清理节点镜像与缓存,核对节点磁盘阈值
摘要与标签不一致 拉取到非预期内容 改为按摘要部署,核对标签当前指向的摘要

标签保留策略、不可变规则的拦截行为与标签指向的查询方式见 镜像仓库与治理。

3.7.6 时区与编码不一致

现象:日志时间与本地时间相差固定小时数,或中文内容显示为乱码。

成因与处理:

  1. 时区。 容器默认使用协调世界时,日志时间戳与业务时间处理都会偏移。处理方式是在镜像内固定时区(ENV TZ=Asia/Shanghai),或挂载宿主机的时区文件;使用精简基础镜像时需额外安装时区数据包。同时需核对 JVM 侧的时间设置与数据库连接的时区参数,任一处不一致都会产生偏移。
  2. 编码。 基础镜像未设置区域与编码时,文件读写与日志输出可能使用非 UTF-8 编码。处理方式是在镜像内设置 LANG 与 LC_ALL 为 C.UTF-8,并在 JVM 参数中显式指定文件编码,而不是依赖平台默认值。

容器日志中的时间与编码问题及其处理方式见 容器日志管理。

3.7.7 日志写入容器层导致磁盘膨胀

现象:节点磁盘使用率持续上升,最终触发节点驱逐或镜像拉取失败;容器可写层占用较大。

成因:容器有两处日志落点,二者的膨胀机制不同:

路径一:应用写入容器可写层内的文件
    日志随容器可写层保留,容器重建才释放
    危害:占用节点磁盘,且随容器生命周期累积

路径二:应用写入标准输出,由运行时捕获
    日志由运行时的日志驱动落盘(默认 json-file 不自动轮转)
    危害:日志文件持续增长直至写满磁盘

处理方向:

  1. 应用日志输出到标准输出,由平台采集。 不向容器内文件写入日志,避免日志随容器可写层累积。
  2. 对运行时捕获的标准输出日志配置轮转。 默认日志驱动不自动清理,需在运行时配置中设置单个文件大小上限与保留文件数,或改用自带轮转能力的日志驱动。
  3. 应用自身写入文件的日志需配置轮转。 挂在卷上的日志文件由应用或宿主机侧的轮转工具管理;注意轮转方式与容器内打开的文件描述符的关系,重命名方式会使进程继续写入旧文件,需要配合重新打开或截断方式。
  4. 同时核对空间与 inode 两类容量。 少量大文件与大量小文件造成的耗尽类型不同,判据是磁盘剩余空间与 inode 剩余量两项指标。

容器日志的落点、驱动配置与轮转设置见 容器日志管理 与 linux: 日志轮转,节点与主机侧的容量告警配置见 linux: 监控与告警。


四、总结

部署对象从主机变为编排系统后,被替换的前提有四组: 资源视图由"整机可见"变为"cgroup 限额约束下的部分可见",生命周期由人工掌握变为由探针与控制器掌握,实例由长期存在变为默认可随时替换,交付物由"发布包加环境配置"变为"不可变镜像加外部注入配置"。这四组变化的共同后果是,部署从"一次做对"变成"每次都要做对"。

原理层面的五条主线:

  1. 资源视图。 容器内部分接口反映宿主机而非限额;容器感知解决的是默认堆容量推导,没有解决线程数与堆外上限;进程内存是堆与元空间、线程栈、直接内存、代码缓存等的总和,限额必须覆盖总和并留余量;CPU 配额不足表现为周期性延迟毛刺与节流计数增长,此时增加线程数无效。
  2. 镜像分层。 层的失效条件是"指令文本或输入内容变化,且父层命中";依赖声明与业务代码分离优化的是增量分发,不改变解包与启动耗时;镜像体积通过拉取时间、扩容与故障转移速度、节点磁盘占用三条路径影响部署。
  3. 生命周期与流量。 启动探针判定启动完成,就绪探针决定是否接流量,存活探针决定是否重启;三者失败后果不同,因此判定条件必须分开设置;优雅下线需要依次完成摘流量、等待存量窗口、处理在途请求、释放资源,任一段缺失都会产生请求失败;强杀会导致在途请求失败、写入未落盘与状态不一致。
  4. 启动加速。 CDS 与 AppCDS 把类加载与校验的结果归档复用,归档与 JDK 版本、类路径绑定,需随镜像重建;原生镜像以构建期静态化换取启动与内存收益,代价是动态特性适配、构建复杂度与诊断手段变化。
  5. 发布模型。 滚动的代价是新旧共存与启动慢导致推进慢,灰度的代价是需要分流能力与单独的指标对照,蓝绿的代价是双份资源与数据层兼容;副本数大于 1 后,本地会话与本地定时任务必须外置或选主,无状态化改造需要区分必须外置、可本地化但需重建、不能简单外置三类状态。

实现层面的七项实践: 镜像构建以多阶段加依赖分层为基线,最终镜像只保留运行时与产物,入口使用 exec 形式,标签采用语义化版本加提交标识且生产不使用 latest;JVM 参数按"堆上限按限额比例、堆外各项显式设上限、核数按配额显式指定"组织,并与限额在同一处审阅;探针阈值由最坏停顿与最慢启动推导,优雅停机的时间预算满足"宽限期大于 preStop 等待加在途请求处理";资源设置遵循"内存 limits 必须设、CPU limits 按场景设、requests 按稳态用量设";配置按变更频率与审计需求在环境变量与配置中心之间分配,密钥不进镜像、不进日志、独立轮换;发布前核对探针、参数配比、容量三项,发布中分开观察新实例与旧实例,回滚触发条件量化写成;数据库变更遵守"先扩展、后发布、再收缩"的顺序。

部署阶段的七类常见问题各有固定的首查项: OOMKilled 先比容器限额、进程 RSS 与堆用量三项数值;启动超时先核对启动探针阈值与启动路径上的外部依赖;就绪反复失败先手工在容器内请求探针端点;CPU 节流先读节流计数并核对核数感知参数;镜像拉取失败先看实例事件中的具体原因;时区与编码问题需在镜像内固定而非依赖运行环境;磁盘膨胀需区分容器可写层写入与运行时捕获的标准输出两条路径。

需要显式防范的五类操作:修改资源限额(会触发重建、引入节流或使堆配置与限额失配)、调整探针阈值(会改变重启与摘流的判定行为)、强制重建实例(会清空本地状态并使新配置在全量实例同时生效)、修改 JVM 参数并重启(参数错误会直接引入故障且影响面为全量实例)、变更发布策略(会改变发布期间的容量下限与共存时长)。这类动作的统一流程是"在预发环境验证、在单个实例灰度、保留原值备回滚、记录变更前后数值"。

一句话记忆:起点是限额而非整机;镜像是制品、分层优化增量分发、体积影响拉取与扩容;堆外要有上限、核数要按配额;探针三分、超时大于最坏停顿;下线先摘流量、再等窗口、后处理在途;配置从外部注入、密钥不进镜像;发布先定回滚条件、数据库先扩展后收缩;出问题先比限额、RSS 与堆三项数值。