Ansible Roles目录结构必须严格标准化，因其依赖硬编码路径识别组件：tasks/main.yml为唯一入口，handlers/main.yml等需精确命名，否则静默跳过；变量优先级为defaults＜vars＜playbook vars，模板文件须以.j2结尾，调用时需显式传参或声明依赖。
Ansible 用 Roles 模块化管理庞大运维代码，核心不是“能不能”，而是“目录结构必须严格对、变量加载顺序不能乱、调用时参数覆盖要留心”——错一个环节，整个角色就 silently 失效。
roles 目录结构为什么必须一模一样？
Ansible 不靠配置识别 role，只靠约定俗成的路径。它在 roles/xxx/ 下硬编码查找 tasks/main.yml、handlers/main.yml 等固定路径。一旦写成 tasks/deploy.yml 或漏掉 main.yml，Ansible 就直接跳过该目录，不报错也不提示。
-
tasks/main.yml是唯一入口，其他.yml文件（如install.yml）必须由它显式include_tasks或import_tasks，不能指望自动加载 -
defaults/main.yml和vars/main.yml都叫main.yml，但优先级不同：前者可被后者覆盖，后者又可被 playbook 中vars:覆盖 -
templates/下的文件名必须带.j2后缀，否则template模块会当成普通文件报错：ERROR! template not found
怎么在 playbook 中安全调用并传参？
直接写 roles: - nginx 最省事，但无法改端口、关 SSL、换用户——这种“裸调用”只适合验证角色本身是否能跑通。
- 需要定制就用字典语法：
- role: nginx换成- role: nginx; vars: { nginx_port: 8080, nginx_user: "www" } - 避免在
vars:里写复杂逻辑，比如nginx_conf_path: "{{ '/etc/nginx' if ansible_distribution == 'CentOS' else '/usr/local/etc/nginx' }}"—— 这种判断应放在 role 内部vars/main.yml或defaults/main.yml中，保持调用层干净 - 如果多个 role 共享同一组变量（如
app_name），别在每个- role:下重复写vars:，统一提到 playbook 顶层vars:块里，让所有 role 自动继承
handlers 触发失败的常见原因
写好 notify: restart nginx 却没重启服务？大概率是 handlers 名称没对上，或者任务没真正“变更”状态。
-
handlers/main.yml中定义的 name 必须和notify:字符串**完全一致**，包括空格和大小写：notify: Restart Nginx对不上- name: restart nginx - 只有任务返回
changed: true才会触发 handler。用copy拷配置文件时，如果内容没变，changed就是false，handler 不执行。加force: true或改用template（总渲染新内容）可绕过 - handler 只在当前 play 结束时批量执行一次，不会每 notify 一次就跑一遍。想立刻生效？得拆成两个 play，把 handler 放到第二个 play 的
handlers:块里
跨环境部署时变量优先级怎么不出错？
开发环境用 8080 端口，生产环境必须用 443——这种差异靠变量覆盖，但顺序错了就会“明明写了却没生效”。
- 最低优先级：role 内
defaults/main.yml（适合设兜底值，比如python_interpreter: /usr/bin/python3） - 中等优先级：role 内
vars/main.yml（适合设该 role 强依赖的值，比如mysql_version: "14"） - 最高优先级：playbook 中
vars:或命令行--extra-vars（适合环境差异化配置） - 注意：
group_vars/prod.yml优先级比 role 内vars/高，但比 playbook 顶层vars:低；别指望 inventory 变量能覆盖 playbook 里明写的vars:
最易被忽略的一点：Roles 之间如果有依赖（比如 app-deploy 依赖 python-runtime），必须在 meta/main.yml 里声明 dependencies:，而不是靠 playbook 里写先后顺序——否则 python-runtime 的变量根本不会提前加载进 app-deploy 的上下文。
