ansible-playbook/docs/xxxigcc_update_pool_url_README.md

XXXigCC Pool URL 更新工具

概述

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

功能特性

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

使用方法

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

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

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

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

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

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:

new_url: "xxxigcc-proxy.ca.vvvo.net:8443"
old_url: "old-proxy.example.com:8443"  # 可选

执行:

ansible-playbook xxxigcc_update_pool_url.yaml \
  -i inventory.ini \
  -e @xxxigcc_update_pool_url_vars.yml

方式4：针对特定主机

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）：

{
  "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，但如果失败，可以手动安装：

# 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>

查看所有备份：

ls -lh /etc/xxxigcc/config.json.backup.*

恢复配置

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

# 查看备份内容
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 服务器

# 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：批量更新多个区域的主机

# 区域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：紧急回滚

# 使用备份文件恢复
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 部署指南
• Ansible 最佳实践
• 配置示例

技术细节

JSON 处理

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

# 读取当前值
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 模块管理服务：

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

---

有任何问题？请查看 故障排查 章节或提交 Issue。