Core Concepts

Before deploying, it helps to understand the nouns VGate is built around.

Manager

The backend service and the source of truth for everything: users, nodes, plans, orders, traffic, and (hot-reloadable) system config. Proxy nodes are clients of the manager, not peers.

Node (Server)

A single deployed server binary running a VLESS inbound. Identified by a node_id and authenticated to the manager with a node_token. Each node:

• syncs its config and authorized user list from the manager,
• serves proxy traffic for those users,
• reports per-user, per-entry-point traffic back.

A node's listen port, transport, and security settings are managed in the admin console, not in the node's local config.yml.

Virtual node

A lightweight multi-IP child of a real node. Virtual nodes live in the same table but carry a parent_id: they inherit the parent's transport/security config and only add their own display identity — name, address (an alternate entry IP), an optional port override, level, and enabled flag. They never poll and never authenticate (their token is a non-secret placeholder).

Virtual nodes are how one server is exposed under several addresses. When the parent uses Reality security, each child can carry a dedicated Reality short ID (reality_sid): the manager keeps it in the parent's short_ids whitelist, subscription links for that child advertise it, and the node attributes traffic arriving with it back to the child — so the admin Traffic page breaks usage down per entry point, not just per server. Only the native tcp + reality path is attributable; ws / xhttp and non-reality traffic always book to the real parent.

Dashboard node counts and Telegram node-up/down alerts cover real nodes only — virtual children never poll, so counting them would only distort the numbers.

User

An account that is allowed to connect to one or more nodes. A user has credentials (VLESS UUID / flow), an optional subscription plan, a quota, and an expiry. Users authenticate to the user portal and to VLESS clients via subscription links.

Plan

A purchasable offering: defines price, traffic quota, and duration/expiry. Plans are created by super_admins.

Order

A billing record tying a user to a plan, with a payment state. Orders are closed on payment (payment gateway notify) or by the expired-order closer.

Subscription

A per-user token (sub_token) that produces a standard subscription link (GET /sub/:sub_token). VLESS client apps and the user portal consume it to fetch node endpoints and credentials.

Traffic accounting

• Delta counters: the server node tracks bytes per user and entry point (real node vs. virtual child, matched by Reality short ID) in memory.
• Report: GetAndResetTraffic returns the accumulated deltas and resets them; posted to POST /server/traffic with the entry point's node_id per delta.
• Aggregation: the manager records hourly traffic stats as nodes report it, attributes each delta to the entry point it arrived on, and enforces quotas against the configured quota.reset_day.

System config

Runtime-tunable settings (JWT TTLs, log level/format, CORS origins, timeouts) stored in the DB and merged over config.yml. Change them via PUT /api/v1/admin/system-config without a restart.

Roles

Role	Capabilities
admin	Manage nodes, users, traffic, stats, orders, system config.
super_admin	Everything admin can do, plus manage plans and other admins.

Auth domains

Three distinct auth mechanisms, deliberately separated:

• User JWT — user portal and /user/* endpoints.
• Admin JWT — admin console and /admin/* endpoints; refreshable.
• Node token — node_auth middleware on /server/* endpoints.

Sync interval

How often each server node calls sync(). Short intervals mean faster propagation of user/config changes; the HTTP 304 optimization keeps the cost low when nothing changed.