微服务架构 | nacos - [配置上线规范]
@
§1 背景
不重要
对于直接将 nacos 开箱即用的组织比较有意义，实力与精力允许的组织，建议自研、二开、上云
§2 术语
【双级审核】：配置项从配置到实际上线，至少经历过两级检查
【双人复核】：配置项从配置到实际上线，至少有另一个人（要求了解相关配置）进行复核
【复核 VS. 审核】：审核强调流程上的完整，复核强调对其功能含义、业务含义上的校验
【checklist】：设计文档中必须包含此部分，用于备注代码之外的所有关键调整，包括但不限于依赖、配置、策略变更、定时任务变更、白名单变更、开关变更
【变更收敛】：变更的配置足够醒目、集中，使相关人员可以轻易找到、找全、看懂
【上线流程】：显示输出上线报告，包括需求说明、关键调整点、审核记录、回滚方案等
【灵魂考问】：出现事故后，不仅需要复盘问题本身，还需要复盘事故出现的原因、事故发酵的原因等
【配置块】：业务上相关或性质上相关的配置，应在空间上紧密相连（配置在一起），而不应该离散
§3 规范内容
配置内容
【强制】 配置在 nacos 中的内容必须使用合适的格式，以取得较高可读性，并促进变更收敛
弱结构的长值：如长黑白名单，单开 text 配置，注意换行
强结构的长值：如长json，单开 json 配置，将原计划的长 json 的值格式化后放入其中
更多优化格式请自行探索，保证应用可以正常引用与使用即可
【推荐】在 nacos 中使用 text/json 格式的配置文件时，请仔细斟酌并在研发组内充分设计评审
配置值可以存放在配置中心、枚举、缓存、数据库、oss、随项目文件、外部文件
请结合业务灵活使用，并在研发组内做充分设计评审
若最后得出结论必须在 nacos 中使用上述格式，请参考前文内容
【建议】对于实在无法优化格式以取得良好可读性的，建议开发对应的 UI 功能，并屏蔽各种直接手动修改配置的途径
UI 功能可以
- 帮助修改者读取、解析、格式化配置，使修改者人员容易找到修改点
- 帮助修改者记录操作日志、校验格式、发起审批流、对比修改内容、持久化配置，辅助符合、避免手残
【强制】 长久不变化的配置，不应该在 nacos 中配置，至少在不破坏配置块的前提下拆分到其他文件
典型如：MQ 的 topic、消费者组、dubbo-group
【强制】 业务相关的配置应该成配置块，必须在空间上紧密联系，方便理解与审核
如下所示，一整块是一个洗数任务的配置，应放在一起
# 是否允许任务执行，用于中断任务 job.clean.allow=1 # 洗数范围控制字，第二位的 -1 表示清洗到最后一个数据 job.clean.ctrl=0,-1 # 单次拉取的数据的窗口大小 job.clean.window=200 # 每轮拉取数据的间隔时长，毫秒 job.clean.period=1050【注意】 假设 job.clean.window 值是不变的，考虑配置项的关联紧密程度，也不应该单独将此配置从 nacos 拆除
【强制】 配置项应尽量有详细的注释说明，除非配置的 key 起的足够望文生义且值也不需要说明
方便复核同学理解，方便后来者理解与指导配置
注释内容不用面面俱到，保证在稍微理解业务与实现的前提下，能起到比较关键指导意义即可
【强制】 配置修改进入审核阶段时，必须做到变更收敛，方便复核同学复核
上述规定的内容，基本全是为了 变更收敛 服务
反例
- 单个 key 的值只有一行但是很长很长，修改量还少，肉眼翻几遍也不一定能找到改了哪里（然后往往就直接蹦过去了）
- 文件很长很长，偏偏修改点很离散（比如500行的配置平均每50行一个修改点），尤其是这么多修改点其实只是改了一两个事的情况
正例
- 一眼就能看到，太长了就拆分、换行
测试
【强制】 所有需要上线的配置必须在测试环境<显示的>配置过，并经过测试
在测试环境测试，至少可以保证配置项（即配置的 key 本身不会导致问题）
<显示的>，可以避免线上环境进行了声明，但测试环境使用默认值因此不用配置所导致的漏测
【建议】测试环境各个组件、中间件尽量与线上配置保持一致
以避免测试环境的测试不能说明线上问题
如对于一个 MQ 的 topic，生产环境和测试环境配置的消费者组不同
上线
【强制】 需要上线的内容必须经过了设计评审
设计评审的形式、频率、时长在此规范中均不作强制性规定，但需要满足下面要求
- 凡是需要上线的修改，必须都进行了设计评审
- 设计评审时，必须有设计文档（经过实践的，较小改动量时，通常可以在半小时之内完成设计文档的撰写）
- 为了强调可行性，设计文档的形式、格式、内容、篇幅等在此规范中均不做完整的强制性规定
- 必须包括上线 checklist，且 checklist 中必须包含配置调整部分（如果有）
- 尽量包含测试支持相关：明确的说明重要的修改点的测试方法，此文档中只强调对配置调整的测试
- 必须包含上线计划：如果没有特殊情况，通常是灰度发布、然后观察日志、然后全量发布
- 必须包含回滚策略：如果没有特殊情况，通常是直接回滚、开关切换二选一
- 每个需求或修改，都必须指定主评审人，并记录在设计文档中，且主评审必须参与评审
- 每个需求或修改，都必须指定主测试，并记录在设计文档中，且此测试同学尽量参与设计评审
说明：这里有个问题，原则上测试同学确实没有必要了解设计方案但是一个实践中的问题在于：没有对设计有一定了解的前提下，怎么保证测试是充分的？
因此强烈建议设计阶段就结合实际情况明确这个问题
PS：设计评审不仅仅局限于形式
换句话说，在设计评审阶段被驳回，修改甚至重新设计后做二次评审是完全正常的现象
【强制】 nacos 配置上线时，采取双人复核制
双人复核执行时机：【发布】与【确认发布】之间，如下图所示
第二人限制：主评审 或 主测试（要求对当前配置的增改有一定了解）
双人复核行为：在【确认发布页】遍历修改点（黄色区域），按 checklist 依次检查各项，完全确认无误后才能确认发布
checklist：当前 checklist 理论上适合绝大多数场景。可以直接使用，也可以在自己的设计阶段调整扩充，涉及到上线无论多怂都是不过分的
【强制】 nacos 配置上线时，采取双级审核制
第一级：先进行【双人复核】，在配置本身和业务层面进行审核
第二级：技术经理或直属领导、团队中指定的负责人，在需求实现合理性和跨团队影响层面进行审核，保持流程完整
第二级结合实际情况觉得是否执行
【建议】测试介入上线流程
从实际出发，对于一个需要上线的需求或变更，将人员按熟悉程度和关联程度排序可得如下顺序
开发人员 > 主测试 > 主评审 > 技术经理 = 直接负责人
下面是一个经过实践验证的流程（但对测试团队要求稍高，可能需要根据实际情况调整）
- 此流程的本质是强调：上线日所有相关人员将上线这个事做为最高优先级的工作，另外当时实践时相关人员包括产研测
- 计划上线日，测试团队统计
- 所负责部门所有待上线需求，以及每个需求所有相关项目，涉及到交叉的项目与核心项目重点关注
- 涉及到跨团队协作的需求，需要双方产研测提前沟通上线顺序、影响
- 计划上线日，主测试进行全量回归，通过后才能正常上线，否则延期上线或打回中止
主要是为了防备跨度较长的需求有测试后修改，顺便相关人员进行一下复习- 上线前，明确上线计划和回滚计划
- 上线后，除非可以明确无流量、开关关闭或不具备条件，否则需要第一时间观察日志，进行线上验证
- 上线日严禁临时搭车上线，严禁休息日前上线，严禁安排额外的活动（其实就是排除所有脱离人员管控的因素）
【强制】 上线过程中，如果在配置变更后已经发现异常情况，严禁拖延，马上回滚并进行公告，排除异常情况后再进行二次操作
基本确认异常后不要纠结，马上执行回滚，防止影响扩大，即使后面发现异常由其他原因引起，最多再滚回来
也不要试图默默地还原消除异常，及时对异常情况公告以便有涉及的团队排查可能存在的影响，即时处理、止损
回滚时，务必核对回滚的信息是否准确，包括配置项、配置文件类型、与回滚点
【建议】生产环境上，配置变更时，通过复制并注释原值的方式进行修改
用于降低修改配置、回滚时造成二次伤害的概率，如下所示
### xxx任务command，clean / check / repire ### 原值 ### job.xxx.command=check job.xxx.command=repire
【建议】经常进行上线的同学进行回滚演练，包括项目回滚和配置回滚，尽量避免因此导致二次伤害
进行了回滚可能导致比不回滚更严重的后果
比如因为配置不全导致部分消息未消费，回滚时，只回滚了部分项目（不全）结果积压的消息错误的消费了
清洗错误数据远比处理积压复杂
复盘 & 总结
【建议】引入灵魂拷问，旨在引发反思，促进相对更边缘当可以降低事故率的措施
灵魂拷问通常由若干个 why 组成，下面这套问题是被实际应用的，以供参考
1、为什么会发生问题？
2、为什么会有这么大的影响？
3、为什么响应的这么慢？（故障发现手动的不充足，验证意识缺失）
4、为什么处理时间这么长？（缺应急预案/回滚方案，没有故障预演）
5、为什么上线前没有发现问题？（测试缺失）
严禁将灵魂拷问执行成鞭尸仪式，必要时可以隐藏甚至忽略部分信息（的收集）
【强制】 因 nacos 配置导致的线上问题，必须复盘， 包括记录、总结、分享，以便吸收经验，吸取教训
只强调相关问题本身的复盘，可以促进整理更加通用的 checklist 或相关措施
也可以帮助各团队生成更符合自身情况的执行细则
考虑信息汇总难易程度，建议由测试或独立部门主持
历史配置(存量配置)
【强制】 各个团队即日起梳理历史配置的规范化改造计划
本规范中只强调计划的输出，旨在促进各个团队思考相关事宜并得出相关结论
比较通用的思路是：
- 首先，盘点各项目配置文件（尤其是特长的那种），整体上了解有哪些配置
- 以此为基础，拆分配置文件，不改变任意key与值
- 调整配置先后顺序，使同业务、同性质的配置成块
- 从配置中心拆除约等常量的配置，并保证程序正常
- 调整可读性差的配置，并保证程序正常
- 最终确认范围、粒度、涉及人员、优先级与相对宽泛排期
改造计划执行的每一个阶段，都格外强调回归的重要性，严禁所谓一步到位 （除非修改量极小）
§4 参考 CHECKLIST
复核 checklist
- 是否经过设计评审
- 是否增加了适当的注释
- 是否具有适宜的可读性
- 是否经过测试
- 是否与测试环境的key保持一致
- 是否与测试环境的值有区分
- 上线的值是否经过了基本的验证（典型的如格式是否正确）
审核 checklist
- 是否经过设计评审
- 是否经过测试
- 是否适合采用这种实现方案
- 采用当前方式配置是否会对其他团队产生影响
浙公网安备 33010602011771号