Ansible 完全指南

官方文档：https://docs.ansible.com/ansible/latest/
适用版本：Ansible 2.15+（2026-05-07 核实）

核心概念

无 Agent 架构

Ansible 通过 SSH 连接被管理节点，无需在目标机器上安装任何代理程序。控制节点（安装 Ansible 的机器）直接通过 SSH 执行任务，任务完成后不留任何持久进程。

核心特性：

• 无 Agent，目标机器只需 Python（2.7+ 或 3.5+）和 SSH
• 幂等性：多次执行同一 Playbook 结果相同
• 声明式配置：描述目标状态，而非具体步骤
• 基于 YAML，可读性强

核心组件关系

Inventory（目标主机清单）
    |
    v
Playbook（剧本）
    |
    +-- Play（针对一组主机的任务集合）
         |
         +-- Task（调用 Module 的单个步骤）
         |    |
         |    +-- Module（执行具体操作的功能单元，如 apt、copy、service）
         |
         +-- Handler（由 notify 触发的特殊 Task，如重启服务）
         |
         +-- Role（可复用的 Task/变量/文件/模板集合）

Inventory

INI 格式

# 独立主机（无分组）
192.168.1.5

[webservers]
web-01.example.com
web-02.example.com ansible_host=192.168.1.11

[dbservers]
db-01.example.com ansible_host=192.168.1.20 ansible_port=2222

# 范围语法（web-01 到 web-05）
[cache]
redis-[01:05].example.com

# 嵌套组：[父组名:children]
[production:children]
webservers
dbservers

# 组变量：[组名:vars]
[webservers:vars]
ansible_user=ubuntu
ansible_ssh_private_key_file=~/.ssh/prod_key
http_port=80

YAML 格式

# inventory.yml
all:
  children:
    webservers:
      hosts:
        web-01.example.com:
          ansible_host: 192.168.1.10
          http_port: 80
        web-02.example.com:
          ansible_host: 192.168.1.11
      vars:
        ansible_user: ubuntu
        ansible_ssh_private_key_file: ~/.ssh/prod_key

    dbservers:
      hosts:
        db-01.example.com:
          ansible_host: 192.168.1.20
          ansible_port: 2222

    production:
      children:
        webservers:
        dbservers:

主机变量说明

动态 Inventory

动态 Inventory 通过可执行脚本或插件从外部系统（AWS、GCP、CMDB）动态获取主机列表。

# 使用动态 inventory 脚本
ansible-playbook -i inventory_script.py site.yml

# 使用 inventory 插件（aws_ec2）
ansible-inventory -i aws_ec2.yml --list

aws_ec2.yml 示例：

plugin: amazon.aws.aws_ec2
regions:
  - cn-north-1
filters:
  instance-state-name: running
  tag:Environment: production
keyed_groups:
  - key: tags.Role
    prefix: role

Playbook 语法

完整 Playbook 结构

---
# site.yml
- name: 配置 Web 服务器
  hosts: webservers
  become: true
  gather_facts: true

  vars:
    app_port: 8000
    app_user: www-data

  vars_files:
    - vars/secrets.yml

  pre_tasks:
    - name: 更新 apt 缓存
      ansible.builtin.apt:
        update_cache: true
        cache_valid_time: 3600

  roles:
    - common
    - nginx

  tasks:
    - name: 确保应用目录存在
      ansible.builtin.file:
        path: /opt/app
        state: directory
        owner: "{{ app_user }}"
        mode: "0755"

    - name: 部署应用配置
      ansible.builtin.template:
        src: app.conf.j2
        dest: /etc/app/app.conf
      notify: restart app

  post_tasks:
    - name: 验证服务启动
      ansible.builtin.uri:
        url: "http://localhost:{{ app_port }}/health"
        status_code: 200

  handlers:
    - name: restart app
      ansible.builtin.service:
        name: myapp
        state: restarted

Play 字段

Task 字段

tasks:
  - name: 安装 Python 依赖
    ansible.builtin.pip:
      requirements: /opt/app/requirements.txt
      virtualenv: /opt/app/venv
    # 条件执行
    when: ansible_os_family == "Debian"
    # 注册返回值
    register: pip_result
    # 触发 Handler
    notify: restart app
    # 循环
    loop:
      - package1
      - package2
    # 标签（ansible-playbook --tags deploy 时执行）
    tags:
      - deploy
      - python
    # 忽略错误
    ignore_errors: true
    # 超时（秒）
    timeout: 60
    # 失败重试
    retries: 3
    delay: 5
    until: pip_result.rc == 0

Task 字段说明：

when 条件语法

tasks:
  # 比较操作系统
  - name: 安装 apt 包（仅 Debian/Ubuntu）
    ansible.builtin.apt:
      name: nginx
    when: ansible_os_family == "Debian"

  # 检查变量
  - name: 仅在生产环境执行
    ansible.builtin.command: /opt/scripts/deploy.sh
    when: env == "production"

  # 多条件（and）
  - name: 满足多个条件
    ansible.builtin.debug:
      msg: "条件满足"
    when:
      - ansible_memtotal_mb > 2048
      - ansible_processor_vcpus >= 2

  # or 条件
  - name: 满足任一条件
    ansible.builtin.debug:
      msg: "OS 匹配"
    when: ansible_distribution == "Ubuntu" or ansible_distribution == "Debian"

  # 检查变量是否定义
  - name: 仅在变量已定义时执行
    ansible.builtin.debug:
      msg: "{{ my_var }}"
    when: my_var is defined

  # 检查命令返回值
  - name: 检查文件是否存在
    ansible.builtin.stat:
      path: /opt/app/.installed
    register: installed_flag

  - name: 仅在未安装时执行安装
    ansible.builtin.command: /opt/scripts/install.sh
    when: not installed_flag.stat.exists

loop 和 with_items

# 现代写法（loop，Ansible 2.5+）
- name: 安装多个软件包
  ansible.builtin.apt:
    name: "{{ item }}"
    state: present
  loop:
    - nginx
    - git
    - python3
    - python3-pip

# 遍历字典列表
- name: 创建多个用户
  ansible.builtin.user:
    name: "{{ item.name }}"
    groups: "{{ item.groups }}"
    shell: /bin/bash
  loop:
    - { name: alice, groups: sudo }
    - { name: bob, groups: www-data }

# loop_control：自定义循环变量名和标签
- name: 部署多个应用
  ansible.builtin.template:
    src: "{{ item.src }}"
    dest: "{{ item.dest }}"
  loop: "{{ app_configs }}"
  loop_control:
    loop_var: item          # 默认就是 item，可以改名避免嵌套循环冲突
    label: "{{ item.dest }}" # 简化输出中每次迭代的显示

# 传统写法（with_items，仍然有效但不推荐）
- name: 安装软件包（旧写法）
  ansible.builtin.apt:
    name: "{{ item }}"
  with_items:
    - nginx
    - git

register 保存结果

- name: 检查 Nginx 运行状态
  ansible.builtin.command: systemctl is-active nginx
  register: nginx_status
  ignore_errors: true

- name: 打印 Nginx 状态
  ansible.builtin.debug:
    msg: "Nginx 状态：{{ nginx_status.stdout }}"

- name: 仅在 Nginx 未运行时启动
  ansible.builtin.service:
    name: nginx
    state: started
  when: nginx_status.rc != 0

# 常用 register 返回字段
# result.stdout        - 标准输出（字符串）
# result.stderr        - 标准错误（字符串）
# result.rc            - 返回码（int）
# result.stdout_lines  - 标准输出按行分割的列表
# result.changed       - 是否有变更（bool）
# result.failed        - 是否失败（bool）

常用模块

ansible.builtin.command / shell

# command：不经过 shell，更安全，不支持管道、重定向、通配符
- name: 执行脚本
  ansible.builtin.command:
    cmd: /opt/scripts/migrate.sh
    chdir: /opt/app         # 执行前切换目录
    creates: /opt/app/.migrated  # 文件存在时跳过（幂等性保障）

# shell：经过 /bin/sh，支持管道、重定向、环境变量展开
- name: 统计日志行数
  ansible.builtin.shell:
    cmd: "grep ERROR /var/log/app.log | wc -l"
  register: error_count

ansible.builtin.copy

- name: 复制配置文件
  ansible.builtin.copy:
    src: files/nginx.conf         # 控制节点上的路径（相对于 playbook 或 role）
    dest: /etc/nginx/nginx.conf   # 目标路径
    owner: root
    group: root
    mode: "0644"
    backup: true                  # 覆盖前备份原文件
  notify: reload nginx

- name: 直接写入内容
  ansible.builtin.copy:
    content: |
      [Unit]
      Description=My App
    dest: /etc/systemd/system/myapp.service
    mode: "0644"

ansible.builtin.template

基于 Jinja2 模板引擎渲染文件，支持变量、条件、循环。

- name: 渲染 Nginx 配置
  ansible.builtin.template:
    src: templates/nginx.conf.j2
    dest: /etc/nginx/sites-available/myapp.conf
    owner: root
    mode: "0644"
  notify: reload nginx

模板文件示例（templates/nginx.conf.j2）：

# 由 Ansible 自动生成，请勿手动修改
server {
    listen {{ http_port }};
    server_name {{ ansible_hostname }};

    location / {
        proxy_pass http://127.0.0.1:{{ app_port }};
        proxy_set_header Host $host;
    }

    {% if ssl_enabled %}
    listen 443 ssl;
    ssl_certificate {{ ssl_cert_path }};
    ssl_certificate_key {{ ssl_key_path }};
    {% endif %}
}

ansible.builtin.file

# 创建目录
- name: 创建应用数据目录
  ansible.builtin.file:
    path: /opt/app/data
    state: directory
    owner: app_user
    group: app_user
    mode: "0755"
    recurse: true    # 递归设置权限

# 创建符号链接
- name: 创建当前版本链接
  ansible.builtin.file:
    src: /opt/app/releases/v1.2.3
    dest: /opt/app/current
    state: link

# 删除文件或目录
- name: 清理旧版本
  ansible.builtin.file:
    path: /opt/app/releases/v1.1.0
    state: absent

ansible.builtin.apt / yum / dnf

# apt（Debian/Ubuntu）
- name: 安装 Nginx
  ansible.builtin.apt:
    name:
      - nginx
      - python3-pip
    state: present
    update_cache: true
    cache_valid_time: 3600

# 安装指定版本
- name: 安装指定版本的 Python
  ansible.builtin.apt:
    name: python3.11=3.11.0-1
    state: present

# yum（CentOS/RHEL 7）
- name: 安装依赖
  ansible.builtin.yum:
    name: "@Development Tools"
    state: present

# dnf（Fedora/CentOS 8+）
- name: 安装软件包
  ansible.builtin.dnf:
    name: python3
    state: latest

apt 模块 state 字段：

ansible.builtin.service

- name: 启动并设置 Nginx 开机自启
  ansible.builtin.service:
    name: nginx
    state: started
    enabled: true

- name: 重启应用（用于 Handler）
  ansible.builtin.service:
    name: myapp
    state: restarted

ansible.builtin.user / group

- name: 创建应用运行组
  ansible.builtin.group:
    name: appgroup
    gid: 1500
    system: true

- name: 创建应用运行用户
  ansible.builtin.user:
    name: appuser
    uid: 1500
    group: appgroup
    groups:
      - sudo
    shell: /bin/bash
    home: /opt/app
    create_home: true
    system: false
    password: "{{ vault_app_password | password_hash('sha512') }}"

ansible.builtin.git

- name: 克隆应用代码
  ansible.builtin.git:
    repo: "https://github.com/org/myapp.git"
    dest: /opt/app/releases/{{ app_version }}
    version: "{{ app_version }}"    # tag、branch 或 commit hash
    depth: 1                         # 浅克隆，加速
    force: false                     # 是否丢弃本地修改
  register: git_result
  notify: restart app

community.docker.docker_container

- name: 启动 Redis 容器
  community.docker.docker_container:
    name: redis
    image: redis:7-alpine
    state: started
    restart_policy: unless-stopped
    ports:
      - "127.0.0.1:6379:6379"
    volumes:
      - /opt/redis/data:/data
    env:
      REDIS_PASSWORD: "{{ vault_redis_password }}"
    command: "redis-server --requirepass {{ vault_redis_password }}"
    networks:
      - name: app-network

变量系统

变量优先级（从低到高）

优先级越高，值越能覆盖低优先级的同名变量：

group_vars 和 host_vars 目录

inventory/
    hosts.yml
    group_vars/
        all.yml               # 所有主机共享变量
        all/
            main.yml
            vault.yml         # ansible-vault 加密的敏感变量
        webservers.yml        # 仅 webservers 组的变量
        dbservers/
            main.yml
            vault.yml
    host_vars/
        web-01.example.com.yml    # 仅 web-01 的变量

group_vars/all.yml 示例：

# 所有主机的公共变量
timezone: Asia/Shanghai
ntp_server: ntp.aliyun.com
log_level: info

vars_files 加载

- name: 部署应用
  hosts: webservers
  vars_files:
    - vars/common.yml
    - vars/{{ env }}.yml        # 动态加载（根据 env 变量选择文件）
    - "vars/secrets.yml"

ansible-vault 加密敏感变量

# 加密整个文件
ansible-vault encrypt vars/secrets.yml

# 解密文件
ansible-vault decrypt vars/secrets.yml

# 查看加密文件内容
ansible-vault view vars/secrets.yml

# 编辑加密文件
ansible-vault edit vars/secrets.yml

# 加密单个字符串（嵌入普通 YAML 文件）
ansible-vault encrypt_string 'my_secret_password' --name 'db_password'

# 执行 Playbook 时提供密码
ansible-playbook site.yml --ask-vault-pass
ansible-playbook site.yml --vault-password-file ~/.vault_pass

加密文件内容示例（vars/secrets.yml）：

$ANSIBLE_VAULT;1.1;AES256
63303831303566336465396561396531303466306365326665313565353065323...

Roles

Role 目录结构

roles/
  myapp/
    tasks/
      main.yml          # 主 Task 文件，其他文件可通过 include 引入
      install.yml
      configure.yml
    handlers/
      main.yml          # Handler 定义
    templates/
      nginx.conf.j2     # Jinja2 模板文件
      app.conf.j2
    files/
      app.service       # 静态文件（copy 模块使用）
    vars/
      main.yml          # Role 变量（高优先级，一般不被覆盖）
    defaults/
      main.yml          # Role 默认变量（最低优先级，允许使用者覆盖）
    meta/
      main.yml          # Role 元数据（依赖声明）
    README.md

defaults/main.yml 示例：

# 使用者可以在 group_vars 或 playbook 中覆盖这些值
app_port: 8000
app_workers: 4
app_log_level: info

meta/main.yml 示例：

galaxy_info:
  author: yourname
  description: Deploy FastAPI app with Supervisor
  min_ansible_version: "2.10"

dependencies:
  - role: common
  - role: nginx
    vars:
      nginx_listen_port: 80

创建 Role

# 使用 ansible-galaxy 初始化 Role 目录结构
ansible-galaxy init roles/myapp

# 初始化后生成完整目录结构

requirements.yml 依赖管理

# requirements.yml
---
roles:
  # 从 Ansible Galaxy 安装
  - name: geerlingguy.nginx
    version: "3.2.0"

  # 从 Git 仓库安装
  - name: internal-common
    src: git+https://github.com/org/ansible-common.git
    version: main
    scm: git

collections:
  - name: community.docker
    version: ">=3.0.0"
  - name: amazon.aws
    version: "6.0.0"

# 安装 requirements.yml 中的依赖
ansible-galaxy install -r requirements.yml
ansible-galaxy collection install -r requirements.yml

实战场景

批量部署 Python 应用（FastAPI + Supervisor）

# playbooks/deploy_fastapi.yml
---
- name: 部署 FastAPI 应用
  hosts: webservers
  become: true
  vars:
    app_name: myapi
    app_version: "{{ version | default('main') }}"
    app_dir: "/opt/{{ app_name }}"
    app_user: appuser
    app_port: 8000
    app_workers: 4

  tasks:
    - name: 确保应用用户存在
      ansible.builtin.user:
        name: "{{ app_user }}"
        system: true
        shell: /bin/false
        home: "{{ app_dir }}"
        create_home: false

    - name: 创建应用目录结构
      ansible.builtin.file:
        path: "{{ item }}"
        state: directory
        owner: "{{ app_user }}"
        mode: "0755"
      loop:
        - "{{ app_dir }}"
        - "{{ app_dir }}/releases"
        - "{{ app_dir }}/shared/logs"
        - "{{ app_dir }}/shared/config"

    - name: 拉取最新代码
      ansible.builtin.git:
        repo: "https://github.com/org/{{ app_name }}.git"
        dest: "{{ app_dir }}/releases/{{ app_version }}"
        version: "{{ app_version }}"
        depth: 1
      register: git_result

    - name: 创建虚拟环境并安装依赖
      ansible.builtin.pip:
        requirements: "{{ app_dir }}/releases/{{ app_version }}/requirements.txt"
        virtualenv: "{{ app_dir }}/venv"
        virtualenv_python: python3

    - name: 更新 current 符号链接
      ansible.builtin.file:
        src: "{{ app_dir }}/releases/{{ app_version }}"
        dest: "{{ app_dir }}/current"
        state: link
      notify: restart app

    - name: 部署 Supervisor 配置
      ansible.builtin.template:
        src: templates/supervisor.conf.j2
        dest: "/etc/supervisor/conf.d/{{ app_name }}.conf"
        mode: "0644"
      notify: reload supervisor

    - name: 确保 Supervisor 运行
      ansible.builtin.service:
        name: supervisor
        state: started
        enabled: true

  handlers:
    - name: reload supervisor
      ansible.builtin.command: supervisorctl reread
      notify: update supervisor

    - name: update supervisor
      ansible.builtin.command: supervisorctl update

    - name: restart app
      ansible.builtin.supervisorctl:
        name: "{{ app_name }}"
        state: restarted

Supervisor 配置模板（templates/supervisor.conf.j2）：

[program:{{ app_name }}]
command={{ app_dir }}/venv/bin/uvicorn main:app --host 0.0.0.0 --port {{ app_port }} --workers {{ app_workers }}
directory={{ app_dir }}/current
user={{ app_user }}
autostart=true
autorestart=true
redirect_stderr=true
stdout_logfile={{ app_dir }}/shared/logs/app.log
stdout_logfile_maxbytes=50MB
stdout_logfile_backups=10
environment=APP_ENV="{{ env }}"

配置 Nginx + SSL

# tasks/nginx_ssl.yml
- name: 安装 Certbot
  ansible.builtin.apt:
    name:
      - certbot
      - python3-certbot-nginx
    state: present

- name: 申请 Let's Encrypt 证书
  ansible.builtin.command:
    cmd: >
      certbot certonly --nginx
      -d {{ domain }}
      --non-interactive
      --agree-tos
      --email {{ admin_email }}
    creates: "/etc/letsencrypt/live/{{ domain }}/fullchain.pem"
  notify: reload nginx

- name: 部署 Nginx 站点配置
  ansible.builtin.template:
    src: templates/nginx_ssl.conf.j2
    dest: "/etc/nginx/sites-available/{{ domain }}"
    mode: "0644"
  notify: reload nginx

- name: 启用站点
  ansible.builtin.file:
    src: "/etc/nginx/sites-available/{{ domain }}"
    dest: "/etc/nginx/sites-enabled/{{ domain }}"
    state: link
  notify: reload nginx

- name: 配置证书自动续期 cron
  ansible.builtin.cron:
    name: "certbot renew"
    hour: "3"
    minute: "30"
    weekday: "1"
    job: "certbot renew --quiet && systemctl reload nginx"

踩坑与注意事项

command vs shell 的区别

command 模块不通过 Shell 解释器执行，因此：

原则：优先用 command，仅在需要管道或重定向时才用 shell。

幂等性设计

Ansible 的核心价值是幂等性，即多次运行结果相同。设计 Task 时注意：

# 错误：每次都会执行，无法判断是否已完成
- name: 初始化数据库
  ansible.builtin.command: python manage.py migrate

# 正确：通过 creates 标志或 register + when 实现幂等
- name: 检查迁移标志
  ansible.builtin.stat:
    path: /opt/app/.migrated
  register: migrated

- name: 初始化数据库（仅首次）
  ansible.builtin.command:
    cmd: python manage.py migrate
    chdir: /opt/app
  when: not migrated.stat.exists

- name: 创建迁移完成标志
  ansible.builtin.file:
    path: /opt/app/.migrated
    state: touch
  when: not migrated.stat.exists

避免以下反幂等模式：

• 不加 creates 的 command / shell
• 用 lineinfile 但没有正确设置 regexp（会重复追加）
• template 中使用每次都变化的值（如时间戳）

become 提权失败排查

# 测试 sudo 权限
ansible webservers -m command -a "whoami" --become -v

# 常见原因 1：目标用户没有 sudo 权限
# 解决：在 /etc/sudoers 中添加
echo "ansible_user ALL=(ALL) NOPASSWD: ALL" | sudo tee /etc/sudoers.d/ansible

# 常见原因 2：sudo 需要密码但未提供
# 解决：执行时添加 --ask-become-pass 或设置 NOPASSWD
ansible-playbook site.yml --ask-become-pass

# 常见原因 3：become_method 不对（某些系统用 su 而非 sudo）
- name: 提权执行
  ansible.builtin.command: whoami
  become: true
  become_method: sudo    # 或 su、doas、pbrun 等
  become_user: root

调试常用命令

# 检查 Inventory 解析结果
ansible-inventory -i inventory/ --list

# 测试主机连通性
ansible all -m ping -i inventory/

# 列出所有 hosts 和 facts
ansible webservers -m setup | grep ansible_distribution

# 空运行（不真正执行，--check）
ansible-playbook site.yml --check

# 显示差异（--diff，配合 template/copy 使用）
ansible-playbook site.yml --check --diff

# 仅执行特定 Tag
ansible-playbook site.yml --tags "deploy,nginx"

# 跳过特定 Tag
ansible-playbook site.yml --skip-tags "slow_tasks"

# 从特定 Task 开始执行
ansible-playbook site.yml --start-at-task="部署应用配置"

# 逐步确认执行
ansible-playbook site.yml --step

# 增加详细输出
ansible-playbook site.yml -v    # -vv -vvv 逐级增加

最佳实践

目录结构：遵循 Ansible 推荐布局

project/
├── ansible.cfg              # 项目级配置（inventory 路径、roles 路径等）
├── inventory/
│   ├── production/
│   │   ├── hosts            # 生产环境主机
│   │   └── group_vars/
│   │       ├── all.yml      # 所有主机共用变量
│   │       └── webservers.yml
│   └── staging/
│       └── hosts
├── roles/
│   ├── common/              # 基础配置（NTP、用户、防火墙）
│   ├── nginx/               # Nginx 角色
│   └── app/                 # 应用部署角色
├── site.yml                 # 主 Playbook（入口）
├── webservers.yml           # 仅针对 webservers 的 Playbook
└── requirements.yml         # Ansible Galaxy 依赖声明

Ansible Vault：加密敏感变量

不要在 Git 中存储明文密码、API Key 等敏感信息：

# 加密整个文件
ansible-vault encrypt vars/secrets.yml

# 编辑加密文件
ansible-vault edit vars/secrets.yml

# 加密单个字符串（嵌入到普通 YAML 中）
ansible-vault encrypt_string 'mysecretpassword' --name 'db_password'

# 执行时提供密码文件
ansible-playbook site.yml --vault-password-file ~/.vault_pass

在 vars/secrets.yml 中：

db_password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  66386439...（加密后的内容）

幂等性设计原则

• 优先使用声明式模块（file、template、apt、service）而非 command/shell
• 使用 command/shell 时配合 creates、removes 或 changed_when 实现幂等
• 避免 command: echo "something" 这类永远 changed 的写法

# 错误：每次都 changed，破坏幂等性
- name: 初始化数据库
  ansible.builtin.command: python manage.py migrate

# 正确：通过返回码判断是否真正有变更
- name: 初始化数据库
  ansible.builtin.command: python manage.py migrate
  register: migrate_result
  changed_when: "'No migrations to apply' not in migrate_result.stdout"

滚动更新：serial + 健康检查

- name: 滚动更新 Web 服务器（每次 20%）
  hosts: webservers
  serial: "20%"          # 或 serial: 2（绝对数量）
  max_fail_percentage: 0 # 任意主机失败立即终止

  tasks:
    - name: 从负载均衡摘除节点
      community.general.haproxy:
        state: disabled
        host: "{{ inventory_hostname }}"
        socket: /var/run/haproxy/admin.sock

    - name: 部署新版本
      ansible.builtin.git:
        repo: "https://github.com/org/app.git"
        dest: /opt/app
        version: "{{ app_version }}"

    - name: 健康检查
      ansible.builtin.uri:
        url: "http://localhost:8000/health"
        status_code: 200
      retries: 5
      delay: 10

    - name: 重新加入负载均衡
      community.general.haproxy:
        state: enabled
        host: "{{ inventory_hostname }}"
        socket: /var/run/haproxy/admin.sock

性能优化

常见陷阱

陷阱：任务幂等性破坏——每次都触发 changed

现象： Playbook 每次运行相同任务都报 changed，重复执行会触发不必要的 handler（如重启服务）。
原因： 使用 shell/command 模块执行的命令无状态感知，Ansible 无法判断是否需要执行，默认标记为 changed。
解决： 优先用内置模块（copy、template、lineinfile、service），它们原生支持幂等性。必须用 shell 时，配合 creates 或 changed_when: false：

- name: 初始化数据库（仅首次）
  shell: init-db.sh
  args:
    creates: /var/lib/db/.initialized  # 文件存在则跳过

陷阱：become: true 与 SSH 转发冲突

现象： 使用 become: true 提权后，任务中的 git 或 ssh 操作报权限错误，无法访问私钥。
原因： become 切换用户后，SSH agent forwarding 的 socket 路径属于原用户，新用户无读取权限。
解决： 避免在 become 后执行需要 SSH 认证的操作；改用 deploy key 或在目标机器上配置 HTTPS token 认证；或用 become_flags: -E 保留环境变量（需 sudo 配置允许）。

陷阱：变量优先级混乱导致意外覆盖

现象： 在 group_vars 中定义的变量被某个任务中的 set_fact 覆盖，后续任务使用了错误值。
原因： Ansible 变量有 22 个优先级层级，set_fact 的优先级高于 group_vars，容易在调试时留下副作用。
解决： 了解优先级顺序（extra vars > set_fact > role vars > group_vars），生产 Playbook 避免用 set_fact 修改全局变量，改用 register 保存局部结果。

参见

• Kubernetes基础 — Ansible 与 Kubernetes 结合部署应用
• Docker Compose完全指南 — 用 Ansible 管理 Docker Compose 应用
• Prometheus与Grafana监控 — 用 Ansible 自动化部署监控栈
• Git进阶指南 — Ansible Playbook 的版本控制工作流