docs: add multi-node shared control guidance

README.md

@@ -41,6 +41,14 @@ go build -ldflags "-w -s" -o build/x-ui main.go
 
 Production builds embed files from `web/public/assets` and `web/public/assets-manifest.json`.
 
+## Multi-Node Shared Control
+
+- use MariaDB as the shared control database
+- keep one `master` node for shared-account writes
+- configure other nodes as `worker`
+- workers rebuild local Xray config from synchronized snapshots
+- traffic is flushed back as deltas, not absolute totals
+
 ## A Special Thanks to
 
 - [alireza0](https://github.com/alireza0/)

README.zh_CN.md

@@ -30,6 +30,14 @@ bash <(curl -Ls https://raw.githubusercontent.com/Sora39831/3x-ui/master/install
 
 完整文档请参阅 [项目Wiki](https://github.com/Sora39831/3x-ui/wiki)。
 
+## 多节点共享控制
+
+- 使用 MariaDB 作为共享控制数据库
+- 仅保留一个 `master` 节点负责共享账号写入
+- 其他节点配置为 `worker`
+- `worker` 通过同步快照重建本地 Xray 配置
+- 流量按增量回刷，不覆盖绝对总量
+
 ## 特别感谢
 
 - [alireza0](https://github.com/alireza0/)

docs/multi-node-sync.md

@@ -0,0 +1,29 @@
+# Multi-Node Shared Control
+
+## Roles
+
+- `master`: the only node allowed to change shared account definitions
+- `worker`: rebuilds local Xray config from shared snapshots and flushes traffic deltas
+
+## Requirements
+
+- shared mode requires MariaDB
+- each worker needs a unique `nodeId`
+- workers keep `/etc/x-ui/shared-cache.json` for outage survival
+
+## Runtime Loops
+
+- workers poll `shared_accounts_version` every `syncInterval`
+- all nodes flush `/etc/x-ui/traffic-pending.json` every `trafficFlushInterval`
+- only `master` runs shared traffic reconciliation that can disable or renew clients
+
+## Manual Verification
+
+1. Start a `master` node on MariaDB.
+2. Start a `worker` node on the same MariaDB with a unique `nodeId`.
+3. Change an inbound or client on `master`.
+4. Confirm the worker sees a newer `shared_accounts_version` and rebuilds local Xray.
+5. Generate traffic on both nodes.
+6. Confirm aggregated MariaDB counters increase without overwriting each other.
+7. Stop MariaDB briefly and confirm the worker continues using `shared-cache.json`.
+8. Restore MariaDB and confirm pending traffic deltas flush successfully.