一、Ansible 生产部署常用模块详解（按功能分类）

---

1. 文件与目录管理

 file 模块

用途：创建/删除目录、文件，设置权限、属主等。

常用参数：

• path：目标路径（必填）
• state：directory（目录）、file（文件）、absent（删除）
• mode：权限（如 0755）
• owner / group：属主/属组

生产示例：

- name: 创建应用目录
  file:
    path: /opt/myapp
    state: directory
    mode: '0755'
    owner: appuser
    group: appuser

实践：权限用字符串 '0755'（避免 YAML 解析为八进制错误）。

---

2. 文件分发与模板渲染

 copy 模块

用途：将控制机上的文件复制到目标主机。

关键参数：

• src：本地源文件（相对 playbook 目录）
• dest：目标路径
• mode：权限
• backup: yes：覆盖前备份

示例：

- name: 分发配置文件
  copy:
    src: files/app.conf
    dest: /etc/myapp/app.conf
    mode: '0644'
    backup: yes

 template 模块

用途：使用 Jinja2 模板动态生成配置文件（生产最常用！）

示例：

- name: 渲染 Nginx 配置
  template:
    src: templates/nginx.conf.j2
    dest: /etc/nginx/sites-available/myapp.conf
    mode: '0644'

模板文件 nginx.conf.j2：

server {
    listen {{ nginx_port }};
    server_name {{ app_domain }};
    root {{ app_root }};
}

优势：支持变量、条件、循环，实现“一份模板，多环境部署”。

---

3. 软件包管理

 ansible.builtin.package（通用）或 yum / apt

用途：安装/卸载系统软件包。

示例（RHEL/CentOS）：

- name: 安装依赖包
  yum:
    name:
      - curl
      - wget
      - openssl
    state: present

示例（Debian/Ubuntu）：

- name: 安装 Docker
  apt:
    name: docker.io
    state: latest
    update_cache: yes

生产：固定版本（name: docker-ce-24.0.7）避免意外升级。

---

4. 服务管理

 systemd 模块（推荐）或 service

用途：启停、启用系统服务。

示例：

- name: 启动并启用 Nginx
  systemd:
    name: nginx
    state: started
    enabled: yes

为什么用 systemd：更现代，支持 daemon_reload、masked 等高级操作。

---

5. 执行命令

 command vs shell

模块	特点	适用场景
command	安全，不经过 shell，无法使用管道、重定向、变量	执行简单命令（如 chdir、creates 判断）
shell	功能强，支持 shell 特性	需要管道、重定向、环境变量等

生产示例（安全优先）：

- name: 检查文件是否存在（避免重复执行）
  command: ls /opt/myapp
  args:
    chdir: /opt
  register: result
  ignore_errors: yes

- name: 仅当未安装时执行脚本
  shell: ./install.sh
  args:
    chdir: /tmp/installer
  when: result is failed

安全建议：优先用 command，仅在必要时用 shell，避免命令注入。

---

6. 用户与权限

 user 模块

用途：创建/管理用户。

示例：

- name: 创建应用专用用户
  user:
    name: appuser
    shell: /sbin/nologin
    system: yes
    create_home: no

---

7. 条件与注册变量

 register + when

用途：根据命令输出决定后续操作（生产必备！）

示例：

- name: 检查服务是否已安装
  command: systemctl is-active myapp
  register: svc_status
  ignore_errors: yes

- name: 仅当未运行时部署
  include_tasks: deploy.yml
  when: svc_status.stdout != "active"

---

8. 错误处理

 ignore_errors / failed_when / block + rescue

示例（优雅处理）：

- block:
    - name: 尝试启动服务
      systemd:
        name: myapp
        state: started
  rescue:
    - name: 启动失败，收集日志
      shell: journalctl -u myapp --since "5 minutes ago"
      register: log_output
    - name: 报警（可集成 webhook）
      debug:
        msg: "服务启动失败: {{ log_output.stdout }}"

---

9. 循环（Loops）

 loop / with_items（旧）

用途：批量操作。

示例：

- name: 创建多个目录
  file:
    path: "{{ item }}"
    state: directory
    mode: '0755'
  loop:
    - /data/logs
    - /data/uploads
    - /data/cache

---

10. 等待与重试

 wait_for / until + retries

用途：等待端口、文件、服务就绪。

示例：

- name: 等待数据库端口开放
  wait_for:
    host: db.example.com
    port: 3306
    timeout: 60

- name: 轮询检查 API 健康
  uri:
    url: http://localhost:8080/health
  register: health
  until: health.status == 200
  retries: 10
  delay: 5

---

 二、生产环境 Playbook 最佳实践

原则	说明
幂等性	同一 Playbook 可重复执行，结果一致（用 creates、when 保证）
最小权限	使用普通用户 + become: yes，避免直接用 root
变量分离	敏感信息用 vault，环境变量放 group_vars/
日志与调试	关键步骤 debug 输出，日志重定向到文件
版本控制	Playbook 纳入 Git，配合 CI/CD 流水线
测试先行	用 molecule 或 Vagrant 本地测试

---

 三、完整生产示例：部署一个 Web 服务

# deploy-web.yml
---
- name: 部署 MyApp Web 服务
  hosts: webservers
  become: yes
  vars:
    app_version: "1.2.3"
    app_port: 8080

  tasks:
    - name: 创建应用用户
      user:
        name: myapp
        system: yes
        shell: /sbin/nologin

    - name: 创建目录
      file:
        path: "{{ item }}"
        state: directory
        owner: myapp
        group: myapp
        mode: '0755'
      loop:
        - /opt/myapp
        - /var/log/myapp

    - name: 分发二进制
      copy:
        src: "files/myapp-{{ app_version }}"
        dest: /opt/myapp/myapp
        mode: '0755'
        owner: myapp

    - name: 渲染配置文件
      template:
        src: myapp.conf.j2
        dest: /etc/myapp.conf
        mode: '0644'

    - name: 部署 systemd 服务
      template:
        src: myapp.service.j2
        dest: /etc/systemd/system/myapp.service
      notify: restart myapp

    - name: 启用并启动服务
      systemd:
        name: myapp
        enabled: yes
        state: started

  handlers:
    - name: restart myapp
      systemd:
        name: myapp
        state: restarted

---

四、总结：生产环境核心模块清单

功能	推荐模块
文件/目录	file, copy, template
软件安装	package / yum / apt
服务管理	systemd
命令执行	command（优先）, shell（必要时）
用户管理	user
条件控制	register + when
错误处理	block/rescue
等待检查	wait_for, uri, until
循环操作	loop