Ansible 常见错误与修复方法
Ansible 排障速查：YAML 缩进语法错、SSH 连接失败、清单与变量解析错、模块参数错、性能瓶颈五大类高频错误的原因与修复，附调试技巧。
直接回答：Ansible 错误集中在五类——YAML 语法（缩进是语法的一部分）、SSH 连接（认证/权限/主机可达性）、清单与变量（组名拼错、变量未定义）、模块参数（参数名/类型不符）、性能（fork 数与事实收集）。调试三板斧：-vvv 加详细度、--check 干跑、ANSIBLE_DEBUG=1。
YAML 语法错误
YAML 缩进即语法，最常见的报错：
Syntax Error while loading YAML.
mapping values are not allowed in this context
修法：统一用空格（2 格）不混 Tab；冒号后必须空格；多行字符串用 | 或 > 块标量。编辑器装 YAML 插件实时校验，ansible-lint 跑在 CI 里。
连接错误
UNREACHABLE! 或认证失败的排查顺序：手动 ssh user@host 能否通 → inventory 里的地址/端口/用户是否正确 → 密钥权限（600）与 ssh-agent → sudo 提权配置（become 与受限 sudo 权限）。
清单与变量错误
- 组名/主机名拼错：任务静默跳过或报 "skipping: no hosts matched"——用
ansible-inventory --list验证解析结果 - 变量未定义：
'xyz' is undefined——检查变量作用域（host/group/play）与拼写，debug模块打印确认
模块错误
参数名拼错、类型不符（字符串给了列表）是主力。ansible-doc <模块名> 查参数定义比搜论坛快。
性能问题
playbook 慢：按控制机与目标机容量审慎调整 forks、关不必要的事实收集（gather_facts: false）、区分 SSH ControlPersist 连接复用与 pipelining（减少模块传输），分别测试兼容性。
常见问题（FAQ）
Q：报"no hosts matched"但清单里明明有这台机器？
A：主机模式不匹配——检查组名层级与 limit 参数；ansible all -i inventory.ini --list-hosts 看实际匹配结果。
Q：--check 干跑可靠吗？
A：多数模块支持 check mode 但非全部（command/shell 通常仅有限支持，使用 creates/removes 等条件时行为不同）。干跑用于预估变更面，不替代测试环境验证。
Q：错误信息看不出原因怎么办？
A：逐级加料：-v → -vvv（连接细节）→ ANSIBLE_DEBUG=1（内部决策）。输出可能包含敏感变量；先脱敏，避免在生产开启 ANSIBLE_DEBUG 导致泄漏。 排查变更失败时，同时保留执行时间、目标主机和 playbook 版本，方便复现。
官方参考
本文依据官方文档整理，示例未在本文中进行运行验证。生产部署需按所用版本、权限和实际负载验证。
