ansible-playbook/README.md

# Ansible Playbook 自动化部署工具集

[![Ansible](https://img.shields.io/badge/ansible-%3E%3D2.9-blue.svg)](https://www.ansible.com/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

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

## 📋 目录

- [功能特性](#功能特性)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [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:

```bash
# macOS
brew install ansible

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

# CentOS/RHEL
sudo yum install ansible

# 验证安装
ansible --version
```

### 2. 配置 Inventory

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

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

### 3. 测试连接

```bash
ansible all -i inventory.ini -m ping
```

### 4. 执行 Playbook

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

## 📚 Playbook 列表

### Nezha Agent 管理

| Playbook | 功能 | 文档 |
|----------|------|------|
| [nezha_update_secret.yml](nezha_update_secret.yml) | 更新 Nezha Agent client_secret | [📖 详细文档](docs/nezha_update_secret_README.md) |
| [nezha_update_secret_v2.yml](nezha_update_secret_v2.yml) | 更新 Nezha Agent (备选方案) | [📖 详细文档](docs/nezha_update_secret_README.md) |

**快速使用:**
```bash
ansible-playbook nezha_update_secret.yml \
  -i inventory.ini \
  -e "client_secret=新密钥"
```

📘 [快速开始指南](docs/QUICKSTART_nezha.md)

---

### XXXigCC 部署管理

| Playbook | 功能 | 参数示例 |
|----------|------|----------|
| [xxxigcc_install.yaml](xxxigcc_install.yaml) | 安装 XXXigCC | [📄 示例](examples/xxxigcc_vars.example.yml) |
| [xxxigcc_uninstall.yaml](xxxigcc_uninstall.yaml) | 卸载 XXXigCC | - |
| [xxxigcc_update_pool_url.yaml](xxxigcc_update_pool_url.yaml) | 更新 Pool URL | [📄 示例](examples/xxxigcc_update_pool_url_vars.example.yml) |

**快速使用:**
```bash
# 安装
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 更新详细文档](docs/xxxigcc_update_pool_url_README.md)

---

### 系统配置管理

| Playbook | 功能 | 参数示例 |
|----------|------|----------|
| [journald_configure.yml](journald_configure.yml) | 配置 systemd-journald | [📄 示例](examples/journald_vars.example.yml) |

**快速使用:**
```bash
ansible-playbook journald_configure.yml -i inventory.ini
```

## 📖 文档

### 主要文档

- 📘 [Nezha Agent 更新完整文档](docs/nezha_update_secret_README.md)
- 🚀 [Nezha Agent 快速开始](docs/QUICKSTART_nezha.md)
- 📄 [示例文件说明](examples/README.md)

### LLM 文档系统

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

- [📑 文档索引](llmdoc/index.md) - 所有文档的入口
- [📋 项目概览](llmdoc/overview/project-overview.md) - 项目简介和架构
- [📚 操作指南](llmdoc/guides/) - 各种操作的详细指南
- [🏗️ 架构文档](llmdoc/architecture/) - 系统架构和设计
- [📖 参考文档](llmdoc/reference/) - API 和配置参考

## 🔒 安全性

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

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

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

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

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

## 🛠️ 开发与维护

### 编码规范

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

详见: [编码规范](llmdoc/reference/coding-conventions.md)

### 最佳实践

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

详见: [Ansible 最佳实践](llmdoc/guides/ansible-best-practices.md)

## 🤝 贡献指南

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

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

### 提交规范

参考: [Git 提交规范](llmdoc/reference/git-conventions.md)

## 📋 待办事项

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

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

## 🔗 相关链接

- [Ansible 官方文档](https://docs.ansible.com/)
- [Ansible 最佳实践](https://docs.ansible.com/ansible/latest/user_guide/playbooks_best_practices.html)

## 💬 支持与反馈

如有问题或建议，请:
- 提交 [Issue](../../issues)
- 发起 [Pull Request](../../pulls)

---

**最后更新**: 2024年12月16日