按层次缩小范围
剧本失败的排查效率取决于排查顺序。先判断失败范围——全批失败通常是剧本本身或公共前置条件问题，个别主机失败通常是环境差异。再把问题归到某一层：连接层（网络与认证）、权限层（执行身份与文件权限）、条件层（变量与判断表达式）、业务逻辑层（命令本身与幂等性）。最后用单机单任务的最小重跑复现，避免在大批量上反复试探造成更大影响。
基本信息
| 定位顺序 | 失败范围、失败任务、问题层次、单机复现、修正重跑 |
|---|---|
| 常用手段 | 限制单主机重跑、只跑失败任务、提高输出级别 |
| 区分要点 | 连接失败不等于任务失败，任务跳过不等于执行成功 |
| 重跑前提 | 动作幂等，不会重复执行已完成步骤 |
| 记录要求 | 根因与处置写入变更或问题记录 |
典型使用场景
- 批量任务部分主机失败：按差异分组定位，避免对全部主机重复操作
- 变量未定义或取值异常：检查变量来源与默认值，确认条件是否命中
- 权限不足：核对执行用户、目标文件属主与提权方式
- 依赖服务未就绪：增加前置检查或等待逻辑，而不是简单重试
- 动作不幂等：改为按状态判定，避免重复执行产生冲突
现象与定位动作
| 现象 | 常见成因 | 定位动作 |
|---|---|---|
| 连接超时或不可达 | 网络路径或认证失败 | 用相同凭据单独测试连通性 |
| 权限被拒 | 执行身份权限不足 | 核对执行用户与目标路径权限 |
| 任务被跳过 | 条件判断未命中 | 打印相关变量取值，验证表达式 |
| 个别主机失败 | 系统版本或包名差异 | 按条件分组，为差异分支分别处理 |
| 重跑即失败 | 动作不幂等或状态残留 | 改为状态判定式逻辑并清理残留 |
| 返回成功但目标未变 | 命令静默失败或未生效 | 在任务后增加结果校验步骤 |
最小复现与重跑
最小复现与重跑
# 1. 只对一台失败主机重跑，缩小影响面
ansible-playbook site.yml --limit web-03 # 先限定单机，确认现象可复现
# 2. 只跑失败任务，从失败点继续，而不是整套重来
ansible-playbook site.yml --limit web-03 --start-at-task 'install package'
# 3. 提高输出粒度，看清变量与判定过程
ansible-playbook site.yml --limit web-03 -vvv # 调试级别按需提高，避免日志淹没
# 4. 修正后先小批验证，再放开全量
ansible-playbook site.yml --limit 'web_group[0:2]'排查期间要冻结并发：多个执行副本同时操作同一批目标会让状态错乱，失败原因被新的失败掩盖。先停下、再定位、后重跑。
「重跑一次就好了」不等于问题已解决。临时性成功的成因（时序竞争、依赖未就绪、限流）必须记录并转问题管理，否则下次发布同样位置会再出一次。