3. Ansible 返回码与状态解析

在 Ansible 执行过程中，每个任务都会返回一个明确的状态码。这些状态码是判断任务执行结果、触发后续事件以及进行故障分派的唯一依据。理解 failed、changed、unreachable、skipped 等核心状态码的含义，是构建自动化事件分派体系的基础。

3.1 核心状态码一览

Ansible 任务执行后，Playbook 回调系统会为每个任务生成一个状态对象。下表列出了最常用的五种状态码及其业务含义：

3.2 状态码的优先级与事件分派关系

当多个状态码同时出现时（例如一个 Playbook 包含多个任务），事件分派系统需要根据状态码的严重程度决定处理顺序。下图展示了状态码的优先级层级以及对应的分派路径：

3.3 状态码的详细行为与判断逻辑

3.3.1 failed 状态

failed 是事件分派中最关键的状态。它表示任务执行过程中遇到了不可恢复的错误。常见的触发原因包括：

• 命令返回非零退出码：shell/command 模块默认检查退出码，非零即视为失败。
• 模块内部异常：如文件模块尝试写入只读目录、yum 模块找不到指定的包。
• 断言失败：使用 assert 模块时，条件表达式结果为 false。
• 自定义失败条件：通过 failed_when 关键字手动定义失败条件。

# 示例：使用 failed_when 自定义失败条件
- name: 检查日志文件中是否存在错误关键字
  ansible.builtin.shell: grep "ERROR" /var/log/app.log
  register: log_check
  failed_when: log_check.rc == 0  # 如果找到错误关键字，视为失败
  ignore_errors: yes

3.3.2 changed 状态

changed 表示任务对目标系统产生了实际影响。这是幂等性检查的核心指标。在事件分派中，changed 通常用于触发变更通知或配置漂移告警。

• 幂等模块：如 file、copy、template、service 等，仅在真正修改时返回 changed。
• 非幂等模块：如 shell、command，默认始终返回 changed，除非使用 creates 或 removes 参数。
• 手动控制：通过 changed_when 关键字可以覆盖默认的 changed 判断逻辑。

# 示例：使用 changed_when 精确控制变更状态
- name: 重启 Nginx 服务
  ansible.builtin.service:
    name: nginx
    state: restarted
  register: nginx_restart
  changed_when: nginx_restart.status.ActiveState == "active"

3.3.3 unreachable 状态

unreachable 是连接层错误，与任务逻辑无关。一旦出现此状态，Ansible 会立即停止该主机的所有后续任务执行。常见原因包括：

• SSH 连接超时或拒绝连接
• 主机名 DNS 解析失败
• SSH 密钥认证失败
• Python 解释器在目标主机上不可用

3.3.4 skipped 状态

skipped 表示任务被条件判断跳过，并非错误。在事件分派中，skipped 通常不触发告警，但可以用于审计和合规性检查。

• when 条件：最常见的跳过原因。
• 标签过滤：使用 --tags 或 --skip-tags 运行 Playbook 时。
• 角色依赖：当角色被标记为 when: false 时。

3.4 状态码在事件分派中的实际应用

在自动化事件分派系统中，状态码是触发后续动作的原始信号。下图展示了从任务执行到事件分派的完整数据流：

3.5 状态码的捕获与调试

在编写事件分派规则时，需要准确捕获状态码。以下是在 Playbook 中获取状态码的常用方法：

# 方法1：使用 register 注册任务结果
- name: 安装 Nginx
  ansible.builtin.yum:
    name: nginx
    state: present
  register: nginx_install

# 方法2：在后续任务中检查状态码
- name: 根据状态码触发事件
  ansible.builtin.debug:
    msg: "安装状态: {{ nginx_install.changed | ternary('CHANGED', 'OK') }}"
  when: nginx_install is succeeded

# 方法3：使用全局变量获取主机状态
- name: 显示所有主机的状态汇总
  ansible.builtin.debug:
    msg: "不可达主机: {{ ansible_play_hosts_all | difference(ansible_play_hosts) }}"

3.6 常见状态码误判场景

在实际运维中，以下场景容易导致状态码误判，需要在事件分派规则中特别处理：