prasx/vless-manager-proxy

Purpose and Runtime

VLESS Manager Proxy is a Flask-based control plane for importing, validating, selecting, and operating VLESS proxies through a local Xray instance. It exposes an HTML dashboard, REST/SSE APIs, and a generated subscription endpoint for VLESS clients.

Primary process entry point: app.py. Flask application creation and route registration are centralized in app/__init__.py. Deployment is intended as a systemd service via vless-manager.service.

Web and API Boundary

Server-rendered dashboard pages are handled separately from operational APIs:

• Page routes: app/routes/pages.py

• REST APIs, SSE test-progress stream, subscription, Xray controls, traffic/connections endpoints: app/routes/api.py

• Browser clients and dashboard interactions: static/dashboard.js, static/sources.js, static/settings.js

The API is the control boundary between the UI/external consumers and proxy lifecycle services. /api/subscribe.txt is a machine-facing output consumed by VLESS-compatible clients.

Persistent State and Settings

SQLite is the durable source of truth for proxies, sources, settings, logs, and likely test/traffic state:

• app/db.py

• config.py

The database layer owns schema initialization/migrations and settings access. Runtime configuration combines base defaults in config.py, persisted UI settings, and potentially environment configuration such as import proxy settings. Generated subscription content is cached/exported as configured through the subscription stage.

Source Import and Proxy Normalization

Import sources may be remote URLs or stored text content. Importing supports conditional HTTP retrieval through ETags, import-proxy routing, and curl fallback; repeated source imports remove stale proxies absent from the refreshed subscription:

• app/importer.py

• app/vless.py

• app/utils.py

app/vless.py is the protocol boundary that parses vless:// inputs into structured proxy records/configuration. Utility enrichment determines country metadata from link fragments or external IP geolocation (ip-api.com).

Validation and Background Lifecycle

The proxy manager coordinates concurrent proxy checks, scheduled DB-only versus import-and-check runs, cancellation/progress reporting, optional failed-node cleanup, speed testing, and failover reconciliation:

• app/proxy_manager.py

• app/importer.py

• app/db.py

Validation is not merely socket probing: each candidate is tested using a temporary Xray execution and an HTTP generate_204 request. Working candidates may then undergo throughput tests; those measurements influence active-node ordering. Progress crosses to clients via API/SSE rather than direct worker/UI coupling.

Xray Configuration and Apply Boundary

The configurator translates selected database proxies and settings into Xray configuration, including SOCKS/HTTP inbounds, country filtering, GeoSite routing, sniffing, Observatory, and balancer strategy:

• app/xray_configurator.py

• app/subscribe.py

• config.py

It also interfaces with Xray’s local gRPC API and system service lifecycle to apply/rebuild configuration and inspect outbounds. This is the critical side-effect boundary: database candidates become live Xray outbounds, while app/subscribe.py emits the corresponding allowed/working VLESS links for external clients.

Monitoring and Host Dependencies

Operational visibility includes Xray outbound status, application logs, traffic history, active connections, and performance recommendations:

• app/proxy_manager.py

• app/routes/api.py

• static/logs.js

Material dependencies are Python 3.9+, Flask, SQLite, Xray 26.3+, and systemd. Xray needs installed geo assets (geosite.dat, geoip.dat) for routing. Host-level traffic and connection telemetry depends on nftables and conntrack; management may invoke systemctl to control the separate Xray service.