Transform XRayMOD from CF Workers-only to a dual-mode system:
- CF Workers Mode — proxy on edge, management API on worker (current, kept as-is)
- Personal Server Mode — proxy on CF edge, management API + UI on VPS
Plus: FastAPI installer with WebUI, Next.js frontend, offline testing.
installer/
├── app.py # FastAPI main (startup, routes)
├── config.py # ~/.xraymod/config.json management
├── cf_api.py # Cloudflare API client (migrated from install.py)
├── deployer.py # Deploy logic (CF Worker + VPS)
├── templates/
│ └── index.html # Jinja2 WebUI
├── static/
│ ├── app.js # Installer frontend logic
│ └── styles.css # Dark emerald theme
├── install.py # CLI fallback (legacy)
└── backend-install.sh # VPS installer (existing)
| Method | Path | Description |
|---|---|---|
| GET | / |
WebUI |
| GET | /api/status |
Install status |
| POST | /api/verify-token |
Validate CF token |
| GET | /api/accounts |
List CF accounts |
| POST | /api/deploy |
Deploy to CF Worker |
| POST | /api/deploy-server |
Deploy to VPS |
| GET | /api/progress |
SSE progress stream |
| GET | /health |
Health check |
- Welcome screen + mode selection (CF Worker / VPS)
- CF API Token form with visual guide
- Worker name + D1 database + admin password config
- Real-time progress (SSE)
- Offline test button (SQLite local)
- Result page: panel URL + password + subscription link
fastapi
uvicorn[standard]
jinja2
httpx
aiosqlite
- User runs
uv run installer/app.py - Browser opens
http://localhost:8000 - User selects mode, enters CF token
- Installer creates D1 + deploys Worker (or sets up VPS)
- Shows result with URL and credentials
backend/
├── main.py # FastAPI app entry
├── config.py # Settings + env
├── database.py # SQLAlchemy async setup
├── models.py # ORM models
├── auth.py # Session + password (SHA-256)
├── routers/
│ ├── login.py # POST /api/login
│ ├── logout.py # POST /api/logout
│ ├── users.py # CRUD /api/users
│ ├── nodes.py # CRUD /api/nodes
│ ├── configs.py # CRUD /api/configs
│ ├── protocols.py # CRUD /api/protocols
│ ├── settings.py # GET/PUT /api/settings
│ ├── cleanip.py # Clean IP scanning
│ ├── backends.py # Backend registration
│ └── wizard.py # Wizard deployment
├── services/
│ ├── subscription.py # Subscription link generation
│ ├── clean_ip.py # Clean IP scanner
│ └── cf_client.py # Cloudflare API client
├── schema.sql # SQLite schema
└── requirements.txt
- SQLite (offline/dev) / PostgreSQL (production)
- SQLAlchemy async with auto-migration on startup
- Same schema as D1: users, configs, protocols, kvstore, backends
New env vars in wrangler.toml:
BACKEND_URL = "https://your-vps.com"
BACKEND_SECRET = "hmac-secret-here"Modified worker/router.ts:
- If
BACKEND_URLset → forward API requests to VPS (with HMAC auth) - If not set → self-contained (current behavior)
- Proxy traffic (WS, gRPC, XHTTP) always local
sequenceDiagram
participant Worker as CF Worker
participant Backend as VPS Backend
Worker->>Backend: API Request (HMAC signed)
Worker->>Internet: Proxy Traffic (always local)
Worker->>Backend: Heartbeat (every 30s)
frontend/
├── app/
│ ├── layout.tsx # Root layout
│ ├── page.tsx # Redirect to /panel
│ ├── login/page.tsx # Login
│ └── panel/
│ ├── layout.tsx # Sidebar + nav
│ ├── page.tsx # Dashboard
│ ├── nodes/page.tsx
│ ├── users/page.tsx
│ ├── cleanip/page.tsx
│ ├── protocols/page.tsx
│ ├── settings/page.tsx
│ └── wallet/page.tsx
├── components/
│ ├── ui/ # shadcn/ui (reuse existing)
│ ├── layout/ # sidebar, mobile-nav, header
│ ├── dashboard/ # stat-card, node-performance
│ ├── users/ # user-table, dialogs
│ ├── cleanip/ # isp-detection, ip-scanner
│ └── settings/ # disguise, network, telegram
├── lib/
│ ├── api.ts # fetch wrapper
│ ├── auth.ts # auth context + hooks
│ ├── protocol-utils.ts # from src/lib/
│ └── types.ts # from worker/types.ts
├── next.config.ts
├── tailwind.config.ts
├── package.json
└── tsconfig.json
- App Router (Next.js 15)
- Server Components for data fetching
- Middleware for auth guard
NEXT_PUBLIC_API_URLfor backend URL- shadcn/ui components reused from existing
components/
- Cache
worker.js+dist/in~/.xraymod/cache/ - Fallback to local cache when offline
- SQLite for local testing
- FastAPI + SQLite = fully offline
uv run backend/main.py→http://localhost:8000- All API endpoints work without CF Worker
wrangler devwith local SQLite (miniflare)- Connect to local FastAPI backend
- Phase 1 — FastAPI Installer ✅
- Phase 2 — FastAPI Backend ✅
- Phase 3 — Next.js Frontend ✅ (build passes)
- Phase 4 — Nova Features Port ✅
panel.pausedin kvstore → 503 for proxy traffic only (panel/API stay accessible)panel.monthly_cap_gbin kvstore → 503 when total traffic exceeds cap- Applied in router.ts BEFORE proxy handling, AFTER schema init
- 5 attempts per minute per IP
- Stored in kvstore
ratelimit:login:<ip>with timestamp - Returns 429 after limit exceeded
- Timing-safe password comparison
protocol.mixed_modein kvstore → cycles['vless', 'trojan', 'ss']- Each config index gets next protocol in cycle
- Label includes protocol name: "Config (VLESS)", "Config (TROJAN)"
- Clean IPs shuffled per subscription request
- Each node gets unique host from shuffled pool
- Prevents fingerprinting across nodes
graph LR
DisguiseRemap[Disguise remap] --> UUIDCheck[UUID check]
UUIDCheck --> RouteMatching[Route matching]
RouteMatching --> DisguiseFallback[Disguise fallback]
- Secret paths (/x-admin) remap BEFORE UUID check
- UUID strips prefix, second disguise check catches /admin decoy
- Registered routes always execute (not blocked by disguise)
- Phase 4 — Offline testing