fix(sub): emit host TLS verification at xray level in JSON subscription

The JSON subscription flattens tlsSettings into xray's client shape before
the per-host loop, then applyExternalProxyTLSToStream writes the host's
echConfigList, verifyPeerCertByName, pinnedPeerCertSha256 and
allowInsecure into the panel-only tlsSettings.settings map. Xray ignores
that map, so a host's ECH (and its pins / verify name) never reached the
client and connections through the host failed.

After the host overrides are applied, lift that map through the same
writer tlsData uses for the inbound's own TLS: fields land at the top of
tlsSettings, pins are joined into the comma string xray parses, and
allowInsecure is dropped exactly as it is for the inbound (removed from
xray). The Clash renderer still reads the nested map and is unchanged.

The helper-level subtest that pinned the nested location as the "json"
shape is replaced by an end-to-end GetJson test on a host-backed inbound.

Closes #6743

.github/workflows/ci.yml

@@ -141,6 +141,22 @@ jobs:
           # internal/web/service runs ~10x slower under -race and overruns the 10m default.
           go test -race -shuffle=on -count=1 -timeout 25m $(cat /tmp/go-packages.txt)
 
+  # A real master and node panel, each its own process, driven through node sync.
+  # A SKIP here means the binary was never handed over, so it fails the job.
+  node-e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: actions/setup-go@v7
+        with:
+          go-version-file: go.mod
+          cache: true
+      - name: Master + node end to end
+        run: |
+          set -o pipefail
+          make node-e2e 2>&1 | tee /tmp/node-e2e.log
+          if grep -q -- '--- SKIP' /tmp/node-e2e.log; then echo "node-e2e skipped"; exit 1; fi
+
   # Brief native-fuzz smoke on the security-/parser-critical decoders. Each runs the
   # generated corpus plus 30s of exploration; a crash here is a real input-handling bug.
   fuzz-smoke:

CLAUDE.md

@@ -160,9 +160,10 @@ file locations when it can answer in one hop.
   `-race`); `httptest` for HTTP. Keep `database.InitDB` for reopening a file or
   migrating a hand-built legacy DB. `internal/sub`'s `initSubDB(t)` is the template.
 - Code must pass `golangci-lint run` (gofumpt + goimports formatting): `make lint`.
-- Postgres, xray-gRPC-e2e and scale tests `t.Skip` unless `XUI_TEST_PG_DSN`,
-  `XUI_DB_TYPE`+`XUI_DB_DSN`, `XRAY_E2E_BINARY` or `XUI_SCALE_TEST` is set — a
-  green `go test ./...` does not mean those paths ran.
+- Postgres, xray-gRPC-e2e, master+node and scale tests `t.Skip` unless
+  `XUI_TEST_PG_DSN`, `XUI_DB_TYPE`+`XUI_DB_DSN`, `XRAY_E2E_BINARY`,
+  `XUI_NODE_E2E_BINARY` or `XUI_SCALE_TEST` is set — a green `go test ./...`
+  does not mean those paths ran.
 
 ## Frontend conventions (summary; full version in frontend/CLAUDE.md)
 - Ant Design 6 only — no Tailwind/shadcn. Targeted tweaks, not rewrites.
@@ -191,9 +192,13 @@ reads as a broken repo, not a missing step. Run `make dist-stub` once; every
     make verify   # gen-check + lint + typecheck + test + build + build-storybook
 
 That is the *fast* gate, not all of CI. `ci.yml` also runs `make race`,
-`make vulncheck`, a live-Postgres job (where a SKIP counts as a failure) and a
+`make vulncheck`, a live-Postgres job (where a SKIP counts as a failure),
+`make node-e2e` (a real master and node panel, `internal/nodee2e/`) and a
 30s fuzz smoke on `FuzzParseLink`/`FuzzDecodeCertPin` — run those locally when
-you touch DB/dialect or parser code.
+you touch DB/dialect, node sync or parser code. Node sync has two layers: every
+`runtime.Remote` call gets a cell in `internal/web/node_contract_test.go` (fast,
+in `make test-go`; a method without one fails it), and a multi-tick flow (cron,
+adopt, node down) gets one in `internal/nodee2e/node_sync_test.go`.
 
 Common targets: `make gen` (regenerate Zod/OpenAPI), `make lint` (Go + frontend),
 `make test` (Go `-shuffle=on` + frontend), `make race`, `make build`. See `Makefile`.

Makefile

@@ -58,6 +58,13 @@ test-go: dist-stub ## Go tests (shuffle, no cache)
 race: dist-stub ## Go tests with the race detector (needs a C compiler)
 	go test -race -shuffle=on -count=1 -timeout 25m $(GO_PKGS)
 
+.PHONY: node-e2e
+# Two real panel processes (master + node); test-go only runs nodee2e as a skip.
+NODE_E2E_BIN = $(CURDIR)/.cache/node-e2e/x-ui$(shell go env GOEXE)
+node-e2e: dist-stub ## Master+node sync end to end with two real panel processes
+	go build -o $(NODE_E2E_BIN) .
+	XUI_NODE_E2E_BINARY=$(NODE_E2E_BIN) go test -count=1 -timeout 20m -v ./internal/nodee2e/
+
 .PHONY: test-fe
 test-fe: ## Frontend tests (vitest)
 	cd $(FRONTEND) && npm test

README.md

@@ -29,7 +29,7 @@ Built as an enhanced fork of the original X-UI project, 3X-UI adds broader proto
 - **Multi-protocol inbounds** — VLESS, VMess, Trojan, Shadowsocks, WireGuard, AmneziaWG, TUIC v5, Hysteria2, MTProto, HTTP, SOCKS (Mixed), Dokodemo-door / Tunnel, and TUN.
 - **Modern transports & security** — TCP (Raw), mKCP, WebSocket, gRPC, HTTPUpgrade, and XHTTP, secured with TLS, XTLS, and REALITY.
 - **AmneziaWG built in** — DPI-resistant WireGuard runs inside the panel on a userspace network stack, with no kernel module, DKMS, or extra packages to install.
-- **TUIC v5 sidecar** — High-performance QUIC-based proxy with native UDP relay traffic metering, 0-RTT handshakes, and BBR congestion control.
+- **Native TUIC v5 server** — In-process Go QUIC server with Xray routing and per-client traffic accounting; BBR and New Reno are available server-side. CUBIC is preserved in the client profile but currently falls back to New Reno on the server.
 - **MTProto proxies** — per-client FakeTLS secrets, ad-tags, and quotas, applied live without dropping existing connections.
 - **Fallbacks** — serve multiple protocols on a single port (e.g. VLESS and Trojan on 443) using Xray's fallback support.
 - **Per-client management** — traffic quotas, expiry dates, IP limits with trusted-address exemptions, HWID device limits, scheduled renewal cycles, live online status, and one-click share links, QR codes, and subscriptions.

README.ru_RU.md

@@ -29,7 +29,7 @@
 - **Многопротокольные входящие подключения** — VLESS, VMess, Trojan, Shadowsocks, WireGuard, AmneziaWG, TUIC v5, Hysteria2, MTProto, HTTP, SOCKS (Mixed), Dokodemo-door / Tunnel и TUN.
 - **Современные транспорты и безопасность** — TCP (Raw), mKCP, WebSocket, gRPC, HTTPUpgrade и XHTTP, защищённые с помощью TLS, XTLS и REALITY.
 - **Встроенный AmneziaWG** — устойчивый к DPI WireGuard работает прямо в панели на сетевом стеке в пространстве пользователя: без модуля ядра, DKMS и дополнительных пакетов.
-- **Встроенный TUIC v5** — высокопроизводительный прокси на базе QUIC с нативным учётом трафика через UDP-релей, 0-RTT рукопожатиями и контролем перегрузок BBR.
+- **Нативный TUIC v5** — Go QUIC-сервер работает внутри процесса панели. Трафик маршрутизируется через Xray, а учёт ведётся по клиентам. На сервере доступны BBR и New Reno; CUBIC сохраняется в профиле клиента, но на сервере пока использует New Reno.
 - **MTProto-прокси** — секреты FakeTLS, ad-tag и квоты для каждого клиента применяются на лету, не разрывая существующие соединения.
 - **Fallback** — обслуживание нескольких протоколов на одном порту (например, VLESS и Trojan на 443) с помощью функции fallback в Xray.
 - **Управление по каждому клиенту** — квоты трафика, даты истечения, лимиты IP с исключениями для доверенных адресов, лимиты устройств (HWID), запланированные циклы продления, статус «онлайн» в реальном времени, а также ссылки для общего доступа, QR-коды и подписки в один клик.

docs/content/docs/en/config/tuic.mdx

@@ -15,16 +15,16 @@ unstable networks.
 
 ## Key settings
 
-### Server & QUIC parameters
+### Server, QUIC & client-profile parameters
 
 | Field | Description |
 | --- | --- |
 | **Port** | UDP port for incoming client QUIC connections. |
 | **Certificate & Key** | Full TLS certificate chain and private key. QUIC mandates TLS encryption; self-signed certificates or valid Let's Encrypt / ACME certs are supported. |
-| **SNI** | Server Name Indication matching your TLS certificate domain name. |
-| **Congestion Control** | QUIC congestion control algorithm: `bbr` (recommended for high throughput), `cubic`, or `new_reno`. The server runs `bbr` or `new_reno`; `cubic` is sent to clients but served as `new_reno`. |
+| **SNI** | Client-profile Server Name Indication. Set it to the domain covered by the server certificate; this field does not configure the listener certificate. |
+| **Congestion Control** | QUIC congestion control algorithm used in the server setting and exported client profile: `bbr`, `cubic`, or `new_reno`. The server runs BBR or New Reno; when CUBIC is selected, the client profile keeps CUBIC while this server currently falls back to New Reno. |
 | **ALPN** | Application-Layer Protocol Negotiation tokens (default: `h3`). |
-| **UDP Relay Mode** | Packet encapsulation mode: `native` (QUIC datagrams, recommended) or `quic`. |
+| **UDP Relay Mode** | Client-profile packet mode: `native` (QUIC datagrams) or `quic` (unidirectional streams). The server accepts both modes regardless of this exported preference. |
 | **Zero-RTT Handshake** | Enables 0-RTT connection resumption to eliminate initial handshake round-trips for returning clients. |
 | **Authentication Timeout** | Maximum time (seconds) allowed for client authentication before disconnecting (default: `3s`). |
 | **Max Idle Time** | Inactivity timeout (seconds) before closing idle QUIC connections (default: `15s`). |
@@ -105,6 +105,8 @@ tuic://<uuid>:<password>@<host>:<port>?congestion_control=bbr&alpn=h3&sni=vpn.ex
   - **Native in-process Go engine**: TUIC v5 runs 100% natively in Go within the 3x-ui process. No external binaries or sidecars to download or maintain.
   - **Full Xray routing & cascading**: Decrypted traffic passes directly through Xray's routing engine. Inbound tags (`in-<port>-udp`) work seamlessly with routing rules, domain/IP blocks, and cascading to any outbound proxy (VLESS, Shadowsocks, WARP, etc.).
   - **Per-client traffic limits & expiration**: Individual traffic quotas (`totalGB`) and expiration timestamps (`expiryTime`) are tracked and enforced for each client.
+  - **Live speed & traffic totals**: Native TUIC client counters are sampled every 10 seconds and sent to the panel for per-client live speed. Xray meters inbound totals through the loopback relay; TUIC's client-speed event does not add inbound totals again.
+  - **UDP resource bounds**: Each QUIC connection can hold up to 256 active UDP associations. Idle associations are closed after five minutes. This is a per-connection limit, not a node-wide association cap. TUIC uses a reserved loopback SOCKS relay port in `64001–65000`; 3x-ui checks it against managed inbound and relay ports.
   - **Zero-downtime client updates**: Adding, modifying, or disabling clients updates the in-memory user registry instantly without restarting the UDP port or interrupting existing client sessions.
   - **Deployment**: A TUIC inbound can be created on, or cloned to, a sub-node. The node's own panel runs the TUIC server, so the node must run panel v3.8.0 or newer; the master refuses an older node.
 </Callout>

docs/content/docs/ru/config/tuic.mdx

@@ -14,16 +14,16 @@ icon: Zap
 
 ## Ключевые параметры
 
-### Параметры сервера и QUIC
+### Параметры сервера, QUIC и клиентского профиля
 
 | Поле | Описание |
 | --- | --- |
 | **Порт** | UDP-порт для входящих QUIC-соединений клиентов. |
 | **Сертификат и ключ** | Полная цепочка SSL-сертификата и приватный ключ. Протокол QUIC требует обязательного шифрования TLS; поддерживаются сертификаты Let's Encrypt / ACME или самоподписанные. |
-| **SNI** | Имя сервера (Server Name Indication), совпадающее с доменным именем в сертификате. |
-| **Контроль перегрузок** | Алгоритм контроля перегрузок QUIC: `bbr` (рекомендуется для максимальной скорости), `cubic` или `new_reno`. Сервер работает с `bbr` или `new_reno`; `cubic` передаётся клиентам, но на сервере применяется как `new_reno`. |
+| **SNI** | Server Name Indication для профиля клиента. Укажите домен, покрытый сертификатом сервера; это поле не настраивает сертификат listener'а. |
+| **Контроль перегрузок** | Алгоритм QUIC в настройках сервера и экспортируемом профиле: `bbr`, `cubic` или `new_reno`. Сервер использует BBR или New Reno; при выборе CUBIC клиентский профиль сохраняет CUBIC, а сервер пока применяет New Reno. |
 | **ALPN** | Токены протоколов уровня приложений (по умолчанию: `h3`). |
-| **Режим UDP Relay** | Режим инкапсуляции пакетов: `native` (QUIC datagrams, рекомендуется) или `quic`. |
+| **Режим UDP Relay** | Режим UDP в профиле клиента: `native` (QUIC datagrams) или `quic` (однонаправленные потоки). Сервер принимает оба режима независимо от этого значения. |
 | **Zero-RTT Handshake** | Включает 0-RTT возобновление сессий для мгновенного повторного подключения клиентов без ожидания завершения рукопожатия. |
 | **Таймаут аутентификации** | Максимальное время (в секундах) на прохождение аутентификации клиентом (по умолчанию: `3s`). |
 | **Максимальный простой** | Таймаут бездействия (в секундах) перед закрытием неактивных QUIC-соединений (по умолчанию: `15s`). |
@@ -104,6 +104,8 @@ tuic://<uuid>:<password>@<host>:<port>?congestion_control=bbr&alpn=h3&sni=vpn.ex
   - **Нативный Go-движок**: TUIC v5 работает на 100% нативно на Go внутри процесса 3x-ui. Никаких внешних сторонних бинарников скачивать не требуется.
   - **Маршрутизация и каскады в Xray**: Трафик проходит через движок маршрутизации Xray. Теги инбаундов (`in-<port>-udp`) полноценно участвуют в правилах маршрутизации (Routing Rules), блокировках geosite/geoip и перенаправлении в любые аутбаунды (VLESS, Shadowsocks, WARP и др.).
   - **Персональные квоты трафика**: Лимиты трафика (`totalGB`) и сроки действия (`expiryTime`) учитываются и применяются индивидуально для каждого клиента.
+  - **Скорость и общий трафик**: Нативные счётчики клиентов TUIC опрашиваются раз в 10 секунд и передаются в панель для отображения скорости. Xray отдельно считает общий трафик инбаунда через локальный relay; событие скорости TUIC повторно его не начисляет.
+  - **Ограничения UDP**: На одно QUIC-соединение допускается до 256 активных UDP-ассоциаций. Неактивные ассоциации закрываются через пять минут. Это лимит на соединение, а не общий лимит узла. TUIC использует выделенный локальный SOCKS-порт из диапазона `64001–65000`; 3x-ui проверяет его конфликты с управляемыми инбаундами и relay-портами.
   - **Горячее обновление без обрыва связи**: Добавление, редактирование или отключение клиентов обновляет реестр пользователей в памяти без перезапуска порта и без сброса активных сессий других пользователей.
   - **Развёртывание**: Инбаунд TUIC можно создать на дочернем узле или клонировать туда. TUIC-сервер запускает панель самого узла, поэтому на узле нужна панель v3.8.0 или новее; более старый узел главная панель отклоняет.
 </Callout>

docs/public/openapi.json

@@ -16027,15 +16027,9 @@
           },
           {
             "type": "traffic",
-            "summary": "Live traffic deltas plus online, per-node and last-online maps. Local polls send traffics/clientTraffics; node polls send nodeTraffics.",
+            "summary": "Live traffic deltas plus online, per-node and last-online maps. TUIC also sends source-tagged client deltas with their sampling interval for live speed.",
             "payloadSchema": {
               "type": "object",
-              "required": [
-                "onlineClients",
-                "onlineByGuid",
-                "activeInbounds",
-                "lastOnlineMap"
-              ],
               "properties": {
                 "traffics": {
                   "type": "array",
@@ -16049,6 +16043,18 @@
                     "$ref": "#/components/schemas/ClientTraffic"
                   }
                 },
+                "clientTrafficSource": {
+                  "type": "string",
+                  "enum": [
+                    "xray",
+                    "tuic"
+                  ],
+                  "description": "Present for native TUIC samples; omitted Xray samples default to xray."
+                },
+                "clientTrafficIntervalMs": {
+                  "type": "integer",
+                  "description": "Sampling interval used to calculate client speed, in milliseconds."
+                },
                 "nodeTraffics": {
                   "type": "array",
                   "nullable": true,
@@ -16092,13 +16098,24 @@
                 {
                   "required": [
                     "traffics",
-                    "clientTraffics"
+                    "clientTraffics",
+                    "onlineClients",
+                    "onlineByGuid",
+                    "activeInbounds",
+                    "lastOnlineMap"
                   ]
                 },
                 {
                   "required": [
                     "nodeTraffics"
                   ]
+                },
+                {
+                  "required": [
+                    "clientTraffics",
+                    "clientTrafficSource",
+                    "clientTrafficIntervalMs"
+                  ]
                 }
               ]
             },

frontend/public/openapi.json

@@ -16027,15 +16027,9 @@
           },
           {
             "type": "traffic",
-            "summary": "Live traffic deltas plus online, per-node and last-online maps. Local polls send traffics/clientTraffics; node polls send nodeTraffics.",
+            "summary": "Live traffic deltas plus online, per-node and last-online maps. TUIC also sends source-tagged client deltas with their sampling interval for live speed.",
             "payloadSchema": {
               "type": "object",
-              "required": [
-                "onlineClients",
-                "onlineByGuid",
-                "activeInbounds",
-                "lastOnlineMap"
-              ],
               "properties": {
                 "traffics": {
                   "type": "array",
@@ -16049,6 +16043,18 @@
                     "$ref": "#/components/schemas/ClientTraffic"
                   }
                 },
+                "clientTrafficSource": {
+                  "type": "string",
+                  "enum": [
+                    "xray",
+                    "tuic"
+                  ],
+                  "description": "Present for native TUIC samples; omitted Xray samples default to xray."
+                },
+                "clientTrafficIntervalMs": {
+                  "type": "integer",
+                  "description": "Sampling interval used to calculate client speed, in milliseconds."
+                },
                 "nodeTraffics": {
                   "type": "array",
                   "nullable": true,
@@ -16092,13 +16098,24 @@
                 {
                   "required": [
                     "traffics",
-                    "clientTraffics"
+                    "clientTraffics",
+                    "onlineClients",
+                    "onlineByGuid",
+                    "activeInbounds",
+                    "lastOnlineMap"
                   ]
                 },
                 {
                   "required": [
                     "nodeTraffics"
                   ]
+                },
+                {
+                  "required": [
+                    "clientTraffics",
+                    "clientTrafficSource",
+                    "clientTrafficIntervalMs"
+                  ]
                 }
               ]
             },

frontend/src/components/command-palette/CommandPalette.tsx

@@ -64,6 +64,7 @@ interface PaletteItem {
 
 export default function CommandPalette() {
   const { t } = useTranslation();
+  const [messageApi, messageContextHolder] = message.useMessage();
   const navigate = useNavigate();
   const { isDark, isUltra, toggleTheme, toggleUltra, antdThemeConfig } = useTheme();
   const { isOpen, close } = useCommandPalette();
@@ -194,14 +195,14 @@ export default function CommandPalette() {
   const copySubscription = useCallback(
     async (client: ClientRecord) => {
       if (!client.subId || !allSetting.subURI) {
-        message.warning(t('pages.clients.noSubId'));
+        messageApi.warning(t('pages.clients.noSubId'));
         return;
       }
       const link = `${allSetting.subURI}${client.subId}`;
       const ok = await ClipboardManager.copyText(link);
-      if (ok) message.success(t('copied'));
+      if (ok) messageApi.success(t('copied'));
     },
-    [allSetting.subURI, t],
+    [allSetting.subURI, messageApi, t],
   );
 
   const restartXray = useCallback(async () => {
@@ -210,9 +211,9 @@ export default function CommandPalette() {
       silentSuccess: true,
     });
     if (msg?.success) {
-      message.success(t('commandPalette.restartXraySuccess'));
+      messageApi.success(t('commandPalette.restartXraySuccess'));
     }
-  }, [close, t]);
+  }, [close, messageApi, t]);
 
   const cycleTheme = useCallback(() => {
     if (!isDark) {
@@ -679,13 +680,15 @@ export default function CommandPalette() {
     }
   };
 
-  if (!isOpen) return null;
+  // Kept mounted while closed: restartXray closes the palette before its toast.
+  if (!isOpen) return messageContextHolder;
 
   let lastCategory = '';
   const themeModeClass = isUltra ? 'ultra' : isDark ? 'dark' : 'light';
 
   return (
     <ConfigProvider theme={antdThemeConfig}>
+      {messageContextHolder}
       <div
         className={`command-palette-backdrop ${themeModeClass}`}
         role="presentation"

frontend/src/hooks/useClients.ts

@@ -98,6 +98,8 @@ export interface ClientSpeedEntry {
   down: number;
 }
 
+type ClientSpeedSource = 'xray' | 'tuic';
+
 type ClientStatRow = ClientTraffic & { email?: string };
 
 export function sameSpeedMap(
@@ -299,7 +301,31 @@ export function useClients(options: UseClientsOptions = {}) {
   // settings request still lets the page fall back and render.
   const settingsReady = defaultsQuery.isFetched;
 
-  const [clientSpeed, setClientSpeed] = useState<Record<string, ClientSpeedEntry>>({});
+  const [clientSpeedBySource, setClientSpeedBySource] = useState<
+    Partial<Record<ClientSpeedSource, Record<string, ClientSpeedEntry>>>
+  >({});
+  const clientSpeedExpiryTimers = useRef<Partial<Record<ClientSpeedSource, number>>>({});
+  const clientSpeedSourceVersions = useRef<Record<ClientSpeedSource, number>>({ xray: 0, tuic: 0 });
+  const clientSpeed = useMemo(() => {
+    const combined: Record<string, ClientSpeedEntry> = {};
+    for (const source of Object.values(clientSpeedBySource)) {
+      if (!source) continue;
+      for (const [email, speed] of Object.entries(source)) {
+        const current = combined[email] ?? { up: 0, down: 0 };
+        combined[email] = { up: current.up + speed.up, down: current.down + speed.down };
+      }
+    }
+    return combined;
+  }, [clientSpeedBySource]);
+
+  useEffect(
+    () => () => {
+      for (const timer of Object.values(clientSpeedExpiryTimers.current)) {
+        if (timer !== undefined) window.clearTimeout(timer);
+      }
+    },
+    [],
+  );
   const summary = listQuery.data?.summary ?? DEFAULT_SUMMARY;
 
   const invalidateAll = useCallback(() => {
@@ -725,6 +751,8 @@ export function useClients(options: UseClientsOptions = {}) {
       const p = payload as {
         onlineClients?: string[];
         clientTraffics?: { email: string; up: number; down: number }[];
+        clientTrafficSource?: 'xray' | 'tuic';
+        clientTrafficIntervalMs?: number;
       };
       if (Array.isArray(p.onlineClients)) {
         queryClient.setQueryData(keys.clients.onlines(), p.onlineClients);
@@ -736,17 +764,45 @@ export function useClients(options: UseClientsOptions = {}) {
         // dropped and an unchanged result returns the previous object — which lets
         // React bail out of the update instead of re-rendering the table.
         const next: Record<string, ClientSpeedEntry> = {};
+        const source = p.clientTrafficSource === 'tuic' ? 'tuic' : 'xray';
+        const sampleIntervalMs =
+          typeof p.clientTrafficIntervalMs === 'number' &&
+          Number.isFinite(p.clientTrafficIntervalMs) &&
+          p.clientTrafficIntervalMs > 0
+            ? p.clientTrafficIntervalMs
+            : TRAFFIC_POLL_INTERVAL_S * 1000;
+        const sampleIntervalSeconds = sampleIntervalMs / 1000;
         for (const ct of p.clientTraffics) {
           if (!ct || !ct.email) continue;
           const up = ct.up || 0;
           const down = ct.down || 0;
           if (up === 0 && down === 0) continue;
+          const current = next[ct.email] ?? { up: 0, down: 0 };
           next[ct.email] = {
-            up: up / TRAFFIC_POLL_INTERVAL_S,
-            down: down / TRAFFIC_POLL_INTERVAL_S,
+            up: current.up + up / sampleIntervalSeconds,
+            down: current.down + down / sampleIntervalSeconds,
           };
         }
-        setClientSpeed((prev) => (sameSpeedMap(prev, next) ? prev : next));
+        setClientSpeedBySource((prev) =>
+          sameSpeedMap(prev[source] ?? {}, next) ? prev : { ...prev, [source]: next },
+        );
+
+        const version = ++clientSpeedSourceVersions.current[source];
+        const previousTimer = clientSpeedExpiryTimers.current[source];
+        if (previousTimer !== undefined) window.clearTimeout(previousTimer);
+        clientSpeedExpiryTimers.current[source] = window.setTimeout(
+          () => {
+            if (clientSpeedSourceVersions.current[source] !== version) return;
+            delete clientSpeedExpiryTimers.current[source];
+            setClientSpeedBySource((prev) => {
+              if (!prev[source]) return prev;
+              const nextSources = { ...prev };
+              delete nextSources[source];
+              return nextSources;
+            });
+          },
+          Math.min(sampleIntervalMs * 2, 120_000),
+        );
       }
     },
     [queryClient],

frontend/src/lib/xray/inbound-link.ts

@@ -17,6 +17,7 @@ import { parseGeckoPacketSize } from '@/lib/xray/forms/transport/FinalMaskForm';
 import { getHeaderValue } from './headers';
 import { canEnableTlsFlow } from './protocol-capabilities';
 import { deriveSpiderX } from './spider-x';
+import { vlessEncryptionAuthKind } from './vless-encryption';
 import { normalizeTuicCongestionController, resolveTuicServerSettings } from '@/lib/tuic';
 
 // Share-link generators. Each per-protocol fn takes a typed inbound plus
@@ -1723,9 +1724,13 @@ function wgPeerCommentSuffix(peer: unknown): string {
   return typeof comment === 'string' && comment.trim() !== '' ? ` (${comment.trim()})` : '';
 }
 
+// Only the post-quantum key payloads outgrow a QR; the REALITY ML-KEM hint and the
+// mlkem768x25519plus prefix of an X25519-authenticated encryption do not (#6730).
 export function isPostQuantumLink(link: string): boolean {
-  if (/[?&]pqv=/.test(link)) return true;
-  if (link.includes('mlkem768') || link.includes('mldsa65')) return true;
-  if (link.includes('ML-KEM-768')) return true;
-  return false;
+  const withoutRemark = link.split('#', 1)[0];
+  const queryStart = withoutRemark.indexOf('?');
+  if (queryStart < 0) return false;
+  const params = new URLSearchParams(withoutRemark.slice(queryStart + 1));
+  if (params.get('pqv')) return true;
+  return vlessEncryptionAuthKind(params.get('encryption') ?? '')?.startsWith('mlkem768') ?? false;
 }

frontend/src/pages/api-docs/websocket-events.ts

@@ -120,10 +120,18 @@ const statusPayloadSchema = {
 
 const trafficPayloadSchema = {
   type: 'object',
-  required: ['onlineClients', 'onlineByGuid', 'activeInbounds', 'lastOnlineMap'],
   properties: {
     traffics: { type: 'array', items: { $ref: '#/components/schemas/Traffic' } },
     clientTraffics: { type: 'array', items: { $ref: '#/components/schemas/ClientTraffic' } },
+    clientTrafficSource: {
+      type: 'string',
+      enum: ['xray', 'tuic'],
+      description: 'Present for native TUIC samples; omitted Xray samples default to xray.',
+    },
+    clientTrafficIntervalMs: {
+      type: 'integer',
+      description: 'Sampling interval used to calculate client speed, in milliseconds.',
+    },
     nodeTraffics: {
       type: 'array',
       nullable: true,
@@ -134,7 +142,20 @@ const trafficPayloadSchema = {
     activeInbounds: stringArrayMap,
     lastOnlineMap: timestampMap,
   },
-  oneOf: [{ required: ['traffics', 'clientTraffics'] }, { required: ['nodeTraffics'] }],
+  oneOf: [
+    {
+      required: [
+        'traffics',
+        'clientTraffics',
+        'onlineClients',
+        'onlineByGuid',
+        'activeInbounds',
+        'lastOnlineMap',
+      ],
+    },
+    { required: ['nodeTraffics'] },
+    { required: ['clientTraffics', 'clientTrafficSource', 'clientTrafficIntervalMs'] },
+  ],
 };
 
 const clientStatsPayloadSchema = {
@@ -205,7 +226,7 @@ export function buildWebSocketEvents(
     {
       type: 'traffic',
       summary:
-        'Live traffic deltas plus online, per-node and last-online maps. Local polls send traffics/clientTraffics; node polls send nodeTraffics.',
+        'Live traffic deltas plus online, per-node and last-online maps. TUIC also sends source-tagged client deltas with their sampling interval for live speed.',
       payloadSchema: trafficPayloadSchema,
       example: {
         type: 'traffic',

frontend/src/pages/inbounds/clients/AttachClientsModal.tsx

@@ -60,7 +60,7 @@ export default function AttachClientsModal({
   // React resets this during render rather than in an effect so the modal's
   // first open frame already shows cleared fields.
   const openSource = open ? source : null;
-  const [syncedSource, setSyncedSource] = useState(openSource);
+  const [syncedSource, setSyncedSource] = useState<DBInbound | null>(null);
   if (openSource !== syncedSource) {
     setSyncedSource(openSource);
     if (openSource) {

frontend/src/pages/inbounds/clients/DetachClientsModal.tsx

@@ -54,7 +54,7 @@ export default function DetachClientsModal({
 
   // Reset during render, not in an effect, so the first frame is already clean.
   const openSource = open ? source : null;
-  const [syncedSource, setSyncedSource] = useState(openSource);
+  const [syncedSource, setSyncedSource] = useState<DBInbound | null>(null);
   if (openSource !== syncedSource) {
     setSyncedSource(openSource);
     if (openSource) {

frontend/src/pages/inbounds/form/protocols/tuic.tsx

@@ -21,6 +21,7 @@ import { HttpUtil } from '@/utils';
 
 export default function TuicFields() {
   const { t } = useTranslation();
+  const [messageApi, messageContextHolder] = message.useMessage();
   const { control, setValue } = useFormContext();
   const [loadingPanelCert, setLoadingPanelCert] = useState(false);
 
@@ -36,7 +37,7 @@ export default function TuicFields() {
   const autofillFromSni = () => {
     const cleanSni = (sni || '').trim();
     if (!cleanSni) {
-      message.warning(t('pages.xray.tuic.sniRequired'));
+      messageApi.warning(t('pages.xray.tuic.sniRequired'));
       return;
     }
     setValue('settings.server.certificate', `/root/cert/${cleanSni}/fullchain.pem`);
@@ -51,12 +52,12 @@ export default function TuicFields() {
           ? await HttpUtil.get(`/panel/api/nodes/webCert/${nodeId}`, undefined, { silent: true })
           : await HttpUtil.post('/panel/api/setting/all', undefined, { silent: true });
       if (!msg?.success) {
-        message.warning(msg?.msg || t('pages.inbounds.setDefaultCertEmpty'));
+        messageApi.warning(msg?.msg || t('pages.inbounds.setDefaultCertEmpty'));
         return;
       }
       const obj = msg.obj as { webCertFile?: string; webKeyFile?: string };
       if (!obj?.webCertFile && !obj?.webKeyFile) {
-        message.warning(t('pages.inbounds.setDefaultCertEmpty'));
+        messageApi.warning(t('pages.inbounds.setDefaultCertEmpty'));
         return;
       }
       if (obj.webCertFile) {
@@ -65,9 +66,9 @@ export default function TuicFields() {
       if (obj.webKeyFile) {
         setValue('settings.server.private_key', obj.webKeyFile);
       }
-      message.success(t('pages.inbounds.setSuccess'));
+      messageApi.success(t('pages.inbounds.setSuccess'));
     } catch {
-      message.error(t('somethingWentWrong'));
+      messageApi.error(t('somethingWentWrong'));
     } finally {
       setLoadingPanelCert(false);
     }
@@ -145,6 +146,7 @@ export default function TuicFields() {
 
   return (
     <>
+      {messageContextHolder}
       <Form.Item label={t('pages.inbounds.publicKey')}>
         <AutoComplete
           value={certificate}
@@ -164,7 +166,7 @@ export default function TuicFields() {
       </Form.Item>
 
       <Form.Item label=" ">
-        <Space>
+        <Space wrap style={{ display: 'flex', flexWrap: 'wrap', width: '100%' }}>
           <Button
             type="primary"
             icon={<CloudDownloadOutlined />}

frontend/src/pages/index/PanelUpdateModal.css

@@ -19,6 +19,8 @@
 
 .actions-row {
   display: flex;
+  flex-wrap: wrap;
   justify-content: flex-end;
+  gap: 8px;
   margin-top: 12px;
 }

frontend/src/pages/index/VersionModal.css

@@ -25,6 +25,8 @@
 
 .actions-row {
   display: flex;
+  flex-wrap: wrap;
   justify-content: flex-end;
+  gap: 8px;
   margin-top: 12px;
 }

frontend/src/pages/settings/HappSettingsContent.tsx

@@ -28,6 +28,7 @@ export default function HappSettingsContent({
   remoteSourceBadge,
 }: HappSettingsContentProps) {
   const { t } = useTranslation();
+  const [messageApi, messageContextHolder] = message.useMessage();
   // Generator choices stay local until Apply updates the draft; page Save persists it.
   const [selectedPreset, setSelectedPreset] = useState<string>('iran-bypass');
   const [includeAdblock, setIncludeAdblock] = useState(false);
@@ -37,18 +38,19 @@ export default function HappSettingsContent({
     const payload = buildHappPresetDeeplink(selectedPreset, includeAdblock);
     if (payload) {
       updateSetting({ subRoutingRules: payload });
-      message.success(t('pages.settings.subHappPresetApplied'));
+      messageApi.success(t('pages.settings.subHappPresetApplied'));
     }
   };
 
   const handleBuildDeeplink = (deeplink: string) => {
     updateSetting({ subRoutingRules: deeplink });
     setIsModalOpen(false);
-    message.success(t('pages.settings.subHappDeeplinkGenerated'));
+    messageApi.success(t('pages.settings.subHappDeeplinkGenerated'));
   };
 
   return (
     <>
+      {messageContextHolder}
       <SettingListItem
         paddings="small"
         title={t('pages.settings.subHappAutoDetect')}

frontend/src/pages/xray/routing/RoutingTab.tsx

@@ -45,6 +45,7 @@ export default function RoutingTab({
   isMobile,
 }: RoutingTabProps) {
   const { t } = useTranslation();
+  const [messageApi, messageContextHolder] = message.useMessage();
   const [modal, modalContextHolder] = Modal.useModal();
   const [ruleModalOpen, setRuleModalOpen] = useState(false);
   const [editingRule, setEditingRule] = useState<RoutingRule | null>(null);
@@ -179,7 +180,7 @@ export default function RoutingTab({
     try {
       parsed = JSON.parse(value);
     } catch {
-      message.error(t('pages.xray.importInvalidJson'));
+      messageApi.error(t('pages.xray.importInvalidJson'));
       return;
     }
     const obj = parsed as { rules?: unknown; routing?: { rules?: unknown } };
@@ -191,7 +192,7 @@ export default function RoutingTab({
           ? obj.routing!.rules
           : null;
     if (!list) {
-      message.error(t('pages.xray.importInvalidJson'));
+      messageApi.error(t('pages.xray.importInvalidJson'));
       return;
     }
     mutate((tt) => {
@@ -347,6 +348,7 @@ export default function RoutingTab({
   return (
     <>
       {modalContextHolder}
+      {messageContextHolder}
       <Tabs
         defaultActiveKey="basic"
         items={[

frontend/src/test/attach-clients-modal.test.tsx

@@ -0,0 +1,43 @@
+import { describe, expect, it } from 'vitest';
+import { screen } from '@testing-library/react';
+
+import AttachClientsModal from '@/pages/inbounds/clients/AttachClientsModal';
+import { DBInbound } from '@/models/dbinbound';
+
+import { renderWithProviders } from './test-utils';
+
+function sourceInbound() {
+  return new DBInbound({
+    id: 7,
+    port: 443,
+    listen: '',
+    protocol: 'vless',
+    remark: 'edge',
+    enable: true,
+    settings: JSON.stringify({
+      clients: [
+        { id: 'uuid-1', email: 'alice@test' },
+        { id: 'uuid-2', email: 'bob@test' },
+      ],
+      decryption: 'none',
+    }),
+    streamSettings: JSON.stringify({ network: 'tcp', security: 'none' }),
+    sniffing: '',
+  });
+}
+
+describe('AttachClientsModal', () => {
+  it('lists the source clients, selected, when first mounted already open', async () => {
+    renderWithProviders(
+      <AttachClientsModal open source={sourceInbound()} dbInbounds={[]} onClose={() => {}} />,
+    );
+
+    expect(await screen.findByText('alice@test')).toBeTruthy();
+    expect(screen.getByText('bob@test')).toBeTruthy();
+
+    const boxes = screen.getAllByRole('checkbox') as HTMLInputElement[];
+    const rowBoxes = boxes.slice(1);
+    expect(rowBoxes).toHaveLength(2);
+    expect(rowBoxes.every((b) => b.checked)).toBe(true);
+  });
+});

frontend/src/test/clients-summary.test.tsx

@@ -115,4 +115,71 @@ describe('client summary always reflects the server, never a client_stats recomp
 
     expect(result.current.summary).toEqual(serverSummary);
   });
+
+  it('combines independently sampled TUIC and Xray speeds and replaces each source snapshot', async () => {
+    const result = await loadedHook();
+
+    act(() => {
+      result.current.applyTrafficEvent({
+        clientTraffics: [{ email: 'shared@example.test', up: 100, down: 150 }],
+      });
+    });
+    expect(result.current.clientSpeed['shared@example.test']).toEqual({ up: 20, down: 30 });
+
+    act(() => {
+      result.current.applyTrafficEvent({
+        clientTrafficSource: 'tuic',
+        clientTrafficIntervalMs: 10_000,
+        clientTraffics: [
+          { email: 'shared@example.test', up: 300, down: 100 },
+          { email: 'shared@example.test', up: 100, down: 100 },
+        ],
+      });
+    });
+    expect(result.current.clientSpeed['shared@example.test']).toEqual({ up: 60, down: 50 });
+
+    act(() => {
+      result.current.applyTrafficEvent({
+        clientTraffics: [{ email: 'shared@example.test', up: 50, down: 25 }],
+      });
+    });
+    expect(result.current.clientSpeed['shared@example.test']).toEqual({ up: 50, down: 25 });
+
+    act(() => {
+      result.current.applyTrafficEvent({
+        clientTrafficSource: 'tuic',
+        clientTrafficIntervalMs: 10_000,
+        clientTraffics: [],
+      });
+    });
+    expect(result.current.clientSpeed['shared@example.test']).toEqual({ up: 10, down: 5 });
+  });
+
+  it('expires stale per-source speeds without clearing the other source', async () => {
+    const result = await loadedHook();
+    vi.useFakeTimers();
+    try {
+      act(() => {
+        result.current.applyTrafficEvent({
+          clientTrafficSource: 'xray',
+          clientTrafficIntervalMs: 1_000,
+          clientTraffics: [{ email: 'shared@example.test', up: 100, down: 200 }],
+        });
+        result.current.applyTrafficEvent({
+          clientTrafficSource: 'tuic',
+          clientTrafficIntervalMs: 2_000,
+          clientTraffics: [{ email: 'shared@example.test', up: 300, down: 400 }],
+        });
+      });
+      expect(result.current.clientSpeed['shared@example.test']).toEqual({ up: 250, down: 400 });
+
+      act(() => vi.advanceTimersByTime(2_000));
+      expect(result.current.clientSpeed['shared@example.test']).toEqual({ up: 150, down: 200 });
+
+      act(() => vi.advanceTimersByTime(2_000));
+      expect(result.current.clientSpeed).toEqual({});
+    } finally {
+      vi.useRealTimers();
+    }
+  });
 });

frontend/src/test/detach-clients-modal.test.tsx

@@ -0,0 +1,36 @@
+import { describe, expect, it } from 'vitest';
+import { screen } from '@testing-library/react';
+
+import DetachClientsModal from '@/pages/inbounds/clients/DetachClientsModal';
+import { DBInbound } from '@/models/dbinbound';
+
+import { renderWithProviders } from './test-utils';
+
+function sourceInbound() {
+  return new DBInbound({
+    id: 7,
+    port: 443,
+    listen: '',
+    protocol: 'vless',
+    remark: 'edge',
+    enable: true,
+    settings: JSON.stringify({
+      clients: [
+        { id: 'uuid-1', email: 'alice@test' },
+        { id: 'uuid-2', email: 'bob@test' },
+      ],
+      decryption: 'none',
+    }),
+    streamSettings: JSON.stringify({ network: 'tcp', security: 'none' }),
+    sniffing: '',
+  });
+}
+
+describe('DetachClientsModal', () => {
+  it('lists the attached clients when first mounted already open', async () => {
+    renderWithProviders(<DetachClientsModal open source={sourceInbound()} onClose={() => {}} />);
+
+    expect(await screen.findByText('alice@test')).toBeTruthy();
+    expect(screen.getByText('bob@test')).toBeTruthy();
+  });
+});

frontend/src/test/happ-routing-editor.test.tsx

@@ -1,6 +1,6 @@
 import { useState } from 'react';
 import { describe, expect, it, vi } from 'vitest';
-import { act, fireEvent, screen, within } from '@testing-library/react';
+import { act, cleanup, fireEvent, screen, within } from '@testing-library/react';
 import { EditorView } from 'codemirror';
 
 import { AllSetting } from '@/models/setting';
@@ -319,4 +319,19 @@ describe('Happ routing editor', () => {
     fireEvent.click(screen.getByRole('button', { name: 'Generate Deeplink' }));
     expect(generatedProfile()).toEqual(minimal);
   });
+
+  // The static message API outlived the test file and logged act() warnings
+  // after teardown, failing CI with "Closing rpc while onUserConsoleLog was pending".
+  it('takes its toast down with it when unmounted', async () => {
+    renderSettings();
+    openEditor();
+    fireEvent.click(screen.getByRole('button', { name: 'Generate Deeplink' }));
+    await screen.findByText('Deeplink generated and applied to routing rules');
+
+    cleanup();
+
+    expect(document.body.textContent).not.toContain(
+      'Deeplink generated and applied to routing rules',
+    );
+  });
 });

frontend/src/test/happ-settings-presets.test.tsx

@@ -1,15 +1,12 @@
 import { useState } from 'react';
 import { describe, expect, it, vi } from 'vitest';
 import { fireEvent, screen } from '@testing-library/react';
-import { message } from 'antd';
 
 import { AllSetting } from '@/models/setting';
 import HappSettingsContent from '@/pages/settings/HappSettingsContent';
 
 import { renderWithProviders } from './test-utils';
 
-vi.spyOn(message, 'success').mockImplementation(() => undefined as never);
-
 const chinaProfile = {
   Name: 'Bypass-CN',
   GlobalProxy: 'true',

frontend/src/test/inbound-link.test.ts

@@ -16,6 +16,7 @@ import {
   genVmessLink,
   genWireguardConfig,
   genWireguardLink,
+  isPostQuantumLink,
   preferPublicHost,
   resolveAddr,
 } from '@/lib/xray/inbound-link';
@@ -1415,3 +1416,46 @@ describe('genTuicLink', () => {
     expect(link).not.toContain('#TUIC-Node-US-US');
   });
 });
+
+describe('isPostQuantumLink', () => {
+  type RealityFixture = {
+    settings: { clients: Array<{ id: string }>; encryption?: string };
+    streamSettings: { realitySettings: { settings: { mldsa65Verify?: string } } };
+  };
+  const [, raw] = fixturesForProtocol('vless').find(([name]) => name === 'vless-tcp-reality')!;
+  const clientId = (raw as RealityFixture).settings.clients[0].id;
+  const x25519Key = 'G3cdPSd1-NnlpTbWNSM5vHsT5VNzWfFzYSKwbUMnV1Y';
+  const mlkem768Key = 'A'.repeat(1579);
+
+  function realityLink(edit: (inbound: RealityFixture) => void = () => {}): string {
+    const copy = structuredClone(raw) as RealityFixture;
+    edit(copy);
+    return genVlessLink({ inbound: InboundSchema.parse(copy), address: 'example.test', clientId });
+  }
+
+  // #6730: the REALITY ML-KEM support hint is a short flag, not a large PQ payload.
+  it('keeps the QR for a plain REALITY link', () => {
+    expect(isPostQuantumLink(realityLink())).toBe(false);
+  });
+
+  it('keeps the QR for VLESS encryption authenticated by an X25519 key', () => {
+    const link = realityLink((ib) => {
+      ib.settings.encryption = `mlkem768x25519plus.native.0rtt.${x25519Key}`;
+    });
+    expect(isPostQuantumLink(link)).toBe(false);
+  });
+
+  it('hides the QR for VLESS encryption authenticated by an ML-KEM-768 key', () => {
+    const link = realityLink((ib) => {
+      ib.settings.encryption = `mlkem768x25519plus.native.0rtt.${mlkem768Key}`;
+    });
+    expect(isPostQuantumLink(link)).toBe(true);
+  });
+
+  it('hides the QR for a REALITY link carrying an ML-DSA-65 verify key', () => {
+    const link = realityLink((ib) => {
+      ib.streamSettings.realitySettings.settings.mldsa65Verify = 'B'.repeat(2603);
+    });
+    expect(isPostQuantumLink(link)).toBe(true);
+  });
+});

frontend/src/test/no-static-message.test.ts

@@ -0,0 +1,31 @@
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join, relative, resolve } from 'node:path';
+
+import { describe, expect, it } from 'vitest';
+
+const srcRoot = resolve(fileURLToPath(import.meta.url), '../..');
+const staticCall = /(?<![\w.$])message\.(success|error|warning|info|loading|open)\(/;
+
+function sourceFiles(dir: string): string[] {
+  return readdirSync(dir).flatMap((name) => {
+    const path = join(dir, name);
+    if (statSync(path).isDirectory()) return name === 'test' ? [] : sourceFiles(path);
+    return /\.tsx?$/.test(name) ? [path] : [];
+  });
+}
+
+// antd's static message renders outside React: it ignores the theme and its
+// timers outlive the component, which broke CI after the Happ tests tore down.
+describe('antd message', () => {
+  it('is only used through message.useMessage()', () => {
+    const offenders = sourceFiles(srcRoot).flatMap((file) =>
+      readFileSync(file, 'utf8')
+        .split('\n')
+        .flatMap((line, i) =>
+          staticCall.test(line) ? [`${relative(srcRoot, file)}:${i + 1}: ${line.trim()}`] : [],
+        ),
+    );
+    expect(offenders).toEqual([]);
+  });
+});

install.sh

@@ -1384,6 +1384,169 @@ setup_fail2ban() {
     return 0
 }
 
+# Major version of the local systemd, 0 when it cannot be determined. The
+# SystemCallFilter=@system-service group only exists from systemd 239 on (other
+# @-named groups exist since 231); on older versions an unknown group is not
+# ignored safely, the filter stays in force and leaves a whitelist the panel
+# cannot run under.
+_xui_systemd_major_version() {
+    local version=""
+    if command -v systemctl > /dev/null 2>&1; then
+        version="$(systemctl --version 2>/dev/null | awk 'NR == 1 {print $2}')"
+    fi
+    if [[ ! "$version" =~ ^[0-9]+$ ]]; then
+        echo 0
+        return 0
+    fi
+    echo "$version"
+}
+
+# The shipped units list hardening that older systemd does not know: the
+# directive is logged and ignored at load time rather than rejected, so the
+# panel still starts, only without that protection. Each entry is the systemd
+# release that introduced the directive (systemd.exec(5)); everything else in
+# the unit predates the oldest systemd install.sh supports (CentOS 7 has 219).
+# SystemCallFilter= is listed because the drop-in only writes it from 239 on.
+_xui_warn_unsupported_hardening() {
+    local version entry missing=""
+    version="$(_xui_systemd_major_version)"
+    [[ "$version" -gt 0 ]] || return 0
+    for entry in RestrictRealtime:231 ReadWritePaths:231 ProtectKernelTunables:232 \
+        ProtectKernelModules:232 RestrictNamespaces:233 LockPersonality:235 \
+        SystemCallFilter:239 ProtectHostname:242 RestrictSUIDSGID:242 \
+        ProtectKernelLogs:244 ProtectClock:245; do
+        if [[ "$version" -lt "${entry##*:}" ]]; then
+            missing="${missing:+$missing, }${entry%%:*} (${entry##*:})"
+        fi
+    done
+    [[ -n "$missing" ]] || return 0
+    echo -e "${yellow}Note: systemd ${version} ignores part of the hardening in x-ui.service; the panel still starts.${plain}"
+    echo "      Not applied, needs a newer systemd: ${missing}."
+    if [[ "$version" -lt 231 ]]; then
+        echo "      The panel's folders stay writable through ReadWriteDirectories=, the alias this script installs."
+    fi
+    echo "      The rest of the hardening is in force. Upgrade systemd to apply the above."
+    return 0
+}
+
+# ProtectSystem=full makes /usr, /boot, /efi and /etc read-only. ProtectSystem=
+# strict would make the whole hierarchy read-only (only the kernel API
+# filesystems stay as they are), and that would break the panel's own use of
+# /tmp. The panel's stores are configurable (XUI_DB_FOLDER, XUI_LOG_FOLDER,
+# XUI_BIN_FOLDER), and XUI_MAIN_FOLDER is the folder install.sh/update.sh place
+# the files in -- the unit's WorkingDirectory on a stock install, and what a
+# relative XUI_BIN_FOLDER is resolved against. So a hard-coded list in the unit
+# either misses a relocated store -- the panel then cannot write its own SQLite
+# database and sits in a Restart=on-failure loop -- or forces the operator to
+# edit a file that every install/update overwrites from the release tarball.
+# install.sh and update.sh therefore regenerate the drop-in from the folders
+# actually in use, and the unit's own ReadWritePaths only carry the
+# plain-install defaults. A relocated store means re-running install or update:
+# the drop-in is only written here.
+_xui_service_write_paths_dropin() {
+    # $1 is the env file to resolve the XUI_* folders from; callers pass nothing
+    # and get the OS-specific path the unit itself uses.
+    local env_file="${1:-}"
+    local dropin_dir dropin temp_file
+    local db_folder log_folder bin_folder main_folder
+    local path line="" whitespace_paths="" seen_paths="" escaped_path
+
+    if [[ -z "$env_file" ]]; then
+        case "${release}" in
+            ubuntu | debian | armbian)
+                env_file="/etc/default/x-ui"
+                ;;
+            arch | manjaro | parch | alpine)
+                env_file="/etc/conf.d/x-ui"
+                ;;
+            *)
+                env_file="/etc/sysconfig/x-ui"
+                ;;
+        esac
+    fi
+    if [[ -r "$env_file" ]]; then
+        set -a
+        # shellcheck disable=SC1090
+        source "$env_file"
+        set +a
+    fi
+
+    # XUI_* wins over the script's own default: the unit hands that same env
+    # file to the panel through EnvironmentFile=, so these are the folders it
+    # will actually use.
+    main_folder="${XUI_MAIN_FOLDER:-${xui_folder}}"
+    db_folder="${XUI_DB_FOLDER:-/etc/x-ui}"
+    log_folder="${XUI_LOG_FOLDER:-/var/log/x-ui}"
+    # An empty XUI_BIN_FOLDER resolves to "bin" relative to the panel's working
+    # directory, which the unit sets to the main folder.
+    bin_folder="${XUI_BIN_FOLDER:-bin}"
+    if [[ "$bin_folder" != /* ]]; then
+        bin_folder="${main_folder%/}/${bin_folder#./}"
+    fi
+
+    for path in "$db_folder" "$log_folder" "$bin_folder" "$main_folder"; do
+        [[ "$path" == /* ]] || continue
+        # ReadWritePaths= is a whitespace-separated list, and a folder whose
+        # name contains whitespace cannot be written into it without relying on
+        # quoting. A wrong entry makes systemd reject the whole drop-in and the
+        # panel would not start, so leave such a folder out and say so instead.
+        if [[ "$path" != "${path//[[:space:]]/}" ]]; then
+            whitespace_paths="${whitespace_paths:+$whitespace_paths }$path"
+            continue
+        fi
+        case " $seen_paths " in
+            *" $path "*) continue ;;
+        esac
+        seen_paths="${seen_paths}${seen_paths:+ }$path"
+        # systemd expands %-specifiers in unit files, so a folder name carrying
+        # a literal % has to be written as %%, or the entry stops naming the
+        # folder systemd is meant to keep writable.
+        escaped_path="${path//%/%%}"
+        line="${line} -${escaped_path}"
+    done
+    if [[ -n "$whitespace_paths" ]]; then
+        echo "Warning: these folders contain whitespace and were left out of" >&2
+        echo "         10-xui-sandbox.conf: $whitespace_paths" >&2
+        echo "         The panel cannot write to them under the unit's sandbox." >&2
+    fi
+    line="${line# }"
+    [[ -n "$line" ]] || return 1
+
+    dropin_dir="${xui_service}/x-ui.service.d"
+    dropin="${dropin_dir}/10-xui-sandbox.conf"
+    temp_file="${dropin}.tmp.$$"
+
+    mkdir -p "$dropin_dir" || return 1
+    cat > "$temp_file" << EOF
+# Regenerated by install.sh/update.sh on every install and update: edits here
+# are lost, and the list only reflects the XUI_* variables read from
+# ${env_file} at that moment. Re-run install/update after moving a store.
+# It lists the folders the panel writes to. Put local additions in their own
+# drop-in, for example 20-x-ui-local.conf, which nothing here touches.
+[Service]
+ReadWritePaths=${line}
+ReadWriteDirectories=${line}
+EOF
+    if [[ "$(_xui_systemd_major_version)" -ge 239 ]]; then
+        cat >> "$temp_file" << 'EOF'
+# @system-service needs systemd >= 239; on older versions the unknown group
+# would leave the panel with a filter it cannot start under (x-ui.service.*).
+SystemCallFilter=@system-service
+SystemCallErrorNumber=EPERM
+EOF
+    fi
+    if [[ ! -s "$temp_file" ]]; then
+        rm -f "$temp_file"
+        return 1
+    fi
+    chmod 644 "$temp_file"
+    mv -f "$temp_file" "$dropin" || { rm -f "$temp_file"; return 1; }
+    if command -v systemctl > /dev/null 2>&1; then
+        systemctl daemon-reload > /dev/null 2>&1 || true
+    fi
+    return 0
+}
+
 # Lands a systemd unit file at ${xui_service}/x-ui.service via a temp file +
 # atomic mv, so a failed cp/curl or an interrupted mv never leaves a
 # truncated unit file at the live path -- systemd would then fail to parse
@@ -1415,6 +1578,11 @@ _install_xui_service_unit() {
         rm -f "$temp_file"
         return 1
     fi
+    if ! _xui_service_write_paths_dropin; then
+        echo -e "${yellow}Warning: could not refresh ${xui_service}/x-ui.service.d/10-xui-sandbox.conf.${plain}"
+        echo -e "${yellow}If XUI_DB_FOLDER or XUI_LOG_FOLDER points outside /etc/x-ui and /var/log/x-ui, the panel may not be able to write to it under ProtectSystem=full.${plain}"
+    fi
+    _xui_warn_unsupported_hardening
     return 0
 }
 

internal/nodee2e/harness_test.go

@@ -0,0 +1,365 @@
+// Package nodee2e drives a real master panel and a real node panel, each its own
+// process, through the node-sync paths. Gated by XUI_NODE_E2E_BINARY.
+package nodee2e
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database"
+)
+
+const settleTimeout = 30 * time.Second
+
+func panelBinary(t *testing.T) string {
+	t.Helper()
+	bin := os.Getenv("XUI_NODE_E2E_BINARY")
+	if bin == "" {
+		t.Skip("XUI_NODE_E2E_BINARY not set; run `make node-e2e`")
+	}
+	abs, err := filepath.Abs(bin)
+	if err != nil {
+		t.Fatalf("resolve %s: %v", bin, err)
+	}
+	return abs
+}
+
+type panel struct {
+	t      *testing.T
+	name   string
+	bin    string
+	dir    string
+	port   int
+	token  string
+	cmd    *exec.Cmd
+	logOut *os.File
+}
+
+func freePort(t *testing.T) int {
+	t.Helper()
+	l, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		t.Fatalf("free port: %v", err)
+	}
+	defer l.Close()
+	return l.Addr().(*net.TCPAddr).Port
+}
+
+func (p *panel) env() []string {
+	return append(os.Environ(),
+		"XUI_DB_FOLDER="+filepath.Join(p.dir, "db"),
+		"XUI_LOG_FOLDER="+filepath.Join(p.dir, "log"),
+		"XUI_BIN_FOLDER="+filepath.Join(p.dir, "bin"),
+		"XUI_ENABLE_FAIL2BAN=false",
+		"MSYS_NO_PATHCONV=1",
+	)
+}
+
+func (p *panel) cli(args ...string) string {
+	p.t.Helper()
+	cmd := exec.Command(p.bin, args...)
+	cmd.Env = p.env()
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		p.t.Fatalf("%s %v: %v\n%s", p.name, args, err, out)
+	}
+	return string(out)
+}
+
+var apiTokenLine = regexp.MustCompile(`(?m)^apiToken:\s*(\S+)`)
+
+func (p *panel) mintToken(name, scope string) string {
+	p.t.Helper()
+	out := p.cli("setting", "-getApiToken", "-tokenName", name, "-tokenScope", scope)
+	m := apiTokenLine.FindStringSubmatch(out)
+	if m == nil {
+		p.t.Fatalf("%s: no apiToken in output:\n%s", p.name, out)
+	}
+	return m[1]
+}
+
+// newPanel prepares a panel's database: credentials, a private port, its own
+// sub-server port (two panels on one host would race for 2096) and an admin token.
+func newPanel(t *testing.T, bin, name string) *panel {
+	t.Helper()
+	p := preparePanel(t, bin, name)
+	p.token = p.mintToken("e2e-driver", "admin")
+	return p
+}
+
+// sharedDBMu guards the process-global database handle the harness borrows
+// while the scopes run in parallel.
+var sharedDBMu sync.Mutex
+
+func preparePanel(t *testing.T, bin, name string) *panel {
+	t.Helper()
+	p := &panel{t: t, name: name, bin: bin, dir: t.TempDir(), port: freePort(t)}
+	for _, d := range []string{"db", "log", "bin"} {
+		if err := os.MkdirAll(filepath.Join(p.dir, d), 0o755); err != nil {
+			t.Fatal(err)
+		}
+	}
+	p.cli("setting", "-username", "e2e", "-password", "e2e-pass", "-port", strconv.Itoa(p.port), "-webBasePath", "/")
+	sharedDBMu.Lock()
+	defer sharedDBMu.Unlock()
+	if err := database.InitDB(filepath.Join(p.dir, "db", "x-ui.db")); err != nil {
+		t.Fatalf("%s: open db: %v", name, err)
+	}
+	db := database.GetDB()
+	db.Exec("DELETE FROM settings WHERE key = ?", "subPort")
+	if err := db.Exec("INSERT INTO settings(key, value) VALUES (?, ?)", "subPort", strconv.Itoa(freePort(t))).Error; err != nil {
+		t.Fatalf("%s: set subPort: %v", name, err)
+	}
+	if err := database.CloseDB(); err != nil {
+		t.Fatalf("%s: close db: %v", name, err)
+	}
+	t.Cleanup(p.stop)
+	return p
+}
+
+func (p *panel) start() {
+	p.t.Helper()
+	logOut, err := os.OpenFile(filepath.Join(p.dir, "stdout.log"), os.O_CREATE|os.O_WRONLY|os.O_APPEND, 0o644)
+	if err != nil {
+		p.t.Fatal(err)
+	}
+	p.logOut = logOut
+	p.cmd = exec.Command(p.bin, "run")
+	p.cmd.Env = p.env()
+	p.cmd.Stdout = logOut
+	p.cmd.Stderr = logOut
+	if err := p.cmd.Start(); err != nil {
+		p.t.Fatalf("%s: start: %v", p.name, err)
+	}
+	eventually(p.t, settleTimeout, p.name+" answers /server/status", func() (bool, string) {
+		env, err := p.try(http.MethodGet, "/panel/api/server/status", nil)
+		if err != nil {
+			return false, err.Error()
+		}
+		return env.Success, env.Msg
+	})
+}
+
+func (p *panel) stop() {
+	if p.cmd == nil || p.cmd.Process == nil {
+		return
+	}
+	_ = p.cmd.Process.Kill()
+	_, _ = p.cmd.Process.Wait()
+	p.cmd = nil
+	if p.logOut != nil {
+		_ = p.logOut.Close()
+		p.logOut = nil
+	}
+	if p.t.Failed() {
+		if b, err := os.ReadFile(filepath.Join(p.dir, "stdout.log")); err == nil {
+			tail := string(b)
+			if len(tail) > 6000 {
+				tail = tail[len(tail)-6000:]
+			}
+			p.t.Logf("---- %s stdout tail ----\n%s", p.name, tail)
+		}
+	}
+}
+
+// deleteInboundRow simulates a node that lost an inbound (restore, reinstall)
+// while stopped; it must not run against a live panel.
+func (p *panel) deleteInboundRow(id int) {
+	p.t.Helper()
+	if p.cmd != nil {
+		p.t.Fatalf("%s: deleteInboundRow on a running panel", p.name)
+	}
+	sharedDBMu.Lock()
+	defer sharedDBMu.Unlock()
+	if err := database.InitDB(filepath.Join(p.dir, "db", "x-ui.db")); err != nil {
+		p.t.Fatalf("%s: open db: %v", p.name, err)
+	}
+	defer func() { _ = database.CloseDB() }()
+	db := database.GetDB()
+	for _, q := range []string{"DELETE FROM client_inbounds WHERE inbound_id = ?", "DELETE FROM client_traffics WHERE inbound_id = ?", "DELETE FROM inbounds WHERE id = ?"} {
+		if err := db.Exec(q, id).Error; err != nil {
+			p.t.Fatalf("%s: %s: %v", p.name, q, err)
+		}
+	}
+}
+
+func (p *panel) url() string { return "http://127.0.0.1:" + strconv.Itoa(p.port) }
+
+type envelope struct {
+	Success bool            `json:"success"`
+	Msg     string          `json:"msg"`
+	Obj     json.RawMessage `json:"obj"`
+}
+
+func (p *panel) try(method, path string, body any) (*envelope, error) {
+	var rd io.Reader
+	if body != nil {
+		b, err := json.Marshal(body)
+		if err != nil {
+			return nil, err
+		}
+		rd = bytes.NewReader(b)
+	}
+	req, err := http.NewRequest(method, p.url()+path, rd)
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Authorization", "Bearer "+p.token)
+	if body != nil {
+		req.Header.Set("Content-Type", "application/json")
+	}
+	resp, err := (&http.Client{Timeout: 20 * time.Second}).Do(req)
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+	raw, err := io.ReadAll(resp.Body)
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode != http.StatusOK {
+		return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, raw)
+	}
+	var env envelope
+	if err := json.Unmarshal(raw, &env); err != nil {
+		return nil, fmt.Errorf("decode %s: %w (%s)", path, err, raw)
+	}
+	return &env, nil
+}
+
+// call fails the test on transport errors or success:false.
+func (p *panel) call(method, path string, body any) json.RawMessage {
+	p.t.Helper()
+	env, err := p.try(method, path, body)
+	if err != nil {
+		p.t.Fatalf("%s %s %s: %v", p.name, method, path, err)
+	}
+	if !env.Success {
+		p.t.Fatalf("%s %s %s: success=false msg=%q", p.name, method, path, env.Msg)
+	}
+	return env.Obj
+}
+
+func eventually(t *testing.T, timeout time.Duration, what string, check func() (bool, string)) {
+	t.Helper()
+	deadline := time.Now().Add(timeout)
+	last := ""
+	for {
+		ok, detail := check()
+		if ok {
+			return
+		}
+		last = detail
+		if time.Now().After(deadline) {
+			t.Fatalf("timed out after %s waiting for %s; last: %s", timeout, what, last)
+		}
+		time.Sleep(500 * time.Millisecond)
+	}
+}
+
+// inboundView is the subset of an inbound row the scenarios assert on.
+type inboundView struct {
+	Id       int             `json:"id"`
+	Remark   string          `json:"remark"`
+	Enable   bool            `json:"enable"`
+	Port     int             `json:"port"`
+	Tag      string          `json:"tag"`
+	NodeID   *int            `json:"nodeId"`
+	Settings json.RawMessage `json:"settings"`
+}
+
+type clientEntry map[string]any
+
+func (c clientEntry) email() string { s, _ := c["email"].(string); return s }
+
+func (ib inboundView) clients() []clientEntry {
+	raw := ib.Settings
+	var asString string
+	if json.Unmarshal(raw, &asString) == nil {
+		raw = json.RawMessage(asString)
+	}
+	var s struct {
+		Clients []clientEntry `json:"clients"`
+	}
+	_ = json.Unmarshal(raw, &s)
+	return s.Clients
+}
+
+func (ib inboundView) emails() []string {
+	out := []string{}
+	for _, c := range ib.clients() {
+		out = append(out, c.email())
+	}
+	return out
+}
+
+func (ib inboundView) client(email string) clientEntry {
+	for _, c := range ib.clients() {
+		if strings.EqualFold(c.email(), email) {
+			return c
+		}
+	}
+	return nil
+}
+
+func (p *panel) inbounds() []inboundView {
+	p.t.Helper()
+	var list []inboundView
+	if err := json.Unmarshal(p.call(http.MethodGet, "/panel/api/inbounds/list", nil), &list); err != nil {
+		p.t.Fatalf("%s: decode inbound list: %v", p.name, err)
+	}
+	return list
+}
+
+func (p *panel) inboundOnPort(port int) (inboundView, bool) {
+	p.t.Helper()
+	for _, ib := range p.inbounds() {
+		if ib.Port == port {
+			return ib, true
+		}
+	}
+	return inboundView{}, false
+}
+
+const tcpStream = `{"network":"tcp","security":"none","tcpSettings":{"header":{"type":"none"}}}`
+
+func vlessInbound(remark string, port int, nodeID *int, clients ...map[string]any) map[string]any {
+	if clients == nil {
+		clients = []map[string]any{}
+	}
+	settings, _ := json.Marshal(map[string]any{"clients": clients, "decryption": "none"})
+	body := map[string]any{
+		"remark": remark, "enable": true, "port": port, "protocol": "vless",
+		"settings": string(settings), "streamSettings": tcpStream, "sniffing": `{}`,
+	}
+	if nodeID != nil {
+		body["nodeId"] = *nodeID
+	}
+	return body
+}
+
+func vlessClient(email string) map[string]any {
+	return map[string]any{"email": email, "enable": true, "id": newUUID(email)}
+}
+
+// newUUID derives a stable, valid UUID from a label so failures are reproducible.
+func newUUID(label string) string {
+	var b [16]byte
+	copy(b[:], []byte(label+"________________"))
+	b[6] = (b[6] & 0x0f) | 0x40
+	b[8] = (b[8] & 0x3f) | 0x80
+	return fmt.Sprintf("%x-%x-%x-%x-%x", b[0:4], b[4:6], b[6:8], b[8:10], b[10:16])
+}

internal/nodee2e/node_sync_test.go

@@ -0,0 +1,344 @@
+package nodee2e
+
+import (
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"slices"
+	"strconv"
+	"testing"
+	"time"
+)
+
+// TestNodeSync walks one master/node pair per enrollment scope through every
+// operation that must converge onto the node. Each subtest names its invariant.
+func TestNodeSync(t *testing.T) {
+	bin := panelBinary(t)
+	for _, scope := range []string{"admin", "node-sync"} {
+		t.Run("enrolled with "+scope+" token", func(t *testing.T) {
+			t.Parallel()
+			runNodeSyncScenarios(t, bin, scope)
+		})
+	}
+}
+
+type pair struct {
+	t      *testing.T
+	master *panel
+	node   *panel
+	nodeID int
+}
+
+func (pr *pair) nodeInbound(port int) (inboundView, bool) { return pr.node.inboundOnPort(port) }
+
+func (pr *pair) masterInbound(port int) (inboundView, bool) {
+	for _, ib := range pr.master.inbounds() {
+		if ib.Port == port && ib.NodeID != nil && *ib.NodeID == pr.nodeID {
+			return ib, true
+		}
+	}
+	return inboundView{}, false
+}
+
+func (pr *pair) waitNode(what string, port int, ok func(inboundView) bool) {
+	pr.t.Helper()
+	eventually(pr.t, settleTimeout, what, func() (bool, string) {
+		ib, found := pr.nodeInbound(port)
+		if !found {
+			return ok(inboundView{}) && false, fmt.Sprintf("node has no inbound on %d", port)
+		}
+		return ok(ib), fmt.Sprintf("node inbound %d: enable=%v remark=%q emails=%v", port, ib.Enable, ib.Remark, ib.emails())
+	})
+}
+
+func (pr *pair) waitNodeAbsent(what string, port int) {
+	pr.t.Helper()
+	eventually(pr.t, settleTimeout, what, func() (bool, string) {
+		ib, found := pr.nodeInbound(port)
+		return !found, fmt.Sprintf("node still has inbound %d with %v", port, ib.emails())
+	})
+}
+
+func (pr *pair) bulkAttach(emails []string, masterInboundID int) {
+	pr.t.Helper()
+	var res struct {
+		Attached []string `json:"attached"`
+		Errors   []string `json:"errors"`
+	}
+	obj := pr.master.call(http.MethodPost, "/panel/api/clients/bulkAttach", map[string]any{"emails": emails, "inboundIds": []int{masterInboundID}})
+	if err := json.Unmarshal(obj, &res); err != nil {
+		pr.t.Fatalf("decode bulkAttach: %v", err)
+	}
+	if len(res.Errors) != 0 || len(res.Attached) != len(emails) {
+		pr.t.Fatalf("bulkAttach attached=%d/%d errors=%v", len(res.Attached), len(emails), res.Errors)
+	}
+}
+
+func emailRange(prefix string, from, to int) []string {
+	out := make([]string, 0, to-from+1)
+	for i := from; i <= to; i++ {
+		out = append(out, prefix+strconv.Itoa(i))
+	}
+	return out
+}
+
+func hasAll(have []string, want ...string) bool {
+	for _, w := range want {
+		if !slices.Contains(have, w) {
+			return false
+		}
+	}
+	return true
+}
+
+func runNodeSyncScenarios(t *testing.T, bin, scope string) {
+	master := newPanel(t, bin, "master")
+	node := newPanel(t, bin, "node")
+	linkToken := node.mintToken("master-link", scope)
+	master.start()
+	node.start()
+	pr := &pair{t: t, master: master, node: node}
+
+	var (
+		adoptedPort   = freePort(t)
+		madePort      = freePort(t)
+		lostPort      = freePort(t)
+		droppedPort   = freePort(t)
+		offlinePort   = freePort(t)
+		unmanagedPort = freePort(t)
+		localPort     = freePort(t)
+	)
+	node.call(http.MethodPost, "/panel/api/inbounds/add", vlessInbound("pre-existing", adoptedPort, nil))
+
+	local := master.call(http.MethodPost, "/panel/api/inbounds/add", vlessInbound("local-pool", localPort, nil))
+	var localIb inboundView
+	_ = json.Unmarshal(local, &localIb)
+	for _, email := range emailRange("p", 1, 45) {
+		master.call(http.MethodPost, "/panel/api/clients/add", map[string]any{
+			"client": map[string]any{"email": email, "enable": true}, "inboundIds": []int{localIb.Id},
+		})
+	}
+
+	var nodeView struct {
+		Id int `json:"id"`
+	}
+	obj := master.call(http.MethodPost, "/panel/api/nodes/add", map[string]any{
+		"name": "n1", "scheme": "http", "address": "127.0.0.1", "port": node.port, "basePath": "/",
+		"apiToken": linkToken, "enable": true, "allowPrivateAddress": true,
+	})
+	if err := json.Unmarshal(obj, &nodeView); err != nil || nodeView.Id == 0 {
+		t.Fatalf("decode node add: %v (%s)", err, obj)
+	}
+	pr.nodeID = nodeView.Id
+
+	var adoptedID, madeID int
+	t.Run("an inbound already on the node is adopted by the master", func(t *testing.T) {
+		pr.t = t
+		eventually(t, settleTimeout, "master adopts the node inbound", func() (bool, string) {
+			ib, ok := pr.masterInbound(adoptedPort)
+			adoptedID = ib.Id
+			return ok, "not adopted yet"
+		})
+	})
+	if adoptedID == 0 {
+		t.Fatal("no adopted inbound; later scenarios depend on it")
+	}
+
+	t.Run("an inbound created on the master for the node lands there with its clients", func(t *testing.T) {
+		pr.t = t
+		obj := master.call(http.MethodPost, "/panel/api/inbounds/add",
+			vlessInbound("made-on-master", madePort, &pr.nodeID, vlessClient("m1"), vlessClient("m2")))
+		var ib inboundView
+		_ = json.Unmarshal(obj, &ib)
+		madeID = ib.Id
+		pr.waitNode("node holds the master-made inbound", madePort, func(ib inboundView) bool {
+			return hasAll(ib.emails(), "m1", "m2")
+		})
+	})
+
+	t.Run("editing the inbound on the master updates the node and keeps its clients", func(t *testing.T) {
+		pr.t = t
+		body := vlessInbound("renamed-on-master", madePort, &pr.nodeID)
+		body["settings"] = `{"decryption":"none"}`
+		master.call(http.MethodPost, "/panel/api/inbounds/update/"+strconv.Itoa(madeID), body)
+		pr.waitNode("node shows the new remark with both clients", madePort, func(ib inboundView) bool {
+			return ib.Remark == "renamed-on-master" && hasAll(ib.emails(), "m1", "m2")
+		})
+	})
+
+	t.Run("attaching a few existing clients reaches the node", func(t *testing.T) {
+		pr.t = t
+		pr.bulkAttach([]string{"p1", "p2", "p3"}, madeID)
+		pr.waitNode("node holds p1..p3", madePort, func(ib inboundView) bool {
+			return hasAll(ib.emails(), "m1", "m2", "p1", "p2", "p3")
+		})
+	})
+
+	t.Run("attaching more clients than the per-client push limit reaches the node", func(t *testing.T) {
+		pr.t = t
+		emails := emailRange("p", 4, 43)
+		pr.bulkAttach(emails, adoptedID)
+		pr.waitNode("node holds all 40", adoptedPort, func(ib inboundView) bool {
+			return hasAll(ib.emails(), emails...)
+		})
+	})
+
+	t.Run("disabling a client on the master disables it on the node", func(t *testing.T) {
+		pr.t = t
+		mib, _ := pr.masterInbound(madePort)
+		entry := mib.client("p1")
+		if entry == nil {
+			t.Fatalf("master inbound has no p1: %v", mib.emails())
+		}
+		entry["enable"] = false
+		master.call(http.MethodPost, "/panel/api/clients/update/p1", entry)
+		pr.waitNode("node p1 disabled", madePort, func(ib inboundView) bool {
+			c := ib.client("p1")
+			return c != nil && c["enable"] == false
+		})
+	})
+
+	t.Run("detaching a client from the node inbound removes it there", func(t *testing.T) {
+		pr.t = t
+		master.call(http.MethodPost, "/panel/api/clients/p2/detach", map[string]any{"inboundIds": []int{madeID}})
+		pr.waitNode("node drops p2", madePort, func(ib inboundView) bool {
+			return ib.client("p2") == nil && ib.client("p3") != nil
+		})
+	})
+
+	t.Run("deleting a client on the master removes it from the node", func(t *testing.T) {
+		pr.t = t
+		master.call(http.MethodPost, "/panel/api/clients/del/p4", nil)
+		pr.waitNode("node drops p4", adoptedPort, func(ib inboundView) bool {
+			return ib.client("p4") == nil && ib.client("p5") != nil
+		})
+	})
+
+	t.Run("switching the inbound off on the master switches it off on the node", func(t *testing.T) {
+		pr.t = t
+		master.call(http.MethodPost, "/panel/api/inbounds/setEnable/"+strconv.Itoa(madeID), map[string]any{"enable": false})
+		pr.waitNode("node inbound disabled", madePort, func(ib inboundView) bool { return !ib.Enable })
+	})
+
+	t.Run("node traffic reaches the master and a master reset clears the node", func(t *testing.T) {
+		pr.t = t
+		node.call(http.MethodPost, "/panel/api/clients/updateTraffic/p5", map[string]any{"upload": 1000, "download": 2000})
+		usage := func(p *panel) int64 {
+			var tr struct{ Up, Down int64 }
+			_ = json.Unmarshal(p.call(http.MethodGet, "/panel/api/clients/traffic/p5", nil), &tr)
+			return tr.Up + tr.Down
+		}
+		eventually(t, settleTimeout, "master sees p5's node traffic", func() (bool, string) {
+			u := usage(master)
+			return u == 3000, fmt.Sprintf("master p5 usage %d", u)
+		})
+		master.call(http.MethodPost, "/panel/api/clients/resetTraffic/p5", nil)
+		eventually(t, settleTimeout, "node p5 usage reset", func() (bool, string) {
+			u := usage(node)
+			return u == 0, fmt.Sprintf("node p5 usage %d", u)
+		})
+		time.Sleep(12 * time.Second)
+		if u := usage(master); u != 0 {
+			t.Fatalf("master p5 usage %d after reset settled, want 0", u)
+		}
+	})
+
+	t.Run("an inbound deleted on the node is removed from the master too", func(t *testing.T) {
+		pr.t = t
+		master.call(http.MethodPost, "/panel/api/inbounds/add", vlessInbound("deleted-on-node", lostPort, &pr.nodeID, vlessClient("l1")))
+		pr.waitNode("node holds the inbound", lostPort, func(ib inboundView) bool { return ib.client("l1") != nil })
+		nib, _ := pr.nodeInbound(lostPort)
+		node.call(http.MethodPost, "/panel/api/inbounds/del/"+strconv.Itoa(nib.Id), nil)
+		eventually(t, settleTimeout, "master mirrors the node-side delete (#6219)", func() (bool, string) {
+			_, still := pr.masterInbound(lostPort)
+			return !still, "master still has the inbound"
+		})
+	})
+
+	t.Run("deleting the inbound on the master removes it from the node", func(t *testing.T) {
+		pr.t = t
+		obj := master.call(http.MethodPost, "/panel/api/inbounds/add", vlessInbound("deleted-on-master", droppedPort, &pr.nodeID, vlessClient("d1")))
+		var ib inboundView
+		_ = json.Unmarshal(obj, &ib)
+		pr.waitNode("node holds the inbound", droppedPort, func(ib inboundView) bool { return ib.client("d1") != nil })
+		master.call(http.MethodPost, "/panel/api/inbounds/del/"+strconv.Itoa(ib.Id), nil)
+		pr.waitNodeAbsent("node drops the inbound", droppedPort)
+	})
+
+	t.Run("a change made while the node is down reaches it once it is back", func(t *testing.T) {
+		pr.t = t
+		node.stop()
+		pr.bulkAttach([]string{"p44"}, adoptedID)
+		node.start()
+		pr.waitNode("node holds p44 after restart", adoptedPort, func(ib inboundView) bool {
+			return ib.client("p44") != nil
+		})
+	})
+
+	t.Run("an inbound the node lost while down is re-created with the master's pending change", func(t *testing.T) {
+		pr.t = t
+		nib, ok := pr.nodeInbound(adoptedPort)
+		if !ok {
+			t.Fatal("node has no adopted inbound to lose")
+		}
+		node.stop()
+		node.deleteInboundRow(nib.Id)
+		pr.bulkAttach([]string{"p45"}, adoptedID)
+		node.start()
+		pr.waitNode("node re-creates the inbound with p44 and p45", adoptedPort, func(ib inboundView) bool {
+			return ib.client("p44") != nil && ib.client("p45") != nil
+		})
+	})
+
+	t.Run("an inbound created and edited while the node is down lands once it is back", func(t *testing.T) {
+		pr.t = t
+		node.stop()
+		obj := master.call(http.MethodPost, "/panel/api/inbounds/add", vlessInbound("made-while-down", offlinePort, &pr.nodeID, vlessClient("o1")))
+		var ib inboundView
+		_ = json.Unmarshal(obj, &ib)
+		body := vlessInbound("edited-while-down", offlinePort, &pr.nodeID)
+		body["settings"] = `{"decryption":"none"}`
+		master.call(http.MethodPost, "/panel/api/inbounds/update/"+strconv.Itoa(ib.Id), body)
+		node.start()
+		pr.waitNode("node holds the edited inbound with o1", offlinePort, func(ib inboundView) bool {
+			return ib.Remark == "edited-while-down" && ib.client("o1") != nil
+		})
+	})
+
+	t.Run("a change made while the node is disabled on the master lands once it is re-enabled", func(t *testing.T) {
+		pr.t = t
+		nodePath := "/panel/api/nodes/setEnable/" + strconv.Itoa(pr.nodeID)
+		master.call(http.MethodPost, nodePath, map[string]any{"enable": false})
+		pr.bulkAttach([]string{"p6"}, madeID)
+		time.Sleep(6 * time.Second)
+		if ib, _ := pr.nodeInbound(madePort); ib.client("p6") != nil {
+			t.Fatal("a disabled node received a push")
+		}
+		master.call(http.MethodPost, nodePath, map[string]any{"enable": true})
+		pr.waitNode("node holds p6 after re-enable", madePort, func(ib inboundView) bool { return ib.client("p6") != nil })
+	})
+
+	t.Run("selected sync mode leaves the node's unselected inbounds alone", func(t *testing.T) {
+		pr.t = t
+		var selected []string
+		for _, ib := range master.inbounds() {
+			if ib.NodeID != nil && *ib.NodeID == pr.nodeID {
+				selected = append(selected, ib.Tag)
+			}
+		}
+		master.call(http.MethodPost, "/panel/api/nodes/update/"+strconv.Itoa(pr.nodeID), map[string]any{
+			"name": "n1", "scheme": "http", "address": "127.0.0.1", "port": node.port, "basePath": "/",
+			"enable": true, "allowPrivateAddress": true, "inboundSyncMode": "selected", "inboundTags": selected,
+		})
+		node.call(http.MethodPost, "/panel/api/inbounds/add", vlessInbound("node-only", unmanagedPort, nil, vlessClient("u1")))
+		pr.bulkAttach([]string{"p7"}, madeID)
+		pr.waitNode("selected inbound still converges", madePort, func(ib inboundView) bool { return ib.client("p7") != nil })
+		time.Sleep(12 * time.Second)
+		if _, adopted := pr.masterInbound(unmanagedPort); adopted {
+			t.Fatal("master adopted an unselected node inbound")
+		}
+		if ib, ok := pr.nodeInbound(unmanagedPort); !ok || ib.client("u1") == nil {
+			t.Fatal("reconcile swept or rewrote an unselected node inbound")
+		}
+	})
+}

internal/sub/host_sub_test.go

@@ -618,3 +618,49 @@ func TestSub_HostCipherSuitesJSON(t *testing.T) {
 		t.Fatalf("a host with no cipher suites should inherit the inbound's:\n%s", out)
 	}
 }
+
+// Xray reads a client's TLS verification fields at the top of tlsSettings; a
+// nested "settings" map is panel-only shape and xray silently ignores it.
+func TestSub_HostTLSVerificationJSONAtXrayLevel(t *testing.T) {
+	seedSubDB(t)
+	ib := seedSubInbound(t, "s1", "ech", 4461, 1,
+		`{"network":"xhttp","security":"tls","xhttpSettings":{"path":"/"},"tlsSettings":{"serverName":"base.sni","settings":{"fingerprint":"chrome"}}}`)
+	seedHost(t, &model.Host{
+		InboundId: ib.Id, SortOrder: 0, Remark: "ECH", Address: "ech.cdn.com", Port: 443, Security: "tls",
+		EchConfigList: "cloudflare-ech.com+udp://1.1.1.1", VerifyPeerCertByName: "cert.example.com",
+		PinnedPeerCertSha256: []string{"aa11", "bb22"}, AllowInsecure: true,
+	})
+
+	out, _, err := NewSubJsonService("", "", "", "", NewSubService("")).GetJson("s1", "req.example.com", false)
+	if err != nil {
+		t.Fatalf("GetJson: %v", err)
+	}
+	var config map[string]any
+	if err := json.Unmarshal([]byte(out), &config); err != nil {
+		t.Fatalf("unmarshal JSON subscription: %v", err)
+	}
+	outbounds, _ := config["outbounds"].([]any)
+	if len(outbounds) == 0 {
+		t.Fatalf("JSON subscription has no outbounds: %s", out)
+	}
+	outbound, _ := outbounds[0].(map[string]any)
+	stream, _ := outbound["streamSettings"].(map[string]any)
+	tls, _ := stream["tlsSettings"].(map[string]any)
+	want := map[string]any{
+		"serverName":           "base.sni",
+		"fingerprint":          "chrome",
+		"echConfigList":        "cloudflare-ech.com+udp://1.1.1.1",
+		"verifyPeerCertByName": "cert.example.com",
+		"pinnedPeerCertSha256": "aa11,bb22",
+	}
+	for key, value := range want {
+		if tls[key] != value {
+			t.Errorf("tlsSettings.%s = %#v, want %#v", key, tls[key], value)
+		}
+	}
+	for _, key := range []string{"settings", "allowInsecure"} {
+		if _, ok := tls[key]; ok {
+			t.Errorf("tlsSettings.%s must not reach xray: %#v", key, tls)
+		}
+	}
+}

internal/sub/hysteria_server_description_test.go

@@ -0,0 +1,57 @@
+package sub
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+)
+
+// #6738: without the host's Description on hysteria(2):// links, Happ falls back
+// to its own "Hysteria | hysteria | TLS" caption on a host that also serves VLESS.
+func TestGenHysteriaLinkAppendsHostServerDescription(t *testing.T) {
+	tests := map[string]struct {
+		version int
+		scheme  string
+	}{
+		"hysteria v1": {version: 1, scheme: "hysteria://"},
+		"hysteria v2": {version: 2, scheme: "hysteria2://"},
+	}
+	for name, tc := range tests {
+		t.Run(name, func(t *testing.T) {
+			host := &model.Host{
+				Address: "hy.example.com", Port: 443,
+				Remark: "Poland", ServerDescription: "Wi-Fi",
+			}
+			stream := map[string]any{
+				"security":      "tls",
+				"externalProxy": []any{hostToExternalProxyMap(host, "hy.example.com", 443)},
+			}
+			rawStream, err := json.Marshal(stream)
+			if err != nil {
+				t.Fatalf("marshal stream settings: %v", err)
+			}
+			// The inbound's own `version` picks the hysteria vs hysteria2 scheme.
+			rawSettings, err := json.Marshal(map[string]any{
+				"version": tc.version,
+				"clients": []any{map[string]any{"auth": "secret", "email": "user"}},
+			})
+			if err != nil {
+				t.Fatalf("marshal inbound settings: %v", err)
+			}
+			in := &model.Inbound{
+				Id: 920010, Listen: "203.0.113.1", Port: 443, Protocol: model.Hysteria,
+				Remark: "hy", StreamSettings: string(rawStream), Settings: string(rawSettings),
+			}
+			got := (&SubService{}).genHysteriaLink(in, "user")
+			if !strings.HasPrefix(got, tc.scheme) {
+				t.Fatalf("link scheme changed.\n got: %s\nwant prefix: %s", got, tc.scheme)
+			}
+			// base64("Wi-Fi"), matching the reporter's subscription output.
+			if !strings.HasSuffix(got, "?serverDescription=V2ktRmk=") {
+				t.Fatalf("host serverDescription missing from fragment.\n got: %s\nwant suffix: ?serverDescription=V2ktRmk=", got)
+			}
+		})
+	}
+}

internal/sub/json_service.go

@@ -634,6 +634,7 @@ func (s *SubJsonService) getConfig(subReq *SubService, inbound *model.Inbound, c
 		security, _ := newStream["security"].(string)
 		if hasExternalProxy {
 			applyExternalProxyTLSToStream(extPrxy, newStream, security)
+			liftHostTLSVerification(newStream)
 		}
 		applyHostStreamOverrides(extPrxy, newStream)
 		if finalmask, ok := newStream["finalmask"].(map[string]any); ok {
@@ -774,6 +775,23 @@ func (s *SubJsonService) tlsData(tData map[string]any) map[string]any {
 	if cs, ok := tData["cipherSuites"].(string); ok && cs != "" {
 		tlsData["cipherSuites"] = cs
 	}
+	putClientTLSVerification(tlsData, tlsClientSettings)
+	return tlsData
+}
+
+// liftHostTLSVerification moves the host overrides applyExternalProxyTLSToStream
+// wrote into the panel-shaped tlsSettings.settings up to where xray reads them.
+func liftHostTLSVerification(stream map[string]any) {
+	tlsSettings, _ := stream["tlsSettings"].(map[string]any)
+	inner, ok := tlsSettings["settings"].(map[string]any)
+	if !ok {
+		return
+	}
+	delete(tlsSettings, "settings")
+	putClientTLSVerification(tlsSettings, inner)
+}
+
+func putClientTLSVerification(tlsData map[string]any, tlsClientSettings map[string]any) {
 	if ech, ok := tlsClientSettings["echConfigList"].(string); ok && ech != "" {
 		tlsData["echConfigList"] = ech
 	}
@@ -785,7 +803,6 @@ func (s *SubJsonService) tlsData(tData map[string]any) map[string]any {
 	if pins, ok := pinnedSha256List(tlsClientSettings); ok {
 		tlsData["pinnedPeerCertSha256"] = strings.Join(pins, ",")
 	}
-	return tlsData
 }
 
 func (s *SubJsonService) realityData(rData map[string]any, clientKey string) map[string]any {

internal/sub/service.go

@@ -1535,7 +1535,11 @@ func (s *SubService) genHysteriaLink(inbound *model.Inbound, email string) strin
 			applyExternalProxyHysteriaParams(ep, epParams)
 
 			link := fmt.Sprintf("%s://%s@%s", protocol, auth, joinHostPort(dest, int(portF)))
-			links = append(links, buildLinkWithParams(link, epParams, s.endpointRemark(inbound, email, ep, "quic")))
+			// VLESS/Trojan/SS get the host's description through buildEndpointLinks;
+			// this loop renders the fragment itself, so add it here too (#6738).
+			remark := s.endpointRemark(inbound, email, ep, "quic")
+			remark = appendHappServerDescription(remark, externalProxyToEndpoint(ep).ServerDescription)
+			links = append(links, buildLinkWithParams(link, epParams, remark))
 		}
 		return strings.Join(links, "\n")
 	}

internal/sub/service_test.go

@@ -744,16 +744,6 @@ func TestApplyExternalProxy_ECHPropagates(t *testing.T) {
 		}
 	})
 
-	t.Run("json stream settings", func(t *testing.T) {
-		stream := map[string]any{"security": "tls", "tlsSettings": map[string]any{}}
-		ep := map[string]any{"dest": "proxy.example.com", "echConfigList": ech}
-		applyExternalProxyTLSToStream(ep, stream, "tls")
-		settings, _ := stream["tlsSettings"].(map[string]any)["settings"].(map[string]any)
-		if settings["echConfigList"] != ech {
-			t.Fatalf("echConfigList = %v, want %q", settings["echConfigList"], ech)
-		}
-	})
-
 	t.Run("non-tls security drops ech", func(t *testing.T) {
 		params := map[string]string{}
 		ep := map[string]any{"echConfigList": ech}

internal/tuic/manager_live_traffic_test.go

@@ -96,9 +96,7 @@ func TestAudit3ManagerEnsureActualSendersWithPersistentTraffic(t *testing.T) {
 			if _, err := stream.Write(frame.Bytes()); err != nil {
 				t.Fatal(err)
 			}
-			if err := stream.Close(); err != nil {
-				t.Fatal(err)
-			}
+			closeUniStream(t, stream)
 			response, err := p.client.AcceptUniStream(ctx)
 			if err != nil {
 				t.Fatal(err)
@@ -164,9 +162,7 @@ func TestAudit3ManagerEnsureActualSendersWithPersistentTraffic(t *testing.T) {
 		if _, err := auth.Write(authBytes); err != nil {
 			t.Fatal(err)
 		}
-		if err := auth.Close(); err != nil {
-			t.Fatal(err)
-		}
+		closeUniStream(t, auth)
 
 		waitForClientCongestionSender(t, server, client, served)
 		var serverConn *quic.Conn

internal/tuic/relay_logging_test.go

@@ -57,9 +57,7 @@ func audit3LogsStart(t *testing.T, level, marker, relayAddr string) (*Server, *c
 	if _, err := auth.Write(frame); err != nil {
 		t.Fatal(err)
 	}
-	if err := auth.Close(); err != nil {
-		t.Fatal(err)
-	}
+	closeUniStream(t, auth)
 	_, _ = authenticatedServerConnection(t, s, id)
 	return s, c, id, password, token
 }

internal/tuic/server_test.go

@@ -10,12 +10,14 @@ import (
 	"crypto/x509"
 	"crypto/x509/pkix"
 	"encoding/pem"
+	"errors"
 	"io"
 	"math/big"
 	"net"
 	"testing"
 	"time"
 
+	serverquic "github.com/apernet/quic-go"
 	"github.com/google/uuid"
 	"github.com/quic-go/quic-go"
 )
@@ -196,12 +198,51 @@ func testServerTCPConnectE2E(t *testing.T, controller string) {
 		t.Fatalf("expected active email alice@example.com, got %v", activeEmails)
 	}
 
-	deltas := server.CollectClientTraffic()
-	if len(deltas) == 0 {
-		t.Fatalf("expected traffic deltas, got none")
+	waitForClientTraffic(t, server, "alice@example.com", int64(len(testMsg)))
+}
+
+// closeUniStream tolerates only the server's STOP_SENDING: it cancels the read side of a
+// uni stream once the command is parsed, which can land before the client's FIN.
+func closeUniStream(t *testing.T, stream interface {
+	Close() error
+	Context() context.Context
+},
+) {
+	t.Helper()
+	err := stream.Close()
+	if err == nil {
+		return
 	}
-	if deltas[0].Email != "alice@example.com" || deltas[0].Up < int64(len(testMsg)) || deltas[0].Down < int64(len(testMsg)) {
-		t.Fatalf("unexpected traffic deltas: %+v", deltas[0])
+	cause := context.Cause(stream.Context())
+	var clientErr *quic.StreamError
+	var serverErr *serverquic.StreamError
+	if (errors.As(cause, &clientErr) && clientErr.Remote) || (errors.As(cause, &serverErr) && serverErr.Remote) {
+		return
+	}
+	t.Fatalf("close uni stream: %v (cause %v)", err, cause)
+}
+
+// waitForClientTraffic accumulates drained deltas because the up and down counters are
+// bumped on different relay goroutines, so the echo can arrive before the upload is counted.
+func waitForClientTraffic(t *testing.T, server *Server, email string, minBytes int64) {
+	t.Helper()
+	var up, down int64
+	deadline := time.Now().Add(4 * time.Second)
+	for {
+		for _, delta := range server.CollectClientTraffic() {
+			if delta.Email != email {
+				t.Fatalf("unexpected traffic delta for %q: %+v", delta.Email, delta)
+			}
+			up += delta.Up
+			down += delta.Down
+		}
+		if up >= minBytes && down >= minBytes {
+			return
+		}
+		if time.Now().After(deadline) {
+			t.Fatalf("traffic for %s = up %d, down %d; want both >= %d", email, up, down, minBytes)
+		}
+		time.Sleep(5 * time.Millisecond)
 	}
 }
 
@@ -356,13 +397,7 @@ func testServerUDPDatagramE2E(t *testing.T, controller string) {
 	}
 
 	// 4. Verify traffic
-	deltas := server.CollectClientTraffic()
-	if len(deltas) == 0 {
-		t.Fatalf("expected traffic deltas, got none")
-	}
-	if deltas[0].Email != "bob@example.com" || deltas[0].Up < int64(len(udpMsg)) || deltas[0].Down < int64(len(udpMsg)) {
-		t.Fatalf("unexpected traffic deltas: %+v", deltas[0])
-	}
+	waitForClientTraffic(t, server, "bob@example.com", int64(len(udpMsg)))
 }
 
 func TestServerUDPStreamE2E(t *testing.T) {
@@ -433,9 +468,7 @@ func testServerUDPStreamE2E(t *testing.T, controller string) {
 	if _, err := authStream.Write(authPayload); err != nil {
 		t.Fatalf("write authentication payload failed: %v", err)
 	}
-	if err := authStream.Close(); err != nil {
-		t.Fatalf("close authentication stream failed: %v", err)
-	}
+	closeUniStream(t, authStream)
 
 	target := &Address{Type: AddrTypeIPv4, IP: net.ParseIP("8.8.8.8"), Port: 53}
 	udpMsg := bytes.Repeat([]byte("s"), 8500)
@@ -458,9 +491,7 @@ func testServerUDPStreamE2E(t *testing.T, controller string) {
 		if _, err := packetStream.Write(frame.Bytes()); err != nil {
 			t.Fatalf("write packet frame failed: %v", err)
 		}
-		if err := packetStream.Close(); err != nil {
-			t.Fatalf("close packet stream failed: %v", err)
-		}
+		closeUniStream(t, packetStream)
 	}
 
 	replyReassembler := newPacketReassembler(maxUdpRelayPacketSize)

internal/tuic/stream_udp_lifecycle_test.go

@@ -57,9 +57,7 @@ func startLifecycleTestServer(t *testing.T, relayAddr, email string) (*Server, *
 	if _, err := stream.Write(auth); err != nil {
 		t.Fatalf("write authentication: %v", err)
 	}
-	if err := stream.Close(); err != nil {
-		t.Fatalf("close authentication stream: %v", err)
-	}
+	closeUniStream(t, stream)
 	return server, client, clientID, password
 }
 

internal/util/wirecodec/wirecodec.go

@@ -16,6 +16,8 @@ const (
 	HashHeader = "X-Config-Sha256"
 	// CapsHeader is set by a node on its API responses to advertise support.
 	CapsHeader = "X-3x-Node-Caps"
+	// MasterPushHeader marks a request as a master's push, whatever its token scope.
+	MasterPushHeader = "X-3x-Master-Push"
 	// EncodingZstd is the Content-Encoding value for a zstd-compressed body.
 	EncodingZstd = "zstd"
 	// CapZstd is the capability token advertised in CapsHeader.

internal/web/controller/api.go

@@ -98,6 +98,7 @@ var nodeSyncScopeAllow = map[string]map[string]struct{}{
 	"/inbounds/add":                {http.MethodPost: {}},
 	"/inbounds/del/:id":            {http.MethodPost: {}},
 	"/inbounds/update/:id":         {http.MethodPost: {}},
+	"/inbounds/:id/subSortIndex":   {http.MethodPost: {}},
 	"/clients/add":                 {http.MethodPost: {}},
 	"/clients/del/:email":          {http.MethodPost: {}},
 	"/clients/:email/detach":       {http.MethodPost: {}},
@@ -106,11 +107,13 @@ var nodeSyncScopeAllow = map[string]map[string]struct{}{
 	"/server/getWebCertFiles":      {http.MethodGet: {}},
 	"/server/descendants":          {http.MethodGet: {}},
 	"/clients/resetTraffic/:email": {http.MethodPost: {}},
+	"/clients/bulkResetTraffic":    {http.MethodPost: {}},
 	"/inbounds/resetAllTraffics":   {http.MethodPost: {}},
 	"/inbounds/:id/resetTraffic":   {http.MethodPost: {}},
 	"/clients/onlinesByGuid":       {http.MethodPost: {}},
 	"/clients/onlines":             {http.MethodPost: {}},
 	"/clients/lastOnline":          {http.MethodPost: {}},
+	"/clients/activeInbounds":      {http.MethodPost: {}},
 	"/inbounds/pushClientTraffics": {http.MethodPost: {}},
 	"/server/clientIps":            {http.MethodGet: {}, http.MethodPost: {}},
 	"/clients/clientIpsByGuid":     {http.MethodPost: {}},

internal/web/controller/api_auth_test.go

@@ -7,7 +7,6 @@ import (
 	"net/http/cookiejar"
 	"net/http/httptest"
 	"path/filepath"
-	"reflect"
 	"testing"
 
 	"github.com/gin-contrib/sessions"
@@ -138,39 +137,6 @@ func TestCheckAPIAuth_AcceptsVerifiedClientCert(t *testing.T) {
 	}
 }
 
-func TestNodeSyncScopeAllowlistMatchesRemoteInventory(t *testing.T) {
-	expected := map[string]map[string]struct{}{
-		"/server/status":               {http.MethodGet: {}},
-		"/inbounds/list":               {http.MethodGet: {}},
-		"/inbounds/add":                {http.MethodPost: {}},
-		"/inbounds/del/:id":            {http.MethodPost: {}},
-		"/inbounds/update/:id":         {http.MethodPost: {}},
-		"/clients/add":                 {http.MethodPost: {}},
-		"/clients/del/:email":          {http.MethodPost: {}},
-		"/clients/:email/detach":       {http.MethodPost: {}},
-		"/clients/update/:email":       {http.MethodPost: {}},
-		"/server/restartXrayService":   {http.MethodPost: {}},
-		"/server/getWebCertFiles":      {http.MethodGet: {}},
-		"/server/descendants":          {http.MethodGet: {}},
-		"/clients/resetTraffic/:email": {http.MethodPost: {}},
-		"/inbounds/resetAllTraffics":   {http.MethodPost: {}},
-		"/inbounds/:id/resetTraffic":   {http.MethodPost: {}},
-		"/clients/onlinesByGuid":       {http.MethodPost: {}},
-		"/clients/onlines":             {http.MethodPost: {}},
-		"/clients/lastOnline":          {http.MethodPost: {}},
-		"/inbounds/pushClientTraffics": {http.MethodPost: {}},
-		"/server/clientIps":            {http.MethodGet: {}, http.MethodPost: {}},
-		"/clients/clientIpsByGuid":     {http.MethodPost: {}},
-		"/hosts/list":                  {http.MethodGet: {}},
-	}
-	if !reflect.DeepEqual(nodeSyncScopeAllow, expected) {
-		t.Fatalf("node-sync allowlist drift:\n got: %#v\nwant: %#v", nodeSyncScopeAllow, expected)
-	}
-	if _, ok := nodeSyncScopeAllow["/server/updatePanel"]; ok {
-		t.Fatal("node-sync must not include /server/updatePanel")
-	}
-}
-
 func TestNodeSyncScopeUsesFullPathPatterns(t *testing.T) {
 	engine, _ := newAPIAuthTestEngine(t)
 	cases := []struct {

internal/web/controller/inbound.go

@@ -7,6 +7,7 @@ import (
 	"strings"
 
 	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/util/wirecodec"
 	"github.com/mhsanaei/3x-ui/v3/internal/web/middleware"
 	"github.com/mhsanaei/3x-ui/v3/internal/web/service"
 	"github.com/mhsanaei/3x-ui/v3/internal/web/session"
@@ -64,7 +65,9 @@ func (a *InboundController) broadcastInboundsUpdate(userId int) {
 func (a *InboundController) inboundServiceFor(c *gin.Context) *service.InboundService {
 	svc := a.inboundService
 	scope, _ := c.Get("api_token_scope")
-	svc.FromNodeSync = scope == model.ApiScopeNodeSync
+	// A master enrolled with an admin token (the -getApiToken default) has no
+	// node-sync scope, so it marks every request it sends instead.
+	svc.FromNodeSync = scope == model.ApiScopeNodeSync || c.GetHeader(wirecodec.MasterPushHeader) != ""
 	return &svc
 }
 

internal/web/job/tuic_job.go

@@ -2,16 +2,22 @@ package job
 
 import (
 	"fmt"
+	"sync"
 	"time"
 
 	"github.com/mhsanaei/3x-ui/v3/internal/logger"
 	"github.com/mhsanaei/3x-ui/v3/internal/tuic"
 	"github.com/mhsanaei/3x-ui/v3/internal/web/service"
+	"github.com/mhsanaei/3x-ui/v3/internal/web/websocket"
 	"github.com/mhsanaei/3x-ui/v3/internal/xray"
 )
 
+const defaultTuicSpeedSampleInterval = 10 * time.Second
+
 type TuicJob struct {
-	inboundService service.InboundService
+	inboundService  service.InboundService
+	runMu           sync.Mutex
+	lastSpeedSample time.Time
 }
 
 func NewTuicJob() *TuicJob {
@@ -19,6 +25,9 @@ func NewTuicJob() *TuicJob {
 }
 
 func (j *TuicJob) Run() {
+	j.runMu.Lock()
+	defer j.runMu.Unlock()
+
 	tuicJournalMu.Lock()
 	journalErr := j.replayTuicJournal()
 	tuicJournalMu.Unlock()
@@ -44,20 +53,28 @@ func (j *TuicJob) Run() {
 	onlineEmails, _ := mgr.GetActiveClients(30 * time.Second)
 
 	clientTraffics := aggregateTuicClientTraffic(clientDeltas, onlineEmails)
+	sampledAt := time.Now()
+	sampleInterval := tuicSpeedSampleInterval(j.lastSpeedSample, sampledAt)
 
 	// Inbound total traffic is already metered through the loopback SOCKS relay
 	// by xray_traffic_job (matching mtproto); only per-client deltas are submitted here.
+	persisted := true
 	if len(clientTraffics) > 0 {
 		needRestart, _, err := j.inboundService.AddTraffic(nil, clientTraffics)
 		if err != nil {
 			logger.Warning("tuic job: add traffic failed:", err)
 			mgr.RequeueClientTraffic(clientDeltas)
+			persisted = false
 		} else if needRestart {
 			if desired, err := j.inboundService.DesiredTuicInstances(); err == nil {
 				mgr.Reconcile(desired)
 			}
 		}
 	}
+	if persisted {
+		websocket.BroadcastTraffic(tuicSpeedPayload(clientTraffics, sampleInterval))
+		j.lastSpeedSample = sampledAt
+	}
 
 	if len(onlineEmails) > 0 {
 		if err := j.inboundService.BumpClientsLastOnline(onlineEmails); err != nil {
@@ -68,6 +85,25 @@ func (j *TuicJob) Run() {
 	j.inboundService.RefreshLocalOnlineClients(onlineEmails, activeTags)
 }
 
+func tuicSpeedSampleInterval(previous, current time.Time) time.Duration {
+	if previous.IsZero() || !current.After(previous) {
+		return defaultTuicSpeedSampleInterval
+	}
+	return current.Sub(previous)
+}
+
+func tuicSpeedPayload(clientTraffics []*xray.ClientTraffic, sampleInterval time.Duration) map[string]any {
+	intervalMs := sampleInterval.Milliseconds()
+	if intervalMs < 1 {
+		intervalMs = 1
+	}
+	return map[string]any{
+		"clientTraffics":          clientTraffics,
+		"clientTrafficSource":     "tuic",
+		"clientTrafficIntervalMs": intervalMs,
+	}
+}
+
 // FlushStoppedTraffic persists counters drained when the TUIC manager stops its
 // listeners. Call it after scheduled jobs have stopped and before the traffic
 // writer shuts down.

internal/web/job/tuic_job_test.go

@@ -180,3 +180,14 @@ func TestAggregateTuicClientTrafficPreservesStableIdentityAcrossEmailRename(t *t
 		t.Fatalf("aggregate counters = (%d,%d), want (40,60)", got[0].Up, got[0].Down)
 	}
 }
+
+func TestTuicSpeedSampleIntervalUsesElapsedPollTime(t *testing.T) {
+	current := time.Date(2026, time.October, 3, 12, 0, 10, 0, time.UTC)
+	previous := current.Add(-12 * time.Second)
+	if got := tuicSpeedSampleInterval(previous, current); got != 12*time.Second {
+		t.Fatalf("sample interval = %s, want 12s", got)
+	}
+	if got := tuicSpeedSampleInterval(time.Time{}, current); got != defaultTuicSpeedSampleInterval {
+		t.Fatalf("initial sample interval = %s, want %s", got, defaultTuicSpeedSampleInterval)
+	}
+}

internal/web/node_contract_test.go

@@ -0,0 +1,383 @@
+package web
+
+import (
+	"context"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"path/filepath"
+	"reflect"
+	"strconv"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+
+	"github.com/robfig/cron/v3"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database"
+	"github.com/mhsanaei/3x-ui/v3/internal/database/dbtest"
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/util/crypto"
+	"github.com/mhsanaei/3x-ui/v3/internal/web/global"
+	"github.com/mhsanaei/3x-ui/v3/internal/web/runtime"
+	"github.com/mhsanaei/3x-ui/v3/internal/web/service"
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+)
+
+// nodeUnderContract serves the production router as a node and records every
+// request the node refused for auth or scope.
+type nodeUnderContract struct {
+	srv     *httptest.Server
+	mu      sync.Mutex
+	refused []string
+}
+
+func startContractNode(t *testing.T) *nodeUnderContract {
+	t.Helper()
+	dbDir := t.TempDir()
+	t.Setenv("XUI_DB_FOLDER", dbDir)
+	dbtest.InitDB(t, filepath.Join(dbDir, "x-ui.db"))
+	prevMgr := runtime.GetManager()
+	runtime.SetManager(runtime.NewManager(runtime.LocalDeps{APIPort: func() int { return 0 }, SetNeedRestart: func() {}}))
+	t.Cleanup(func() { runtime.SetManager(prevMgr) })
+
+	previous := global.GetWebServer()
+	s := NewServer()
+	s.cron = cron.New(cron.WithLocation(time.Local), cron.WithSeconds())
+	global.SetWebServer(s)
+	t.Cleanup(func() {
+		s.cancel()
+		global.SetWebServer(previous)
+	})
+	engine, err := s.initRouter()
+	if err != nil {
+		t.Fatalf("initRouter: %v", err)
+	}
+	n := &nodeUnderContract{}
+	n.srv = httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		rec := &statusRecorder{ResponseWriter: w, status: http.StatusOK}
+		engine.ServeHTTP(rec, r)
+		if rec.status == http.StatusUnauthorized || rec.status == http.StatusForbidden {
+			n.mu.Lock()
+			n.refused = append(n.refused, r.Method+" "+r.URL.Path+" -> "+strconv.Itoa(rec.status))
+			n.mu.Unlock()
+		}
+	}))
+	t.Cleanup(n.srv.Close)
+	return n
+}
+
+type statusRecorder struct {
+	http.ResponseWriter
+	status int
+}
+
+func (r *statusRecorder) WriteHeader(code int) {
+	r.status = code
+	r.ResponseWriter.WriteHeader(code)
+}
+
+func (n *nodeUnderContract) takeRefused() []string {
+	n.mu.Lock()
+	defer n.mu.Unlock()
+	out := n.refused
+	n.refused = nil
+	return out
+}
+
+func (n *nodeUnderContract) masterWithToken(t *testing.T, scope string) *runtime.Remote {
+	t.Helper()
+	token := "contract-" + scope
+	if err := database.GetDB().Create(&model.ApiToken{
+		Name: "master-" + scope, Token: crypto.HashTokenSHA256(token), Enabled: true, Scope: scope,
+	}).Error; err != nil {
+		t.Fatalf("seed %s token: %v", scope, err)
+	}
+	u, _ := url.Parse(n.srv.URL)
+	port, _ := strconv.Atoi(u.Port())
+	return runtime.NewRemote(&model.Node{
+		Id: 1, Name: "contract-node", Scheme: "http", Address: u.Hostname(), Port: port,
+		BasePath: "/", ApiToken: token, Enable: true, AllowPrivateAddress: true,
+	}, nil)
+}
+
+func nodeRow(t *testing.T, tag string) (*model.Inbound, bool) {
+	t.Helper()
+	var ib model.Inbound
+	err := database.GetDB().Where("tag = ?", tag).First(&ib).Error
+	return &ib, err == nil
+}
+
+func nodeTraffic(t *testing.T, email string) int64 {
+	t.Helper()
+	var ct xray.ClientTraffic
+	if err := database.GetDB().Where("email = ?", email).First(&ct).Error; err != nil {
+		t.Fatalf("client_traffics %s: %v", email, err)
+	}
+	return ct.Up + ct.Down
+}
+
+func seedNodeTraffic(t *testing.T, emails ...string) {
+	t.Helper()
+	for _, e := range emails {
+		if err := database.GetDB().Model(&xray.ClientTraffic{}).Where("email = ?", e).
+			Updates(map[string]any{"up": 100, "down": 200}).Error; err != nil {
+			t.Fatalf("seed traffic %s: %v", e, err)
+		}
+	}
+	if err := database.GetDB().Model(&model.Inbound{}).Where("tag = ?", contractTag).
+		Updates(map[string]any{"up": 100, "down": 200}).Error; err != nil {
+		t.Fatalf("seed inbound traffic: %v", err)
+	}
+}
+
+const contractTag = "in-51001-tcp"
+
+func masterInbound(remark string, enable bool, clients ...string) *model.Inbound {
+	entries := make([]string, 0, len(clients))
+	for i, email := range clients {
+		entries = append(entries, `{"email":"`+email+`","enable":true,"subId":"s-`+email+
+			`","id":"0b6d5c2e-7c1a-4f4e-9d3b-00000000000`+strconv.Itoa(i)+`"}`)
+	}
+	return &model.Inbound{
+		Tag: contractTag, Remark: remark, Enable: enable, Port: 51001, Protocol: model.VLESS,
+		Settings:       `{"clients":[` + strings.Join(entries, ",") + `],"decryption":"none"}`,
+		StreamSettings: `{"network":"tcp","security":"none","tcpSettings":{"header":{"type":"none"}}}`,
+		Sniffing:       `{}`,
+	}
+}
+
+func nodeEmails(t *testing.T) []string {
+	t.Helper()
+	ib, ok := nodeRow(t, contractTag)
+	if !ok {
+		t.Fatal("node has no contract inbound")
+	}
+	clients, err := (&service.InboundService{}).GetClients(ib)
+	if err != nil {
+		t.Fatalf("parse node clients: %v", err)
+	}
+	emails := make([]string, 0, len(clients))
+	for _, c := range clients {
+		emails = append(emails, c.Email)
+	}
+	return emails
+}
+
+// TestMasterNodeContract sends every node call the master makes through the production
+// router, once per enrollment scope; UpdatePanel is excluded from node-sync on purpose.
+func TestMasterNodeContract(t *testing.T) {
+	for _, scope := range []string{model.ApiScopeAdmin, model.ApiScopeNodeSync} {
+		t.Run(scope, func(t *testing.T) {
+			node := startContractNode(t)
+			master := node.masterWithToken(t, scope)
+			ctx := context.Background()
+
+			cells := []struct {
+				name   string
+				covers []string
+				run    func() error
+				check  func(t *testing.T)
+			}{
+				{"AddInbound creates the inbound with its clients", []string{"AddInbound"}, func() error {
+					return master.AddInbound(ctx, masterInbound("added", true, "c0", "c1"))
+				}, func(t *testing.T) {
+					if got := nodeEmails(t); strings.Join(got, ",") != "c0,c1" {
+						t.Fatalf("node clients = %v, want c0,c1", got)
+					}
+				}},
+				{"UpdateInbound applies remark, clients and enable", []string{"UpdateInbound", "AddUser", "RemoveUser", "ReconcileInbound"}, func() error {
+					ib := masterInbound("updated", false, "c0", "c1", "c2")
+					if err := master.AddUser(ctx, ib, nil); err != nil {
+						return err
+					}
+					if err := master.RemoveUser(ctx, ib, ""); err != nil {
+						return err
+					}
+					if _, err := master.ReconcileInbound(ctx, ib, true); err != nil {
+						return err
+					}
+					return master.UpdateInbound(ctx, ib, ib)
+				}, func(t *testing.T) {
+					ib, _ := nodeRow(t, contractTag)
+					if ib.Remark != "updated" || ib.Enable {
+						t.Fatalf("node remark=%q enable=%v, want updated/false", ib.Remark, ib.Enable)
+					}
+					if got := nodeEmails(t); strings.Join(got, ",") != "c0,c1,c2" {
+						t.Fatalf("node clients = %v, want c0,c1,c2", got)
+					}
+				}},
+				{"SetInboundSubSortIndex reaches the node", []string{"SetInboundSubSortIndex"}, func() error {
+					return master.SetInboundSubSortIndex(ctx, masterInbound("updated", false), 7)
+				}, func(t *testing.T) {
+					if ib, _ := nodeRow(t, contractTag); ib.SubSortIndex != 7 {
+						t.Fatalf("node subSortIndex = %d, want 7", ib.SubSortIndex)
+					}
+				}},
+				{"AddClient attaches one client", []string{"AddClient"}, func() error {
+					return master.AddClient(ctx, masterInbound("updated", false), model.Client{
+						Email: "c3", ID: "0b6d5c2e-7c1a-4f4e-9d3b-000000000003", SubID: "s-c3", Enable: true,
+					})
+				}, func(t *testing.T) {
+					if got := nodeEmails(t); !strings.Contains(strings.Join(got, ","), "c3") {
+						t.Fatalf("node clients = %v, want c3 among them", got)
+					}
+				}},
+				{"UpdateUser changes the client's limits", []string{"UpdateUser"}, func() error {
+					return master.UpdateUser(ctx, masterInbound("updated", false), "c3", model.Client{
+						Email: "c3", ID: "0b6d5c2e-7c1a-4f4e-9d3b-000000000003", SubID: "s-c3", Enable: true, TotalGB: 5 << 30,
+					})
+				}, func(t *testing.T) {
+					var ct xray.ClientTraffic
+					database.GetDB().Where("email = ?", "c3").First(&ct)
+					if ct.Total != 5<<30 {
+						t.Fatalf("node c3 total = %d, want %d", ct.Total, int64(5<<30))
+					}
+				}},
+				{"ResetClientTraffic zeroes one client", []string{"ResetClientTraffic"}, func() error {
+					seedNodeTraffic(t, "c0")
+					return master.ResetClientTraffic(ctx, nil, "c0")
+				}, func(t *testing.T) {
+					if u := nodeTraffic(t, "c0"); u != 0 {
+						t.Fatalf("node c0 usage = %d, want 0", u)
+					}
+				}},
+				{"ResetClientTraffics zeroes several clients", []string{"ResetClientTraffics"}, func() error {
+					seedNodeTraffic(t, "c1", "c2")
+					return master.ResetClientTraffics(ctx, []string{"c1", "c2"})
+				}, func(t *testing.T) {
+					if u := nodeTraffic(t, "c1") + nodeTraffic(t, "c2"); u != 0 {
+						t.Fatalf("node c1+c2 usage = %d, want 0", u)
+					}
+				}},
+				{"ResetInboundTraffic zeroes the inbound", []string{"ResetInboundTraffic"}, func() error {
+					seedNodeTraffic(t)
+					return master.ResetInboundTraffic(ctx, masterInbound("updated", false))
+				}, func(t *testing.T) {
+					if ib, _ := nodeRow(t, contractTag); ib.Up+ib.Down != 0 {
+						t.Fatalf("node inbound usage = %d, want 0", ib.Up+ib.Down)
+					}
+				}},
+				{"ResetAllTraffics zeroes every inbound's counters", []string{"ResetAllTraffics"}, func() error {
+					seedNodeTraffic(t)
+					return master.ResetAllTraffics(ctx)
+				}, func(t *testing.T) {
+					if ib, _ := nodeRow(t, contractTag); ib.Up+ib.Down != 0 {
+						t.Fatalf("node inbound usage = %d, want 0", ib.Up+ib.Down)
+					}
+				}},
+				{"FetchTrafficSnapshot reads every part of the snapshot", []string{"FetchTrafficSnapshot"}, func() error {
+					_, err := master.FetchTrafficSnapshot(ctx)
+					return err
+				}, nil},
+				{"PushGlobalClientTraffics is accepted", []string{"PushGlobalClientTraffics"}, func() error {
+					return master.PushGlobalClientTraffics(ctx, "master-guid", []*xray.ClientTraffic{{Email: "c0", Up: 1, Down: 2}})
+				}, nil},
+				{"client IP sync is accepted both ways", []string{"FetchAllClientIps", "PushAllClientIps", "FetchClientIpsByGuid"}, func() error {
+					ips, err := master.FetchAllClientIps(ctx)
+					if err != nil {
+						return err
+					}
+					if err := master.PushAllClientIps(ctx, ips); err != nil {
+						return err
+					}
+					_, err = master.FetchClientIpsByGuid(ctx)
+					return err
+				}, nil},
+				{"host groups, descendants and web cert files are readable", []string{"FetchHostGroups", "GetDescendants", "GetWebCertFiles", "ListInboundOptions", "ListRemoteTags"}, func() error {
+					if _, err := master.FetchHostGroups(ctx); err != nil {
+						return err
+					}
+					if _, err := master.GetDescendants(ctx); err != nil {
+						return err
+					}
+					if _, err := master.GetWebCertFiles(ctx); err != nil {
+						return err
+					}
+					if _, err := master.ListInboundOptions(ctx); err != nil {
+						return err
+					}
+					_, err := master.ListRemoteTags(ctx)
+					return err
+				}, nil},
+				{"RestartXray is accepted by the node", []string{"RestartXray"}, func() error {
+					// No core binary here: only the node's own restart failure may come back.
+					if err := master.RestartXray(ctx); err != nil && !strings.Contains(err.Error(), "rebooting the Xray") {
+						return err
+					}
+					return nil
+				}, nil},
+				{"DeleteUser detaches the client from the inbound", []string{"DeleteUser"}, func() error {
+					return master.DeleteUser(ctx, masterInbound("updated", false), "c3")
+				}, func(t *testing.T) {
+					if got := nodeEmails(t); strings.Contains(strings.Join(got, ","), "c3") {
+						t.Fatalf("node clients = %v, want c3 gone", got)
+					}
+				}},
+				{"DeleteClient removes the client everywhere", []string{"DeleteClient"}, func() error {
+					return master.DeleteClient(ctx, "c2")
+				}, func(t *testing.T) {
+					if got := nodeEmails(t); strings.Contains(strings.Join(got, ","), "c2") {
+						t.Fatalf("node clients = %v, want c2 gone", got)
+					}
+				}},
+				{"DelInbound removes the inbound", []string{"DelInbound"}, func() error {
+					return master.DelInbound(ctx, masterInbound("updated", false))
+				}, func(t *testing.T) {
+					if _, ok := nodeRow(t, contractTag); ok {
+						t.Fatal("node still has the inbound")
+					}
+				}},
+			}
+			covered := map[string]bool{}
+			for _, c := range cells {
+				for _, m := range c.covers {
+					covered[m] = true
+				}
+			}
+			assertEveryRemoteCallCovered(t, covered)
+			for _, c := range cells {
+				t.Run(c.name, func(t *testing.T) {
+					node.takeRefused()
+					if err := c.run(); err != nil {
+						t.Fatalf("master call failed: %v", err)
+					}
+					if refused := node.takeRefused(); len(refused) != 0 {
+						t.Fatalf("node refused master requests: %v", refused)
+					}
+					if c.check != nil {
+						c.check(t)
+					}
+				})
+			}
+		})
+	}
+}
+
+// Remote methods that never reach the node, or that this table must not run.
+var remoteMethodsOutsideContract = map[string]string{
+	"Name":                  "local label",
+	"RecordAdoptedInbound":  "local fingerprint bookkeeping",
+	"AdoptInboundAlias":     "local alias bookkeeping",
+	"AdoptedInboundAliases": "local alias bookkeeping",
+	"AdvancePushedInbound":  "local fingerprint bookkeeping",
+	"ForgetPushedInbound":   "local fingerprint bookkeeping",
+	"UpdatePanel":           "replaces the node binary; node-sync is denied it on purpose (#6201)",
+}
+
+// A Remote method with no cell is how activeInbounds and bulkResetTraffic
+// drifted out of the node-sync allowlist unnoticed.
+func assertEveryRemoteCallCovered(t *testing.T, covered map[string]bool) {
+	t.Helper()
+	rt := reflect.TypeOf(&runtime.Remote{})
+	for i := 0; i < rt.NumMethod(); i++ {
+		name := rt.Method(i).Name
+		if _, skip := remoteMethodsOutsideContract[name]; skip {
+			continue
+		}
+		if !covered[name] {
+			t.Errorf("runtime.Remote.%s has no cell in TestMasterNodeContract", name)
+		}
+	}
+}

internal/web/runtime/reconcile_skip_test.go

@@ -17,7 +17,8 @@ import (
 func TestReconcileInbound_SkipsUnchanged(t *testing.T) {
 	var pushes atomic.Int32
 	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		if r.Method == http.MethodPost && strings.Contains(r.URL.Path, "/panel/api/inbounds/update/") {
+		if r.Method == http.MethodPost && (strings.Contains(r.URL.Path, "/panel/api/inbounds/update/") ||
+			strings.Contains(r.URL.Path, "/panel/api/inbounds/add")) {
 			pushes.Add(1)
 		}
 		w.Header().Set("Content-Type", "application/json")
@@ -283,7 +284,7 @@ func TestDelInboundDropsReconcileFingerprint(t *testing.T) {
 	ib := &model.Inbound{Tag: "in-del", Protocol: model.VLESS, Port: 443, Settings: `{"clients":[]}`}
 	r.cacheSet(ib.Tag, 7)
 
-	if pushed, err := r.ReconcileInbound(context.Background(), ib, false); err != nil || !pushed {
+	if pushed, err := r.ReconcileInbound(context.Background(), ib, true); err != nil || !pushed {
 		t.Fatalf("initial reconcile: pushed=%v err=%v, want push", pushed, err)
 	}
 	if err := r.DelInbound(context.Background(), ib); err != nil {
@@ -317,3 +318,36 @@ func TestUpdateInboundFallbackAddSeedsReconcileFingerprint(t *testing.T) {
 		t.Fatalf("reconcile sent %d full inbound updates, want 0", got)
 	}
 }
+
+// An inbound deleted on the node must be re-created by the next reconcile; a
+// cached tag→id from before the delete used to send update/<gone id> forever.
+func TestReconcileInbound_RecreatesInboundTheNodeLost(t *testing.T) {
+	var adds, staleUpdates atomic.Int32
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		switch {
+		case strings.Contains(r.URL.Path, "/panel/api/inbounds/list"):
+			_, _ = w.Write([]byte(`{"success":true,"obj":[]}`))
+		case strings.Contains(r.URL.Path, "/panel/api/inbounds/update/"):
+			staleUpdates.Add(1)
+			_, _ = w.Write([]byte(`{"success":false,"msg":"record not found"}`))
+		case strings.Contains(r.URL.Path, "/panel/api/inbounds/add"):
+			adds.Add(1)
+			_, _ = w.Write([]byte(`{"success":true,"obj":{"id":9,"tag":"in-1"}}`))
+		default:
+			_, _ = w.Write([]byte(`{"success":true}`))
+		}
+	}))
+	defer srv.Close()
+
+	r := NewRemote(nodeForPlainServer(t, srv, "verify", "tok"), nil)
+	ib := &model.Inbound{Tag: "n1-in-1", Protocol: model.VLESS, Port: 443, Settings: `{"clients":[]}`}
+	r.cacheSet("in-1", 7)
+
+	if pushed, err := r.ReconcileInbound(context.Background(), ib, false); err != nil || !pushed {
+		t.Fatalf("reconcile of a lost inbound: pushed=%v err=%v, want a re-create", pushed, err)
+	}
+	if staleUpdates.Load() != 0 || adds.Load() != 1 {
+		t.Fatalf("updates to the stale id=%d adds=%d, want 0 and 1", staleUpdates.Load(), adds.Load())
+	}
+}

internal/web/runtime/remote.go

@@ -237,6 +237,7 @@ func (r *Remote) do(ctx context.Context, method, path string, body any) (*envelo
 		req.Header.Set("Authorization", "Bearer "+token)
 	}
 	req.Header.Set("Accept", "application/json")
+	req.Header.Set(wirecodec.MasterPushHeader, "1")
 	if contentType != "" {
 		req.Header.Set("Content-Type", contentType)
 	}
@@ -359,6 +360,15 @@ func (r *Remote) cacheDel(tag string) {
 	delete(r.pushedFP, tag)
 }
 
+// forgetTag drops every tag form cacheGetTag would match, once the node reports
+// none of them, so the next resolve re-reads the node instead of a deleted id.
+func (r *Remote) forgetTag(tag string) {
+	prefix := nodeInboundTagPrefix(r.node.Id)
+	bare := strings.TrimPrefix(tag, prefix)
+	r.cacheDel(bare)
+	r.cacheDel(prefix + bare)
+}
+
 func (r *Remote) ListRemoteTags(ctx context.Context) ([]string, error) {
 	if err := r.refreshRemoteIDs(ctx); err != nil {
 		return nil, err
@@ -494,6 +504,8 @@ func (r *Remote) ReconcileInbound(ctx context.Context, ib *model.Inbound, exists
 		if ok && prev == fp {
 			return false, nil
 		}
+	} else {
+		r.forgetTag(ib.Tag)
 	}
 	if err := r.UpdateInbound(ctx, ib, ib); err != nil {
 		return false, err
@@ -516,6 +528,17 @@ func (r *Remote) RecordAdoptedInbound(ib *model.Inbound) {
 	r.recordPushedInbound(ib)
 }
 
+// ForgetPushedInbound drops the reconcile-skip fingerprint once the node is seen
+// without the payload it stamped, so the next reconcile re-sends the inbound.
+func (r *Remote) ForgetPushedInbound(tag string) {
+	prefix := nodeInboundTagPrefix(r.node.Id)
+	bare := strings.TrimPrefix(tag, prefix)
+	r.mu.Lock()
+	delete(r.pushedFP, bare)
+	delete(r.pushedFP, prefix+bare)
+	r.mu.Unlock()
+}
+
 // AdoptInboundAlias records a deployed alias without mutating either panel.
 // The runtime association is rediscovered after a master restart.
 func (r *Remote) AdoptInboundAlias(ib *model.Inbound, remote RemoteInboundOption) {

internal/web/service/client_sync_orphan_test.go

@@ -30,8 +30,8 @@ func backdateOrphanMark(t *testing.T, db *gorm.DB, email string) {
 	}
 }
 
-// The merge must soft-orphan, not delete: everything stays recoverable until
-// the grace period has elapsed and the reaper confirms nothing reclaimed it.
+// A partial snapshot (node alive, still serving another client) authoritatively drops one;
+// the merge soft-orphans, recoverable until the grace elapses and the reaper confirms it.
 func TestSyncOrphanSurvivesMergeUntilGraceElapses(t *testing.T) {
 	db := initTrafficTestDB(t)
 	svc := &InboundService{}
@@ -40,16 +40,20 @@ func TestSyncOrphanSurvivesMergeUntilGraceElapses(t *testing.T) {
 	seedNodeRow(t, db, &model.Node{Id: 1, Name: "n1", Address: "127.0.0.1", Port: 2096, ApiToken: "tok", Enable: true})
 
 	const email = "gone@x"
-	createNodeInboundWithClient(t, db, 1, "n1-in", 41001, email)
-	settings := fmt.Sprintf(`{"clients":[{"email":%q,"enable":true}]}`, email)
-	syncNodeWithSettings(t, svc, 1, "n1-in", settings,
+	const keep = "keep@x"
+	createNodeInboundWithClient(t, db, 1, "n1-in", 41001, keep)
+	bothSettings := fmt.Sprintf(`{"clients":[{"email":%q,"enable":true},{"email":%q,"enable":true}]}`, keep, email)
+	syncNodeWithSettings(t, svc, 1, "n1-in", bothSettings,
+		xray.ClientTraffic{Email: keep, Enable: true},
 		xray.ClientTraffic{Email: email, Up: 5, Down: 5, Enable: true})
 
 	if rec, traf := countClientRows(t, db, email); rec != 1 || traf != 1 {
 		t.Fatalf("setup: clients=%d client_traffics=%d, want 1/1", rec, traf)
 	}
 
-	if _, err := svc.setRemoteTrafficLocked(1, snapshotWithoutClients(t, "n1-in"), false, false); err != nil {
+	keepOnly := fmt.Sprintf(`{"clients":[{"email":%q,"enable":true}]}`, keep)
+	if _, err := svc.setRemoteTrafficLocked(1, snapshotWithClients(t, "n1-in", keepOnly,
+		xray.ClientTraffic{Email: keep, Enable: true}), false, false); err != nil {
 		t.Fatalf("orphaning merge: %v", err)
 	}
 	if rec, traf := countClientRows(t, db, email); rec != 1 || traf != 1 {
@@ -84,7 +88,7 @@ func TestSyncOrphanSurvivesMergeUntilGraceElapses(t *testing.T) {
 	}
 }
 
-// A client the node reports again was never gone: clearing the mark is what
+// A client the node reports again (partial snapshot) was never gone: clearing the mark
 // turns a bad merge into a recoverable blip instead of a delayed deletion.
 func TestSyncOrphanMarkClearedOnReattach(t *testing.T) {
 	db := initTrafficTestDB(t)
@@ -94,19 +98,24 @@ func TestSyncOrphanMarkClearedOnReattach(t *testing.T) {
 	seedNodeRow(t, db, &model.Node{Id: 1, Name: "n1", Address: "127.0.0.1", Port: 2096, ApiToken: "tok", Enable: true})
 
 	const email = "flaky@x"
-	createNodeInboundWithClient(t, db, 1, "n1-in", 41001, email)
-	settings := fmt.Sprintf(`{"clients":[{"email":%q,"enable":true}]}`, email)
-	syncNodeWithSettings(t, svc, 1, "n1-in", settings,
+	const keep = "keep@x"
+	createNodeInboundWithClient(t, db, 1, "n1-in", 41001, keep)
+	bothSettings := fmt.Sprintf(`{"clients":[{"email":%q,"enable":true},{"email":%q,"enable":true}]}`, keep, email)
+	syncNodeWithSettings(t, svc, 1, "n1-in", bothSettings,
+		xray.ClientTraffic{Email: keep, Enable: true},
 		xray.ClientTraffic{Email: email, Up: 5, Down: 5, Enable: true})
 
-	if _, err := svc.setRemoteTrafficLocked(1, snapshotWithoutClients(t, "n1-in"), false, false); err != nil {
+	keepOnly := fmt.Sprintf(`{"clients":[{"email":%q,"enable":true}]}`, keep)
+	if _, err := svc.setRemoteTrafficLocked(1, snapshotWithClients(t, "n1-in", keepOnly,
+		xray.ClientTraffic{Email: keep, Enable: true}), false, false); err != nil {
 		t.Fatalf("orphaning merge: %v", err)
 	}
 	if readOrphanMark(t, db, email) <= 0 {
 		t.Fatal("setup: expected the merge to mark the client")
 	}
 
-	syncNodeWithSettings(t, svc, 1, "n1-in", settings,
+	syncNodeWithSettings(t, svc, 1, "n1-in", bothSettings,
+		xray.ClientTraffic{Email: keep, Enable: true},
 		xray.ClientTraffic{Email: email, Up: 6, Down: 6, Enable: true})
 
 	if orphanedAt := readOrphanMark(t, db, email); orphanedAt != 0 {

internal/web/service/inbound_amneziawg_test.go

@@ -287,6 +287,9 @@ func TestNormalizeAmneziaWGSettings_CanonicalizesClientAllowedIPs(t *testing.T)
 }
 
 func TestGetAmneziaWGLogs_ClampsCountAndFiltersEvents(t *testing.T) {
+	// GetAmneziaWGLogs appends peer handshake activity, which reads the DB;
+	// own a throwaway one so -shuffle can't leave us the global nil DB.
+	setupConflictDB(t)
 	logger.InitLogger(logging.DEBUG)
 	logger.Info("amneziawg: started interface awg1 for inbound 1")
 	logger.Info("xray: unrelated line that must never show up here")

internal/web/service/inbound_node.go

@@ -427,6 +427,34 @@ func adoptedWireInbound(c, snapIb *model.Inbound, adoptedSettings string) *model
 	return &a
 }
 
+// snapshotDropsEveryHubClient reports a node that lists no clients where the hub
+// still links some: a reset or half-started node, never an authoritative removal.
+func snapshotDropsEveryHubClient(tx *gorm.DB, inboundID int, wireSettings string) bool {
+	clients, err := ParseInboundSettingsClients(wireSettings)
+	if err != nil || len(clients) > 0 {
+		return false
+	}
+	var links int64
+	if err := tx.Table("client_inbounds").Where("inbound_id = ?", inboundID).Count(&links).Error; err != nil {
+		return false
+	}
+	return links > 0
+}
+
+// snapshotAttachedEmails lowercases the emails a snapshot inbound's settings list;
+// ok is false when the settings cannot be parsed, so membership is unknown.
+func snapshotAttachedEmails(settings string) (map[string]struct{}, bool) {
+	clients, err := ParseInboundSettingsClients(settings)
+	if err != nil {
+		return nil, false
+	}
+	emails := make(map[string]struct{}, len(clients))
+	for i := range clients {
+		emails[strings.ToLower(clients[i].Email)] = struct{}{}
+	}
+	return emails, true
+}
+
 // clientEmailsOwnedElsewhere returns the emails attached only to inbounds of
 // other nodes: email is unique, so adopting one would overwrite a client this
 // node does not serve. Attached nowhere means soft-orphaned, hence adoptable.
@@ -644,6 +672,7 @@ func (s *InboundService) setRemoteTrafficLocked(nodeID int, snap *runtime.Traffi
 		wireSettings string
 	}
 	var pendingAdopts []pendingAdopt
+	degradedInbounds := map[int]string{}
 
 	newInboundIDs := make(map[int]struct{})
 
@@ -782,7 +811,9 @@ func (s *InboundService) setRemoteTrafficLocked(nodeID int, snap *runtime.Traffi
 			adoptedSettings = deduped
 		}
 		updates := map[string]any{}
-		if !dirty {
+		if !dirty && snapshotDropsEveryHubClient(tx, c.Id, adoptedSettings) {
+			degradedInbounds[c.Id] = c.Tag
+		} else if !dirty {
 			// Defer lifecycle lift until after client_traffics absorbs this tick's
 			// deltas so quota stale-disable matches SQL (#6228).
 			pendingAdopts = append(pendingAdopts, pendingAdopt{
@@ -925,7 +956,12 @@ func (s *InboundService) setRemoteTrafficLocked(nodeID int, snap *runtime.Traffi
 		snapEmails := make(map[string]struct{}, len(snapIb.ClientStats))
 		// Parsed once per inbound on the first renewal candidate, not per client.
 		var snapExpiries map[string]int64
+		attachedOnNode, membershipKnown := snapshotAttachedEmails(snapIb.Settings)
 		for _, cs := range snapIb.ClientStats {
+			// A node detach keeps the stat row, so its quota and verdict are stale (#6724).
+			if _, attached := attachedOnNode[strings.ToLower(cs.Email)]; membershipKnown && !attached {
+				continue
+			}
 			snapEmails[cs.Email] = struct{}{}
 
 			// Node-wide total, not this inbound's possibly-stale copy (#5274).
@@ -1121,6 +1157,9 @@ func (s *InboundService) setRemoteTrafficLocked(nodeID int, snap *runtime.Traffi
 			if k.inboundID != c.Id {
 				continue
 			}
+			if _, degraded := degradedInbounds[c.Id]; degraded {
+				continue
+			}
 			if _, kept := snapEmails[k.email]; kept {
 				continue
 			}
@@ -1228,6 +1267,13 @@ func (s *InboundService) setRemoteTrafficLocked(nodeID int, snap *runtime.Traffi
 			applyMasterClientLifecycle(&clients[i], existing, csPtr)
 			filtered = append(filtered, clients[i])
 		}
+		// A degraded node (reset/restart/removal) reports zero clients for an inbound the
+		// hub populates; adopting it empties links and ReapSyncOrphans deletes shared clients (#6734).
+		if _, degraded := degradedInbounds[c.Id]; degraded {
+			logger.Warningf("setRemoteTraffic: node %d reported zero clients for tag %q while the hub has %d attached — keeping them and re-pushing", nodeID, snapIb.Tag, len(oldEmailsRows))
+			syncFailedInbounds[c.Id] = struct{}{}
+			continue
+		}
 		localEmails := make([]string, 0, len(filtered))
 		for i := range filtered {
 			if filtered[i].Email != "" {
@@ -1337,6 +1383,21 @@ func (s *InboundService) setRemoteTrafficLocked(nodeID int, snap *runtime.Traffi
 	}
 	committed = true
 
+	if len(degradedInbounds) > 0 {
+		if mgr := runtime.GetManager(); mgr != nil {
+			if rt, rtErr := mgr.RuntimeFor(&nodeID); rtErr == nil {
+				if rem, ok := rt.(*runtime.Remote); ok {
+					for _, tag := range degradedInbounds {
+						rem.ForgetPushedInbound(tag)
+					}
+				}
+			}
+		}
+		if err := (&NodeService{}).MarkNodeDirty(nodeID); err != nil {
+			logger.Warningf("setRemoteTraffic: mark node %d dirty after an empty snapshot failed: %v", nodeID, err)
+		}
+	}
+
 	if lifecycleLifted && !dirty {
 		var already model.Node
 		if err := database.GetDB().Select("config_dirty").Where("id = ?", nodeID).First(&already).Error; err == nil && already.ConfigDirty {

internal/web/service/node_degraded_snapshot_test.go

@@ -0,0 +1,205 @@
+package service
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/web/runtime"
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+
+	"gorm.io/gorm"
+)
+
+// linkCount returns how many client_inbounds links a client currently has,
+// across every inbound — the value ReapSyncOrphans checks before deleting.
+func linkCount(t *testing.T, db *gorm.DB, email string) int64 {
+	t.Helper()
+	var n int64
+	if err := db.Table("client_inbounds").
+		Joins("JOIN clients ON clients.id = client_inbounds.client_id").
+		Where("clients.email = ?", email).
+		Count(&n).Error; err != nil {
+		t.Fatalf("count links for %q: %v", email, err)
+	}
+	return n
+}
+
+// A degraded node reporting zero clients for an inbound the hub populates must
+// keep its links and never orphan-mark, or SyncInbound/ReapSyncOrphans delete the row.
+func TestSetRemoteTraffic_EmptySnapshotKeepsClients(t *testing.T) {
+	db := initTrafficTestDB(t)
+	svc := &InboundService{}
+
+	seedNodeRow(t, db, &model.Node{Id: 1, Name: "n1", Address: "127.0.0.1", Port: 2096, ApiToken: "tok", Enable: true})
+	createNodeInboundWithClient(t, db, 1, "n1-in", 41001, "svc@x")
+
+	settings := `{"clients":[{"email":"svc@x","enable":true}]}`
+	if _, err := svc.setRemoteTrafficLocked(1, snapshotWithClients(t, "n1-in", settings,
+		xray.ClientTraffic{Email: "svc@x", Enable: true}), false, false); err != nil {
+		t.Fatalf("seed sync: %v", err)
+	}
+	if n := linkCount(t, db, "svc@x"); n != 1 {
+		t.Fatalf("setup: svc@x links=%d, want 1", n)
+	}
+
+	// The node returns an empty snapshot — the trigger that deleted real clients.
+	if _, err := svc.setRemoteTrafficLocked(1, snapshotWithoutClients(t, "n1-in"), false, false); err != nil {
+		t.Fatalf("empty-snapshot sync: %v", err)
+	}
+
+	if rec, _ := countClientRows(t, db, "svc@x"); rec != 1 {
+		t.Fatalf("empty snapshot deleted the client row: clients=%d, want 1", rec)
+	}
+	if n := linkCount(t, db, "svc@x"); n != 1 {
+		t.Fatalf("empty snapshot stripped the client link: links=%d, want 1", n)
+	}
+	if at := readOrphanMark(t, db, "svc@x"); at != 0 {
+		t.Fatalf("empty snapshot orphan-marked a live client: sync_orphaned_at=%d, want 0", at)
+	}
+	// The hub must keep the client in the inbound's settings, or reconcile re-pushes
+	// an empty blob to the node and the clients never come back (#6734).
+	var ib model.Inbound
+	if err := db.Where("tag = ?", "n1-in").First(&ib).Error; err != nil {
+		t.Fatalf("read central inbound: %v", err)
+	}
+	if !strings.Contains(ib.Settings, "svc@x") {
+		t.Fatalf("empty snapshot blanked the inbound settings: %q", ib.Settings)
+	}
+}
+
+// The guard is narrow: a snapshot still carrying a client is authoritative, so a
+// client the node really dropped is unlinked and orphan-marked; only all-empty is degraded.
+func TestSetRemoteTraffic_PartialSnapshotStillPrunes(t *testing.T) {
+	db := initTrafficTestDB(t)
+	svc := &InboundService{}
+
+	seedNodeRow(t, db, &model.Node{Id: 1, Name: "n1", Address: "127.0.0.1", Port: 2096, ApiToken: "tok", Enable: true})
+	createNodeInboundWithClient(t, db, 1, "n1-in", 41001, "keep@x")
+
+	bothSettings := `{"clients":[{"email":"keep@x","enable":true},{"email":"drop@x","enable":true}]}`
+	if _, err := svc.setRemoteTrafficLocked(1, snapshotWithClients(t, "n1-in", bothSettings,
+		xray.ClientTraffic{Email: "keep@x", Enable: true},
+		xray.ClientTraffic{Email: "drop@x", Enable: true}), false, false); err != nil {
+		t.Fatalf("seed sync: %v", err)
+	}
+	if n := linkCount(t, db, "drop@x"); n != 1 {
+		t.Fatalf("setup: drop@x links=%d, want 1", n)
+	}
+
+	// Node now reports only keep@x — drop@x was genuinely removed there.
+	keepOnlySettings := `{"clients":[{"email":"keep@x","enable":true}]}`
+	if _, err := svc.setRemoteTrafficLocked(1, snapshotWithClients(t, "n1-in", keepOnlySettings,
+		xray.ClientTraffic{Email: "keep@x", Enable: true}), false, false); err != nil {
+		t.Fatalf("partial-snapshot sync: %v", err)
+	}
+
+	if n := linkCount(t, db, "keep@x"); n != 1 {
+		t.Fatalf("partial snapshot dropped a reported client: keep@x links=%d, want 1", n)
+	}
+	if n := linkCount(t, db, "drop@x"); n != 0 {
+		t.Fatalf("partial snapshot kept an unreported client linked: drop@x links=%d, want 0", n)
+	}
+	if at := readOrphanMark(t, db, "drop@x"); at <= 0 {
+		t.Fatalf("partial snapshot did not orphan-mark the removed client: sync_orphaned_at=%d, want >0", at)
+	}
+}
+
+// Keeping the hub's settings is not recovery: the node is only healed once the
+// hub actually re-pushes them, which needs a dirty node and a stale fingerprint.
+func TestSetRemoteTraffic_EmptySnapshotRepushesHubClients(t *testing.T) {
+	db := initTrafficTestDB(t)
+	svc := &InboundService{}
+
+	var mu sync.Mutex
+	var pushed []string
+	writeOK := func(w http.ResponseWriter, obj any) {
+		w.Header().Set("Content-Type", "application/json")
+		_ = json.NewEncoder(w).Encode(map[string]any{"success": true, "msg": "", "obj": obj})
+	}
+	mux := http.NewServeMux()
+	mux.HandleFunc("/panel/api/inbounds/list", func(w http.ResponseWriter, _ *http.Request) {
+		writeOK(w, []map[string]any{{"id": 7, "tag": "deg-in", "port": 41001, "protocol": "vless"}})
+	})
+	mux.HandleFunc("/panel/api/inbounds/update/", func(w http.ResponseWriter, r *http.Request) {
+		if err := r.ParseForm(); err != nil {
+			http.Error(w, err.Error(), http.StatusBadRequest)
+			return
+		}
+		mu.Lock()
+		pushed = append(pushed, r.PostForm.Get("settings"))
+		mu.Unlock()
+		writeOK(w, nil)
+	})
+	ts := httptest.NewServer(mux)
+	t.Cleanup(ts.Close)
+
+	node := reconcileTestNode(t, ts, "deg-node", "all", nil)
+	settings := `{"clients":[{"email":"svc@x","enable":true,"id":"11111111-1111-1111-1111-111111111111"}]}`
+	nid := node.Id
+	if err := db.Create(&model.Inbound{UserId: 1, Tag: "deg-in", Enable: true, Port: 41001, Protocol: model.VLESS, NodeID: &nid, Settings: settings}).Error; err != nil {
+		t.Fatalf("create inbound: %v", err)
+	}
+	rt := runtime.NewRemote(node, nil)
+	mgr := runtime.NewManager(runtime.LocalDeps{})
+	mgr.SetRuntimeOverride(node.Id, rt)
+	runtime.SetManager(mgr)
+	t.Cleanup(func() { runtime.SetManager(nil) })
+
+	if _, err := svc.setRemoteTrafficLocked(node.Id, snapshotWithClients(t, "deg-in", settings,
+		xray.ClientTraffic{Email: "svc@x", Enable: true}), false, false); err != nil {
+		t.Fatalf("seed sync: %v", err)
+	}
+	if err := svc.ReconcileNode(context.Background(), rt, node); err != nil {
+		t.Fatalf("first reconcile: %v", err)
+	}
+	mu.Lock()
+	pushed = nil
+	mu.Unlock()
+
+	if _, err := svc.setRemoteTrafficLocked(node.Id, snapshotWithoutClients(t, "deg-in"), false, false); err != nil {
+		t.Fatalf("empty-snapshot sync: %v", err)
+	}
+	var after model.Node
+	if err := db.Where("id = ?", node.Id).First(&after).Error; err != nil {
+		t.Fatalf("reload node: %v", err)
+	}
+	if !after.ConfigDirty {
+		t.Fatal("empty snapshot left the node clean: the job never reconciles it, so the node stays without its clients")
+	}
+	if err := svc.ReconcileNode(context.Background(), rt, &after); err != nil {
+		t.Fatalf("reconcile after empty snapshot: %v", err)
+	}
+	mu.Lock()
+	defer mu.Unlock()
+	if len(pushed) != 1 || !strings.Contains(pushed[0], "svc@x") {
+		t.Fatalf("reconcile after empty snapshot pushed %d settings payload(s) %q, want one carrying svc@x", len(pushed), pushed)
+	}
+}
+
+// The traffic a client used while its node reported nothing must still count
+// once the node reports it again.
+func TestSetRemoteTraffic_EmptySnapshotKeepsTrafficBaseline(t *testing.T) {
+	db := initTrafficTestDB(t)
+	svc := &InboundService{}
+
+	seedNodeRow(t, db, &model.Node{Id: 1, Name: "n1", Address: "127.0.0.1", Port: 2096, ApiToken: "tok", Enable: true})
+	createNodeInboundWithClient(t, db, 1, "n1-in", 41001, "svc@x")
+	settings := `{"clients":[{"email":"svc@x","enable":true}]}`
+	for _, used := range []int64{100, 200} {
+		syncNodeWithSettings(t, svc, 1, "n1-in", settings, xray.ClientTraffic{Email: "svc@x", Up: used, Down: used, Enable: true})
+	}
+	before := readTraffic(t, db, "svc@x")
+
+	if _, err := svc.setRemoteTrafficLocked(1, snapshotWithoutClients(t, "n1-in"), false, false); err != nil {
+		t.Fatalf("empty-snapshot sync: %v", err)
+	}
+	syncNodeWithSettings(t, svc, 1, "n1-in", settings, xray.ClientTraffic{Email: "svc@x", Up: 250, Down: 250, Enable: true})
+
+	assertUpDown(t, readTraffic(t, db, "svc@x"), before.Up+50, before.Down+50, "after the node recovered")
+}

internal/web/service/node_detached_client_stats_test.go

@@ -0,0 +1,61 @@
+package service
+
+import (
+	"errors"
+	"testing"
+
+	"gorm.io/gorm"
+
+	"github.com/mhsanaei/3x-ui/v3/internal/database/model"
+	"github.com/mhsanaei/3x-ui/v3/internal/xray"
+)
+
+// A node detach keeps the client's stat row (keepTraffic), so the node goes on
+// reporting it under an inbound whose settings no longer list the client (#6724).
+func TestNodeSnapshotIgnoresStatsOfClientDetachedFromInbound(t *testing.T) {
+	const gib = int64(1) << 30
+	const emptyClients = `{"clients": []}`
+
+	t.Run("stale node quota and disable never reach the master row", func(t *testing.T) {
+		db := initTrafficTestDB(t)
+		createNodeInbound(t, db, 1, "n1-in", 41001)
+		local := &model.Inbound{UserId: 1, Tag: "local-in", Enable: true, Port: 41010, Protocol: model.VLESS}
+		if err := db.Create(local).Error; err != nil {
+			t.Fatalf("create local inbound: %v", err)
+		}
+		const email = "moved"
+		if err := db.Create(&xray.ClientTraffic{InboundId: local.Id, Email: email, Enable: true, Total: 200 * gib, Up: 5, Down: 5}).Error; err != nil {
+			t.Fatalf("seed client_traffics: %v", err)
+		}
+		if err := db.Create(&model.NodeClientTraffic{NodeId: 1, Email: email, Up: 40, Down: 40}).Error; err != nil {
+			t.Fatalf("seed node baseline: %v", err)
+		}
+
+		svc := &InboundService{}
+		// Two ticks: the first copies the quota, which makes the second's disable look genuine.
+		for range 2 {
+			syncNodeWithSettings(t, svc, 1, "n1-in", emptyClients,
+				xray.ClientTraffic{Email: email, Up: 40, Down: 40, Total: 100 * gib, Enable: false})
+		}
+
+		got := readTraffic(t, db, email)
+		if got.Total != 200*gib || !got.Enable {
+			t.Fatalf("master row = total %d enable %v, want total %d enable true", got.Total, got.Enable, 200*gib)
+		}
+	})
+
+	t.Run("a detached email gets no master traffic row", func(t *testing.T) {
+		db := initTrafficTestDB(t)
+		createNodeInbound(t, db, 1, "n1-in", 41001)
+
+		svc := &InboundService{}
+		syncNodeWithSettings(t, svc, 1, "n1-in", emptyClients,
+			xray.ClientTraffic{Email: "gone", Up: 40, Down: 40, Total: 100 * gib, Enable: true})
+
+		var ct xray.ClientTraffic
+		err := db.Model(xray.ClientTraffic{}).Where("email = ?", "gone").First(&ct).Error
+		if !errors.Is(err, gorm.ErrRecordNotFound) {
+			t.Fatalf("client_traffics row for detached email: err = %v, row = %+v; want ErrRecordNotFound", err, ct)
+		}
+	})
+}

internal/web/websocket/hub.go

@@ -94,10 +94,12 @@ func NewHub() *Hub {
 	}
 }
 
+// Traffic messages carry independent partial updates from Xray, TUIC, and node
+// polling jobs. Throttling by message type would silently discard one source
+// when two jobs publish within the throttle window.
 var throttledMessageTypes = map[MessageType]struct{}{
 	MessageTypeInbounds:    {},
 	MessageTypeOutbounds:   {},
-	MessageTypeTraffic:     {},
 	MessageTypeClientStats: {},
 }
 

internal/web/websocket/hub_test.go

@@ -81,21 +81,45 @@ func TestHub_BroadcastDeliversToClient(t *testing.T) {
 	waitClientCount(t, h, 1)
 
 	h.Broadcast(MessageTypeStatus, map[string]string{"k": "v"})
-
 	select {
 	case raw := <-c.Send:
-		var m Message
-		if err := json.Unmarshal(raw, &m); err != nil {
-			t.Fatalf("payload is not valid JSON: %v\n%s", err, raw)
+		var message Message
+		if err := json.Unmarshal(raw, &message); err != nil {
+			t.Fatalf("payload is not valid JSON: %v", err)
 		}
-		if m.Type != MessageTypeStatus {
-			t.Fatalf("Type = %q, want %q", m.Type, MessageTypeStatus)
+		if message.Type != MessageTypeStatus {
+			t.Fatalf("message type = %q, want %q", message.Type, MessageTypeStatus)
 		}
-		if m.Time == 0 {
+		if message.Time == 0 {
 			t.Fatal("Time should be set to a non-zero unix-millis value")
 		}
 	case <-time.After(500 * time.Millisecond):
-		t.Fatal("timed out waiting for broadcast to reach client")
+		t.Fatal("timed out waiting for status broadcast to reach client")
+	}
+
+	for _, source := range []string{"tuic", "xray"} {
+		h.Broadcast(MessageTypeTraffic, map[string]string{"source": source})
+	}
+
+	for _, wantSource := range []string{"tuic", "xray"} {
+		select {
+		case raw := <-c.Send:
+			var message struct {
+				Type    MessageType       `json:"type"`
+				Payload map[string]string `json:"payload"`
+			}
+			if err := json.Unmarshal(raw, &message); err != nil {
+				t.Fatalf("traffic event is not valid JSON: %v", err)
+			}
+			if message.Type != MessageTypeTraffic {
+				t.Fatalf("message type = %q, want %q", message.Type, MessageTypeTraffic)
+			}
+			if got := message.Payload["source"]; got != wantSource {
+				t.Fatalf("traffic source = %q, want %q", got, wantSource)
+			}
+		case <-time.After(500 * time.Millisecond):
+			t.Fatalf("timed out waiting for %q traffic event", wantSource)
+		}
 	}
 }
 
@@ -156,23 +180,28 @@ func TestHub_ShouldThrottle(t *testing.T) {
 		t.Fatal("non-gated message type should never throttle on second call")
 	}
 
-	if h.shouldThrottle(MessageTypeTraffic) {
+	if h.shouldThrottle(MessageTypeInbounds) {
 		t.Fatal("first call for gated type should not throttle")
 	}
-	if !h.shouldThrottle(MessageTypeTraffic) {
+	if !h.shouldThrottle(MessageTypeInbounds) {
 		t.Fatal("immediate second call for gated type should throttle")
 	}
+	for i := range 2 {
+		if h.shouldThrottle(MessageTypeTraffic) {
+			t.Fatalf("traffic event %d must not be throttled", i+1)
+		}
+	}
 }
 
 func TestHub_ShouldThrottle_DistinctTypesIndependent(t *testing.T) {
 	h := NewHub()
 	defer h.Stop()
 
-	if h.shouldThrottle(MessageTypeTraffic) {
-		t.Fatal("first Traffic call should not throttle")
-	}
 	if h.shouldThrottle(MessageTypeInbounds) {
-		t.Fatal("first Inbounds call should not throttle even after Traffic")
+		t.Fatal("first Inbounds call should not throttle")
+	}
+	if h.shouldThrottle(MessageTypeOutbounds) {
+		t.Fatal("first Outbounds call should not throttle even after Inbounds")
 	}
 }
 

update.sh

@@ -940,6 +940,180 @@ setup_fail2ban() {
     return 0
 }
 
+# The hardened unit makes /usr, /boot, /efi and /etc read-only. The panel's own
+# updater is expected to escape that sandbox by running this script through a
+# transient systemd-run unit; when systemd-run is unavailable it starts this
+# script as a plain child instead, and that child inherits the sandbox and then
+# cannot write anything this update needs. Say so once, up front, instead of
+# dying partway through with "Failed to download x-ui".
+require_writable_update_paths() {
+    local dir probe
+    for dir in "${xui_folder%/*}" "/usr/bin"; do
+        [[ -n "$dir" && -d "$dir" ]] || continue
+        probe="${dir}/.x-ui-write-test.$$"
+        # A real write test rather than [[ -w ]]: this runs as root, where a
+        # permission bit means little and the test only reflects the file mode
+        # and the mount flags, not an immutable attribute or a full filesystem.
+        if ! : > "$probe" 2> /dev/null; then
+            _fail "ERROR: ${dir} is not writable for this process (read-only mount, attribute or full filesystem). The panel's fallback updater cannot run inside the hardened systemd sandbox; update from the panel UI (which uses systemd-run) or run 'x-ui update' in a shell."
+        fi
+        rm -f "$probe"
+    done
+}
+
+# Major version of the local systemd, 0 when it cannot be determined. The
+# SystemCallFilter=@system-service group only exists from systemd 239 on (other
+# @-named groups exist since 231); on older versions an unknown group is not
+# ignored safely, the filter stays in force and leaves a whitelist the panel
+# cannot run under.
+_xui_systemd_major_version() {
+    local version=""
+    if command -v systemctl > /dev/null 2>&1; then
+        version="$(systemctl --version 2>/dev/null | awk 'NR == 1 {print $2}')"
+    fi
+    if [[ ! "$version" =~ ^[0-9]+$ ]]; then
+        echo 0
+        return 0
+    fi
+    echo "$version"
+}
+
+# The shipped units list hardening that older systemd does not know: the
+# directive is logged and ignored at load time rather than rejected, so the
+# panel still starts, only without that protection. Each entry is the systemd
+# release that introduced the directive (systemd.exec(5)); everything else in
+# the unit predates the oldest systemd install.sh supports (CentOS 7 has 219).
+# SystemCallFilter= is listed because the drop-in only writes it from 239 on.
+_xui_warn_unsupported_hardening() {
+    local version entry missing=""
+    version="$(_xui_systemd_major_version)"
+    [[ "$version" -gt 0 ]] || return 0
+    for entry in RestrictRealtime:231 ReadWritePaths:231 ProtectKernelTunables:232 \
+        ProtectKernelModules:232 RestrictNamespaces:233 LockPersonality:235 \
+        SystemCallFilter:239 ProtectHostname:242 RestrictSUIDSGID:242 \
+        ProtectKernelLogs:244 ProtectClock:245; do
+        if [[ "$version" -lt "${entry##*:}" ]]; then
+            missing="${missing:+$missing, }${entry%%:*} (${entry##*:})"
+        fi
+    done
+    [[ -n "$missing" ]] || return 0
+    echo -e "${yellow}Note: systemd ${version} ignores part of the hardening in x-ui.service; the panel still starts.${plain}"
+    echo "      Not applied, needs a newer systemd: ${missing}."
+    if [[ "$version" -lt 231 ]]; then
+        echo "      The panel's folders stay writable through ReadWriteDirectories=, the alias this script installs."
+    fi
+    echo "      The rest of the hardening is in force. Upgrade systemd to apply the above."
+    return 0
+}
+
+# ProtectSystem=full makes /usr, /boot, /efi and /etc read-only. ProtectSystem=
+# strict would make the whole hierarchy read-only (only the kernel API
+# filesystems stay as they are), and that would break the panel's own use of
+# /tmp. The panel's stores are configurable (XUI_DB_FOLDER, XUI_LOG_FOLDER,
+# XUI_BIN_FOLDER), and XUI_MAIN_FOLDER is the folder install.sh/update.sh place
+# the files in -- the unit's WorkingDirectory on a stock install, and what a
+# relative XUI_BIN_FOLDER is resolved against. So a hard-coded list in the unit
+# either misses a relocated store -- the panel then cannot write its own SQLite
+# database and sits in a Restart=on-failure loop -- or forces the operator to
+# edit a file that every install/update overwrites from the release tarball.
+# install.sh and update.sh therefore regenerate the drop-in from the folders
+# actually in use, and the unit's own ReadWritePaths only carry the
+# plain-install defaults. A relocated store means re-running install or update:
+# the drop-in is only written here.
+_xui_service_write_paths_dropin() {
+    # $1 is the env file to resolve the XUI_* folders from; callers pass nothing
+    # and get the OS-specific path the unit itself uses.
+    local env_file="${1:-}"
+    local dropin_dir dropin temp_file
+    local db_folder log_folder bin_folder main_folder
+    local path line="" whitespace_paths="" seen_paths="" escaped_path
+
+    if [[ -z "$env_file" ]]; then
+        env_file="$(xui_env_file_path)"
+    fi
+    if [[ -r "$env_file" ]]; then
+        set -a
+        # shellcheck disable=SC1090
+        source "$env_file"
+        set +a
+    fi
+
+    # XUI_* wins over the script's own default: the unit hands that same env
+    # file to the panel through EnvironmentFile=, so these are the folders it
+    # will actually use.
+    main_folder="${XUI_MAIN_FOLDER:-${xui_folder}}"
+    db_folder="${XUI_DB_FOLDER:-/etc/x-ui}"
+    log_folder="${XUI_LOG_FOLDER:-/var/log/x-ui}"
+    # An empty XUI_BIN_FOLDER resolves to "bin" relative to the panel's working
+    # directory, which the unit sets to the main folder.
+    bin_folder="${XUI_BIN_FOLDER:-bin}"
+    if [[ "$bin_folder" != /* ]]; then
+        bin_folder="${main_folder%/}/${bin_folder#./}"
+    fi
+
+    for path in "$db_folder" "$log_folder" "$bin_folder" "$main_folder"; do
+        [[ "$path" == /* ]] || continue
+        # ReadWritePaths= is a whitespace-separated list, and a folder whose
+        # name contains whitespace cannot be written into it without relying on
+        # quoting. A wrong entry makes systemd reject the whole drop-in and the
+        # panel would not start, so leave such a folder out and say so instead.
+        if [[ "$path" != "${path//[[:space:]]/}" ]]; then
+            whitespace_paths="${whitespace_paths:+$whitespace_paths }$path"
+            continue
+        fi
+        case " $seen_paths " in
+            *" $path "*) continue ;;
+        esac
+        seen_paths="${seen_paths}${seen_paths:+ }$path"
+        # systemd expands %-specifiers in unit files, so a folder name carrying
+        # a literal % has to be written as %%, or the entry stops naming the
+        # folder systemd is meant to keep writable.
+        escaped_path="${path//%/%%}"
+        line="${line} -${escaped_path}"
+    done
+    if [[ -n "$whitespace_paths" ]]; then
+        echo "Warning: these folders contain whitespace and were left out of" >&2
+        echo "         10-xui-sandbox.conf: $whitespace_paths" >&2
+        echo "         The panel cannot write to them under the unit's sandbox." >&2
+    fi
+    line="${line# }"
+    [[ -n "$line" ]] || return 1
+
+    dropin_dir="${xui_service}/x-ui.service.d"
+    dropin="${dropin_dir}/10-xui-sandbox.conf"
+    temp_file="${dropin}.tmp.$$"
+
+    mkdir -p "$dropin_dir" || return 1
+    cat > "$temp_file" << EOF
+# Regenerated by install.sh/update.sh on every install and update: edits here
+# are lost, and the list only reflects the XUI_* variables read from
+# ${env_file} at that moment. Re-run install/update after moving a store.
+# It lists the folders the panel writes to. Put local additions in their own
+# drop-in, for example 20-x-ui-local.conf, which nothing here touches.
+[Service]
+ReadWritePaths=${line}
+ReadWriteDirectories=${line}
+EOF
+    if [[ "$(_xui_systemd_major_version)" -ge 239 ]]; then
+        cat >> "$temp_file" << 'EOF'
+# @system-service needs systemd >= 239; on older versions the unknown group
+# would leave the panel with a filter it cannot start under (x-ui.service.*).
+SystemCallFilter=@system-service
+SystemCallErrorNumber=EPERM
+EOF
+    fi
+    if [[ ! -s "$temp_file" ]]; then
+        rm -f "$temp_file"
+        return 1
+    fi
+    chmod 644 "$temp_file"
+    mv -f "$temp_file" "$dropin" || { rm -f "$temp_file"; return 1; }
+    if command -v systemctl > /dev/null 2>&1; then
+        systemctl daemon-reload > /dev/null 2>&1 || true
+    fi
+    return 0
+}
+
 # Lands a systemd unit file at ${xui_service}/x-ui.service via a temp file +
 # atomic mv, so a failed cp/curl or an interrupted mv never leaves a
 # truncated unit file at the live path -- systemd would then fail to parse
@@ -971,6 +1145,11 @@ _install_xui_service_unit() {
         rm -f "$temp_file"
         return 1
     fi
+    if ! _xui_service_write_paths_dropin; then
+        echo -e "${yellow}Warning: could not refresh ${xui_service}/x-ui.service.d/10-xui-sandbox.conf.${plain}"
+        echo -e "${yellow}If XUI_DB_FOLDER or XUI_LOG_FOLDER points outside /etc/x-ui and /var/log/x-ui, the panel may not be able to write to it under ProtectSystem=full.${plain}"
+    fi
+    _xui_warn_unsupported_hardening
     return 0
 }
 
@@ -1171,6 +1350,11 @@ update_x-ui() {
         chmod 640 ${xui_folder}/bin/config.json > /dev/null 2>&1
     fi
 
+    # Finish the schema/data migrations before the service starts, so the service and
+    # config_after_update's CLI calls never run them on the same database at once (#6728).
+    echo -e "${green}Migrating database...${plain}"
+    "${xui_folder}/x-ui" migrate
+
     if [[ $release == "alpine" ]]; then
         echo -e "${green}Downloading and installing startup unit x-ui.rc...${plain}"
         xui_rc_temp="/etc/init.d/x-ui.tmp.$$"
@@ -1287,5 +1471,6 @@ update_x-ui() {
 }
 
 echo -e "${green}Running...${plain}"
+require_writable_update_paths
 install_base
 update_x-ui $1

x-ui.service.arch

@@ -15,5 +15,81 @@ ExecReload=/bin/kill -USR1 $MAINPID
 Restart=on-failure
 RestartSec=5s
 
+# The panel intentionally stays root: it supervises the Xray child processes,
+# edits netfilter state and reads TLS private keys. These settings only bound
+# what a panel-level flaw can reach.
+#
+# PrivateTmp=yes is deliberately absent: the web updater writes its script into
+# /tmp and hands the absolute path to a "systemd-run" transient unit, which
+# does not share this service's private /tmp (the download would vanish).
+NoNewPrivileges=yes
+ProtectSystem=full
+# Default stores: DB/update status/node-token in XUI_DB_FOLDER (/etc/x-ui),
+# xray binary/config/geo in XUI_BIN_FOLDER under /usr/local/x-ui, logs in
+# XUI_LOG_FOLDER (/var/log/x-ui). These are the plain-install defaults and the
+# floor, not the whole list: install.sh and update.sh regenerate a drop-in
+# (x-ui.service.d/10-xui-sandbox.conf) with the folders resolved from the XUI_*
+# variables, so a relocated XUI_DB_FOLDER or XUI_LOG_FOLDER stays writable and
+# the list survives an update instead of being reset to these defaults. Changing
+# one of those variables in the env file is not enough by itself: the drop-in has
+# to be refreshed as well, i.e. install or update the panel again.
+# Add local extras in your own drop-in (e.g. 20-local.conf).
+# The leading '-' keeps the unit startable if a path does not exist yet.
+# What ProtectSystem=full covers, precisely: /usr, /boot, /efi and /etc become
+# read-only, everything else stays writable. So this list matters for stores
+# under those trees -- the default main folder under /usr/local is one.
+#
+# The in-panel updater is expected to leave this sandbox: it runs update.sh
+# through a transient systemd-run unit, which does not inherit these settings.
+# Its plain-child fallback (taken when systemd-run is unavailable) cannot work
+# here -- update.sh stages the release archive beside the main folder, replaces
+# /usr/bin/x-ui and calls the package manager -- so it stops with one clear
+# message instead of failing halfway, and the sandbox deliberately does not
+# grant /usr or /etc to accommodate it.
+# ReadWritePaths= requires systemd >= 231; ReadWriteDirectories= is the deprecated
+# alias for older systemd, needed so ProtectSystem=full keeps /etc/x-ui writable.
+ReadWritePaths=-/etc/x-ui -/usr/local/x-ui -/var/log/x-ui
+ReadWriteDirectories=-/etc/x-ui -/usr/local/x-ui -/var/log/x-ui
+ProtectKernelTunables=yes
+ProtectKernelModules=yes
+ProtectKernelLogs=yes
+ProtectClock=yes
+ProtectHostname=yes
+# read-only rather than yes: installs keep TLS certs under /root/cert, and the
+# panel must still be able to read them.
+ProtectHome=read-only
+LockPersonality=yes
+RestrictRealtime=yes
+RestrictSUIDSGID=yes
+RestrictNamespaces=yes
+UMask=0077
+# AF_NETLINK for interface/route lookups and the ip(8) child used by the
+# AmneziaWG IPv6-alias feature.
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK
+# NET_ADMIN for ip(8)/tproxy, NET_BIND_SERVICE for ports below 1024, NET_RAW
+# for raw sockets and SO_BINDTODEVICE.
+#
+# DAC_OVERRIDE has to stay. The panel runs as root, but a bounding set is
+# subtracted from root's own privileges too: without it root can only read a
+# file when the owner/group/other bits let uid 0 through, and any TLS private
+# key belonging to another account becomes unreadable -- a certificate issued to
+# Caddy, an acme.sh home, any 0600 file that root does not own. TLS then fails
+# quietly: the panel listener catches the tls.LoadX509KeyPair error, logs it and
+# keeps serving plain HTTP, and every Xray inbound using that key stops. Those
+# reads worked before the sandbox because the panel is root.
+# DAC_READ_SEARCH is deliberately absent: directory search is already covered by
+# DAC_OVERRIDE, so it would only widen the set without adding anything.
+CapabilityBoundingSet=CAP_DAC_OVERRIDE CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_NET_RAW
+SystemCallArchitectures=native
+# No seccomp whitelist here on purpose. @system-service needs systemd >= 239
+# (other @-named groups exist since 231), and older systemd does not ignore an
+# unknown group name gracefully: on
+# <231 the name fails to resolve and the filter stays the built-in whitelist of
+# execve/exit/exit_group/rt_sigreturn/sigreturn, on 231..238 it degrades to
+# @default -- either way the panel then gets EPERM on read/openat/mmap/clone and
+# cannot start. install.sh and update.sh add SystemCallFilter=@system-service and
+# SystemCallErrorNumber=EPERM to the generated drop-in, but only when
+# "systemctl --version" reports 239 or newer.
+
 [Install]
 WantedBy=multi-user.target

x-ui.service.debian

@@ -15,5 +15,81 @@ ExecReload=/bin/kill -USR1 $MAINPID
 Restart=on-failure
 RestartSec=5s
 
+# The panel intentionally stays root: it supervises the Xray child processes,
+# edits netfilter state and reads TLS private keys. These settings only bound
+# what a panel-level flaw can reach.
+#
+# PrivateTmp=yes is deliberately absent: the web updater writes its script into
+# /tmp and hands the absolute path to a "systemd-run" transient unit, which
+# does not share this service's private /tmp (the download would vanish).
+NoNewPrivileges=yes
+ProtectSystem=full
+# Default stores: DB/update status/node-token in XUI_DB_FOLDER (/etc/x-ui),
+# xray binary/config/geo in XUI_BIN_FOLDER under /usr/local/x-ui, logs in
+# XUI_LOG_FOLDER (/var/log/x-ui). These are the plain-install defaults and the
+# floor, not the whole list: install.sh and update.sh regenerate a drop-in
+# (x-ui.service.d/10-xui-sandbox.conf) with the folders resolved from the XUI_*
+# variables, so a relocated XUI_DB_FOLDER or XUI_LOG_FOLDER stays writable and
+# the list survives an update instead of being reset to these defaults. Changing
+# one of those variables in the env file is not enough by itself: the drop-in has
+# to be refreshed as well, i.e. install or update the panel again.
+# Add local extras in your own drop-in (e.g. 20-local.conf).
+# The leading '-' keeps the unit startable if a path does not exist yet.
+# What ProtectSystem=full covers, precisely: /usr, /boot, /efi and /etc become
+# read-only, everything else stays writable. So this list matters for stores
+# under those trees -- the default main folder under /usr/local is one.
+#
+# The in-panel updater is expected to leave this sandbox: it runs update.sh
+# through a transient systemd-run unit, which does not inherit these settings.
+# Its plain-child fallback (taken when systemd-run is unavailable) cannot work
+# here -- update.sh stages the release archive beside the main folder, replaces
+# /usr/bin/x-ui and calls the package manager -- so it stops with one clear
+# message instead of failing halfway, and the sandbox deliberately does not
+# grant /usr or /etc to accommodate it.
+# ReadWritePaths= requires systemd >= 231; ReadWriteDirectories= is the deprecated
+# alias for older systemd, needed so ProtectSystem=full keeps /etc/x-ui writable.
+ReadWritePaths=-/etc/x-ui -/usr/local/x-ui -/var/log/x-ui
+ReadWriteDirectories=-/etc/x-ui -/usr/local/x-ui -/var/log/x-ui
+ProtectKernelTunables=yes
+ProtectKernelModules=yes
+ProtectKernelLogs=yes
+ProtectClock=yes
+ProtectHostname=yes
+# read-only rather than yes: installs keep TLS certs under /root/cert, and the
+# panel must still be able to read them.
+ProtectHome=read-only
+LockPersonality=yes
+RestrictRealtime=yes
+RestrictSUIDSGID=yes
+RestrictNamespaces=yes
+UMask=0077
+# AF_NETLINK for interface/route lookups and the ip(8) child used by the
+# AmneziaWG IPv6-alias feature.
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK
+# NET_ADMIN for ip(8)/tproxy, NET_BIND_SERVICE for ports below 1024, NET_RAW
+# for raw sockets and SO_BINDTODEVICE.
+#
+# DAC_OVERRIDE has to stay. The panel runs as root, but a bounding set is
+# subtracted from root's own privileges too: without it root can only read a
+# file when the owner/group/other bits let uid 0 through, and any TLS private
+# key belonging to another account becomes unreadable -- a certificate issued to
+# Caddy, an acme.sh home, any 0600 file that root does not own. TLS then fails
+# quietly: the panel listener catches the tls.LoadX509KeyPair error, logs it and
+# keeps serving plain HTTP, and every Xray inbound using that key stops. Those
+# reads worked before the sandbox because the panel is root.
+# DAC_READ_SEARCH is deliberately absent: directory search is already covered by
+# DAC_OVERRIDE, so it would only widen the set without adding anything.
+CapabilityBoundingSet=CAP_DAC_OVERRIDE CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_NET_RAW
+SystemCallArchitectures=native
+# No seccomp whitelist here on purpose. @system-service needs systemd >= 239
+# (other @-named groups exist since 231), and older systemd does not ignore an
+# unknown group name gracefully: on
+# <231 the name fails to resolve and the filter stays the built-in whitelist of
+# execve/exit/exit_group/rt_sigreturn/sigreturn, on 231..238 it degrades to
+# @default -- either way the panel then gets EPERM on read/openat/mmap/clone and
+# cannot start. install.sh and update.sh add SystemCallFilter=@system-service and
+# SystemCallErrorNumber=EPERM to the generated drop-in, but only when
+# "systemctl --version" reports 239 or newer.
+
 [Install]
 WantedBy=multi-user.target

x-ui.service.rhel

@@ -15,5 +15,81 @@ ExecReload=/bin/kill -USR1 $MAINPID
 Restart=on-failure
 RestartSec=5s
 
+# The panel intentionally stays root: it supervises the Xray child processes,
+# edits netfilter state and reads TLS private keys. These settings only bound
+# what a panel-level flaw can reach.
+#
+# PrivateTmp=yes is deliberately absent: the web updater writes its script into
+# /tmp and hands the absolute path to a "systemd-run" transient unit, which
+# does not share this service's private /tmp (the download would vanish).
+NoNewPrivileges=yes
+ProtectSystem=full
+# Default stores: DB/update status/node-token in XUI_DB_FOLDER (/etc/x-ui),
+# xray binary/config/geo in XUI_BIN_FOLDER under /usr/local/x-ui, logs in
+# XUI_LOG_FOLDER (/var/log/x-ui). These are the plain-install defaults and the
+# floor, not the whole list: install.sh and update.sh regenerate a drop-in
+# (x-ui.service.d/10-xui-sandbox.conf) with the folders resolved from the XUI_*
+# variables, so a relocated XUI_DB_FOLDER or XUI_LOG_FOLDER stays writable and
+# the list survives an update instead of being reset to these defaults. Changing
+# one of those variables in the env file is not enough by itself: the drop-in has
+# to be refreshed as well, i.e. install or update the panel again.
+# Add local extras in your own drop-in (e.g. 20-local.conf).
+# The leading '-' keeps the unit startable if a path does not exist yet.
+# What ProtectSystem=full covers, precisely: /usr, /boot, /efi and /etc become
+# read-only, everything else stays writable. So this list matters for stores
+# under those trees -- the default main folder under /usr/local is one.
+#
+# The in-panel updater is expected to leave this sandbox: it runs update.sh
+# through a transient systemd-run unit, which does not inherit these settings.
+# Its plain-child fallback (taken when systemd-run is unavailable) cannot work
+# here -- update.sh stages the release archive beside the main folder, replaces
+# /usr/bin/x-ui and calls the package manager -- so it stops with one clear
+# message instead of failing halfway, and the sandbox deliberately does not
+# grant /usr or /etc to accommodate it.
+# ReadWritePaths= requires systemd >= 231; ReadWriteDirectories= is the deprecated
+# alias for older systemd, needed so ProtectSystem=full keeps /etc/x-ui writable.
+ReadWritePaths=-/etc/x-ui -/usr/local/x-ui -/var/log/x-ui
+ReadWriteDirectories=-/etc/x-ui -/usr/local/x-ui -/var/log/x-ui
+ProtectKernelTunables=yes
+ProtectKernelModules=yes
+ProtectKernelLogs=yes
+ProtectClock=yes
+ProtectHostname=yes
+# read-only rather than yes: installs keep TLS certs under /root/cert, and the
+# panel must still be able to read them.
+ProtectHome=read-only
+LockPersonality=yes
+RestrictRealtime=yes
+RestrictSUIDSGID=yes
+RestrictNamespaces=yes
+UMask=0077
+# AF_NETLINK for interface/route lookups and the ip(8) child used by the
+# AmneziaWG IPv6-alias feature.
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK
+# NET_ADMIN for ip(8)/tproxy, NET_BIND_SERVICE for ports below 1024, NET_RAW
+# for raw sockets and SO_BINDTODEVICE.
+#
+# DAC_OVERRIDE has to stay. The panel runs as root, but a bounding set is
+# subtracted from root's own privileges too: without it root can only read a
+# file when the owner/group/other bits let uid 0 through, and any TLS private
+# key belonging to another account becomes unreadable -- a certificate issued to
+# Caddy, an acme.sh home, any 0600 file that root does not own. TLS then fails
+# quietly: the panel listener catches the tls.LoadX509KeyPair error, logs it and
+# keeps serving plain HTTP, and every Xray inbound using that key stops. Those
+# reads worked before the sandbox because the panel is root.
+# DAC_READ_SEARCH is deliberately absent: directory search is already covered by
+# DAC_OVERRIDE, so it would only widen the set without adding anything.
+CapabilityBoundingSet=CAP_DAC_OVERRIDE CAP_NET_ADMIN CAP_NET_BIND_SERVICE CAP_NET_RAW
+SystemCallArchitectures=native
+# No seccomp whitelist here on purpose. @system-service needs systemd >= 239
+# (other @-named groups exist since 231), and older systemd does not ignore an
+# unknown group name gracefully: on
+# <231 the name fails to resolve and the filter stays the built-in whitelist of
+# execve/exit/exit_group/rt_sigreturn/sigreturn, on 231..238 it degrades to
+# @default -- either way the panel then gets EPERM on read/openat/mmap/clone and
+# cannot start. install.sh and update.sh add SystemCallFilter=@system-service and
+# SystemCallErrorNumber=EPERM to the generated drop-in, but only when
+# "systemctl --version" reports 239 or newer.
+
 [Install]
 WantedBy=multi-user.target

x-ui.sh

@@ -294,6 +294,12 @@ uninstall() {
         systemctl stop x-ui
         systemctl disable x-ui
         rm ${xui_service}/x-ui.service -f
+        # The sandbox drop-in generated by install.sh/update.sh lives beside the
+        # unit; leaving it behind would keep an empty x-ui.service.d around and
+        # silently re-apply on a later install of another unit of the same name.
+        # Local drop-ins the operator added go with it, which is what an
+        # uninstall is expected to do.
+        rm -rf -- "${xui_service}/x-ui.service.d"
         systemctl daemon-reload
         systemctl reset-failed
     fi