调试失败的 Shell 和 Command 模块实用指南

当没有专用模块可用时，Ansible 的 command 和 shell 模块非常有用，但调试起来可能比较棘手。除非您自行捕获命令输出，否则失败的任务可能仅显示返回码。

本指南将向您展示如何通过检查 rc、stdout 和 stderr，然后使用 failed_when 和 changed_when 让 Ansible 报告真实结果，从而调试失败的 shell 和 command 模块。

Command 与 Shell：理解差异

在深入调试之前，理解这两个模块之间的根本区别至关重要，因为它们的执行环境会影响失败模式。

`ansible.builtin.command`

此模块直接执行命令，绕过标准 shell 环境。这使其更安全、更可预测，因为它避免了变量插值、通配符、管道 (|) 和重定向 (>) 等 shell 功能。

最佳实践： 当任务简单且不需要 shell 功能时，使用 command。

`ansible.builtin.shell`

此模块通过远程主机的标准 shell（/bin/sh 或等效）执行命令。这对于复杂操作、环境变量或使用标准 shell 语法（例如 cd /tmp && ls -l）是必需的。

警告： 由于 shell 依赖于环境，因此更容易出现与 PATH 配置、隐藏环境变量或复杂引号相关的不可预测故障。

Ansible 命令失败的剖析

默认情况下，Ansible 根据进程的返回码 (RC) 确定 command 或 shell 模块任务是成功还是失败。

返回码 (RC)	解释
`rc = 0`	成功（任务继续）
`rc != 0`	失败（任务立即停止，主机标记为失败）

但是，这种简单的检查通常无法捕捉真实世界脚本的细微差别。命令可能返回 RC 为 0，但仍然产生不需要的结果（逻辑失败），或者命令可能返回预期的非零 RC（例如，如果未找到匹配项，grep 返回 1）。

为了处理这些细微差别，我们必须捕获输出并有条件地控制失败状态。

步骤 1：使用 `register` 捕获命令输出

有效调试的第一步是使用 register 关键字将所有可用的输出流捕获到 Ansible 变量中。这允许检查返回码、标准输出和标准错误。

为了防止在初始测试期间因非零返回码而立即停止剧本，通常暂时使用 ignore_errors: yes 很有用。

- name: 执行可能不可靠的命令并捕获结果
  ansible.builtin.shell: | 
    /usr/local/bin/check_config.sh 2>&1 || exit 1
  register: cmd_output
  ignore_errors: yes  # 暂时允许 RC != 0 继续执行

注册后，cmd_output 变量将包含几个有用的键，最值得注意的是：

cmd_output.rc：整数返回码。
cmd_output.stdout：标准输出流。
cmd_output.stderr：标准错误流。
cmd_output.failed：布尔值，指示 Ansible 当前是否认为任务失败。

步骤 2：使用 `debug` 检查捕获的数据

在失败的任务之后立即使用 debug 模块来检查注册变量的内容。这有助于区分真正的技术故障（例如，找不到命令）和逻辑故障（例如，脚本运行但报告了内部错误）。

- name: 显示完整的捕获输出以进行调试
  ansible.builtin.debug:
    var: cmd_output
    # 使用 'when' 仅在任务失败时显示，以清理输出
  when: cmd_output.failed is defined and cmd_output.failed

- name: 突出显示 stderr 内容
  ansible.builtin.debug:
    msg: "捕获的 STDERR：{{ cmd_output.stderr }}"
  when: cmd_output.stderr | length > 0

通过检查完整输出，您可以精确定位指示真正失败的特定错误消息或模式。

步骤 3：使用 `failed_when` 覆盖默认失败行为

failed_when 条件语句是调试和管理复杂 shell 模块结果的最强大工具。它允许您使用 Jinja2 表达式定义自定义逻辑，以确定是否应将任务标记为失败，而不管默认返回码如何。

场景 A：处理预期的非零返回码

某些实用程序会为预期结果返回非零码。例如，grep 在未找到匹配项时返回 1，在实际错误时返回大于 1。

- name: 检查设置是否存在，但不存在时不要失败
  ansible.builtin.command: grep -q '^feature_enabled=true' /etc/myapp.conf
  register: grep_result
  failed_when: grep_result.rc > 1
  changed_when: false

场景 B：逻辑错误时失败（RC=0，但输出错误）

如果脚本即使在发生内部错误时也始终返回 RC=0，但将特定的错误字符串打印到 stdout 或 stderr，请使用 failed_when 捕获该字符串。

- name: 验证数据库连接脚本
  ansible.builtin.shell: /opt/scripts/db_connect_test.sh
  register: db_result
  # 检查 stdout 和 stderr 中常见的错误短语
  failed_when: >
    ('Connection refused' in db_result.stderr) or
    ('Authentication failure' in db_result.stdout)

场景 C：结合 RC 和输出检查

对于健壮的检查，使用逻辑运算符（and、or、括号）结合返回码和内容检查。

- name: 检查部署日志
  ansible.builtin.shell: tail -n 50 /var/log/deployment.log
  register: log_check
  # 如果 RC 非零，或者成功的输出包含单词 'FATAL'，则失败
  failed_when: log_check.rc != 0 or 'FATAL' in log_check.stdout

提示： 使用 failed_when 时，通常应移除 ignore_errors: yes，除非您明确希望记录失败但让剧本继续执行。

可靠命令执行的最佳实践

为了最大限度地减少复杂调试的需要，在编写使用 command 或 shell 的任务时，请遵循以下标准：

1. 始终使用绝对路径

不要依赖远程用户的 $PATH。始终指定可执行文件的完整路径（例如 /usr/bin/python，而不仅仅是 python）。这可以避免因环境不一致或执行路径的细微差异而导致的失败。

2. 利用条件语句而非 Shell 逻辑

不要在 shell 模块内部使用复杂的 shell 逻辑（如 || 或 &&），而应利用 Ansible 的原生条件语句（when:、failed_when:、changed_when:）和 register 关键字。这使剧本逻辑透明且更易于调试。

3. 显式控制变更检测 (`changed_when`)

默认情况下，如果返回码为 0，command 和 shell 会将任务标记为 changed。如果您的脚本运行但未对系统进行任何更改（例如，简单的状态检查），则应使用 changed_when 手动定义任务何时导致更改。

- name: 检查磁盘空间（不应导致 'changed'）
  ansible.builtin.command: df -h /data
  changed_when: false

4. 尽可能使用状态模块

如果您发现自己使用 shell 来检查文件是否存在、启动/停止服务或安装软件包，请停下来寻找专用的 Ansible 模块（例如 ansible.builtin.stat、ansible.builtin.service、ansible.builtin.package）。专用模块在内部处理幂等性和错误检查，从而显著减少调试工作。

最终要点

当 shell 或 command 任务失败时，首先捕获结果，检查 rc、stdout 和 stderr，然后在 failed_when 中编码真正的成功条件。一旦任务稳定，添加 changed_when，以便状态检查不会在每次剧本运行时显示虚假的更改。