运维文档应按日常巡检、故障处理、变更操作、安全合规、环境部署五大场景组织，每个场景下分服务再按典型现象细化，配套版本绑定、责任人标识、轻量索引及禁孤本机制。
核心原则：按角色与场景组织，而非按技术分类
运维文档不是技术百科，而是解决具体问题的工具。一线人员查故障时不会想“SSH协议原理”，只会搜“服务器连不上怎么办”。文档结构要匹配真实工作流：值班工程师看告警→定位服务→检查配置→执行恢复→复盘归档。因此顶层分类应是日常巡检、故障处理、变更操作、安全合规、环境部署五大场景，每个场景下再分服务/组件，避免按“Nginx、MySQL、Kubernetes”平铺导致信息碎片化。
三级结构示例：以“故障处理”为例
一级：故障处理（对应SOP流程）
二级：按服务维度（如API服务、数据库服务、消息队列）
三级：按典型现象（如“API响应超时504”“MySQL主从延迟突增”“Kafka消费者堆积”）
每个三级条目包含：
- 现象特征（监控指标阈值、日志关键词、告警名称）
- 快速验证步骤（3条以内命令，如curl -I http://localhost:8080/health）
- 常见根因与对应命令（如“连接数满→ss -s | grep "TCP:"”）
- 恢复操作（带--dry-run提示的脚本或明确回滚步骤）
关键配套机制：让文档真正可用
- 版本绑定：每篇文档标注适用的系统版本（如CentOS 7.9 / Kubernetes 1.24）、软件版本（如Prometheus 2.37）、以及最后验证时间；
- 责任人标识：每篇文档页脚写明“维护人：张三（DBA组）｜更新日期：2024-06-12”，避免“已失效但无人认领”；
- 轻量级索引：在Git仓库README中用表格列出高频问题关键词（如“磁盘满”“证书过期”“OOMKilled”）及对应文档路径，支持Ctrl+F快速定位；
- 禁止孤本文档：所有配置模板、检查脚本必须内嵌在对应场景文档中，不单独存放，防止脚本升级后文档未同步。
避免常见陷阱
- 不写“原理概述”“架构图”等非动作内容，除非该图直接指导操作（例如“根据这张VIP流向图，判断当前流量走的是哪台LB”）；
- 不用“请确保”“建议检查”等模糊表述，改为“执行：df -h /data → 若使用率＞90%，执行下一步”；
- 不维护“所有命令大全”，只保留该场景下高频、易错、有副作用的命令（如systemctl reset-failed需谨慎，必须写清触发条件）；
- 文档中所有路径、IP、端口默认用占位符（如[APP_PORT]），配合部署时自动替换脚本，杜绝硬编码。
