Architecture
One binary runs four things over one SQLite file. This page is the short version; the README carries the same material with sequence and ER diagrams.
What runs on one server
| Part | Listens on | Does |
|---|---|---|
| Panel | :2053 /app/ (and :2054 /dl/ for resellers) | Sessions, API, reseller scoping. Same frontend for both, the session decides what is visible. |
| Subscription server | :2056 /sub/ | Three formats, landing page, client-download page, temporary sharing, the "subscription unavailable" page. |
| Data plane | line ports | Embedded sing-box: an inbound per line, an outbound per upstream in use; beyond a line's default upstream, routing rules can send domains / IP ranges / ports to another exit or block them; traffic and connection tracking, per-user limits. |
| Background | — | Stats and limit rules every 10 s, quota judgment every minute, upstream probes (each server checks only what it uses), hourly public IPv4 / IPv6 probing and log cleanup, mainland reachability checks, certificate renewal, backups, master/node sync every 5 s. |
All four share m-ui.db (SQLite in WAL mode). The panel writes, the data plane and subscription server read, so a click in the panel is visible everywhere immediately. There is no message queue, cache server or second database to run.
The only outside calls are optional: GitHub (update check), the v2fly domain list (app domain lookup), Cloudflare / ipify (probing public IPv4 and IPv6), Globalping (mainland reachability) and Telegram (alerts). If one is unreachable only that feature is affected.
What a save does
- Field validation and port checks — against other lines, the panel ports and anything else already listening on the server.
- A write transaction (
BEGIN IMMEDIATE) writes the change. - The full configuration is rendered from the database and handed to sing-box's own parser. If it does not parse, the transaction rolls back and the request fails with the reason. Nothing in production moved.
- On success the change is applied by tier: user → swap the inbound user table (nobody else drops); upstream → hot-swap the outbound; line → restart the data plane, and if the new config fails to start (a port grabbed by another process, say) restore the previous working one.
A subscription request
GET /sub/<key>: the key is matched as a user name, a random subscription token, or a temporary share token (which serves the same user with a second credential set). With the subscription page on (the default; the master and each reseller have a switch), a browser gets the landing page for a key that matches (the reason is shown at the top when the user is disabled, expired or out of traffic; a share token gets a trimmed page without the owner's usage and expiry); a client gets universal links, Clash YAML or a sing-box config depending on ?format= (picked from the User-Agent when it is absent), or a 404 while the user (or their reseller) is disabled, expired or out of traffic. A key that matches nobody gets a short "invalid subscription link" page in browsers and a plain 404 for clients. With the page switched off, browsers are treated like clients: the raw subscription, or a plain 404 when the user is blocked or the key matches nobody. Nodes are the user's assigned lines × the servers each line is deployed on, plus external nodes and subscriptions.
Master and nodes
Every 5 seconds the master snapshots lines (with routing rules), upstreams, users, credentials, resellers, active limit-rule states and synced settings, hashes them into a revision, pushes to all nodes concurrently and pulls each node's report (traffic since a cursor, online IPs, public IPv4 / IPv6, upstream health). Each server probes its own public addresses and renders its own config, so an IPv6-only node handles DNS for its own situation. Nodes never judge quota; users the master disables simply disappear from the next snapshot. Details on the multi-server page.
Data model
| Table | Holds | Relations |
|---|---|---|
| lines | protocol, port, TLS, transport, options, which servers, routing rules | → upstream (exit); ↔ users via user_lines; ↔ nodes |
| users | credentials per protocol, quota and usage, expiry, device and speed limits, subscription key, share token | ↔ lines; → reseller (optional); ← plans on create |
| upstreams | outbound type and options | ← lines |
| nodes | name, domain, connect address, probed public IPv4 / IPv6, which one subscriptions use, API URL and token, ratio | ↔ lines |
| rules | schedule / burst limit rules and whom they apply to | → users, resellers |
| resellers | budgets (traffic, bandwidth, devices), expiry, own landing copy, granted lines | → users, plans |
| stats, agent_counters, traffic_cursors | time series and cross-server accounting | |
| settings, admins, sub_logs, audit | everything else |
Background cadence
| Every | What |
|---|---|
| 5 s | Master → nodes snapshot push and report pull |
| 10 s | Read traffic and connections from the data plane, write per user / line / upstream stats |
| 10 s | Evaluate limit rules (schedule / burst); active states ride the next snapshot to nodes |
| 1 min | Quota, expiry and periodic resets; data-plane watchdog |
| 10 min | WAL checkpoint so the live database is always safe to copy |
| 10 min (configurable) | Upstream probes, down / recovered alerts |
| 30 min (configurable) | Master refreshes external subscriptions |
| 90 min (configurable) | Master runs the mainland reachability check (over IPv4; servers with IPv6 lines also get an IPv6 inbound check from probes abroad in the same round) |
| 1 h | Probe public IPv4 / IPv6; expiry and usage warnings; prune series and logs by retention, fold minute samples older than 48 h into hourly buckets |
| 6 h | Version check against GitHub Releases (check only; through local WARP when GitHub is unreachable directly) |
| 12 h | Certificate renewal check (sing-box swaps the renewed certificate itself, no restart) |
| daily | Daily report; scheduled backup |
Code layout
| Directory | Responsibility |
|---|---|
web/ | Panel and API, reseller panel, external API, embedded frontend (zero-build ES modules) |
sub/ | Subscription formats, landing page, client downloads, sharing |
render/ core/ | Lines → sing-box config and its dry run (routing rules, DNS redirect on IPv6-only servers); the embedded data plane and its tracking |
hub/ | Snapshot push, traffic reclaim, online aggregation |
runner/ | Process orchestration, three-tier reload and rollback, certificates, backups |
jobs/ monitor/ rules/ | Stats, quota enforcement, limit rules, probes, alerts |
reach/ acme/ | Mainland reachability; certificate issuance and public IP probing |
appdomains/ | App name → domains lookup (v2fly domain list) |
database/ | Models, SQLite open and migration |
selfupdate/ deploy/ | Version check and in-place update, installer |
Diagrams: README → Architecture. Deeper dives: why the core is embedded · how hot reload works · how sync works.