介绍

Ansible 模块（Module）是 Ansible 的 最小执行单元，也叫插件。执行 ansible/ansible-playbook 时，模块会被临时传输到目标主机执行，执行完成后自动删除，无常驻代理。

特点：**无Agent**；绝大多数模块是幂等的（多次执行结果一致，不会重复改动）。

一、模块分类

核心模块（core modules）：官方维护，常用基础模块，优先内置。
集合模块（collection modules）：Ansible 2.10+ 把大量模块剥离到 ansible.collections，需要安装对应集合。
自定义模块：自己用 Python/Shell 编写。

二、高频常用模块详解

1. command

执行简单命令，不支持管道、重定向、变量替换（底层不是shell）

- name: 查看主机时间
  command: date

注意：不要用 | > &，有shell需求改用 shell

2. shell

在目标主机shell中执行命令，支持管道、重定向

- name: 过滤进程
  shell: ps aux | grep nginx

安全提醒：尽量优先command；传入用户变量时注意注入风险。

3. raw

直接发送原始命令，不依赖目标主机有Python。
适用场景：新裸机、网络设备、没有Python的系统。

- name: 无Python机器执行命令
  raw: hostname

4. file

文件/目录管理，创建、删除、修改权限属主

# 创建目录
- file:
    path: /data/test
    state: directory  # directory=目录，touch=文件，absent=删除
    owner: root
    group: root
    mode: '0755'

5. copy

把控制端本地文件拷贝到远程主机

- name: 推送配置文件
  copy:
    src: ./nginx.conf
    dest: /etc/nginx/nginx.conf
    owner: root
    mode: '0644'
    backup: yes # 改动前备份原文件

6. fetch

和copy反向：拉取远程文件到控制端，只能拉文件，不能拉目录

- name: 收集远程日志
  fetch:
    src: /var/log/messages
    dest: ./log_backup/

保存路径：dest/主机名/src路径

7. template

模板文件（Jinja2）推送远程，支持变量渲染

- name: 渲染模板
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf

模板文件内可写 {{ nginx_port }} 变量

8. yum / dnf

RHEL/CentOS 系列软件包管理

- name: 安装nginx
  yum:
    name: nginx
    state: present # present安装，latest最新版，absent卸载

CentOS8+推荐用 dnf

9. apt

Debian/Ubuntu 包管理

- name: 安装nginx
  apt:
    name: nginx
    state: present
    update_cache: yes # 相当于apt update

10. service / systemd

服务启停、开机自启

- name: 启动nginx并开机自启
  service:
    name: nginx
    state: started # started/stopped/restarted/reloaded
    enabled: yes

systemd模块支持更多systemd特性（daemon_reload等）

11. user

用户管理，创建删除用户、设置uid、密码

- name: 创建test用户
  user:
    name: test
    uid: 1008
    shell: /bin/bash
    state: present

12. group

用户组管理

- group:
    name: ops
    gid: 2000
    state: present

13. lineinfile

修改文件单行内容，适合替换/新增一行

- name: 修改sshd配置允许密码登录
  lineinfile:
    path: /etc/ssh/sshd_config
    regexp: '^PasswordAuthentication'
    line: 'PasswordAuthentication yes'

14. blockinfile

在文件中插入一段多行文本，会自动加标记 # BEGIN/END ANSIBLE MANAGED BLOCK

- blockinfile:
    path: /etc/profile
    block: |
      export JAVA_HOME=/usr/local/jdk

15. unarchive

解压压缩包到远程主机

remote_src=no：压缩包在控制机（默认），上传后解压
remote_src=yes：压缩包已经在远程主机，直接解压
```yaml
name: 解压本地jdk包到远程
unarchive:
src: jdk.tar.gz
dest: /usr/local/
remote_src: no
```

16. get_url

远程主机下载网络文件（wget/curl）

- name: 下载nginx源码包
  get_url:
    url: https://xxx/nginx.tar.gz
    dest: /tmp/nginx.tar.gz

17. cron

定时任务管理

- name: 每天凌晨2点备份
  cron:
    name: backup
    minute: 0
    hour: 2
    job: /bin/sh /data/backup.sh

18. mount

挂载文件系统，写入/etc/fstab持久化

- name: 挂载/data分区
  mount:
    path: /data
    src: /dev/sdb1
    fstype: ext4
    state: mounted # mounted临时挂载+fstab写入；present只写fstab

19. assert

断言校验，用于playbook做条件检查，失败直接终止playbook

- assert:
    that:
      - ansible_distribution == "CentOS"
    fail_msg: "仅支持CentOS系统"

三、模块使用方式

1. Ad-hoc 命令行直接调用模块

格式：ansible 主机组 -m 模块名 -a "模块参数"

ansible web -m shell -a "df -h"
ansible web -m file -a "path=/tmp/abc state=touch"

2. Playbook YAML中调用

tasks:
  - name: task描述
    模块名:
      参数1: 值
      参数2: 值

四、查看模块文档

# 查看模块帮助
ansible-doc file
# 只看示例
ansible-doc -s copy

五、模块选择建议（避坑）

优先使用原生模块，不要无脑shell/command：原生模块自带幂等、错误处理；shell每次都会返回changed。
单行修改文件用 lineinfile，多行用 blockinfile，批量模板渲染用 template。
需要Jinja变量渲染文件 → template；单纯静态文件拷贝 → copy。

原文出处：/show_1GW45HDJMSJG.html