Remove outdated guides and references related to Ansible best practices, Gitea repository configuration, journald management, and XXXigCC deployment. Introduce a new playbook for reinstalling Nezha Agent, ensuring proper parameter validation and service management. Update documentation to reflect the latest practices and remove deprecated content.

2026-06-29 15:38:00 +08:00
parent 31da18eca6
commit 8f03780bfb
46 changed files with 183 additions and 2560 deletions
@@ -1,255 +1,43 @@
-# Ansible Playbook 自动化部署工具集
+# 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，涵盖 Gitea 软件源配置、日志管理、监控 Agent 与 XXXig 软件的部署维护。

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

-## 📋 目录
+| Playbook | 说明 | 变量示例 |
+| --- | --- | --- |
+| `gitea_repo_setup.yaml` | 配置 Gitea APT 软件源（下载 GPG 密钥、写入 source、更新缓存） | `examples/gitea_repo_setup_vars.example.yml` |
+| `journald_configure.yml` | 配置 systemd-journald 日志限额与速率限制 | `examples/journald_configure_vars.example.yml` |
+| `nezha_reinstall.yml` | 重装 Nezha Agent（卸载旧版本并安装新版本） | `examples/nezha_reinstall_vars.example.yml` |
+| `xxxig_install.yaml` | 安装 XXXig（按参数动态拼接安装命令） | `examples/xxxig_install_vars.example.yml` |
+| `xxxig_update.yaml` | 更新 XXXig 软件包并启动服务 | `examples/xxxig_update_vars.example.yml` |
+| `xxxig_uninstall.yaml` | 卸载 XXXig（无需变量） | — |

- [功能特性](#功能特性)
- [项目结构](#项目结构)
- [快速开始](#快速开始)
- [Playbook 列表](#playbook-列表)
- [文档](#文档)
- [贡献指南](#贡献指南)
+## 使用方法

-## ✨ 功能特性
+1. 准备 inventory 文件（如 `inventory.ini`），列出目标主机：

- 🚀 **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
+   ```ini
+   [all]
+   server1 ansible_host=192.168.1.10 ansible_user=root
   ```

-## 🚀 快速开始
-
-### 1. 准备环境
-
-确保已安装 Ansible:
+2. 复制对应的变量示例并按需修改：

   ```bash
-# macOS
-brew install ansible
-
-# Ubuntu/Debian
-sudo apt update && sudo apt install ansible
-
-# CentOS/RHEL
-sudo yum install ansible
-
-# 验证安装
-ansible --version
+   cp examples/xxxig_install_vars.example.yml xxxig_install_vars.yml
+   # 编辑 xxxig_install_vars.yml，填入必填参数
   ```

-### 2. 配置 Inventory
+3. 运行 playbook：

   ```bash
-# 复制示例文件
-cp examples/inventory.example.ini inventory.ini
-
-# 编辑文件，添加你的服务器信息
-vim inventory.ini
+   ansible-playbook xxxig_install.yaml -i inventory.ini -e @xxxig_install_vars.yml
   ```

-### 3. 测试连接
+无变量的 playbook（如 `xxxig_uninstall.yaml`）可省略 `-e` 参数直接运行。

-```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日
+- `examples/` 下为变量模板，每个文件顶部均注明用法及必填/可选参数。
+- `inventory.ini`、`*_vars.yml` 等含主机或密钥的文件已在 `.gitignore` 中忽略，仅 `*.example.yml` 入库，请勿将真实密钥提交到仓库。
@@ -1,200 +0,0 @@
-# Nezha Agent Secret 更新 - 快速开始
-
-## 🚀 5分钟快速上手
-
-### 步骤 1: 准备 Inventory 文件
-
-```bash
-# 复制示例文件
-cp inventory.example.ini inventory.ini
-
-# 编辑 inventory.ini，添加你的服务器信息
-vim inventory.ini
-```
-
-最简单的 inventory.ini 示例:
-```ini
-[nezha_agents]
-your-server.com ansible_host=1.2.3.4 ansible_user=root
-```
-
-### 步骤 2: 测试连接
-
-```bash
-# 测试 Ansible 连接
-ansible nezha_agents -i inventory.ini -m ping
-```
-
-如果成功，你会看到:
-```
-your-server.com | SUCCESS => {
-    "changed": false,
-    "ping": "pong"
-}
-```
-
-### 步骤 3: 执行更新
-
-#### 方式A：强制更新（推荐用于首次使用）
-
-```bash
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e "client_secret=你的新密钥"
-```
-
-#### 方式B：安全更新（推荐用于生产环境）
-
-```bash
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e "client_secret=新密钥" \
-  -e "old_client_secret=旧密钥"
-```
-
-### 步骤 4: 验证结果
-
-执行成功后，你会看到类似输出:
-```
-TASK [显示更新结果] ****************************************************
-ok: [your-server.com] => {
-    "msg": "client_secret 已成功更新"
-}
-
-TASK [显示服务状态] ****************************************************
-ok: [your-server.com] => {
-    "msg": "Nezha Agent 服务状态: active"
-}
-```
-
-## 🎯 常见使用场景
-
-### 场景 1: 单台服务器更新
-
-```bash
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  --limit your-server.com \
-  -e "client_secret=NewSecret123"
-```
-
-### 场景 2: 先测试，后执行
-
-```bash
-# 1. 测试模式（不实际执行，只显示会做什么）
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e "client_secret=NewSecret123" \
-  --check --diff
-
-# 2. 确认无误后，去掉 --check 实际执行
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e "client_secret=NewSecret123"
-```
-
-### 场景 3: 批量更新多台服务器
-
-```bash
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e "client_secret=NewSecret123"
-```
-
-### 场景 4: 使用变量文件（保护敏感信息）
-
-创建 `secret_vars.yml`:
-```yaml
-client_secret: "你的新密钥"
-```
-
-执行:
-```bash
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e @secret_vars.yml
-```
-
-## ⚠️ 注意事项
-
-1. **备份**: 每次执行都会自动备份配置文件
-2. **重启**: 更新后会自动重启 nezha-agent 服务（服务会短暂中断几秒）
-3. **权限**: 确保你有 root 或 sudo 权限
-4. **验证**: 使用 `-e "old_client_secret=旧值"` 可以避免误操作
-
-## 🔧 故障排查
-
-### 问题：连接失败
-
-```bash
-# 检查 SSH 连接
-ssh root@your-server.com
-
-# 测试 Ansible 连接
-ansible nezha_agents -i inventory.ini -m ping -vvv
-```
-
-### 问题：权限不足
-
-```bash
-# 如果不是 root 用户，确保在 inventory.ini 中添加
-ansible_become=yes
-
-# 或在命令中添加
-ansible-playbook nezha_update_secret.yml -i inventory.ini -b -K
-# -b: 使用 become (sudo)
-# -K: 询问 sudo 密码
-```
-
-### 问题：配置文件路径不同
-
-```bash
-# 指定自定义路径
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e "client_secret=NewSecret" \
-  -e "config_file=/custom/path/config.yml"
-```
-
-## 📚 更多信息
-
- 详细文档: [nezha_update_secret_README.md](nezha_update_secret_README.md)
- 查看其他 playbook 示例: `ls *.yml *.yaml`
-
-## 💡 专业提示
-
-1. **使用 Ansible Vault 保护密钥**:
-   ```bash
-   ansible-vault encrypt_string 'YourSecret' --name 'client_secret'
-   ```
-
-2. **保存执行日志**:
-   ```bash
-   ansible-playbook nezha_update_secret.yml \
-     -i inventory.ini \
-     -e "client_secret=NewSecret" | tee update.log
-   ```
-
-3. **并行执行（多台服务器）**:
-   ```bash
-   ansible-playbook nezha_update_secret.yml \
-     -i inventory.ini \
-     -e "client_secret=NewSecret" \
-     -f 10  # 同时处理10台服务器
-   ```
-
-## ✅ 检查清单
-
- [ ] 已准备 inventory.ini 文件
- [ ] 已测试 SSH/Ansible 连接 (`ansible -m ping`)
- [ ] 已准备新的 client_secret 值
- [ ] 在生产环境前已在测试环境验证
- [ ] 已使用 `--check --diff` 预览变更
- [ ] 已准备回滚方案（保留旧密钥值）
-
-准备就绪？执行以下命令开始:
-```bash
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e "client_secret=你的新密钥"
-```
@@ -1,116 +0,0 @@
-# Docs - 文档目录
-
-本目录包含项目的详细文档。
-
-## 📚 文档列表
-
-### Nezha Agent 管理
-
- **[nezha_update_secret_README.md](nezha_update_secret_README.md)** - Nezha Agent Client Secret 更新工具完整文档
-  - 详细的使用方法和参数说明
-  - 安全性和可靠性特性
-  - 错误处理和故障排查
-  - 最佳实践建议
-
- **[QUICKSTART_nezha.md](QUICKSTART_nezha.md)** - Nezha Agent 5分钟快速开始
-  - 快速上手步骤
-  - 常见使用场景
-  - 故障排查指南
-
-### XXXigCC 管理
-
- **[xxxigcc_update_pool_url_README.md](xxxigcc_update_pool_url_README.md)** - XXXigCC Pool URL 更新工具完整文档
-  - 详细的使用方法和参数说明
-  - 条件更新和安全特性
-  - 配置备份和服务管理
-  - 故障排查和最佳实践
-
-## 🔍 查找文档
-
-### 按需求查找
-
-| 我想... | 查看文档 |
-|---------|----------|
-| 快速更新 Nezha Agent | [快速开始](QUICKSTART_nezha.md) |
-| 了解所有功能和参数 | [完整文档](nezha_update_secret_README.md) |
-| 更新 XXXigCC Pool URL | [Pool URL 更新文档](xxxigcc_update_pool_url_README.md) |
-| 查看配置示例 | [examples/](../examples/) |
-| 了解项目架构 | [llmdoc/architecture/](../llmdoc/architecture/) |
-| 学习最佳实践 | [llmdoc/guides/](../llmdoc/guides/) |
-
-## 📖 文档组织
-
-本项目采用分层文档结构:
-
-```
-docs/                    # 用户文档（人类友好）
-├── nezha_update_secret_README.md
-├── QUICKSTART_nezha.md
-└── xxxigcc_update_pool_url_README.md
-
-llmdoc/                  # LLM 文档系统（AI 友好）
-├── index.md            # 文档索引
-├── overview/           # 项目概览
-├── guides/             # 操作指南
-├── architecture/       # 架构文档
-└── reference/          # 参考文档
-```
-
-### docs/ vs llmdoc/
-
- **docs/** - 面向人类用户的详细文档
-  - 更注重实用性和可读性
-  - 包含大量示例和使用场景
-  - 适合快速上手和日常使用
-
- **llmdoc/** - 面向 LLM 的结构化文档
-  - 更注重系统性和完整性
-  - 按架构/指南/参考分类
-  - 适合深入理解和检索
-
-## 🚀 快速导航
-
-### 新手入门
-
-1. 阅读 [项目 README](../README.md)
-2. 查看 [快速开始指南](QUICKSTART_nezha.md)
-3. 参考 [示例配置](../examples/)
-
-### 深入学习
-
-1. 浏览 [LLM 文档索引](../llmdoc/index.md)
-2. 学习 [Ansible 最佳实践](../llmdoc/guides/ansible-best-practices.md)
-3. 了解 [项目架构](../llmdoc/architecture/)
-
-### 问题解决
-
-1. 查看文档中的"故障排查"章节
-2. 检查 [示例配置](../examples/)是否正确
-3. 参考 [安全最佳实践](../llmdoc/guides/security-best-practices.md)
-
-## 🔄 文档更新
-
-文档会随项目更新而更新。如发现文档问题:
-
- 提交 Issue 报告文档错误
- 直接提 PR 修正文档
-
-## 📝 文档编写规范
-
-如果您想贡献文档:
-
-1. 遵循 Markdown 语法
-2. 使用清晰的标题层级
-3. 添加必要的代码示例
-4. 包含实际使用场景
-5. 保持简洁明了
-
-## 🔗 相关资源
-
- [Ansible 官方文档](https://docs.ansible.com/)
- [YAML 语法指南](https://yaml.org/spec/1.2/spec.html)
- [Jinja2 模板文档](https://jinja.palletsprojects.com/)
-
---
-
-有任何文档相关的问题？请提交 [Issue](../../issues)。
@@ -1,225 +0,0 @@
-# Nezha Agent Client Secret 更新工具
-
-## 概述
-
-本工具提供两个 Ansible Playbook，用于安全地更新 Nezha Agent 配置文件中的 `client_secret` 字段。
-
-## 文件说明
-
- **nezha_update_secret.yml** (推荐)：使用 `lineinfile` 模块，简单可靠
- **nezha_update_secret_v2.yml** (备选)：使用 `replace` 模块，正则表达式更灵活
-
-## 使用方法
-
-### 方式1：强制更新（不验证旧值）
-
-```bash
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e "client_secret=你的新密钥"
-```
-
-### 方式2：安全更新（验证旧值）
-
-```bash
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e "client_secret=你的新密钥" \
-  -e "old_client_secret=旧密钥值"
-```
-
-### 方式3：使用变量文件
-
-创建变量文件 `vars.yml`:
-```yaml
-client_secret: "HWzBMgbtWbSHdTyTVyh5U8bu3JhPmStw"
-old_client_secret: "OldSecretValue123"  # 可选
-```
-
-执行:
-```bash
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e @vars.yml
-```
-
-### 方式4：针对特定主机
-
-```bash
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  --limit "server1,server2" \
-  -e "client_secret=你的新密钥"
-```
-
-## 参数说明
-
-| 参数 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| `client_secret` | 字符串 | ✅ 是 | 新的 client_secret 值 |
-| `old_client_secret` | 字符串 | ❌ 否 | 旧的 client_secret 值，用于验证。留空则强制更新 |
-| `config_file` | 字符串 | ❌ 否 | 配置文件路径，默认 `/opt/nezha/agent/config.yml` |
-| `service_name` | 字符串 | ❌ 否 | 服务名称，默认 `nezha-agent.service` |
-
-## 功能特性
-
-### ✅ 安全性保障
- ✔️ 自动备份配置文件（带时间戳）
- ✔️ 可选的旧值验证，防止误操作
- ✔️ 配置文件存在性检查
- ✔️ 参数完整性验证
-
-### ✅ 可靠性保障
- ✔️ 幂等操作，可重复执行
- ✔️ 更新失败时不会重启服务
- ✔️ 服务状态验证和显示
-
-### ✅ 自动化功能
- ✔️ 配置更新后自动重启 nezha-agent 服务
- ✔️ 使用 handler 机制，只在配置变更时重启
-
-## 执行流程
-
-1. **参数验证** - 检查必填参数是否提供
-2. **文件检查** - 验证配置文件是否存在
-3. **备份配置** - 创建带时间戳的备份文件
-4. **更新配置** - 根据是否提供旧值选择更新策略
-5. **触发重启** - 配置变更时触发服务重启（handler）
-6. **状态验证** - 显示服务最终状态
-
-## 备份说明
-
-每次执行都会创建两个备份：
-
-1. **时间戳备份**: `config.yml.backup.20231216T153045`
-2. **Ansible 备份**: `config.yml.[随机后缀]~`
-
-备份文件保存在与原配置文件相同的目录中。
-
-## 错误处理
-
-### 错误：client_secret 参数为空
-```
-FAILED! => {"msg": "参数 client_secret 不能为空"}
-```
-**解决**: 确保提供了 `client_secret` 参数
-
-### 错误：配置文件不存在
-```
-FAILED! => {"msg": "配置文件 /opt/nezha/agent/config.yml 不存在"}
-```
-**解决**: 检查 Nezha Agent 是否已安装，或使用 `-e config_file=路径` 指定正确路径
-
-### 错误：未找到匹配的旧值
-```
-FAILED! => {"msg": "未找到匹配的旧 client_secret 值"}
-```
-**解决**: 检查 `old_client_secret` 参数是否正确，或使用强制更新模式（不提供旧值）
-
-## 使用示例
-
-### 示例1：生产环境安全更新
-
-```bash
-# 先在测试环境验证
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  --limit test_servers \
-  -e "client_secret=NewSecret123" \
-  -e "old_client_secret=OldSecret456" \
-  --check --diff
-
-# 确认无误后应用到生产环境
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  --limit prod_servers \
-  -e "client_secret=NewSecret123" \
-  -e "old_client_secret=OldSecret456"
-```
-
-### 示例2：批量更新所有服务器
-
-```bash
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e "client_secret=NewUnifiedSecret"
-```
-
-### 示例3：测试模式（不实际执行）
-
-```bash
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e "client_secret=TestSecret" \
-  --check --diff
-```
-
-## 回滚操作
-
-如果更新后需要回滚：
-
-```bash
-# 方法1：使用备份文件恢复
-ansible all -i inventory.ini -b \
-  -m copy \
-  -a "src=/opt/nezha/agent/config.yml.backup.20231216T153045 \
-      dest=/opt/nezha/agent/config.yml \
-      remote_src=yes"
-
-# 方法2：使用原有的 client_secret 再次运行
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e "client_secret=原来的密钥"
-```
-
-## 注意事项
-
-1. **权限要求**: 需要 root 或 sudo 权限
-2. **服务中断**: 更新会导致 Nezha Agent 服务短暂重启（通常几秒钟）
-3. **批量操作**: 建议先在小范围测试，再批量应用
-4. **密钥安全**: 不要将密钥直接写在命令历史中，建议使用变量文件或 Ansible Vault
-5. **幂等性**: 可以安全地重复执行，不会造成重复修改
-
-## 与 Ansible Vault 结合使用
-
-为保护敏感信息，建议使用 Ansible Vault：
-
-```bash
-# 创建加密的变量文件
-ansible-vault create secret_vars.yml
-
-# 在文件中添加
-client_secret: "你的密钥"
-
-# 使用加密文件执行
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e @secret_vars.yml \
-  --ask-vault-pass
-```
-
-## 最佳实践
-
-1. ✅ 在生产环境使用前，先在测试环境验证
-2. ✅ 使用 `--check --diff` 模式预览变更
-3. ✅ 使用 `old_client_secret` 参数进行安全验证
-4. ✅ 使用 Ansible Vault 保护敏感信息
-5. ✅ 定期清理旧的备份文件
-6. ✅ 记录每次更新的时间和原因
-
-## 技术细节
-
-### 方案A (lineinfile) vs 方案B (replace)
-
-| 特性 | lineinfile | replace |
-|------|-----------|---------|
-| 复杂度 | 简单 | 中等 |
-| 灵活性 | 中等 | 高 |
-| 适用场景 | 单行替换 | 复杂模式匹配 |
-| 推荐度 | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ |
-
-推荐使用 `nezha_update_secret.yml` (方案A)，除非有特殊的正则表达式需求。
-
-## 许可证
-
-遵循项目主许可证
@@ -1,294 +0,0 @@
-# XXXigCC Pool URL 更新工具
-
-## 概述
-
-本工具提供一个 Ansible Playbook，用于安全地更新 XXXigCC 配置文件中的 Pool URL，并清理日志、重启服务。
-
-## 功能特性
-
- ✅ 支持条件更新（可选验证旧 URL）
- ✅ 自动备份配置文件
- ✅ 清理日志目录
- ✅ 自动重启服务
- ✅ 详细的操作日志和结果验证
-
-## 使用方法
-
-### 方式1：无条件更新（推荐）
-
-适用于快速更新 Pool URL，不验证当前值：
-
-```bash
-ansible-playbook xxxigcc_update_pool_url.yaml \
-  -i inventory.ini \
-  -e "new_url=xxxigcc-proxy.ca.vvvo.net:8443"
-```
-
-### 方式2：条件更新（更安全）
-
-只有当前 URL 等于 `old_url` 时才执行更新，适用于批量更新时确保只更新特定主机：
-
-```bash
-ansible-playbook xxxigcc_update_pool_url.yaml \
-  -i inventory.ini \
-  -e "new_url=xxxigcc-proxy.ca.vvvo.net:8443" \
-  -e "old_url=old-proxy.example.com:8443"
-```
-
-### 方式3：使用变量文件
-
-创建变量文件 `xxxigcc_update_pool_url_vars.yml`:
-```yaml
-new_url: "xxxigcc-proxy.ca.vvvo.net:8443"
-old_url: "old-proxy.example.com:8443"  # 可选
-```
-
-执行:
-```bash
-ansible-playbook xxxigcc_update_pool_url.yaml \
-  -i inventory.ini \
-  -e @xxxigcc_update_pool_url_vars.yml
-```
-
-### 方式4：针对特定主机
-
-```bash
-ansible-playbook xxxigcc_update_pool_url.yaml \
-  -i inventory.ini \
-  --limit "server1,server2" \
-  -e "new_url=xxxigcc-proxy.ca.vvvo.net:8443"
-```
-
-## 参数说明
-
-| 参数 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `new_url` | 字符串 | ✅ 是 | - | 新的 Pool URL |
-| `old_url` | 字符串 | ❌ 否 | "" | 旧的 Pool URL，用于条件验证。留空则无条件更新 |
-| `config_file` | 字符串 | ❌ 否 | `/etc/xxxigcc/config.json` | 配置文件路径 |
-| `log_dir` | 字符串 | ❌ 否 | `/var/log/xxxigcc` | 日志目录路径 |
-| `service_name` | 字符串 | ❌ 否 | `xxxigcc-daemon.service` | 服务名称 |
-
-## 执行流程
-
-Playbook 将按以下顺序执行操作：
-
-1. **参数验证** - 检查必填参数 `new_url` 是否提供
-2. **工具检查** - 确保 `jq` 工具已安装（用于 JSON 处理）
-3. **配置文件验证** - 检查配置文件是否存在
-4. **备份配置** - 创建带时间戳的配置文件备份
-5. **读取当前值** - 获取当前的 Pool URL
-6. **条件判断** - 根据 `old_url` 参数决定是否执行更新
-7. **更新 URL** - 修改配置文件中的 `pools[0].url` 字段
-8. **清理日志** - 删除 `/var/log/xxxigcc` 下的所有日志文件
-9. **重启服务** - 重启 `xxxigcc-daemon.service` 服务
-10. **验证结果** - 显示操作总结和最终状态
-
-## 配置文件示例
-
-需要修改的配置文件结构（`/etc/xxxigcc/config.json`）：
-
-```json
-{
-  "pools": [
-    {
-      "algo": "rx/0",
-      "url": "xxxigcc-proxy.ca.vvvo.net:8443",
-      "user": "empty_wallet_1764940944",
-      "pass": "25_187_cYwsT",
-      "tls": true,
-      ...
-    }
-  ],
-  ...
-}
-```
-
-Playbook 会修改 `pools[0].url` 字段的值。
-
-## 安全特性
-
- ✅ **自动备份**：每次更新前创建带时间戳的配置文件备份
- ✅ **条件更新**：支持验证旧值，避免误更新
- ✅ **原子操作**：使用临时文件确保配置更新的原子性
- ✅ **权限管理**：使用 `become: yes` 确保有足够权限
-
-## 故障排查
-
-### 问题1：jq 命令未找到
-
-**错误信息**：
-```
-jq: command not found
-```
-
-**解决方案**：
-Playbook 会自动安装 jq，但如果失败，可以手动安装：
-```bash
-# Ubuntu/Debian
-sudo apt-get install jq
-
-# CentOS/RHEL
-sudo yum install jq
-```
-
-### 问题2：配置文件不存在
-
-**错误信息**：
-```
-配置文件 /etc/xxxigcc/config.json 不存在
-```
-
-**解决方案**：
- 确认 XXXigCC 已经正确安装
- 检查配置文件路径是否正确
- 如果路径不同，使用 `-e config_file=/path/to/config.json` 指定
-
-### 问题3：服务重启失败
-
-**错误信息**：
-```
-Failed to restart xxxigcc-daemon.service
-```
-
-**解决方案**：
- 检查服务是否存在：`systemctl status xxxigcc-daemon.service`
- 查看服务日志：`journalctl -u xxxigcc-daemon.service -n 50`
- 验证配置文件语法：`jq . /etc/xxxigcc/config.json`
-
-### 问题4：条件更新未执行
-
-**现象**：
-提供了 `old_url` 参数，但没有执行更新
-
-**原因**：
-当前配置文件中的 URL 与提供的 `old_url` 不匹配
-
-**解决方案**：
- 检查当前 URL：`jq -r '.pools[0].url' /etc/xxxigcc/config.json`
- 确认 `old_url` 参数是否正确
- 如需强制更新，不要提供 `old_url` 参数
-
-## 备份和恢复
-
-### 查看备份文件
-
-备份文件保存在配置文件同目录下，格式为：
-```
-/etc/xxxigcc/config.json.backup.<timestamp>
-```
-
-查看所有备份：
-```bash
-ls -lh /etc/xxxigcc/config.json.backup.*
-```
-
-### 恢复配置
-
-如果需要恢复到之前的配置：
-
-```bash
-# 查看备份内容
-cat /etc/xxxigcc/config.json.backup.1734326400
-
-# 恢复配置
-sudo cp /etc/xxxigcc/config.json.backup.1734326400 /etc/xxxigcc/config.json
-
-# 重启服务
-sudo systemctl restart xxxigcc-daemon.service
-```
-
-## 最佳实践
-
-1. **先测试，后批量**：
-   - 先在单个主机上测试：`--limit "test-server"`
-   - 验证成功后再批量执行
-
-2. **使用条件更新**：
-   - 批量更新时使用 `old_url` 参数，避免误更新已经更新过的主机
-
-3. **保留备份**：
-   - 定期清理旧备份，但保留最近几次的备份文件
-
-4. **监控服务状态**：
-   - 更新后验证服务是否正常运行
-   - 检查日志确认连接到新的 Pool URL
-
-5. **使用变量文件**：
-   - 对于复杂配置，使用变量文件更易于管理和版本控制
-
-## 示例场景
-
-### 场景1：迁移到新的 Pool 服务器
-
-```bash
-# 1. 更新 Pool URL
-ansible-playbook xxxigcc_update_pool_url.yaml \
-  -i inventory.ini \
-  -e "new_url=new-pool.example.com:8443" \
-  -e "old_url=old-pool.example.com:8443"
-
-# 2. 验证服务状态
-ansible all -i inventory.ini -m shell -a "systemctl status xxxigcc-daemon.service" -b
-```
-
-### 场景2：批量更新多个区域的主机
-
-```bash
-# 区域1
-ansible-playbook xxxigcc_update_pool_url.yaml \
-  -i inventory.ini \
-  --limit "region_us" \
-  -e "new_url=us-pool.example.com:8443"
-
-# 区域2
-ansible-playbook xxxigcc_update_pool_url.yaml \
-  -i inventory.ini \
-  --limit "region_eu" \
-  -e "new_url=eu-pool.example.com:8443"
-```
-
-### 场景3：紧急回滚
-
-```bash
-# 使用备份文件恢复
-ansible all -i inventory.ini -m shell -a \
-  "cp /etc/xxxigcc/config.json.backup.1734326400 /etc/xxxigcc/config.json && \
-   systemctl restart xxxigcc-daemon.service" -b
-```
-
-## 相关文档
-
- [XXXigCC 部署指南](../llmdoc/guides/how-to-deploy-xxxigcc.md)
- [Ansible 最佳实践](../llmdoc/guides/ansible-best-practices.md)
- [配置示例](../examples/xxxigcc_update_pool_url_vars.example.yml)
-
-## 技术细节
-
-### JSON 处理
-
-使用 `jq` 工具进行 JSON 文件的精确修改：
-
-```bash
-# 读取当前值
-jq -r '.pools[0].url' /etc/xxxigcc/config.json
-
-# 更新值（使用临时文件确保原子性）
-jq '.pools[0].url = "new-url"' config.json > config.json.tmp
-mv config.json.tmp config.json
-```
-
-### 服务管理
-
-使用 Ansible 的 `systemd` 模块管理服务：
-
-```yaml
- name: 重启服务
-  ansible.builtin.systemd:
-    name: xxxigcc-daemon.service
-    state: restarted
-```
-
---
-
-有任何问题？请查看 [故障排查](#故障排查) 章节或提交 [Issue](../../issues)。
@@ -1,93 +0,0 @@
-# Examples - 示例文件目录
-
-本目录包含各种 Ansible Playbook 的示例配置文件。
-
-## 📁 文件说明
-
-### Inventory 示例
-
- **[inventory.example.ini](inventory.example.ini)** - Ansible inventory 配置示例
-  - 单服务器和多服务器配置
-  - 不同认证方式示例
-  - 组变量配置示例
-
-### 变量文件示例
-
- **[nezha_vars.example.yml](nezha_vars.example.yml)** - Nezha Agent 更新配置变量
- **[xxxigcc_vars.example.yml](xxxigcc_vars.example.yml)** - XXXigCC 安装配置变量
- **[journald_vars.example.yml](journald_vars.example.yml)** - Journald 日志配置变量
-
-## 🚀 使用方法
-
-### 1. Inventory 文件
-
-```bash
-# 复制示例文件
-cp examples/inventory.example.ini inventory.ini
-
-# 编辑文件，填入你的服务器信息
-vim inventory.ini
-
-# 测试连接
-ansible all -i inventory.ini -m ping
-```
-
-### 2. 变量文件
-
-```bash
-# 复制相应的示例文件
-cp examples/nezha_vars.example.yml nezha_vars.yml
-
-# 编辑文件，填入实际配置
-vim nezha_vars.yml
-
-# 使用变量文件执行 playbook
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e @nezha_vars.yml
-```
-
-### 3. 直接命令行传参
-
-不使用变量文件，直接在命令行传递参数：
-
-```bash
-ansible-playbook nezha_update_secret.yml \
-  -i inventory.ini \
-  -e "client_secret=YourNewSecret"
-```
-
-## 📋 最佳实践
-
-1. **不要提交实际配置到版本控制**
-   - 将 `inventory.ini` 和 `*_vars.yml` 添加到 `.gitignore`
-   - 只提交 `.example` 示例文件
-
-2. **使用 Ansible Vault 保护敏感信息**
-   ```bash
-   # 加密变量文件
-   ansible-vault encrypt nezha_vars.yml
-
-   # 使用加密文件
-   ansible-playbook nezha_update_secret.yml \
-     -i inventory.ini \
-     -e @nezha_vars.yml \
-     --ask-vault-pass
-   ```
-
-3. **变量文件命名规范**
-   - 开发环境: `vars.dev.yml`
-   - 测试环境: `vars.test.yml`
-   - 生产环境: `vars.prod.yml`
-
-## 🔗 相关文档
-
- [Nezha Agent 更新文档](../docs/nezha_update_secret_README.md)
- [Nezha Agent 快速开始](../docs/QUICKSTART_nezha.md)
- [项目主 README](../README.md)
-
-## 💡 提示
-
- 所有 `.example` 文件都包含详细的注释说明
- 复制示例文件时，记得去掉 `.example` 后缀
- 根据实际需求修改示例文件中的值
@@ -0,0 +1,9 @@
+# Gitea APT 仓库配置变量示例
+# 使用方法: ansible-playbook gitea_repo_setup.yaml -i inventory.ini -e @gitea_repo_setup_vars.yml
+
+# 可选参数：Gitea 仓库地址（默认值如下）
+repo_url: "https://gitea.bcde.io"
+
+# 可选参数：仓库所属用户/组织（默认值如下）
+# 同时决定软件源文件名与 GPG 密钥文件名
+repo_owner: "wangdefa"
@@ -1,35 +0,0 @@
-# Ansible Inventory 示例文件
-# 复制此文件为 inventory.ini 并修改为你的实际服务器信息
-
-[nezha_agents]
-# 单个服务器示例
-server1.example.com ansible_host=192.168.1.10 ansible_user=root
-
-# 多个服务器
-server2.example.com ansible_host=192.168.1.11 ansible_user=admin ansible_become=yes
-server3.example.com ansible_host=192.168.1.12 ansible_user=admin ansible_become=yes
-
-# 使用不同的 SSH 端口
-server4.example.com ansible_host=192.168.1.13 ansible_port=2222 ansible_user=root
-
-[nezha_agents:vars]
-# 组级别的变量
-ansible_python_interpreter=/usr/bin/python3
-# 如果使用 SSH 密钥
-# ansible_ssh_private_key_file=~/.ssh/id_rsa
-
-# 测试环境
-[test_servers]
-test1.example.com ansible_host=192.168.10.10
-
-# 生产环境
-[prod_servers]
-prod1.example.com ansible_host=192.168.20.10
-prod2.example.com ansible_host=192.168.20.11
-prod3.example.com ansible_host=192.168.20.12
-
-# 所有服务器
-[all:children]
-nezha_agents
-test_servers
-prod_servers
@@ -1,20 +1,17 @@
-# Journald 配置变量示例
-# 使用方法: ansible-playbook journald_configure.yml -i inventory.ini -e @journald_vars.yml
+# systemd-journald 配置变量示例
+# 使用方法: ansible-playbook journald_configure.yml -i inventory.ini -e @journald_configure_vars.yml

-# Journald 配置参数
+# 可选参数：journald 配置项（默认值如下）
 journald_config:
  # 限制日志最大使用空间（所有服务总和）
  system_max_use: "500M"
-
  # 单个日志文件最大大小
  system_max_file_size: "100M"
-
  # 保留日志的时间
  max_retention_sec: "7day"
-
  # 限制单个服务的日志速率（防止日志炸弹）
  rate_limit_interval_sec: "30s"
  rate_limit_burst: "10000"

-# 是否备份原有配置
+# 可选参数：部署前是否备份原有 journald.conf（默认 true）
 backup_journald: true
@@ -0,0 +1,14 @@
+# Nezha Agent 重装配置变量示例
+# 使用方法: ansible-playbook nezha_reinstall.yml -i inventory.ini -e @nezha_reinstall_vars.yml
+
+# 必填参数：客户端密钥
+nz_client_secret: "your_client_secret_here"
+
+# 可选参数：Nezha 服务端地址（默认值如下）
+nz_server: "dash.miner.vvvo.net:443"
+
+# 可选参数：是否启用 TLS（默认 true）
+nz_tls: true
+
+# 可选参数：安装脚本 URL（默认值如下）
+# install_script_url: "https://raw.githubusercontent.com/wangdefaa/nezha-agent/refs/heads/main/script/install.sh"
@@ -1,17 +0,0 @@
-# Nezha Agent 更新配置变量示例
-# 使用方法: ansible-playbook nezha_update_secret.yml -i inventory.ini -e @nezha_vars.yml
-
-# 必填参数：新的 client_secret 值
-client_secret: "HWzBMgbtWbSHdTyTVyh5U8bu3JhPmStw"
-
-# 可选参数：旧的 client_secret 值（用于安全验证）
-# 如果提供此参数，将验证配置文件中的旧值是否匹配
-# 如果不匹配，更新将失败，避免误操作
-# 留空或删除此行则强制更新，不进行验证
-old_client_secret: ""
-
-# 可选参数：配置文件路径（默认值如下）
-# config_file: "/opt/nezha/agent/config.yml"
-
-# 可选参数：服务名称（默认值如下）
-# service_name: "nezha-agent.service"
@@ -0,0 +1,19 @@
+# XXXig 安装配置变量示例
+# 使用方法: ansible-playbook xxxig_install.yaml -i inventory.ini -e @xxxig_install_vars.yml
+
+# 必填参数：矿池地址
+pool_url: "stratum+tcp://pool.example.com:3333"
+
+# 必填参数：CC 控制端地址与令牌（启用 enable_cc 时必填）
+cc_url: "cc.example.com:443"
+cc_token: "your-cc-token-here"
+
+# 可选参数：功能开关（默认均为 true）
+enable_cc: true          # 启用 CC 控制端连接
+enable_tls: true         # 矿池连接启用 TLS
+enable_cc_tls: true      # CC 连接启用 TLS
+enable_keepalive: true   # 启用 keepalive
+enable_1gb_pages: true   # 启用 1GB 大页内存
+
+# 可选参数：安装脚本 URL（默认值如下）
+# install_script_url: "https://gitea.bcde.io/wangdefa/xxxig/raw/branch/main/script/install.deb.sh"
@@ -0,0 +1,8 @@
+# XXXig 更新配置变量示例
+# 使用方法: ansible-playbook xxxig_update.yaml -i inventory.ini -e @xxxig_update_vars.yml
+
+# 可选参数：软件包名称（默认值如下）
+package_name: "xxxig"
+
+# 可选参数：服务名称（默认值如下）
+service_name: "xxxig-daemon.service"
@@ -1,19 +0,0 @@
-# XXXigCC Pool URL 更新配置变量示例
-# 使用方法: ansible-playbook xxxigcc_update_pool_url.yaml -i inventory.ini -e @xxxigcc_update_pool_url_vars.yml
-
-# 必填参数
-new_url: "xxxigcc-proxy.ca.vvvo.net:8443"
-
-# 可选参数
-# 如果提供此参数，只有当前 URL 等于 old_url 时才会执行更新
-# 如果不提供，则无条件更新
-# old_url: "old-proxy.example.com:8443"
-
-# 配置文件路径（一般不需要修改）
-# config_file: "/etc/xxxigcc/config.json"
-
-# 日志目录路径（一般不需要修改）
-# log_dir: "/var/log/xxxigcc"
-
-# 服务名称（一般不需要修改）
-# service_name: "xxxigcc-daemon.service"
@@ -1,17 +0,0 @@
-# XXXigCC 安装配置变量示例
-# 使用方法: ansible-playbook xxxigcc_install.yaml -i inventory.ini -e @xxxigcc_vars.yml
-
-# 必填参数
-pool_url: "stratum+tcp://pool.example.com:3333"
-cc_url: "https://control.example.com"
-cc_token: "your-control-center-token"
-
-# 可选参数（布尔值）
-enable_cc: true
-enable_tls: true
-enable_cc_tls: true
-enable_keepalive: true
-enable_1gb_pages: true
-
-# 脚本URL（一般不需要修改）
-# install_script_url: "https://gitea.bcde.io/wangdefa/xxxigcc/raw/branch/main/script/install.deb.sh"
@@ -1,5 +1,5 @@
 ---
- name: 配置 systemd-journald
+- name: systemd-journald 配置脚本
  hosts: all
  become: yes

@@ -1,71 +0,0 @@
-# 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` 验证
- **配置安全**：自动备份原始配置
- **错误处理**：完整的配置和服务验证机制
@@ -1,37 +0,0 @@
-# 动态参数构建架构
-
-## 1. 身份定义
-
- **定义：** 一种通过条件逻辑动态生成命令行参数的 Ansible 技术模式
- **目的：** 根据变量状态灵活构建命令，实现高度可配置的安装/卸载脚本
-
-## 2. 核心组件
-
- `xxxigcc_install.yaml:22-35`: 动态参数构建的关键实现区域
- `ansible.builtin.set_fact`: 用于动态生成 `install_command`
-
-## 3. 执行流程（LLM检索映射）
-
-1. **参数定义**：在 `vars` 部分预定义布尔开关
-   - 例如：`enable_keepalive`、`enable_1gb_pages`
-
-2. **条件参数生成**：使用 Jinja2 条件语法
-   ```yaml
-   {{ '--keepalive' if enable_keepalive else '' }}
-   ```
-
-3. **命令构建**：通过 `set_fact` 拼接最终命令
-   - 根据布尔变量动态添加/移除参数
-   - 支持复杂的条件逻辑（如 `enable_cc and enable_cc_tls`）
-
-## 4. 设计原理
-
- **灵活性**：通过布尔开关实现细粒度配置控制
- **可读性**：使用声明式语法，避免复杂的编程逻辑
- **可扩展性**：易于添加新的可选参数和配置
-
-## 5. 关键实践
-
- 默认值设置为 `true`，降低配置复杂度
- 使用条件语法代替显式条件判断
- 保持参数生成逻辑集中和清晰
@@ -1,48 +0,0 @@
-# Systemd-Journald 日志配置管理架构
-
-## 1. 身份
-
- **目的：** 通过 Ansible Playbook 管理和优化 systemd-journald 日志配置
- **核心功能：** 提供自动化、可重复且可控制的日志管理策略
-
-## 2. 核心组件
-
- `journald_configure.yml` (主要配置剧本): 负责整个日志配置管理流程
- `journald_config` (变量集): 定义日志配置参数和限制
-
-## 3. 执行流程（LLM 检索图）
-
-### 3.1 备份阶段
- **步骤：** 使用 `ansible.builtin.copy` 备份原始 `journald.conf`
- **条件：** `backup_journald` 变量为 `true`
- **备份路径：** `/etc/systemd/journald.conf.backup.[timestamp]`
-
-### 3.2 配置部署
- **步骤：** 使用 `ansible.builtin.copy` 部署新的 `journald.conf`
- **配置参数：**
-  - 日志总体空间限制
-  - 单文件日志大小限制
-  - 日志保留时间
-  - 日志速率控制
-
-### 3.3 服务管理
- **触发重启：** 通过 handler `重启 systemd-journald`
- **触发条件：** 配置文件发生变更
-
-### 3.4 验证与监控
- **服务状态检查：** 使用 `ansible.builtin.systemd` 模块
- **磁盘使用监控：** 执行 `journalctl --disk-usage`
-
-## 4. 设计原理
-
- **幂等性：** 确保多次执行不会产生意外副作用
- **安全性：** 防止日志炸弹，限制日志资源消耗
- **可追溯性：** 通过备份机制保留配置变更历史
-
-## 5. 关键变量和参数
-
- `system_max_use`: 总日志空间限制
- `system_max_file_size`: 单文件日志大小限制
- `max_retention_sec`: 日志保留时间
- `rate_limit_interval_sec`: 日志速率限制时间间隔
- `rate_limit_burst`: 日志突发速率限制
@@ -1,38 +0,0 @@
-# Gitea 仓库配置架构
-
-## 1. 身份定义
-
- **组件**: Gitea APT 仓库配置管理
- **目的**: 自动化 APT 仓库源配置过程
-
-## 2. 核心组件
-
- `playbooks/gitea_repo_setup.yaml`: 主要配置逻辑
-  - `ansible.builtin.file`: 目录管理
-  - `ansible.builtin.get_url`: 密钥下载
-  - `ansible.builtin.template`: 源文件生成
-  - `ansible.builtin.apt`: 缓存更新
-
-## 3. 执行流程
-
-1. **目录准备**
-   - 检查并创建 `/etc/apt/keyrings/`
-   - 删除旧的仓库源文件
-
-2. **密钥管理**
-   - 下载 GPG 公钥
-   - 确保密钥正确导入
-
-3. **源配置**
-   - 生成 `wangdefa.list`
-   - 配置仓库 URL 和签名信息
-
-4. **缓存刷新**
-   - 触发 `apt update`
-   - 记录更新日志
-
-## 4. 设计原则
-
- 幂等性：可安全重复执行
- 参数化：关键配置可动态调整
- 模块化：遵循 Ansible 最佳实践
@@ -1,38 +0,0 @@
-# 安全架构和权限管理
-
-## 1. 身份和目的
-
- **定义**：基于 Ansible 的安全和权限管理系统
- **目的**：通过精细的权限控制和安全机制，确保自动化部署的安全性
-
-## 2. 核心安全组件
-
-### 权限提升机制
- **技术**：`become: yes`
- **位置**：所有 Playbook（`xxxigcc_install.yaml`, `xxxigcc_uninstall.yaml`）
- **功能**：使用 sudo 权限执行关键任务
-
-### 脚本下载安全
- **证书验证**：`validate_certs: yes`
- **文件权限**：`mode: '0755'`
- **更新机制**：`force: yes` 和 `backup: yes`
-
-### 日志安全
- **位置**：`journald_configure.yml`
- **关键配置**：
-  - 限制日志总大小
-  - 防止日志炸弹攻击
-  - 日志保留策略
-
-## 3. 执行流程
-
-1. 权限申请：`become: yes`
-2. 安全下载：验证证书、限制权限
-3. 脚本执行：受限执行环境
-4. 日志记录：受控日志系统
-
-## 4. 设计原理
-
- 最小权限原则
- 安全防御性编程
- 日志可审计性
@@ -1,31 +0,0 @@
-# XXXigCC 部署架构
-
-## 1. 身份标识
-
- **定义：** 一个灵活的自动化部署和管理系统
- **目的：** 通过 Ansible Playbook 实现跨主机的自动化 XXXigCC 安装和卸载
-
-## 2. 核心组件
-
- `xxxigcc_install.yaml`: 负责 XXXigCC 的安装流程
- `xxxigcc_uninstall.yaml`: 负责 XXXigCC 的卸载流程
-
-## 3. 执行流程（LLM 检索路径）
-
-### 安装流程
-1. **脚本准备：** 从固定 URL 下载安装脚本到 `/tmp/install.deb.sh`
-2. **命令构建：** 根据布尔参数动态生成安装命令
-3. **权限设置：** 设置脚本执行权限 `0755`
-4. **执行安装：** 使用 Ansible 的 `shell` 模块执行安装
-5. **清理临时文件：** 删除下载的安装脚本
-
-### 卸载流程
-1. **脚本准备：** 从固定 URL 下载卸载脚本到 `/tmp/uninstall.sh`
-2. **执行卸载：** 使用 `-y --purge` 参数完全卸载
-3. **清理临时文件：** 删除下载的卸载脚本
-
-## 4. 设计原理
-
- 使用动态参数生成，增强灵活性
- 严格的安全下载和执行机制
- 支持多种功能开关（TLS、Keepalive、大页内存）
@@ -1,30 +0,0 @@
-# xxxigcc Update Playbook 架构
-
-## 1. 身份定义
- **功能**: 自动化 xxxigcc 软件包更新和服务管理
- **目的**: 简化 xxxigcc 服务的部署和维护流程
-
-## 2. 核心组件
- `xxxigcc_update.yaml`: 主要 Playbook 文件
-  - 使用 `ansible.builtin.apt` 模块管理软件包
-  - 使用 `ansible.builtin.systemd` 模块控制服务
-
-## 3. 执行流程（LLM 检索路径）
-1. **APT 更新**
-   - 更新本地软件包缓存
-   - 确保可获取最新版本的 xxxigcc
-
-2. **软件包管理**
-   - 安装或更新 xxxigcc 到最新版本
-   - 处理潜在的依赖关系
-
-3. **服务管理**
-   - 启用服务开机自启
-   - 启动服务
-   - 验证服务状态
-
-## 4. 设计原则
- 幂等性
- 最小化复杂性
- 详细日志记录
- 错误处理和状态验证
@@ -1,59 +0,0 @@
-# Ansible 最佳实践指南
-
-## 1. 参数管理
-
-### 变量定义
-1. **明确区分必填和可选参数**
-2. **使用布尔开关控制功能**
-3. **默认值设置要合理**
-
-示例：
-```yaml
-vars:
-  # 必填参数
-  pool_url: ""
-
-  # 可选参数
-  enable_cc: true  # 默认开启某些功能
-```
-
-## 2. 模块使用
-
-### 推荐模块
- `ansible.builtin.set_fact`：动态构建参数
- `ansible.builtin.debug`：日志和调试
- `ansible.builtin.get_url`：文件下载
- `ansible.builtin.shell`：执行复杂命令
- `ansible.builtin.file`：文件管理
-
-## 3. 命令构建
-
-### 条件渲染技巧
-1. 使用三元运算符动态生成命令
-2. 根据布尔开关添加可选参数
-
-```yaml
-install_command: >-
-  bash script.sh
-  {{ '--optional-flag' if enable_feature else '' }}
-```
-
-## 4. 安全与权限
-
-### 特权执行
- 始终使用 `become: yes`
- 谨慎管理 `sudo` 权限
-
-## 5. 错误处理
-
-### 日志与调试
-1. 使用 `register` 捕获命令输出
-2. 通过 `debug` 模块记录执行过程
-3. 考虑添加更详细的错误处理机制
-
-## 6. 性能与维护
-
-### 代码组织
- 保持 Playbook 模块化
- 减少重复代码
- 添加充分的注释说明
@@ -1,38 +0,0 @@
-# 如何配置 Gitea APT 仓库
-
-## 前提条件
-
- 已安装 Ansible
- 目标机器可访问互联网
- 具有 sudo 权限
-
-## 配置步骤
-
-1. **准备清单文件**
-   - 编辑 `inventory` 文件，添加目标主机
-   ```ini
-   [gitea_hosts]
-   your_target_host ansible_user=your_username
-   ```
-
-2. **设置变量**
-   在 `group_vars` 或 playbook 中定义必要变量：
-   ```yaml
-   repo_url: "https://gitea.example.com/repo"
-   repo_owner: "wangdefa"
-   ```
-
-3. **执行 Playbook**
-   ```bash
-   ansible-playbook -i inventory playbooks/gitea_repo_setup.yaml
-   ```
-
-4. **验证配置**
-   - 检查 `/etc/apt/sources.list.d/wangdefa.list`
-   - 运行 `apt update` 验证源可用性
-
-## 注意事项
-
- 确保网络连接正常
- 检查 GPG 密钥下载是否成功
- 对于不同的 Linux 发行版可能需要调整
@@ -1,64 +0,0 @@
-# 如何配置和管理 Journald 日志
-
-## 先决条件
-
- 已安装 Ansible
- 目标服务器已配置 SSH 访问
- 拥有对目标服务器的 sudo/root 权限
-
-## 配置步骤
-
-### 1. 编辑配置变量
-
-打开 `journald_configure.yml`，根据需求修改 `journald_config` 变量：
-
-```yaml
-journald_config:
-  system_max_use: "500M"     # 总日志空间限制
-  system_max_file_size: "100M" # 单文件日志大小限制
-  max_retention_sec: "7day"   # 日志保留时间
-  rate_limit_interval_sec: "30s" # 日志速率限制间隔
-  rate_limit_burst: "10000"   # 日志突发速率限制
-```
-
-### 2. 控制备份行为
-
-通过 `backup_journald` 变量控制是否在应用新配置前备份当前 `journald.conf`：
-
-```yaml
-backup_journald: true  # 启用备份
-```
-
-### 3. 执行 Playbook
-
-使用以下命令运行 Playbook：
-
-```bash
-ansible-playbook journald_configure.yml
-```
-
-### 4. 验证配置
-
-Playbook 将自动：
- 备份原始配置文件
- 部署新配置
- 重启 systemd-journald 服务
- 显示服务状态
- 报告日志磁盘使用情况
-
-## 常见问题与解决方案
-
-1. **配置未生效？**
-   - 检查 Ansible 执行输出
-   - 确认 SSH 连接和权限
-   - 验证目标服务器的 systemd 版本兼容性
-
-2. **日志空间不足？**
-   - 增加 `system_max_use` 值
-   - 减少 `max_retention_sec`
-
-## 最佳实践
-
- 定期审核和调整日志配置
- 监控日志磁盘使用情况
- 根据系统负载动态调整参数
@@ -1,44 +0,0 @@
-# 如何部署和卸载 XXXigCC
-
-## 1. 准备部署
-
-### 必填参数
- `pool_url`：资源池 URL
- `cc_url`：控制中心 URL
- `cc_token`：控制中心访问令牌
-
-### 可选参数
-以下是默认启用的可选参数：
- `enable_cc`：启用控制中心（默认 true）
- `enable_tls`：启用 TLS（默认 true）
- `enable_cc_tls`：启用控制中心 TLS（默认 true）
- `enable_keepalive`：保持连接（默认 true）
- `enable_1gb_pages`：使用大页内存（默认 true）
-
-## 2. 安装 XXXigCC
-
-### 步骤
-1. 准备 Ansible Playbook：`xxxigcc_install.yaml`
-2. 配置必填和可选参数
-3. 使用命令执行：
-   ```bash
-   ansible-playbook xxxigcc_install.yaml -e pool_url=http://example.com -e cc_url=http://control.center -e cc_token=your_token
-   ```
-
-## 3. 卸载 XXXigCC
-
-### 步骤
-1. 准备 Ansible Playbook：`xxxigcc_uninstall.yaml`
-2. 执行卸载命令：
-   ```bash
-   ansible-playbook xxxigcc_uninstall.yaml
-   ```
-
-### 注意事项
- 卸载将完全删除 XXXigCC 及其相关组件
- 使用 `-y --purge` 参数确保彻底卸载
-
-## 4. 验证部署
-
- 检查安装/卸载输出日志
- 验证服务运行状态
@@ -1,33 +0,0 @@
-# 安全最佳实践指南
-
-## 1. 权限管理
-
-### Sudo 权限使用
-1. **始终** 使用 `become: yes`
-2. 仅在必要时提升权限
-3. 避免使用全局 root 权限
-
-### 脚本下载安全
-1. 始终启用证书验证 `validate_certs: yes`
-2. 限制下载脚本权限 `mode: '0755'`
-3. 使用 HTTPS 下载源
-
-## 2. 日志安全
-
-### 日志配置最佳实践
-1. 限制日志总大小（默认 500M）
-2. 控制单个日志文件大小（默认 100M）
-3. 设置日志保留期限（默认 7 天）
-4. 启用日志速率限制
-
-### 防御策略
-1. 防止日志炸弹攻击
-2. 定期审查日志配置
-3. 备份重要日志
-
-## 3. 安全检查清单
-
- [ ] 验证所有下载脚本的来源
- [ ] 检查 sudo 权限使用范围
- [ ] 审核日志配置
- [ ] 定期更新和补丁
@@ -1,44 +0,0 @@
-# 如何使用动态参数构建模式
-
-## 前提条件
-
- 已安装 Ansible
- 拥有 Ansible Playbook 的执行权限
-
-## 步骤指南
-
-1. **定义必填参数**
-   ```yaml
-   vars:
-     pool_url: "https://your-pool-url.com"
-     cc_url: "https://your-cc-url.com"
-     cc_token: "your-secret-token"
-   ```
-
-2. **配置可选参数**
-   ```yaml
-   vars:
-     enable_cc: true           # 启用控制中心
-     enable_tls: true          # 启用传输层安全
-     enable_keepalive: false   # 关闭长连接
-     enable_1gb_pages: true    # 启用大页内存
-   ```
-
-3. **理解参数影响**
-   - `true` 将添加对应的命令行参数
-   - `false` 将移除对应的命令行参数
-
-4. **执行 Playbook**
-   ```bash
-   ansible-playbook xxxigcc_install.yaml
-   ```
-
-## 高级技巧
-
- 可以在 `group_vars` 或 `host_vars` 中预置默认配置
- 支持复杂的条件参数，如仅在特定条件下启用 TLS
-
-## 常见陷阱
-
- 确保 `pool_url`、`cc_url`、`cc_token` 正确配置
- 布尔参数默认为 `true`，需要显式设置为 `false` 才会禁用
@@ -1,50 +0,0 @@
-# 如何使用项目文档和示例
-
-## 1. 文档目录 (docs/)
-
-`docs/` 目录提供了详细的用户文档，包括：
-
- `nezha_update_secret_README.md`: Nezha Agent 配置更新指南
- `QUICKSTART_nezha.md`: Nezha Agent 快速入门指南
- `README.md`: 项目文档入口
-
-### 使用建议
-
-1. 首先阅读 `README.md`，了解项目整体情况
-2. 根据需求查看相应的专项文档
-3. 遵循文档中的操作步骤和最佳实践
-
-## 2. 示例目录 (examples/)
-
-`examples/` 目录包含各种配置文件示例：
-
- `inventory.example.ini`: Ansible Inventory 配置示例
- `nezha_vars.example.yml`: Nezha Agent 变量配置示例
- `xxxigcc_vars.example.yml`: XXXigCC 部署变量示例
- `journald_vars.example.yml`: Journald 配置变量示例
-
-### 使用步骤
-
-1. 复制相应的 `.example` 文件
-2. 根据自己的环境修改配置
-3. 在 Playbook 执行时使用修改后的配置文件
-
-## 3. 快速复制配置示例
-
-```bash
-# 复制 Nezha Agent 变量示例
-cp examples/nezha_vars.example.yml nezha_vars.yml
-
-# 编辑配置文件
-vim nezha_vars.yml
-
-# 使用配置文件执行 Playbook
-ansible-playbook nezha_update_secret.yml -e @nezha_vars.yml
-```
-
-## 4. 推荐实践
-
- 始终保留 `.example` 文件作为参考
- 将个性化配置文件添加到 `.gitignore`
- 不要直接修改示例文件
- 为不同的环境创建不同的配置文件副本
@@ -1,76 +0,0 @@
-# 如何更新 XXXigCC 的 Pool URL
-
-## 0. 版本兼容性
-
-**重要提示**：
- 支持 Ansible 2.14 及以上版本
- 已移除 `warn: false` 参数，确保兼容性
- 使用 `ansible.builtin.shell` 模块替代传统 `command` 模块
-
-## 1. 准备工作
-
-在更新 XXXigCC 的 Pool URL 之前，请确保：
- 已安装 Ansible 2.14 或更高版本
- 已安装 `jq` 工具
- 有权限修改 `/etc/xxxigcc/config.json`
- 有权限重启 `xxxigcc-daemon.service`
-
-## 2. 更新步骤
-
-1. **准备变量文件**：
-   创建一个 `xxxigcc_update_vars.yml` 文件，包含以下关键变量：
-   ```yaml
-   new_pool_url: "https://new-pool.example.com"
-   # 可选：验证旧 URL（如需）
-   old_pool_url: "https://old-pool.example.com"
-   ```
-
-2. **执行 Playbook**：
-   ```bash
-   ansible-playbook xxxigcc_update_pool_url.yaml -e @xxxigcc_update_vars.yml
-   ```
-
-## 3. 操作说明
-
- Playbook 将自动备份原始配置文件
- 更新 `pools[0].url` 字段
- 清理 `/var/log/xxxigcc` 目录下的日志文件
- 重启 `xxxigcc-daemon.service`
-
-## 4. 故障排除
-
- 如果更新失败，检查：
-  1. 变量文件格式
-  2. URL 地址正确性
-  3. 系统权限
-  4. Ansible 版本兼容性
-
-### 常见错误处理
-
-#### Stat 模块属性访问问题
-
- **错误**：`'dict object' has no attribute 'isdir'`
- **原因**：Ansible stat 模块返回嵌套字典结构
- **解决方案**：始终使用 `log_dir_stat.stat.isdir` 而非 `log_dir_stat.isdir`
-
-示例修复：
-```yaml
- name: 检查日志目录
-  ansible.builtin.stat:
-    path: "/var/log/xxxigcc"
-  register: log_dir_stat
-
-# 正确的条件判断
- name: 处理日志目录
-  when: log_dir_stat.stat.exists and log_dir_stat.stat.isdir
-  block:
-    - name: 清理日志
-      # 清理操作
-```
-
-## 5. 安全注意事项
-
- 仅在可信环境中执行此 Playbook
- 谨慎使用 `old_pool_url` 参数
- 确保 Ansible 版本满足最低要求
- 注意处理 stat 模块返回的嵌套字典属性
@@ -1,27 +0,0 @@
-# 如何使用 xxxigcc_update.yaml Playbook
-
-## 前置条件
-1. 已安装 Ansible
-2. 已配置 APT 软件仓库（使用 gitea_repo_setup.yaml）
-
-## 使用步骤
-
-1. **准备工作**
-   ```bash
-   # 确保 Ansible 已正确安装
-   ansible --version
-   ```
-
-2. **执行 Playbook**
-   ```bash
-   ansible-playbook xxxigcc_update.yaml
-   ```
-
-3. **验证服务状态**
-   - Playbook 将自动检查并报告 xxxigcc-daemon 服务状态
-   - 查看详细输出以确认服务正常运行
-
-## 注意事项
- 此 Playbook 支持幂等执行
- 可重复运行，不会影响已配置的服务
- 始终检查 Ansible 输出，确保没有错误
@@ -1,12 +0,0 @@
-# Ansible Playbook 文档索引
-
-## 核心组件
- `gitea_repo_setup.yaml`: APT 仓库配置
- `xxxigcc_update.yaml`: xxxigcc 软件包更新与服务管理
- `xxxigcc_update_pool_url.yaml`: 服务配置更新
-
-## 文档目录
- [项目概览](/overview/project-overview.md)
- [指南](/guides/)
- [架构](/architecture/)
- [参考](/reference/)
@@ -1,13 +0,0 @@
-# Ansible Playbook 项目概览
-
-## 1. 身份定义
- **项目目的**: 通过自动化 Ansible Playbook 简化 Linux 服务器配置和管理
- **核心功能**: 自动化软件包管理、仓库配置和服务部署
-
-## 2. 高级描述
-本项目提供了一组模块化的 Ansible Playbook，专注于简化 Linux 服务器的软件包管理和服务配置。通过标准化和自动化的方法，降低系统管理复杂性。
-
-## 3. 核心组件
- `gitea_repo_setup.yaml`: 配置并管理 APT 软件仓库
- `xxxigcc_update.yaml`: 更新并管理 xxxigcc 软件包及其服务
- `xxxigcc_update_pool_url.yaml`: 动态更新服务配置
@@ -1,47 +0,0 @@
-# Ansible 模块参考
-
-## 核心模块列表
-
-### 1. ansible.builtin.set_fact
- **用途**：动态构建和设置变量
- **示例**：`ansible.builtin.set_fact: install_command="..."`
-
-### 2. ansible.builtin.debug
- **用途**：输出调试信息和变量
- **关键参数**：
-  - `msg`：直接打印消息
-  - `var`：打印变量值
-
-### 3. ansible.builtin.get_url
- **用途**：从远程 URL 下载文件
- **关键参数**：
-  - `url`：文件源地址
-  - `dest`：目标路径
-  - `mode`：文件权限
-
-### 4. ansible.builtin.shell
- **用途**：执行复杂的 Shell 命令
- **注意事项**：
-  - 比 `command` 模块更灵活
-  - 支持管道和重定向
-
-### 5. ansible.builtin.file
- **用途**：文件和目录管理
- **常用状态**：
-  - `present`：确保文件存在
-  - `absent`：确保文件不存在
-  - `directory`：确保目录存在
-
-## 使用场景映射
-
- 文件下载：`get_url`
- 动态参数：`set_fact`
- 命令执行：`shell`
- 日志记录：`debug`
- 文件清理：`file`
-
-## 最佳实践提示
-
-1. 优先使用专用模块
-2. 谨慎使用 `shell` 模块
-3. 始终关注安全性和幂等性
@@ -1,52 +0,0 @@
-# Ansible 版本兼容性参考
-
-## 版本兼容性矩阵
-
-| Ansible 版本 | 状态   | 主要变更                     | 兼容性级别 |
-|------------|---------|-----------------------------|------------|
-| 2.9 及以下   | 不推荐  | 传统模块实现                 | 低         |
-| 2.10-2.13  | 部分兼容 | 模块命名空间变更              | 中         |
-| 2.14+      | 推荐    | 废弃 `warn` 参数，模块规范化   | 高         |
-
-## 关键变更详情
-
-### 模块属性访问
-
-Ansible stat 模块返回的是嵌套字典结构，访问属性时需要注意：
-
- **错误示例**：`log_dir_stat.isdir`
- **正确示例**：`log_dir_stat.stat.isdir`
-
-原因：
- stat 模块返回一个包含 `stat` 子字典的对象
- 必须通过 `stat` 子字典访问文件/目录属性
- 直接访问根对象属性会导致 `'dict object' has no attribute` 错误
-
-### `warn` 参数的移除
-
- **版本**：Ansible 2.14
- **影响模块**：`command` 和 `shell`
- **变更原因**：简化模块接口，提高安全性
-
-#### 迁移指南
-
-1. 移除 `warn: false`
-2. 使用 `ansible.builtin.shell` 替代
-3. 调整执行策略
-
-### 模块命名空间变更
-
- 从 `command` → `ansible.legacy.command`
- 推荐使用 `ansible.builtin.shell`
-
-## 最佳实践
-
- 始终使用最新的 Ansible 版本
- 定期检查并更新 Playbook
- 使用 `ansible_version` 进行版本兼容性检查
- 谨慎访问模块返回的嵌套字典属性
-
-## 参考资源
-
- [Ansible 官方版本发行说明](https://docs.ansible.com/ansible/latest/release_notes/index.html)
- [Ansible 模块迁移指南](https://docs.ansible.com/ansible/latest/dev_guide/module_lifecycle.html)
@@ -1,65 +0,0 @@
-# Ansible 与 YAML 编码规范
-
-## YAML 格式规范
-
-### 基本格式
- 使用 `---` 作为 YAML 文件开头
- 缩进严格使用 **2 个空格**
- 禁止使用制表符 `\t`
- 保持每行末尾无多余空白
-
-### 文件命名
- Playbook 文件使用 `snake_case`
- 文件扩展名为 `.yml`
-
-## Ansible 编码规范
-
-### 变量命名
- 变量名使用 `snake_case`
- 布尔变量使用肯定语气命名，如 `enable_feature`
- 使用有意义的、描述性的变量名
-
-### Playbook 结构
- 每个 Playbook 应包含:
-  1. `name`: 描述性标题
-  2. `hosts`: 目标主机
-  3. `vars`: 变量定义区
-  4. `tasks`: 任务列表
-  5. 可选 `handlers`: 触发的服务重启/重载任务
-
-### 任务编写
- 每个任务使用 `name` 描述具体操作
- 优先使用 `ansible.builtin` 模块
- 添加 `when` 条件控制任务执行
- 使用 `register` 捕获任务输出
- 通过 `changed_when: false` 控制任务变更状态
-
-### 注释规范
- 使用 `#` 添加注释
- 注释应解释"为什么"，而非"做什么"
- 在复杂配置处添加必要的注释说明
-
-### 安全与最佳实践
- 使用 `become: yes` 控制权限提升
- 避免硬编码敏感信息
- 使用 `no_log: true` 隐藏敏感输出
- 合理使用 `backup: yes` 保护现有配置
-
-## 示例代码风格
-```yaml
---
- name: 配置服务
-  hosts: servers
-  become: yes
-
-  vars:
-    service_port: 8080
-    enable_monitoring: true
-
-  tasks:
-    - name: 部署服务配置
-      ansible.builtin.template:
-        src: config.j2
-        dest: /etc/service/config.yml
-      when: enable_monitoring
-```
@@ -1,31 +0,0 @@
-# Git 约定参考
-
-## 分支策略
-
- **主分支:** `main`
- **分支管理:** 直接在 `main` 分支上提交更改
-
-## Commit Message 规范
-
-### 消息风格
- 使用简体中文
- 简洁描述更改内容
- 消息格式示例：
-  - `添加执行参数`
-  - `添加`
-
-### Commit 模式
- 提交频率：较低，主要捕捉重要功能和变更
- 提交者：单一开发者（Wang Defa）
-
-## 版本管理
-
- **当前版本管理方式:** 简单、直接
- **特点:** 轻量级提交，无复杂的分支管理
- **建议:** 考虑引入更结构化的版本控制流程
-
-## 最佳实践建议
-
-1. 保持 Commit Message 简洁明了
-2. 每次提交聚焦于单一功能或修复
-3. 考虑添加更详细的变更描述
@@ -1,34 +0,0 @@
-# Jinja2 参数构建模式参考
-
-## 1. 条件参数生成基本模式
-
-### 布尔开关模式
-```yaml
-{{ '--flag' if boolean_var else '' }}
-```
-
-### 带值参数模式
-```yaml
-{{ '--param ' + value if condition else '' }}
-```
-
-## 2. 复合条件示例
-
-```yaml
-{{ '--cc-tls' if enable_cc and enable_cc_tls else '' }}
-```
-
-## 3. 参数构建最佳实践
-
- 使用三元运算符 `if-else`
- 避免使用复杂的嵌套条件
- 保持参数生成逻辑简洁明了
-
-## 4. 性能与可读性
-
- Jinja2 条件语法开销极小
- 比传统编程逻辑更加声明式和直观
-
-## 5. 源代码参考
-
- `xxxigcc_install.yaml:25-34`: 动态参数构建的实际实现
@@ -1,53 +0,0 @@
-# Journald 配置参数参考
-
-## 核心摘要
-
-本文档提供了 systemd-journald 日志配置的详细参数参考，旨在帮助开发者和系统管理员精确控制日志行为。
-
-## 参数列表
-
-### 空间管理参数
-
-1. **SystemMaxUse**
-   - **描述：** 日志总体使用空间上限
-   - **默认值：** "500M"
-   - **类型：** 存储大小（字节/K/M/G）
-   - **作用：** 限制所有日志条目占用的总磁盘空间
-
-2. **SystemMaxFileSize**
-   - **描述：** 单个日志文件大小限制
-   - **默认值：** "100M"
-   - **类型：** 存储大小（字节/K/M/G）
-   - **作用：** 控制单个日志文件的最大尺寸
-
-### 保留和过期策略
-
-3. **MaxRetentionSec**
-   - **描述：** 日志保留时间
-   - **默认值：** "7day"
-   - **类型：** 时间间隔（秒/分钟/小时/天）
-   - **作用：** 确定日志保留的最长时间
-
-### 速率控制参数
-
-4. **RateLimitIntervalSec**
-   - **描述：** 日志速率限制时间间隔
-   - **默认值：** "30s"
-   - **类型：** 时间间隔
-   - **作用：** 定义速率限制的时间窗口
-
-5. **RateLimitBurst**
-   - **描述：** 日志突发速率限制
-   - **默认值：** "10000"
-   - **类型：** 整数
-   - **作用：** 在指定时间间隔内允许的最大日志条目数
-
-## 源代码引用
-
- **主要配置文件：** `journald_configure.yml`
- **架构文档：** `/llmdoc/architecture/journald-configuration-flow.md`
-
-## 相关架构文档
-
- [Journald 配置流程架构](/llmdoc/architecture/journald-configuration-flow.md)
- [Journald 配置指南](/llmdoc/guides/how-to-configure-journald.md)
@@ -1,25 +0,0 @@
-# 安全检查清单
-
-## 1. 权限管理检查
-
-### Sudo 和权限提升
- [ ] 所有 Playbook 是否正确使用 `become: yes`
- [ ] 权限提升是否遵循最小权限原则
- [ ] 是否有不必要的全局 root 权限使用
-
-## 2. 脚本下载安全
- [ ] 所有脚本下载是否启用 `validate_certs: yes`
- [ ] 下载脚本权限是否正确设置（`mode: '0755'`）
- [ ] 下载源是否可信且使用 HTTPS
-
-## 3. 日志安全配置
- [ ] 日志总大小限制是否合理（默认 500M）
- [ ] 单个日志文件大小限制（默认 100M）
- [ ] 日志保留期限设置（默认 7 天）
- [ ] 日志速率限制是否正确配置
-
-## 4. 常规安全审计
- [ ] 定期检查并更新安全配置
- [ ] 审核所有自动化脚本
- [ ] 检查证书和加密设置
- [ ] 监控异常日志和访问行为
@@ -1,31 +0,0 @@
-# XXXigCC 部署参数参考
-
-## 1. 核心摘要
-XXXigCC 的部署采用高度灵活的参数配置机制，支持多种功能开关和高级配置选项。
-
-## 2. 参数分类
-
-### 必填参数
-| 参数名称 | 描述 | 示例 |
-|---------|------|------|
-| `pool_url` | 资源池 URL | `http://pool.example.com` |
-| `cc_url` | 控制中心 URL | `https://control.center` |
-| `cc_token` | 控制中心访问令牌 | `secret-token-123` |
-
-### 可选布尔参数
-| 参数名称 | 默认值 | 功能描述 |
-|---------|--------|----------|
-| `enable_cc` | true | 启用控制中心功能 |
-| `enable_tls` | true | 启用传输层安全 |
-| `enable_cc_tls` | true | 控制中心启用 TLS |
-| `enable_keepalive` | true | 维持长连接 |
-| `enable_1gb_pages` | true | 使用大页内存 |
-
-## 3. 来源真相
- 主要代码：`xxxigcc_install.yaml` - 定义参数和安装逻辑
- 安装脚本：`https://gitea.bcde.io/wangdefa/xxxigcc/raw/branch/main/script/install.deb.sh`
- 卸载脚本：`https://gitea.bcde.io/wangdefa/xxxigcc/raw/branch/main/script/uninstall.sh`
-
-## 4. 外部文档
- 功能规范文档：待补充
- 性能配置指南：待补充
@@ -1,17 +0,0 @@
-# xxxigcc 更新 Playbook 参考
-
-## 核心摘要
-本文档提供 `xxxigcc_update.yaml` Playbook 的参考信息，包括关键操作和设计决策。
-
-## 真实来源
- **主要 Playbook**: `xxxigcc_update.yaml`
- **相关配置**: `ansible.cfg`（如有）
-
-## 详细操作
- **APT 更新**: `ansible.builtin.apt: update_cache=yes`
- **软件包管理**: `ansible.builtin.apt: name=xxxigcc state=latest`
- **服务控制**: `ansible.builtin.systemd: name=xxxigcc-daemon enabled=yes state=started`
-
-## 外部链接
- [Ansible APT 模块文档](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/apt_module.html)
- [Ansible Systemd 模块文档](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/systemd_module.html)
@@ -0,0 +1,98 @@
+---
+- name: 重装 Nezha Agent（卸载旧版本并安装新版本）
+  hosts: all
+  become: yes
+
+  vars:
+    # Nezha 服务端地址（host:port）
+    nz_server: "dash.miner.vvvo.net:443"
+
+    # 是否启用 TLS
+    nz_tls: true
+
+    # 客户端密钥（必填，建议通过 -e 或 vars 文件传入，勿硬编码到仓库）
+    nz_client_secret: ""
+
+    # 安装脚本 URL
+    install_script_url: "https://raw.githubusercontent.com/wangdefaa/nezha-agent/refs/heads/main/script/install.sh"
+
+    # 服务与路径配置
+    service_name: "nezha-agent.service"
+    service_file: "/etc/systemd/system/nezha-agent.service"
+    install_dir: "/opt/nezha"
+    script_path: "/tmp/nezha-agent.sh"
+
+  tasks:
+    # ---------- 参数校验 ----------
+    - name: 验证必填参数
+      ansible.builtin.assert:
+        that:
+          - nz_client_secret | length > 0
+        fail_msg: "参数 nz_client_secret 不能为空"
+        success_msg: "参数验证通过"
+
+    # ---------- 卸载旧版本 ----------
+    - name: 检查服务单元文件是否存在
+      ansible.builtin.stat:
+        path: "{{ service_file }}"
+      register: service_file_stat
+
+    - name: 停止并禁用 Nezha Agent 服务
+      ansible.builtin.systemd:
+        name: "{{ service_name }}"
+        state: stopped
+        enabled: no
+      when: service_file_stat.stat.exists
+
+    - name: 删除服务单元文件
+      ansible.builtin.file:
+        path: "{{ service_file }}"
+        state: absent
+      register: unit_removed
+
+    - name: 重新加载 systemd 配置
+      ansible.builtin.systemd:
+        daemon_reload: yes
+      when: unit_removed.changed
+
+    - name: 删除安装目录
+      ansible.builtin.file:
+        path: "{{ install_dir }}"
+        state: absent
+
+    # ---------- 安装新版本 ----------
+    - name: 下载安装脚本
+      ansible.builtin.get_url:
+        url: "{{ install_script_url }}"
+        dest: "{{ script_path }}"
+        mode: '0755'
+        force: yes
+
+    - name: 执行安装脚本
+      ansible.builtin.shell: "bash {{ script_path }}"
+      args:
+        executable: /bin/bash
+      environment:
+        NZ_SERVER: "{{ nz_server }}"
+        NZ_TLS: "{{ nz_tls | lower }}"
+        NZ_CLIENT_SECRET: "{{ nz_client_secret }}"
+      register: install_output
+
+    - name: 显示安装结果
+      ansible.builtin.debug:
+        var: install_output.stdout_lines
+
+    - name: 清理临时脚本
+      ansible.builtin.file:
+        path: "{{ script_path }}"
+        state: absent
+
+    # ---------- 验证 ----------
+    - name: 验证 Nezha Agent 服务状态
+      ansible.builtin.systemd:
+        name: "{{ service_name }}"
+      register: service_status
+
+    - name: 显示服务状态
+      ansible.builtin.debug:
+        msg: "Nezha Agent 服务状态: {{ service_status.status.ActiveState }}"
@@ -1,93 +0,0 @@
---
- name: 更新 Nezha Agent Client Secret
-  hosts: all
-  become: yes
-
-  vars:
-    # 必填参数：新的 client_secret 值
-    client_secret: ""
-
-    # 可选参数：旧的 client_secret 值（用于验证）
-    # 留空则强制修改，无论当前值是什么
-    old_client_secret: ""
-
-    # 配置文件路径
-    config_file: "/opt/nezha/agent/config.yml"
-
-    # 服务名称
-    service_name: "nezha-agent.service"
-
-  tasks:
-    - name: 验证必填参数
-      ansible.builtin.assert:
-        that:
-          - client_secret is defined
-          - client_secret | length > 0
-        fail_msg: "参数 client_secret 不能为空"
-        success_msg: "参数验证通过"
-
-    - name: 检查配置文件是否存在
-      ansible.builtin.stat:
-        path: "{{ config_file }}"
-      register: config_file_stat
-
-    - name: 配置文件不存在时报错
-      ansible.builtin.fail:
-        msg: "配置文件 {{ config_file }} 不存在"
-      when: not config_file_stat.stat.exists
-
-    - name: 备份原始配置文件
-      ansible.builtin.copy:
-        src: "{{ config_file }}"
-        dest: "{{ config_file }}.backup.{{ ansible_date_time.iso8601_basic_short }}"
-        remote_src: yes
-        force: no
-
-    - name: 更新 client_secret（不验证旧值）
-      ansible.builtin.lineinfile:
-        path: "{{ config_file }}"
-        regexp: '^client_secret:\s*.+$'
-        line: "client_secret: {{ client_secret }}"
-        backup: yes
-      when: old_client_secret == ""
-      notify: 重启 Nezha Agent
-      register: update_result_force
-
-    - name: 更新 client_secret（验证旧值）
-      ansible.builtin.lineinfile:
-        path: "{{ config_file }}"
-        regexp: '^client_secret:\s*{{ old_client_secret | regex_escape }}$'
-        line: "client_secret: {{ client_secret }}"
-        backup: yes
-      when: old_client_secret != ""
-      notify: 重启 Nezha Agent
-      register: update_result_safe
-
-    - name: 检查是否成功替换（验证旧值模式）
-      ansible.builtin.fail:
-        msg: "未找到匹配的旧 client_secret 值，请检查 old_client_secret 参数是否正确"
-      when:
-        - old_client_secret != ""
-        - update_result_safe is defined
-        - not update_result_safe.changed
-
-    - name: 显示更新结果
-      ansible.builtin.debug:
-        msg: "client_secret 已成功更新"
-      when: (update_result_force is defined and update_result_force.changed) or
-            (update_result_safe is defined and update_result_safe.changed)
-
-    - name: 验证 Nezha Agent 服务状态
-      ansible.builtin.systemd:
-        name: "{{ service_name }}"
-      register: service_status
-
-    - name: 显示服务状态
-      ansible.builtin.debug:
-        msg: "Nezha Agent 服务状态: {{ service_status.status.ActiveState }}"
-
-  handlers:
-    - name: 重启 Nezha Agent
-      ansible.builtin.systemd:
-        name: "{{ service_name }}"
-        state: restarted
@@ -1,93 +0,0 @@
---
- name: 更新 Nezha Agent Client Secret (使用 replace 模块)
-  hosts: all
-  become: yes
-
-  vars:
-    # 必填参数：新的 client_secret 值
-    client_secret: ""
-
-    # 可选参数：旧的 client_secret 值（用于验证）
-    # 留空则强制修改，无论当前值是什么
-    old_client_secret: ""
-
-    # 配置文件路径
-    config_file: "/opt/nezha/agent/config.yml"
-
-    # 服务名称
-    service_name: "nezha-agent.service"
-
-  tasks:
-    - name: 验证必填参数
-      ansible.builtin.assert:
-        that:
-          - client_secret is defined
-          - client_secret | length > 0
-        fail_msg: "参数 client_secret 不能为空"
-        success_msg: "参数验证通过"
-
-    - name: 检查配置文件是否存在
-      ansible.builtin.stat:
-        path: "{{ config_file }}"
-      register: config_file_stat
-
-    - name: 配置文件不存在时报错
-      ansible.builtin.fail:
-        msg: "配置文件 {{ config_file }} 不存在"
-      when: not config_file_stat.stat.exists
-
-    - name: 备份原始配置文件
-      ansible.builtin.copy:
-        src: "{{ config_file }}"
-        dest: "{{ config_file }}.backup.{{ ansible_date_time.iso8601_basic_short }}"
-        remote_src: yes
-        force: no
-
-    - name: 更新 client_secret（不验证旧值）
-      ansible.builtin.replace:
-        path: "{{ config_file }}"
-        regexp: '^(client_secret:)\s*.+$'
-        replace: '\1 {{ client_secret }}'
-        backup: yes
-      when: old_client_secret == ""
-      notify: 重启 Nezha Agent
-      register: update_result_force
-
-    - name: 更新 client_secret（验证旧值）
-      ansible.builtin.replace:
-        path: "{{ config_file }}"
-        regexp: '^(client_secret:)\s*{{ old_client_secret | regex_escape }}$'
-        replace: '\1 {{ client_secret }}'
-        backup: yes
-      when: old_client_secret != ""
-      notify: 重启 Nezha Agent
-      register: update_result_safe
-
-    - name: 检查是否成功替换（验证旧值模式）
-      ansible.builtin.fail:
-        msg: "未找到匹配的旧 client_secret 值，请检查 old_client_secret 参数是否正确"
-      when:
-        - old_client_secret != ""
-        - update_result_safe is defined
-        - update_result_safe.changed == false
-
-    - name: 显示更新结果
-      ansible.builtin.debug:
-        msg: "client_secret 已成功更新"
-      when: (update_result_force is defined and update_result_force.changed) or
-            (update_result_safe is defined and update_result_safe.changed)
-
-    - name: 验证 Nezha Agent 服务状态
-      ansible.builtin.systemd:
-        name: "{{ service_name }}"
-      register: service_status
-
-    - name: 显示服务状态
-      ansible.builtin.debug:
-        msg: "Nezha Agent 服务状态: {{ service_status.status.ActiveState }}"
-
-  handlers:
-    - name: 重启 Nezha Agent
-      ansible.builtin.systemd:
-        name: "{{ service_name }}"
-        state: restarted