ansible-playbook/docs/QUICKSTART_nezha.md

# 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=你的新密钥"
```