当 Playbook 变大后，应按职责拆成 Role，并用 Collection 管理模块、插件和内容依赖。复用不是复制目录，而是定义清晰输入、默认值、依赖和验证方法。
## Role 结构
```text
roles/web/
├── defaults/main.yml
├── tasks/main.yml
├── handlers/main.yml
├── templates/
├── files/
├── vars/main.yml
├── meta/main.yml
└── README.md
```
可被调用者覆盖的值放 defaults；vars 优先级较高，应少用。Role 名称加命名空间，变量如 web_port，避免与其他 Role 冲突。
调用：
```yaml
- hosts: web
roles:
- role: web
vars:
web_port: 8080
```
## Galaxy 与 Collections
使用 requirements 文件锁定依赖版本：
```yaml
collections:
- name: community.general
version: '>=10.0.0,<11.0.0'
roles:
- name: geerlingguy.nginx
version: 3.2.0
```
```bash
ansible-galaxy collection install -r collections/requirements.yml
ansible-galaxy role install -r requirements.yml
```
第三方内容进入生产前要审查源码、维护状态、许可证、依赖和权限，不盲目安装最新版本。
## 测试与质量
- ansible-lint 检查常见问题。
- yamllint 统一格式。
- Molecule 或临时环境进行场景测试。
- CI 执行 syntax、lint、check 和幂等测试。
- 在支持的 ansible-core/Collection 版本矩阵验证。
Ansible Core 版本升级可能改变模板、变量或模块行为，依赖必须锁定并阅读 porting guide。
## 性能优化
先测量慢在哪里：SSH 建连、facts、包管理、模板、网络设备还是外部 API。
常用措施：
- 不需要 facts 的 Play 设置 gather_facts: false，或只收集子集。
- 启用合适的 SSH 连接复用和 pipelining，并评估 sudo 安全策略。
- 用 forks 提高并发，但受控制节点、网络和目标服务容量限制。
- 使用 async/poll 处理长任务，不占用连接。
- 避免在循环中重复调用包管理器；一次传入列表。
- 缓存动态 Inventory 和 facts，但设置失效时间。
- 使用 strategy 和 serial 匹配风险，不为速度一次改全量。
## 可维护性原则
- 每个任务有说明结果的 name。
- 优先完全限定模块名。
- command/shell 明确 changed_when、failed_when 和 creates/removes。
- 配置模板先 validate。
- 删除重复逻辑，抽成 Role 或 include_tasks。
- 不用 tags 替代清晰的 Playbook 边界。
- README 说明变量、示例、平台和回滚。
## 生产治理
自动化仓库需要代码评审、分支保护、CI、签名或受控发布。执行平台记录发起人、Inventory、版本、变量和结果。控制节点与自动化凭证按高权限系统保护。
优化的目标不是最短执行时间，而是用可预测、可审计和可回滚的方式管理更多主机。
参考：https://docs.ansible.com/projects/ansible/latest/playbook_guide/playbooks_reuse_roles.html