4. Ansible 日志与调试基础
在生产环境中，Ansible 执行失败后的第一要务是快速定位根因。本章聚焦三种最实用的调试手段：详细输出模式（-vvvv）、预演模式（--check）以及持久化日志配置。掌握这些工具，可以将故障排查时间从小时级压缩到分钟级。
4.1 详细输出模式：-v / -vv / -vvv / -vvvv
Ansible 的详细输出级别决定了控制台回显的信息量。级别越高，输出的调试信息越完整，但同时也意味着更多的噪音。下表总结了各级别的适用场景：
| 级别 | 参数 | 输出内容 | 典型用途 |
|---|---|---|---|
| 0（默认） | 无 | 仅显示 PLAY 和 TASK 名称、成功/失败状态 | 日常执行，快速查看结果 |
| 1 | -v |
增加任务返回的 JSON 数据（stdout、stderr） | 验证变量值、命令输出 |
| 2 | -vv |
显示任务是否发生变更（changed/when 条件评估） | 调试条件判断、handlers 触发 |
| 3 | -vvv |
包含 SSH 连接参数、插件加载信息、facts 收集详情 | 排查连接失败、插件冲突 |
| 4 | -vvvv |
输出 SSH 原始传输数据、底层连接调试、回调插件细节 | 深度网络问题、SSH 认证失败、ControlPath 冲突 |
实战建议：日常调试从
-vvv 开始，它提供了足够的信息且不会过度淹没终端。仅在怀疑 SSH 协议层或连接复用问题时才使用 -vvvv。
4.2 预演模式：--check 与 --diff
--check 模式（又称干运行）让 Ansible 模拟执行所有任务，但不实际修改目标主机。它通过调用模块的 check_mode 接口来报告“如果执行，会发生什么变化”。
- 基本用法：
ansible-playbook site.yml --check - 结合 --diff：
ansible-playbook site.yml --check --diff会显示文件内容的预期变更（类似 diff 命令的输出），对模板和配置文件调试极为有效。 - 局限性：并非所有模块都支持 check 模式（如
command、shell模块默认跳过）；部分模块在 check 模式下仍可能产生副作用（如创建临时文件）。
注意：不要将
--check 视为安。对于不支持 check 模式的模块，Ansible 会静默跳过，导致预演结果不完整。务必在非生产环境验证 playbook 的 check 行为。
4.3 日志文件配置
将日志持久化到文件是审计和事后分析的基础。Ansible 通过 ansible.cfg 中的 log_path 配置项控制日志输出。
# ansible.cfg
[defaults]
log_path = /var/log/ansible/ansible.log
# 可选：控制日志级别（0-4，与 -v 对应）
# 注意：log_path 不直接支持级别过滤，所有级别信息都会写入
日志文件会记录每次执行的以下信息：
- 执行时间戳
- Playbook 名称与路径
- 目标主机列表
- 每个任务的执行结果（ok/changed/failed/unreachable）
- 错误堆栈与模块返回的原始 JSON
日志轮转建议：生产环境务必配置 logrotate 防止磁盘写满。示例配置：
/var/log/ansible/*.log { daily; rotate 30; compress; delaycompress; missingok; notifempty; }
4.4 调试工作流：从失败到根因
下图展示了当 Ansible 执行失败时，如何组合使用上述三种调试手段进行系统化排查：
4.5 综合配置示例
以下是一个生产环境推荐的 ansible.cfg 调试相关配置片段：
[defaults]
# 日志持久化
log_path = /var/log/ansible/ansible.log
# 显示任务耗时，便于定位慢任务
callback_whitelist = timer, profile_tasks
# 控制台输出详细度（可通过 -v 覆盖）
# 默认不设置，由命令行控制
[ssh_connection]
# 启用 SSH 复用，减少连接开销
pipelining = True
# SSH 调试级别（0-3），3 为最详细
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o LogLevel=ERROR
关键原则：
- 先看日志，再跑 -vvvv：日志文件记录了所有历史执行，适合回溯；-vvvv 适合实时跟踪单次执行。
- --check 是安全阀，不是万能药：始终在 staging 环境验证 check 模式的行为是否与预期一致。
- 日志轮转不可省略：未配置 logrotate 的日志文件可能在数周内耗尽磁盘空间。