添加 XXXigCC Pool URL 更新功能和完整文档系统
This commit is contained in:
@@ -17,6 +17,14 @@
|
||||
- 常见使用场景
|
||||
- 故障排查指南
|
||||
|
||||
### XXXigCC 管理
|
||||
|
||||
- **[xxxigcc_update_pool_url_README.md](xxxigcc_update_pool_url_README.md)** - XXXigCC Pool URL 更新工具完整文档
|
||||
- 详细的使用方法和参数说明
|
||||
- 条件更新和安全特性
|
||||
- 配置备份和服务管理
|
||||
- 故障排查和最佳实践
|
||||
|
||||
## 🔍 查找文档
|
||||
|
||||
### 按需求查找
|
||||
@@ -25,6 +33,7 @@
|
||||
|---------|----------|
|
||||
| 快速更新 Nezha Agent | [快速开始](QUICKSTART_nezha.md) |
|
||||
| 了解所有功能和参数 | [完整文档](nezha_update_secret_README.md) |
|
||||
| 更新 XXXigCC Pool URL | [Pool URL 更新文档](xxxigcc_update_pool_url_README.md) |
|
||||
| 查看配置示例 | [examples/](../examples/) |
|
||||
| 了解项目架构 | [llmdoc/architecture/](../llmdoc/architecture/) |
|
||||
| 学习最佳实践 | [llmdoc/guides/](../llmdoc/guides/) |
|
||||
@@ -36,7 +45,8 @@
|
||||
```
|
||||
docs/ # 用户文档（人类友好）
|
||||
├── nezha_update_secret_README.md
|
||||
└── QUICKSTART_nezha.md
|
||||
├── QUICKSTART_nezha.md
|
||||
└── xxxigcc_update_pool_url_README.md
|
||||
|
||||
llmdoc/ # LLM 文档系统（AI 友好）
|
||||
├── index.md # 文档索引
|
||||
|
||||
294
docs/xxxigcc_update_pool_url_README.md
Normal file
294
docs/xxxigcc_update_pool_url_README.md
Normal file
@@ -0,0 +1,294 @@
|
||||
# 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)。
|
||||
Reference in New Issue
Block a user