服务器上的Ansible任务执行失败,如何从报错信息排查权限与模块问题?

发布人:A5数据发布时间:2026-10-24 11:21阅读量:79

Ansible任务失败时,终端里最醒目的 fatal 或 MODULE FAILURE 往往只是结果包装,并不等于根因。排查权限与模块问题,首先要判断失败发生在控制节点、SSH连接、提权、远程临时目录,还是模块已经启动后的业务执行阶段。

运维工程师通常会先保留原始输出,再按照“控制节点和目标主机是否可达 → 登录用户是谁 → 是否成功提权 → 远程文件能否创建和执行 → 模块参数与运行环境是否匹配”的顺序缩小范围。这样可以避免一开始就修改权限、关闭安全策略或切换到 root,降低对线上环境的影响。

先确认失败属于哪一层配图

先确认失败属于哪一层

开始操作前,保留一次完整的失败记录。不要只复制最后一行错误,因为 Ansible 的有效线索通常出现在 msg、rc、module_stderr、module_stdout、invocation 和任务名称中。

下面是一段用于说明字段含义的模拟输出,不代表已在读者环境中执行:

TASK [install web package] ********************************************
fatal: [web-01]: FAILED! => {
    "changed": false,
    "msg": "MODULE FAILURE\nSee stdout/stderr for the exact error",
    "rc": 1,
    "module_stderr": "sudo: a password is required\n",
    "module_stdout": "",
    "invocation": {
        "module_args": {
            "name": "nginx",
            "state": "present"
        }
    }
}

重点字段可以这样理解:

字段或现象排查重点不能直接得出的结论
UNREACHABLESSH地址、端口、认证、主机名解析、网络路径不能说明模块有问题
FAILED模块已被调用,但任务返回失败不一定是权限问题
rc远程命令或模块的退出码rc=1 不能单独证明是权限不足
msgAnsible对失败的概括需要结合标准错误继续判断
module_stderrsudo、Python、动态库、执行权限等错误可能包含真正的根因
module_stdout模块或被调用程序的标准输出空内容不表示模块没有执行
invocation.module_args实际传入的参数和模块含密码、令牌的任务可能需要脱敏
changed任务是否报告了变更changed=false 不等于所有检查都成功

如果任务使用了 no_log: true,敏感参数会被隐藏,错误详情也可能不完整。不要为了方便在生产环境直接删除 no_log。更稳妥的做法是编写一个不包含密码和令牌的诊断任务,单独确认用户、路径和依赖状态。

第一层:保留控制节点上的执行证据

使用单台主机和较高日志级别重现

确认问题前,先查看 Ansible 版本、实际使用的配置和清单变量。以下命令在控制节点执行,web-01 和 inventory.ini 需要替换为实际对象:

ansible --version
ansible-config dump --only-changed
ansible-inventory -i inventory.ini --host web-01

这些命令是只读检查。它们可以发现以下常见偏差:

  • 运行命令的 Ansible 版本与预期不同;
  • 实际加载的 ansible.cfg 不是项目目录中的那份;
  • 清单中的远程用户、端口、提权方式或 Python 解释器被主机变量覆盖;
  • 主机名解析到了错误地址;
  • 某个组变量覆盖了单台主机的设置。

为了减少并发输出干扰,可以先只针对一台主机重跑:

umask 077
ansible-playbook -i inventory.ini site.yml \
  --limit web-01 \
  --forks 1 \
  -vvv 2>&1 | tee ansible-web-01.log

-vvv 通常足以观察连接、远程临时目录和模块执行过程。-vvvv 会输出更多连接细节,可能包含主机名、路径甚至认证相关信息,只有在确有需要且日志存储受控时使用。tee 生成的日志应限制访问权限,排查完成后按组织的日志保留规范处理。

如果控制节点使用了任务平台或作业调度系统,除了平台页面中的作业输出,还要查看执行环境或运行容器日志。不能默认认为日志一定写在控制节点的 /var/log/ansible/ 下。

配置控制节点日志时避免泄露参数

需要长期保留执行记录时,可以在项目目录下使用独立的 ansible.cfg,避免直接修改系统级配置:

[defaults]
log_path = ./logs/ansible.log
display_args_to_stdout = False

先创建受限目录,再运行任务:

umask 077
mkdir -p ./logs

log_path 只负责记录 Ansible 输出,不会自动为所有内容添加精确时间戳。若需要关联时间线,应结合任务平台时间、终端记录和目标主机日志。修改配置前应保存原配置;验证结束后删除项目级临时配置,或者将其恢复到原版本。

第二层:先排除连接和目标主机选错

区分 UNREACHABLE 与模块失败

先执行 Ansible 的 ping 模块:

ansible -i inventory.ini web-01 \
  -m ansible.builtin.ping \
  -vvv

这里的 ping 检查的是 Ansible 远程执行链路,不是 ICMP 连通性。结果通常有三种含义:

  • 返回 pong:SSH登录、远程解释器和基础模块链路基本可用;
  • 返回 UNREACHABLE:优先查地址、端口、用户名、认证方式和 SSH 服务;
  • 返回 FAILED 且包含 Python 或模块错误:SSH可能已经成功,继续检查远程运行环境。

也可以用不依赖 Python 的 raw 模块查看最基础的远端信息:

ansible -i inventory.ini web-01 \
  -m ansible.builtin.raw \
  -a 'id; printf "host="; hostname; printf "time="; date -Ins'

raw 直接通过远程Shell执行命令,适合确认 Python 尚未安装或解释器路径不确定的场景。但它绕过了普通模块的参数校验,不应作为长期任务实现方式。

查看目标主机上的认证日志

确认失败发生的时间窗口后,在目标主机查看 SSH 认证日志。sshd.service、ssh.service 以及日志文件路径会随发行版不同而变化,先用实际系统中存在的服务名和文件。

sudo journalctl -u sshd.service \
  --since "2025-01-01 10:10:00" \
  --until "2025-01-01 10:15:00" \
  -o short-iso-precise

如果没有 sshd.service,可以检查:

sudo journalctl -u ssh.service \
  --since "2025-01-01 10:10:00" \
  --until "2025-01-01 10:15:00" \
  -o short-iso-precise

传统日志文件中,基于 RHEL 系的系统常见 /var/log/secure,基于 Debian 系的系统常见 /var/log/auth.log。应以目标系统实际配置为准:

sudo grep -E 'sshd|sudo' /var/log/secure
sudo grep -E 'sshd|sudo' /var/log/auth.log

文件不存在时不要反复执行同一命令,应转回 journalctl 或查看日志服务配置。重点关注:

  • 日志时间是否落在任务失败窗口;
  • 认证用户名是否为清单中配置的用户;
  • 来源IP是否为控制节点;
  • 是密码错误、密钥拒绝、账户锁定,还是公钥认证成功后又被策略拒绝;
  • 是否出现 AllowUsers、AllowGroups、PAM 或账户过期相关提示。

如果多台主机同时出现 UNREACHABLE,更应先核对控制节点的清单、DNS、网络策略和统一凭据,而不是逐台修改目标主机权限。

第三层:确认远程用户和提权状态

SSH登录成功后,Ansible任务可能仍然因为远程用户权限不足而失败。先分别查看不提权和提权后的身份:

ansible -i inventory.ini web-01 \
  -m ansible.builtin.command \
  -a 'id'

ansible -i inventory.ini web-01 \
  --become \
  -m ansible.builtin.command \
  -a 'id'

预期结果是第一条显示清单中的登录用户,第二条显示目标任务需要的特权用户。若第二条失败,重点看输出中的:

  • sudo: a password is required:当前执行方式没有提供可用的提权凭据;
  • is not in the sudoers file:用户不在授权范围内;
  • a terminal is required:sudo策略要求终端;
  • not allowed to execute:授权规则限制了命令或目标用户;
  • su: Authentication failure:实际使用的提权方法可能不是 sudo,或账户认证失败。

如果环境允许非交互验证,可以用 sudo -n 检查是否必须输入密码:

ansible -i inventory.ini web-01 \
  -m ansible.builtin.command \
  -a 'sudo -n -u root id'

这条命令只检查当前登录用户是否能在无交互条件下切换到 root。失败不一定说明管理员人工执行 sudo 也失败,因为人工终端可能具备密码输入、TTY或不同的环境变量。

同时确认任务使用的提权方式:

ansible-config dump --only-changed | grep -E 'BECOME|REMOTE_USER|REMOTE_TMP'
ansible-inventory -i inventory.ini --host web-01

如果是 doas、su 或其他提权插件,不能套用 sudo 的判断方式。应从任务的 become_method、主机变量和相应认证日志入手。

关联 sudo 和审计日志

在目标主机上,可以按时间窗口查看 sudo 记录:

sudo journalctl _COMM=sudo \
  --since "2025-01-01 10:10:00" \
  --until "2025-01-01 10:15:00" \
  -o short-iso-precise

启用了 auditd 和 SELinux 审计的系统,还可以搜索访问拒绝:

sudo ausearch -m avc,user_avc \
  -ts 10:10:00 \
  -te 10:15:00

如果结果中同时出现控制节点连接成功、sudo被拒绝和任务失败,时间线就能把问题从“模块报错”收敛为“提权策略不满足”。

不要为了让任务通过而直接给用户增加全量 root 权限。若确实要调整 sudoers,应先备份相关文件,并使用语法检查:

sudo visudo -c
sudo visudo -cf /etc/sudoers.d/ansible-deploy

修改必须限定到目标用户、目标主机和必要命令。保留一个已登录的管理员会话,确认新规则生效后再关闭其他会话。若规则修改导致异常,应使用备份恢复,并再次执行 visudo -c,不要直接覆盖整个 /etc/sudoers。

第四层:检查远程临时目录和文件系统权限

Ansible通常需要在目标主机上创建临时目录、上传模块文件并执行。登录用户能够进入系统,并不代表能够写入远程临时目录或访问任务目标路径。

检查目录链路、所有权和ACL

对报错中出现的路径,先查看每一级目录:

ansible -i inventory.ini web-01 \
  -m ansible.builtin.command \
  -a 'namei -l /opt/example/conf/app.conf'

再查看目标文件和父目录:

ansible -i inventory.ini web-01 \
  -m ansible.builtin.command \
  -a 'stat -c "%A %a %U:%G %n" /opt /opt/example /opt/example/conf /opt/example/conf/app.conf'

namei -l 可以发现某一级父目录缺少执行权限。访问文件不仅需要文件本身的读写权限,路径上的每一级目录通常还需要相应的搜索权限。

存在ACL时,普通的 ls -l 可能无法说明完整权限:

ansible -i inventory.ini web-01 \
  -m ansible.builtin.command \
  -a 'getfacl -p /opt/example/conf/app.conf'

如果目标路径位于挂载点,还要检查容量、inode和挂载参数:

ansible -i inventory.ini web-01 \
  -m ansible.builtin.raw \
  -a 'df -h /tmp; df -i /tmp; findmnt -no TARGET,OPTIONS /tmp 2>/dev/null || true'

典型判断如下:

  • No space left on device:可能是磁盘空间耗尽,也可能是 inode耗尽;
  • Permission denied:检查所有权、ACL、SELinux和挂载参数;
  • Read-only file system:文件系统可能被只读挂载或发生错误;
  • 挂载参数包含 noexec:文件可以写入,但临时模块可能无法执行。

检查 Ansible 的远程临时目录

先查看实际配置和远程用户的家目录:

ansible-config dump --only-changed | grep -E 'REMOTE_TMP|DEFAULT_REMOTE_USER'

ansible -i inventory.ini web-01 \
  -m ansible.builtin.raw \
  -a 'id; printf "home="; printf "%s\n" "$HOME"; ls -ld "$HOME" "$HOME/.ansible" "$HOME/.ansible/tmp" /tmp 2>&1'

如果目录不存在,先不要直接执行递归删除或批量修改权限。要确认:

  1. 该路径是否确实属于当前任务;
  2. 是否有其他Ansible作业正在运行;
  3. 目录是否由其他服务或安全策略管理;
  4. 当前用户是否拥有父目录的搜索和写权限;
  5. 远程临时目录所在文件系统是否允许执行。

在确认用户、路径和影响范围后,才考虑创建专用目录。例如目标账户明确为 deploy,且 /home/deploy 是其真实家目录时,可以采用受限权限创建:

sudo install -d -o deploy -g deploy -m 700 /home/deploy/.ansible/tmp

这属于权限变更,不能在未知账户或未知路径上直接执行。执行前应保存原有ACL和属性,示例:

sudo getfacl -p /home/deploy/.ansible /home/deploy/.ansible/tmp \
  > /root/ansible-tmp-acl.backup

如果修改结果不符合预期,且系统支持对应ACL恢复方式,可按备份恢复:

sudo setfacl --restore=/root/ansible-tmp-acl.backup

恢复前要确认备份文件对应的是同一台主机和同一路径。不要使用 chmod -R 777 处理临时目录,也不要在不了解业务的情况下清空 /tmp。若必须清理,只能针对已确认不再使用、属于本次任务的精确路径,并避开正在运行的作业。

第五层:判断模块本身是否能加载和运行

当 SSH、用户和提权均正常后,再进入模块层排查。MODULE FAILURE 常见于以下几类情况。

模块或集合无法解析

例如:

ERROR! couldn't resolve module/action 'community.general.some_module'

或者:

ERROR! couldn't resolve module/action 'custom_module'

这表示控制节点无法解析模块名称,优先检查集合是否安装、模块名称是否拼写正确,以及任务运行时使用的 Ansible环境是否与手工查询时相同:

ansible-galaxy collection list
ansible-doc ansible.builtin.copy
ansible-doc community.general.some_module

建议在任务中使用完整模块名,例如:

- name: Ensure application configuration exists
  ansible.builtin.copy:
    src: app.conf
    dest: /opt/example/conf/app.conf
    owner: deploy
    group: deploy
    mode: "0640"

如果模块来自外部集合,应在项目依赖文件中固定兼容范围,并在同一个执行环境中安装和验证,而不是临时在某个用户目录下安装后期待所有作业都能找到。

远程Python解释器不存在或路径错误

常见错误包括:

/usr/bin/python3: No such file or directory
/bin/sh: python: command not found

先使用 raw 查询实际路径:

ansible -i inventory.ini web-01 \
  -m ansible.builtin.raw \
  -a 'command -v python3 || true; command -v python || true; python3 --version 2>&1 || true'

如果目标主机只有 /usr/local/bin/python3,应在清单或主机变量中显式设置经过确认的解释器路径,而不是凭经验填写某个发行版路径:

[web]
web-01 ansible_host=192.0.2.10 ansible_python_interpreter=/usr/local/bin/python3

修改清单前应备份当前版本,并先用单台主机验证。解释器路径变化后,使用 ansible.builtin.ping 和一个无副作用的 command 任务确认模块能正常启动。

参数不兼容或类型错误

以下错误通常是模块参数问题,而不是Linux文件权限问题:

Unsupported parameters for (ansible.builtin.copy) module
missing required arguments
argument 'mode' is of type <class 'int'> and we were expecting a string

处理顺序是:

  1. 用 ansible-doc 模块完整名称 查看当前执行环境的参数;
  2. 对照当前 Ansible Core 和集合版本;
  3. 检查变量最终展开后的值和类型;
  4. 先用固定、非敏感的测试值验证;
  5. 再恢复变量化配置。

例如文件模式建议写成字符串:

mode: "0640"

这样可以避免YAML把带前导零的值按其他类型解析。涉及密码、令牌和私钥时,不要把变量值直接放入 -vvv 输出或诊断日志。

模块已经启动,但被目标程序拒绝

如果 module_stderr 显示模块已运行,而 module_stdout 或 msg 中出现应用程序错误,应继续查看目标程序自身日志。例如包管理器、服务管理器或应用程序可能拒绝了参数、端口、配置格式或当前状态。

还要区分 command 与 shell 的行为:

  • ansible.builtin.command 不经过Shell解析,不支持管道、重定向和通配符展开;
  • ansible.builtin.shell 会经过Shell,功能更灵活,但也带来变量展开和注入风险;
  • rc=126 常表示命令无法执行,rc=127 常见于命令不存在,但最终仍应结合标准错误;
  • creates、removes 等条件可能让任务被跳过,不能只根据 changed 判断程序是否运行。

对于自定义模块或集合,还要检查模块文件是否能被远程用户读取,依赖的动态库和命令是否存在,以及安全策略是否阻止了执行。

按日志结果选择下一步

可以把一次失败归入下面的分支,避免在错误层级上反复尝试:

观察结果优先查看下一步
UNREACHABLE,没有模块输出SSH日志、地址、端口、认证、DNS先恢复连接,不分析任务参数
SSH成功,--become失败sudo日志、提权方法、TTY和密码策略修正有限的提权规则或凭据
Permission denied 出现在临时目录remote_tmp、父目录、ACL、挂载参数修复专用目录或调整受控配置
MODULE FAILURE 且Python不存在解释器路径、目标主机Python安装或指定已确认的解释器
couldn't resolve module/action控制节点集合和模块名称使用正确FQCN并统一执行环境
模块参数校验失败ansible-doc、变量类型、版本修正参数,不改变系统权限
模块返回应用错误服务日志、包管理器日志、配置文件按目标程序的错误处理
只有一台主机失败该主机的权限、磁盘、策略和版本对比正常主机差异
所有主机同时失败控制节点、集合、清单和公共凭据优先检查共享配置

时间线关联时,至少记录控制节点任务开始和结束时间、目标主机的 SSH认证时间、sudo执行时间、内核或审计拒绝时间,以及模块返回时间。示例时间线如下,日志内容为模拟数据:

2025-01-01T10:12:08.431+08:00 controller  TASK [install package]
2025-01-01T10:12:08.702+08:00 web-01      sshd[2184]: Accepted publickey for deploy
2025-01-01T10:12:08.735+08:00 web-01      sudo[2191]: deploy : user NOT in sudoers
2025-01-01T10:12:08.911+08:00 controller  web-01 | FAILED! => rc=1

这组信息说明 SSH已成功,失败发生在提权阶段,不应继续检查模块集合。若顺序变成“模块上传后出现 SELinux AVC,再返回 Permission denied”,则排查重点应转向安全上下文和审计策略。

注意控制节点和目标主机可能使用不同的时区。必要时分别执行:

date -Ins -u
timedatectl status

日志查询使用 -o short-iso-precise 或统一使用UTC,可以减少秒级甚至分钟级错位。系统时间异常也可能导致证书、审计和日志关联出现误判。

修复应从局部变更开始

定位根因后,优先采用影响范围最小的修复方式:

  • 清单写错:修正单台主机的地址、用户或解释器变量;
  • 远程目录权限错误:只修复专用目录的所有者、模式或ACL;
  • sudo规则缺失:只增加任务所需的最小授权,并通过 visudo 校验;
  • 集合版本不一致:固定项目依赖并在同一执行环境验证;
  • SELinux拒绝:依据审计记录修复正确的文件上下文或策略,不直接关闭SELinux;
  • noexec导致模块无法执行:与系统安全策略负责人确认可用的临时目录或挂载方案,不要未经审批直接重新挂载;
  • 磁盘或inode耗尽:先确认占用来源和清理范围,再执行有记录的清理操作。

涉及配置、权限或安全策略的修改,都应保留变更前备份、记录操作者和时间,并准备可逆操作。不要用“放开全部权限”“关闭安全策略”“改成root运行”作为第一选择。它们可能让一次任务通过,却掩盖真实配置问题,并扩大后续风险。

修复后的复测与持续观察

修复后不要直接在整个生产清单上重跑。先执行语法检查和目标主机范围检查:

ansible-playbook -i inventory.ini site.yml --syntax-check

ansible-playbook -i inventory.ini site.yml \
  --limit web-01 \
  --forks 1 \
  -vvv

--syntax-check 主要验证控制节点能否解析Playbook,不能替代目标主机上的权限和模块测试。--check 对部分模块有帮助,但并非所有模块都能完全模拟真实执行,因此不能把检查模式成功视为实际变更一定成功。

验证内容至少包括:

  1. 控制节点日志中不再出现 UNREACHABLE 或模块加载错误;
  2. 目标主机上的登录用户和提权用户符合预期;
  3. 远程临时目录可以创建、读取和执行必要文件;
  4. 任务返回 rc=0,标准错误中没有被忽略的警告;
  5. 目标文件的所有者、权限、内容或服务状态符合设计;
  6. 第二次运行结果符合幂等性预期,通常不应重复产生无意义变更。

可以针对权限和服务状态做只读验证:

ansible -i inventory.ini web-01 \
  -m ansible.builtin.command \
  -a 'id'

ansible -i inventory.ini web-01 \
  -m ansible.builtin.command \
  -a 'stat -c "%A %U:%G %n" /opt/example/conf/app.conf'

如果任务涉及服务,还应查看对应服务状态和修复后的日志窗口。连续观察数次任务运行,确认问题没有在并发执行、定时作业或另一台主机上重复出现。最终保留一份“错误输出—时间线—根因—变更—复测结果”的记录,下一次遇到相同的权限或模块故障时,可以直接从正确的日志层级开始,而不是重新尝试高风险修改。

A5数据提供中国香港、美国、日本等地区的物理服务器租用,涵盖不同CPU、内存及SSD、NVMe存储配置,并提供相应的线路与带宽选择。对于使用Ansible管理多台主机的团队,这些服务器资源可承载网站、接口、数据库和自动化作业,支持按业务访问地区与计算、存储需求组织部署。

本文由A5数据原创发布,转载请注明出处:https://www.a5idc.com/helpcontent/5474.html