Ansible Role 通过标准化的目录结构将任务、变量、文件等模块化，是实现代码复用和维护的核心方式，适合中大型自动化场景。

命令速用版

# 初始化角色结构
ansible-galaxy init <role_name>

# 查看角色目录树
tree <role_name>

为什么会这样

Ansible 在设计 Role 时约定了特定的目录名称和文件加载顺序。当 Playbook 调用某个 Role 时，系统会自动在 roles 目录下查找对应文件夹，并默认加载 tasks/main.yml、vars/main.yml 等文件。这种机制让逻辑、数据和文件分离，避免了将所有代码写在一个大文件里，便于单独测试和版本控制。

分步处理

1. 配置 roles 路径

在 ansible.cfg 中确认 roles_path，默认通常为 /etc/ansible/roles，也可以自定义。

grep '^roles_path' /etc/ansible/ansible.cfg

2. 创建角色目录

推荐使用命令自动生成，包含 defaults、files、handlers、meta、tasks、templates、tests、vars 等标准子目录。

cd /etc/ansible/roles
ansible-galaxy init my_role

3. 编写核心文件

在 tasks/main.yml 中写任务逻辑，templates 放 Jinja2 模板，files 放静态文件，vars 或 defaults 定义变量。以下是具体示例：

defaults/main.yml (默认变量，优先级低):

---
nginx_port: 80
nginx_package: nginx

tasks/main.yml (任务逻辑):

---
- name: Install nginx
  apt:
    name: "{{ nginx_package }}"
    state: present

- name: Deploy config
  template:
    src: nginx.conf.j2
    dest: /etc/nginx/nginx.conf
  notify: restart nginx

templates/nginx.conf.j2 (模板示例):

server {
    listen {{ nginx_port }};
    server_name localhost;
}

4. 在 Playbook 中调用

---
- hosts: all
  roles:
    - my_role

怎么验证是否生效

使用 `--check` 参数模拟运行，观察是否有报错；使用 `--list-tasks` 查看加载的任务列表。

ansible-playbook site.yml `--check`
ansible-playbook site.yml `--list-tasks`

执行后登录目标主机检查服务状态或文件是否存在。

常见坑

1. 变量优先级混淆：vars 目录下的变量优先级高于 defaults，覆盖时需留意。

2. 缺少 main.yml：tasks、handlers 等目录必须包含 main.yml 才能被自动识别。

3. 路径引用错误：在模板或 copy 任务中引用 files 或 templates 目录文件时，只需写相对文件名，无需写完整路径。

参考来源

• Ansible 官方文档：Working With Playbooks - Roles
• Ansible 官方文档：Creating Roles