参数通常散在三处：启动脚本里的 -Xmx、Dockerfile 里的环境变量、运维平台的运行时覆盖。某天有人为压一次告警在其中一处加了个 -XX，服务好了，全组没人知道。三个月后问题复发，所有人对着三处配置猜生效值。
参数不是配置细节，而是运行时行为的一部分。治理要回答的不是"该给多少"，而是三件事：唯一来源、变更可见、效果可验。
1. 三个目标与对应的失败形态
| 目标 | 没做到时的表现 | 判据 |
|---|---|---|
| 唯一来源 | 三处各不相同，没人知道生效值 | 一条命令能回答"生效参数是什么、来自哪一层" |
| 变更可见 | 参数被改过，无人评审、无记录 | 每次参数变更都有变更单与责任人 |
| 效果可验 | 改完"感觉好了"，指标没对照 | 变更前后同口径对照，差异可解释 |
最容易糊弄的是第三项：参数改动常伴随发版、扩缩容、流量变化，"改完变好了"很可能是别的原因。
2. 四种来源与优先级混乱的后果
| 来源 | 典型形态 | 谁在改 | 可见性 |
|---|---|---|---|
| 启动脚本 | java -Xmx2g -jar app.jar |
开发 | 高，在仓库里 |
| 容器环境变量 | JAVA_OPTS=-Xmx2g |
运维、CI | 中，在部署描述里 |
| 应用配置文件 | 框架读取的自定义属性 | 开发 | 中，常与 JVM 无关 |
| 平台下发 | 控制台上的运行时覆盖 | 值班、SRE | 低，登录平台才看得见 |
混乱的后果有三个：同名参数重复时以最后一个为准，但很多参数不支持重复，重复会启动失败；平台覆盖常只对新建实例生效，滚动发布后一半新值一半旧值；配置文件里的"内存上限"往往只是应用自己的缓存预算，却最容易被当成堆。
─── 反例：同一份参数写两遍，靠"最后一个赢"
ENV JAVA_OPTS="-Xms2g -Xmx2g -XX:+UseG1GC"
ENTRYPOINT ["sh", "-c", "java -Xmx3g $JAVA_OPTS -jar /app/app.jar"]
实际生效是 -Xmx2g，读代码的人会以为 3g。这不是灵活，是把冲突藏进一行 shell。
3. 收敛到哪一份
目标不是"只有一处能改"，而是只有一处是权威，其余是受控覆盖。
| 方案 | 权威在哪 | 覆盖方式 | 代价 |
|---|---|---|---|
| 全写进启动脚本 | 脚本 | 无 | 每次改都要重建镜像 |
| 全交给环境变量 | 部署描述 | 建镜像时无需知道 | 参数变长串，易错 |
| 外置基线 + 环境变量覆盖 + 平台只读 | 仓库里的基线文件 | 按需覆盖单项 | 需要解析层，且要能打印来源 |
| 平台全权下发 | 平台 | 平台 | 最不可见，不宜作唯一权威 |
推荐第三种：基线进仓库、环境变量做覆盖、平台只读展示。它把"参数该是什么"与"这台机器想改成什么"分开：前者可评审，后者可回滚。
─── 基线文件：一行一个参数，注释写理由，进仓库走 PR
$ cat jvm/baseline.args
-Xms2g
-Xmx2g
-XX:+UseG1GC
-XX:MaxGCPauseMillis=200
-XX:+HeapDumpOnOutOfMemoryError
-XX:HeapDumpPath=/var/dump
-Xlog:gc*:file=/var/log/gc.log:time,uptime:filecount=5,filesize=20m
─── 生效值核对：以运行时为准，不以文本为准
$ jcmd <pid> VM.flags
$ jcmd <pid> VM.command_line
$ java -XX:+PrintFlagsFinal -version | grep -E 'MaxHeapSize|UseG1GC'
VM.flags 是实际生效值（含 JVM 推算项），VM.command_line 是启动命令行。两者不一致，通常意味着被覆盖或 ergonomics 推算——这正是要记录的地方。
4. 参数分类与生命周期
| 类别 | 例子 | 变化频率 | 谁该有权改 | 验证方式 |
|---|---|---|---|---|
| 内存 | -Xms、-Xmx、MaxDirectMemorySize |
随规格与限额变 | 开发提，运维批 | 堆曲线、GC 频率、OOM 记录 |
| GC | +UseG1GC、MaxGCPauseMillis |
低 | 需性能负责人 | 停顿分布、P99 |
| JIT | TieredStopAtLevel、CICompilerCount |
极低 | 需基准数据 | 启动时长、预热曲线 |
| 诊断 | GC 日志、heap dump、JFR | 阶段性 | 开发 | 磁盘占用、启动开销 |
| 兼容性 | --add-opens、allowAttachSelf |
随依赖升级 | 开发 | 启动成功、反射路径可用 |
生命周期不同，力度也不同：内存与 GC 类需双人评审；诊断类要有有效期；兼容性类跟依赖版本一起退役。
最容易被遗忘的是诊断类：+HeapDumpOnOutOfMemoryError 配一个不设上限的转储路径，会把一次 OOM 变成一次全站故障；GC 日志常开但必须配轮转（filecount 与 filesize）。
5. 改参数等价于改代码
同一条纪律应同时约束两者，差别只在回滚速度：参数改错重启即可，代码改错要走构建。这差别常被用来给参数变更开绿灯，结果是参数成了绕过评审的后门。评审、理由、可回滚、有验证、有责任人，五项都不该省。
─── 参数文件的守门脚本：拦住无理由、无边界、重复定义的改动
$ git diff --unified=0 jvm/baseline.args | grep '^+[-]' | grep -v '^+++'
$ grep -cE '^-Xmx' jvm/baseline.args // 必须是 1，重复即埋雷
$ grep -E '^-XX:HeapDumpPath' jvm/baseline.args // 有 dump 必须有路径
$ grep -E '^-Xlog:gc' jvm/baseline.args // 有 gc 日志必须有轮转
这类脚本的价值不在"拦住多少"，而在把隐含约定变成断言。参数评审很容易退化成"看着差不多就行"，脚本是唯一不疲劳的评审者。
6. 验证：基线对照怎么才算对照
| 手段 | 能回答什么 | 成本 | 局限 |
|---|---|---|---|
| 生效值核对 | 改没改到 | 低 | 不说明效果 |
| GC 日志指标 | 停顿分布、回收频率、晋升量 | 中 | 受流量形态影响大 |
| P99 与错误率 | 端到端是否变好 | 中 | 混淆变量多 |
| 压测回放 | 可控负载下的对照 | 高 | 与真实流量有差距 |
对照的基本要求是同口径：同一时段、同一负载形态、同一采集口径。GC 对流量形态极敏感，工作日高峰对比周末凌晨只反映流量差异。
─── 变更前：先把基线落盘，别相信记忆与截图
$ jcmd <pid> VM.flags > /tmp/flags.before
$ grep -E 'Pause' /var/log/gc.log | tail -200 > /tmp/pause.before
─── 变更后：同样采集、同样时间窗，至少两轮
$ diff <(sort /tmp/flags.before) <(jcmd <pid> VM.flags | sort) | head -40
单轮分不清"参数效果"与"当天流量"，两轮方向一致才勉强算证据。
7. 堆与容器限额的强耦合
| 事实 | 后果 | 处理 |
|---|---|---|
| 容器 limit 是硬墙，堆只是其中一部分 | 堆按物理内存比例推算时会被 OOMKilled | 容器感知写法或显式写死 |
| 堆外还有元空间、线程栈、直接缓冲、代码缓存 | 堆设到 limit 的 100% 必然被杀 | 预留堆外空间，按应用规模定 |
| limit 改了参数没改 | 参数变成"刚好卡住"的隐患 | limit 变更与参数变更绑成一次变更 |
| 老版本对容器的识别能力不同 | 读不到 cgroup 限额 | 按实际 JDK 版本核对行为 |
核对要三方对齐：cgroup 的 memory.max、GC.heap_info 的提交量、VM.flags 的堆上限，缺一个别下结论。典型量级是堆占 limit 的六到八成，其余留给元空间、线程栈与直接缓冲。
8. 漂移检测与度量
漂移不是"有人乱改"，而是合法的局部改动累积：紧急扩容临时加的 -Xmx 没人删，排障开的 JFR 忘了关。
─── 巡检：把所有实例的生效参数拉平比对，差异即漂移
$ for h in $(cat hosts.txt); do
> ssh "$h" "jcmd \$(pgrep -f app.jar | head -1) VM.flags" | sed "s/^/$h /"
> done > /tmp/flags.all
$ awk '{print $NF}' /tmp/flags.all | sort | uniq -c | sort -rn | head
| 度量 | 采集方式 | 用途 | 反噬 |
|---|---|---|---|
| 参数项数 | 基线文件行数 | 判断是否膨胀 | 项数多不等于治理好 |
| 变更频次 | 变更单计数 | 发现高频抖动 | 低频也可能是无人敢碰 |
| 变更验证率 | 有对照记录的变更占比 | 治理成熟度核心指标 | 靠自觉填报，容易注水 |
| 参数相关故障数 | 归因标记 | 判断是否在起作用 | 口径不一致会失真 |
| 漂移实例数 | 巡检差异数 | 发现局部改动 | 频率低时只能事后发现 |
"变更验证率"最值得盯：不看你改了多少，只看改完有没有对照。它长期偏低，说明机制只在纸面上。
9. 排错
| 现象 | 原因 | 处理 |
|---|---|---|
| 改了参数但行为没变 | 覆盖层级更高，或参数拼写不被识别 | jcmd VM.flags 看生效值，查 unknown 警告 |
| 启动直接失败 | 同名参数重复，或参数被新版本废弃 | 看启动日志首行报错，逐项与版本核对 |
| 容器被 OOMKilled 但堆没满 | 堆外内存与 limit 不匹配 | 同时看 cgroup 事件与 NMT 基线 |
| 一半实例新值一半旧值 | 平台覆盖只对新建实例生效 | 统一走滚动发布，并在巡检里对齐 |
| GC 日志写满磁盘 | 没配轮转 | 补 filecount 与 filesize，加磁盘水位告警 |
| dump 触发时服务不可用 | 路径所在盘满，或 dump 期 STW 过长 | 限定目录与配额，或改为按需触发 |
10. 边界
| 场景 | 为什么正式治理收益低 |
|---|---|
| 单一小服务、无性能诉求 | 参数项少，一份文件加一句注释就够 |
| 托管运行时已封装参数 | 能改的只剩少量旋钮，机制边际价值低 |
| 团队只有一两个人 | 沟通成本天然低，"可见"不需流程保证 |
| 服务生命周期短（一次性作业） | 治理成本高于参数出错风险 |
| 尚无稳定基线 | 先建指标基线，再谈变更验证 |
需要治理的信号：实例数过十、参数项过二十、或已发生一次"不知道谁改的"故障。之前用轻量做法更划算。
"先加参数再说"是典型的负债化：每加一项就多一个要核对、要解释、要在升级时重新验证的对象。参数表该像代码一样有删除动作——没人能说清为什么存在的参数，就是该删的候选。
11. 自测
- 你现在能用一条命令回答"当前生效的 JVM 参数是什么、来自哪一层"吗？
- 四种来源同时存在时谁最终生效？你怎么确认而不是猜？
- 哪几类参数应该强制双人评审，为什么诊断类不必？
- 参数变更的"同口径对照"具体指哪几个条件一致？
- 容器 limit 调整后，为什么必须同时复核堆参数？
- 你的参数表上一次删除条目是什么时候？