概述

Ansible 的上手门槛很低——一个 YAML 文件、几行 yum install 就能跑通。但当你面对几百台服务器、多套环境、复杂的依赖关系和严格的变更审计要求时，“能跑"和"能上线"之间隔着一整个工程体系。本文把生产级 Playbook 的核心实践浓缩成一份可操作的指南，涵盖从结构组织到性能优化的全链路。

参考来源：Ansible 官方好的实践

一、Playbook 结构优化

1.1 目录布局

生产级 Ansible 项目应该遵循标准目录结构。这不是 Ansible 的强制要求，而是大量团队踩坑后形成的共识：

production-project/
├── ansible.cfg              # 项目级配置
├── inventory/
│   ├── production/
│   │   ├── hosts.ini        # 生产环境主机清单
│   │   └── group_vars/
│   │       ├── all.yml      # 所有环境共享变量
│   │       ├── web.yml      # web 组专用变量
│   │       └── db.yml       # db 组专用变量
│   └── staging/
│       ├── hosts.ini
│       └── group_vars/
│           └── all.yml
├── roles/
│   ├── nginx/
│   │   ├── defaults/
│   │   │   └── main.yml     # 默认变量（低优先级）
│   │   ├── vars/
│   │   │   └── main.yml     # 角色内部变量（高优先级）
│   │   ├── tasks/
│   │   │   └── main.yml
│   │   ├── handlers/
│   │   │   └── main.yml
│   │   ├── templates/
│   │   │   └── nginx.conf.j2
│   │   ├── files/
│   │   └── meta/
│   │       └── main.yml
│   └── postgresql/
├── playbooks/
│   ├── site.yml             # 主入口
│   ├── web.yml
│   └── db.yml
└── requirements.yml          # Galaxy 依赖

1.2 入口文件设计

site.yml 是整个 Playbook 的总入口，应该做到"一眼看清架构”：

---
# site.yml - 主部署入口
- name: 部署 Web 层
  import_playbook: playbooks/web.yml

- name: 部署数据库层
  import_playbook: playbooks/db.yml

- name: 部署缓存层
  import_playbook: playbooks/cache.yml

- name: 部署监控层
  import_playbook: playbooks/monitoring.yml

每个子 Playbook 只负责自己的层级：

---
# playbooks/web.yml
- name: 配置 Web 服务器
  hosts: web
  become: true
  roles:
    - role: common
      tags: [common, base]
    - role: nginx
      tags: [nginx, web]
    - role: logrotate
      tags: [logrotate]

关键原则：入口文件保持扁平，用 import_playbook 组织流程；每个角色只做一件事；用 tags 控制执行范围。

1.3 import vs include

Ansible 提供两种引入方式，行为差异显著：

特性import_*（静态）include_*（动态）
解析时机Playbook 解析时运行到该处时
变量可用性只能使用解析时已知变量可使用运行时动态变量
循环不支持支持
条件应用于所有子任务应用于 include 语句本身
tags继承到所有子任务仅应用于 include 语句
# 静态导入：编译时确定，适合固定结构
- import_tasks: install.yml

# 动态包含：运行时确定，适合条件分支
- include_tasks: "{{ ansible_os_family | lower }}_setup.yml"

二、变量管理

2.1 变量优先级

Ansible 的变量优先级从低到高多达 22 层，理解核心几层即可覆盖 90% 场景：

优先级变量来源典型用途
1（低）role defaults角色的安全默认值
2inventory group_vars环境级共享配置
3inventory host_vars单台主机特殊配置
4play varsPlaybook 级变量
5role vars角色内部强制值
6extra vars（-e）命令行覆盖，最高优先级

实践建议：把"可能被覆盖的默认值"放在 defaults/，把"角色正常工作必须的值"放在 vars/。默认值要安全到"不传任何变量也能跑通"。

2.2 变量分层组织

# inventory/production/group_vars/all.yml
# === 全局共享变量 ===
---
ntp_servers:
  - ntp1.aliyun.com
  - ntp2.aliyun.com
dns_servers:
  - 223.5.5.5
  - 8.8.8.8
sysctl_config:
  net.core.somaxconn: 65535
  vm.swappiness: 10
  net.ipv4.tcp_max_syn_backlog: 65535

# inventory/production/group_vars/web.yml
# === Web 层专用变量 ===
---
nginx_worker_processes: auto
nginx_worker_connections: 10240
nginx_keepalive_timeout: 65
upstream_backends:
  - { name: app1, host: 10.0.1.11, port: 8080 }
  - { name: app2, host: 10.0.1.12, port: 8080 }

# inventory/production/host_vars/web-01.yml
# === 单台主机变量 ===
---
ansible_host: 10.0.1.21
nginx_worker_processes: 4  # 覆盖组级别配置

2.3 变量验证

用 assert 模块在执行前验证变量，避免错误传到后面才暴露：

---
# roles/nginx/tasks/main.yml
- name: 验证必需变量
  assert:
    that:
      - nginx_worker_processes is defined
      - nginx_worker_processes | int >= 1
      - nginx_port in [80, 443, 8080, 8443]
      - upstream_backends | length > 0
    fail_msg: "Nginx 角色必需变量缺失或非法，请检查 group_vars 配置"
    success_msg: "变量验证通过"
  tags: [validate]

三、角色设计

3.1 角色职责单一

好的角色像 Unix 工具：只做一件事，做好它。对比以下两种设计：

# ❌ 糟糕的设计：一个角色包揽一切
roles/
  └── lamp/
      └── tasks/main.yml    # 安装 Linux+Apache+MySQL+PHP 全塞这里

# ✅ 良好的设计：拆分为可组合的原子角色
roles/
  ├── common/               # 基础初始化
  ├── nginx/                # Web 服务器
  ├── php-fpm/              # PHP 运行时
  ├── mysql/                # 数据库
  └── composer/             # 依赖管理

3.2 角色 meta 声明依赖

通过 meta/main.yml 声明角色依赖，Ansible 会自动按顺序执行：

---
# roles/php-fpm/meta/main.yml
dependencies:
  - role: common
    tags: [common]
  - role: repo-remi
    when: ansible_os_family == "RedHat"

注意：角色依赖会在当前角色之前执行。避免循环依赖，避免在 meta 中写复杂的条件逻辑。

3.3 幂等性设计

幂等性是 Ansible 的核心优势，但不是自动的——需要你在写 task 时刻意保证：

---
# ❌ 非幂等：每次都会追加
- name: 配置 hosts
  shell: echo "10.0.1.10 app-server" >> /etc/hosts

# ✅ 幂等：使用 lineinfile 模块
- name: 确保 hosts 配置存在
  lineinfile:
    path: /etc/hosts
    line: "10.0.1.10 app-server"
    state: present

# ✅ 幂等：使用 blockinfile 管理多行配置块
- name: 确保 hosts 配置块存在
  blockinfile:
    path: /etc/hosts
    marker: "# {mark} ANSIBLE MANAGED BLOCK"
    block: |
      10.0.1.10 app-server
      10.0.1.11 db-server
      10.0.1.12 cache-server      
    state: present

四、条件与循环

4.1 条件判断

---
# 基于操作系统分发
- name: 安装 Nginx（RedHat 系）
  yum:
    name: nginx
    state: present
  when: ansible_os_family == "RedHat"

- name: 安装 Nginx（Debian 系）
  apt:
    name: nginx
    state: present
    update_cache: true
  when: ansible_os_family == "Debian"

# 基于变量标记
- name: 配置高可用参数
  sysctl:
    name: "{{ item.key }}"
    value: "{{ item.value }}"
    sysctl_set: true
  loop: "{{ sysctl_config | dict2items }}"
  when: enable_ha_tuning | default(false) | bool

# 基于命令结果
- name: 检查是否需要重建配置
  command: nginx -t
  register: nginx_test
  changed_when: false
  failed_when: false

- name: 重载 Nginx 配置
  systemd:
    name: nginx
    state: reloaded
  when: nginx_test.rc == 0

4.2 循环模式

---
# 基本循环
- name: 创建多个用户
  user:
    name: "{{ item.name }}"
    groups: "{{ item.groups }}"
    shell: "{{ item.shell | default('/bin/bash') }}"
  loop:
    - { name: deploy, groups: www-data }
    - { name: monitor, groups: www-data, shell: /sbin/nologin }
    - { name: backup, groups: backup }

# 字典循环
- name: 创建数据目录
  file:
    path: "/data/{{ item.key }}"
    state: directory
    owner: "{{ item.value.owner }}"
    mode: "{{ item.value.mode }}"
  loop: "{{ data_dirs | dict2items }}"

# 带过滤的循环
- name: 仅在磁盘使用率超阈值的服务器上告警
  debug:
    msg: "磁盘告警: {{ item.mount }} 使用率 {{ item.use_percent }}"
  loop: "{{ ansible_mounts }}"
  when: item.use_percent | regex_replace('%','') | int > 80

# 并行循环（Ansible 2.12+）
- name: 批量下载文件
  get_url:
    url: "{{ item }}"
    dest: "/tmp/{{ item | basename }}"
  loop: "{{ file_list }}"
  throttle: 5  # 限制并发数为 5

五、错误处理

5.1 block/rescue/always

这是 Ansible 的 try-catch-finally，生产环境必备：

---
- name: 数据库迁移（带回滚）
  block:
    - name: 备份当前数据库
      command: "pg_dump {{ db_name }} > /backup/{{ db_name }}_{{ ansible_date_time.epoch }}.sql"
      register: backup_result

    - name: 执行数据库迁移
      command: "psql -d {{ db_name }} -f /tmp/migration.sql"
      register: migrate_result

  rescue:
    - name: 迁移失败，恢复数据库
      command: "psql -d {{ db_name }} < /backup/{{ db_name }}_{{ ansible_date_time.epoch }}.sql"
      when: backup_result is succeeded

    - name: 发送失败告警
      mail:
        to: ops@example.com
        subject: "[严重] 数据库迁移失败 - {{ inventory_hostname }}"
        body: "迁移脚本执行失败，已自动回滚。请检查 /tmp/migration.sql"

  always:
    - name: 清理临时文件
      file:
        path: /tmp/migration.sql
        state: absent

5.2 failed_when 自定义失败条件

---
- name: 执行健康检查脚本
  command: /opt/app/health_check.sh
  register: health_result
  changed_when: false
  failed_when:
    - health_result.rc != 0
    - "'CRITICAL' in health_result.stdout"

- name: 检查应用启动日志
  shell: "tail -100 {{ app_log_dir }}/startup.log"
  register: startup_log
  changed_when: false
  failed_when: startup_log.rc != 0 or "'FATAL' in startup_log.stdout"

- name: 编译项目
  command: make build
  register: build_result
  failed_when: build_result.rc != 0 or "'error' in build_result.stderr | lower"

5.3 changed_when 控制变更状态

非 Ansible 模块的命令默认都标记为 changed，需要手动控制：

---
- name: 检查配置是否需要更新
  shell: diff /tmp/nginx.conf.new /etc/nginx/nginx.conf
  register: config_diff
  changed_when: false
  failed_when: false

- name: 更新 Nginx 配置
  copy:
    src: /tmp/nginx.conf.new
    dest: /etc/nginx/nginx.conf
    remote_src: true
  when: config_diff.rc != 0
  notify: reload nginx

六、动态 Inventory

6.1 为什么需要动态 Inventory

静态 hosts 文件适合物理服务器固定的场景。在云环境或 K8s 中，节点随时增减，静态文件无法跟上变化。动态 Inventory 通过脚本实时查询云 API 返回主机列表。

6.2 AWS 动态 Inventory

# ansible.cfg
[defaults]
inventory = inventory/aws_ec2.yml
host_key_checking = False

---
# inventory/aws_ec2.yml
plugin: aws_ec2
regions:
  - cn-north-1
  - cn-northwest-1
keyed_groups:
  - key: tags.Environment
    prefix: env
  - key: tags.Role
    prefix: role
  - key: tags.Stack
    prefix: stack
filters:
  instance-state-name: running
  tag:Project: production-platform
compose:
  ansible_host: private_ip_address
  ansible_user: "'ec2-user'"
host_vars:
  ansible_python_interpreter: /usr/bin/python3

执行验证：

# 列出所有主机
ansible-inventory -i inventory/aws_ec2.yml --list

# 按组查看
ansible-inventory -i inventory/aws_ec2.yml --graph

# 查看主机详情
ansible-inventory -i inventory/aws_ec2.yml --host 10.0.1.21

6.3 自定义动态 Inventory 脚本

当现有插件无法满足时，可以用任何语言编写自定义脚本，只需输出 JSON：

#!/usr/bin/env python3
"""自定义动态 Inventory：从 CMDB API 获取主机列表"""
import json
import requests
import sys

def get_inventory():
    resp = requests.get(
        "https://cmdb.internal/api/v1/hosts",
        headers={"Authorization": "Bearer ${CMDB_TOKEN}"},
        params={"env": "production", "status": "active"},
        timeout=10
    )
    hosts = resp.json()

    inventory = {"_meta": {"hostvars": {}}}
    
    for host in hosts:
        group = host.get("role", "ungrouped")
        if group not in inventory:
            inventory[group] = {"hosts": [], "vars": {}}
        
        inventory[group]["hosts"].append(host["hostname"])
        inventory["_meta"]["hostvars"][host["hostname"]] = {
            "ansible_host": host["ip"],
            "ansible_port": host.get("ssh_port", 22),
            "datacenter": host["datacenter"],
        }
    
    return inventory

if __name__ == "__main__":
    # 支持 --list 和 --host 参数
    if len(sys.argv) == 2 and sys.argv[1] == "--list":
        print(json.dumps(get_inventory(), indent=2))
    elif len(sys.argv) == 3 and sys.argv[1] == "--host":
        print(json.dumps({}))

七、Ansible Vault

7.1 加密敏感数据

生产环境中的密码、密钥、证书不能明文存储在 Git 仓库。Ansible Vault 提供了透明的加密机制：

# 创建加密变量文件
ansible-vault create inventory/production/group_vars/vault.yml

# 加密已有文件
ansible-vault encrypt inventory/production/group_vars/secrets.yml

# 编辑加密文件（自动解密→编辑→加密）
ansible-vault edit inventory/production/group_vars/vault.yml

# 查看加密文件内容
ansible-vault view inventory/production/group_vars/vault.yml

# 修改密码
ansible-vault rekey inventory/production/group_vars/vault.yml

7.2 多密码文件管理

生产环境通常有多套 Vault 密码（开发/测试/生产），用密码文件管理更安全：

# ansible.cfg
[defaults]
vault_password_file = /etc/ansible/.vault_pass

# 为不同环境使用不同密码文件
ansible-playbook site.yml -i inventory/production/ \
  --vault-password-file /etc/ansible/.vault_prod

# 多密码文件（用于合并不同来源的加密变量）
ansible-playbook site.yml \
  --vault-password-file /etc/ansible/.vault_prod \
  --vault-password-file /etc/ansible/.vault_common

7.3 加密部分变量

不必加密整个文件，可以只加密敏感字段：

---
# group_vars/all.yml（混合文件，部分加密）
db_host: 10.0.1.30
db_port: 5432
db_name: production_db
# 以下内容通过 ansible-vault encrypt_string 加密
db_password: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          62313365393831383739656138356465396664663339383738383338666637353766623638666139
          ...
api_secret: !vault |
          $ANSIBLE_VAULT;1.1;AES256
          37343734393438363531346337343363636136623633326432353062353366333062393733336532
          ...

# 加密单个变量值
ansible-vault encrypt_string 'MySecretPassword123' --name 'db_password'

# 加密并输出到指定文件
ansible-vault encrypt_string 'sk-xxxxx' --name 'api_key' >> group_vars/all.yml

八、Galaxy 生态

8.1 使用社区角色

---
# requirements.yml - 声明角色依赖
roles:
  - name: geerlingguy.nginx
    version: 3.1.0
  - name: geerlingguy.mysql
    version: 4.3.0
  - name: cloudalchemy.node_exporter
    version: 2.0.0
collections:
  - name: community.general
    version: ">=6.0.0"
  - name: ansible.posix
    version: ">=1.5.0"
  - name: community.docker
    version: ">=3.0.0"

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

# 安装到指定路径
ansible-galaxy install -r requirements.yml -p roles/

8.2 评估社区角色

不要盲目引入社区角色，评估清单：

评估维度检查点方法
活跃度最近提交时间、Issue 响应速度查看 GitHub 仓库
星标数社区认可度Galaxy 页面
测试覆盖是否有 Molecule 测试查看仓库 molecule/ 目录
兼容性支持的 OS 和 Ansible 版本查看 meta/main.yml
安全性是否有可疑脚本、硬编码密钥审查 tasks/ 内容
变量设计默认值是否合理、是否有文档查看 defaults/main.yml

生产建议：对关键角色 fork 到自己的仓库，锁定版本并做安全审查后使用。不要直接依赖上游最新 tag。

九、调试技巧

9.1 常用调试方法

# 1. 检查语法
ansible-playbook site.yml --syntax-check

# 2. Dry-run 模式（只看会做什么，不实际执行）
ansible-playbook site.yml --check --diff

# 3. 指定步骤执行
ansible-playbook site.yml --step

# 4. 从指定 task 开始执行
ansible-playbook site.yml --start-at-task="install nginx"

# 5. 详细输出
ansible-playbook site.yml -vvv  # -v 到 -vvvv 四个级别

# 6. 列出所有主机和 task
ansible-playbook site.yml --list-hosts
ansible-playbook site.yml --list-tasks
ansible-playbook site.yml --list-tags

9.2 debug 模块

---
# 打印变量值
- name: 调试 - 显示主机信息
  debug:
    var: ansible_default_ipv4

# 打印自定义消息
- name: 调试 - 显示执行进度
  debug:
    msg: |
      当前主机: {{ inventory_hostname }}
      操作系统: {{ ansible_distribution }} {{ ansible_distribution_version }}
      内存: {{ ansible_memtotal_mb }}MB
      磁盘: {{ ansible_mounts | map(attribute='mount') | list }}      

# 条件调试
- name: 调试 - 仅在 verbose 模式输出
  debug:
    var: result
  when: ansible_verbosity >= 2

# 使用 verbosity 控制输出级别
- name: 调试 - 详细输出
  debug:
    var: complex_data_structure
  verbosity: 2  # 需要 -vv 才会显示

9.3 捕获执行结果

---
- name: 执行脚本并捕获完整输出
  shell: /opt/app/deploy.sh 2>&1
  register: deploy_output
  changed_when: deploy_output.rc == 0

- name: 输出执行结果
  debug:
    msg: "{{ deploy_output.stdout_lines }}"

- name: 检查执行结果
  assert:
    that:
      - deploy_output.rc == 0
      - "'SUCCESS' in deploy_output.stdout"
    fail_msg: "部署失败，输出:\n{{ deploy_output.stderr }}"

十、性能优化

10.1 SSH 连接优化

SSH 连接是 Ansible 最大的性能瓶颈，优化效果立竿见影：

# ansible.cfg
[defaults]
# SSH 管道模式，避免反复建立连接
pipelining = true
# 并发数
forks = 50
# SSH 超时
timeout = 30
# 持久化连接
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o ServerAliveInterval=30
# 事实缓存（避免每次收集 facts）
gathering = smart
fact_caching = redis
fact_caching_timeout = 86400
fact_caching_connection = localhost:6379:0

10.2 事实缓存

每次 Playbook 执行前，Ansible 默认会对所有目标主机执行 setup 模块收集 facts，这在数百台主机时非常耗时。启用事实缓存后，facts 存入 Redis/JSON 文件，后续执行直接读取：

# 方案一：Redis 缓存（推荐，多机共享）
[defaults]
fact_caching = redis
fact_caching_timeout = 86400
fact_caching_connection = localhost:6379:0

# 方案二：JSON 文件缓存（单机使用）
[defaults]
fact_caching = jsonfile
fact_caching_timeout = 86400
fact_caching_connection = /tmp/ansible_facts

10.3 按需收集 facts

---
# 完全跳过 facts 收集
- name: 快速任务（无需 facts）
  hosts: all
  gather_facts: false
  tasks:
    - name: 重启服务
      systemd:
        name: nginx
        state: restarted

# 只收集需要的 facts
- name: 精确收集 facts
  hosts: all
  gather_facts: true
  module_defaults:
    setup:
      gather_subset:
        - "!all"
        - "network"
        - "hardware"

10.4 性能对比

以下是一组 200 台主机执行简单任务的实测对比：

优化措施耗时提升幅度
默认配置320s基准
pipelining=true180s44%
forks=50120s63%
fact_caching=redis65s80%
gather_facts=false45s86%
全部优化叠加28s91%

10.5 异步任务

长时间运行的任务使用 async 避免阻塞：

---
- name: 大文件下载（异步）
  get_url:
    url: "https://releases.example.com/data-{{ version }}.tar.gz"
    dest: /tmp/data.tar.gz
  async: 3600          # 超时时间 1 小时
  poll: 0              # 不等待，立即返回
  register: download_task

- name: 执行其他任务
  debug:
    msg: "下载在后台进行，继续其他工作..."

- name: 等待下载完成
  async_status:
    jid: "{{ download_task.ansible_job_id }}"
  register: job_result
  until: job_result.finished
  retries: 120
  delay: 30

十一、生产级配置模板

11.1 完整 ansible.cfg

# ansible.cfg - 生产级配置
[defaults]
# 基础配置
inventory = inventory/production
roles_path = roles
collections_path = collections
host_key_checking = False
timeout = 30
forks = 50

# 输出
stdout_callback = yaml
callbacks_enabled = timer, profile_tasks, profile_roles
callbacks_whitelist = timer, profile_tasks

# SSH 优化
pipelining = true
ssh_args = -o ControlMaster=auto -o ControlPersist=60s -o ServerAliveInterval=30

# 事实缓存
gathering = smart
fact_caching = redis
fact_caching_timeout = 86400
fact_caching_connection = localhost:6379:0

# Vault
vault_password_file = /etc/ansible/.vault_pass

# 错误处理
any_errors_fatal = true
max_fail_percentage = 10

# 角色
private_role_vars = true
allow_world_readable_tmpfiles = false

[privilege_escalation]
become = true
become_method = sudo

[ssh_connection]
transfer_method = smart
retries = 3

11.2 Molecule 测试框架

为角色编写自动化测试，确保变更不会引入回归：

---
# roles/nginx/molecule/default/converge.yml
- name: 测试 Nginx 角色
  hosts: all
  become: true
  roles:
    - role: nginx

# roles/nginx/molecule/default/verify.yml
- name: 验证 Nginx 安装
  hosts: all
  tasks:
    - name: 检查 nginx 服务状态
      service:
        name: nginx
        state: started
        enabled: true
      check_mode: true
      register: svc

    - name: 断言服务已启动
      assert:
        that:
          - not svc.changed

    - name: 检查端口监听
      wait_for:
        port: 80
        timeout: 5

    - name: HTTP 健康检查
      uri:
        url: http://localhost
        status_code: 200

# 运行测试
cd roles/nginx
molecule test

# 使用 Docker 驱动
molecule test --driver-name docker

总结

生产级 Ansible Playbook 的核心在于工程化思维：不是把命令堆进 YAML 就行，而是要在结构组织、变量管理、错误处理、性能优化、测试覆盖五个维度系统设计。回顾本文的要点：

  1. 结构优先：标准目录布局 + 角色化拆分 + 入口文件清晰，是可维护的基础
  2. 变量分层：defaults 给安全默认值、group_vars 管环境差异、extra vars 做临时覆盖，优先级要烂熟于心
  3. 幂等至上：每个 task 都要问"再跑一次会怎样"，善用 lineinfile、blockinfile、assert
  4. 错误可恢复：block/rescue 是 Ansible 的异常处理利器，关键操作必须有回滚方案
  5. 安全闭环：Vault 加密敏感数据、动态 Inventory 适配云环境、Galaxy 依赖要锁版本
  6. 性能可控：pipelining + forks + fact_caching 三板斧，200 台主机从 5 分钟压到 30 秒
  7. 测试驱动：Molecule 让角色变更可验证，CI 集成让 Playbook 质量可度量

Ansible 的价值不在于替代手动操作，而在于让基础设施配置可版本化、可审查、可复现。当你能把几百台服务器的配置变成一个 git diff 就能审查的 PR 时，运维才算真正进入了工程化阶段。

参考资料与致谢

本文在撰写过程中参考了以下资料，感谢原作者的贡献：

  1. Ansible 官方好的实践 — Ansible 社区，参考了Ansible 官方好的实践相关内容