V2Hub — An Ecosystem for Managing VPN Subscriptions (V2Ray/Xray/VLESS/VMess/Trojan/Hysteria2)

#opensource #python #vpn #fastapi

Why this exists

If you've ever handed out VPN configs or small subscription links to friends or clients manually, you know the pain: one provider goes down, another changes its address, a third needs to be temporarily hidden — and the end user is supposed to keep using a single, unchanging subscription URL that always resolves to the current list of servers. V2Hub is an attempt to solve this end-to-end: not just a proxy aggregator, but a full ecosystem — API, web panel, CLI, Telegram bot, and admin tooling.

One clarification up front: this project does not generate VPN configs. If you're looking for how to set up a VPN server from scratch, check out vless.wiki. V2Hub is purely about managing subscriptions and configs you already have — aggregating them, hiding sources, annotating them, resolving nested references, and serving it all as one link.

The components

Repo	Try it live	Role
v2hub-api	v2hub.link	Core — FastAPI service that aggregates and resolves subscriptions
v2hub-core	PyPI	Python library with core methods for managing subscriptions
v2hub-admin	PyPI	Add-on module providing admin functionality (HMAC auth, user CRUD)
v2hub-cli	PyPI	Terminal client built with Typer and Rich
v2hub-panel	panel.v2hub.link	Web panel for managing subscriptions (FastAPI + vanilla JS)
v2hub-bot	Telegram Bot	Telegram bot for self-service subscription access

The core — v2hub-api

This is the most fleshed-out piece, so it's worth going into some detail.

Multi-source aggregation. A subscription can pull configs from three kinds of sources at once: raw URIs (vless://, vmess://, trojan://, ss://, etc.), external subscription URLs from another provider, and internal references to other subscriptions inside the same system.

Recursive resolution. If subscription A references subscription B, which references C, everything gets flattened into a single list by the time it reaches the client. There's circular-reference detection built in, plus a configurable nesting depth limit (max_depth, default 3).

Per-source fine-tuning. Any source inside a subscription can be hidden from the resolved output (is_hidden) without deleting it, and annotated with its own comment.

Two-tier caching. Redis as a fast L1 cache, PostgreSQL as the source of truth. A Celery worker refreshes external sources on a schedule (Celery beat, every 15 minutes), so resolution is almost always served from cache. Next up: replacing the periodic worker with lazy refresh, triggered right at request time instead.

Admin-side security. Admin endpoints aren't protected by a plain token — they require an HMAC-SHA256 signature over the request (timestamp + method + path + body), plus an IP whitelist on top. There's also Redis-backed rate limiting per endpoint, with automatic IP bans once violations pile up.

Core stack: FastAPI 0.136, SQLAlchemy 2.0 (async) + asyncpg, Pydantic 2.13, Celery 5.6, Alembic for migrations, Uvicorn + Nginx.

Panel, CLI, bot

v2hub-panel is a minimal web UI for managing subscriptions and sources straight from the browser.

v2hub-cli is built on Typer and Rich — you can create subscriptions, add sources, and run admin operations right from the terminal with nicely formatted output.

v2hub-bot is a simple bot whose main job is issuing access tokens. It embeds v2hub-panel as a mini-app for extra convenience.

Python libraries on PyPI

v2hub — a library that bundles everything an end user needs to work with subscriptions.

v2hub-admin — an add-on to the core library that handles user CRUD, plus allow-lists and ban-lists.

Who this might be useful for

Anyone running a small VPN service for themselves, friends, or a small company, who wants a ready-made infrastructure with monitoring built in instead of hacking something together.
Anyone curious what a genuinely "production-ready" FastAPI project looks like end to end — migrations, async ORM, HMAC auth, observability, CI/CD — regardless of the domain (VPN is more the excuse here than the point).
Developers who want to see a working example of recursive resolution over nested entities with cycle protection — a pattern that's useful well beyond VPN tooling.
Where this is headed

If the project finds an audience and builds up a small community around it, we'll keep developing it. The long-term goal is for V2Hub to become a real alternative to Marzban API and 3x-ui for subscription management — something usable not just by hobbyists and small projects, but by full-fledged VPN companies too.