From 8f03780bfb9a9b28162e695bcbb3f98659c53736 Mon Sep 17 00:00:00 2001 From: Wang Defa Date: Mon, 29 Jun 2026 15:38:00 +0800 Subject: [PATCH] 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. --- README.md | 272 ++-------------- docs/QUICKSTART_nezha.md | 200 ------------ docs/README.md | 116 ------- docs/nezha_update_secret_README.md | 225 -------------- docs/xxxigcc_update_pool_url_README.md | 294 ------------------ examples/README.md | 93 ------ examples/gitea_repo_setup_vars.example.yml | 9 + examples/inventory.example.ini | 35 --- ...ml => journald_configure_vars.example.yml} | 11 +- examples/nezha_reinstall_vars.example.yml | 14 + examples/nezha_vars.example.yml | 17 - examples/xxxig_install_vars.example.yml | 19 ++ examples/xxxig_update_vars.example.yml | 8 + .../xxxigcc_update_pool_url_vars.example.yml | 19 -- examples/xxxigcc_vars.example.yml | 17 - journald_configure.yml | 2 +- .../architecture/ansible-project-structure.md | 71 ----- .../dynamic-parameter-building.md | 37 --- .../journald-configuration-flow.md | 48 --- llmdoc/architecture/repo-configuration.md | 38 --- llmdoc/architecture/security-architecture.md | 38 --- .../xxxigcc-deployment-architecture.md | 31 -- .../architecture/xxxigcc-update-playbook.md | 30 -- llmdoc/guides/ansible-best-practices.md | 59 ---- llmdoc/guides/gitea-repo-configuration.md | 38 --- llmdoc/guides/how-to-configure-journald.md | 64 ---- llmdoc/guides/how-to-deploy-xxxigcc.md | 44 --- llmdoc/guides/security-best-practices.md | 33 -- llmdoc/guides/using-dynamic-parameters.md | 44 --- llmdoc/guides/using-project-documentation.md | 50 --- llmdoc/guides/xxxigcc-pool-url-update.md | 76 ----- llmdoc/guides/xxxigcc-update-guide.md | 27 -- llmdoc/index.md | 12 - llmdoc/overview/project-overview.md | 13 - llmdoc/reference/ansible-modules-used.md | 47 --- .../ansible-version-compatibility.md | 52 ---- llmdoc/reference/coding-conventions.md | 65 ---- llmdoc/reference/git-conventions.md | 31 -- llmdoc/reference/jinja2-parameter-patterns.md | 34 -- llmdoc/reference/journald-parameters.md | 53 ---- llmdoc/reference/security-checklist.md | 25 -- llmdoc/reference/xxxigcc-parameters.md | 31 -- llmdoc/reference/xxxigcc-update-reference.md | 17 - nezha_reinstall.yml | 98 ++++++ nezha_update_secret.yml | 93 ------ nezha_update_secret_v2.yml | 93 ------ 46 files changed, 183 insertions(+), 2560 deletions(-) delete mode 100644 docs/QUICKSTART_nezha.md delete mode 100644 docs/README.md delete mode 100644 docs/nezha_update_secret_README.md delete mode 100644 docs/xxxigcc_update_pool_url_README.md delete mode 100644 examples/README.md create mode 100644 examples/gitea_repo_setup_vars.example.yml delete mode 100644 examples/inventory.example.ini rename examples/{journald_vars.example.yml => journald_configure_vars.example.yml} (67%) create mode 100644 examples/nezha_reinstall_vars.example.yml delete mode 100644 examples/nezha_vars.example.yml create mode 100644 examples/xxxig_install_vars.example.yml create mode 100644 examples/xxxig_update_vars.example.yml delete mode 100644 examples/xxxigcc_update_pool_url_vars.example.yml delete mode 100644 examples/xxxigcc_vars.example.yml delete mode 100644 llmdoc/architecture/ansible-project-structure.md delete mode 100644 llmdoc/architecture/dynamic-parameter-building.md delete mode 100644 llmdoc/architecture/journald-configuration-flow.md delete mode 100644 llmdoc/architecture/repo-configuration.md delete mode 100644 llmdoc/architecture/security-architecture.md delete mode 100644 llmdoc/architecture/xxxigcc-deployment-architecture.md delete mode 100644 llmdoc/architecture/xxxigcc-update-playbook.md delete mode 100644 llmdoc/guides/ansible-best-practices.md delete mode 100644 llmdoc/guides/gitea-repo-configuration.md delete mode 100644 llmdoc/guides/how-to-configure-journald.md delete mode 100644 llmdoc/guides/how-to-deploy-xxxigcc.md delete mode 100644 llmdoc/guides/security-best-practices.md delete mode 100644 llmdoc/guides/using-dynamic-parameters.md delete mode 100644 llmdoc/guides/using-project-documentation.md delete mode 100644 llmdoc/guides/xxxigcc-pool-url-update.md delete mode 100644 llmdoc/guides/xxxigcc-update-guide.md delete mode 100644 llmdoc/index.md delete mode 100644 llmdoc/overview/project-overview.md delete mode 100644 llmdoc/reference/ansible-modules-used.md delete mode 100644 llmdoc/reference/ansible-version-compatibility.md delete mode 100644 llmdoc/reference/coding-conventions.md delete mode 100644 llmdoc/reference/git-conventions.md delete mode 100644 llmdoc/reference/jinja2-parameter-patterns.md delete mode 100644 llmdoc/reference/journald-parameters.md delete mode 100644 llmdoc/reference/security-checklist.md delete mode 100644 llmdoc/reference/xxxigcc-parameters.md delete mode 100644 llmdoc/reference/xxxigcc-update-reference.md create mode 100644 nezha_reinstall.yml delete mode 100644 nezha_update_secret.yml delete mode 100644 nezha_update_secret_v2.yml diff --git a/README.md b/README.md index bbdf267..792030b 100644 --- a/README.md +++ b/README.md @@ -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 专注于特定任务 -- 🔧 **高度可配置** - 灵活的参数化配置 + ```ini + [all] + server1 ansible_host=192.168.1.10 ansible_user=root + ``` -## 📁 项目结构 +2. 复制对应的变量示例并按需修改： -``` -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 -``` + ```bash + cp examples/xxxig_install_vars.example.yml xxxig_install_vars.yml + # 编辑 xxxig_install_vars.yml，填入必填参数 + ``` -## 🚀 快速开始 +3. 运行 playbook： -### 1. 准备环境 + ```bash + ansible-playbook xxxig_install.yaml -i inventory.ini -e @xxxig_install_vars.yml + ``` -确保已安装 Ansible: +无变量的 playbook（如 `xxxig_uninstall.yaml`）可省略 `-e` 参数直接运行。 -```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日 +- `examples/` 下为变量模板，每个文件顶部均注明用法及必填/可选参数。 +- `inventory.ini`、`*_vars.yml` 等含主机或密钥的文件已在 `.gitignore` 中忽略，仅 `*.example.yml` 入库，请勿将真实密钥提交到仓库。 diff --git a/docs/QUICKSTART_nezha.md b/docs/QUICKSTART_nezha.md deleted file mode 100644 index dc01260..0000000 --- a/docs/QUICKSTART_nezha.md +++ /dev/null @@ -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=你的新密钥" -``` diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 096356b..0000000 --- a/docs/README.md +++ /dev/null @@ -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)。 diff --git a/docs/nezha_update_secret_README.md b/docs/nezha_update_secret_README.md deleted file mode 100644 index 834c76d..0000000 --- a/docs/nezha_update_secret_README.md +++ /dev/null @@ -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)，除非有特殊的正则表达式需求。 - -## 许可证 - -遵循项目主许可证 diff --git a/docs/xxxigcc_update_pool_url_README.md b/docs/xxxigcc_update_pool_url_README.md deleted file mode 100644 index 0e82913..0000000 --- a/docs/xxxigcc_update_pool_url_README.md +++ /dev/null @@ -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. -``` - -查看所有备份： -```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)。 diff --git a/examples/README.md b/examples/README.md deleted file mode 100644 index d237ed4..0000000 --- a/examples/README.md +++ /dev/null @@ -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` 后缀 -- 根据实际需求修改示例文件中的值 diff --git a/examples/gitea_repo_setup_vars.example.yml b/examples/gitea_repo_setup_vars.example.yml new file mode 100644 index 0000000..8760fc6 --- /dev/null +++ b/examples/gitea_repo_setup_vars.example.yml @@ -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" diff --git a/examples/inventory.example.ini b/examples/inventory.example.ini deleted file mode 100644 index be1302b..0000000 --- a/examples/inventory.example.ini +++ /dev/null @@ -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 diff --git a/examples/journald_vars.example.yml b/examples/journald_configure_vars.example.yml similarity index 67% rename from examples/journald_vars.example.yml rename to examples/journald_configure_vars.example.yml index b2f31aa..f4dbbca 100644 --- a/examples/journald_vars.example.yml +++ b/examples/journald_configure_vars.example.yml @@ -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 diff --git a/examples/nezha_reinstall_vars.example.yml b/examples/nezha_reinstall_vars.example.yml new file mode 100644 index 0000000..38b282d --- /dev/null +++ b/examples/nezha_reinstall_vars.example.yml @@ -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" diff --git a/examples/nezha_vars.example.yml b/examples/nezha_vars.example.yml deleted file mode 100644 index 25b6c76..0000000 --- a/examples/nezha_vars.example.yml +++ /dev/null @@ -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" diff --git a/examples/xxxig_install_vars.example.yml b/examples/xxxig_install_vars.example.yml new file mode 100644 index 0000000..0376227 --- /dev/null +++ b/examples/xxxig_install_vars.example.yml @@ -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" diff --git a/examples/xxxig_update_vars.example.yml b/examples/xxxig_update_vars.example.yml new file mode 100644 index 0000000..ef61126 --- /dev/null +++ b/examples/xxxig_update_vars.example.yml @@ -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" diff --git a/examples/xxxigcc_update_pool_url_vars.example.yml b/examples/xxxigcc_update_pool_url_vars.example.yml deleted file mode 100644 index 982496e..0000000 --- a/examples/xxxigcc_update_pool_url_vars.example.yml +++ /dev/null @@ -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" diff --git a/examples/xxxigcc_vars.example.yml b/examples/xxxigcc_vars.example.yml deleted file mode 100644 index 71843ad..0000000 --- a/examples/xxxigcc_vars.example.yml +++ /dev/null @@ -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" diff --git a/journald_configure.yml b/journald_configure.yml index fc58f1c..ab1019c 100644 --- a/journald_configure.yml +++ b/journald_configure.yml @@ -1,5 +1,5 @@ --- -- name: 配置 systemd-journald +- name: systemd-journald 配置脚本 hosts: all become: yes diff --git a/llmdoc/architecture/ansible-project-structure.md b/llmdoc/architecture/ansible-project-structure.md deleted file mode 100644 index 54c145c..0000000 --- a/llmdoc/architecture/ansible-project-structure.md +++ /dev/null @@ -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` 验证 -- **配置安全**：自动备份原始配置 -- **错误处理**：完整的配置和服务验证机制 \ No newline at end of file diff --git a/llmdoc/architecture/dynamic-parameter-building.md b/llmdoc/architecture/dynamic-parameter-building.md deleted file mode 100644 index cc34e0a..0000000 --- a/llmdoc/architecture/dynamic-parameter-building.md +++ /dev/null @@ -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`，降低配置复杂度 -- 使用条件语法代替显式条件判断 -- 保持参数生成逻辑集中和清晰 \ No newline at end of file diff --git a/llmdoc/architecture/journald-configuration-flow.md b/llmdoc/architecture/journald-configuration-flow.md deleted file mode 100644 index 4a9a3ea..0000000 --- a/llmdoc/architecture/journald-configuration-flow.md +++ /dev/null @@ -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`: 日志突发速率限制 \ No newline at end of file diff --git a/llmdoc/architecture/repo-configuration.md b/llmdoc/architecture/repo-configuration.md deleted file mode 100644 index 130e6e3..0000000 --- a/llmdoc/architecture/repo-configuration.md +++ /dev/null @@ -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 最佳实践 \ No newline at end of file diff --git a/llmdoc/architecture/security-architecture.md b/llmdoc/architecture/security-architecture.md deleted file mode 100644 index 1d75535..0000000 --- a/llmdoc/architecture/security-architecture.md +++ /dev/null @@ -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. 设计原理 - -- 最小权限原则 -- 安全防御性编程 -- 日志可审计性 \ No newline at end of file diff --git a/llmdoc/architecture/xxxigcc-deployment-architecture.md b/llmdoc/architecture/xxxigcc-deployment-architecture.md deleted file mode 100644 index 05bff7e..0000000 --- a/llmdoc/architecture/xxxigcc-deployment-architecture.md +++ /dev/null @@ -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、大页内存） \ No newline at end of file diff --git a/llmdoc/architecture/xxxigcc-update-playbook.md b/llmdoc/architecture/xxxigcc-update-playbook.md deleted file mode 100644 index b6f693f..0000000 --- a/llmdoc/architecture/xxxigcc-update-playbook.md +++ /dev/null @@ -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. 设计原则 -- 幂等性 -- 最小化复杂性 -- 详细日志记录 -- 错误处理和状态验证 \ No newline at end of file diff --git a/llmdoc/guides/ansible-best-practices.md b/llmdoc/guides/ansible-best-practices.md deleted file mode 100644 index 1e288db..0000000 --- a/llmdoc/guides/ansible-best-practices.md +++ /dev/null @@ -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 模块化 -- 减少重复代码 -- 添加充分的注释说明 \ No newline at end of file diff --git a/llmdoc/guides/gitea-repo-configuration.md b/llmdoc/guides/gitea-repo-configuration.md deleted file mode 100644 index dd6a3ba..0000000 --- a/llmdoc/guides/gitea-repo-configuration.md +++ /dev/null @@ -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 发行版可能需要调整 \ No newline at end of file diff --git a/llmdoc/guides/how-to-configure-journald.md b/llmdoc/guides/how-to-configure-journald.md deleted file mode 100644 index 5077f20..0000000 --- a/llmdoc/guides/how-to-configure-journald.md +++ /dev/null @@ -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` - -## 最佳实践 - -- 定期审核和调整日志配置 -- 监控日志磁盘使用情况 -- 根据系统负载动态调整参数 \ No newline at end of file diff --git a/llmdoc/guides/how-to-deploy-xxxigcc.md b/llmdoc/guides/how-to-deploy-xxxigcc.md deleted file mode 100644 index a5a8a51..0000000 --- a/llmdoc/guides/how-to-deploy-xxxigcc.md +++ /dev/null @@ -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. 验证部署 - -- 检查安装/卸载输出日志 -- 验证服务运行状态 \ No newline at end of file diff --git a/llmdoc/guides/security-best-practices.md b/llmdoc/guides/security-best-practices.md deleted file mode 100644 index 2195384..0000000 --- a/llmdoc/guides/security-best-practices.md +++ /dev/null @@ -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 权限使用范围 -- [ ] 审核日志配置 -- [ ] 定期更新和补丁 \ No newline at end of file diff --git a/llmdoc/guides/using-dynamic-parameters.md b/llmdoc/guides/using-dynamic-parameters.md deleted file mode 100644 index 355d9be..0000000 --- a/llmdoc/guides/using-dynamic-parameters.md +++ /dev/null @@ -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` 才会禁用 \ No newline at end of file diff --git a/llmdoc/guides/using-project-documentation.md b/llmdoc/guides/using-project-documentation.md deleted file mode 100644 index be3ccb6..0000000 --- a/llmdoc/guides/using-project-documentation.md +++ /dev/null @@ -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` -- 不要直接修改示例文件 -- 为不同的环境创建不同的配置文件副本 \ No newline at end of file diff --git a/llmdoc/guides/xxxigcc-pool-url-update.md b/llmdoc/guides/xxxigcc-pool-url-update.md deleted file mode 100644 index 9581e25..0000000 --- a/llmdoc/guides/xxxigcc-pool-url-update.md +++ /dev/null @@ -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 模块返回的嵌套字典属性 \ No newline at end of file diff --git a/llmdoc/guides/xxxigcc-update-guide.md b/llmdoc/guides/xxxigcc-update-guide.md deleted file mode 100644 index 7da6112..0000000 --- a/llmdoc/guides/xxxigcc-update-guide.md +++ /dev/null @@ -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 输出，确保没有错误 \ No newline at end of file diff --git a/llmdoc/index.md b/llmdoc/index.md deleted file mode 100644 index caf2131..0000000 --- a/llmdoc/index.md +++ /dev/null @@ -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/) diff --git a/llmdoc/overview/project-overview.md b/llmdoc/overview/project-overview.md deleted file mode 100644 index 5e01558..0000000 --- a/llmdoc/overview/project-overview.md +++ /dev/null @@ -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`: 动态更新服务配置 diff --git a/llmdoc/reference/ansible-modules-used.md b/llmdoc/reference/ansible-modules-used.md deleted file mode 100644 index df52401..0000000 --- a/llmdoc/reference/ansible-modules-used.md +++ /dev/null @@ -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. 始终关注安全性和幂等性 \ No newline at end of file diff --git a/llmdoc/reference/ansible-version-compatibility.md b/llmdoc/reference/ansible-version-compatibility.md deleted file mode 100644 index 5fb7f97..0000000 --- a/llmdoc/reference/ansible-version-compatibility.md +++ /dev/null @@ -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) \ No newline at end of file diff --git a/llmdoc/reference/coding-conventions.md b/llmdoc/reference/coding-conventions.md deleted file mode 100644 index 5beb203..0000000 --- a/llmdoc/reference/coding-conventions.md +++ /dev/null @@ -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 -``` \ No newline at end of file diff --git a/llmdoc/reference/git-conventions.md b/llmdoc/reference/git-conventions.md deleted file mode 100644 index a6646e8..0000000 --- a/llmdoc/reference/git-conventions.md +++ /dev/null @@ -1,31 +0,0 @@ -# Git 约定参考 - -## 分支策略 - -- **主分支:** `main` -- **分支管理:** 直接在 `main` 分支上提交更改 - -## Commit Message 规范 - -### 消息风格 -- 使用简体中文 -- 简洁描述更改内容 -- 消息格式示例： - - `添加执行参数` - - `添加` - -### Commit 模式 -- 提交频率：较低，主要捕捉重要功能和变更 -- 提交者：单一开发者（Wang Defa） - -## 版本管理 - -- **当前版本管理方式:** 简单、直接 -- **特点:** 轻量级提交，无复杂的分支管理 -- **建议:** 考虑引入更结构化的版本控制流程 - -## 最佳实践建议 - -1. 保持 Commit Message 简洁明了 -2. 每次提交聚焦于单一功能或修复 -3. 考虑添加更详细的变更描述 \ No newline at end of file diff --git a/llmdoc/reference/jinja2-parameter-patterns.md b/llmdoc/reference/jinja2-parameter-patterns.md deleted file mode 100644 index ac215a2..0000000 --- a/llmdoc/reference/jinja2-parameter-patterns.md +++ /dev/null @@ -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`: 动态参数构建的实际实现 \ No newline at end of file diff --git a/llmdoc/reference/journald-parameters.md b/llmdoc/reference/journald-parameters.md deleted file mode 100644 index 5d785b8..0000000 --- a/llmdoc/reference/journald-parameters.md +++ /dev/null @@ -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) \ No newline at end of file diff --git a/llmdoc/reference/security-checklist.md b/llmdoc/reference/security-checklist.md deleted file mode 100644 index 4899a80..0000000 --- a/llmdoc/reference/security-checklist.md +++ /dev/null @@ -1,25 +0,0 @@ -# 安全检查清单 - -## 1. 权限管理检查 - -### Sudo 和权限提升 -- [ ] 所有 Playbook 是否正确使用 `become: yes` -- [ ] 权限提升是否遵循最小权限原则 -- [ ] 是否有不必要的全局 root 权限使用 - -## 2. 脚本下载安全 -- [ ] 所有脚本下载是否启用 `validate_certs: yes` -- [ ] 下载脚本权限是否正确设置（`mode: '0755'`） -- [ ] 下载源是否可信且使用 HTTPS - -## 3. 日志安全配置 -- [ ] 日志总大小限制是否合理（默认 500M） -- [ ] 单个日志文件大小限制（默认 100M） -- [ ] 日志保留期限设置（默认 7 天） -- [ ] 日志速率限制是否正确配置 - -## 4. 常规安全审计 -- [ ] 定期检查并更新安全配置 -- [ ] 审核所有自动化脚本 -- [ ] 检查证书和加密设置 -- [ ] 监控异常日志和访问行为 \ No newline at end of file diff --git a/llmdoc/reference/xxxigcc-parameters.md b/llmdoc/reference/xxxigcc-parameters.md deleted file mode 100644 index 59ef8a6..0000000 --- a/llmdoc/reference/xxxigcc-parameters.md +++ /dev/null @@ -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. 外部文档 -- 功能规范文档：待补充 -- 性能配置指南：待补充 \ No newline at end of file diff --git a/llmdoc/reference/xxxigcc-update-reference.md b/llmdoc/reference/xxxigcc-update-reference.md deleted file mode 100644 index 25759df..0000000 --- a/llmdoc/reference/xxxigcc-update-reference.md +++ /dev/null @@ -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) \ No newline at end of file diff --git a/nezha_reinstall.yml b/nezha_reinstall.yml new file mode 100644 index 0000000..adda520 --- /dev/null +++ b/nezha_reinstall.yml @@ -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 }}" diff --git a/nezha_update_secret.yml b/nezha_update_secret.yml deleted file mode 100644 index d11a8a8..0000000 --- a/nezha_update_secret.yml +++ /dev/null @@ -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 diff --git a/nezha_update_secret_v2.yml b/nezha_update_secret_v2.yml deleted file mode 100644 index 4612484..0000000 --- a/nezha_update_secret_v2.yml +++ /dev/null @@ -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