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          # 顶层外观门面（Facade，100% 向后兼容 CLI 与 API）
├── rotator/                   # 核心领域高内聚模块子包
│   ├── config.py              # 配置校验、路径解析与输出设定
│   ├── filter.py              # 域名清洗、正则匹配与黑名单过滤
│   ├── sources.py             # 远程 API 与本地 cfst 数据源适配
│   ├── scoring.py             # 评分排名、平局决胜、迟滞防抖与候选构建
│   ├── storage.py             # 原子落盘写入与状态读写
│   ├── notify.py              # 通知命令执行与超时防护
│   └── main.py                # 主轮换工作流编排与 CLI 参数解析
├── run_update_and_commit.sh   # Server 模式调度器 + Git 自动提交与滚动修剪（模式 A）
├── 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

tests/
├── test_domain_updater.py     # Python 核心选优、极性、回退、配置校验及 Facade 完整性
├── test_shell_lifecycle.py    # Shell 部署、发布安全、凭证保护及 Git 历史滚动修剪
├── test_router_scripts.py     # 路由器 BusyBox 脚本文件原子性、测速过滤及 SSOT 打包同步
└── test_substore_operator.py  # Sub-Store 算子类型安全与时效降级

build_router_package.sh        # 打包路由器部署 tarball → vmess.tar.gz（支持 --sync-from-config）
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

自动化测试

# 运行全套测试（覆盖 Python 核心、Shell 部署、路由器脚本及 Sub-Store 算子）
python3 -m unittest discover tests -v

运行

# 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

# 打包路由器部署包（默认打包现有 config_router.conf）
./build_router_package.sh

# 打包路由器部署包（SSOT 单源模式：自动从 config.local.json 投影同步测速与输出参数）
./build_router_package.sh --sync-from-config config.local.json

systemd 安装/卸载

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

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

Testing

• 全套自动化回归测试：运行 python3 -m unittest discover tests -v（覆盖 4 大模块 21 项用例，秒级执行，零第三方依赖）。
• 语法校验：使用 py_compile 与 bash -n / sh -n 快速检查语法。
• 路径解析验证：python3 scripts/domain_updater.py --config config.server.json --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

• 想了解架构终审与缺陷复现清单 → ARCHITECTURE_REVIEW_UNIFIED.md
• 想了解自动化测试用例 → tests/
• 想了解配置字段含义 → 直接读对应的 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