vmess-domain-rotator/CLAUDE.md

CLAUDE.md

What This Repo Does

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

两种独立运行模式：

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

File Map

configs/                       # 统一配置仓
├── config.server.json         # Server 模式完整配置
├── config.local.json          # Python 本地 cfst 模式配置
└── config_router.conf         # BusyBox shell 模式配置

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 参数解析
├── server/                    # Linux / Debian 服务端运维脚本
│   ├── run_update_and_commit.sh # 实际调度器 + Git 自动提交与滚动修剪（模式 A）
│   ├── install_debian.sh      # systemd timer/service 安装
│   └── uninstall_debian.sh    # systemd 卸载
├── router/                    # 路由器 BusyBox 嵌入式脚本
│   ├── router_local_update.sh # 运行 cfst 并原子写输出
│   └── router_local_http.sh   # BusyBox httpd 提供运行时文件

docs/
├── README.md                  # 文档导航中心
├── workflow.md                # 业务全景工作流图 (Mermaid)
└── reviews/                   # 架构审查、分歧裁决与修复台账归档
    ├── ARCHITECTURE_REVIEW_UNIFIED.md  # 终审统一报告与演进台账（唯一权威）
    ├── ARCHITECTURE_REVIEW.md          # 历史初审报告归档
    └── ARCHITECTURE_REVIEW_RECHECK.md  # 历史复核报告归档

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）

Common Commands

语法校验

env PYTHONPYCACHEPREFIX=/tmp/pycache python3 -m py_compile scripts/rotator/*.py scripts/domain_updater.py
bash -n scripts/server/*.sh scripts/router/*.sh build_router_package.sh
node -c substore/operator_template.js

自动化测试

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

运行

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

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

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

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

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

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

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

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

systemd 安装/卸载

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

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

Testing

• 全套自动化回归测试：运行 python3 -m unittest discover tests -v（覆盖 4 大模块 22 项用例，秒级执行，零第三方依赖）。
• 语法校验：使用 py_compile 与 bash -n / sh -n 快速检查语法。
• 路径解析验证：python3 scripts/domain_updater.py --config configs/config.server.json --print-output-settings。
• 本地测试服务器端时，仅运行 python3 scripts/domain_updater.py --config configs/config.server.json 进行输出验证，严禁直接运行 scripts/server/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 控制开关，不受任何模式和策略影响。
• vps789.com API 指标极性与业务公式（Score SSOT 权威规范）： 实测原始数据已逆向破解并确证 vps789.com API 中所有 *Score 字段（ydScore, dxScore, ltScore, avgScore）的真实物理含义：
  • 上游公式严格为综合成本惩罚分（Cost / Penalty Metric，越小越优 / 高尔夫计分制）： $$\text{Score} = \text{LatencyAvg} + \text{PkgLostRateAvg} \times 50$$ $$\text{avgScore} = \frac{\text{ydScore} + \text{dxScore} + \text{ltScore}}{3}$$
  • 零丢包时分数等于平均延迟（ms）；丢包每增加 1% 加罚 50 分。
  • 极性结论：所有 *Score 与延迟、丢包完全同向，必须严格遵循 越小越优。
  • 策略落地：平局决胜 tie_breakers 中必须指定 {"field": "yd_score", "order": "asc"}（低分优胜）；若将来在加权计算中使用，也必须遵循 prefer_lower: true / order: "asc"。历史审查曾将其误解为百分制健康分（误配 desc），现已永久纠偏。

Where to Look

• 想了解架构终审与缺陷复现清单 → docs/reviews/ARCHITECTURE_REVIEW_UNIFIED.md
• 想了解自动化测试用例 → tests/
• 想了解配置字段含义 → 直接读对应的 config JSON/conf 文件，字段名即文档
• 想了解评分/筛选逻辑 → scripts/domain_updater.py / scripts/rotator/
• 想了解 git 提交/推送流程 → scripts/server/run_update_and_commit.sh
• 想了解 systemd 部署细节 → scripts/server/install_debian.sh
• 想了解下游消费方式 → substore/operator_template.js
• 想了解完整工作流图 → docs/workflow.md（Mermaid 流程图）
• 想了解项目综合文档中心 → docs/README.md
• 想了解用户快速上手文档 → README.md