【Linux&Ansible】学习笔记合集三

排查 Playbook 的第一步，优先从ansible-navigator run命令的输出入手，这份输出会清晰展示 Play 名称、每个 Task 的执行结果，以及最终的 PLAY RECAP 汇总 ------ 包括每台主机的任务成功、变更、失败、不可达等状态，能快速判断是单台主机问题还是全局任务问题。

如果基础输出不足以定位问题，可通过-v系列选项开启分级调试，不同级别能获取不同维度的信息，满足不同排查需求：

-V：显示基础输出数据；
-VV：同时展示输出和输入数据；
-VVV：包含与受管主机的连接细节，适合排查连接相关的任务问题；
-VVVV：展示远程主机执行的脚本及执行用户，是深度调试的最佳选择。

2. 变量核查：用 Debug 模块掌握运行时真实值

Playbook 中变量配置错误是常见问题，ansible.builtin.debug模块能精准展示变量在 Playbook 执行时的真实值，帮我们验证变量是否按预期赋值。

复制代码

# 方式1：结合msg自定义提示，展示变量值
- name: 显示系统空闲内存
  ansible.builtin.debug:
    msg: "本系统的空闲内存为 {{ ansible_facts['memfree_mb'] }} MB"

# 方式2：直接展示变量，verbosity指定调试级别
- name: 显示output变量值
  ansible.builtin.debug:
    var: output
    verbosity: 2

3. 语法与规范检查

很多 Playbook 执行失败，根源是简单的语法错误或编写不规范，我们可以通过专用命令和工具，在执行前提前发现并修复这类问题。

语法检查 ：使用ansible-navigator run -m stdout playbook.yml --syntax-check命令，快速验证 Playbook 的 YAML 语法是否合规，清单、模块调用是否存在基础错误；
规范检查 ：借助ansible-lint工具，通过预定义规则检查 Playbook 的编写规范，比如是否使用模块的全限定名称（FQCN）、是否存在多余空格 / 空行、是否遵循 Ansible 最佳实践等。

ansible-lint会清晰标注问题位置和原因，比如未使用ansible.builtin.package而直接写package、行尾有多余空格、空行过多等。对于非致命的规范问题，还能通过配置文件.config/ansible-lint.yml，将其加入warn_list转为警告，或加入skip_list直接跳过检查。

4. 工件与日志溯源

如果 Playbook 通过了语法和规范检查，但执行仍失败，就需要借助Playbook artifact工件文件和日志文件进行深度溯源。

ansible-navigator run执行 Playbook 时，会默认生成 JSON 格式的 artifact 文件，命名规则为playbook名称-artifact-时间戳.json，该文件记录了 Playbook 运行的全量信息，包括每个任务的执行细节、主机返回结果、失败原因等。

我们可以通过ansible-navigator replay命令查看 artifact 文件内容：

加-m stdout：直接在终端打印输出，快速查看；
不加选项：进入交互模式，可按 Play、Task、主机筛选信息，精准定位失败任务的具体原因，比如安装软件包时仓库中无对应包、权限不足等。

如果需要长期留存日志，还能通过 Ansible 配置文件ansible.cfg的log_path参数，或$ANSIBLE_LOG_PATH环境变量，将 Playbook 运行日志写入文本文件，方便后续检索分析。若担心敏感信息泄露，也可在ansible-navigator.yml中关闭 artifact 文件生成：

复制代码

ansible-navigator:
  playbook-artifact:
    enable: false

二、受管主机故障排除

当 Playbook 本身无问题，但部分或全部受管主机执行失败时，问题多集中在主机连接 和主机侧执行环境，核心排查方向包括连接认证、地址解析、特权升级、执行依赖等。

1. 连接问题：最常见的主机侧故障根源

受管主机连接失败是 Ansible 运维中最常遇到的问题，主要分为身份验证 、地址解析 、特权升级三类，每种问题都有明确的排查和解决方法。

（1）身份验证问题

表现为执行时提示Permission denied，核心原因是 SSH 密钥未配置、远程用户错误、密码错误等。

检查ansible.cfg或 Play 中配置的remote_user是否正确，是否为受管主机上的有效用户；
验证控制节点的 SSH 公钥，是否已添加到受管主机对应用户的~/.ssh/authorized_keys文件中；
若使用密码认证，确认密码正确且受管主机开启了密码登录。

（2）名称或地址解析问题

表现为无法解析主机名，核心原因是清单中的主机名与实际可访问的地址不一致。

可通过 **ansible_host变量 ** 解决，该变量能覆盖清单名称，指定 Ansible 连接受管主机时实际使用的 IP 或域名，可在清单文件中直接配置：

复制代码

# 清单中配置：访问web4.phx.example.com时，实际连接192.0.2.4
web4.phx.example.com ansible_host=192.0.2.4

也可在主机的host_vars文件中配置，更适合大规模主机的管理。

（3）特权升级问题

表现为提示Missing sudo password或特权操作失败，核心原因是sudo配置错误、无免密 sudo 权限、become相关参数配置不当。

检查 Play 中的become: yes是否开启，become_user是否配置为需要的特权用户（默认 root）；
验证受管主机上的远程用户，是否拥有 sudo 权限，是否配置了免密 sudo（可通过visudo编辑 sudo 配置）；
若需要 sudo 密码，执行 Playbook 时需正确提供，确保密码无误。

2. 执行依赖问题：确保主机有 Ansible 运行的基础环境

Ansible 模块运行依赖受管主机的 Python 解释器，若主机上未安装 Python，或 Ansible 无法找到合适的 Python 解释器，会导致任务执行失败，提示/usr/bin/python: not found。

排查时需确认受管主机已安装 Python3（推荐），并确保 Ansible 能检测到解释器；若主机的 Python 安装路径特殊，可通过ansible_python_interpreter变量指定具体路径。

3. 测试工具：提前验证主机状态，规避执行失败

在正式执行 Playbook 前，可通过 Ansible 的检查模式 和专用模块，提前测试受管主机的状态，验证任务是否能正常执行，做到防患于未然。

（1）检查模式：无改动测试 Playbook 执行效果

使用ansible-navigator run --check命令开启检查模式，Ansible 会正常连接受管主机、执行任务检查，但不会对主机做出任何实际更改，适合做 "烟雾测试"。

如果模块支持检查模式，会显示任务执行后将产生的变更；若仅需对部分任务开启检查模式，可在任务中配置check_mode: yes/no：

复制代码

# 强制该任务以检查模式执行，即使全局未开--check
- name: 检查系统信息
  ansible.builtin.shell: uname -a
  check_mode: yes

# 强制该任务正常执行，即使全局开了--check
- name: 查看内存使用
  ansible.builtin.shell: free -m
  check_mode: no

（2）专用测试模块：验证主机状态与服务可用性

Ansible 提供了多个专用模块，可快速验证受管主机的状态、服务可用性，常用的有：

ansible.builtin.uri：检查 RESTful API 是否可用，返回内容是否符合预期，适合测试应用接口；
ansible.builtin.stat：收集主机上文件 / 目录的信息，验证文件是否存在、权限是否正确；
ansible.builtin.assert ：自定义条件检查，若条件不满足则任务失败，可替代fail模块，更灵活的做状态校验；
ansible.builtin.script：在受管主机上执行控制节点的脚本，脚本返回非 0 则任务失败，适合自定义主机状态检查。

示例：检查主机上是否存在锁文件，若存在则中止 Playbook 执行

复制代码

- name: 检查/var/run/app.lock是否存在
  ansible.builtin.stat:
    path: /var/run/app.lock
  register: lock_file

- name: 若锁文件存在则失败
  ansible.builtin.assert:
    that:
      - not lock_file['stat']['exists']
    fail_msg: "检测到应用锁文件，应用已在运行，中止执行"

4. 临时命令：快速验证主机连通性与基础状态

Ansible 的临时命令无需编写 Playbook，可直接在终端执行单个任务，适合快速测试受管主机的连通性、基础状态，是故障排除的 "快捷工具"。

临时命令的核心格式为：

复制代码

ansible 主机模式 -m 模块 [-a '模块参数'] [-i 清单文件]

若未指定-m，默认使用ansible.builtin.command模块，常用的临时命令示例：

复制代码

# 测试主机连通性，验证SSH和Python环境
ansible all -m ansible.builtin.ping

# 查看所有主机的磁盘使用情况
ansible all -m ansible.builtin.command -a 'df -h'

# 测试主机特权升级是否正常
ansible demo -m ansible.builtin.ping --become

临时命令仅适用于故障排除和一次性测试，不建议用于正式的自动化流程。

三、Ansible 故障排除核心总结

Ansible 故障排除的核心，是先定位问题维度，再逐层拆解排查：先判断是 Playbook 本身的问题，还是受管主机的问题；再通过对应的工具和方法，从基础到深度逐步溯源。核心要点可总结为以下 5 点：

ansible-navigator run的-v系列选项是基础调试工具，分级获取调试信息，快速定位问题方向；
ansible.builtin.debug模块是变量核查的关键，能验证运行时变量的真实值，解决变量配置问题；
--syntax-check和ansible-lint能提前规避语法和编写规范错误，减少低级故障；
Playbook artifact 工件文件是解决无明显错误执行失败的核心，可通过ansible-navigator replay深度溯源失败原因；
受管主机问题多集中在连接层，重点排查 SSH 认证、地址解析、特权升级，结合检查模式和临时命令可提前验证主机状态。