添加 Nezha Agent 管理功能和完整文档系统
- 新增 Nezha Agent client_secret 更新 playbook（两种实现方案） - 建立三层文档架构：docs/（用户文档）、examples/（配置示例）、llmdoc/（技术文档） - 添加项目主 README.md 和配置示例文件 - 初始化 .gitignore 保护敏感信息
This commit is contained in:
Wang Defa
244
README.md
Normal file
244
README.md
Normal file
@@ -0,0 +1,244 @@
|
||||
# Ansible Playbook 自动化部署工具集
|
||||
|
||||
[](https://www.ansible.com/)
|
||||
[](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
|
||||
├── examples/ # 示例配置文件
|
||||
│ ├── inventory.example.ini # Inventory 示例
|
||||
│ ├── nezha_vars.example.yml # Nezha 变量示例
|
||||
│ ├── xxxigcc_vars.example.yml # XXXigCC 变量示例
|
||||
│ └── 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
|
||||
```
|
||||
|
||||
## 🚀 快速开始
|
||||
|
||||
### 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 | - |
|
||||
|
||||
**快速使用:**
|
||||
```bash
|
||||
# 安装
|
||||
ansible-playbook xxxigcc_install.yaml \
|
||||
-i inventory.ini \
|
||||
-e @examples/xxxigcc_vars.example.yml
|
||||
|
||||
# 卸载
|
||||
ansible-playbook xxxigcc_uninstall.yaml -i inventory.ini
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 系统配置管理
|
||||
|
||||
| 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日
|
||||
Reference in New Issue
Block a user