只升了命令行没升解释服务：运行时升级的双端核对
一、为什么两边会不一致
该说明把最常见的故障原因直接写了出来：多数问题不是新版本本身出问题，而是只升了命令行解释器，或者只升了 Web 侧的解释服务。这句话之所以值得单独成段，是因为它描述的是一个结构性现象，不是操作失误。
不一致有四条典型来路。第一条最朴素：配置文件本来就有两份，命令行读一份，Web 侧读一份，路径不同、内容各自演化过，改了一边另一边没人动。第二条是运行接口类型天然是两套，一套走服务进程，一套走另一种调用方式，安装时是两个包，升级时只升了一个。第三条在容器化之后很常见：镜像换了新版本，宿主机上的命令行还是旧的，或者反过来，构建脚本用的是宿主机那一份，跑出来的产物在容器里行为不一样。第四条在多站点托管环境里最多：面板按站点或者按账户绑定版本，改全局设置只对新建站点生效，历史站点仍然挂在旧运行时上。
这四条来路里，第三条和第四条最隐蔽。它们的共同点是没有任何一个文件里写着”这里有两个版本”——版本信息分散在镜像标签、面板配置和站点绑定关系里，升级动作只覆盖了其中一处。
二、三项核对缺一不可
说明给出的做法是双向核对：命令行侧和一个 Web 侧探针页各自输出信息，比对三项内容——版本号、实际加载的配置文件路径、运行接口类型，按它的原话是三者必须完全一致。这三项按来源转述即可，我们要说的是为什么不能只看第一项。
| 核对项 | 只看版本号会漏掉什么 | 典型故障形态 |
|---|---|---|
| 版本号 | 同版本但配置来源不同 | 版本一致，错误报告级别与扩展开关完全不同 |
| 配置文件加载路径 | 配置项写在了另一份文件里，根本没被读进 | 改了半天不生效，实际读的是默认那份 |
| 运行接口类型 | 同一份配置被两种运行方式使用 | 只在某个入口出现的问题，页面正常而任务出错 |
版本号一致但加载了不同配置，是最省力气的一种错法：错误抑制、时区、内存上限、扩展开关全在这份文件里，两边不同就会得到”同一台机器上两种行为”。配置一致但跑成了另一种接口类型更麻烦，因为连配置文件都在同一个路径下看起来没问题，实际两条执行链的默认行为不一样。
三项里最容易被误当成”不用核对”的是接口类型。它的核对成本最低，但一旦不一致，排查成本最高——页面侧全部正常，只有定时任务出错，或者反过来。任何”只在某个入口出现”的问题，都该先回到这三项上。探针页本身要收在内网或者加鉴权之后，不要把配置路径和接口类型大方地暴露给外部访问。
三、并存窗口是设计出来的
说明里把核心思路分成三段：分步验证、平滑切换、快速回滚。并存窗口是”分步验证”存在的前提，而它不是自然发生的，要主动搭出来。多版本并存的可行手段按来源是三类：发行版同时保留两个版本，用模块开关与 alternatives 那类机制切；面板按账户或子目录做隔离；面板按站点指定版本。
并存窗口的工程要求有三条，这三条比手段更重要。
第一，同一套代码要在两个版本下都能跑。这意味着窗口内不许出现”为了新版本改一段代码、为了旧版本再改回来”的情况。真要动，动的应当是被两个版本都接受的同一种写法。该说明提到框架侧要替换掉过时的单例获取与导入写法，这类改动的价值就在于它向前后兼容，属于并存窗口内可以做的那一类。
第二，不能靠改代码去适配版本。代码里出现版本分支判断，等于把并存窗口永久化，最后没人敢删。
第三，定时任务与队列消费者也要指定版本。这一条是”只升一边”的另一个来源：Web 侧切过去了，计划任务脚本还在用默认那一份解释器；消费者进程是老的，队列里的任务被两种运行时交替处理。并存窗口里，凡是能独立启动进程的地方都要显式指定版本，不能依赖系统默认。
四、静态扫描能抓什么、抓不到什么
说明在切换前置动作里写了一条实用建议：把错误报告级别调到全部、打开错误日志并指向独立文件、生产环境关闭错误直接输出，然后用静态分析工具扫三类问题——被移除的旧函数调用、未声明返回类型、向数组类型提示传空值。框架侧的过时写法替换也属于这一轮。
抓不到的那半部分才是运行时升级真正的风险，也是我们做兼容评估时最容易高估自己的地方：
- 依赖扩展的行为差异。扩展是编译进去的，静态分析看不见它返回值的细微变化。
- 时区与浮点格式化。同一行代码在不同默认设置下给出不同字符串，落进数据库或者导出文件里才对上。
- 被废弃但仍在用的隐式转换。工具报的是”废弃警告”，很多人直接把它归为噪音，实际是行为改变的前兆。
这三类只能靠用例覆盖，不能靠扫描器。所以我们的做法是：静态扫描负责”能不能跑起来”，用例负责”跑起来对不对”，两者不许互相替代。错误日志指向独立文件这一条看着小，实际决定了并存窗口里能不能分辨是新版本产生的错误还是旧版本一直就有的。
五、观察期盯四条路径与两类指标
说明给出的观察期是上线后 24 至 48 小时，要盯四类关键路径：首页、登录、支付回调、后台导出。这四个选得准，因为它们各自代表一类风险：首页代表最高频渲染路径，登录代表会话与密码学相关扩展，支付回调代表外部发起、不带页面上下文的入口，后台导出代表长执行时间与大内存。任何一类出问题，另外三类可能完全正常。
观察期要定成可自动探测的东西，不能写成”注意有没有人反馈”。
- 每条路径各设一条检查：一个不依赖登录态的首页可达性判断、一条模拟登录的探针、一个能验证回调签名与幂等的固定样本重放、一个限时的导出任务，按固定频率跑。
- 两类指标做对照：错误日志的新增量，以及状态码分布相对基线的偏移。前者抓崩溃与废弃警告，后者抓”没报错但结果不对”。
- 判定权要写清：由谁在什么时点宣布观察期结束，未通过时是延长观察还是回滚，不要把决定留给”感觉没问题的人”。
- 窗口内冻结其他变量：并存期间不要再上业务改动，否则指标一动就说不清是谁干的。
第四点最常被违反，代价也最实在——观察期的意义全在于只有一个自变量。切换顺序本身也按同一条原则排：预发和一台生产节点先跑完整周期，再按站点或者按路径分流放大范围，一次只动一个变量，不要在切运行时的同一天再动配置或代码。
六、回滚设计与对客户的交付口径
说明里有一条很值得抄：在 Web 服务器加解释服务这种架构下，回滚只需要把转发端口改到旧版本，不需要重启。回滚的快慢因此取决于入口配置，而不是代码部署。这里要额外核对两件事：一是转发目标或者上游配置的变更多久真正生效，是即时、下个请求，还是要等连接回收；二是回滚之后，新版本期间新产生的数据旧运行时能不能读。第二件事常被忽略——会话与缓存里的序列化格式、新版本写进库的字段解释方式，可能已经把回滚变成一条单向门。回滚方案里要专门写明这两类数据在窗口期内如何保持双版本可读。
交付口径上，我们把它写进升级单而不是聊天记录：升级窗口与预计影响范围；双端三项核对的执行结果由谁签字；并存期结束的时间点；回滚承诺是”改一处转发配置”还是”重新部署”；观察期时长与四类路径的判定标准；验收人。除此之外还有一条归属条款——“只升一边”这类故障的排查归谁。这一类问题的现象出现在业务侧，原因在环境侧，如果不事先写明，客户会认为我们没做好，我们会认为环境不该我们动。把双端核对表作为交付件附上，归属就自然清楚了。
在洹拓经手的这类升级里，最省时间的从来不是切换那一下，而是提前把”有几个入口、每个入口用哪份配置”这件事问出来。运行时升级的难度不在版本差异，在于一个应用其实同时跑在两个世界里，而这两个世界很少被同一份清单管着。