Ansible Playbook 自动化部署工具集

一个专业的 Ansible Playbook 工具集，用于自动化部署和配置管理。

📋 目录

• 功能特性
• 项目结构
• 快速开始
• Playbook 列表
• 文档
• 贡献指南

✨ 功能特性

• 🚀 Nezha Agent 管理 - 自动化更新 Nezha Agent 配置
• ⚙️ XXXigCC 部署 - 自动化安装和卸载 XXXigCC
• 📝 Journald 配置 - 系统日志服务配置管理
• 🔒 安全性 - 内置配置备份和验证机制
• 📦 模块化设计 - 每个 Playbook 专注于特定任务
• 🔧 高度可配置 - 灵活的参数化配置

📁 项目结构

ansible-playbook/
├── README.md                      # 项目主文档
├── docs/                          # 详细文档目录
│   ├── nezha_update_secret_README.md
│   ├── QUICKSTART_nezha.md
│   └── xxxigcc_update_pool_url_README.md
├── examples/                      # 示例配置文件
│   ├── inventory.example.ini      # Inventory 示例
│   ├── nezha_vars.example.yml     # Nezha 变量示例
│   ├── xxxigcc_vars.example.yml   # XXXigCC 变量示例
│   ├── xxxigcc_update_pool_url_vars.example.yml  # XXXigCC Pool URL 更新变量示例
│   └── journald_vars.example.yml  # Journald 变量示例
├── llmdoc/                        # LLM 文档系统
│   ├── index.md                   # 文档索引
│   ├── overview/                  # 项目概览
│   ├── guides/                    # 操作指南
│   ├── architecture/              # 架构文档
│   └── reference/                 # 参考文档
├── journald_configure.yml         # Journald 配置 Playbook
├── nezha_update_secret.yml        # Nezha Agent 更新 Playbook
├── nezha_update_secret_v2.yml     # Nezha Agent 更新 Playbook (备选)
├── xxxigcc_install.yaml           # XXXigCC 安装 Playbook
├── xxxigcc_uninstall.yaml         # XXXigCC 卸载 Playbook
└── xxxigcc_update_pool_url.yaml   # XXXigCC Pool URL 更新 Playbook

🚀 快速开始

1. 准备环境

确保已安装 Ansible:

# macOS
brew install ansible

# Ubuntu/Debian
sudo apt update && sudo apt install ansible

# CentOS/RHEL
sudo yum install ansible

# 验证安装
ansible --version

2. 配置 Inventory

# 复制示例文件
cp examples/inventory.example.ini inventory.ini

# 编辑文件，添加你的服务器信息
vim inventory.ini

3. 测试连接

ansible all -i inventory.ini -m ping

4. 执行 Playbook

# 示例：更新 Nezha Agent
ansible-playbook nezha_update_secret.yml \
  -i inventory.ini \
  -e "client_secret=YourNewSecret"

📚 Playbook 列表

Nezha Agent 管理

Playbook	功能	文档
nezha_update_secret.yml	更新 Nezha Agent client_secret	📖 详细文档
nezha_update_secret_v2.yml	更新 Nezha Agent (备选方案)	📖 详细文档

快速使用:

ansible-playbook nezha_update_secret.yml \
  -i inventory.ini \
  -e "client_secret=新密钥"

📘 快速开始指南

---

XXXigCC 部署管理

Playbook	功能	参数示例
xxxigcc_install.yaml	安装 XXXigCC	📄 示例
xxxigcc_uninstall.yaml	卸载 XXXigCC	-
xxxigcc_update_pool_url.yaml	更新 Pool URL	📄 示例

快速使用:

# 安装
ansible-playbook xxxigcc_install.yaml \
  -i inventory.ini \
  -e @examples/xxxigcc_vars.example.yml

# 更新 Pool URL
ansible-playbook xxxigcc_update_pool_url.yaml \
  -i inventory.ini \
  -e "new_url=xxxigcc-proxy.ca.vvvo.net:8443"

# 卸载
ansible-playbook xxxigcc_uninstall.yaml -i inventory.ini

📘 Pool URL 更新详细文档

---

系统配置管理

Playbook	功能	参数示例
journald_configure.yml	配置 systemd-journald	📄 示例

快速使用:

ansible-playbook journald_configure.yml -i inventory.ini

📖 文档

主要文档

• 📘 Nezha Agent 更新完整文档
• 🚀 Nezha Agent 快速开始
• 📄 示例文件说明

LLM 文档系统

本项目包含完整的 LLM 友好文档系统，位于 llmdoc/ 目录:

• 📑 文档索引 - 所有文档的入口
• 📋 项目概览 - 项目简介和架构
• 📚 操作指南 - 各种操作的详细指南
• 🏗️ 架构文档 - 系统架构和设计
• 📖 参考文档 - API 和配置参考

🔒 安全性

本项目的所有 Playbook 都遵循安全最佳实践:

• ✅ 自动备份配置文件
• ✅ 参数验证和错误处理
• ✅ 可选的旧值验证机制
• ✅ 幂等操作，可安全重复执行

建议使用 Ansible Vault 保护敏感信息:

# 加密变量文件
ansible-vault encrypt vars.yml

# 使用加密文件
ansible-playbook playbook.yml -e @vars.yml --ask-vault-pass

🛠️ 开发与维护

编码规范

• 使用 2 空格缩进
• 变量命名使用 snake_case
• 每个任务添加描述性的 name
• 使用 ansible.builtin 模块
• 添加适当的注释说明

详见: 编码规范

最佳实践

• 保持 Playbook 模块化和单一职责
• 使用变量实现参数化配置
• 使用 handler 管理服务重启
• 添加充分的任务输出和调试信息

详见: Ansible 最佳实践

🤝 贡献指南

欢迎贡献！请遵循以下步骤:

1. Fork 本项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m '添加某个特性')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

提交规范

参考: Git 提交规范

📋 待办事项

• 添加更多系统配置 Playbook
• 支持更多 Linux 发行版
• 添加 CI/CD 集成示例
• 完善错误处理机制

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件

🔗 相关链接

• Ansible 官方文档
• Ansible 最佳实践

💬 支持与反馈

如有问题或建议，请:

• 提交 Issue
• 发起 Pull Request

---

最后更新: 2024年12月16日