ansible-playbook/llmdoc/architecture/ansible-project-structure.md

Ansible 项目架构设计

1. 身份与目的

• 项目定位：自动化安装和配置系统组件的 Ansible Playbook 集
• 主要功能：提供模块化、可配置的安装和卸载流程

2. 核心组件

• xxxigcc_install.yaml：系统组件安装主 Playbook
• xxxigcc_uninstall.yaml：系统组件卸载 Playbook
• journald_configure.yml：日志系统配置 Playbook
• xxxigcc_update_pool_url.yaml：Pool URL 更新 Playbook

3. 执行流程（LLM 检索映射）

安装流程

1. 参数准备：ansible.builtin.set_fact 动态构建安装参数
2. 下载脚本：ansible.builtin.get_url 获取安装脚本
3. 执行安装：ansible.builtin.shell 运行安装命令
4. 结果记录：ansible.builtin.debug 输出执行日志
5. 清理资源：ansible.builtin.file 移除临时文件

Pool URL 更新流程

1. 配置验证：使用 jq 验证 JSON 配置
2. 文件备份：创建 config.json 备份
3. URL 更新：通过 jq 修改 pools[0].url
4. 日志清理：清理 /var/log/xxxigcc 目录
5. 服务重启：重启 xxxigcc-daemon.service

4. 设计原则

• 高度参数化：支持丰富的可选配置开关
• 模块解耦：每个 Playbook 专注单一功能
• 动态命令构建：根据参数灵活生成执行命令

5. 关键设计模式

• 特权执行：使用 become: yes
• 条件渲染：{{ condition ? value : '' }}
• 临时文件管理
• 幂等性：确保多次执行不会产生意外后果

6. Ansible 版本兼容性

版本要求

• 最低版本：Ansible 2.14
• 移除的特性：command 模块的 warn: false 参数

版本兼容性调整

• 模块替换：

  • 使用 ansible.builtin.shell 替代带有 warn: false 的 command 模块
  • 确保与最新 Ansible 版本兼容

• 兼容性检查：

  1. 使用 ansible_version 变量进行版本检查
  2. 动态选择兼容的执行方式
  3. 提供明确的版本要求和迁移指南

安全与性能考虑

• 减少对已废弃特性的依赖
• 保持代码的向前兼容性
• 提高 Playbook 的可移植性

7. 新增 Playbook 设计特点

• 条件更新：支持可选的 old_url 验证
• 配置安全：自动备份原始配置
• 错误处理：完整的配置和服务验证机制