2. 角色目录结构深度解析：tasks、handlers、templates、files、vars、defaults、meta 的作用与规范

Ansible 角色（Role）是内容复用的核心单元。一个标准化的角色目录结构，不仅决定了 Playbook 的可读性与可维护性，更是实现“环境一致性基线核验”的物理基础。本章将逐层剖析每个子目录的设计意图、使用规范与常见陷阱。

2.1 标准角色目录树

执行 ansible-galaxy init role_name 命令后，Ansible 会自动生成以下目录骨架：

role_name/
├── tasks/            # 主任务列表（必须）
│   └── main.yml
├── handlers/         # 处理器，由任务通知触发
│   └── main.yml
├── templates/        # Jinja2 模板文件
│   └── *.j2
├── files/            # 静态文件，直接复制到目标主机
│   └── *
├── vars/             # 高优先级变量（覆盖 defaults）
│   └── main.yml
├── defaults/         # 默认变量（最低优先级）
│   └── main.yml
├── meta/             # 角色依赖与元数据
│   └── main.yml
└── README.md         # 角色说明文档（推荐）

2.2 各目录深度解析

2.2.1 tasks/ —— 角色执行引擎

tasks/main.yml 是角色被调用时的唯一入口。Ansible 按顺序执行该文件中的任务列表。规范要求：

• 单一职责：一个角色只完成一个功能维度（如安装 Nginx、配置防火墙）。
• 任务拆分：超过 15 个任务时，应使用 include_tasks 或 import_tasks 拆分到子文件（如 install.yml、configure.yml）。
• 标签（tags）：每个关键任务必须打标签，便于选择性执行。

# tasks/main.yml 示例
---
- name: 安装 Nginx 软件包
  ansible.builtin.package:
    name: nginx
    state: present
  tags: [nginx, install]

- name: 部署 Nginx 主配置
  ansible.builtin.template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  notify: restart nginx
  tags: [nginx, config]

- name: 启用并启动 Nginx 服务
  ansible.builtin.service:
    name: nginx
    enabled: true
    state: started
  tags: [nginx, service]

2.2.2 handlers/ —— 事件驱动的响应器

Handlers 是特殊的任务，仅在被 notify 触发且任务状态为 changed 时执行。典型场景：配置文件变更后重启服务。

# handlers/main.yml
---
- name: restart nginx
  ansible.builtin.service:
    name: nginx
    state: restarted
  listen: "restart web services"

2.2.3 templates/ —— 动态配置生成器

存放 Jinja2 模板文件（扩展名 .j2），在任务执行时渲染为具体配置文件。模板内可使用变量、条件、循环。

{# templates/nginx.conf.j2 片段 #}
server {
    listen       {{ nginx_port | default(80) }};
    server_name  {{ server_name }};
    root         {{ web_root }};
    index        index.html index.htm;
}

2.2.4 files/ —— 静态文件仓库

存放不需要变量渲染的静态文件（如二进制包、证书、字体文件）。使用 copy 模块直接传输。

• 权限管理：在任务中显式指定 owner、group、mode。
• 大文件处理：超过 10MB 的文件建议使用 get_url 或对象存储，避免角色体积膨胀。

2.2.5 vars/ 与 defaults/ —— 变量优先级博弈

这是角色设计中最重要的概念之一。变量优先级从低到高为：

1. 角色 defaults（最低优先级）
2. Playbook 变量
3. Inventory 变量
4. 角色 vars（高优先级）
5. extra_vars（最高优先级）

# defaults/main.yml —— 用户可覆盖
---
nginx_port: 80
nginx_user: nginx
log_level: warn

# vars/main.yml —— 角色内部固定
---
__nginx_service_name: nginx
__nginx_default_conf_dir: /etc/nginx/conf.d

2.2.6 meta/ —— 角色依赖与元数据

meta/main.yml 声明角色的依赖关系、支持的平台、作者信息。Ansible 在执行角色前会先递归执行所有依赖角色。

# meta/main.yml
---
galaxy_info:
  author: DevOps Team
  description: 标准 Nginx 部署角色
  company: Example Corp
  license: MIT
  min_ansible_version: "2.14"
  platforms:
    - name: EL
      versions:
        - "8"
        - "9"
    - name: Ubuntu
      versions:
        - "20.04"
        - "22.04"
  galaxy_tags:
    - nginx
    - web
    - reverse-proxy

dependencies:
  - role: common
    vars:
      common_timezone: "Asia/Shanghai"
  - role: epel
    when: ansible_os_family == "RedHat"

2.3 目录规范与基线核验清单

在自动化运维体系中，角色目录结构必须纳入代码审查与 CI 流水线。以下为推荐基线核验项：

2.4 最佳实践与常见误区

• ✅ 正确做法： 将操作系统差异封装在 vars/ 中，通过 ansible_os_family 条件加载不同变量文件。
• ❌ 常见误区： 在 tasks/ 中硬编码路径或端口，应统一引用 defaults/ 变量。
• ✅ 正确做法： 使用 include_vars 按环境加载敏感变量（如密码），避免将明文密码提交到版本库。
• ❌ 常见误区： 在 handlers/ 中编写复杂逻辑，handler 应保持轻量，仅执行重启/重载操作。
• ✅ 正确做法： 在 meta/main.yml 中声明所有依赖角色及其版本范围，确保环境一致性。