m-uising-box panel

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

PartListens onDoes
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 planeline portsEmbedded 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

  1. Field validation and port checks — against other lines, the panel ports and anything else already listening on the server.
  2. A write transaction (BEGIN IMMEDIATE) writes the change.
  3. 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.
  4. 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

TableHoldsRelations
linesprotocol, port, TLS, transport, options, which servers, routing rules→ upstream (exit); ↔ users via user_lines; ↔ nodes
userscredentials per protocol, quota and usage, expiry, device and speed limits, subscription key, share token↔ lines; → reseller (optional); ← plans on create
upstreamsoutbound type and options← lines
nodesname, domain, connect address, probed public IPv4 / IPv6, which one subscriptions use, API URL and token, ratio↔ lines
rulesschedule / burst limit rules and whom they apply to→ users, resellers
resellersbudgets (traffic, bandwidth, devices), expiry, own landing copy, granted lines→ users, plans
stats, agent_counters, traffic_cursorstime series and cross-server accounting
settings, admins, sub_logs, auditeverything else

Background cadence

EveryWhat
5 sMaster → nodes snapshot push and report pull
10 sRead traffic and connections from the data plane, write per user / line / upstream stats
10 sEvaluate limit rules (schedule / burst); active states ride the next snapshot to nodes
1 minQuota, expiry and periodic resets; data-plane watchdog
10 minWAL 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 hProbe public IPv4 / IPv6; expiry and usage warnings; prune series and logs by retention, fold minute samples older than 48 h into hourly buckets
6 hVersion check against GitHub Releases (check only; through local WARP when GitHub is unreachable directly)
12 hCertificate renewal check (sing-box swaps the renewed certificate itself, no restart)
dailyDaily report; scheduled backup

Code layout

DirectoryResponsibility
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.