运维文档体系建设本质上是对团队隐性知识的显性化管理。很多团队在业务规模扩张后，会发现核心系统的操作逻辑只存在于个别老员工的脑子里，一旦人员流动或夜间故障，排查效率急剧下降。建立体系并不是简单地把文件堆到共享盘，而是要从使用场景出发，定义清楚文档的分类、 owner、更新触发点和检索方式，让文档真正参与日常运维闭环。
一、运维文档的内容分类与边界划分
在动手写文档之前，首先要解决的是“写什么”的问题。如果把所有东西都往知识库里塞，结果就是没人看得完，搜索也搜不到重点。通常我们可以将运维文档划分为四大类：系统架构类记录全局拓扑与依赖关系，操作手册类描述具体的部署、扩容、切流步骤，事件复盘类沉淀故障原因与改进项，制度规范类明确权限、值班和审批流程。每一类对应的读者和维护者都不同，例如架构类由技术负责人每季度评审，操作手册由模块 owner 在每次变更后更新。
边界划分的另一个重点是避免文档与代码仓库职责重叠。很多团队把部署脚本的说明也写进 wiki，但脚本本身就在 Git 里且有 README，这时文档只需写“为什么这样设计”和“异常时如何回滚”，而不是复述命令。我们建议用下表来区分存放位置：
| 内容性质 | 推荐位置 | 更新方式 |
|---|---|---|
| 可执行脚本与配置 | 代码仓库 | 随代码提交 |
| 系统设计权衡说明 | 知识库架构类 | 负责人季度评审 |
| 线上操作步骤 | 知识库手册类 | 变更单关联更新 |
| 故障时间线 | 知识库复盘类 | 事件关闭后三天内 |
当分类和边界清晰后，新人有据可循，老人也愿意维护，因为每次写的内容都是“补缺”而不是“重复造轮子”。这也是文档体系能持续运转的基础。
二、模板规范与写作习惯的强制约束
文档写得好不好，很多时候取决于有没有模板。自由格式看似灵活，实则让后续检索和自动化解析变得困难。我们给操作手册类定义了固定结构：背景、适用环境、前置条件、步骤、验证方法、回滚方案。事件复盘类则强制包含时间线、影响面、根因、短期修复、长期改进、责任人。通过模板，任何人打开文档都能在十秒内定位自己关心的部分。
除了结构模板，还要统一术语和敏感信息处理规则。比如内部主机名必须用脱敏后的逻辑名，真实 IP 在文档中只允许出现在受限访问的“生产环境附录”中。下面是一段用于自动生成操作手册骨架的 Python 脚本示例，它在每次新建变更单时往知识库写入草稿，减少人工从零开始的成本：
import requests
def create_doc(title, owner):
# 调用知识库 API 创建带模板的文档
payload = {
"title": title,
"owner": owner,
"template": "ops_manual",
"sections": ["背景", "适用环境", "前置条件", "步骤", "验证方法", "回滚方案"]
}
resp = requests.post("http://127.0.0.1:8080/api/doc", json=payload)
return resp.json()
print(create_doc("订单服务扩容", "zhangshan"))
模板如果只是建议，很容易被忽略，因此要将其嵌入流程。例如 CI 流水线在合并运维相关仓库时，检查关联文档链接是否存在；变更评审会上，缺少对应手册草稿的不予通过。用机制而不是自觉性来保证规范落地，文档质量才会稳步提升。
三、文档生命周期与自动化维护机制
文档最怕写完即死。我们见过太多 wiki 上写着“当前使用 MySQL 5.6”，而生产早已升级到 8.0。解决过期问题不能靠人工定期巡检，而要让文档的更新绑定系统事实。一种做法是定时任务抓取 CMDB 中的版本、拓扑数据，与文档中的声明做 diff，不一致就在文档头部打“可能过期”标签并通知 owner。
生命周期管理还涉及权限与归档。离职人员的文档必须在一周内完成转移，否则设为只读并挂到“历史归档”空间，避免误编辑。对于一年无访问且无关联变更的文档，自动折叠进冷知识区，减少干扰。以下 Shell 片段演示了如何列出超过365天未修改且无人认领的文档 ID，供后续归档脚本调用：
#!/bin/bash
# 查找老旧且无 owner 的文档记录
find /var/ops_docs -type f -mtime +365 | while read file; do
owner=$(grep -c "owner:" "$file")
if [ "$owner" -eq 0 ]; then
echo "需归档: $file"
fi
done
当文档的生老病死都有系统看管，团队对知识库的信任度才会提高。大家愿意查、敢照着做，运维文档体系才从“面子工程”变成真正降低 MTTR 的生产力工具。体系建设没有终点，它应与监控、变更、复盘机制长在一起，而不是孤立存在。