ansible-playbook/docs/QUICKSTART_nezha.md

Nezha Agent Secret 更新 - 快速开始

🚀 5分钟快速上手

步骤 1: 准备 Inventory 文件

# 复制示例文件
cp inventory.example.ini inventory.ini

# 编辑 inventory.ini，添加你的服务器信息
vim inventory.ini

最简单的 inventory.ini 示例:

[nezha_agents]
your-server.com ansible_host=1.2.3.4 ansible_user=root

步骤 2: 测试连接

# 测试 Ansible 连接
ansible nezha_agents -i inventory.ini -m ping

如果成功，你会看到:

your-server.com | SUCCESS => {
    "changed": false,
    "ping": "pong"
}

步骤 3: 执行更新

方式A：强制更新（推荐用于首次使用）

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

方式B：安全更新（推荐用于生产环境）

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: 单台服务器更新

ansible-playbook nezha_update_secret.yml \
  -i inventory.ini \
  --limit your-server.com \
  -e "client_secret=NewSecret123"

场景 2: 先测试，后执行

# 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: 批量更新多台服务器

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

场景 4: 使用变量文件（保护敏感信息）

创建 secret_vars.yml:

client_secret: "你的新密钥"

执行:

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=旧值" 可以避免误操作

🔧 故障排查

问题：连接失败

# 检查 SSH 连接
ssh root@your-server.com

# 测试 Ansible 连接
ansible nezha_agents -i inventory.ini -m ping -vvv

问题：权限不足

# 如果不是 root 用户，确保在 inventory.ini 中添加
ansible_become=yes

# 或在命令中添加
ansible-playbook nezha_update_secret.yml -i inventory.ini -b -K
# -b: 使用 become (sudo)
# -K: 询问 sudo 密码

问题：配置文件路径不同

# 指定自定义路径
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
• 查看其他 playbook 示例: ls *.yml *.yaml

💡 专业提示

1. 使用 Ansible Vault 保护密钥:

   ansible-vault encrypt_string 'YourSecret' --name 'client_secret'
   

2. 保存执行日志:

   ansible-playbook nezha_update_secret.yml \
     -i inventory.ini \
     -e "client_secret=NewSecret" | tee update.log
   

3. 并行执行（多台服务器）:

   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 预览变更
• 已准备回滚方案（保留旧密钥值）

准备就绪？执行以下命令开始:

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