One master, any number of nodes
m-ui is a multi-server sing-box panel by design, not by add-on. Every server runs the same binary; one is the master and does the accounting, the others only forward traffic.

Roles
| Master | Node | |
|---|---|---|
| Panel | Full: lines, users, upstreams, resellers, settings | Read-only view of what the master pushed; local settings, certificate, logs |
| Data plane | Embedded sing-box, serves its own lines | Embedded sing-box, serves the lines deployed to it |
| Accounting | Rolls up traffic from every server, judges quota, expiry and device limits | Keeps a monotonic counter per user, reports deltas |
| Subscriptions | Serves them (nodes also can, with the same data) | Same data, same formats |
Pairing a node
- Install m-ui on the new server with the same one-line installer.
- In its panel, Settings → Run as node. The pairing card shows its API address and token.
- On the master, Servers → Add server, paste the address and token, give it a name and a domain or IP. Each node issues its own certificate (self-signed is fine).
That is the whole procedure. Within five seconds the node shows online · synced and starts serving the lines deployed to it.
Versions: keep the master and the nodes on the same version, and upgrade the nodes first, then the master. Once the master uses a newer feature, a node that is too old rejects the whole sync and keeps serving its last configuration (the Servers page marks it "Version differs from master") until it is upgraded.
What gets synced, and how
Every 5 seconds the master builds a snapshot — lines, upstreams, users with credentials, user↔line assignments, external nodes, resellers and the subscription settings — hashes it into a revision, and pushes it to every node concurrently. A node that already has that revision does nothing; one that does not applies it and reloads its data plane using the same three-tier reload as the master: user changes hot-swap the inbound user table, upstream changes hot-swap outbounds, only line changes restart sing-box (with rollback if the new config fails to start).
In the same round the master pulls each node's report: traffic since the last cursor, online source IPs per user, version, core status, certificate days left and renewal results, recent inbound connections. Nodes usually have no notifications of their own, so the master alerts for their failed renewals and expiring certificates. A slow or unreachable node only delays itself; the others sync on time.
Traffic, quota and device limits across servers
- Traffic is accounted once. Nodes keep a monotonic per-user counter; the master stores a cursor per node and adds only the delta. A node that reinstalls (counter resets) is detected and re-based, so nothing is double-counted.
- Quota and expiry are judged on the master only. A user who runs out is simply absent from the next snapshot, so every server stops serving them within seconds.
- Device limit counts source IPs across all servers: IPv4 addresses and IPv6 /64s are counted separately and each must stay within the limit (a dual-stack device never counts twice; a limit of 3 allows up to 3 IPv4 addresses plus 3 IPv6 /64s). The master merges online IPs from every node and pushes each node the IPs seen elsewhere, so the limit applies to the whole fleet, not to each server.
Subscriptions with many servers
A line deployed to N servers appears N times in the user's subscription, named line – server, with each server's own domain or IP. Clash, sing-box and universal-link clients then pick by latency or let the user choose. Adding a server to a line updates every subscription on the next refresh — no per-user edits. When you do want a user, a plan or a reseller grant to carry only one server's entry of a line, pick that entry instead of the whole line; the subscription then lists just that one.
A line deployed on several servers gets a latency-tested group named after the line in Clash and sing-box subscriptions (not when the user only has one server on that line), with node names and order unchanged. Line names always stay with your own lines: external nodes with the same name become "X 2" whether or not the group appears, so a client that picked the line group never lands on a third-party node of the same name.
When a node goes offline
- The node keeps forwarding with the configuration it has. Users on it do not notice.
- The master marks it offline, sends a Telegram alert after a minute if configured, and keeps trying every 5 seconds.
- When it returns, the cursor picks up traffic from where it left off and the current snapshot is pushed. Users disabled meanwhile are removed on that push.
Moving the master, and when the master dies
Two things: Set as master moves the master to another server as planned; master failover lets a standby take over when the master dies (the VPS crashes or gets deleted). Both are done on the master's panel, or over SSH with m-ui ha status | takeover | set-master | abandon | pause | resume | yield | reset.
Set as master
- Click the server's role tag on the Servers page → "Set as master" and enter the admin password once. The confirmation lists the new panel address, the new reseller-panel address and the IP the subscription domain should point to.
- All of the master's data is handed to that server encrypted end to end; it becomes the master with a higher epoch and the old master turns into a node. To move to a fresh VPS, add it like a node and set it as master once synced, with no backup or restore.
- Writes pause for a minute or two (at most 15–60 minutes depending on the database size, with a deadline shown); if any step fails before the commit, it is cancelled automatically and the old master carries on.
- If the target goes silent after the commit request (unknown result), writes stay paused and this server asks the target every 10 seconds; at the deadline it checks whether any node follows the target and, if none does, fences it off with a higher epoch and resumes writes. If unreachable nodes are gone for good and cannot confirm, run
m-ui ha abandon --forceon the master. - If the link to that server is plain http, you must tick a risk acknowledgement first: an active man in the middle on the link could read and rewrite the whole database. Switch to https first if you can; a self-signed certificate with a pinned fingerprint is fine.
- It does not promise that every byte gets counted: traffic on these two servers' own lines between packing the data and their restarts is not counted towards users' usage; traffic on the other nodes is recovered through the cursors as usual.
Master failover
- Turn it on in Settings → Master failover; it is off by default. The first few nodes in the server list (2 by default, 1–3) become standbys and regularly receive a replica of the data, encrypted to their own public key and signed by the master.
- Takeover modes: Off, Confirm, then take over (the default: 3 minutes after the master is lost a Telegram message arrives; reply with the code or click on the standby's panel) and Take over automatically when the master is lost (after 10 minutes; a majority of nodes must agree with three or more servers, and with one master and one node overseas probes must fail to reach the master too).
- Lost means all of: the standby has heard nothing from the master for over a minute, the other nodes cannot reach it either, and overseas probes cannot reach it. The master being blocked from mainland China, one node losing its link, or the master upgrading or restarting does not count; you can also pause takeovers before an upgrade.
- Against split brain, every change of master raises the epoch and nodes only follow the highest one; an old master that comes back turns into a node. A takeover cannot recover changes made after the last replica or a few minutes of traffic on the old master's own lines.
- Nodes linked over plain http are not standbys by default; allow them under Advanced only if you trust the link. Every node needs v0.7.17 or later, and upgrade the nodes first, then the master.
- Restoring the master's backup on another server and starting it moves the master there: the old master is pushed down to a node if it starts again. If you only want to look inside a backup, do not start it on a machine that is online.
- What a takeover moves over: master duties only by default — pushing configs, merging traffic, expiry / quota cut-offs, the Telegram bot and the external API move to the new master, while its subscription settings and DNS stay as they are (subscription addresses still point to the old master, so refreshing fails while it is gone; connected lines keep working). "Subscriptions too" needs the subscription address on a domain and a DNS API limited to that domain (Cloudflare, Aliyun DNS, Tencent DNSPod): on takeover the A / AAAA records pointing at the old master move to the new one, and the subscription certificate is reissued through the same API if the one carried over cannot be used; when the panel also uses a domain, the panel, reseller panel and external API addresses follow the master, so shops and bots keep their URLs. The DNS API is self-checked every 6 hours. Set as master is not affected by this choice and always moves everything.
- Traffic charts, subscription logs and older audit entries go to standbys as separate encrypted, signed history data (about hourly) and are merged into the new database on takeover, so the charts do not start blank.
- Two masters at once (a standby took over but cannot reach the other nodes, and most of them still follow the old master when it returns): both sides turn red under Needs attention and Telegram gets one message; on the server with the higher epoch click "Hand back master" (or run
m-ui ha yield). - With failover on, the ports a node needs after a takeover are kept free of lines and relay entries; standbys check them every 10 minutes and warn when another program holds one, and at takeover fall back to their own previous port, then to a free one.
Traffic ratio
Each server has a ratio (default 1). Traffic through a server with ratio 2 counts double against the user's quota — useful for premium routes or expensive bandwidth. A user's usage and the charts in the user details and on the landing page all show the scaled numbers, so they reconcile. A node's landing page only sees the traffic through that node, so it shows no chart.
Deeper: how the sync protocol is built · architecture overview