vmess-domain-rotator/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

VMess domain rotator - automated pipeline that fetches preferred domains from an API, selects the best candidate, and exports runtime files for Sub-Store and V2Ray integration.

Key Commands

Development

# Syntax check Python scripts
python3 -m py_compile scripts/domain_updater.py
python3 -m py_compile scripts/update_vmess_links.py

# Manual run (single update)
python3 scripts/domain_updater.py --config config.json

# Manual run with conditional git commit (commits only if domain changed)
bash scripts/run_update_and_commit.sh config.json

# Update VMess base64 links with selected domain
python3 scripts/update_vmess_links.py --input ./nodes.txt --output ./nodes.updated.txt --domain-file ./runtime/current_domain.txt

# Update specific nodes by regex
python3 scripts/update_vmess_links.py --input ./nodes.txt --output ./nodes.updated.txt --domain-file ./runtime/current_domain.txt --name-regex "(argo|cf|vm)"

# Local smoke test HTTP endpoint for runtime outputs
python3 -m http.server 8080 --directory runtime

Deployment (Debian)

# Install systemd service+timer (uses current git repo directory)
sudo bash scripts/install_debian.sh

# Install with custom timer interval
sudo bash scripts/install_debian.sh --interval 5min

# Uninstall (keeps git repository and files)
sudo bash scripts/uninstall_debian.sh

Architecture

Core Flow

1. scripts/domain_updater.py - Main entrypoint that:

   • Fetches domain candidates from API (configured in config.json)
   • Parses response using JSON path or regex
   • Optionally scores candidates based on API fields
   • Optionally healthchecks domains (TLS handshake)
   • Selects best domain and writes runtime outputs
   • Falls back to last_good_domain from state.json if all checks fail

2. scripts/run_update_and_commit.sh - Scheduler entrypoint that:

   • Runs domain_updater.py
   • Compares before/after domain
   • Commits to runtime-state branch if domain changed
   • Pushes to remote if configured

3. scripts/update_vmess_links.py - Post-processor for VMess subscription links:

   • Decodes vmess:// base64 payloads
   • Updates add field with selected domain
   • Supports node name filtering by regex

Configuration Structure

• config.json - Single runtime config file containing:
  • api: endpoint URL, method, headers, timeout
  • parser: JSON paths (field_paths) or regex for extracting domains
  • domain_filter: include/exclude patterns (e.g., filter out IPv4 addresses)
  • scoring: ranking logic based on API fields or API order
  • healthcheck: TLS handshake verification settings
  • selection: top_n candidates to consider
  • output: runtime directory and file paths
  • v2ray: template file token replacement (optional)

Output Files

All runtime outputs are written to runtime/:

• current_domain.txt - Plain text domain
• current_domain.json - JSON payload with domain, timestamp, status, source_count
• state.json - Persistent state including last_good_domain for fallback
• substore_vars.json - Variables for Sub-Store operator scripts

Sub-Store Integration

substore/operator_template.js - Operator script that:

• Fetches current_domain.json via HTTP using $substore.http.get
• Caches domain with TTL (5 minutes by default)
• Replaces VMess server field for nodes matching NODE_NAME_REGEX
• Must be configured with actual DOMAIN_JSON_URL in production

Systemd Deployment

• Service runs run_update_and_commit.sh oneshot
• Timer triggers every 1h by default (configurable via install_debian.sh)
• Uses current git repository directory (in-place mode only)
• Uses the installing user (from SUDO_USER) as service user
• Runtime state committed to runtime-state branch
• No separate service user created - uses existing user's git credentials

Important Behaviors

• Fallback: If all healthchecks fail, script uses last_good_domain from runtime/state.json
• Conditional commits: run_update_and_commit.sh only commits when domain actually changes
• Branch separation: Runtime state goes to runtime-state branch via git worktree
• API order mode: For vps789 Top20, set scoring.use_api_order=true to trust API ranking
• Domain filtering: Use domain_filter.exclude_regex to filter out IPv4 addresses when API returns mixed results
• Sub-Store caching: Operator uses scriptResourceCache with TTL to avoid excessive HTTP requests

Configuration Notes

For vps789 Top20 API specifically:

• Use parser.field_paths: ["data.good[].ip"]
• Enable scoring.use_api_order: true to respect API ranking
• Set healthcheck.enabled: false if you want pure API-based selection
• Add IPv4 exclude regex to domain_filter.exclude_regex to filter out IP addresses

Git Workflow

• Main branch: main (source code)
• Runtime branch: runtime-state (auto-committed domain updates)
• Commits to runtime-state use generic git identity: vmess-domain-rotator@localhost
• Script creates runtime-state branch automatically if missing