必须用系统包管理器安装：Ubuntu/Debian执行sudo apt update && sudo apt install ansible，RHEL 8+/Rocky/AlmaLinux 8+执行sudo dnf install epel-release && sudo dnf install ansible-core，CentOS 7执行sudo yum install epel-release && sudo yum install ansible；装完需验证ansible --version及ansible localhost -m ping，并配置SSH免密和用户级inventory。
直接用系统包管理器安装，别碰 pip install ansible
Ansible 必须走系统包管理器安装——这是 2026 年主流发行版（Ubuntu 22.04+、Rocky 9、RHEL 9、AlmaLinux 9）下唯一稳妥路径。pip install ansible 会大概率触发 ImportError: No module named 'yaml' 或 ModuleNotFoundError: No module named 'ansible.errors'，因为 pip 会覆盖系统自带的 ansible-core 依赖链，且无法自动拉取 libyaml、openssh-client 等底层组件。
各发行版命令如下：
- Ubuntu/Debian：
sudo apt update && sudo apt install ansible - RHEL 8+/Rocky/AlmaLinux 8+：
sudo dnf install epel-release && sudo dnf install ansible-core（注意是ansible-core，不是旧版ansible） - CentOS 7（EOL 但仍在用）：
sudo yum install epel-release && sudo yum install ansible
装完立刻验证：ansible --version 应输出版本号，并带 configured module search path 字段；若为空，说明模块路径未初始化，后续所有模块调用都会失败。
装完必须配 SSH 免密，否则 ansible localhost -m ping 都会卡住
Ansible 默认走 SSH 连接，ansible localhost -m ping 失败时，90% 不是 Ansible 没装好，而是 SSH 密钥没配。报错如 Permission denied (publickey) 或卡在 SSH connection failed 就是这个原因。
执行以下三步即可解决：
- 生成密钥：
ssh-keygen -t ed25519 -N ''（空密码，生产环境可加密码但需配合ssh-agent） - 把公钥写入本地 authorized_keys：
cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys - 测试连接：
ssh -o StrictHostKeyChecking=no localhost -C 'echo ok'，能输出ok才算通
注意：ansible localhost -m ping 成功 ≠ 能连其他主机。它只测控制节点自身 SSH 回环，是验证 Ansible 基础运行能力的第一关。
/etc/ansible/hosts 是默认 inventory，但别直接改它
Ansible 启动时默认读 /etc/ansible/hosts，但直接编辑这个文件容易被系统更新覆盖，也违背最小权限原则。更安全的做法是：用自己的用户目录维护 inventory。
操作建议：
- 创建个人 inventory：
mkdir -p ~/ansible && echo "[test]\n127.0.0.1" > ~/ansible/hosts - 让 Ansible 优先读它：在
~/ansible.cfg中写入[defaults]\ninventory = ~/ansible/hosts - 验证是否生效：
ansible-inventory --graph应显示@test分组
如果 ansible --version 显示 config file = None，说明没加载到配置，此时 inventory 会回退到默认路径，但第三方 collection（如 community.general）可能无法加载。
ansible-core 和 ansible 全功能包的区别必须搞清
RHEL 8+ / Rocky 9 / AlmaLinux 9 默认安装的是 ansible-core，它只含约 150 个内置模块（如 ping、copy、shell），不含任何第三方集合（collection）。想用 community.mysql 或 amazon.aws，必须手动安装：
- 安装 collection：
ansible-galaxy collection install community.mysql - 普通用户安装默认落进
~/.ansible/collections；root 用户则进/usr/share/ansible/collections - 切换用户执行时，
ansible-galaxy list输出可能不一致，务必确认当前用户下的 collection 路径
另外，ansible-core 不带 ansible-doc 的完整文档索引，ansible-doc -l 只列出内置模块；要查 collection 模块帮助，得用 ansible-doc -s community.mysql.mysql_user 这种全名写法。
最易被忽略的一点：Ansible 不是“装完就能跑”，它本质是 SSH 封装器。所有失败，先查 SSH 是否通、密钥是否对、Python 是否在目标机上（ansible all -m raw -a "which python3"）、inventory 路径是否被正确加载——而不是怀疑 Ansible 本身坏了。
