ansible-playbook/docs/nezha_update_secret_README.md

Nezha Agent Client Secret 更新工具

概述

本工具提供两个 Ansible Playbook，用于安全地更新 Nezha Agent 配置文件中的 client_secret 字段。

文件说明

• nezha_update_secret.yml (推荐)：使用 lineinfile 模块，简单可靠
• nezha_update_secret_v2.yml (备选)：使用 replace 模块，正则表达式更灵活

使用方法

方式1：强制更新（不验证旧值）

ansible-playbook nezha_update_secret.yml \
  -i inventory.ini \
  -e "client_secret=你的新密钥"

方式2：安全更新（验证旧值）

ansible-playbook nezha_update_secret.yml \
  -i inventory.ini \
  -e "client_secret=你的新密钥" \
  -e "old_client_secret=旧密钥值"

方式3：使用变量文件

创建变量文件 vars.yml:

client_secret: "HWzBMgbtWbSHdTyTVyh5U8bu3JhPmStw"
old_client_secret: "OldSecretValue123"  # 可选

执行:

ansible-playbook nezha_update_secret.yml \
  -i inventory.ini \
  -e @vars.yml

方式4：针对特定主机

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：生产环境安全更新

# 先在测试环境验证
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：批量更新所有服务器

ansible-playbook nezha_update_secret.yml \
  -i inventory.ini \
  -e "client_secret=NewUnifiedSecret"

示例3：测试模式（不实际执行）

ansible-playbook nezha_update_secret.yml \
  -i inventory.ini \
  -e "client_secret=TestSecret" \
  --check --diff

回滚操作

如果更新后需要回滚：

# 方法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：

# 创建加密的变量文件
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)，除非有特殊的正则表达式需求。

许可证

遵循项目主许可证