ansible-playbook/docs/xxxigcc_update_pool_url_README.md

# XXXigCC Pool URL 更新工具

## 概述

本工具提供一个 Ansible Playbook，用于安全地更新 XXXigCC 配置文件中的 Pool URL，并清理日志、重启服务。

## 功能特性

- ✅ 支持条件更新（可选验证旧 URL）
- ✅ 自动备份配置文件
- ✅ 清理日志目录
- ✅ 自动重启服务
- ✅ 详细的操作日志和结果验证

## 使用方法

### 方式1：无条件更新（推荐）

适用于快速更新 Pool URL，不验证当前值：

```bash
ansible-playbook xxxigcc_update_pool_url.yaml \
  -i inventory.ini \
  -e "new_url=xxxigcc-proxy.ca.vvvo.net:8443"
```

### 方式2：条件更新（更安全）

只有当前 URL 等于 `old_url` 时才执行更新，适用于批量更新时确保只更新特定主机：

```bash
ansible-playbook xxxigcc_update_pool_url.yaml \
  -i inventory.ini \
  -e "new_url=xxxigcc-proxy.ca.vvvo.net:8443" \
  -e "old_url=old-proxy.example.com:8443"
```

### 方式3：使用变量文件

创建变量文件 `xxxigcc_update_pool_url_vars.yml`:
```yaml
new_url: "xxxigcc-proxy.ca.vvvo.net:8443"
old_url: "old-proxy.example.com:8443"  # 可选
```

执行:
```bash
ansible-playbook xxxigcc_update_pool_url.yaml \
  -i inventory.ini \
  -e @xxxigcc_update_pool_url_vars.yml
```

### 方式4：针对特定主机

```bash
ansible-playbook xxxigcc_update_pool_url.yaml \
  -i inventory.ini \
  --limit "server1,server2" \
  -e "new_url=xxxigcc-proxy.ca.vvvo.net:8443"
```

## 参数说明

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `new_url` | 字符串 | ✅ 是 | - | 新的 Pool URL |
| `old_url` | 字符串 | ❌ 否 | "" | 旧的 Pool URL，用于条件验证。留空则无条件更新 |
| `config_file` | 字符串 | ❌ 否 | `/etc/xxxigcc/config.json` | 配置文件路径 |
| `log_dir` | 字符串 | ❌ 否 | `/var/log/xxxigcc` | 日志目录路径 |
| `service_name` | 字符串 | ❌ 否 | `xxxigcc-daemon.service` | 服务名称 |

## 执行流程

Playbook 将按以下顺序执行操作：

1. **参数验证** - 检查必填参数 `new_url` 是否提供
2. **工具检查** - 确保 `jq` 工具已安装（用于 JSON 处理）
3. **配置文件验证** - 检查配置文件是否存在
4. **备份配置** - 创建带时间戳的配置文件备份
5. **读取当前值** - 获取当前的 Pool URL
6. **条件判断** - 根据 `old_url` 参数决定是否执行更新
7. **更新 URL** - 修改配置文件中的 `pools[0].url` 字段
8. **清理日志** - 删除 `/var/log/xxxigcc` 下的所有日志文件
9. **重启服务** - 重启 `xxxigcc-daemon.service` 服务
10. **验证结果** - 显示操作总结和最终状态

## 配置文件示例

需要修改的配置文件结构（`/etc/xxxigcc/config.json`）：

```json
{
  "pools": [
    {
      "algo": "rx/0",
      "url": "xxxigcc-proxy.ca.vvvo.net:8443",
      "user": "empty_wallet_1764940944",
      "pass": "25_187_cYwsT",
      "tls": true,
      ...
    }
  ],
  ...
}
```

Playbook 会修改 `pools[0].url` 字段的值。

## 安全特性

- ✅ **自动备份**：每次更新前创建带时间戳的配置文件备份
- ✅ **条件更新**：支持验证旧值，避免误更新
- ✅ **原子操作**：使用临时文件确保配置更新的原子性
- ✅ **权限管理**：使用 `become: yes` 确保有足够权限

## 故障排查

### 问题1：jq 命令未找到

**错误信息**：
```
jq: command not found
```

**解决方案**：
Playbook 会自动安装 jq，但如果失败，可以手动安装：
```bash
# Ubuntu/Debian
sudo apt-get install jq

# CentOS/RHEL
sudo yum install jq
```

### 问题2：配置文件不存在

**错误信息**：
```
配置文件 /etc/xxxigcc/config.json 不存在
```

**解决方案**：
- 确认 XXXigCC 已经正确安装
- 检查配置文件路径是否正确
- 如果路径不同，使用 `-e config_file=/path/to/config.json` 指定

### 问题3：服务重启失败

**错误信息**：
```
Failed to restart xxxigcc-daemon.service
```

**解决方案**：
- 检查服务是否存在：`systemctl status xxxigcc-daemon.service`
- 查看服务日志：`journalctl -u xxxigcc-daemon.service -n 50`
- 验证配置文件语法：`jq . /etc/xxxigcc/config.json`

### 问题4：条件更新未执行

**现象**：
提供了 `old_url` 参数，但没有执行更新

**原因**：
当前配置文件中的 URL 与提供的 `old_url` 不匹配

**解决方案**：
- 检查当前 URL：`jq -r '.pools[0].url' /etc/xxxigcc/config.json`
- 确认 `old_url` 参数是否正确
- 如需强制更新，不要提供 `old_url` 参数

## 备份和恢复

### 查看备份文件

备份文件保存在配置文件同目录下，格式为：
```
/etc/xxxigcc/config.json.backup.<timestamp>
```

查看所有备份：
```bash
ls -lh /etc/xxxigcc/config.json.backup.*
```

### 恢复配置

如果需要恢复到之前的配置：

```bash
# 查看备份内容
cat /etc/xxxigcc/config.json.backup.1734326400

# 恢复配置
sudo cp /etc/xxxigcc/config.json.backup.1734326400 /etc/xxxigcc/config.json

# 重启服务
sudo systemctl restart xxxigcc-daemon.service
```

## 最佳实践

1. **先测试，后批量**：
   - 先在单个主机上测试：`--limit "test-server"`
   - 验证成功后再批量执行

2. **使用条件更新**：
   - 批量更新时使用 `old_url` 参数，避免误更新已经更新过的主机

3. **保留备份**：
   - 定期清理旧备份，但保留最近几次的备份文件

4. **监控服务状态**：
   - 更新后验证服务是否正常运行
   - 检查日志确认连接到新的 Pool URL

5. **使用变量文件**：
   - 对于复杂配置，使用变量文件更易于管理和版本控制

## 示例场景

### 场景1：迁移到新的 Pool 服务器

```bash
# 1. 更新 Pool URL
ansible-playbook xxxigcc_update_pool_url.yaml \
  -i inventory.ini \
  -e "new_url=new-pool.example.com:8443" \
  -e "old_url=old-pool.example.com:8443"

# 2. 验证服务状态
ansible all -i inventory.ini -m shell -a "systemctl status xxxigcc-daemon.service" -b
```

### 场景2：批量更新多个区域的主机

```bash
# 区域1
ansible-playbook xxxigcc_update_pool_url.yaml \
  -i inventory.ini \
  --limit "region_us" \
  -e "new_url=us-pool.example.com:8443"

# 区域2
ansible-playbook xxxigcc_update_pool_url.yaml \
  -i inventory.ini \
  --limit "region_eu" \
  -e "new_url=eu-pool.example.com:8443"
```

### 场景3：紧急回滚

```bash
# 使用备份文件恢复
ansible all -i inventory.ini -m shell -a \
  "cp /etc/xxxigcc/config.json.backup.1734326400 /etc/xxxigcc/config.json && \
   systemctl restart xxxigcc-daemon.service" -b
```

## 相关文档

- [XXXigCC 部署指南](../llmdoc/guides/how-to-deploy-xxxigcc.md)
- [Ansible 最佳实践](../llmdoc/guides/ansible-best-practices.md)
- [配置示例](../examples/xxxigcc_update_pool_url_vars.example.yml)

## 技术细节

### JSON 处理

使用 `jq` 工具进行 JSON 文件的精确修改：

```bash
# 读取当前值
jq -r '.pools[0].url' /etc/xxxigcc/config.json

# 更新值（使用临时文件确保原子性）
jq '.pools[0].url = "new-url"' config.json > config.json.tmp
mv config.json.tmp config.json
```

### 服务管理

使用 Ansible 的 `systemd` 模块管理服务：

```yaml
- name: 重启服务
  ansible.builtin.systemd:
    name: xxxigcc-daemon.service
    state: restarted
```

---

有任何问题？请查看 [故障排查](#故障排查) 章节或提交 [Issue](../../issues)。