添加 Nezha Agent 管理功能和完整文档系统
- 新增 Nezha Agent client_secret 更新 playbook（两种实现方案） - 建立三层文档架构：docs/（用户文档）、examples/（配置示例）、llmdoc/（技术文档） - 添加项目主 README.md 和配置示例文件 - 初始化 .gitignore 保护敏感信息
This commit is contained in:
Wang Defa
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