# vmess-domain-rotator

一个用于 **自动获取优选域名**、写入 `runtime/` 运行时文件，并按计划将运行时变更提交到 `runtime-state` 分支的工具。

---

## 1. 功能概览

本项目主要完成以下流程：

1. 从 API 拉取候选域名/IP
2. 解析并过滤候选结果
3. 按规则打分/选择最终域名
4. 写入运行时文件到 `runtime/`
5. （可选）将运行时变更自动提交并 push 到 `runtime-state`

核心脚本：

- `scripts/domain_updater.py`：执行域名拉取、选择与写文件
- `scripts/run_update_and_commit.sh`：执行 updater + git 提交/推送
- `scripts/install_debian.sh`：Debian 下安装 systemd service + timer
- `scripts/uninstall_debian.sh`：卸载 systemd 与认证环境文件

---

## 2. 运行产物

默认写入仓库根目录 `runtime/`：

- `runtime/current_domain.txt`：当前域名（纯文本）
- `runtime/current_domain.json`：当前结果 JSON
- `runtime/state.json`：状态文件（含 `last_good_domain`）
- `runtime/substore_vars.json`：给外部系统消费的变量

> 注意：`domain_updater.py` 现在会按 `--config` 文件所在目录解析 `output.runtime_dir`（默认 `./runtime`），避免误写到 `scripts/runtime/`。

---

## 3. 本地快速开始

### 3.1 配置

编辑 `config.json`。

典型解析路径（如 API 返回 `data.good[].ip`）：

```json
"parser": {
  "field_paths": ["data.good[].ip"],
  "json_paths": [],
  "regex": "[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}"
}
```

### 3.2 语法检查

```bash
python3 -m py_compile scripts/domain_updater.py
python3 -m py_compile scripts/update_vmess_links.py
```

### 3.3 运行一次

```bash
python3 scripts/domain_updater.py --config config.json
```

### 3.4 本地查看结果

```bash
cat runtime/current_domain.txt
cat runtime/current_domain.json
```

可选 HTTP 验证：

```bash
python3 -m http.server 8080 --directory runtime
curl http://127.0.0.1:8080/current_domain.json
```

---

## 4. Debian 一键部署（完整教程）

## 4.1 前置条件

- Debian/Ubuntu
- 项目已 `git clone` 到服务器（在仓库目录执行安装）
- 远程仓库 `origin` 可用
- 用于运行服务的用户有仓库读写权限

---

### 4.2 推荐方案（不传参数）

如果你采用“每台机器先手动保存 git 凭证”的流程，直接执行：

```bash
sudo bash scripts/install_debian.sh
```

默认行为：

- 服务用户：当前 `sudo` 执行前用户（`SUDO_USER`）
- 定时间隔：`1h`
- 自动 push：开启（`--git-push 1`）
- 认证模式：`credential.helper store`
- 推送分支：`runtime-state`

---

### 4.3 Git 凭证（无交互）配置建议

#### 方式 A：手动存凭证（你当前采用的方式）

在**服务用户**下执行一次：

```bash
git config --global credential.helper store
git push origin runtime-state:runtime-state
```

首次输入用户名/密码（或 PAT）后，后续 systemd 可无交互 push。

> 关键点：保存凭证的用户必须和 service 的 `User=` 一致。

#### 方式 B：安装脚本带 token（可选）

```bash
sudo bash scripts/install_debian.sh \
  --git-http-username <your-user> \
  --git-http-token-file /root/.config/vmess-token \
  --git-use-credential-store 1
```

---

### 4.4 安装后验证

```bash
sudo systemctl status vmess-domain-rotator.timer
sudo systemctl status vmess-domain-rotator.service

# 手动触发一次
sudo systemctl start vmess-domain-rotator.service

# 看日志
sudo journalctl -u vmess-domain-rotator.service -n 120 --no-pager
```

成功时应看到：

- updater 输出 JSON
- `committed runtime changes on runtime-state ...`
- `pushed to origin/runtime-state`

---

## 5. install_debian.sh 参数说明

```bash
sudo bash scripts/install_debian.sh [options]
```

| 参数 | 说明 | 默认值 |
|---|---|---|
| `--user <name>` | 指定 service 用户 | 当前 `sudo` 用户 |
| `--group <name>` | 指定 service 用户组 | 当前 `sudo` 用户主组 |
| `--interval <value>` | 定时周期（如 `1h`/`5min`） | `1h` |
| `--git-push <0|1>` | 是否自动 push | `1` |
| `--git-push-remote <name>` | 远程名 | `origin` |
| `--git-http-username <u>` | HTTPS 认证用户名 | `git` |
| `--git-http-token <t>` | HTTPS token（明文参数） | 空 |
| `--git-http-token-file <f>` | 从文件读取 token | 空 |
| `--git-use-credential-store <0|1>` | 是否使用 `credential.helper store` | `1` |
| `--git-credentials-file <f>` | 指定 credential store 文件路径 | 空（Git 默认） |
| `--no-install-deps` | 跳过 apt 安装依赖 | 关闭 |
| `-h, --help` | 查看帮助 | - |

说明：

- `--git-push 1` 时，push 失败会返回非 0，systemd 任务标记失败（便于监控）。
- 安装会写入环境文件：`/etc/vmess-domain-rotator.env`。

---

## 6. 自动提交/推送逻辑说明

`scripts/run_update_and_commit.sh` 的行为：

1. 运行 `domain_updater.py` 更新根目录 `runtime/`
2. 切到（或创建）`runtime-state` worktree
3. 将 `runtime/` 下四个文件同步到 `runtime-state` worktree
4. 仅当 **runtime-state 分支内容有差异** 时才 commit
5. `--git-push 1` 时要求 push 成功

即：不再只看 main 分支当前文件是否变化，而是看 `runtime-state` 目标内容是否有变化。

---

## 7. 常用运维命令

### 7.1 service / timer

```bash
sudo systemctl status vmess-domain-rotator.timer
sudo systemctl status vmess-domain-rotator.service
sudo systemctl start vmess-domain-rotator.service
sudo systemctl restart vmess-domain-rotator.timer
```

### 7.2 日志

```bash
sudo journalctl -u vmess-domain-rotator.service -n 200 --no-pager
sudo journalctl -u vmess-domain-rotator.service -f
```

### 7.3 查看 runtime-state 提交

```bash
git log runtime-state --oneline -n 20
```

---

## 8. 卸载

```bash
sudo bash scripts/uninstall_debian.sh
```

保留认证/env 文件：

```bash
sudo bash scripts/uninstall_debian.sh --keep-auth-files
```

---

## 9. VMess 链接批量替换（可选）

```bash
python3 scripts/update_vmess_links.py \
  --input ./nodes.txt \
  --output ./nodes.updated.txt \
  --domain-file ./runtime/current_domain.txt
```

仅替换匹配名称（`ps`）的节点：

```bash
python3 scripts/update_vmess_links.py \
  --input ./nodes.txt \
  --output ./nodes.updated.txt \
  --domain-file ./runtime/current_domain.txt \
  --name-regex "(argo|cf|vm)"
```

---

## 10. 注意事项

1. **服务用户与 git 凭证用户必须一致**，否则会出现：
   - `fatal: could not read Username ... terminal prompts disabled`
2. `credential.helper store` 为明文存储，建议仅在可控服务器使用。
3. 不要把 token 提交进仓库。
4. `runtime/state.json` 需要持久化，保障 fallback 能用。