vmess-domain-rotator/CLAUDE.md

CLAUDE.md

What This Repo Does

自动选优 Cloudflare 优选域名/IP，写入运行时文件供 Sub-Store 等下游消费。

两种独立运行模式：

模式	数据源	配置	输出目录	Git 自动化
Server	远程 API	config.server.json	runtime/	runtime-state 分支
Router (Python)	本地 cfst	config.local.json	cfip_runtime/	无
Router (BusyBox)	本地 cfst	config_router.conf	由配置决定	无

File Map

scripts/
├── domain_updater.py          # 核心：两种模式共用的 Python 更新器
├── run_update_and_commit.sh   # Server 模式调度器 + git 提交逻辑
├── router_local_update.sh     # BusyBox 路由器：运行 cfst 并写输出
├── router_local_http.sh       # BusyBox 路由器：httpd 提供运行时文件
├── install_debian.sh          # systemd timer/service 安装
└── uninstall_debian.sh        # systemd 卸载

substore/
└── operator_template.js       # Sub-Store 脚本操作符，消费运行时 JSON

build_router_package.sh        # 打包路由器部署 tarball → vmess.tar.gz
config.server.json             # Server 模式完整配置
config.local.json              # Python 本地 cfst 模式配置
config_router.conf             # BusyBox shell 模式配置

Common Commands

语法校验

env PYTHONPYCACHEPREFIX=/tmp/pycache python3 -m py_compile scripts/domain_updater.py
bash -n scripts/run_update_and_commit.sh
bash -n scripts/install_debian.sh
bash -n scripts/uninstall_debian.sh
sh -n scripts/router_local_update.sh
sh -n scripts/router_local_http.sh

运行

# Server 模式单次运行
python3 scripts/domain_updater.py --config config.server.json

# 本地 cfst 模式单次运行
python3 scripts/domain_updater.py --config config.local.json

# 查看解析后的输出路径（不执行更新）
python3 scripts/domain_updater.py --config config.server.json --print-output-settings

# Server 调度器入口
bash scripts/run_update_and_commit.sh config.server.json

# 强制提交
bash scripts/run_update_and_commit.sh --force-commit config.server.json

# BusyBox 路由器
sh scripts/router_local_update.sh ./config_router.conf
sh scripts/router_local_http.sh ./config_router.conf

# 打包路由器部署包
./build_router_package.sh

systemd 安装/卸载

sudo bash scripts/install_debian.sh --config config.server.json
sudo bash scripts/uninstall_debian.sh

install_debian.sh --help 查看完整参数（peak/offpeak 间隔、时区等）。

Testing

• 无专用测试框架，以语法校验 + 手动运行为主。
• --print-output-settings 是最快的路径解析验证方式。
• 本地测试服务器端时，仅运行 python3 scripts/domain_updater.py --config config.server.json 进行输出验证，不要运行 run_update_and_commit.sh 调度/Git 推送脚本。

Key Constraints

• config.json / config.example.json 已废弃，不要重新引入。
• 输出路径由配置驱动，不要硬编码 runtime/current_domain.txt 之类的路径。
• runtime/ 和 cfip_runtime/ 在 main 分支被 gitignore。
• 只有 Server 模式向 runtime-state 分支提交。
• state.json 用于 fallback（保存上次正常值），两种模式都依赖它。
• substore_vars.json 是给下游消费者的轻量契约，不要把完整运行时数据塞进去。
• BusyBox shell 脚本需兼容 POSIX sh，不能用 bash 特性。
• router_local_http.sh 使用配置中的 BusyBox 二进制的 httpd applet，不使用系统 httpd。
• SubStore 脚本的 $arguments.domain 参数为最高优先级覆盖，$arguments.domain_override 控制开关，不受任何模式和策略影响。

Where to Look

• 想了解配置字段含义 → 直接读对应的 config JSON/conf 文件，字段名即文档
• 想了解评分/筛选逻辑 → scripts/domain_updater.py
• 想了解 git 提交/推送流程 → scripts/run_update_and_commit.sh
• 想了解 systemd 部署细节 → scripts/install_debian.sh
• 想了解下游消费方式 → substore/operator_template.js
• 想了解完整工作流图 → workflow.md（Mermaid 流程图）
• 想了解用户文档 → README.md