添加 Nezha Agent 管理功能和完整文档系统
- 新增 Nezha Agent client_secret 更新 playbook（两种实现方案） - 建立三层文档架构：docs/（用户文档）、examples/（配置示例）、llmdoc/（技术文档） - 添加项目主 README.md 和配置示例文件 - 初始化 .gitignore 保护敏感信息
This commit is contained in:
Wang Defa
200
docs/QUICKSTART_nezha.md
Normal file
200
docs/QUICKSTART_nezha.md
Normal file
@@ -0,0 +1,200 @@
|
||||
# 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=你的新密钥"
|
||||
```
|
||||
106
docs/README.md
Normal file
106
docs/README.md
Normal file
@@ -0,0 +1,106 @@
|
||||
# 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分钟快速开始
|
||||
- 快速上手步骤
|
||||
- 常见使用场景
|
||||
- 故障排查指南
|
||||
|
||||
## 🔍 查找文档
|
||||
|
||||
### 按需求查找
|
||||
|
||||
| 我想... | 查看文档 |
|
||||
|---------|----------|
|
||||
| 快速更新 Nezha Agent | [快速开始](QUICKSTART_nezha.md) |
|
||||
| 了解所有功能和参数 | [完整文档](nezha_update_secret_README.md) |
|
||||
| 查看配置示例 | [examples/](../examples/) |
|
||||
| 了解项目架构 | [llmdoc/architecture/](../llmdoc/architecture/) |
|
||||
| 学习最佳实践 | [llmdoc/guides/](../llmdoc/guides/) |
|
||||
|
||||
## 📖 文档组织
|
||||
|
||||
本项目采用分层文档结构:
|
||||
|
||||
```
|
||||
docs/ # 用户文档（人类友好）
|
||||
├── nezha_update_secret_README.md
|
||||
└── QUICKSTART_nezha.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)。
|
||||
225
docs/nezha_update_secret_README.md
Normal file
225
docs/nezha_update_secret_README.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# 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)，除非有特殊的正则表达式需求。
|
||||
|
||||
## 许可证
|
||||
|
||||
遵循项目主许可证
|
||||
Reference in New Issue
Block a user