当集群达到一定规模后，应急预案不再是一纸空文，而是需要定期执行的「体检」流程。常见的做法是：运维人员按照一份Word或Confluence文档中的步骤，在预发布或灰度环境中逐条演练，然后截图、登录堡垒机确认状态，最后把结果汇总成演练报告。这套流程最大的问题在于——文档是静态的，而集群在变化；演练是动态的，但文档却要手动更新。一旦某个服务端口、配置文件路径或依赖关系发生调整，手头那份预案文档往往还是旧版本，导致演练过程频频受阻。更麻烦的是，每次演练后编写报告需要从各种终端里翻找命令输出、整理截图，再对齐上次的模板，耗费大量精力。
要打破这个僵局，最直接的想法就是让演练动作和文档生成绑定在一起：执行一条演练脚本，就自动记录对应的输出、环境快照，并按照既定模板拼装成一份可直接交付的文档。这样不仅能消除「写文档」这项重复劳动，还能确保文档内容与真实执行结果完全一致，因为文档本身就是从执行痕迹中派生出来的。
1. 模板化：用结构化的演练工单驱动一切
一切自动化文档的源头，应当是一份结构化的演练定义。我们自己设计了一套YAML格式的演练工单，每个工单描述一个预案场景，包含场景名称、触发条件、涉及服务列表、预置检查项、演练步骤以及每个步骤的预期结果与校验命令。例如：
scenario: redis主节点故障切换演练
services:
- redis-sentinel
- app-backend
precheck:
- cmd: "redis-cli -h 127.0.0.1 -p 26379 SENTINEL MASTER mymaster"
expect: "10.0.1.5"
steps:
- name: 模拟主节点宕机
action: "kubectl delete pod redis-master-0 -n cache"
wait: "30s"
verify:
- cmd: "redis-cli -h 127.0.0.1 -p 26379 SENTINEL MASTER mymaster"
expect: "10.0.1.6"
- cmd: "curl -s http://app-backend/health | jq .redis"
expect: "true"
这里的关键不是语法本身，而是将演练动作与校验逻辑固化成结构化数据。有了这份工单，后续无论是执行引擎还是文档生成器，都能以相同的数据结构为输入，避免理解偏差。更实用的是，我们可以为每个步骤嵌入一个可选的screenshot属性，告诉自动化流程在验证完成后自动调用截图工具，截取指定URL或终端回显。
定义好工单格式后，还需要一个模板来规定最终文档的样子。采用Markdown作为中间格式非常合适，它既能被版本控制系统轻松追踪，也能方便地转换成HTML或PDF。模板中使用占位符引用工单中的变量，比如{{ scenario }}、{{ execution_time }}、{{ step_results }}等。
2. 执行引擎：把演练脚本与文档采集串联起来
有了工单和模板，下一步就是建立执行引擎。这个引擎需要承担两个任务：按照工单定义逐步执行演练动作，并沿途采集证据。可以采用Python编写一个Runner，利用subprocess执行命令，借助paramiko连接远程主机，同时维护一个执行上下文字典，把每步的stdout、stderr、返回码以及可能的截图路径都记录下来。
对于截图需求，一个轻量的方案是集成本地Headless Chrome。在执行某个步骤的verify阶段后，如果工单中标记了截图URL，Runner自动启动Puppeteer或pyppeteer，访问该URL并生成全屏截图，将文件路径存入上下文。这里有一个技巧：为了避免截图依赖外部监控面板，可以在Kubernetes集群内运行Runner Pod，直接通过Service域名访问内部路由，这样每次截图的视角都和实际运维人员看到的完全一致，省去了配置VPN的麻烦。
当所有步骤执行完毕，上下文字典中已经包含了本次演练的全部原始数据：每一条命令的执行时间、输出内容、是否匹配预期、每一步的截图链接。接下来要做的，就是将这些数据灌入Jinja2模板。例如，模板中有一个for循环遍历所有step_results，可以将每条命令及其输出渲染成代码块，同时把截图作为图片插入。最终得到一份完整的Markdown文件，内容天然带有时间戳和真实输出，不需要任何手动整理。
3. 集成CI流水线：让文档随演练自动发布
如果每次演练还要手动触发Runner、拷贝Markdown文件、再用Pandoc转成PDF，那自动化程度还远远不够。理想的状态是：提交一次演练工单的Git变更，就能触发一条CI任务，自动在预发布集群中执行全套演练，并把生成的报告归档到文档仓库，甚至直接发布到内部Wiki。
在GitLab CI或Jenkins中，可以定义一条专门的Job，它克隆演练仓库和文档模板仓库，运行Python Runner，然后执行后续的渲染与发布脚本。例如，在Runner生成Markdown后，调用Pandoc命令将其转换为PDF，同时生成一份HTML版本用于内网浏览。为了让报告样式更专业，可以准备一份CSS文件，通过--css参数注入Pandoc，这样生成的HTML自带页眉页脚、水印和排版样式。代码片段如下：
pandoc report.md --metadata title="集群预案演练报告" --css report-style.css --standalone --toc --pdf-engine=xelatex -o report.pdf
下一步是如何将生成的文档自动归档。如果公司使用Confluence，可以利用其REST API直接将HTML上传为新页面或更新现有页面。通过Confluence的存储格式（XHTML），可以将演练报告嵌入到已有空间下，并自动添加标签（如"预案演练"、"自动生成"），方便其他团队索引。如果公司习惯用Git管理文档，则可以将生成的PDF或Markdown推送到专门的docs仓库，并在每次演练后自动提交，附上语义化的commit message，比如"演练: redis故障切换 2025-06-15 通过"。
这种CI集成还有一个额外好处：可以轻松串联告警和通知。例如，一旦Runner检测到某个步骤的预期与实际输出不符，除了在报告中高亮标记外，还可以通过邮件或企业微信机器人发送异常提醒，附带报告链接，让相关人员第一时间介入，而不是等演练结束后翻看冗长的PDF才发现问题。
4. 应对复杂集群的进阶设计
当集群环境更加复杂时，比如存在多个数据中心、混合云架构，单一的Runner可能无法覆盖所有演练范围。此时可以将执行引擎设计为分布式Agent模式，每个数据中心部署一个轻量Agent，由中心调度器统一下发演练工单，并汇总各Agent回传的执行结果。文档生成可以继续集中在中心节点完成，利用汇总后的全局上下文渲染出一份覆盖多区域的统一报告。
另一个常见痛点是敏感信息掩码。演练过程中输出的命令可能包含密码、Token等，直接写入文档会带来安全隐患。解决办法是在Jinja2模板渲染之前，通过正则过滤器对上下文中的字段进行脱敏。例如，将所有形如password=xxx的字符串替换为password=***，或者从配置文件读取需要掩码的key列表，统一处理。这样即使自动化生成的文档被广泛分发，也不会泄露敏感信息。
此外，考虑到演练预案本身也需要版本管控，可以将工单与文档紧密联动。每次更新工单时，通过CI自动触发一次「静默演练」——只执行命令，但不真正注入故障，这样可以快速验证工单的有效性，并生成一份预览报告。这样一来，预案文档始终与最新的工单定义保持同步，运维团队再也无需担心文档过时。
从实际效果来看，引入文档自动化后，一个原本需要半天人力的演练报告整理工作，现在完全被压缩到CI流水线的几分钟内，而且报告质量更高、信息更全。更重要的是，集群运维知识不再锁在个别人的头脑里，而是沉淀为可复用的工单、模板和自动化流程，真正实现了「演练即文档」的持续交付闭环。