如何排查Ansible执行错误

排查 Ansible 执行错误，通常可以按照「从现象到原因、从全局到局部」的思路进行。下面是一套比较系统的方法。

一、先看清错误现象

1. 使用 -v / -vv / -vvv 提高日志级别

ansible-playbook site.yml -vvv

• -v：基本信息
• -vv：任务级信息
• -vvv：连接、模块参数、返回值（最常用）

重点关注：

• 是哪一步失败（task 名称）
• 错误信息（stderr / msg）
• 是哪个主机（host）

二、确认基础连接问题（最常见）

2. 测试主机连通性

ansible all -m ping

常见问题：

• SSH 不通
• 用户不对
• 密钥/密码错误
• 主机不在 inventory

3. 检查 inventory

ansible-inventory --list
ansible all --list-hosts

确认：

• 主机名/IP 是否正确
• 分组是否正确
• 变量是否生效

三、分析具体错误类型

4. 权限类错误

典型表现：

• Permission denied
• sudo: a password is required

排查：

[web]
192.168.1.10 ansible_user=deploy ansible_become=yes ansible_become_user=root

或：

ansible-playbook site.yml --become --ask-become-pass

5. 模块参数错误

典型表现：

• invalid argument
• missing required arguments

排查：

• 查官方模块文档
• 用 -vvv 看实际传参
• 先用手动命令验证

6. 目标主机环境问题

例如：

• Python 版本不对
• 缺少依赖包
• SELinux / 防火墙

排查：

ansible all -m setup
ansible all -m command -a "python3 --version"

四、缩小问题范围

7. 单独跑某个 task

ansible-playbook site.yml --start-at-task="Install nginx"

8. 只跑一台机器

ansible-playbook site.yml -l web01

9. 手动执行等价命令

在目标机上手动执行 Ansible 报错的命令，观察真实环境差异。

五、利用调试手段

10. 使用 debug 模块

- debug:
    var: some_var

11. 查看返回结果

- command: /some/cmd
  register: result

- debug:
    var: result

六、常见坑位速查

七、推荐排查顺序（总结）

1. -vvv 看错误
2. ping 测连通
3. 检查 inventory & 变量
4. 检查权限 / become
5. 单独跑 task
6. 手动复现
7. debug 变量

如果你愿意，可以把具体的报错信息或 playbook 片段贴出来，我可以直接帮你定位问题。