Authorization: Bearer <token> header below. Every endpoint
returns a uniform { success, msg, obj } envelope unless otherwise noted.
+
{{ tokenVisible ? (apiToken || '—') : (apiToken ? '••••••••••••••••••••••••••••' : '—') }}
-
- Send it on every request as Authorization: Bearer <token>. Token-authenticated
- callers skip CSRF and don't need a session cookie. Regenerating rotates the secret immediately —
- running bots will need the new value.
+ Create, enable, or revoke named Bearer tokens in
+ Settings → Security. Send each request as
+ Authorization: Bearer <token>. Token-authenticated callers skip CSRF and don't
+ need a session cookie. Deleting a token revokes it immediately — running bots will need a new one.
{{ curlExample }}
+ {{ section.description }}
-';
+ const close = '';
+ let out = '';
+ let i = 0;
+ while (i < input.length) {
+ const oIdx = input.indexOf(open, i);
+ if (oIdx === -1) {
+ out += escape(input.slice(i));
+ break;
+ }
+ out += escape(input.slice(i, oIdx));
+ const cIdx = input.indexOf(close, oIdx + open.length);
+ if (cIdx === -1) {
+ out += escape(input.slice(oIdx));
+ break;
+ }
+ out += '' + escape(input.slice(oIdx + open.length, cIdx)) + '';
+ i = cIdx + close.length;
+ }
+ return out;
+}
+
export const sections = [
{
- id: 'auth',
+ id: 'authentication',
title: 'Authentication',
description:
'Two authentication modes are supported. UI sessions use a cookie set by the login endpoint. Programmatic clients (bots, scripts, remote panels) authenticate with a Bearer token taken from Settings → Security → API Token. Both work for every endpoint under /panel/api/*.',
@@ -17,11 +42,14 @@ export const sections = [
body: '{\n "username": "admin",\n "password": "admin",\n "twoFactorCode": "123456"\n}',
response:
'{\n "success": true,\n "msg": "Logged in successfully"\n}',
+ errorResponse:
+ '{\n "success": false,\n "msg": "Wrong username or password"\n}',
},
{
- method: 'GET',
+ method: 'POST',
path: '/logout',
- summary: 'Clear the session cookie. Redirects back to the login page; not useful from non-browser clients.',
+ summary: 'Clear the session cookie. Requires the CSRF header for browser sessions.',
+ response: '{\n "success": true\n}',
},
{
method: 'GET',
@@ -41,9 +69,9 @@ export const sections = [
{
id: 'inbounds',
- title: 'Inbounds API',
+ title: 'Inbounds',
description:
- 'Manage inbound configurations and their clients. All endpoints live under /panel/api/inbounds and require a logged-in session or Bearer token. Link-generating endpoints honour X-Forwarded-Host / X-Forwarded-Proto, so callers behind a reverse proxy get the correct external host in returned URLs.',
+ 'Manage inbound configurations and their clients. All endpoints live under /panel/api/inbounds and require a logged-in session or Bearer token. Link-generating endpoints honour forwarded headers only when the request comes from a configured trusted proxy.',
endpoints: [
{
method: 'GET',
@@ -67,6 +95,7 @@ export const sections = [
params: [
{ name: 'email', in: 'path', type: 'string', desc: 'Client email (unique across the panel).' },
],
+ response: '{\n "success": true,\n "obj": {\n "email": "user1",\n "up": 1048576,\n "down": 2097152,\n "total": 10737418240,\n "expiryTime": 1735689600000\n }\n}',
},
{
method: 'GET',
@@ -75,6 +104,7 @@ export const sections = [
params: [
{ name: 'id', in: 'path', type: 'string', desc: 'Client subId / UUID.' },
],
+ response: '{\n "success": true,\n "obj": {\n "email": "user1",\n "up": 1048576,\n "down": 2097152,\n "total": 10737418240,\n "expiryTime": 1735689600000\n }\n}',
},
{
method: 'POST',
@@ -82,6 +112,8 @@ export const sections = [
summary: 'Create a new inbound. Send the full inbound payload (protocol, port, settings JSON, streamSettings JSON, sniffing JSON, remark, expiryTime, total, enable).',
body:
'{\n "enable": true,\n "remark": "VLESS-443",\n "listen": "",\n "port": 443,\n "protocol": "vless",\n "expiryTime": 0,\n "total": 0,\n "settings": "{\\"clients\\":[{\\"id\\":\\"...\\",\\"email\\":\\"user1\\"}],\\"decryption\\":\\"none\\",\\"fallbacks\\":[]}",\n "streamSettings": "{\\"network\\":\\"tcp\\",\\"security\\":\\"reality\\",\\"realitySettings\\":{...}}",\n "sniffing": "{\\"enabled\\":true,\\"destOverride\\":[\\"http\\",\\"tls\\"]}"\n}',
+ errorResponse:
+ '{\n "success": false,\n "msg": "Port 443 is already in use"\n}',
},
{
method: 'POST',
@@ -161,6 +193,14 @@ export const sections = [
body:
'{\n "id": 1,\n "settings": "{\\"clients\\":[{\\"id\\":\\"uuid-here\\",\\"email\\":\\"user1\\",\\"limitIp\\":2,\\"totalGB\\":10737418240,\\"expiryTime\\":1735689600000,\\"enable\\":true}]}"\n}',
},
+ {
+ method: 'POST',
+ path: '/panel/api/inbounds/:id/resetTraffic',
+ summary: 'Zero out upload + download counters for a single inbound. Does not touch per-client counters.',
+ params: [
+ { name: 'id', in: 'path', type: 'number', desc: 'Inbound ID.' },
+ ],
+ },
{
method: 'POST',
path: '/panel/api/inbounds/:id/resetClientTraffic/:email',
@@ -209,6 +249,7 @@ export const sections = [
method: 'POST',
path: '/panel/api/inbounds/lastOnline',
summary: 'Map of client email → last-seen unix timestamp.',
+ response: '{\n "success": true,\n "obj": [\n { "email": "user1", "lastOnline": 1700000000 },\n { "email": "user2", "lastOnline": 1699999000 }\n ]\n}',
},
{
method: 'GET',
@@ -256,7 +297,7 @@ export const sections = [
{
id: 'server',
- title: 'Server API',
+ title: 'Server',
description:
'System status, log retrieval, certificate generators, Xray binary management, and backup/restore. All under /panel/api/server.',
endpoints: [
@@ -264,6 +305,7 @@ export const sections = [
method: 'GET',
path: '/panel/api/server/status',
summary: 'Real-time machine snapshot: CPU, memory, swap, disk, network IO, load averages, open connections, Xray state. Cached and refreshed every 2 seconds in the background.',
+ response: '{\n "success": true,\n "obj": {\n "cpu": 12.5,\n "mem": { "current": 2147483648, "total": 8589934592 },\n "swap": { "current": 0, "total": 4294967296 },\n "disk": { "current": 53687091200, "total": 268435456000 },\n "netIO": { "up": 1073741824, "down": 2147483648 },\n "xray": { "state": "running", "version": "v25.10.31" },\n "tcpCount": 42,\n "load": { "load1": 0.5, "load5": 0.3, "load15": 0.2 }\n }\n}',
},
{
method: 'GET',
@@ -278,7 +320,36 @@ export const sections = [
path: '/panel/api/server/history/:metric/:bucket',
summary: 'Aggregated time-series for one metric. Returns an array of {t, v} samples covering the last ~6 hours.',
params: [
- { name: 'metric', in: 'path', type: 'string', desc: 'cpu | mem | swap | netIn | netOut | tcpCount | udpCount | load1 | online.' },
+ { name: 'metric', in: 'path', type: 'string', desc: 'cpu | mem | netUp | netDown | online | load1 | load5 | load15.' },
+ { name: 'bucket', in: 'path', type: 'number', desc: 'Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.' },
+ ],
+ response: '{\n "success": true,\n "obj": [\n { "t": 1700000000, "v": 12.5 },\n { "t": 1700000002, "v": 13.1 }\n ]\n}',
+ },
+ {
+ method: 'GET',
+ path: '/panel/api/server/xrayMetricsState',
+ summary: 'Xray runtime metrics state — whether the xray config has a `metrics` block, which expvar keys are flowing, and the current snapshot values for each. Returns an empty state when metrics are not configured.',
+ },
+ {
+ method: 'GET',
+ path: '/panel/api/server/xrayMetricsHistory/:metric/:bucket',
+ summary: 'Time-series history for one Xray runtime metric over the last ~6 hours. Same {t, v} shape as /history/:metric/:bucket.',
+ params: [
+ { name: 'metric', in: 'path', type: 'string', desc: 'xrAlloc | xrSys | xrHeapObjects | xrNumGC | xrPauseNs.' },
+ { name: 'bucket', in: 'path', type: 'number', desc: 'Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.' },
+ ],
+ },
+ {
+ method: 'GET',
+ path: '/panel/api/server/xrayObservatory',
+ summary: 'Latest snapshot from the Xray observatory — per-outbound latency, health status, and last-probe time. Only populated when the Xray config has an observatory configured.',
+ },
+ {
+ method: 'GET',
+ path: '/panel/api/server/xrayObservatoryHistory/:tag/:bucket',
+ summary: 'Time-series of observatory probe results for one outbound tag. Same {t, v} shape as the other history endpoints.',
+ params: [
+ { name: 'tag', in: 'path', type: 'string', desc: 'Outbound tag from the observatory config.' },
{ name: 'bucket', in: 'path', type: 'number', desc: 'Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.' },
],
},
@@ -286,6 +357,7 @@ export const sections = [
method: 'GET',
path: '/panel/api/server/getXrayVersion',
summary: 'List Xray binary versions available for install on this host.',
+ response: '{\n "success": true,\n "obj": ["v25.10.31", "v25.9.15", "v25.8.1"]\n}',
},
{
method: 'GET',
@@ -295,7 +367,8 @@ export const sections = [
{
method: 'GET',
path: '/panel/api/server/getConfigJson',
- summary: 'Return the assembled Xray config that’s currently running on this host.',
+ summary: 'Return the assembled Xray config that\u2019s currently running on this host.',
+ response: '{\n "success": true,\n "obj": {\n "log": { "loglevel": "warning" },\n "inbounds": [...],\n "outbounds": [...],\n "routing": { "rules": [...] }\n }\n}',
},
{
method: 'GET',
@@ -306,36 +379,45 @@ export const sections = [
method: 'GET',
path: '/panel/api/server/getNewUUID',
summary: 'Generate a fresh UUID v4. Convenience helper for client IDs.',
+ response: '{\n "success": true,\n "obj": "550e8400-e29b-41d4-a716-446655440000"\n}',
},
{
method: 'GET',
path: '/panel/api/server/getNewX25519Cert',
summary: 'Generate a new X25519 keypair for Reality.',
+ response: '{\n "success": true,\n "obj": {\n "privateKey": "uN9qLfV3zH8w...",\n "publicKey": "5v8xPqR2sM7k..."\n }\n}',
},
{
method: 'GET',
path: '/panel/api/server/getNewmldsa65',
summary: 'Generate a new ML-DSA-65 keypair (post-quantum signature). Returns {privateKey, publicKey, seed}.',
+ response: '{\n "success": true,\n "obj": {\n "privateKey": "mdsa65priv...",\n "publicKey": "mdsa65pub...",\n "seed": "random-seed..."\n }\n}',
},
{
method: 'GET',
path: '/panel/api/server/getNewmlkem768',
summary: 'Generate a new ML-KEM-768 keypair (post-quantum KEM). Returns {clientKey, serverKey}.',
+ response: '{\n "success": true,\n "obj": {\n "clientKey": "mlkem768-client...",\n "serverKey": "mlkem768-server..."\n }\n}',
},
{
method: 'GET',
path: '/panel/api/server/getNewVlessEnc',
- summary: 'Generate VLESS encryption auth options. Returns auths with id, label, decryption, and encryption.',
+ summary: 'Generate VLESS encryption auth options. Returns an auths array each with id, label, encryption, and decryption fields.',
+ response: '{\n "success": true,\n "obj": {\n "auths": [\n { "id": 0, "label": "Auth #0", "encryption": "aes-256-gcm", "decryption": "" }\n ]\n }\n}',
},
{
method: 'POST',
path: '/panel/api/server/stopXrayService',
summary: 'Stop the Xray binary. All proxies go offline immediately.',
+ errorResponse:
+ '{\n "success": false,\n "msg": "Xray is not running"\n}',
},
{
method: 'POST',
path: '/panel/api/server/restartXrayService',
summary: 'Reload Xray with the current config. Typically required after structural inbound or routing changes.',
+ errorResponse:
+ '{\n "success": false,\n "msg": "Xray config is invalid: ..."\n}',
},
{
method: 'POST',
@@ -354,6 +436,10 @@ export const sections = [
method: 'POST',
path: '/panel/api/server/updateGeofile',
summary: 'Refresh the default GeoIP / GeoSite data files. Body can include a fileName, or use the /:fileName variant.',
+ params: [
+ { name: 'fileName', in: 'body (form)', type: 'string', desc: 'Filename to update (e.g. geoip.dat, geosite.dat). Omit to update all defaults.' },
+ ],
+ body: 'fileName=geoip.dat',
},
{
method: 'POST',
@@ -366,11 +452,12 @@ export const sections = [
{
method: 'POST',
path: '/panel/api/server/logs/:count',
- summary: 'Return the last N lines of the panel’s own log.',
+ summary: 'Return the last N lines of the panel\u2019s own log.',
params: [
{ name: 'count', in: 'path', type: 'number', desc: 'Number of trailing log lines.' },
],
body: '{\n "level": "info",\n "syslog": false\n}',
+ response: '{\n "success": true,\n "obj": "2025/01/01 12:00:00 [INFO] Server started\\n2025/01/01 12:00:01 [INFO] Xray is running"\n}',
},
{
method: 'POST',
@@ -378,24 +465,38 @@ export const sections = [
summary: 'Return the last N lines of the Xray process log.',
params: [
{ name: 'count', in: 'path', type: 'number', desc: 'Number of trailing log lines.' },
+ { name: 'filter', in: 'body (form)', type: 'string', desc: 'Keyword filter — only lines containing this string.' },
+ { name: 'showDirect', in: 'body (form)', type: 'string', desc: '"true" to include direct (freedom) traffic lines.' },
+ { name: 'showBlocked', in: 'body (form)', type: 'string', desc: '"true" to include blocked (blackhole) traffic lines.' },
+ { name: 'showProxy', in: 'body (form)', type: 'string', desc: '"true" to include proxy traffic lines.' },
],
+ body: 'filter=error&showDirect=false&showBlocked=true&showProxy=true',
+ response: '{\n "success": true,\n "obj": "2025/01/01 12:00:00 rejected vless proxy example.com reason: no valid user\\n2025/01/01 12:00:01 direct freedom ok"\n}',
},
{
method: 'POST',
path: '/panel/api/server/importDB',
summary: 'Restore the panel DB from an uploaded SQLite file (multipart form, field name "db"). The panel restarts after restore. Destructive.',
+ params: [
+ { name: 'db', in: 'body (multipart)', type: 'file', desc: 'SQLite database file to upload.' },
+ ],
},
{
method: 'POST',
path: '/panel/api/server/getNewEchCert',
- summary: 'Generate a new ECH (Encrypted Client Hello) keypair. Body picks the algorithm.',
+ summary: 'Generate a new ECH (Encrypted Client Hello) keypair and config list for the given SNI.',
+ params: [
+ { name: 'sni', in: 'body (form)', type: 'string', desc: 'Server Name Indication to generate the ECH config for.' },
+ ],
+ body: 'sni=example.com',
+ response: '{\n "success": true,\n "obj": {\n "echKeySet": "...",\n "echServerKeys": [...],\n "echConfigList": "..."\n }\n}',
},
],
},
{
id: 'nodes',
- title: 'Nodes API',
+ title: 'Nodes',
description:
'Manage remote 3x-ui panels acting as nodes for a central panel. All endpoints under /panel/api/nodes.',
endpoints: [
@@ -403,6 +504,7 @@ export const sections = [
method: 'GET',
path: '/panel/api/nodes/list',
summary: 'List every configured node with its connection details, health, and last heartbeat patch.',
+ response: '{\n "success": true,\n "obj": [\n {\n "id": 1,\n "name": "de-fra-1",\n "scheme": "https",\n "host": "node1.example.com",\n "port": 2053,\n "status": "online",\n "cpu": 23.5,\n "mem": 45.1\n }\n ]\n}',
},
{
method: 'GET',
@@ -422,10 +524,11 @@ export const sections = [
{
method: 'POST',
path: '/panel/api/nodes/update/:id',
- summary: 'Replace a node’s connection details. Same body shape as /add.',
+ summary: 'Replace a node\u2019s connection details. Same body shape as /add.',
params: [
{ name: 'id', in: 'path', type: 'number', desc: 'Node ID.' },
],
+ body: '{\n "name": "de-fra-1",\n "scheme": "https",\n "host": "node1.example.com",\n "port": 2053,\n "basePath": "/",\n "apiToken": "abcdef..."\n}',
},
{
method: 'POST',
@@ -448,6 +551,8 @@ export const sections = [
method: 'POST',
path: '/panel/api/nodes/test',
summary: 'Probe a node without saving it. Uses the body as connection details and returns whether the handshake succeeds.',
+ body: '{\n "scheme": "https",\n "host": "node1.example.com",\n "port": 2053,\n "basePath": "/",\n "apiToken": "abcdef..."\n}',
+ response: '{\n "success": true,\n "obj": {\n "status": "online",\n "cpu": 12.5,\n "mem": 45.2\n }\n}',
},
{
method: 'POST',
@@ -463,16 +568,16 @@ export const sections = [
summary: 'Aggregated metric history for a node — same shape as /server/history, scoped to one node.',
params: [
{ name: 'id', in: 'path', type: 'number', desc: 'Node ID.' },
- { name: 'metric', in: 'path', type: 'string', desc: 'Metric key (cpu, mem, netIn, …).' },
- { name: 'bucket', in: 'path', type: 'number', desc: 'Bucket size in seconds.' },
+ { name: 'metric', in: 'path', type: 'string', desc: 'cpu | mem.' },
+ { name: 'bucket', in: 'path', type: 'number', desc: 'Bucket size in seconds. Allowed: 2, 30, 60, 120, 180, 300.' },
],
},
],
},
{
- id: 'customGeo',
- title: 'Custom Geo API',
+ id: 'custom-geo',
+ title: 'Custom Geo',
description:
'Manage user-supplied GeoIP / GeoSite source files. All endpoints under /panel/api/custom-geo.',
endpoints: [
@@ -531,12 +636,268 @@ export const sections = [
description: 'Operations that interact with the configured Telegram bot.',
endpoints: [
{
- method: 'GET',
+ method: 'POST',
path: '/panel/api/backuptotgbot',
summary: 'Send a fresh DB backup to every Telegram chat configured as an admin recipient. No body, no params.',
},
],
},
+
+ {
+ id: 'settings',
+ title: 'Settings',
+ description:
+ 'Panel configuration and user credentials. All endpoints live under /panel/setting and require a logged-in session or Bearer token.',
+ endpoints: [
+ {
+ method: 'POST',
+ path: '/panel/setting/all',
+ summary: 'Return every panel setting: web server, Telegram bot, subscription, security, LDAP. The full JSON blob that the Settings page edits.',
+ response: '{\n "success": true,\n "obj": {\n "webPort": 2053,\n "webCertFile": "",\n "webKeyFile": "",\n "webBasePath": "/",\n "subPort": 10882,\n "subPath": "/sub/",\n "tgBotEnable": false,\n "tgBotToken": "",\n ...\n }\n}',
+ },
+ {
+ method: 'POST',
+ path: '/panel/setting/defaultSettings',
+ summary: 'Return the computed default settings based on the request host. Useful to preview what a fresh install would use.',
+ },
+ {
+ method: 'POST',
+ path: '/panel/setting/update',
+ summary: 'Persist every setting at once. The body mirrors the shape returned by /all. Invalid values (bad ports, missing cert pairs, etc.) are rejected before write.',
+ body: '{\n "webPort": 2053,\n "webBasePath": "/",\n "subPort": 10882,\n "subPath": "/sub/",\n "tgBotEnable": false,\n ...\n}',
+ },
+ {
+ method: 'POST',
+ path: '/panel/setting/updateUser',
+ summary: 'Change the panel admin username and password. Requires the current credentials for verification. The session is refreshed with the new values on success.',
+ params: [
+ { name: 'oldUsername', in: 'body', type: 'string', desc: 'Current admin username.' },
+ { name: 'oldPassword', in: 'body', type: 'string', desc: 'Current admin password.' },
+ { name: 'newUsername', in: 'body', type: 'string', desc: 'Desired new username.' },
+ { name: 'newPassword', in: 'body', type: 'string', desc: 'Desired new password.' },
+ ],
+ body: '{\n "oldUsername": "admin",\n "oldPassword": "admin",\n "newUsername": "newadmin",\n "newPassword": "newpass"\n}',
+ },
+ {
+ method: 'POST',
+ path: '/panel/setting/restartPanel',
+ summary: 'Restart the entire 3x-ui process after a 3-second grace period. The connection drops immediately; the panel comes back online ~5-10 seconds later.',
+ },
+ {
+ method: 'GET',
+ path: '/panel/setting/getDefaultJsonConfig',
+ summary: 'Return the built-in default Xray JSON config template that ships with this panel version.',
+ },
+ ],
+ },
+
+ {
+ id: 'api-tokens',
+ title: 'API Tokens',
+ description:
+ 'Manage Bearer tokens used for programmatic auth (bots, central panels acting on this node, CI). Each token has a unique name and an enabled flag — disable to revoke without deleting, delete to revoke permanently. Tokens are stored plaintext so the SPA can show them on demand. Send one as Authorization: Bearer <token> on any /panel/api/* request.',
+ endpoints: [
+ {
+ method: 'GET',
+ path: '/panel/setting/apiTokens',
+ summary: 'List every API token, enabled or not.',
+ response: '{\n "success": true,\n "obj": [\n {\n "id": 1,\n "name": "default",\n "token": "abcdef-12345-...",\n "enabled": true,\n "createdAt": 1736000000\n }\n ]\n}',
+ },
+ {
+ method: 'POST',
+ path: '/panel/setting/apiTokens/create',
+ summary: 'Mint a new API token. Name must be unique and 1-64 characters; the token string is server-generated.',
+ params: [
+ { name: 'name', in: 'body', type: 'string', desc: 'Human-readable label, e.g. "central-panel-a".' },
+ ],
+ body: '{\n "name": "central-panel-a"\n}',
+ response: '{\n "success": true,\n "obj": {\n "id": 2,\n "name": "central-panel-a",\n "token": "new-token-string",\n "enabled": true,\n "createdAt": 1736000000\n }\n}',
+ errorResponse: '{\n "success": false,\n "msg": "a token with that name already exists"\n}',
+ },
+ {
+ method: 'POST',
+ path: '/panel/setting/apiTokens/delete/:id',
+ summary: 'Permanently delete a token. Any caller using it stops authenticating immediately.',
+ params: [
+ { name: 'id', in: 'path', type: 'number', desc: 'Token row ID.' },
+ ],
+ response: '{\n "success": true\n}',
+ },
+ {
+ method: 'POST',
+ path: '/panel/setting/apiTokens/setEnabled/:id',
+ summary: 'Toggle a token enabled/disabled without deleting it. Disabled tokens are rejected by checkAPIAuth on the next request.',
+ params: [
+ { name: 'id', in: 'path', type: 'number', desc: 'Token row ID.' },
+ { name: 'enabled', in: 'body', type: 'boolean', desc: 'New enabled state.' },
+ ],
+ body: '{\n "enabled": false\n}',
+ response: '{\n "success": true\n}',
+ },
+ ],
+ },
+
+ {
+ id: 'xray-settings',
+ title: 'Xray Settings',
+ description:
+ 'Xray configuration template, outbound management, Warp/Nord integration, and config testing. All endpoints under /panel/xray.',
+ endpoints: [
+ {
+ method: 'POST',
+ path: '/panel/xray/',
+ summary: 'Return the Xray config template (JSON string), available inbound tags, client reverse tags, and the configured outbound test URL in one response.',
+ response: '{\n "success": true,\n "obj": {\n "xraySetting": "{...raw xray config...}",\n "inboundTags": "[\\"inbound-443\\"]",\n "clientReverseTags": "[]",\n "outboundTestUrl": "https://www.google.com/generate_204"\n }\n}',
+ },
+ {
+ method: 'GET',
+ path: '/panel/xray/getDefaultJsonConfig',
+ summary: 'Return the built-in default Xray config shipped with the panel (identical to /panel/setting/getDefaultJsonConfig).',
+ },
+ {
+ method: 'GET',
+ path: '/panel/xray/getOutboundsTraffic',
+ summary: 'Return traffic statistics for every outbound. Each outbound shows up/down/total counters.',
+ },
+ {
+ method: 'GET',
+ path: '/panel/xray/getXrayResult',
+ summary: 'Return the most recent Xray process stdout/stderr output. Useful to check for startup errors or runtime warnings.',
+ },
+ {
+ method: 'POST',
+ path: '/panel/xray/update',
+ summary: 'Save the Xray JSON config template and optionally the outbound test URL. Both are sent as form fields.',
+ params: [
+ { name: 'xraySetting', in: 'body (form)', type: 'string', desc: 'Full Xray JSON config template.' },
+ { name: 'outboundTestUrl', in: 'body (form)', type: 'string', desc: 'URL used for outbound reachability tests. Defaults to https://www.google.com/generate_204.' },
+ ],
+ },
+ {
+ method: 'POST',
+ path: '/panel/xray/warp/:action',
+ summary: 'Manage Cloudflare Warp integration. The action parameter selects the operation.',
+ params: [
+ { name: 'action', in: 'path', type: 'string', desc: 'data — return Warp stats (quota, remaining). del — delete Warp data. config — return current Warp config. reg — register a new Warp endpoint (sends privateKey, publicKey). license — set a Warp+ license key (sends license).' },
+ { name: 'privateKey', in: 'body (form)', type: 'string', desc: 'Required when action=reg.' },
+ { name: 'publicKey', in: 'body (form)', type: 'string', desc: 'Required when action=reg.' },
+ { name: 'license', in: 'body (form)', type: 'string', desc: 'Required when action=license.' },
+ ],
+ },
+ {
+ method: 'POST',
+ path: '/panel/xray/nord/:action',
+ summary: 'Manage NordVPN integration. The action parameter selects the operation.',
+ params: [
+ { name: 'action', in: 'path', type: 'string', desc: 'countries — list available countries. servers — list servers in a country (sends countryId). reg — get NordVPN credentials (sends token). setKey — store NordVPN API key (sends key). data — return current NordVPN connection data. del — delete NordVPN data.' },
+ { name: 'countryId', in: 'body (form)', type: 'string', desc: 'Required when action=servers.' },
+ { name: 'token', in: 'body (form)', type: 'string', desc: 'Required when action=reg.' },
+ { name: 'key', in: 'body (form)', type: 'string', desc: 'Required when action=setKey.' },
+ ],
+ },
+ {
+ method: 'POST',
+ path: '/panel/xray/resetOutboundsTraffic',
+ summary: 'Reset traffic counters for a specific outbound by tag.',
+ params: [
+ { name: 'tag', in: 'body (form)', type: 'string', desc: 'Outbound tag to reset (e.g. "proxy", "direct").' },
+ ],
+ body: 'tag=proxy',
+ },
+ {
+ method: 'POST',
+ path: '/panel/xray/testOutbound',
+ summary: 'Test an outbound configuration. Sends the outbound JSON (required), optionally all outbounds (to resolve sockopt.dialerProxy dependencies), and a mode flag.',
+ params: [
+ { name: 'outbound', in: 'body (form)', type: 'string', desc: 'JSON-encoded single outbound to test (required).' },
+ { name: 'allOutbounds', in: 'body (form)', type: 'string', desc: 'JSON array of all outbounds — used to resolve dialerProxy chains.' },
+ { name: 'mode', in: 'body (form)', type: 'string', desc: '"tcp" for a fast dial-only probe (parallel-safe). Default/empty uses a full HTTP probe through a temp xray instance.' },
+ ],
+ body: 'outbound={"protocol":"freedom","settings":{}}&mode=tcp',
+ },
+ ],
+ },
+
+ {
+ id: 'subscription',
+ title: 'Subscription Server',
+ description:
+ 'A separate HTTP/HTTPS server that serves proxy subscription links (standard, JSON, and Clash) to clients. The server listens on its own port (default 10882) and is configured in Settings → Subscription. Paths are configurable; defaults are shown below. All subscription endpoints set response headers for client apps to read traffic/expiry info.',
+ subHeader: [
+ { name: 'Subscription-Userinfo', desc: 'Traffic and expiry: upload=N; download=N; total=N; expire=TS' },
+ { name: 'Profile-Title', desc: 'Base64-encoded subscription display name' },
+ { name: 'Profile-Web-Page-Url', desc: 'Link to the subscription info page' },
+ { name: 'Support-Url', desc: 'Support contact URL configured in settings' },
+ { name: 'Profile-Update-Interval', desc: 'Suggested polling interval in minutes (e.g. 10)' },
+ { name: 'Announce', desc: 'Base64-encoded announcement string' },
+ { name: 'Routing-Enable', desc: 'true or false — whether routing rules are included' },
+ { name: 'Routing', desc: 'Global routing rules for client apps that support them (e.g. Happ)' },
+ ],
+ endpoints: [
+ {
+ method: 'GET',
+ path: '/{subPath}:subid',
+ summary: 'Return base64-encoded subscription links for all enabled clients matching the subscription ID. When the request has an Accept: text/html header or ?html=1, renders a styled info page instead. Default path: /sub/:subid.',
+ params: [
+ { name: 'subid', in: 'path', type: 'string', desc: 'Client subscription ID.' },
+ ],
+ },
+ {
+ method: 'GET',
+ path: '/{jsonPath}:subid',
+ summary: 'Return subscription as a JSON array of proxy configs (one per enabled client). Only when JSON subscription is enabled in settings. Default path: /json/:subid.',
+ params: [
+ { name: 'subid', in: 'path', type: 'string', desc: 'Client subscription ID.' },
+ ],
+ },
+ {
+ method: 'GET',
+ path: '/{clashPath}:subid',
+ summary: 'Return subscription as a Clash/Mihomo-compatible YAML config. Only when Clash subscription is enabled in settings. Default path: /clash/:subid.',
+ params: [
+ { name: 'subid', in: 'path', type: 'string', desc: 'Client subscription ID.' },
+ ],
+ },
+ ],
+ },
+
+ {
+ id: 'websocket',
+ title: 'WebSocket',
+ description:
+ 'Real-time status updates via WebSocket. Connect once at ws:///ws to receive a stream of JSON messages without polling. Requires an authenticated session cookie (Bearer token auth is not supported). Each message has a type field that identifies the payload shape.',
+ endpoints: [
+ {
+ method: 'GET',
+ path: '/ws',
+ summary: 'Upgrade an HTTP connection to a WebSocket. Requires an authenticated session cookie (Bearer token auth is not supported here). Returns 101 Switching Protocols on success. The server then pushes JSON messages described below.',
+ },
+ {
+ method: 'WS',
+ path: '→ type: status',
+ summary: 'Server health snapshot pushed every 2 seconds. Contains CPU, memory, swap, disk, network IO, load, and Xray state — same shape as GET /panel/api/server/status.',
+ response: '{\n "type": "status",\n "data": { "cpu": 12.5, "mem": { "current": 2147483648, "total": 8589934592 }, "xray": { "state": "running" } }\n}',
+ },
+ {
+ method: 'WS',
+ path: '→ type: xrayState',
+ summary: 'Xray process state change. Fired when Xray starts, stops, or encounters an error.',
+ response: '{\n "type": "xrayState",\n "data": "running"\n}',
+ },
+ {
+ method: 'WS',
+ path: '→ type: notification',
+ summary: 'In-panel toast notification. Fired on Xray stop/restart, DB import, panel restart, etc.',
+ response: '{\n "type": "notification",\n "title": "Xray service restarted",\n "body": "Xray has been restarted successfully",\n "severity": "success"\n}',
+ },
+ {
+ method: 'WS',
+ path: '→ type: invalidate',
+ summary: 'Instructs the UI to re-fetch a resource. Fired when another admin session modifies data (e.g. toggling inbound enable).',
+ response: '{\n "type": "invalidate",\n "resource": "inbounds"\n}',
+ },
+ ],
+ },
];
export const methodColors = {
@@ -545,4 +906,5 @@ export const methodColors = {
PUT: 'orange',
PATCH: 'orange',
DELETE: 'red',
+ WS: 'purple',
};
diff --git a/frontend/src/pages/inbounds/ClientRowTable.vue b/frontend/src/pages/inbounds/ClientRowTable.vue
index f6119323..dc4b8b84 100644
--- a/frontend/src/pages/inbounds/ClientRowTable.vue
+++ b/frontend/src/pages/inbounds/ClientRowTable.vue
@@ -32,6 +32,7 @@ const props = defineProps({
lastOnlineMap: { type: Object, default: () => ({}) },
isDarkTheme: { type: Boolean, default: false },
pageSize: { type: Number, default: 0 },
+ totalClientCount: { type: Number, default: 0 },
});
const emit = defineEmits([
@@ -138,7 +139,7 @@ function statsExpColor(email) {
return PURPLE;
}
-const isRemovable = computed(() => clients.value.length > 1);
+const isRemovable = computed(() => (props.totalClientCount || clients.value.length) > 1);
function totalGbDisplay(client) {
if (!client.totalGB || client.totalGB <= 0) return '';
diff --git a/frontend/src/pages/inbounds/InboundFormModal.vue b/frontend/src/pages/inbounds/InboundFormModal.vue
index fd045bbb..2c814dc2 100644
--- a/frontend/src/pages/inbounds/InboundFormModal.vue
+++ b/frontend/src/pages/inbounds/InboundFormModal.vue
@@ -12,6 +12,7 @@ import {
SizeFormatter,
Wireguard,
} from '@/utils';
+import { getRandomRealityTarget } from '@/models/reality-targets';
import {
Inbound,
Protocols,
@@ -69,6 +70,7 @@ const inbound = ref(null);
const dbForm = ref(null);
const saving = ref(false);
const advancedJson = ref({ stream: '', sniffing: '', settings: '' });
+const activeTabKey = ref('basic');
// Cached default cert/key paths from /panel/setting/defaultSettings —
// powers the "Set default cert" button on the TLS form.
const defaultCert = ref('');
@@ -240,9 +242,60 @@ watch(() => props.open, (next) => {
dbForm.value = freshDbForm();
primeAdvancedJson();
}
+ activeTabKey.value = 'basic';
fetchDefaultCertSettings();
});
+function applyAdvancedJsonToBasic() {
+ if (!inbound.value) return true;
+ let parsedSettings;
+ let parsedStream;
+ let parsedSniffing;
+ try {
+ parsedSettings = advancedJson.value.settings.trim()
+ ? JSON.parse(advancedJson.value.settings)
+ : inbound.value.settings?.toJson?.();
+ } catch (e) { message.error(`Settings JSON invalid: ${e.message}`); return false; }
+ try {
+ parsedStream = advancedJson.value.stream.trim()
+ ? JSON.parse(advancedJson.value.stream)
+ : inbound.value.stream?.toJson?.();
+ } catch (e) { message.error(`Stream JSON invalid: ${e.message}`); return false; }
+ try {
+ parsedSniffing = advancedJson.value.sniffing.trim()
+ ? JSON.parse(advancedJson.value.sniffing)
+ : inbound.value.sniffing?.toJson?.();
+ } catch (e) { message.error(`Sniffing JSON invalid: ${e.message}`); return false; }
+
+ try {
+ inbound.value = Inbound.fromJson({
+ port: inbound.value.port,
+ listen: inbound.value.listen,
+ protocol: inbound.value.protocol,
+ settings: parsedSettings,
+ streamSettings: parsedStream,
+ tag: inbound.value.tag,
+ sniffing: parsedSniffing,
+ clientStats: inbound.value.clientStats,
+ });
+ } catch (e) {
+ message.error(`Advanced JSON: ${e.message}`);
+ return false;
+ }
+ return true;
+}
+
+let isRevertingTab = false;
+watch(activeTabKey, (next, prev) => {
+ if (isRevertingTab) { isRevertingTab = false; return; }
+ if (prev === 'advanced' && next !== 'advanced') {
+ if (!applyAdvancedJsonToBasic()) {
+ isRevertingTab = true;
+ activeTabKey.value = 'advanced';
+ }
+ }
+});
+
// In add mode, switching protocol restamps settings + re-syncs port.
function onProtocolChange(next) {
if (props.mode === 'edit' || !inbound.value) return;
@@ -339,11 +392,9 @@ function clearMldsa65() {
inbound.value.stream.reality.settings.mldsa65Verify = '';
}
-// Reality target/SNI randomizer — only available if the helper is loaded
function randomizeRealityTarget() {
if (!inbound.value?.stream?.reality) return;
- if (typeof window.getRandomRealityTarget !== 'function') return;
- const t = window.getRandomRealityTarget();
+ const t = getRandomRealityTarget();
inbound.value.stream.reality.target = t.target;
inbound.value.stream.reality.serverNames = t.sni;
}
@@ -573,7 +624,7 @@ watch(
{{ t('pages.nodes.apiTokenHint') }}
+{{ isTokenVisible(row.id) ? row.token : maskToken(row.token) }}
+