mirror of
https://github.com/MHSanaei/3x-ui.git
synced 2026-07-16 09:36:07 +00:00
docs: vendor the documentation site into the monorepo
Fold the standalone 3x-ui-docs project (Next.js 16 + Fumadocs, deployed to docs.sanaei.dev) into docs/ so the panel and its documentation share a single source of truth, the way sing-box keeps its docs in-tree. The old repo becomes redundant and can be retired. - Import the full site under docs/ (app, components, content, lib, public, scripts, config). The self-contained pnpm project sits alongside the existing engineering notes with no filename collisions. - Re-point "Edit on GitHub" links from MHSanaei/3x-ui-docs to this repo's docs/content/docs path (docs/lib/shared.ts, docs/app/.../page.tsx). - Add docs-ci.yml and docs-deploy.yml under .github/workflows/, scoped to docs/** and run with working-directory: docs, since GitHub only runs workflows from the repo-root .github/. deploy-static.yml's GitHub Pages publish (CNAME docs.sanaei.dev) carries over unchanged. Follow-up (outside this commit): attach the docs.sanaei.dev custom domain to this repository's Pages (or set the Vercel project's root directory to docs), confirm the site is live from the monorepo, then delete MHSanaei/3x-ui-docs.
This commit is contained in:
MHSanaei
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: 客户端
|
||||
description: 管理 3x-ui 客户端——凭据、流量与到期限制、IP 限制、分组、批量操作、外部链接以及在线状态。
|
||||
icon: Users
|
||||
---
|
||||
|
||||
**客户端**是由唯一的**电子邮箱**标识的单个用户。在当前版本的
|
||||
面板中，客户端是一等记录，可以同时关联到**多个入站**，并对每个客户端单独进行流量统计。
|
||||
|
||||
## 客户端字段
|
||||
|
||||
| 字段 | 适用于 | 含义 |
|
||||
| -------------- | --------------------- | ------------------------------------------------------------------ |
|
||||
| **Email** | 全部 | 用于统计和查询的唯一标识符。 |
|
||||
| **ID (UUID)** | VLESS、VMess | 客户端凭据。 |
|
||||
| **Password** | Trojan、Shadowsocks | 客户端凭据。 |
|
||||
| **Auth** | Hysteria2 | 客户端凭据。 |
|
||||
| **Flow** | VLESS | XTLS 流控，例如 `xtls-rprx-vision`。 |
|
||||
| **Limit IP** | 全部 | 最大同时连接的源 IP 数量（通过 Fail2ban 强制执行）。 |
|
||||
| **Total (GB)** | 全部 | 流量配额；用尽后客户端将被禁用。 |
|
||||
| **Expiry** | 全部 | 该日期之后客户端停止工作。 |
|
||||
| **Reset** | 全部 | 以**天**为单位的自动续期周期（滚动重置配额）。 |
|
||||
| **Telegram ID**| 全部 | 将客户端关联到 Telegram 用户，用于自助服务/通知。 |
|
||||
| **Sub ID** | 全部 | 用于对该客户端链接分组的订阅标识符。 |
|
||||
| **Group** | 全部 | 可选的客户端分组，便于组织管理和批量筛选。 |
|
||||
| **Comment** | 全部 | 自由文本备注。 |
|
||||
|
||||
<Callout type="info">
|
||||
达到**流量**或**到期**限制会禁用客户端；当客户端被自动禁用时，面板可以
|
||||
自动重启 Xray（`restartXrayOnClientDisable`，默认开启）。
|
||||
</Callout>
|
||||
|
||||
## 限制与 IP 控制
|
||||
|
||||
- **流量 / 到期**上限达到时会禁用客户端；**Reset** 周期可
|
||||
自动续期配额。
|
||||
- **Limit IP** 限制同时连接的源 IP 数量。其强制执行依赖于 Fail2ban——
|
||||
参见 [安全](/docs/operations/security)。你可以查看某个客户端最近使用的 IP，
|
||||
并从该客户端的操作中清除它们。
|
||||
- 系统会按客户端（在多节点部署中还会按节点）跟踪**在线状态**和**最后在线**时间。
|
||||
|
||||
## 分享链接与外部链接
|
||||
|
||||
每个客户端都有针对其各入站的分享链接和二维码，外加一个合并的
|
||||
[订阅](/docs/config/subscription)。你还可以为客户端附加**外部
|
||||
链接**——额外的 `vless://`、`vmess://`、`trojan://`、`ss://`、
|
||||
`hysteria2://` 或 `wireguard://` 链接，或一个远程订阅 URL——使它们
|
||||
与面板生成的链接一起出现在该客户端的订阅中。
|
||||
|
||||
要查看链接的确切内容，可将其粘贴到
|
||||
[分享链接检查器](/docs/config/share-links)中。
|
||||
|
||||
## 批量操作
|
||||
|
||||
为便于一次性管理大量客户端，面板支持批量**创建、启用、
|
||||
禁用、删除、关联/解除关联**（到入站）、**重置流量**以及
|
||||
**调整**（增加天数 / 增加字节 / 设置 flow）。维护操作还允许你
|
||||
删除**已耗尽**的客户端（配额/到期用尽）和**孤立**的客户端
|
||||
（未关联到任何入站）。
|
||||
|
||||
<Callout type="warn">
|
||||
客户端的分享链接包含其凭据。请像对待密码一样对待链接和二维码，
|
||||
一旦泄露应立即轮换凭据。
|
||||
</Callout>
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
title: 入站与协议
|
||||
description: 在 3x-ui 中创建入站——协议、传输方式、流量重置与到期，以及在同一端口上服务多种协议的回落（fallback）。
|
||||
icon: ArrowDownToLine
|
||||
---
|
||||
|
||||
**入站**（inbound）是一个监听器，它使用特定的协议和传输方式在某个端口上接受客户端连接。
|
||||
你的日常工作大多是创建和管理入站，以及其中的客户端。
|
||||
|
||||
## 创建入站
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### 添加入站
|
||||
|
||||
打开 **Inbounds → Add**，填写备注，选择一个**协议**，再选择**端口**和监听地址。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 选择传输方式和安全层
|
||||
|
||||
选择传输方式（TCP、WebSocket、gRPC、HTTPUpgrade、XHTTP……）和安全层
|
||||
（none、TLS 或 REALITY）。参见 [传输方式](/docs/config/transports) 和
|
||||
[REALITY](/docs/config/reality)。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 添加客户端
|
||||
|
||||
添加一个或多个客户端，每个客户端都有各自的凭据、限额和分享链接。
|
||||
参见 [客户端](/docs/config/clients)。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 设置流量限制、到期和重置
|
||||
|
||||
可选地为入站设置总流量上限和到期日期，并选择一个周期性的**流量重置**计划：
|
||||
`never`（默认）、`hourly`、`daily`、`weekly` 或 `monthly`。
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## 支持的协议
|
||||
|
||||
入站编辑器接受以下协议：
|
||||
|
||||
| Protocol | Notes |
|
||||
| ---------------------- | ------------------------------------------------------------------------ |
|
||||
| **VLESS** | 轻量级；是 REALITY + XTLS-Vision 的基础。推荐使用。 |
|
||||
| **VMess** | 较老，但客户端支持极为广泛。 |
|
||||
| **Trojan** | 基于 TLS；支持 XTLS 和回落。 |
|
||||
| **Shadowsocks** | 包含 Shadowsocks-2022（`2022-blake3-*`）加密方式。 |
|
||||
| **WireGuard** | 现代隧道协议。 |
|
||||
| **Hysteria2** | 选择为 `hysteria`；面板生成 `hysteria2://` 链接。 |
|
||||
| **HTTP** | HTTP 代理。 |
|
||||
| **Mixed (SOCKS/HTTP)** | SOCKS + HTTP 的组合监听器。 |
|
||||
| **Dokodemo-door / Tunnel** | 端口转发 / 流量重定向。 |
|
||||
| **MTProto** | Telegram MTProto 代理，由内置的 `mtg` 进程提供（而非 Xray）。 |
|
||||
|
||||
<Callout type="info">
|
||||
在内部，Hysteria2 并不是一个独立的协议——它是把传输版本设为 2 的 `hysteria`
|
||||
协议，面板会为它生成 `hysteria2://` 分享链接。
|
||||
</Callout>
|
||||
|
||||
## 回落——在同一端口上服务多种协议
|
||||
|
||||
回落（fallback）让单个 TLS 端口（例如 `443`）可以服务不止一种协议——例如同时服务
|
||||
VLESS **和** Trojan——方法是将无法匹配的握手路由到子入站。在 3x-ui 中，回落是在
|
||||
面板里管理的（主入站的 **Fallbacks** 列表），而不是手写进 JSON。
|
||||
|
||||
只有当主入站满足以下条件时，回落才可用：
|
||||
|
||||
- 协议为 **VLESS** 或 **Trojan**，
|
||||
- 使用裸 **TCP** 传输，
|
||||
- 安全层为 **TLS** 或 **REALITY**。
|
||||
|
||||
每条回落规则都指向一个子入站，并可按 `path`、`alpn` 和 `dest` 进行匹配。
|
||||
回落子入站的客户端分享链接会被自动改写，以公布主入站的地址、端口和 TLS。
|
||||
|
||||
## 不确定该选哪个？
|
||||
|
||||
使用向导，根据你的目标和客户端获取推荐：
|
||||
|
||||
<ProtocolWizard />
|
||||
|
||||
<Callout type="info">
|
||||
若要在现代客户端上实现抗审查能力，**VLESS + REALITY + XTLS-Vision** 通常是最佳选择
|
||||
——继续阅读 [REALITY](/docs/config/reality)。
|
||||
</Callout>
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"title": "配置",
|
||||
"icon": "Settings",
|
||||
"pages": [
|
||||
"panel",
|
||||
"ssl-certificates",
|
||||
"inbounds",
|
||||
"reality",
|
||||
"transports",
|
||||
"clients",
|
||||
"subscription",
|
||||
"share-links"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,73 @@
|
||||
---
|
||||
title: 面板设置
|
||||
description: 全部 3x-ui 面板设置——Web 服务器、TLS、显示、安全与通知——并附上源码中的默认值。
|
||||
icon: SlidersHorizontal
|
||||
---
|
||||
|
||||
**面板设置**控制面板本身如何对外提供服务以及如何受到保护（与你的入站和客户端相互独立）。设置以键/值对的形式存储；下面的默认值直接取自面板源码。机密信息（令牌、密码）仅以"已设置 / 未设置"指示器的形式展示，绝不会以完整形式返回到浏览器。
|
||||
|
||||
## Web 服务器
|
||||
|
||||
| 设置 | 默认值 | 含义 |
|
||||
| ------------------- | ----------------------- | ----------------------------------------------------------------------- |
|
||||
| `webPort` | `2053` | 面板端口（1–65535）。`XUI_PORT` 环境变量会在运行时覆盖它。 |
|
||||
| `webListen` | _（所有网络接口）_ | 将面板绑定到指定的 IP。 |
|
||||
| `webBasePath` | `/` | 面板对外提供服务所使用的 URL 路径（始终规范化为 `/…/`）。 |
|
||||
| `webCertFile` / `webKeyFile` | _（无）_ | TLS 证书 + 密钥。两者都设置后，面板将以 **HTTPS** 提供服务。 |
|
||||
| `sessionMaxAge` | `360` | 会话有效期，单位为**分钟**（默认 6 小时）。 |
|
||||
| `trustedProxyCIDRs` | `127.0.0.1/32,::1/128` | 其转发头（真实客户端 IP）受信任的 IP/CIDR。 |
|
||||
| `panelOutbound` | _（无）_ | 通过一个命名的 Xray 出站来路由面板自身的出口流量（更新检查、Telegram、地理/订阅拉取）。 |
|
||||
|
||||
更改端口或基础路径后，面板 URL 将变为
|
||||
`http(s)://<server>:<port><web-base-path>`。你可以在首次启动时通过
|
||||
[`XUI_INIT_WEB_BASE_PATH`](/docs/reference/env-vars) 预设基础路径。
|
||||
|
||||
### TLS
|
||||
|
||||
通过 HTTPS 提供面板服务可保护你的凭据在传输过程中的安全。要么设置
|
||||
`webCertFile` + `webKeyFile`——[`x-ui` SSL 菜单](/docs/config/ssl-certificates)
|
||||
可以为你申请 Let's Encrypt 证书——要么在
|
||||
[反向代理](/docs/operations/reverse-proxy)处终止 TLS。
|
||||
|
||||
<Callout type="warn">
|
||||
切勿在公网上以明文 HTTP 暴露面板。请使用 TLS、非默认端口和一个长随机的
|
||||
Web 基础路径。
|
||||
</Callout>
|
||||
|
||||
## 显示
|
||||
|
||||
| 设置 | 默认值 | 含义 |
|
||||
| ---------------- | ------------------------------------------------ | ------------------------------------------------------------- |
|
||||
| `pageSize` | `25` | 列表中每页的行数（`0` 表示禁用分页）。 |
|
||||
| `expireDiff` | `0` | 到期前开始预警的天数。 |
|
||||
| `trafficDiff` | `0` | 配额剩余达到该百分比时开始预警。 |
|
||||
| `remarkTemplate` | `{{INBOUND}}-{{EMAIL}}\|📊{{TRAFFIC_LEFT}}\|⏳{{DAYS_LEFT}}D` | 默认的客户端备注模板（参见 [分享链接](/docs/config/share-links#remark-template-variables)）。 |
|
||||
| `timeLocation` | `Local` | 统计和到期所用的时区。 |
|
||||
| `datepicker` | `gregorian` | 日期输入所用的日历（公历或波斯历/Jalali）。 |
|
||||
|
||||
## 安全与身份验证
|
||||
|
||||
凭据、双因素认证、暴力破解限制器、会话以及 LDAP 在
|
||||
[首次登录](/docs/guide/first-login)和
|
||||
[安全](/docs/operations/security)中有详细介绍。简而言之：
|
||||
|
||||
- 密码以 **bcrypt** 哈希形式存储；更改密码会登出所有会话。
|
||||
- 登录时可要求 **2FA（TOTP）**。
|
||||
- 当本地密码校验失败时，可由 **LDAP** 回退来验证用户。
|
||||
- API 访问使用在面板设置下管理的 **API 令牌**（参见
|
||||
[API 参考](/docs/reference/api/api-tokens)）。
|
||||
|
||||
## 通知与订阅
|
||||
|
||||
它们各自拥有独立的设置分组和页面：
|
||||
|
||||
<Cards>
|
||||
<Card title="Telegram 机器人" href="/docs/operations/telegram-bot" description="令牌、聊天 ID、告警与报告。" />
|
||||
<Card title="订阅" href="/docs/config/subscription" description="订阅服务器、格式与路径。" />
|
||||
<Card title="安全" href="/docs/operations/security" description="2FA、IP 限制与加固。" />
|
||||
</Cards>
|
||||
|
||||
<Callout type="info">
|
||||
电子邮件（SMTP）通知同样可配置（主机、端口、加密、收件人），并与 Telegram
|
||||
机器人使用相同的事件类型。
|
||||
</Callout>
|
||||
@@ -0,0 +1,120 @@
|
||||
---
|
||||
title: REALITY
|
||||
description: 在 3x-ui 中配合 XTLS-Vision 搭建 VLESS + REALITY 入站——密钥、short ID、SNI、指纹以及常见陷阱。
|
||||
icon: ShieldCheck
|
||||
---
|
||||
|
||||
**REALITY** 是 Xray 的一种传输安全机制，它将你的代理流量伪装成发往某个真实、热门网站的普通流量。
|
||||
与传统 TLS 不同，你的服务器**无需拥有自己的证书**——它会借用目标站点（`dest`）的 TLS 握手。
|
||||
再结合 **XTLS-Vision** 流控，它既快速又能抵抗深度包检测（DPI）。
|
||||
|
||||
REALITY 配合 **VLESS**（以及 Trojan）使用，推荐的流控为 `xtls-rprx-vision`。
|
||||
|
||||
## 关键设置
|
||||
|
||||
当你在某个 VLESS 入站上将安全模式选为 **REALITY** 时，3x-ui 会暴露以下字段：
|
||||
|
||||
| 字段 | 含义 |
|
||||
| ------------------------ | ------------------------------------------------------------------ |
|
||||
| **Dest (target)** | 要伪装成的真实 TLS 站点，例如 `www.microsoft.com:443`。 |
|
||||
| **SNI / Server Names** | 客户端发送的主机名；必须与目标站点的证书匹配。 |
|
||||
| **Public / Private key** | 一对 **x25519** 密钥。私钥保留在服务器上。 |
|
||||
| **Short IDs** | 用于验证客户端的十六进制字符串（可以设置多个）。 |
|
||||
| **Flow** | 设为 `xtls-rprx-vision`。 |
|
||||
| **Fingerprint (uTLS)** | 要模仿的客户端 TLS 指纹，例如 `chrome`。 |
|
||||
|
||||
私钥由 Xray 的 `x25519` 工具生成（面板可以为你生成这对密钥）：
|
||||
|
||||
```bash title="generate an x25519 keypair"
|
||||
xray x25519
|
||||
```
|
||||
|
||||
## 在面板中配置
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### 创建 VLESS 入站
|
||||
|
||||
添加一个新入站，协议选择 **VLESS**，并将 **Security** 设为 **reality**。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 选择目标（dest）和 SNI
|
||||
|
||||
选一个支持 TLS 1.3 和 HTTP/2、且你的服务器与客户端都能访问的可信站点
|
||||
（例如 `www.microsoft.com:443`）。将 server names / SNI 设为与该站点证书匹配。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 生成密钥和 short ID
|
||||
|
||||
生成 x25519 密钥对以及一个或多个 short ID。请妥善保管**私钥**；客户端永远只会收到**公钥**。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 设置流控和指纹
|
||||
|
||||
使用 `xtls-rprx-vision` 流控，以及一个常见的 uTLS 指纹（例如 `chrome`）。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 添加客户端并分享链接
|
||||
|
||||
创建一个客户端，然后在兼容的应用（v2rayNG、Hiddify、Mihomo 等）中使用它的分享链接或二维码。
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## 配置长什么样
|
||||
|
||||
在服务器端，一个 REALITY 入站的 `streamSettings` 大致如下：
|
||||
|
||||
```json title="server inbound (excerpt)"
|
||||
{
|
||||
"network": "tcp",
|
||||
"security": "reality",
|
||||
"realitySettings": {
|
||||
"dest": "www.microsoft.com:443",
|
||||
"serverNames": ["www.microsoft.com"],
|
||||
"privateKey": "<x25519 private key>",
|
||||
"shortIds": ["<hex short id>"],
|
||||
"fingerprint": "chrome"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
与之匹配的客户端分享链接携带的是**公开**参数：
|
||||
|
||||
```text title="vless:// (excerpt)"
|
||||
vless://<uuid>@<server>:443?security=reality&pbk=<public-key>&sid=<short-id>&sni=www.microsoft.com&fp=chrome&spx=%2F&flow=xtls-rprx-vision#my-reality
|
||||
```
|
||||
|
||||
- `pbk` —— REALITY **公**钥
|
||||
- `sid` —— short ID（与服务器上的某一个匹配）
|
||||
- `sni` —— server name（与目标站点的证书匹配）
|
||||
- `fp` —— 客户端指纹
|
||||
- `spx` —— spiderX 路径
|
||||
- `flow` —— `xtls-rprx-vision`
|
||||
|
||||
## 常见陷阱
|
||||
|
||||
<Callout type="warn">
|
||||
|
||||
- **目标选得不好。** `dest` 必须是一个真实站点，支持 **TLS 1.3** 和 **HTTP/2**、可访问，且在你所在地区未被封锁。请选一个你并不拥有、且访问量很大的站点。
|
||||
- **SNI 不匹配。** SNI / server names 必须与目标站点的真实证书匹配，否则握手会暴露伪装。
|
||||
- **私钥泄露。** 永远只把**公钥**分发给客户端。
|
||||
- **流控设置错误。** REALITY + XTLS-Vision 要求在入站的客户端条目和分享链接上都设置 `flow = xtls-rprx-vision`。
|
||||
|
||||
</Callout>
|
||||
|
||||
## 生成配置
|
||||
|
||||
使用下面的生成器创建一对全新的 X25519 密钥、UUID 和 short ID，然后复制服务器入站 JSON 和客户端分享链接。
|
||||
所有内容都在**你的浏览器中**计算——不会有任何密钥或链接被发送到任何地方。
|
||||
|
||||
<RealityConfigGenerator />
|
||||
|
||||
<Callout type="info">
|
||||
**私钥**只应留在你的服务器上。请把生成的 `vless://` 链接（其中包含**公钥**）分享给客户端。
|
||||
</Callout>
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: 分享链接
|
||||
description: 3x-ui 的分享链接格式（vless、vmess、trojan、ss、hysteria2、mtproto）、备注模板变量，以及一个浏览器内的链接检查器。
|
||||
icon: Link
|
||||
---
|
||||
|
||||
3x-ui 会为每个客户端生成一个**分享链接**（以及二维码）。v2rayNG、Hiddify、Mihomo
|
||||
等客户端应用通过导入这些链接来完成自身配置。
|
||||
|
||||
## 链接格式
|
||||
|
||||
| Scheme | Shape |
|
||||
| -------------- | --------------------------------------------------------------- |
|
||||
| `vless://` | `vless://<uuid>@<host>:<port>?<params>#<remark>` |
|
||||
| `vmess://` | `vmess://<base64-json>` (a base64-encoded JSON object) |
|
||||
| `trojan://` | `trojan://<password>@<host>:<port>?<params>#<remark>` |
|
||||
| `ss://` | `ss://<userinfo>@<host>:<port>?<params>#<remark>` (SIP002; Shadowsocks-2022 uses percent-encoded userinfo) |
|
||||
| `hysteria2://` | `hysteria2://<auth>@<host>:<port>?<params>#<remark>` |
|
||||
| `tg://proxy` | `tg://proxy?server=…&port=…&secret=…` (MTProto) |
|
||||
|
||||
查询参数承载传输和安全设置——`security`、`sni`、`fp`、`pbk`、`sid`、`spx`、`flow`、
|
||||
`type`、`path`、`host`、`alpn` 等。
|
||||
|
||||
## 检查链接
|
||||
|
||||
粘贴任意分享链接即可解码出每一个字段。解析**完全在你的浏览器中**进行——链接绝不会通过网络发送出去。
|
||||
|
||||
<ShareLinkInspector />
|
||||
|
||||
<Callout type="warn">
|
||||
分享链接包含以客户端身份连接所需的一切信息，其中包括客户端的凭据。请像对待密码一样对待它们。
|
||||
</Callout>
|
||||
|
||||
## 备注模板变量
|
||||
|
||||
每个链接中 `#` 之后的文本（即**备注**）由你在面板设置中控制的模板（`remarkTemplate`）生成。默认值为：
|
||||
|
||||
```text
|
||||
{{INBOUND}}-{{EMAIL}}|📊{{TRAFFIC_LEFT}}|⏳{{DAYS_LEFT}}D
|
||||
```
|
||||
|
||||
占位符使用 `{{UPPER_CASE}}` 语法。模板会按 `|` 拆分成若干段；若某一段的唯一值是无限标记 `∞`
|
||||
（用于 `TRAFFIC_LEFT`、`TRAFFIC_TOTAL`、`DAYS_LEFT` 或 `TIME_LEFT`），该段会被丢弃，
|
||||
这样不限量的客户端就不会显示空白的修饰内容。
|
||||
|
||||
### 可用的占位符
|
||||
|
||||
| Token | Value |
|
||||
| ----- | ----- |
|
||||
| `{{EMAIL}}` / `{{USERNAME}}` | 客户端电子邮箱（标识符） |
|
||||
| `{{INBOUND}}` | 入站备注 |
|
||||
| `{{HOST}}` | 主机行备注（受管主机） |
|
||||
| `{{ID}}` / `{{SHORT_ID}}` | 客户端 UUID / 其前 8 个字符 |
|
||||
| `{{TELEGRAM_ID}}` · `{{SUB_ID}}` · `{{COMMENT}}` | Telegram ID、订阅 ID、备注 |
|
||||
| `{{STATUS}}` / `{{STATUS_EMOJI}}` | `active`/`expired`/`depleted`/`disabled`（或 ✅⏳🚫） |
|
||||
| `{{DAYS_LEFT}}` / `{{TIME_LEFT}}` | 剩余天数，或 `Xd Xh Xm`（不限量时为 `∞`） |
|
||||
| `{{EXPIRE_DATE}}` / `{{JALALI_EXPIRE_DATE}}` / `{{EXPIRE_UNIX}}` | 到期时间，分别为公历 / 波斯历日期 / Unix 秒数 |
|
||||
| `{{CREATED_UNIX}}` | 创建时间（Unix 秒数） |
|
||||
| `{{TRAFFIC_USED}}` / `{{TRAFFIC_LEFT}}` / `{{TRAFFIC_TOTAL}}` | 人类可读的用量（不限量时为 `∞`） |
|
||||
| `{{TRAFFIC_USED_BYTES}}` / `{{TRAFFIC_LEFT_BYTES}}` / `{{TRAFFIC_TOTAL_BYTES}}` | 同上，以字节为单位 |
|
||||
| `{{UP}}` / `{{DOWN}}` | 上传 / 下载（人类可读） |
|
||||
| `{{RESET_DAYS}}` · `{{USAGE_PERCENTAGE}}` | 重置周期（天）· 已用百分比 |
|
||||
| `{{PROTOCOL}}` / `{{TRANSPORT}}` / `{{SECURITY}}` | 例如 `VLESS` / `ws` / `REALITY` |
|
||||
|
||||
<Callout type="info">
|
||||
用量类占位符（流量、天数、状态）会出现在订阅**正文**中，但会从显示 / 二维码视图中剥离，
|
||||
这样分享出去的二维码就不会泄露客户端的剩余配额。日期类占位符遵循 `datepicker` 设置（公历或波斯历）。
|
||||
</Callout>
|
||||
|
||||
## 相关
|
||||
|
||||
<Cards>
|
||||
<Card title="REALITY" href="/docs/config/reality" description="生成 VLESS + REALITY 配置和链接。" />
|
||||
<Card title="订阅" href="/docs/config/subscription" description="通过一个 URL 提供某客户端的全部链接。" />
|
||||
</Cards>
|
||||
@@ -0,0 +1,180 @@
|
||||
---
|
||||
title: SSL 证书
|
||||
description: 为 3x-ui 面板和入站获取并续期 TLS 证书——可使用 x-ui 的 ACME 菜单（域名或裸 IP）、Cloudflare DNS-01 通配符，或手动 Certbot。
|
||||
icon: ShieldCheck
|
||||
---
|
||||
|
||||
TLS 证书让你能够通过 HTTPS 提供**面板**服务（这样你的登录和 API
|
||||
流量都会被加密），并在**入站**上终止 TLS（VLESS-TLS、Trojan、
|
||||
Shadowsocks-TLS 等等）。获取证书有三种方式：
|
||||
|
||||
- **`x-ui` 菜单**——内置的 [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment)
|
||||
客户端。对于单个域名或裸 IP 来说最为简单。
|
||||
- **Cloudflare DNS-01**——同样在菜单中提供；适用于**通配符**证书，或者
|
||||
当 80 端口被封锁 / 服务器位于 Cloudflare 代理之后时。
|
||||
- **手动 Certbot**——如果你更愿意自己管理 `acme.sh`/Certbot。
|
||||
|
||||
<Callout type="info">
|
||||
如果你将面板置于 Nginx 或 Caddy 之后，可以改为让反向代理来处理
|
||||
证书——参见[反向代理](/docs/operations/reverse-proxy)。
|
||||
[REALITY](/docs/config/reality) 入站**完全不需要**证书；它们
|
||||
借用真实站点的 TLS。本页面针对的是面板和传统的 TLS 入站。
|
||||
</Callout>
|
||||
|
||||
## `x-ui` SSL 菜单（Let's Encrypt）
|
||||
|
||||
运行 `x-ui` 并选择 **`20` — SSL Certificate Management**。它会调用
|
||||
[acme.sh](https://github.com/acmesh-official/acme.sh)，并提供以下功能：
|
||||
|
||||
| 选项 | 作用 |
|
||||
| ------------------------------ | ------------------------------------------------------------------- |
|
||||
| Get SSL (Domain) | 通过 HTTP 验证为域名签发证书。 |
|
||||
| Get SSL for IP Address | 为**裸 IP** 签发短期（6 天、自动续期）证书。 |
|
||||
| Revoke | 吊销现有证书。 |
|
||||
| Force Renew | 在到期前立即续期。 |
|
||||
| Show Existing Domains | 列出服务器上已有的证书。 |
|
||||
| Set Cert paths for the panel | 将面板的 TLS 指向已签发的证书（自动为你填写相关字段）。 |
|
||||
|
||||
### 为域名签发证书
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### 将域名指向服务器
|
||||
|
||||
为你的域名创建一条 `A`（和/或 `AAAA`）记录，解析到该
|
||||
服务器的公网 IP。在 DNS 完成传播之前，验证将会失败。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 腾出 80 端口
|
||||
|
||||
HTTP 验证需要 **80 端口**可从互联网访问且未被占用。请在验证期间
|
||||
停止任何绑定该端口的程序，并在[防火墙](/docs/reference/ports-firewall)中放行它。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 运行签发程序
|
||||
|
||||
`x-ui` → `20` → **Get SSL (Domain)**，然后输入域名。acme.sh 会请求
|
||||
证书，并将其保存在 `/root/cert/<domain>/` 目录下，文件名为 `fullchain.pem`
|
||||
（证书链）和 `privkey.pem`（私钥）。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 接入面板
|
||||
|
||||
选择 **Set Cert paths for the panel** 来填写 `webCertFile` 和
|
||||
`webKeyFile` 并重启面板，或者在
|
||||
[面板设置](/docs/config/panel#tls)中自行设置。两项都设置完成后，面板便会
|
||||
立即提供 HTTPS 服务。
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
### 为裸 IP 签发证书
|
||||
|
||||
没有域名？选择 **Get SSL for IP Address** 来获取一个绑定到服务器 IP 的
|
||||
短期证书（有效期约 6 天，自动续期）。
|
||||
在你设置好域名之前，这对于通过 HTTPS 访问面板很有用。
|
||||
|
||||
## Cloudflare（DNS-01 通配符）
|
||||
|
||||
DNS 验证通过创建 TXT 记录来证明你对域名的控制权，而无需在 80 端口上
|
||||
作出应答——因此它能在 **Cloudflare 代理之后**、在 80 端口被封锁的
|
||||
服务器上，以及为**通配符**证书（`*.example.com`）正常工作。
|
||||
|
||||
你的域名 DNS 必须由 Cloudflare 托管，并且你需要具备以下两者之一：
|
||||
|
||||
- 一个具有 `Zone:DNS:Edit` 权限的**受限范围 API 令牌**（推荐），或
|
||||
- 你的账户**邮箱 + Global API Key**。
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### 创建受限范围 API 令牌
|
||||
|
||||
在 Cloudflare 控制台中进入 **My Profile → API Tokens →
|
||||
[Create Token](https://dash.cloudflare.com/profile/api-tokens)**，选择
|
||||
**Edit zone DNS** 模板，将其范围限定到你要签发证书的区域，然后创建
|
||||
它。复制该令牌——它只会显示一次。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 运行 Cloudflare 签发程序
|
||||
|
||||
`x-ui` → **`21` — Cloudflare SSL Certificate**。当提示时，选择 **`t`** 使用
|
||||
API 令牌（默认），或选择 **`g`** 使用 Global API Key，然后输入你的
|
||||
域名（如果使用 Global API Key，还需输入你的账户邮箱和密钥）。acme.sh 会创建
|
||||
TXT 记录、完成验证，并在之后将其清理。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 将面板指向证书
|
||||
|
||||
与域名流程一样，使用 **Set Cert paths for the panel**（菜单 `20`）或在
|
||||
[面板设置](/docs/config/panel#tls)中设置
|
||||
`webCertFile` / `webKeyFile`。
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
<Callout type="info">
|
||||
请优先使用受限范围令牌而非 Global API Key——它只授予对你所选区域的
|
||||
DNS 编辑权限，因此即使泄露也无法波及你 Cloudflare 账户的其余部分。
|
||||
</Callout>
|
||||
|
||||
## 手动（Certbot）
|
||||
|
||||
如果你不想使用菜单，可以用 Certbot 的 standalone 插件来签发证书
|
||||
（同样需要 80 端口空闲，且域名已解析到服务器）：
|
||||
|
||||
```bash
|
||||
apt-get install certbot -y
|
||||
certbot certonly --standalone --agree-tos --register-unsafely-without-email -d yourdomain.com
|
||||
certbot renew --dry-run
|
||||
```
|
||||
|
||||
Certbot 会将证书写入 `/etc/letsencrypt/live/yourdomain.com/`
|
||||
（`fullchain.pem` 和 `privkey.pem`）。在[面板设置](/docs/config/panel#tls)中
|
||||
将面板指向这两个文件，并设置好续期——`certbot renew`
|
||||
默认会在 systemd 定时器上运行。
|
||||
|
||||
## 使用证书
|
||||
|
||||
- **面板**——在[面板设置](/docs/config/panel#tls)中设置 `webCertFile`（完整证书链）
|
||||
和 `webKeyFile`（私钥）。两项都必须设置，面板才会
|
||||
切换到 HTTPS。菜单选项 **`11` — View Current Settings** 会打印
|
||||
当前正在使用的路径。
|
||||
- **入站**——当你在某个入站上启用 TLS 时，在该入站的 TLS
|
||||
设置中引用相同的证书和密钥文件（或粘贴其内容）。参见
|
||||
[入站](/docs/config/inbounds)和
|
||||
[传输](/docs/config/transports)。
|
||||
|
||||
<Callout type="warn">
|
||||
证书会过期（Let's Encrypt：90 天；IP 证书：约 6 天）。菜单和
|
||||
Certbot 都会自动续期，但面板始终读取固定路径下的**文件**——
|
||||
因此请**原地**续期，而不要移动文件，这样面板会在下次重启时
|
||||
自动加载新证书。**Force Renew**（菜单 `20`）可
|
||||
按需触发一次续期。
|
||||
</Callout>
|
||||
|
||||
## 后续步骤
|
||||
|
||||
<Cards>
|
||||
<Card
|
||||
title="面板设置"
|
||||
href="/docs/config/panel#tls"
|
||||
description="webCertFile / webKeyFile 以及其余的 Web 服务器设置。"
|
||||
/>
|
||||
<Card
|
||||
title="反向代理"
|
||||
href="/docs/operations/reverse-proxy"
|
||||
description="改为让 Nginx 或 Caddy 替你终止 TLS。"
|
||||
/>
|
||||
<Card
|
||||
title="REALITY"
|
||||
href="/docs/config/reality"
|
||||
description="面向入站的隐身 TLS——无需任何证书。"
|
||||
/>
|
||||
</Cards>
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
title: 订阅
|
||||
description: 运行 3x-ui 订阅服务器 —— base64/JSON/Clash 格式、端口与路径、TLS、响应头以及自定义模板。
|
||||
icon: Rss
|
||||
---
|
||||
|
||||
**订阅**是一个返回客户端全部配置的单一 URL。客户端应用会定期刷新它，因此当你修改某个入站时，客户端会自动获取这些变更。订阅服务器作为一个**独立于**面板的服务器运行。
|
||||
|
||||
## 启用与配置
|
||||
|
||||
订阅服务器**默认开启**（`subEnable`）。在面板的订阅设置中进行配置：
|
||||
|
||||
| 设置 | 默认值 | 含义 |
|
||||
| ------------- | ------- | --------------------------------------------------------------- |
|
||||
| `subPort` | `2096` | 监听端口（与面板分开）。 |
|
||||
| `subListen` | _(全部)_ | 绑定地址。 |
|
||||
| `subPath` | `/sub/` | 原始订阅 URL 的基础路径。 |
|
||||
| `subDomain` | _(无)_ | 公开主机名；若设置，服务器仅响应该 Host。 |
|
||||
| `subCertFile` / `subKeyFile` | _(无)_ | TLS 证书 + 密钥 —— 设置后，服务器以 **HTTPS** 提供服务。 |
|
||||
| `subEncrypt` | `true` | 对原始订阅内容进行 base64 编码。 |
|
||||
| `subUpdates` | `12` | 发送给客户端的建议刷新间隔（小时）。 |
|
||||
|
||||
一个订阅 URL 形如：
|
||||
|
||||
```text
|
||||
https://<sub-host>:<sub-port>/sub/<sub-id>
|
||||
```
|
||||
|
||||
其中 `<sub-id>` 是客户端的 **Sub ID**。
|
||||
|
||||
同一个 Sub ID 会在不同路径上以多种格式提供 —— `subPath` 上的 **Base64** 列表和 JSON 路径上的 **JSON**（Xray-json）配置。在此构建这些 URL 并预览两种内容：
|
||||
|
||||
<SubscriptionBuilder />
|
||||
|
||||
## 输出格式
|
||||
|
||||
**格式由路径决定**，每种格式都有各自的启用开关：
|
||||
|
||||
| 格式 | 路径 | 启用方式 | 输出 |
|
||||
| --------------------- | --------- | ---------------- | --------------------------------------------------- |
|
||||
| **原始链接** | `/sub/` | 始终（若已开启） | 一组 `vless://`、`vmess://` 等链接的列表（当 `subEncrypt` 开启时进行 base64 编码）。 |
|
||||
| **JSON** | `/json/` | `subJsonEnable` | 完整的 Xray 客户端配置。 |
|
||||
| **Clash / Mihomo** | `/clash/` | `subClashEnable` | YAML 配置文件。 |
|
||||
|
||||
只有使用 **VLESS、VMess、Trojan、Shadowsocks 或 Hysteria2** 的已启用入站才会出现在订阅中，并按其订阅排序索引排列。使用 `Accept: text/html` 头（或 `?html=1`）请求 `/sub/` 会返回一个人类可读的信息页面，而非原始内容。
|
||||
|
||||
### Base64 与 JSON
|
||||
|
||||
**Base64** 内容只是用换行符连接的分享链接，经标准 base64 编码（通过 `subEncrypt` 开关控制）。**JSON** 内容则将每个客户端包装为一份完整的 Xray 客户端配置 —— 一套固定的骨架（本地 mixed/HTTP 入站、DNS、路由、策略）加上一个指向该入站的 `proxy` 出站。3x-ui **对单个客户端输出单个配置对象，对多个客户端输出数组**，使用扁平的出站 `settings` 形式（`address`/`port`/`id`，`level: 8`），并从 `streamSettings` 中剥离 `sockopt`。
|
||||
|
||||
## 响应头
|
||||
|
||||
订阅会返回兼容应用可读取的标准响应头：
|
||||
|
||||
- **`Subscription-Userinfo`** —— `upload`、`download`、`total`（字节；`total=0` 表示无限制）以及 `expire`（Unix 秒）。
|
||||
- **`Profile-Update-Interval`** —— 刷新间隔，以小时为单位（`subUpdates`）。
|
||||
- **`Profile-Title`**、**`Support-Url`**、**`Profile-Web-Page-Url`**、**`Announce`** —— 部分客户端会显示的可选品牌信息。
|
||||
|
||||
## 自定义页面模板
|
||||
|
||||
将 `subThemeDir` 指向一个包含自定义信息页模板的文件夹，即可为 HTML 订阅页面定制品牌。每条链接上的客户端备注完全支持模板化 —— 参见[分享链接 → 备注变量](/docs/config/share-links#remark-template-variables)。
|
||||
|
||||
<Callout type="info">
|
||||
将订阅服务器置于 TLS 之后（设置 `subCertFile`/`subKeyFile`，或使用
|
||||
[反向代理](/docs/operations/reverse-proxy)），以免订阅内容在传输过程中被暴露。
|
||||
</Callout>
|
||||
@@ -0,0 +1,184 @@
|
||||
---
|
||||
title: 传输方式与安全层
|
||||
description: 3x-ui 提供的每一种传输方式——TCP、mKCP、WebSocket、gRPC、HTTPUpgrade、XHTTP、Hysteria——及其设置项，外加 FinalMask 混淆、sockopt、TLS/REALITY、XTLS-Vision 以及 VLESS 加密。
|
||||
icon: Network
|
||||
---
|
||||
|
||||
**传输方式**决定数据包在客户端与服务器之间如何承载，**安全**层决定它们如何被加密和伪装，
|
||||
而 **FinalMask** 可以对剩下的部分进行混淆。面板只提供有效的组合；本页列出每一种传输方式的
|
||||
设置项以及面板强制执行的规则。
|
||||
|
||||
## 传输方式
|
||||
|
||||
在入站/出站表单中选择传输方式（入站的 `network`）。每种网络会在传输链路上写入它自己的
|
||||
设置键（`tcpSettings`、`kcpSettings`……）。
|
||||
|
||||
| 传输方式 | 设置键 | 适用场景 |
|
||||
| --------------- | --------------------- | ---------------------------------------------------------------------- |
|
||||
| **TCP (Raw)** | `tcpSettings` | 开销最低。是 REALITY + XTLS-Vision 以及回落的基础；可选的 HTTP/1.1 头部伪装。 |
|
||||
| **mKCP** | `kcpSettings` | 基于 **UDP** 的可靠协议——以带宽换取在丢包链路上更低的延迟。承载不了 TLS/REALITY。 |
|
||||
| **WebSocket** | `wsSettings` | 可穿透 CDN 和 HTTP 反向代理；兼容性极佳。 |
|
||||
| **gRPC** | `grpcSettings` | 基于 HTTP/2；多路复用效果好，通过 Nginx 代理也很干净。 |
|
||||
| **HTTPUpgrade** | `httpupgradeSettings` | 对 CDN 友好的 HTTP/1.1 `Upgrade`；比完整的 WebSocket 更轻量。 |
|
||||
| **XHTTP** | `xhttpSettings` | 现代的流多路复用 HTTP 传输；对 CDN 友好且支持 REALITY。 |
|
||||
| **Hysteria** | `hysteriaSettings` | 基于 QUIC 的传输——仅用于 **Hysteria2** 协议。 |
|
||||
|
||||
<Callout type="info">
|
||||
**WireGuard** 和 **Tunnel**（dokodemo-door）入站不提供传输方式选择器——它们的传输流
|
||||
只承载安全层/sockopt。早期的面板还提供过一个原始的 **HTTP/2 (`http`)** 传输；它已被
|
||||
**XHTTP** 取代，不再可供选择。
|
||||
</Callout>
|
||||
|
||||
### TCP (Raw) — `tcpSettings`
|
||||
|
||||
| 字段 | 默认值 | 含义 |
|
||||
| ------------------------------ | ------- | ----------------------------------------------------------------------- |
|
||||
| `acceptProxyProtocol` | `false` | 接受来自上游代理的 PROXY 协议，以保留真实的客户端 IP。 |
|
||||
| `header.type` | `none` | `none`，或 `http`（用于 HTTP/1.1 伪装）。 |
|
||||
| `header.request` / `response` | — | 当 `type: http` 时：方法、路径、版本以及一个模仿正常 HTTP 交互的头部映射。 |
|
||||
|
||||
### mKCP — `kcpSettings`
|
||||
|
||||
| 字段 | 默认值 | 含义 |
|
||||
| ------------------ | ----------- | ---------------------------------------------------------------- |
|
||||
| `mtu` | `1350` | 最大传输单元，单位字节（576–1460）。 |
|
||||
| `tti` | `20` | 传输时间间隔，单位毫秒（10–100）。越低 = 响应越快，开销越大。 |
|
||||
| `uplinkCapacity` | `5` | 上行带宽预算，单位 **MB/s**。 |
|
||||
| `downlinkCapacity` | `20` | 下行带宽预算，单位 **MB/s**。 |
|
||||
| `cwndMultiplier` | `1` | 拥塞窗口乘数；在优质链路上调高可以更激进地发送。 |
|
||||
| `maxSendingWindow` | `2097152` | 在途数据包数量的上限。 |
|
||||
|
||||
<Callout type="info">
|
||||
mKCP 无法承载 TLS 或 REALITY。要伪装它，可以添加一个 **FinalMask** UDP 掩码——
|
||||
`mkcp-legacy` 掩码重现了旧版 Xray 存储在 `kcpSettings.header`/`seed` 中的经典头部
|
||||
混淆（这些字段在这里已不复存在）。
|
||||
</Callout>
|
||||
|
||||
### WebSocket — `wsSettings`
|
||||
|
||||
| 字段 | 默认值 | 含义 |
|
||||
| --------------------- | ------- | ---------------------------------------------------------------- |
|
||||
| `path` | `/` | 请求路径——当多个服务共用一个主机时可据此路由。 |
|
||||
| `host` | _(无)_ | `Host` 头部覆盖（在 CDN 后面很有用）。 |
|
||||
| `headers` | `{}` | 额外的请求头。 |
|
||||
| `heartbeatPeriod` | `0` | keepalive ping 之间的秒数；`0` 表示禁用。 |
|
||||
| `acceptProxyProtocol` | `false` | 接受来自上游的 PROXY 协议。 |
|
||||
|
||||
### gRPC — `grpcSettings`
|
||||
|
||||
| 字段 | 默认值 | 含义 |
|
||||
| ------------- | ------- | --------------------------------------------------------- |
|
||||
| `serviceName` | _(无)_ | gRPC 服务路径；作用类似一个秘密路由。 |
|
||||
| `authority` | _(无)_ | `:authority` 伪头部覆盖。 |
|
||||
| `multiMode` | `false` | 在一条连接上多路复用多个流。 |
|
||||
|
||||
### HTTPUpgrade — `httpupgradeSettings`
|
||||
|
||||
| 字段 | 默认值 | 含义 |
|
||||
| --------------------- | ------- | --------------------------------------------- |
|
||||
| `path` | `/` | 请求路径。 |
|
||||
| `host` | _(无)_ | `Host` 头部覆盖。 |
|
||||
| `headers` | `{}` | 额外的请求头。 |
|
||||
| `acceptProxyProtocol` | `false` | 接受来自上游的 PROXY 协议。 |
|
||||
|
||||
HTTPUpgrade 是一次性的 HTTP/1.1 `Upgrade`，没有 WebSocket 帧——因此没有心跳字段。
|
||||
|
||||
### XHTTP — `xhttpSettings`
|
||||
|
||||
XHTTP（SplitHTTP）有一组庞大的字段；面板会填入合理的默认值。你通常会改动的那些：
|
||||
|
||||
| 字段 | 默认值 | 含义 |
|
||||
| ---------------------- | ----------- | ---------------------------------------------------------------------- |
|
||||
| `path` | `/` | 请求路径。 |
|
||||
| `host` | _(无)_ | `Host` 头部覆盖。 |
|
||||
| `mode` | `auto` | `auto`、`packet-up`、`stream-up` 或 `stream-one`。`packet-up` 对 CDN 兼容性最好；`stream-*` 延迟更低。 |
|
||||
| `xPaddingBytes` | `100-1000` | 用于模糊数据包大小的随机填充范围。 |
|
||||
| `scMaxBufferedPosts` | `30` | 服务端对上传 POST 的缓冲区。 |
|
||||
| `scStreamUpServerSecs` | `20-80` | stream-up 服务端窗口（短横线范围）。 |
|
||||
| `xmux` (`enableXmux`) | _(关闭)_ | 连接多路复用——`maxConcurrency` `16-32`、`maxConnections` `6`……为高并发场景开启。 |
|
||||
|
||||
Session-ID 字段（`sessionIDPlacement`、`sessionIDKey`、`sessionIDTable`、
|
||||
`sessionIDLength`）以及 `scMin/MaxEachPostBytes` 旋钮属于高级项；除非要匹配某个特定的
|
||||
上游，否则保持为空。
|
||||
|
||||
### Hysteria — `hysteriaSettings`
|
||||
|
||||
仅当协议为 **Hysteria2** 时有效。
|
||||
|
||||
| 字段 | 默认值 | 含义 |
|
||||
| ---------------- | ------- | ----------------------------------------------------------------------- |
|
||||
| `version` | `2` | Hysteria 协议版本。 |
|
||||
| `auth` | _(无)_ | 共享的认证字符串。 |
|
||||
| `udpIdleTimeout` | `60` | 空闲 UDP 会话被丢弃前的秒数（2–600）。 |
|
||||
| `masquerade` | — | 伪装成一个 HTTP/3 服务器：`type` 为 `proxy`/`file`/`string`，配合 `url`/`dir`/`content`，外加 `headers` 与 `statusCode`。 |
|
||||
|
||||
## FinalMask — 末层混淆
|
||||
|
||||
**FinalMask** 在传输方式和安全层**之后**包裹流量，因此它既能伪装那些承载不了 TLS 的
|
||||
传输（如 mKCP），也能在 TLS 之上再加一层外壳。掩码按方向分别配置：
|
||||
|
||||
- **TCP 掩码** — `fragment`、`sudoku`、`header-custom`。
|
||||
- **UDP 掩码** — `salamander`、`mkcp-legacy`、`header-custom`、`xdns`、`xicmp`、
|
||||
`noise`、`sudoku`、`realm`。（`mkcp-legacy` 重现旧版 mKCP 的头部混淆。）
|
||||
- **QUIC 参数** — 拥塞控制（`reno`、`bbr`、`brutal`、`force-brutal`）、Brutal 上/下行
|
||||
速率、`udpHop`（在一个范围内轮换 QUIC 端口以规避端口封锁）以及接收窗口调优。
|
||||
|
||||
FinalMask 取代了旧版 Xray 构建中暴露的、按每种传输各自实现的 `header`/`seed` 混淆。
|
||||
|
||||
## sockopt — 底层套接字选项
|
||||
|
||||
`sockopt` 与任意传输方式一同生效，用于调优底层套接字。最有用的字段：
|
||||
|
||||
| 字段 | 默认值 | 含义 |
|
||||
| --------------------- | ------- | ---------------------------------------------------------------- |
|
||||
| `tcpFastOpen` | `false` | 启用 TCP Fast Open。 |
|
||||
| `tcpcongestion` | `bbr` | 拥塞控制：`bbr`、`cubic` 或 `reno`。 |
|
||||
| `tproxy` | `off` | 透明代理模式：`off`、`redirect` 或 `tproxy`。 |
|
||||
| `domainStrategy` | `AsIs` | 地址如何解析（`UseIP`、`ForceIPv4`……）。 |
|
||||
| `dialerProxy` | _(无)_ | 将此出站的拨号链式经过另一个出站标签。 |
|
||||
| `interface` | _(无)_ | 绑定到指定的网络接口。 |
|
||||
| `mark` | `0` | 用于策略路由的 SO_MARK（`0` = 未设置）。 |
|
||||
|
||||
保持为 `0` 的数值字段不会写入传输链路，因此 Xray 会沿用操作系统的默认值。高级条目
|
||||
（`happyEyeballs`、`customSockopt[]`、keepalive 计时器）可用于特殊场景。
|
||||
|
||||
## 安全
|
||||
|
||||
安全层为 **`none`**、**`tls`** 或 **`reality`** 三者之一，并遵循以下适用规则：
|
||||
|
||||
| 安全层 | 适用的传输方式 | 适用的协议 |
|
||||
| ----------- | -------------------------------------------- | --------------------------------------------------- |
|
||||
| **TLS** | `tcp`, `ws`, `grpc`, `httpupgrade`, `xhttp` | VLESS、VMess、Trojan、Shadowsocks（Hysteria2 始终为 TLS） |
|
||||
| **REALITY** | `tcp`, `grpc`, `xhttp` | VLESS、Trojan |
|
||||
|
||||
mKCP 和 Hysteria 不使用单独的 TLS/REALITY 层——mKCP 以明文运行（用 FinalMask 混淆），
|
||||
而 Hysteria 在设计上就是 QUIC/TLS。REALITY 会把你的服务器伪装成一个真实的 TLS 站点，
|
||||
且无需证书——参见 [REALITY](/docs/config/reality)。
|
||||
|
||||
## XTLS-Vision 流控
|
||||
|
||||
`xtls-rprx-vision` 流控既快速又能抵抗 DPI。在以下任一情况下，它都可用于 **VLESS**：
|
||||
|
||||
- 传输方式为裸 **TCP**，安全层为 **TLS** 或 **REALITY**（经典的 XTLS-Vision），或者
|
||||
- 传输方式为 **XHTTP** 且启用了 VLESS 加密（见下文）。
|
||||
|
||||
请在 VLESS **客户端**上设置流控，而不是在入站上。在 TCP 上使用经典 Vision 时，一旦某个
|
||||
客户端使用该流控，面板还可以提供一个 **Vision seed**。
|
||||
|
||||
## VLESS 加密（ML-KEM）
|
||||
|
||||
VLESS 支持后量子**加密**（ML-KEM / `mlkem768x25519`），它存储在入站的 `decryption`
|
||||
（服务器）以及客户端的 `encryption`（用于生成链接）中。启用后，它会解锁在 XHTTP
|
||||
之上的 Vision 流控。请从面板的 VLESS 设置中生成密钥。
|
||||
|
||||
## Shadowsocks 加密方式
|
||||
|
||||
Shadowsocks 入站同时支持经典加密方式和 **Shadowsocks-2022**（以 `2022-blake3-`
|
||||
开头的方法名）。大多数加密方式支持多用户；`2022-blake3-chacha20-poly1305`
|
||||
为单用户。
|
||||
|
||||
<Callout type="info">
|
||||
传输方式和安全层必须在两端一致。客户端的分享链接会对它们进行编码（`type=ws`、
|
||||
`security=reality`、`flow=xtls-rprx-vision`……）——可使用
|
||||
[分享链接检查器](/docs/config/share-links)解码任意链接。
|
||||
</Callout>
|
||||
@@ -0,0 +1,107 @@
|
||||
---
|
||||
title: 首次登录
|
||||
description: 找到自动生成的 3x-ui 登录凭据，进入面板，启用双因素认证，并在对外暴露任何内容之前完成安全加固。
|
||||
icon: KeyRound
|
||||
---
|
||||
|
||||
安装完成后，你的第一项任务就是登录并**保护好面板**，然后再对外暴露其他任何内容。
|
||||
|
||||
## 进入面板
|
||||
|
||||
面板的访问地址为：
|
||||
|
||||
```text
|
||||
http://<your-server-ip>:<port>/<web-base-path>
|
||||
```
|
||||
|
||||
默认端口为 **2053**，默认根路径为 `/`——但脚本安装会**随机生成**用户名、密码、**端口**和 Web 根路径，因此请以你的实际值为准。
|
||||
|
||||
### 找到你的登录凭据
|
||||
|
||||
脚本安装在完成时会打印一份凭据摘要，同时也会将其写入一个仅 root 可读的文件：
|
||||
|
||||
```bash title="/etc/x-ui/install-result.env (mode 600)"
|
||||
XUI_USERNAME=...
|
||||
XUI_PASSWORD=...
|
||||
XUI_PANEL_PORT=...
|
||||
XUI_WEB_BASE_PATH=...
|
||||
XUI_ACCESS_URL=...
|
||||
XUI_API_TOKEN=...
|
||||
XUI_DB_TYPE=sqlite
|
||||
```
|
||||
|
||||
如果你错过了这些信息，可以使用管理工具：
|
||||
|
||||
```bash
|
||||
x-ui # menu → 11 (View Current Settings)
|
||||
x-ui settings # or the one-shot form
|
||||
```
|
||||
|
||||
对于 **Docker**，请从容器日志中读取生成的凭据，或运行 `docker exec -it <container> x-ui setting -show`。
|
||||
|
||||
<Callout type="warn">
|
||||
如果你的面板仍在使用默认的 `admin` / `admin`（面板会就此发出警告），请立即修改——在创建任何入站之前。
|
||||
</Callout>
|
||||
|
||||
## 修改凭据、端口和路径
|
||||
|
||||
使用非默认端口和一个长而随机的 **Web 根路径**，能让面板更难被发现。你可以在 UI 的**面板设置**中修改，或通过 `x-ui` 菜单修改：
|
||||
|
||||
- **7 — Reset Username & Password**（可同时禁用 2FA）
|
||||
- **8 — Reset Web Base Path**（将其随机化）
|
||||
- **10 — Change Port**
|
||||
|
||||
修改用户名或密码会**注销所有现有会话**；如果当时启用了双因素认证，还会将其禁用。
|
||||
|
||||
## 双因素认证（2FA）
|
||||
|
||||
3x-ui 支持 TOTP 双因素认证（兼容 Google Authenticator、Aegis 等）。在**面板设置**中启用即可——启用后，登录页面除了密码外还会要求输入一个 6 位验证码，并且开启该功能会强制所有人重新登录。你可以通过菜单的 **Reset Username & Password** 步骤，或使用 `x-ui setting -resetTwoFactor` 来禁用它。
|
||||
|
||||
## 内置登录保护
|
||||
|
||||
- **暴力破解限制：** 同一 IP/用户名在 5 分钟内登录失败 **5** 次后，该组合将被封锁 **15 分钟**。
|
||||
- **通用错误提示：** 无论是凭据错误还是 2FA 验证码错误，登录页面都只提示 "wrong username or password"，因此不会泄露任何信息。
|
||||
- **会话**有效期为 `sessionMaxAge` 分钟（默认 **360** = 6 小时），并在你修改凭据时失效。
|
||||
- 可在面板设置中启用 **LDAP** 作为认证回退方案。
|
||||
|
||||
## 必备加固清单
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### 设置高强度且唯一的凭据
|
||||
|
||||
将生成的（或 `admin/admin`）用户名和密码替换为高强度的值。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 使用非默认端口和随机根路径
|
||||
|
||||
将面板从 `2053` 端口移走，并将其置于一个长而随机的路径下提供服务。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 启用双因素认证
|
||||
|
||||
开启 2FA，这样即便密码泄露，单凭密码也无法获得访问权限。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 将面板置于 TLS 之后
|
||||
|
||||
使用有效的证书（通过 `x-ui` 菜单的 SSL 管理，或通过反向代理），使面板仅能通过 HTTPS 访问。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 用防火墙限制访问
|
||||
|
||||
只开放你确实需要的端口，并考虑按 IP 限制面板访问。
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
<Callout type="info">
|
||||
想让面板运行在一个干净的域名上并自动启用 HTTPS？请参阅
|
||||
[反向代理](/docs/operations/reverse-proxy)。如需更深入的加固，请参阅
|
||||
[安全](/docs/operations/security)。
|
||||
</Callout>
|
||||
@@ -0,0 +1,56 @@
|
||||
---
|
||||
title: 认识 3x-ui
|
||||
description: 面向 Xray-core 的 Web 面板——在浏览器中管理入站、协议、客户端与订阅，无需手动编辑 JSON。
|
||||
icon: Info
|
||||
---
|
||||
|
||||
**3x-ui** 是一个 Web 控制面板，运行在
|
||||
[Xray-core](https://github.com/XTLS/Xray-core)（真正负责转发流量的代理引擎）之上。
|
||||
你无需手动编写并重载 Xray 的 JSON 配置，而是通过浏览器仪表盘管理一切——入站、协议、客户端、证书、订阅。
|
||||
|
||||
## 各组件如何协同工作
|
||||
|
||||
<Mermaid
|
||||
chart={`
|
||||
flowchart LR
|
||||
Admin["Admin browser"] -->|HTTPS panel| Panel["3x-ui panel"]
|
||||
Panel -->|writes config, reloads| Xray["Xray-core"]
|
||||
Panel --- DB[("SQLite or PostgreSQL")]
|
||||
Clients["Client apps"] -->|VLESS / VMess / Trojan / ...| Xray
|
||||
Xray -->|proxied traffic| Internet["Internet"]
|
||||
`}
|
||||
/>
|
||||
|
||||
- **面板**是管理层：它将你的配置存储在数据库中，渲染仪表盘，暴露 REST API，并写入实时生效的 Xray 配置。
|
||||
- **Xray-core** 是数据平面：它在你的**入站**上终结客户端连接，并将流量转发到目标地址。
|
||||
- **客户端应用**（例如 v2rayNG、Clash/Mihomo、Hiddify 等）使用面板为每个客户端生成的分享链接或订阅进行连接。
|
||||
|
||||
## 它为你提供什么
|
||||
|
||||
- 一个面向所有主流协议的**入站**仪表盘——VLESS、VMess、Trojan、Shadowsocks、WireGuard、Hysteria2、SOCKS、HTTP 以及 Dokodemo-door。
|
||||
- 一流的 **REALITY** 与 **XTLS-Vision** 支持，带来隐蔽、快速的传输方式。
|
||||
- **按客户端**设置的流量配额、到期日期、IP 限制、在线状态，以及一键生成分享链接 / 二维码。
|
||||
- 支持 VLESS、Clash/Mihomo 和 JSON 格式的**订阅**。
|
||||
- 运维工具：**多节点**管理、**Telegram 机器人**、备份、基于 Fail2ban 的 IP 限制，以及一套有文档说明的 REST API。
|
||||
|
||||
## 底层原理
|
||||
|
||||
| 层级 | 技术 |
|
||||
| ------------ | -------------------------------------------- |
|
||||
| 后端 | Go，搭配 Gin Web 框架 |
|
||||
| 前端 | TypeScript / React |
|
||||
| 数据库 | SQLite（默认）或 PostgreSQL |
|
||||
| 代理引擎 | Xray-core（由面板内置并管理） |
|
||||
|
||||
默认的 SQLite 数据库位于 `/etc/x-ui/x-ui.db`，面板默认监听 **2053** 端口。两者均可配置——参见
|
||||
[首次登录](/docs/guide/first-login)和环境变量参考。
|
||||
|
||||
## 它适合谁
|
||||
|
||||
3x-ui 面向任何运行自己 Xray 服务器的人：从一台个人 VPS，到管理众多节点和客户端的运营者。如果你想拥有 Xray-core 的强大能力，又不想终日埋首于 JSON 配置文件，那么它正适合你。
|
||||
|
||||
<Callout type="info">
|
||||
3x-ui 是原始 X-UI 项目的增强分支，增加了更广泛的协议支持、更高的稳定性、按客户端的流量统计、多节点管理，以及许多提升使用体验的特性。
|
||||
</Callout>
|
||||
|
||||
准备好安装了吗？继续阅读[安装](/docs/guide/installation)。
|
||||
@@ -0,0 +1,146 @@
|
||||
---
|
||||
title: 安装
|
||||
description: 通过官方脚本（稳定版、指定版本或开发最新版）、无人值守 / cloud-init 或 Docker 安装 3x-ui，并选择 SQLite 或 PostgreSQL。
|
||||
icon: Download
|
||||
---
|
||||
|
||||
3x-ui 可运行在多种 Linux 发行版上——Ubuntu、Debian、Armbian、
|
||||
Fedora、CentOS、RHEL、AlmaLinux、Rocky Linux、Oracle Linux、Amazon Linux、
|
||||
Virtuozzo、Arch、Manjaro、openSUSE（Tumbleweed/Leap）、Alpine——以及 Windows，
|
||||
覆盖 `amd64`、`386`、`arm64`、`armv7`、`armv6`、`armv5` 和 `s390x` 架构。
|
||||
|
||||
<Callout type="warn">
|
||||
请以 **root** 身份（或使用 `sudo`）运行脚本安装程序。它会安装服务、
|
||||
配置 `x-ui` 管理命令，并将面板设为开机自启。
|
||||
</Callout>
|
||||
|
||||
<Tabs items={['Script', 'Docker', 'Manual']}>
|
||||
|
||||
<Tab value="Script">
|
||||
|
||||
官方脚本是推荐的安装方式。安装过程中，它会生成一个**随机**的用户名、密码和访问（Web 根）路径，配置服务，
|
||||
并安装 `x-ui` 管理命令。
|
||||
|
||||
```bash title="latest stable"
|
||||
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
|
||||
```
|
||||
|
||||
在命令后附加标签即可安装**指定版本**：
|
||||
|
||||
```bash title="pinned version"
|
||||
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.4.0
|
||||
```
|
||||
|
||||
传入 `dev-latest` 可安装滚动更新的**开发版**构建（来自 `main` 的最新逐提交预发布版本
|
||||
——并非稳定版）：
|
||||
|
||||
```bash title="rolling dev build"
|
||||
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest
|
||||
```
|
||||
|
||||
安装完成后，记下打印出的登录信息并运行 `x-ui` 打开
|
||||
[管理菜单](/docs/guide/update-uninstall#the-x-ui-management-menu)，然后
|
||||
继续阅读[首次登录](/docs/guide/first-login)。
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab value="Docker">
|
||||
|
||||
默认的 Compose 配置使用 SQLite。克隆仓库（或复制其
|
||||
`docker-compose.yml` 和 `Dockerfile`）并启动：
|
||||
|
||||
```bash
|
||||
docker compose up -d
|
||||
```
|
||||
|
||||
如需使用内置的 **PostgreSQL** 服务，请取消 `docker-compose.yml` 中两行 `XUI_DB_*`
|
||||
的注释，并使用对应 profile 启动：
|
||||
|
||||
```bash
|
||||
docker compose --profile postgres up -d
|
||||
```
|
||||
|
||||
更想用预构建镜像？它已发布到 GitHub Container Registry。该镜像内置了 Fail2ban（用于
|
||||
[IP 限制](/docs/operations/security)），其封禁通过 `iptables` 实现，因此需要 `NET_ADMIN`
|
||||
（IPv6 还需 `NET_RAW`）——
|
||||
否则封禁只会被记录，而不会实际生效：
|
||||
|
||||
```bash title="docker run"
|
||||
docker run -d \
|
||||
--cap-add=NET_ADMIN \
|
||||
--cap-add=NET_RAW \
|
||||
-e XUI_ENABLE_FAIL2BAN=true \
|
||||
-v $PWD/db/:/etc/x-ui/ \
|
||||
-v $PWD/cert/:/root/cert/ \
|
||||
--network=host \
|
||||
--restart=unless-stopped \
|
||||
--name 3x-ui \
|
||||
ghcr.io/mhsanaei/3x-ui:latest
|
||||
```
|
||||
|
||||
`db/` 卷保存 SQLite 数据库（`/etc/x-ui/x-ui.db`），`cert/`
|
||||
保存 TLS 证书，因此你的数据可在升级后保留。
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab value="Manual">
|
||||
|
||||
高级用户可从[发布页面](https://github.com/MHSanaei/3x-ui/releases)
|
||||
下载适用于你架构的发布归档包，解压后
|
||||
将二进制文件作为 systemd 服务运行。安装脚本正是将这些步骤自动化，
|
||||
因此除非你有特定理由要手动安装，否则更推荐使用脚本。
|
||||
|
||||
</Tab>
|
||||
|
||||
</Tabs>
|
||||
|
||||
## 构建你的安装命令
|
||||
|
||||
根据你的环境定制命令：
|
||||
|
||||
<InstallCommandBuilder />
|
||||
|
||||
## 选择数据库
|
||||
|
||||
你在安装时选择存储后端：
|
||||
|
||||
- **SQLite**（默认）——位于 `/etc/x-ui/x-ui.db` 的单个文件。无需任何配置。
|
||||
- **PostgreSQL**——适用于客户端数量庞大或多节点的部署。安装程序
|
||||
可以在本地安装它，也可以使用你提供的 DSN。
|
||||
|
||||
详情及 SQLite→PostgreSQL 迁移请参见[数据库](/docs/reference/database)。
|
||||
|
||||
## 无人值守 / cloud-init
|
||||
|
||||
安装程序也可**非交互式**运行，用于自动化。设置
|
||||
`XUI_NONINTERACTIVE=1`（或在无 TTY 的环境下运行），它便会全程零提示地完成
|
||||
端到端安装，生成随机凭据并写入
|
||||
`/etc/x-ui/install-result.env`：
|
||||
|
||||
```bash
|
||||
XUI_NONINTERACTIVE=1 bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
|
||||
```
|
||||
|
||||
仓库的 [`deploy/`](https://github.com/MHSanaei/3x-ui/tree/main/deploy)
|
||||
目录提供了现成的 **cloud-init** user-data，可用于在任意云平台上进行无人值守安装
|
||||
（Hetzner、AWS、DigitalOcean、Vultr、GCP、Azure、Oracle）。
|
||||
|
||||
## 后续步骤
|
||||
|
||||
<Cards>
|
||||
<Card
|
||||
title="首次登录"
|
||||
href="/docs/guide/first-login"
|
||||
description="访问面板并保护它的安全。"
|
||||
/>
|
||||
<Card
|
||||
title="更新与卸载"
|
||||
href="/docs/guide/update-uninstall"
|
||||
description="x-ui 菜单、更新与移除。"
|
||||
/>
|
||||
<Card
|
||||
title="REALITY"
|
||||
href="/docs/config/reality"
|
||||
description="配置你的第一个隐蔽入站。"
|
||||
/>
|
||||
</Cards>
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "快速开始",
|
||||
"icon": "Rocket",
|
||||
"pages": ["index", "installation", "first-login", "update-uninstall"]
|
||||
}
|
||||
@@ -0,0 +1,98 @@
|
||||
---
|
||||
title: 更新与卸载
|
||||
description: 使用 x-ui 菜单和命令行管理 3x-ui——更新（稳定版、开发版或指定旧版本）、修改设置，以及干净地卸载。
|
||||
icon: RefreshCw
|
||||
---
|
||||
|
||||
脚本安装完成后，`x-ui` 命令就是你的控制中心。不带参数运行它会进入交互式菜单，
|
||||
或传入一个子命令来执行单次操作。
|
||||
|
||||
```bash
|
||||
x-ui
|
||||
```
|
||||
|
||||
## The `x-ui` management menu
|
||||
|
||||
菜单（项 `0`–`28`）在顶部显示面板/Xray 状态，然后列出：
|
||||
|
||||
| # | Item | What it does |
|
||||
| ----- | -------------------------------------- | --------------------------------------------------------- |
|
||||
| 1 | Install | 从远程脚本（重新）安装 |
|
||||
| 2 | Update | 更新到最新的**稳定版** |
|
||||
| 3 | Update to Dev Channel (latest commit) | 更新到滚动的 `dev-latest` 构建 |
|
||||
| 4 | Update Menu | 仅更新 `x-ui` 菜单脚本 |
|
||||
| 5 | Legacy Version | 安装指定的旧版本（提示输入标签） |
|
||||
| 6 | Uninstall | 移除 3x-ui（见下文） |
|
||||
| 7 | Reset Username & Password | 设置新凭据；可选择禁用 2FA |
|
||||
| 8 | Reset Web Base Path | 随机生成 Web 根路径 |
|
||||
| 9 | Reset Settings | 重置面板设置（保留你的账户） |
|
||||
| 10 | Change Port | 修改面板端口 |
|
||||
| 11 | View Current Settings | 显示用户名、端口、Web 根路径、证书路径 |
|
||||
| 12–14 | Start / Stop / Restart | 控制面板服务 |
|
||||
| 15 | Restart Xray | 仅重新加载 Xray-core |
|
||||
| 16 | Check Status | 服务状态 |
|
||||
| 17 | Logs Management | 查看调试日志 / 清除日志 |
|
||||
| 18–19 | Enable / Disable Autostart | 开关开机自启 |
|
||||
| 20 | SSL Certificate Management | Let's Encrypt（域名或 IP）、自定义路径、续期/吊销 |
|
||||
| 21 | Cloudflare SSL Certificate | 通过 Cloudflare 的 DNS-01 通配符证书 |
|
||||
| 22 | IP Limit Management | 基于 Fail2ban 的按客户端 IP 限制 |
|
||||
| 23 | Firewall Management | `ufw` 安装与端口规则 |
|
||||
| 24 | SSH Port Forwarding Management | 将面板绑定到 localhost 并通过 SSH 隧道访问 |
|
||||
| 25 | PostgreSQL Management | 安装/迁移/管理 PostgreSQL |
|
||||
| 26 | Enable BBR | 开关 BBR 拥塞控制 sysctl |
|
||||
| 27 | Update Geo Files | 更新 geoip/geosite 数据（Loyalsoldier、IR、RU） |
|
||||
| 28 | Speedtest by Ookla | 运行 Ookla 测速 |
|
||||
| 0 | Exit | — |
|
||||
|
||||
其中部分功能有各自的页面：[SSL 证书](/docs/config/ssl-certificates)
|
||||
（项 20–21）、[安全](/docs/operations/security)（IP 限制、防火墙）、
|
||||
[反向代理](/docs/operations/reverse-proxy) 和 [面板设置](/docs/config/panel)
|
||||
（TLS），以及 [数据库](/docs/reference/database)（PostgreSQL）。
|
||||
|
||||
## 命令行子命令
|
||||
|
||||
对于脚本和快速操作，`x-ui` 也可直接接受一个子命令：
|
||||
|
||||
| Command | Action |
|
||||
| -------------------------- | --------------------------------------------------- |
|
||||
| `x-ui start` / `stop` / `restart` | 控制服务 |
|
||||
| `x-ui restart-xray` | 仅重新加载 Xray-core |
|
||||
| `x-ui status` | 显示状态 |
|
||||
| `x-ui settings` | 显示当前设置 |
|
||||
| `x-ui enable` / `disable` | 开关开机自启 |
|
||||
| `x-ui log` | 跟踪查看调试日志 |
|
||||
| `x-ui banlog` | 显示 Fail2ban 封禁日志 |
|
||||
| `x-ui update` | 更新到最新的稳定版 |
|
||||
| `x-ui update-dev` | 更新到滚动的 `dev-latest` 构建 |
|
||||
| `x-ui legacy` | 安装指定的旧版本（带提示） |
|
||||
| `x-ui update-all-geofiles` | 更新所有 geo 文件，如有变化则重启 |
|
||||
| `x-ui migrate-db --dsn …` | 将 SQLite → PostgreSQL 迁移（见 [数据库](/docs/reference/database)） |
|
||||
| `x-ui install` / `uninstall` | 安装 / 卸载 |
|
||||
|
||||
## 更新
|
||||
|
||||
- **稳定版：** 菜单选项 **2** 或 `x-ui update`。重新运行安装脚本
|
||||
同样会就地更新。
|
||||
- **开发版渠道：** 菜单选项 **3** 或 `x-ui update-dev`——即滚动的
|
||||
`dev-latest` 逐提交构建（并非稳定版）。
|
||||
- **指定的旧版本：** 菜单选项 **5**（Legacy Version）。
|
||||
|
||||
更新会保留你的数据库和设置。在跨大版本升级前请先做一次
|
||||
[备份](/docs/operations/backup-restore)。
|
||||
|
||||
<Callout type="info">
|
||||
Docker 用户的更新方式不同——拉取新镜像并重新创建容器
|
||||
（`docker compose pull && docker compose up -d`），而不是使用
|
||||
`x-ui` 更新命令。
|
||||
</Callout>
|
||||
|
||||
## 卸载
|
||||
|
||||
菜单选项 **6** 或 `x-ui uninstall`。它会停止并禁用服务、移除服务单元，
|
||||
并删除 `/etc/x-ui/` 和安装目录。如果面板使用的是本地安装的 PostgreSQL，
|
||||
它还会询问是否一并清除（这是一次单独的、不可逆的确认）。
|
||||
|
||||
<Callout type="warn">
|
||||
卸载会删除数据库（`/etc/x-ui/x-ui.db`）和你的配置。
|
||||
如果以后可能还需要，请先[备份](/docs/operations/backup-restore)。
|
||||
</Callout>
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: 参与贡献
|
||||
description: 如何为 3x-ui 贡献代码并翻译本文档。
|
||||
icon: GitPullRequestArrow
|
||||
---
|
||||
|
||||
3x-ui 由社区驱动。我们欢迎你为面板和这些文档做出贡献。
|
||||
|
||||
## 支持开发者
|
||||
|
||||
3x-ui 是免费且开源的，完全在公开环境中构建与维护。如果它对你有帮助，欢迎
|
||||
考虑支持其持续开发：
|
||||
|
||||
- 前往 [donate.sanaei.dev](https://donate.sanaei.dev/) **捐赠**——该页面会展示
|
||||
当前的资金**目标与进度**，你可以一同助力达成。
|
||||
- 为[仓库](https://github.com/MHSanaei/3x-ui)点 **Star**，并分享这个
|
||||
项目。
|
||||
- **加入** Telegram 频道 [@XrayUI](https://t.me/XrayUI)，关注最新动态并
|
||||
帮助其他用户。
|
||||
|
||||
## 为 3x-ui 贡献
|
||||
|
||||
- 阅读[仓库](https://github.com/MHSanaei/3x-ui)中项目的 `CONTRIBUTING.md`。
|
||||
- 为 bug 和功能请求提交 issue，并附上清晰的复现步骤。
|
||||
- 使用 Conventional Commits，并保持 pull request 聚焦单一主题。
|
||||
|
||||
## 翻译文档
|
||||
|
||||
本站点专为翻译而设计。内容位于 `content/docs/<locale>/` 目录下
|
||||
（`en`、`fa`、`ru`、`zh`），未翻译的页面会**回退到英文**，因此你
|
||||
可以逐步翻译。
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### 复制页面
|
||||
|
||||
将 `content/docs/en/...` 中的某个页面复制到你所用语言下的相同路径，例如
|
||||
`content/docs/fa/guide/installation.mdx`。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 只翻译正文文字
|
||||
|
||||
翻译正文以及 frontmatter 中的 `title`/`description`。**不要**翻译
|
||||
代码、命令、环境变量名、协议名或分享链接。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 注意文字方向
|
||||
|
||||
波斯语（`fa`）从右到左渲染。请保持代码块和链接从左到右
|
||||
（布局已自动处理这一点），并在两种方向下检查页面。
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
<Callout type="info">
|
||||
你所用语言缺少某个页面没有关系——它会回退到英文，而不会出现
|
||||
404。请优先翻译访问量最高的页面（安装、首次登录、
|
||||
REALITY）。
|
||||
</Callout>
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
title: 常见问题
|
||||
description: 关于 3x-ui 的常见问题 —— 许可协议、受支持的系统、数据库以及客户端。
|
||||
icon: CircleQuestionMark
|
||||
---
|
||||
|
||||
## 3x-ui 是免费且开源的吗？
|
||||
|
||||
是的。3x-ui 基于 GPL-3.0 许可协议开源，源代码托管在
|
||||
[GitHub](https://github.com/MHSanaei/3x-ui) 上。
|
||||
|
||||
## 它能运行在哪些系统上？
|
||||
|
||||
绝大多数主流 Linux 发行版（Ubuntu、Debian、CentOS/RHEL 及其衍生版、
|
||||
Fedora、Arch、Alpine 等），并支持 `amd64`、`arm64` 以及其他架构。
|
||||
它同样可以作为 Docker 容器运行。参见[安装](/docs/guide/installation)。
|
||||
|
||||
## 选 SQLite 还是 PostgreSQL？
|
||||
|
||||
SQLite 是默认选项，适用于大多数部署场景。对于规模更大的部署，可以通过
|
||||
`XUI_DB_TYPE=postgres` 和 `XUI_DB_DSN` 启用 PostgreSQL —— 参见
|
||||
[环境变量](/docs/reference/env-vars)。
|
||||
|
||||
## 哪些客户端应用可以配合使用？
|
||||
|
||||
任何兼容 Xray 的客户端 —— 例如 v2rayNG、Hiddify 以及 Clash/Mihomo。
|
||||
导入客户端的分享链接或 QR 码，或者使用
|
||||
[订阅](/docs/config/subscription)。
|
||||
|
||||
## 3x-ui 与 x-ui 有什么区别？
|
||||
|
||||
3x-ui 是原版 X-UI 项目的增强分支。它增加了更广泛的协议支持、更佳的稳定性、
|
||||
按客户端的流量统计、多节点管理、13 种语言的界面，以及众多提升使用体验的功能。
|
||||
|
||||
## 我该如何更新？
|
||||
|
||||
重新运行安装脚本（它会原地更新），或者拉取新的 Docker 镜像。
|
||||
参见[安装](/docs/guide/installation)以及
|
||||
[发布页面](https://github.com/MHSanaei/3x-ui/releases)。
|
||||
|
||||
## 我可以在哪里获取帮助？
|
||||
|
||||
加入官方 Telegram 频道 [@XrayUI](https://t.me/XrayUI) 获取公告与社区支持，
|
||||
或在 [GitHub](https://github.com/MHSanaei/3x-ui/issues) 上提交 issue。遇到常见问题时，
|
||||
请先查看[故障排查](/docs/help/troubleshooting)。
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "帮助",
|
||||
"icon": "LifeBuoy",
|
||||
"pages": ["troubleshooting", "faq", "migration", "contributing"]
|
||||
}
|
||||
@@ -0,0 +1,47 @@
|
||||
---
|
||||
title: 迁移
|
||||
description: 从 x-ui 迁移到 3x-ui、在服务器之间迁移，或在不同 3x-ui 版本之间迁移。
|
||||
icon: ArrowRightLeft
|
||||
---
|
||||
|
||||
## 在服务器之间迁移
|
||||
|
||||
迁移到新服务器本质上就是迁移数据库：
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### 备份旧服务器
|
||||
|
||||
复制数据库（默认位于 `/etc/x-ui/x-ui.db`）以及你的证书。参见
|
||||
[备份与恢复](/docs/operations/backup-restore)。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 在新服务器上安装 3x-ui
|
||||
|
||||
使用相同的安装方式以及兼容的版本。参见
|
||||
[安装](/docs/guide/installation)。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 恢复数据库
|
||||
|
||||
停止面板，将数据库放置到位，恢复证书，然后启动面板。同时更新所有与 IP/域名相关的设置。
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## 在不同 3x-ui 版本之间迁移
|
||||
|
||||
在同一后端内，升级通常只需重新运行安装程序或拉取新镜像即可——面板会自行迁移其数据库。如果是跨**大版本**升级，请先阅读
|
||||
[版本发布说明](https://github.com/MHSanaei/3x-ui/releases)
|
||||
并做好备份。
|
||||
|
||||
## 从 x-ui 迁移
|
||||
|
||||
将旧版 x-ui 面板的数据库直接导入 3x-ui **不受支持**——两者的数据库结构不同。请全新安装 3x-ui 并重新创建入站/客户端，同时从旧面板逐一导出分享链接。
|
||||
|
||||
<Callout type="warn">
|
||||
在任何迁移之前都要先做好备份，并在确认新服务器正常工作之前保持旧服务器继续运行。
|
||||
</Callout>
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: 故障排查
|
||||
description: 解决 3x-ui 常见问题——面板无法启动、502 错误、证书问题，以及客户端无法连接。
|
||||
icon: Wrench
|
||||
---
|
||||
|
||||
最常见问题的排查清单。如有疑问，请调高日志级别
|
||||
（`XUI_LOG_LEVEL=debug`），并检查面板和 Xray 日志。
|
||||
|
||||
## 面板无法启动
|
||||
|
||||
- 检查服务状态和日志（`x-ui` 菜单 → 状态/日志）。
|
||||
- 确认**面板端口未被**其他服务占用。
|
||||
- 验证数据库路径可写（默认为 `/etc/x-ui/x-ui.db`）。
|
||||
|
||||
## 502 / 通过代理时面板无法访问
|
||||
|
||||
- 确认面板确实在监听上游端口（例如 `2053`）。
|
||||
- 确保你的[反向代理](/docs/operations/reverse-proxy)传递了 WebSocket
|
||||
升级头，并指向正确的端口和**网站根路径（web base path）**。
|
||||
- 检查防火墙没有阻断代理 → 面板的连接。
|
||||
|
||||
## 证书问题
|
||||
|
||||
- 在签发证书之前，域名的 DNS 必须已指向服务器。
|
||||
- 80/443 端口必须可访问，以便进行 HTTP/TLS 验证（或改用 DNS 验证）。
|
||||
- 对于 REALITY，请记住它**无需证书**——问题通常出在错误的
|
||||
`dest`/SNI 上（参见 [REALITY 常见陷阱](/docs/config/reality)）。
|
||||
|
||||
## 客户端无法连接
|
||||
|
||||
- 使用[分享链接检查器](/docs/config/share-links)解码客户端的链接，
|
||||
并确认每一个参数。
|
||||
- 检查两端的**传输方式和安全设置是否匹配**。
|
||||
- 确认客户端未触及其**流量、到期时间或 IP 限制**。
|
||||
- 确认入站端口已在防火墙中开放。
|
||||
|
||||
<Callout type="info">
|
||||
仍然无法解决？搜索
|
||||
[GitHub issues](https://github.com/MHSanaei/3x-ui/issues)——你遇到的现象
|
||||
很可能此前已有人遇到过。
|
||||
</Callout>
|
||||
@@ -0,0 +1,51 @@
|
||||
---
|
||||
title: 3x-ui 文档
|
||||
description: 3x-ui 官方文档 —— 用于管理 Xray-core 服务器、代理、客户端与订阅的高级 Web 面板。
|
||||
icon: House
|
||||
---
|
||||
|
||||
**3x-ui** 是一个开源 Web 面板，用于部署和管理
|
||||
[Xray-core](https://github.com/XTLS/Xray-core) 服务器。它为入站、协议、客户端、流量统计、订阅
|
||||
等提供了现代化的控制台 —— 无需在命令行手动编辑 Xray JSON。
|
||||
|
||||
本站点是官方文档，同时提供一套**交互式、在浏览器内运行的工具**（配置生成器），它们完全运行在你的设备上 —— 任何数据都不会离开页面。
|
||||
|
||||
## 从这里开始
|
||||
|
||||
<Cards>
|
||||
<Card
|
||||
title="什么是 3x-ui？"
|
||||
href="/docs/guide"
|
||||
description="全景概览：Xray-core、面板，以及它适合谁使用。"
|
||||
/>
|
||||
<Card
|
||||
title="安装"
|
||||
href="/docs/guide/installation"
|
||||
description="通过脚本、Docker 或手动方式安装。"
|
||||
/>
|
||||
<Card
|
||||
title="首次登录"
|
||||
href="/docs/guide/first-login"
|
||||
description="访问面板，并在进行其他操作之前对其进行加固。"
|
||||
/>
|
||||
<Card
|
||||
title="REALITY"
|
||||
href="/docs/config/reality"
|
||||
description="搭配 XTLS-Vision 配置 VLESS + REALITY。"
|
||||
/>
|
||||
</Cards>
|
||||
|
||||
## 亮点
|
||||
|
||||
- **覆盖所有主流协议** —— VLESS、VMess、Trojan、Shadowsocks、WireGuard、
|
||||
Hysteria2、SOCKS、HTTP 以及 Dokodemo-door。
|
||||
- **REALITY 与 XTLS-Vision** —— 现代化、抗审查的传输方式。
|
||||
- **细粒度的客户端管理** —— 流量配额、到期日期、IP 限制、分享
|
||||
链接以及 QR 码。
|
||||
- **订阅** —— 支持 VLESS、Clash/Mihomo 以及 JSON 格式。
|
||||
- **运维能力** —— 多节点管理、Telegram 机器人、备份以及 REST API。
|
||||
|
||||
<Callout type="info">
|
||||
初次接触 Xray？请先阅读 [什么是 3x-ui？](/docs/guide) —— 它解释了面板、Xray-core 与
|
||||
你的客户端应用如何协同工作。
|
||||
</Callout>
|
||||
@@ -0,0 +1,3 @@
|
||||
{
|
||||
"pages": ["index", "guide", "config", "operations", "reference", "help"]
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
title: 备份与恢复
|
||||
description: 手动或通过 Telegram 机器人备份并恢复你的 3x-ui 数据库与证书。
|
||||
icon: DatabaseBackup
|
||||
---
|
||||
|
||||
你的全部配置——入站、客户端、各项设置——都存放在面板的数据库中。
|
||||
请定期备份，以便日后恢复或迁移。
|
||||
|
||||
## 需要备份的内容
|
||||
|
||||
- **数据库** —— 默认为位于 `/etc/x-ui/x-ui.db` 的 SQLite（如果你使用
|
||||
PostgreSQL 后端，则为对应的 PostgreSQL 数据库）。
|
||||
- **证书** —— `/root/cert/` 下的所有内容（或你存放 TLS 证书的任意位置）。
|
||||
|
||||
## 手动备份
|
||||
|
||||
你可以从面板的概览页下载备份，也可以直接从服务器上复制数据库文件：
|
||||
|
||||
```bash title="copy the SQLite database"
|
||||
cp /etc/x-ui/x-ui.db /root/x-ui-backup-$(date +%F).db
|
||||
```
|
||||
|
||||
要恢复时，先停止面板，把数据库文件放回原位，然后重新启动面板。
|
||||
|
||||
<Callout type="warn">
|
||||
尽量将备份恢复到与其来源**相同的主版本**上。跨主版本升级时，应让面板自行
|
||||
运行迁移，而不要强行套用旧的数据库结构。
|
||||
</Callout>
|
||||
|
||||
## Telegram 备份
|
||||
|
||||
如果你已配置 [Telegram 机器人](/docs/operations/telegram-bot)，启用
|
||||
**`tgBotBackup`** 即可在周期性报告中附带一份备份（按 `tgRunTime`
|
||||
计划执行，默认每天一次）。机器人会将**数据库**与 Xray 的
|
||||
**`config.json`** 一并发送到你的管理员聊天，从而让你始终拥有一份服务器之外的副本。
|
||||
管理员也可以从机器人的菜单中按需请求备份。
|
||||
|
||||
## SQLite 转储 / 恢复
|
||||
|
||||
`x-ui migrate-db` 命令可在 SQLite 数据库与纯文本 SQL 转储之间相互转换
|
||||
（便于检查，或在不同机器之间转移）：
|
||||
|
||||
```bash
|
||||
x-ui migrate-db --dump /root/x-ui.sql # SQLite -> SQL text
|
||||
x-ui migrate-db --restore /root/x-ui.sql # SQL text -> SQLite
|
||||
```
|
||||
|
||||
若想改用 PostgreSQL，请参阅[数据库](/docs/reference/database)。
|
||||
|
||||
<Callout type="info">
|
||||
无论采用哪种方式，都请将备份保存在**服务器之外**，并不时测试一次恢复——
|
||||
未经测试的备份算不上备份。
|
||||
</Callout>
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"title": "运维",
|
||||
"icon": "ServerCog",
|
||||
"pages": [
|
||||
"reverse-proxy",
|
||||
"multi-node",
|
||||
"outbounds-routing",
|
||||
"backup-restore",
|
||||
"telegram-bot",
|
||||
"security"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,79 @@
|
||||
---
|
||||
title: 多节点与受管主机
|
||||
description: 通过 API 令牌或 mTLS 信任、心跳检测以及针对每个入站的主机覆盖，从一个主控面板统一管理多个 3x-ui 面板并定制订阅。
|
||||
icon: Boxes
|
||||
---
|
||||
|
||||
3x-ui 可以从单个主控面板管理**多台服务器**，并借助**受管主机**覆盖每个入站在订阅中的通告方式。
|
||||
|
||||
## 节点
|
||||
|
||||
**节点**是另一个由你的主控面板通过其 API 管理的 3x-ui 面板。主控会轮询每个节点，并在一处集中展示其状态、版本、CPU/内存、运行时间和流量。
|
||||
|
||||
### 添加节点
|
||||
|
||||
提供节点的连接信息：
|
||||
|
||||
| 字段 | 说明 |
|
||||
| ----------------- | --------------------------------------------------------------------- |
|
||||
| **Name** | 唯一标签（例如 `de-fra-1`）。 |
|
||||
| **Scheme** | `https`（默认）或 `http`。 |
|
||||
| **Address / Port**| 节点面板的主机和端口。 |
|
||||
| **Base path** | 节点的 Web 基础路径。 |
|
||||
| **API token** | 在节点上创建的 Bearer 令牌（mTLS 模式下不需要）。 |
|
||||
| **TLS verify** | `verify`（默认）、`skip`、`pin`（固定证书 SHA-256）或 `mtls`。 |
|
||||
| **Inbound sync** | `all` 入站，或按标签 `selected`。 |
|
||||
| **Outbound tag** | 可选地**通过**指定的出站到达节点（出口桥接）。 |
|
||||
|
||||
当你添加或测试节点时，主控会验证其可达性。随后它每隔几秒发送一次**心跳**，更新节点的状态（`online` / `offline`）并发出 `node.up` / `node.down` 事件（参见 [Telegram 机器人](/docs/operations/telegram-bot)）。
|
||||
|
||||
<Callout type="info">
|
||||
节点通过每个面板稳定的 GUID 来标识，因此节点在重启后仍能保持其身份。节点本身也可以管理更多节点——主控会将这些以只读的**传递性**子节点形式呈现（Node 1 → Node 2 → Node 3）。
|
||||
</Callout>
|
||||
|
||||
### 主控与节点之间的双向 TLS（mTLS）
|
||||
|
||||
若要获得最强的信任，请使用 `tlsVerifyMode = mtls`（需要 `https`）：
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### 获取主控的 CA
|
||||
|
||||
在主控上获取其节点认证 CA 证书（CA 私钥永远不会离开面板）。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 在节点上信任该 CA
|
||||
|
||||
将该 CA 粘贴到节点的“受信任 CA”设置中。它会在节点下次重启时生效。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 将节点切换到 mTLS
|
||||
|
||||
将节点的 TLS 验证模式设置为 `mtls`。现在主控将出示客户端证书而非 API 令牌。
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
## 受管主机
|
||||
|
||||
**受管主机**是附加到入站上的覆盖端点。在订阅时，每个启用的主机会以其自己的地址、端口、TLS、SNI、主机头、路径等渲染出一条额外的分享链接 / 代理——取代旧的“外部代理”列表。可用于：
|
||||
|
||||
- 通过 **CDN**（Cloudflare）以不同的地址/SNI 为入站做前置，
|
||||
- 为单个入站通告**多个域名**或按地区划分的端点，
|
||||
- 为每个端点调整 ALPN、指纹、ECH 或 mux。
|
||||
|
||||
每个主机都有一个备注（支持相同的[模板变量](/docs/config/share-links#remark-template-variables)）、一个启用开关、一个排序顺序，并且可以**从特定订阅格式中排除**或**限定到特定节点**。
|
||||
|
||||
<Callout type="info">
|
||||
将地址/端口指向 CDN 的主机让你能够在客户端通过 CDN 边缘连接的同时，保持真实服务器地址的私密性。
|
||||
</Callout>
|
||||
|
||||
## 相关内容
|
||||
|
||||
<Cards>
|
||||
<Card title="出站与路由" href="/docs/operations/outbounds-routing" description="WARP、NordVPN、出站订阅以及路由。" />
|
||||
<Card title="订阅" href="/docs/config/subscription" description="主机如何塑造订阅输出。" />
|
||||
</Cards>
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: 出站与路由
|
||||
description: 在 3x-ui 中调整出口流量——WARP 与 NordVPN 出站、出站订阅（服务器池）、路由规则以及负载均衡器。
|
||||
icon: Route
|
||||
---
|
||||
|
||||
入站负责接受客户端；**出站**则决定客户端的流量接下来发往何处。
|
||||
3x-ui 可以让流量经由 Cloudflare WARP、NordVPN，或从订阅导入的任意出站池转发，
|
||||
并通过路由规则和均衡器在它们之间进行选择。
|
||||
|
||||
## 编辑出站与路由
|
||||
|
||||
出站、路由规则、均衡器、DNS 和日志全部都位于 **Xray
|
||||
配置**中（即你在 Xray 设置下编辑的配置模板）。这里没有单独的逐条规则界面——你直接编辑
|
||||
JSON，面板随后会重载 Xray。面板同时还提供**出站连通性测试**以及**路由测试**（向正在运行的核心查询某个目标地址将会使用哪个出站）。
|
||||
|
||||
## 构建出站
|
||||
|
||||
每个出站都是一个 JSON 对象，最多包含四个部分：一个 **`tag`**（供路由规则和均衡器引用）、
|
||||
一个 **`protocol`**、协议专属的 **`settings`**，以及——对于代理协议而言——必须与远程入站的
|
||||
传输方式和安全设置相匹配的 **`streamSettings`**。有两个出站几乎总是会存在：
|
||||
|
||||
- **`freedom`** 会将流量直接发往其目标地址——这是默认出口。
|
||||
可选地设置一个 `domainStrategy`（例如 `UseIP`）来控制主机名的解析方式。
|
||||
- **`blackhole`** 会丢弃流量。将不需要的目标地址（广告、种子下载）路由到这里。
|
||||
|
||||
```json title="freedom + blackhole"
|
||||
{
|
||||
"outbounds": [
|
||||
{ "tag": "direct", "protocol": "freedom", "settings": {} },
|
||||
{ "tag": "block", "protocol": "blackhole", "settings": {} }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**代理**出站（VLESS、VMess、Trojan、Shadowsocks）会转发到另一台
|
||||
服务器——便于进行链式代理或将部分流量发往境外。注意 3x-ui 所使用的各种线路
|
||||
结构：**VLESS 采用扁平形式**（`address`/`port`/`id`/`flow`/
|
||||
`encryption`），**VMess 使用 `settings.vnext[]`**，而 **Trojan/Shadowsocks 使用
|
||||
`settings.servers[]`**。`streamSettings` 必须与目标的
|
||||
[传输方式和安全设置](/docs/config/transports)保持一致。
|
||||
|
||||
在下方组装任意出站，并将生成的 JSON 粘贴到 **Xray 设置 → Outbounds** 中：
|
||||
|
||||
<OutboundGenerator />
|
||||
|
||||
## Cloudflare WARP
|
||||
|
||||
WARP 让你的服务器经由 Cloudflare 的网络出口。3x-ui 可以为你注册一个
|
||||
WARP 账户，并将其接入一个标签为 **`warp`** 的 WireGuard 出站：
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### 添加一个标签为 `warp` 的出站
|
||||
|
||||
在你的 Xray 配置中创建一个标签为 `warp` 的 WireGuard 出站。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 注册 WARP
|
||||
|
||||
在面板的 WARP 控制项中注册一个账户。3x-ui 会自动填入该出站的
|
||||
密钥、地址、保留字节以及对端端点。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### （可选）自动轮换 IP
|
||||
|
||||
设置一个 WARP 更新间隔（以**天**为单位），即可定期轮换 WARP IP。也可以
|
||||
应用一个免费许可证。
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
通过路由规则，将你希望的流量（例如特定域名）路由到 `warp` 出站。
|
||||
|
||||
## NordVPN
|
||||
|
||||
3x-ui 可以根据访问令牌获取 NordVPN（NordLynx/WireGuard）凭据（或
|
||||
直接接受一个私钥），并列出国家/服务器，从而让你构建一个
|
||||
NordVPN 出站。
|
||||
|
||||
## 出站订阅（服务器池）
|
||||
|
||||
**出站订阅**会导入一个远程分享链接订阅，并将其中的服务器作为**出站**注入到正在运行的
|
||||
Xray 配置中——而不会改动你已保存的模板。这是订阅一*池*服务器的推荐方式。
|
||||
|
||||
| 字段 | 默认值 | 含义 |
|
||||
| ---------------- | ------- | -------------------------------------------------------------- |
|
||||
| `url` | — | 远程订阅 URL（受 SSRF 防护）。 |
|
||||
| `tagPrefix` | auto | 生成的出站标签的前缀（例如 `hk-`）；留空 = `subN-`。 |
|
||||
| `updateInterval` | `600` | 刷新间隔，以**秒**为单位。 |
|
||||
| `prepend` | `false` | 将这些出站放在你的手动出站之前。 |
|
||||
| `priority` | `0` | 合并顺序（数值越小越靠前）。 |
|
||||
|
||||
导入的出站会获得**稳定的标签**：同一台服务器在多次刷新之间始终保持同一个标签，
|
||||
因此精确标签的路由/均衡器选择器会保持固定——而前缀/通配符选择器（例如 `hk-*`）
|
||||
则会随着服务器池的变化自动纳入新的服务器。支持的链接协议：`vmess`、`vless`、`trojan`、`ss`、
|
||||
`hysteria2`（`hy2`）以及 `wireguard`（`wg`）。面板会按定时器刷新已启用的
|
||||
订阅，并在内容发生变化时重载 Xray。
|
||||
|
||||
## 路由规则
|
||||
|
||||
**路由规则**决定每个连接使用哪个出站（或均衡器）。每条
|
||||
规则都是一个 `field` 类型的匹配器：设置 `domain`、`ip`、`port`、`network`、
|
||||
`protocol`、`inboundTag`、`sourceIP` 等中的任意项，并将其指向一个 **`outboundTag`** 或
|
||||
**`balancerTag`**。规则会**自上而下**逐条求值——**第一个匹配者胜出**，因此请
|
||||
将具体的规则放在通用规则之上。
|
||||
|
||||
```json title="route ads to blackhole, private IPs direct"
|
||||
{
|
||||
"routing": {
|
||||
"domainStrategy": "IPIfNonMatch",
|
||||
"rules": [
|
||||
{ "type": "field", "domain": ["geosite:category-ads-all"], "outboundTag": "block" },
|
||||
{ "type": "field", "ip": ["geoip:private"], "outboundTag": "direct" }
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 均衡器
|
||||
|
||||
**均衡器**通过一个**选择器**（标签前缀，包括来自出站订阅的通配符池）将出站分组，
|
||||
并以某种**策略**在它们之间分散流量或进行故障转移：
|
||||
|
||||
| 策略 | 选取…… | 是否需要监视器 |
|
||||
| ------------- | ----------------------------------------------- | ------------------------ |
|
||||
| `random` | 每个连接随机选取一个成员 | 否 |
|
||||
| `roundRobin` | 轮流选取各个成员 | 否 |
|
||||
| `leastPing` | 延迟最低的成员 | **`observatory`** |
|
||||
| `leastLoad` | 按采样负载最稳定的成员 | **`burstObservatory`** |
|
||||
|
||||
通过 `balancerTag` 从规则中引用某个均衡器。`leastPing` 和 `leastLoad`
|
||||
需要一个健康监视器，Xray 会将其放置在配置的**顶层**
|
||||
（`observatory` / `burstObservatory`，**而不是**放在 `routing` 内部）。面板可以
|
||||
报告均衡器状态，并允许你为测试目的将某个均衡器**覆盖**为特定的出站。
|
||||
|
||||
在此构建路由块——规则、均衡器以及配套的 observatory：
|
||||
|
||||
<RoutingBuilder />
|
||||
|
||||
<Callout type="warn">
|
||||
访问外部服务的出站在获取时会受到 SSRF 防护——默认情况下，私有/内部地址会被
|
||||
阻止，除非你按来源明确允许它们。
|
||||
</Callout>
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: 反向代理
|
||||
description: 通过 Nginx 或 Caddy 为 3x-ui 面板和订阅提供 Let's Encrypt TLS 保护。
|
||||
icon: Waypoints
|
||||
---
|
||||
|
||||
反向代理让你能够在一个简洁的域名上提供面板和订阅服务，并自动启用 HTTPS，同时将真实端口隐藏在 80/443 端口之后。更希望让面板直接终结 TLS？可以改用
|
||||
[`x-ui` SSL 菜单](/docs/config/ssl-certificates)来获取证书。
|
||||
|
||||
## 生成配置
|
||||
|
||||
<ReverseProxyGenerator />
|
||||
|
||||
<Callout type="info">
|
||||
面板使用 WebSocket 来实时更新，因此代理必须传递
|
||||
`Upgrade`/`Connection` 头（上面的 Nginx 输出已经做到了这一点）。Caddy
|
||||
会自动处理 WebSocket 升级。
|
||||
</Callout>
|
||||
|
||||
## Nginx + 证书
|
||||
|
||||
使用 Nginx 时，请通过 `certbot`（或 `acme.sh`）获取证书，并在 server 块中引用它：
|
||||
|
||||
```bash title="certbot"
|
||||
certbot certonly --nginx -d panel.example.com
|
||||
```
|
||||
|
||||
安装证书后请重新加载 Nginx，并设置自动续期（`certbot renew` 默认通过定时器运行）。
|
||||
|
||||
## Caddy
|
||||
|
||||
Caddy 会为你获取并续期证书——只需让 Caddyfile 指向面板，它便能正常工作：
|
||||
|
||||
```text title="Caddyfile"
|
||||
panel.example.com {
|
||||
reverse_proxy 127.0.0.1:2053
|
||||
}
|
||||
```
|
||||
|
||||
## 小贴士
|
||||
|
||||
- 即使在代理之后，也请保留面板的 **Web 基础路径**；这是纵深防御。
|
||||
- 如果你在代理处终结 TLS，可能需要在面板上设置 `XUI_SKIP_HSTS=true`——参见[环境变量参考](/docs/reference/env-vars)。
|
||||
- 也请代理[订阅](/docs/config/subscription)服务器，使其内容通过 HTTPS 提供。
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: 安全加固
|
||||
description: 加固 3x-ui——面板认证与 2FA、Fail2ban IP 限制、防火墙规则、BBR，以及保持更新。
|
||||
icon: ShieldCheck
|
||||
---
|
||||
|
||||
代理面板是高价值目标。几层加固措施就能带来很大改善。
|
||||
|
||||
## 面板加固
|
||||
|
||||
- 强而唯一的凭据，并启用**双因素认证**（TOTP）。
|
||||
- 使用非默认的面板端口，以及一个长且随机的 Web 根路径。
|
||||
- 为面板启用 TLS（直接启用，或通过[反向代理](/docs/operations/reverse-proxy)）。
|
||||
- 内置的**登录限制器**会在某个 IP/用户名于 5 分钟内连续 5 次登录失败后将其封锁
|
||||
（封锁 15 分钟），并且面板可以将自身的出站流量经由某个 outbound 路由出去。
|
||||
|
||||
完整的检查清单请参见[首次登录](/docs/guide/first-login)。
|
||||
|
||||
## Fail2ban 与 IP 限制
|
||||
|
||||
为每个客户端设置一个 **IP 限制**（参见[客户端](/docs/config/clients)），以限制同时使用的源
|
||||
IP 数量。限制的执行由 **Fail2ban** 负责，3x-ui 会为你安装并配置好它（脚本安装时默认启用，
|
||||
Docker 安装时通过 `XUI_ENABLE_FAIL2BAN=true` 启用）。
|
||||
|
||||
可从 `x-ui` 菜单（**22 — IP Limit Management**）进行管理：安装/配置、修改封锁时长
|
||||
（默认 **30 分钟**）、封锁/解封某个 IP、查看封锁日志，以及检查状态。其底层机制如下：
|
||||
|
||||
- 该 jail 名为 **`3x-ipl`**；封锁日志位于 `/var/log/x-ui/3xipl.log` 与
|
||||
`/var/log/x-ui/3xipl-banned.log`（也可通过 `x-ui banlog` 查看）。
|
||||
- 封锁覆盖所有 TCP/UDP，**但不包括**你的 SSH 端口和面板端口，因此封锁不会把你
|
||||
锁在服务器或面板之外。
|
||||
|
||||
<Callout type="warn">
|
||||
在 Docker 上，Fail2ban 使用 `iptables` 进行封锁，这需要 `NET_ADMIN`（以及
|
||||
`NET_RAW`）权能——`docker-compose.yml` 已授予这些权能。若使用裸的
|
||||
`docker run`，请添加 `--cap-add=NET_ADMIN --cap-add=NET_RAW`，否则封锁只会被
|
||||
记录但永远不会真正生效。
|
||||
</Callout>
|
||||
|
||||
## 防火墙
|
||||
|
||||
只开放你实际使用的端口：SSH、面板端口、订阅端口以及你的入站端口。`x-ui` 菜单
|
||||
（**23 — Firewall Management**）封装了 `ufw`，或者你也可以在此生成规则：
|
||||
|
||||
<FirewallRulesGenerator />
|
||||
|
||||
<Callout type="warn">
|
||||
在启用默认拒绝（default-deny）的防火墙之前，请确保 SSH 始终处于放行状态，否则你
|
||||
可能把自己锁在外面。请在保留第二个会话的情况下进行测试。
|
||||
</Callout>
|
||||
|
||||
## 网络调优（BBR）
|
||||
|
||||
`x-ui` 菜单（**26 — Enable BBR**）用于切换 Google 的 BBR 拥塞控制算法
|
||||
（`net.ipv4.tcp_congestion_control = bbr`、`net.core.default_qdisc = fq`），它在拥塞链路
|
||||
上通常能提升吞吐量。
|
||||
|
||||
## 保持更新
|
||||
|
||||
定期更新 3x-ui 和 Xray-core——安全修复会随新版本发布。请关注
|
||||
[发布页面](https://github.com/MHSanaei/3x-ui/releases)，并参见
|
||||
[更新与卸载](/docs/guide/update-uninstall)。
|
||||
@@ -0,0 +1,110 @@
|
||||
---
|
||||
title: Telegram 机器人
|
||||
description: 将 Telegram 机器人接入 3x-ui，实现命令交互、周期性报告、事件告警（登录、CPU、节点上线/下线）、备份以及客户端自助服务。
|
||||
icon: Send
|
||||
---
|
||||
|
||||
3x-ui 可以驱动一个 Telegram 机器人，用于监控、告警、备份和远程管理。
|
||||
管理员拥有完全的控制权；普通用户（通过 Telegram ID 关联）则可以
|
||||
查询自己的用量和链接。
|
||||
|
||||
<Callout type="info">
|
||||
想获取最新动态和社区支持？欢迎加入官方 Telegram 频道
|
||||
[@XrayUI](https://t.me/XrayUI)。它与下文中那个由你自行运行、用于管理自己面板的
|
||||
机器人是两回事。
|
||||
</Callout>
|
||||
|
||||
## 完成配置
|
||||
|
||||
<Steps>
|
||||
|
||||
<Step>
|
||||
### 创建机器人
|
||||
|
||||
向 [@BotFather](https://t.me/BotFather) 发送消息，发送 `/newbot`，然后复制**机器人令牌**（bot token）。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 查找你的 Telegram ID
|
||||
|
||||
获取你的数字 Telegram 用户 ID（机器人连接成功后，其自带的 `/id` 命令会显示该 ID）。
|
||||
这就是你的**管理员** ID。
|
||||
</Step>
|
||||
|
||||
<Step>
|
||||
### 配置面板
|
||||
|
||||
在面板设置中启用 Telegram 机器人，并填写**令牌**和**管理员聊天 ID**
|
||||
（多个时以逗号分隔）。保存后，再向你的机器人发送消息。
|
||||
</Step>
|
||||
|
||||
</Steps>
|
||||
|
||||
在将令牌、管理员 ID 和报告计划粘贴到面板之前，先对它们进行校验：
|
||||
|
||||
<TelegramSetupHelper />
|
||||
|
||||
## 命令
|
||||
|
||||
以下命令会出现在 Telegram 命令菜单中：`/start`、`/help`、`/status`、`/id`。
|
||||
其他命令：
|
||||
|
||||
| 命令 | 适用对象 | 作用 |
|
||||
| ------------------ | ------ | ------------------------------------------------------------ |
|
||||
| `/start`、`/help` | 任何人 | 问候语以及内联按钮菜单 |
|
||||
| `/status` | 任何人 | 确认机器人在线 |
|
||||
| `/id` | 任何人 | 显示你的 Telegram 数字 ID |
|
||||
| `/usage <arg>` | 两者 | 管理员可搜索客户端；用户则查询自己的用量 |
|
||||
| `/inbound <remark>`| 管理员 | 显示某个入站的详情 |
|
||||
| `/restart` | 管理员 | 重启 Xray |
|
||||
|
||||
管理员还可通过内联按钮使用一系列功能：服务器用量、按流量排序的报告、
|
||||
重置流量、数据库备份、封禁日志、列出入站/客户端、在线客户端、
|
||||
“即将耗尽”，以及完整的**添加客户端**向导。普通用户则可以使用按钮查看
|
||||
自己的用量、订阅链接、单条链接和 QR 码。
|
||||
|
||||
## 报告与告警
|
||||
|
||||
- **周期性报告** —— 按 `tgRunTime` 计划（默认 `@daily`），机器人会向管理员
|
||||
发送服务器用量（主机、版本、运行时长、负载、内存、在线客户端、流量）、
|
||||
一份已耗尽/即将到期的客户端列表，以及——如果启用了 `tgBotBackup`——
|
||||
一份数据库 + Xray 配置的备份。通过 Telegram ID 关联的客户端则会收到
|
||||
各自的到期/配额提醒。
|
||||
- **事件告警** —— 由 `tgEnabledEvents` 选定（默认 `login.attempt,cpu.high`）：
|
||||
|
||||
| 事件 | 触发时机 |
|
||||
| --------------- | ------------------------------------------------------- |
|
||||
| `login.attempt` | 面板登录成功或失败时（附带 IP 和用户名） |
|
||||
| `cpu.high` | CPU 超过 `tgCpu` 百分比（默认 80） |
|
||||
| `memory.high` | 内存超过 `tgMemory` 百分比（默认 80） |
|
||||
| `xray.crash` | Xray-core 崩溃 |
|
||||
| `outbound.down` / `outbound.up` | 某个出站断开 / 恢复 |
|
||||
| `node.down` / `node.up` | 某个节点下线 / 重新上线 |
|
||||
|
||||
提醒的提前时间由 `expireDiff`（到期前的天数）和 `trafficDiff`
|
||||
（剩余配额的 GB 数）决定；两者默认均为 `0`（关闭）。
|
||||
|
||||
## 设置
|
||||
|
||||
| 设置项 | 默认值 | 含义 |
|
||||
| -------------- | -------------------------- | ---------------------------------------------- |
|
||||
| `tgBotEnable` | `false` | 总开关。 |
|
||||
| `tgBotToken` | _（机密）_ | 机器人 API 令牌。 |
|
||||
| `tgBotChatId` | _（无）_ | 以逗号分隔的**管理员** Telegram ID。 |
|
||||
| `tgBotProxy` | _（无）_ | `socks5://`、`http://` 或 `https://` 代理。 |
|
||||
| `tgBotAPIServer` | _（默认）_ | 自定义 Telegram Bot API 服务器。 |
|
||||
| `tgRunTime` | `@daily` | 报告计划（cron / `@daily` / `@every …`）。 |
|
||||
| `tgBotBackup` | `false` | 在周期性报告中附带一份数据库备份。 |
|
||||
| `tgCpu` / `tgMemory` | `80` / `80` | CPU / 内存告警阈值（百分比）。 |
|
||||
| `tgLang` | `en-US` | 机器人语言。 |
|
||||
| `tgEnabledEvents` | `login.attempt,cpu.high`| 投递哪些事件。 |
|
||||
|
||||
<Callout type="warn">
|
||||
机器人令牌掌控着你的机器人——务必妥善保密，且只添加**可信的**管理员聊天 ID。
|
||||
登录告警绝不会包含密码。
|
||||
</Callout>
|
||||
|
||||
<Callout type="info">
|
||||
如果你更倾向于通过邮件接收告警，邮件（SMTP）通知会镜像同样的这些事件
|
||||
（`smtpEnabledEvents`）——请在面板设置中配置 SMTP。
|
||||
</Callout>
|
||||
@@ -0,0 +1,75 @@
|
||||
---
|
||||
title: API 令牌
|
||||
description: >-
|
||||
管理用于程序化认证的 Bearer 令牌（机器人、代表本节点操作的中心面板、CI）。每个令牌都有唯一的名称和一个启用标志——禁用即可在不删除的情况下吊销，删除则为永久吊销。令牌以
|
||||
SHA-256 哈希形式存储，明文仅在创建响应中返回一次——此后无法再次获取，因此请当场复制保存。在任意 /panel/api/* 请求中以
|
||||
<code>Authorization: Bearer <token></code> 的形式发送令牌——该令牌是一份完全管理员凭据。
|
||||
full: true
|
||||
_openapi:
|
||||
preload:
|
||||
- ./public/openapi.json
|
||||
toc:
|
||||
- depth: 2
|
||||
title: >-
|
||||
List every API token, enabled or not. The token value is never returned
|
||||
— only metadata.
|
||||
url: >-
|
||||
#list-every-api-token-enabled-or-not-the-token-value-is-never-returned--only-metadata
|
||||
- depth: 2
|
||||
title: >-
|
||||
Mint a new API token. Name must be unique and 1-64 characters; the token
|
||||
string is server-generated and returned only in this response — it is
|
||||
stored hashed and cannot be retrieved later.
|
||||
url: >-
|
||||
#mint-a-new-api-token-name-must-be-unique-and-1-64-characters-the-token-string-is-server-generated-and-returned-only-in-this-response--it-is-stored-hashed-and-cannot-be-retrieved-later
|
||||
- depth: 2
|
||||
title: >-
|
||||
Permanently delete a token. Any caller using it stops authenticating
|
||||
immediately.
|
||||
url: >-
|
||||
#permanently-delete-a-token-any-caller-using-it-stops-authenticating-immediately
|
||||
- depth: 2
|
||||
title: >-
|
||||
Toggle a token enabled/disabled without deleting it. Disabled tokens are
|
||||
rejected by checkAPIAuth on the next request.
|
||||
url: >-
|
||||
#toggle-a-token-enableddisabled-without-deleting-it-disabled-tokens-are-rejected-by-checkapiauth-on-the-next-request
|
||||
structuredData:
|
||||
headings:
|
||||
- content: >-
|
||||
List every API token, enabled or not. The token value is never
|
||||
returned — only metadata.
|
||||
id: >-
|
||||
list-every-api-token-enabled-or-not-the-token-value-is-never-returned--only-metadata
|
||||
- content: >-
|
||||
Mint a new API token. Name must be unique and 1-64 characters; the
|
||||
token string is server-generated and returned only in this response —
|
||||
it is stored hashed and cannot be retrieved later.
|
||||
id: >-
|
||||
mint-a-new-api-token-name-must-be-unique-and-1-64-characters-the-token-string-is-server-generated-and-returned-only-in-this-response--it-is-stored-hashed-and-cannot-be-retrieved-later
|
||||
- content: >-
|
||||
Permanently delete a token. Any caller using it stops authenticating
|
||||
immediately.
|
||||
id: >-
|
||||
permanently-delete-a-token-any-caller-using-it-stops-authenticating-immediately
|
||||
- content: >-
|
||||
Toggle a token enabled/disabled without deleting it. Disabled tokens
|
||||
are rejected by checkAPIAuth on the next request.
|
||||
id: >-
|
||||
toggle-a-token-enableddisabled-without-deleting-it-disabled-tokens-are-rejected-by-checkapiauth-on-the-next-request
|
||||
contents: []
|
||||
---
|
||||
|
||||
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
|
||||
|
||||
export default function Layout(props) {
|
||||
const { APIPage, OpenAPIPage } = props.components ?? {};
|
||||
// "APIPage" is the old name from v10, this allows both for backward compatibility
|
||||
const Comp = OpenAPIPage ?? APIPage;
|
||||
return (
|
||||
<>
|
||||
{props.children}
|
||||
<Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/panel/api/setting/apiTokens","method":"get"},{"path":"/panel/api/setting/apiTokens/create","method":"post"},{"path":"/panel/api/setting/apiTokens/delete/{id}","method":"post"},{"path":"/panel/api/setting/apiTokens/setEnabled/{id}","method":"post"}]} showTitle />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,72 @@
|
||||
---
|
||||
title: 身份验证
|
||||
description: >-
|
||||
支持两种身份验证模式。UI 会话使用登录端点设置的 Cookie。程序化客户端（机器人、脚本、远程面板）则使用从“设置 →
|
||||
安全 → API Token”获取的 Bearer token 进行身份验证。两者都适用于 /panel/api/* 下的所有端点。
|
||||
full: true
|
||||
_openapi:
|
||||
preload:
|
||||
- ./public/openapi.json
|
||||
toc:
|
||||
- depth: 2
|
||||
title: >-
|
||||
Authenticate with username + password and receive a session cookie.
|
||||
Required before any cookie-based API call.
|
||||
url: >-
|
||||
#authenticate-with-username--password-and-receive-a-session-cookie-required-before-any-cookie-based-api-call
|
||||
- depth: 2
|
||||
title: Clear the session cookie. Requires the CSRF header for browser sessions.
|
||||
url: '#clear-the-session-cookie-requires-the-csrf-header-for-browser-sessions'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Mint a CSRF token for the current session. The SPA replays it in the
|
||||
X-CSRF-Token header on unsafe requests. Bearer-token callers can skip
|
||||
this — the middleware short-circuits CSRF for authenticated API
|
||||
requests.
|
||||
url: >-
|
||||
#mint-a-csrf-token-for-the-current-session-the-spa-replays-it-in-the-x-csrf-token-header-on-unsafe-requests-bearer-token-callers-can-skip-this--the-middleware-short-circuits-csrf-for-authenticated-api-requests
|
||||
- depth: 2
|
||||
title: >-
|
||||
Returns whether 2FA is enabled on the panel — used by the login page to
|
||||
decide whether to show the OTP field.
|
||||
url: >-
|
||||
#returns-whether-2fa-is-enabled-on-the-panel--used-by-the-login-page-to-decide-whether-to-show-the-otp-field
|
||||
structuredData:
|
||||
headings:
|
||||
- content: >-
|
||||
Authenticate with username + password and receive a session cookie.
|
||||
Required before any cookie-based API call.
|
||||
id: >-
|
||||
authenticate-with-username--password-and-receive-a-session-cookie-required-before-any-cookie-based-api-call
|
||||
- content: >-
|
||||
Clear the session cookie. Requires the CSRF header for browser
|
||||
sessions.
|
||||
id: clear-the-session-cookie-requires-the-csrf-header-for-browser-sessions
|
||||
- content: >-
|
||||
Mint a CSRF token for the current session. The SPA replays it in the
|
||||
X-CSRF-Token header on unsafe requests. Bearer-token callers can skip
|
||||
this — the middleware short-circuits CSRF for authenticated API
|
||||
requests.
|
||||
id: >-
|
||||
mint-a-csrf-token-for-the-current-session-the-spa-replays-it-in-the-x-csrf-token-header-on-unsafe-requests-bearer-token-callers-can-skip-this--the-middleware-short-circuits-csrf-for-authenticated-api-requests
|
||||
- content: >-
|
||||
Returns whether 2FA is enabled on the panel — used by the login page
|
||||
to decide whether to show the OTP field.
|
||||
id: >-
|
||||
returns-whether-2fa-is-enabled-on-the-panel--used-by-the-login-page-to-decide-whether-to-show-the-otp-field
|
||||
contents: []
|
||||
---
|
||||
|
||||
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
|
||||
|
||||
export default function Layout(props) {
|
||||
const { APIPage, OpenAPIPage } = props.components ?? {};
|
||||
// "APIPage" is the old name from v10, this allows both for backward compatibility
|
||||
const Comp = OpenAPIPage ?? APIPage;
|
||||
return (
|
||||
<>
|
||||
{props.children}
|
||||
<Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/login","method":"post"},{"path":"/logout","method":"post"},{"path":"/csrf-token","method":"get"},{"path":"/getTwoFactorEnable","method":"post"}]} showTitle />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: 备份
|
||||
description: 与已配置的 Telegram 机器人进行交互的操作。
|
||||
full: true
|
||||
_openapi:
|
||||
preload:
|
||||
- ./public/openapi.json
|
||||
toc:
|
||||
- depth: 2
|
||||
title: >-
|
||||
向每个配置为管理员接收方的 Telegram 聊天发送一份最新的数据库备份。无请求体，无参数。
|
||||
url: >-
|
||||
#send-a-fresh-db-backup-to-every-telegram-chat-configured-as-an-admin-recipient-no-body-no-params
|
||||
structuredData:
|
||||
headings:
|
||||
- content: >-
|
||||
向每个配置为管理员接收方的 Telegram 聊天发送一份最新的数据库备份。无请求体，无参数。
|
||||
id: >-
|
||||
send-a-fresh-db-backup-to-every-telegram-chat-configured-as-an-admin-recipient-no-body-no-params
|
||||
contents: []
|
||||
---
|
||||
|
||||
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
|
||||
|
||||
export default function Layout(props) {
|
||||
const { APIPage, OpenAPIPage } = props.components ?? {};
|
||||
// "APIPage" is the old name from v10, this allows both for backward compatibility
|
||||
const Comp = OpenAPIPage ?? APIPage;
|
||||
return (
|
||||
<>
|
||||
{props.children}
|
||||
<Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/panel/api/backuptotgbot","method":"post"}]} showTitle />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,511 @@
|
||||
---
|
||||
title: 客户端
|
||||
description: >-
|
||||
将客户端作为一等实体进行管理，可将其挂载到一个或多个入站。单条客户端记录会驱动其所属
|
||||
每个入站中的 settings.clients 条目。相关端点位于 /panel/api/clients 之下。
|
||||
full: true
|
||||
_openapi:
|
||||
preload:
|
||||
- ./public/openapi.json
|
||||
toc:
|
||||
- depth: 2
|
||||
title: >-
|
||||
列出每个客户端及其挂载的入站 ID 和流量记录。reverse 字段若已设置，将以嵌套 JSON
|
||||
对象的形式返回（写入时仍接受旧版的 JSON 编码字符串形式）。
|
||||
url: >-
|
||||
#list-every-client-with-its-attached-inbound-ids-and-traffic-record-the-reverse-field-if-set-is-returned-as-a-nested-json-object-legacy-json-encoded-string-form-is-still-accepted-on-write
|
||||
- depth: 2
|
||||
title: >-
|
||||
在服务端对客户端进行筛选、排序和分页。每一项都是精简记录（不含
|
||||
uuid/password/auth/flow/security/reverse/tgId），因此客户端页面只需几 KB
|
||||
即可承载约 25 行，而无需返回整张表。响应中还包含一个基于完整数据库行集计算的汇总，
|
||||
这样在用户分页或筛选时仪表盘计数器仍保持稳定。每页上限为 200；可调用 /get/:email
|
||||
获取某个客户端用于编辑/信息弹窗的完整载荷。
|
||||
url: >-
|
||||
#filter-sort-and-paginate-clients-on-the-server-each-item-is-a-slim-row-no-uuidpasswordauthflowsecurityreversetgid-so-the-clients-page-can-ship-25-ish-rows-in-a-few-kb-instead-of-the-full-table-the-response-also-includes-a-summary-computed-across-the-full-db-row-set-so-dashboard-counters-stay-stable-as-the-user-paginates-or-filters-page-size-capped-at-200-fetch-getemail-to-obtain-the-full-per-client-payload-for-an-editinfo-modal
|
||||
- depth: 2
|
||||
title: >-
|
||||
按 email 获取单个客户端，包括它所挂载的入站 ID 和外部配置 ID。
|
||||
url: >-
|
||||
#fetch-one-client-by-email-including-the-inbound-ids-and-external-config-ids-it-is-attached-to
|
||||
- depth: 2
|
||||
title: >-
|
||||
在一次调用中创建一个新客户端并将其挂载到一个或多个入站。请求体为 JSON。各协议的密钥
|
||||
（VLESS/VMess 的 UUID、Trojan/Shadowsocks 的 password、Hysteria 的 auth）在
|
||||
省略时由服务端生成，因此调用方只需发送通用字段。
|
||||
url: >-
|
||||
#create-a-new-client-and-attach-it-to-one-or-more-inbounds-in-a-single-call-body-is-json-per-protocol-secrets-uuid-for-vlessvmess-password-for-trojanshadowsocks-auth-for-hysteria-are-generated-server-side-when-omitted-so-callers-can-send-only-the-universal-fields
|
||||
- depth: 2
|
||||
title: >-
|
||||
按 email 更新现有客户端。变更会传播到每个挂载的入站。请求体为 JSON 客户端载荷——
|
||||
请提供你希望保留的完整字段集（服务端会替换整条记录，而非局部更新）。
|
||||
url: >-
|
||||
#update-an-existing-client-by-email-changes-propagate-to-every-attached-inbound-body-is-the-json-client-payload--supply-the-full-set-of-fields-you-want-to-keep-the-server-replaces-the-row-it-does-not-patch
|
||||
- depth: 2
|
||||
title: >-
|
||||
按 email 删除客户端。将其从每个挂载的入站中移除，并删除其流量记录，除非传入
|
||||
keepTraffic=1。
|
||||
url: >-
|
||||
#delete-a-client-by-email-removes-it-from-every-attached-inbound-and-drops-its-traffic-record-unless-keeptraffic1-is-passed
|
||||
- depth: 2
|
||||
title: >-
|
||||
将现有客户端挂载到一个或多个额外的入站。请求体为 JSON。
|
||||
url: >-
|
||||
#attach-an-existing-client-to-one-or-more-additional-inbounds-body-is-json
|
||||
- depth: 2
|
||||
title: 在不删除客户端的前提下，将其从一个或多个入站上分离。
|
||||
url: '#detach-a-client-from-one-or-more-inbounds-without-deleting-the-client'
|
||||
- depth: 2
|
||||
title: >-
|
||||
替换某客户端的外部链接（在其订阅中呈现的按客户端分享链接和远程订阅 URL）。发送完整
|
||||
集合；服务端会替换所有记录。
|
||||
url: >-
|
||||
#replace-a-clients-external-links-per-client-share-links-and-remote-subscription-urls-surfaced-in-their-subscription-sends-the-full-set-the-server-replaces-all-rows
|
||||
- depth: 2
|
||||
title: >-
|
||||
全局重置每个客户端的上行/下行计数器。配额和到期时间不受影响。若有任何计数器实际发生
|
||||
变动，则触发一次 Xray 重启。
|
||||
url: >-
|
||||
#reset-the-updown-counters-for-every-client-globally-quotas-and-expiry-are-not-affected-triggers-an-xray-restart-if-any-counter-actually-moved
|
||||
- depth: 2
|
||||
title: >-
|
||||
删除所有流量配额已耗尽（在禁用重置时，used >= total）或已过期的客户端。返回删除
|
||||
数量，并在任一客户端位于运行中的入站时触发一次 Xray 重启。
|
||||
url: >-
|
||||
#delete-every-client-whose-traffic-quota-is-exhausted-used--total-when-reset-is-disabled-or-whose-expiry-has-passed-returns-the-deleted-count-and-triggers-an-xray-restart-when-any-client-was-on-a-running-inbound
|
||||
- depth: 2
|
||||
title: >-
|
||||
删除所有未挂载到任何入站的客户端，连同其流量记录、IP 日志和外部链接一并删除。适用于
|
||||
清理在其入站被移除后处于未挂载状态的客户端。返回删除数量。无法撤销。
|
||||
url: >-
|
||||
#delete-every-client-that-is-not-attached-to-any-inbound-along-with-its-traffic-record-ip-log-and-external-links-useful-for-clearing-clients-left-unattached-after-their-inbounds-were-removed-returns-the-deleted-count-cannot-be-undone
|
||||
- depth: 2
|
||||
title: >-
|
||||
以 {client, inboundIds} 数组的形式返回每个客户端——与 /bulkCreate 和 /import
|
||||
接受的形态相同——因此该载荷可原样回传至 /import。未挂载任何入站的客户端也会包含在内，
|
||||
其 inboundIds 列表为空。UI 会在 CodeMirror 查看器中展示（复制/下载）；程序化调用方
|
||||
则可在 obj 中获取该数组。
|
||||
url: >-
|
||||
#return-every-client-as-a-client-inboundids-array--the-same-shape-bulkcreate-and-import-accept--so-the-payload-round-trips-straight-back-through-import-clients-with-no-inbound-attachment-are-included-with-an-empty-inboundids-list-the-ui-shows-this-in-a-codemirror-viewer-copy--download-programmatic-callers-get-the-array-in-obj
|
||||
- depth: 2
|
||||
title: >-
|
||||
从 JSON 请求体 { "data": "<json>" } 导入客户端，其中 data 是由 /export 生成的
|
||||
字符串编码数组（[{client, inboundIds}]）。带有 inboundIds 的项会被创建并挂载到
|
||||
这些入站；inboundIds 列表为空的项会作为未挂载的客户端记录还原。已存在的 email
|
||||
绝不会被覆盖——它们会在 skipped 中返回。若任一目标入站处于运行中，则在最后触发一次
|
||||
Xray 重启。
|
||||
url: >-
|
||||
#import-clients-from-a-json-body--data-json--where-data-is-a-string-encoded-array-produced-by-export-client-inboundids-items-with-inboundids-are-created-and-attached-to-those-inbounds-items-with-an-empty-inboundids-list-are-restored-as-unattached-client-records-existing-emails-are-never-overwritten--they-are-returned-in-skipped-triggers-a-single-xray-restart-at-the-end-if-any-target-inbound-was-running
|
||||
- depth: 2
|
||||
title: >-
|
||||
在一次调用中为多个客户端调整到期时间和/或流量配额。addDays/addBytes 可为负值。对于
|
||||
到期无限（expiryTime=0）或流量无限（totalGB=0）的客户端，会跳过相应字段——批量延期
|
||||
绝不会将无限转为有限。可选的 flow 指令会为每个客户端设置 XTLS flow："none" 将其清除，
|
||||
"xtls-rprx-vision"/"xtls-rprx-vision-udp443" 在入站支持时将其设置（省略或传 "" 则
|
||||
保持不变）。返回调整数量和按 email 的跳过原因。
|
||||
url: >-
|
||||
#shift-expiry-andor-traffic-quota-for-many-clients-in-one-call-adddaysaddbytes-may-be-negative-clients-with-unlimited-expiry-expirytime0-or-unlimited-traffic-totalgb0-are-skipped-for-the-corresponding-field--bulk-extend-never-converts-unlimited-to-limited-the-optional-flow-directive-sets-the-xtls-flow-on-every-client-none-clears-it-xtls-rprx-visionxtls-rprx-vision-udp443-set-it-where-the-inbound-supports-it-omit-or--to-leave-it-unchanged-returns-the-adjusted-count-and-per-email-skip-reasons
|
||||
- depth: 2
|
||||
title: >-
|
||||
在一次调用中启用多个客户端。email 会按入站分组，并对每个入站执行一次读-改-写；运行中
|
||||
的 Xray（本地或远程节点）会被更新以添加每个用户。请注意，启用一个配额已耗尽或已过期的
|
||||
客户端只会翻转标志——流量循环会在下一个周期再次将其禁用。返回变更数量和按 email 的
|
||||
跳过原因。
|
||||
url: >-
|
||||
#enable-many-clients-in-one-call-emails-are-grouped-by-inbound-and-applied-with-a-single-read-modify-write-per-inbound-the-running-xray-local-or-remote-node-is-updated-to-add-each-user-note-that-enabling-a-client-whose-quota-is-exhausted-or-whose-expiry-has-passed-only-flips-the-flag--the-traffic-loop-will-disable-it-again-on-the-next-tick-returns-the-changed-count-and-per-email-skip-reasons
|
||||
- depth: 2
|
||||
title: >-
|
||||
在一次调用中禁用多个客户端。email 会按入站分组，并对每个入站执行一次读-改-写；运行中
|
||||
的 Xray（本地或远程节点）会被更新以移除每个用户。返回变更数量和按 email 的跳过原因。
|
||||
url: >-
|
||||
#disable-many-clients-in-one-call-emails-are-grouped-by-inbound-and-applied-with-a-single-read-modify-write-per-inbound-the-running-xray-local-or-remote-node-is-updated-to-remove-each-user-returns-the-changed-count-and-per-email-skip-reasons
|
||||
- depth: 2
|
||||
title: >-
|
||||
在一次调用中删除多个客户端。服务端会顺序处理该列表，使每次删除都能看到上一次删除已
|
||||
提交的状态——避免了面板侧按 email 扇出时存在的竞态。传入 keepTraffic=true 可在删除
|
||||
后保留 xray_client_traffic 记录。
|
||||
url: >-
|
||||
#delete-many-clients-in-one-call-the-server-processes-the-list-sequentially-so-each-delete-sees-the-committed-state-of-the-previous-one--avoids-the-race-the-per-email-fan-out-had-on-the-panel-side-pass-keeptraffictrue-to-retain-the-xray_client_traffic-rows-after-deletion
|
||||
- depth: 2
|
||||
title: >-
|
||||
在一次调用中创建多个客户端。请求体是一个 {client, inboundIds} 载荷的 JSON 数组
|
||||
——与 /add 接受的形态相同。各项按顺序处理；对于失败的项（例如 email 重复）会返回
|
||||
按 email 的跳过原因。若任一入站处于运行中，则在最后触发一次 Xray 重启。
|
||||
url: >-
|
||||
#create-many-clients-in-one-call-body-is-a-json-array-of-client-inboundids-payloads--the-same-shape-add-accepts-items-are-processed-sequentially-per-email-skip-reasons-are-returned-for-items-that-fail-eg-duplicate-email-triggers-a-single-xray-restart-at-the-end-if-any-inbound-was-running
|
||||
- depth: 2
|
||||
title: >-
|
||||
在一次调用中将多个客户端加入某个分组。会更新 clients.group_name，并在单个事务中修补
|
||||
每个所属入站的 settings JSON 内匹配的客户端条目。若该分组名尚不存在（无论是在
|
||||
client_groups 中还是作为派生标签），则会将其自动创建为持久化分组。要清除分组标签，
|
||||
请改用 /groups/bulkRemove。
|
||||
url: >-
|
||||
#add-many-clients-to-a-group-in-one-call-updates-clientsgroup_name-and-patches-the-matching-client-entry-inside-every-owning-inbounds-settings-json-in-a-single-transaction-if-the-group-name-does-not-yet-exist-in-client_groups-or-as-a-derived-label-it-is-auto-created-as-a-persistent-group-to-clear-the-group-label-use-groupsbulkremove-instead
|
||||
- depth: 2
|
||||
title: >-
|
||||
在一次调用中清除多个客户端的分组标签。与 /groups/bulkAdd 相反。客户端本身会保留——
|
||||
仅从 clients.group_name 以及每个所属入站的 settings JSON 中清除分组标签。若某分组的
|
||||
全部成员都被移除，该分组将变为空。
|
||||
url: >-
|
||||
#clear-the-group-label-on-many-clients-in-one-call-inverse-of-groupsbulkadd-clients-themselves-are-kept--only-the-group-label-is-cleared-from-clientsgroup_name-and-from-each-owning-inbounds-settings-json-groups-become-empty-if-all-their-members-are-removed
|
||||
- depth: 2
|
||||
title: >-
|
||||
在一次调用中将多个现有客户端挂载到多个入站。每个客户端都保留其身份
|
||||
（email/UUID/password/subId）以及共享的流量记录；所有客户端会在单次 AddInboundClient
|
||||
调用中被添加到一个目标入站。已存在于目标上的客户端会在 skipped 中报告。返回按 email 的
|
||||
attached/skipped/errors 列表，并在任一目标入站处于运行中时触发一次 Xray 重启。
|
||||
url: >-
|
||||
#attach-many-existing-clients-to-many-inbounds-in-one-call-each-client-keeps-its-identity-emailuuidpasswordsubid-and-a-shared-traffic-row-all-clients-are-added-to-a-target-inbound-in-a-single-addinboundclient-call-clients-already-present-on-a-target-are-reported-under-skipped-returns-per-email-attachedskippederrors-lists-and-triggers-a-single-xray-restart-if-any-target-inbound-was-running
|
||||
- depth: 2
|
||||
title: >-
|
||||
bulkAttach 的镜像操作：在一次调用中将多个现有客户端从多个入站上分离。对于每个 email，
|
||||
会将该客户端当前的入站集合与请求的集合取交集，并仅从这些入站上分离；客户端当前未挂载的
|
||||
(email, inbound) 组合会被静默地视为空操作。未挂载到任一请求入站的 email 会在 skipped
|
||||
中报告。即使客户端记录因此变为孤立，也会被保留——如需完全移除请使用 bulkDel。返回按
|
||||
email 的 detached/skipped/errors 列表，并在任一目标入站处于运行中时触发一次 Xray
|
||||
重启。
|
||||
url: >-
|
||||
#mirror-of-bulkattach-detach-many-existing-clients-from-many-inbounds-in-one-call-for-each-email-intersects-the-clients-current-inbounds-with-the-requested-set-and-detaches-from-those-only-email-inbound-pairs-where-the-client-is-not-currently-attached-are-silently-no-ops-emails-not-attached-to-any-of-the-requested-inbounds-are-reported-under-skipped-client-records-are-kept-even-if-they-become-orphaned--use-bulkdel-for-full-removal-returns-per-email-detachedskippederrors-lists-and-triggers-a-single-xray-restart-if-any-target-inbound-was-running
|
||||
- depth: 2
|
||||
title: >-
|
||||
在一次调用中将多个客户端的上行/下行计数器清零。循环执行单个重置流程，使每个客户端在其
|
||||
挂载的各入站上被重新启用，并推送到 Xray/远程节点。返回成功重置的客户端数量。
|
||||
url: >-
|
||||
#zero-updown-counters-for-many-clients-in-one-call-loops-the-single-reset-path-so-each-client-is-re-enabled-across-its-attached-inbounds-and-pushed-to-xrayremote-nodes-returns-the-count-of-successfully-reset-clients
|
||||
- depth: 2
|
||||
title: >-
|
||||
列出所有客户端分组及其成员数量。将持久化分组（client_groups 中的记录，包括空占位符）
|
||||
与当前在客户端上设置的去重后的 group_name 值合并。按字母顺序排序（不区分大小写）。
|
||||
url: >-
|
||||
#list-all-client-groups-with-their-member-counts-merges-persisted-groups-rows-in-client_groups-including-empty-placeholders-with-the-distinct-group_name-values-currently-set-on-clients-sorted-alphabetically-case-insensitive
|
||||
- depth: 2
|
||||
title: >-
|
||||
仅返回当前属于指定分组的客户端 email 列表。适用于将单个批量操作扇出到整个分组，而无需
|
||||
往返获取完整的客户端列表。
|
||||
url: >-
|
||||
#return-just-the-email-list-of-clients-that-currently-belong-to-the-given-group-useful-for-fanning-a-single-bulk-action-over-an-entire-group-without-round-tripping-the-full-client-list
|
||||
- depth: 2
|
||||
title: >-
|
||||
创建一个新的空（占位）分组。即使尚未向其添加任何客户端，该分组也会在客户端表单和筛选
|
||||
抽屉中变为可选。若已存在同名分组，则报错。
|
||||
url: >-
|
||||
#create-a-new-empty-placeholder-group-the-group-becomes-selectable-in-client-forms-and-the-filter-drawer-even-before-any-client-is-added-to-it-errors-if-a-group-with-the-same-name-already-exists
|
||||
- depth: 2
|
||||
title: >-
|
||||
重命名分组。新名称会应用到 client_groups 记录，并在单个事务中传播到每个匹配的客户端
|
||||
（包括 clients.group_name 以及每个所属入站的 settings JSON 内的客户端条目）。返回
|
||||
标签被更新的客户端数量。
|
||||
url: >-
|
||||
#rename-a-group-the-new-name-is-applied-to-the-client_groups-row-and-propagated-to-every-matching-client-both-clientsgroup_name-and-the-client-entry-inside-every-owning-inbounds-settings-json-in-a-single-transaction-returns-the-number-of-clients-whose-label-was-updated
|
||||
- depth: 2
|
||||
title: >-
|
||||
移除分组。删除 client_groups 记录，并从每个匹配的客户端清除分组标签（包括
|
||||
clients.group_name 以及入站 settings JSON）。客户端本身不会被删除——如需删除请先按
|
||||
分组筛选后再使用 /bulkDel。返回标签被清除的客户端数量。
|
||||
url: >-
|
||||
#remove-a-group-deletes-the-client_groups-row-and-clears-the-group-label-from-every-matching-client-both-clientsgroup_name-and-the-inbound-settings-json-the-clients-themselves-are-not-deleted--use-bulkdel-after-filtering-by-group-for-that-returns-the-count-of-clients-whose-label-was-cleared
|
||||
- depth: 2
|
||||
title: >-
|
||||
将单个客户端的上行/下行计数器清零。会在每个挂载的入站上重新启用该客户端，并将变更推送
|
||||
到 Xray（或远程节点），使流量耗尽的用户能够立即重新连接。
|
||||
url: >-
|
||||
#zero-out-a-single-clients-updown-counters-re-enables-the-client-across-every-attached-inbound-and-pushes-the-change-to-xray-or-the-remote-node-so-depleted-users-can-connect-again-immediately
|
||||
- depth: 2
|
||||
title: >-
|
||||
手动调整某个客户端的上传 + 下载计数器。适用于从外部计费系统迁移的场景。
|
||||
url: >-
|
||||
#manually-adjust-a-clients-upload--download-counters-useful-for-migrations-from-external-accounting-systems
|
||||
- depth: 2
|
||||
title: >-
|
||||
列出曾使用指定客户端凭据连接过的来源 IP。返回一个 "ip (timestamp)" 字符串数组。
|
||||
url: >-
|
||||
#list-source-ips-that-have-connected-with-the-given-clients-credentials-returns-an-array-of-ip-timestamp-strings
|
||||
- depth: 2
|
||||
title: 重置某个客户端已记录的 IP 列表。
|
||||
url: '#reset-the-recorded-ip-list-for-a-client'
|
||||
- depth: 2
|
||||
title: >-
|
||||
列出当前已连接的客户端 email（在心跳窗口内最近一次出现过），并跨所有节点去重。
|
||||
url: >-
|
||||
#list-the-emails-of-currently-connected-clients-last-seen-within-the-heartbeat-window-deduped-across-every-node
|
||||
- depth: 2
|
||||
title: >-
|
||||
按实际承载每个客户端的节点的 panelGuid 分组的在线客户端 email。本地面板使用自身的
|
||||
GUID；链路中（任意深度）的每个节点使用其自身的 GUID。让入站页面能将在线状态归因到
|
||||
真实节点，而非它所经由的中间节点。
|
||||
url: >-
|
||||
#online-client-emails-grouped-by-the-panelguid-of-the-node-that-physically-hosts-each-client-the-local-panel-uses-its-own-guid-each-node-at-any-depth-in-a-chain-uses-its-guid-lets-the-inbounds-page-attribute-online-status-to-the-real-node-instead-of-the-intermediate-one-it-syncs-through
|
||||
- depth: 2
|
||||
title: >-
|
||||
按观测到这些 IP 的节点的 panelGuid 分组的按客户端来源 IP。让中央面板能使用每个节点
|
||||
所见的真实访客 IP 来归因并执行按客户端的 IP 限制，而非它所经由的中间面板的地址。
|
||||
url: >-
|
||||
#per-client-source-ips-grouped-by-the-panelguid-of-the-node-that-observed-them-lets-the-central-panel-attribute-and-enforce-per-client-ip-limits-using-the-real-visitor-ips-each-node-sees-instead-of-the-address-of-the-intermediate-panel-it-syncs-through
|
||||
- depth: 2
|
||||
title: >-
|
||||
在心跳窗口内承载过流量的入站标签，按承载节点的 panelGuid 分组。与 onlinesByGuid 配合，
|
||||
使入站页面只在多入站客户端实际使用过的入站上将其标记为在线。不报告按入站活动的节点
|
||||
将被省略。
|
||||
url: >-
|
||||
#inbound-tags-that-carried-traffic-within-the-heartbeat-window-grouped-by-the-hosting-nodes-panelguid-pairs-with-onlinesbyguid-so-the-inbounds-page-only-marks-a-multi-inbound-client-online-on-the-inbounds-it-actually-used-nodes-that-do-not-report-per-inbound-activity-are-absent
|
||||
- depth: 2
|
||||
title: 客户端 email → 最近一次出现的 unix 时间戳的映射。
|
||||
url: '#map-of-client-email--last-seen-unix-timestamp'
|
||||
- depth: 2
|
||||
title: 按 email 标识的客户端的流量计数器。
|
||||
url: '#traffic-counters-for-a-client-identified-by-email'
|
||||
- depth: 2
|
||||
title: >-
|
||||
返回与该订阅 ID 匹配的客户端的每个协议 URL（vless://、vmess://、trojan://、ss://、
|
||||
hysteria://、hy2://）。结果集与 /sub/<subId> 相同，但以 JSON 数组形式返回——不含
|
||||
base64。当某入站设置了 streamSettings.externalProxy 时，每个外部代理会发出一条 URL。
|
||||
当该 subId 没有已启用的客户端时返回空数组。
|
||||
url: >-
|
||||
#return-every-protocol-url-vless-vmess-trojan-ss-hysteria-hy2-for-clients-matching-the-subscription-id-same-result-set-as-subsubid-but-as-a-json-array--no-base64-when-an-inbound-has-streamsettingsexternalproxy-set-one-url-is-emitted-per-external-proxy-empty-array-when-the-subid-has-no-enabled-clients
|
||||
- depth: 2
|
||||
title: >-
|
||||
返回单个客户端在所有挂载入站上的每个 URL——与面板 UI 中“复制 URL”按钮所复制的字符串
|
||||
相同。支持的协议：vmess、vless、trojan、shadowsocks、hysteria。若设置了
|
||||
streamSettings.externalProxy，则每个外部代理返回一条 URL。没有 URL 形式的协议
|
||||
（socks、http、mixed、wireguard、dokodemo、tunnel）不产生任何内容。
|
||||
url: >-
|
||||
#return-every-url-for-one-client-across-all-attached-inbounds--the-same-strings-the-copy-url-button-copies-in-the-panel-ui-supported-protocols-vmess-vless-trojan-shadowsocks-hysteria-if-streamsettingsexternalproxy-is-set-returns-one-url-per-external-proxy-protocols-without-a-url-form-socks-http-mixed-wireguard-dokodemo-tunnel-contribute-nothing
|
||||
structuredData:
|
||||
headings:
|
||||
- content: >-
|
||||
列出每个客户端及其挂载的入站 ID 和流量记录。reverse 字段若已设置，将以嵌套 JSON
|
||||
对象的形式返回（写入时仍接受旧版的 JSON 编码字符串形式）。
|
||||
id: >-
|
||||
list-every-client-with-its-attached-inbound-ids-and-traffic-record-the-reverse-field-if-set-is-returned-as-a-nested-json-object-legacy-json-encoded-string-form-is-still-accepted-on-write
|
||||
- content: >-
|
||||
在服务端对客户端进行筛选、排序和分页。每一项都是精简记录（不含
|
||||
uuid/password/auth/flow/security/reverse/tgId），因此客户端页面只需几 KB
|
||||
即可承载约 25 行，而无需返回整张表。响应中还包含一个基于完整数据库行集计算的汇总，
|
||||
这样在用户分页或筛选时仪表盘计数器仍保持稳定。每页上限为 200；可调用 /get/:email
|
||||
获取某个客户端用于编辑/信息弹窗的完整载荷。
|
||||
id: >-
|
||||
filter-sort-and-paginate-clients-on-the-server-each-item-is-a-slim-row-no-uuidpasswordauthflowsecurityreversetgid-so-the-clients-page-can-ship-25-ish-rows-in-a-few-kb-instead-of-the-full-table-the-response-also-includes-a-summary-computed-across-the-full-db-row-set-so-dashboard-counters-stay-stable-as-the-user-paginates-or-filters-page-size-capped-at-200-fetch-getemail-to-obtain-the-full-per-client-payload-for-an-editinfo-modal
|
||||
- content: >-
|
||||
按 email 获取单个客户端，包括它所挂载的入站 ID 和外部配置 ID。
|
||||
id: >-
|
||||
fetch-one-client-by-email-including-the-inbound-ids-and-external-config-ids-it-is-attached-to
|
||||
- content: >-
|
||||
在一次调用中创建一个新客户端并将其挂载到一个或多个入站。请求体为 JSON。各协议的密钥
|
||||
（VLESS/VMess 的 UUID、Trojan/Shadowsocks 的 password、Hysteria 的 auth）在
|
||||
省略时由服务端生成，因此调用方只需发送通用字段。
|
||||
id: >-
|
||||
create-a-new-client-and-attach-it-to-one-or-more-inbounds-in-a-single-call-body-is-json-per-protocol-secrets-uuid-for-vlessvmess-password-for-trojanshadowsocks-auth-for-hysteria-are-generated-server-side-when-omitted-so-callers-can-send-only-the-universal-fields
|
||||
- content: >-
|
||||
按 email 更新现有客户端。变更会传播到每个挂载的入站。请求体为 JSON 客户端载荷——
|
||||
请提供你希望保留的完整字段集（服务端会替换整条记录，而非局部更新）。
|
||||
id: >-
|
||||
update-an-existing-client-by-email-changes-propagate-to-every-attached-inbound-body-is-the-json-client-payload--supply-the-full-set-of-fields-you-want-to-keep-the-server-replaces-the-row-it-does-not-patch
|
||||
- content: >-
|
||||
按 email 删除客户端。将其从每个挂载的入站中移除，并删除其流量记录，除非传入
|
||||
keepTraffic=1。
|
||||
id: >-
|
||||
delete-a-client-by-email-removes-it-from-every-attached-inbound-and-drops-its-traffic-record-unless-keeptraffic1-is-passed
|
||||
- content: >-
|
||||
将现有客户端挂载到一个或多个额外的入站。请求体为 JSON。
|
||||
id: >-
|
||||
attach-an-existing-client-to-one-or-more-additional-inbounds-body-is-json
|
||||
- content: 在不删除客户端的前提下，将其从一个或多个入站上分离。
|
||||
id: detach-a-client-from-one-or-more-inbounds-without-deleting-the-client
|
||||
- content: >-
|
||||
替换某客户端的外部链接（在其订阅中呈现的按客户端分享链接和远程订阅 URL）。发送完整
|
||||
集合；服务端会替换所有记录。
|
||||
id: >-
|
||||
replace-a-clients-external-links-per-client-share-links-and-remote-subscription-urls-surfaced-in-their-subscription-sends-the-full-set-the-server-replaces-all-rows
|
||||
- content: >-
|
||||
全局重置每个客户端的上行/下行计数器。配额和到期时间不受影响。若有任何计数器实际发生
|
||||
变动，则触发一次 Xray 重启。
|
||||
id: >-
|
||||
reset-the-updown-counters-for-every-client-globally-quotas-and-expiry-are-not-affected-triggers-an-xray-restart-if-any-counter-actually-moved
|
||||
- content: >-
|
||||
删除所有流量配额已耗尽（在禁用重置时，used >= total）或已过期的客户端。返回删除
|
||||
数量，并在任一客户端位于运行中的入站时触发一次 Xray 重启。
|
||||
id: >-
|
||||
delete-every-client-whose-traffic-quota-is-exhausted-used--total-when-reset-is-disabled-or-whose-expiry-has-passed-returns-the-deleted-count-and-triggers-an-xray-restart-when-any-client-was-on-a-running-inbound
|
||||
- content: >-
|
||||
删除所有未挂载到任何入站的客户端，连同其流量记录、IP 日志和外部链接一并删除。适用于
|
||||
清理在其入站被移除后处于未挂载状态的客户端。返回删除数量。无法撤销。
|
||||
id: >-
|
||||
delete-every-client-that-is-not-attached-to-any-inbound-along-with-its-traffic-record-ip-log-and-external-links-useful-for-clearing-clients-left-unattached-after-their-inbounds-were-removed-returns-the-deleted-count-cannot-be-undone
|
||||
- content: >-
|
||||
以 {client, inboundIds} 数组的形式返回每个客户端——与 /bulkCreate 和 /import
|
||||
接受的形态相同——因此该载荷可原样回传至 /import。未挂载任何入站的客户端也会包含在内，
|
||||
其 inboundIds 列表为空。UI 会在 CodeMirror 查看器中展示（复制/下载）；程序化调用方
|
||||
则可在 obj 中获取该数组。
|
||||
id: >-
|
||||
return-every-client-as-a-client-inboundids-array--the-same-shape-bulkcreate-and-import-accept--so-the-payload-round-trips-straight-back-through-import-clients-with-no-inbound-attachment-are-included-with-an-empty-inboundids-list-the-ui-shows-this-in-a-codemirror-viewer-copy--download-programmatic-callers-get-the-array-in-obj
|
||||
- content: >-
|
||||
从 JSON 请求体 { "data": "<json>" } 导入客户端，其中 data 是由 /export 生成的
|
||||
字符串编码数组（[{client, inboundIds}]）。带有 inboundIds 的项会被创建并挂载到
|
||||
这些入站；inboundIds 列表为空的项会作为未挂载的客户端记录还原。已存在的 email
|
||||
绝不会被覆盖——它们会在 skipped 中返回。若任一目标入站处于运行中，则在最后触发一次
|
||||
Xray 重启。
|
||||
id: >-
|
||||
import-clients-from-a-json-body--data-json--where-data-is-a-string-encoded-array-produced-by-export-client-inboundids-items-with-inboundids-are-created-and-attached-to-those-inbounds-items-with-an-empty-inboundids-list-are-restored-as-unattached-client-records-existing-emails-are-never-overwritten--they-are-returned-in-skipped-triggers-a-single-xray-restart-at-the-end-if-any-target-inbound-was-running
|
||||
- content: >-
|
||||
在一次调用中为多个客户端调整到期时间和/或流量配额。addDays/addBytes 可为负值。对于
|
||||
到期无限（expiryTime=0）或流量无限（totalGB=0）的客户端，会跳过相应字段——批量延期
|
||||
绝不会将无限转为有限。可选的 flow 指令会为每个客户端设置 XTLS flow："none" 将其清除，
|
||||
"xtls-rprx-vision"/"xtls-rprx-vision-udp443" 在入站支持时将其设置（省略或传 "" 则
|
||||
保持不变）。返回调整数量和按 email 的跳过原因。
|
||||
id: >-
|
||||
shift-expiry-andor-traffic-quota-for-many-clients-in-one-call-adddaysaddbytes-may-be-negative-clients-with-unlimited-expiry-expirytime0-or-unlimited-traffic-totalgb0-are-skipped-for-the-corresponding-field--bulk-extend-never-converts-unlimited-to-limited-the-optional-flow-directive-sets-the-xtls-flow-on-every-client-none-clears-it-xtls-rprx-visionxtls-rprx-vision-udp443-set-it-where-the-inbound-supports-it-omit-or--to-leave-it-unchanged-returns-the-adjusted-count-and-per-email-skip-reasons
|
||||
- content: >-
|
||||
在一次调用中启用多个客户端。email 会按入站分组，并对每个入站执行一次读-改-写；运行中
|
||||
的 Xray（本地或远程节点）会被更新以添加每个用户。请注意，启用一个配额已耗尽或已过期的
|
||||
客户端只会翻转标志——流量循环会在下一个周期再次将其禁用。返回变更数量和按 email 的
|
||||
跳过原因。
|
||||
id: >-
|
||||
enable-many-clients-in-one-call-emails-are-grouped-by-inbound-and-applied-with-a-single-read-modify-write-per-inbound-the-running-xray-local-or-remote-node-is-updated-to-add-each-user-note-that-enabling-a-client-whose-quota-is-exhausted-or-whose-expiry-has-passed-only-flips-the-flag--the-traffic-loop-will-disable-it-again-on-the-next-tick-returns-the-changed-count-and-per-email-skip-reasons
|
||||
- content: >-
|
||||
在一次调用中禁用多个客户端。email 会按入站分组，并对每个入站执行一次读-改-写；运行中
|
||||
的 Xray（本地或远程节点）会被更新以移除每个用户。返回变更数量和按 email 的跳过原因。
|
||||
id: >-
|
||||
disable-many-clients-in-one-call-emails-are-grouped-by-inbound-and-applied-with-a-single-read-modify-write-per-inbound-the-running-xray-local-or-remote-node-is-updated-to-remove-each-user-returns-the-changed-count-and-per-email-skip-reasons
|
||||
- content: >-
|
||||
在一次调用中删除多个客户端。服务端会顺序处理该列表，使每次删除都能看到上一次删除已
|
||||
提交的状态——避免了面板侧按 email 扇出时存在的竞态。传入 keepTraffic=true 可在删除
|
||||
后保留 xray_client_traffic 记录。
|
||||
id: >-
|
||||
delete-many-clients-in-one-call-the-server-processes-the-list-sequentially-so-each-delete-sees-the-committed-state-of-the-previous-one--avoids-the-race-the-per-email-fan-out-had-on-the-panel-side-pass-keeptraffictrue-to-retain-the-xray_client_traffic-rows-after-deletion
|
||||
- content: >-
|
||||
在一次调用中创建多个客户端。请求体是一个 {client, inboundIds} 载荷的 JSON 数组
|
||||
——与 /add 接受的形态相同。各项按顺序处理；对于失败的项（例如 email 重复）会返回
|
||||
按 email 的跳过原因。若任一入站处于运行中，则在最后触发一次 Xray 重启。
|
||||
id: >-
|
||||
create-many-clients-in-one-call-body-is-a-json-array-of-client-inboundids-payloads--the-same-shape-add-accepts-items-are-processed-sequentially-per-email-skip-reasons-are-returned-for-items-that-fail-eg-duplicate-email-triggers-a-single-xray-restart-at-the-end-if-any-inbound-was-running
|
||||
- content: >-
|
||||
在一次调用中将多个客户端加入某个分组。会更新 clients.group_name，并在单个事务中修补
|
||||
每个所属入站的 settings JSON 内匹配的客户端条目。若该分组名尚不存在（无论是在
|
||||
client_groups 中还是作为派生标签），则会将其自动创建为持久化分组。要清除分组标签，
|
||||
请改用 /groups/bulkRemove。
|
||||
id: >-
|
||||
add-many-clients-to-a-group-in-one-call-updates-clientsgroup_name-and-patches-the-matching-client-entry-inside-every-owning-inbounds-settings-json-in-a-single-transaction-if-the-group-name-does-not-yet-exist-in-client_groups-or-as-a-derived-label-it-is-auto-created-as-a-persistent-group-to-clear-the-group-label-use-groupsbulkremove-instead
|
||||
- content: >-
|
||||
在一次调用中清除多个客户端的分组标签。与 /groups/bulkAdd 相反。客户端本身会保留——
|
||||
仅从 clients.group_name 以及每个所属入站的 settings JSON 中清除分组标签。若某分组的
|
||||
全部成员都被移除，该分组将变为空。
|
||||
id: >-
|
||||
clear-the-group-label-on-many-clients-in-one-call-inverse-of-groupsbulkadd-clients-themselves-are-kept--only-the-group-label-is-cleared-from-clientsgroup_name-and-from-each-owning-inbounds-settings-json-groups-become-empty-if-all-their-members-are-removed
|
||||
- content: >-
|
||||
在一次调用中将多个现有客户端挂载到多个入站。每个客户端都保留其身份
|
||||
（email/UUID/password/subId）以及共享的流量记录；所有客户端会在单次 AddInboundClient
|
||||
调用中被添加到一个目标入站。已存在于目标上的客户端会在 skipped 中报告。返回按 email 的
|
||||
attached/skipped/errors 列表，并在任一目标入站处于运行中时触发一次 Xray 重启。
|
||||
id: >-
|
||||
attach-many-existing-clients-to-many-inbounds-in-one-call-each-client-keeps-its-identity-emailuuidpasswordsubid-and-a-shared-traffic-row-all-clients-are-added-to-a-target-inbound-in-a-single-addinboundclient-call-clients-already-present-on-a-target-are-reported-under-skipped-returns-per-email-attachedskippederrors-lists-and-triggers-a-single-xray-restart-if-any-target-inbound-was-running
|
||||
- content: >-
|
||||
bulkAttach 的镜像操作：在一次调用中将多个现有客户端从多个入站上分离。对于每个 email，
|
||||
会将该客户端当前的入站集合与请求的集合取交集，并仅从这些入站上分离；客户端当前未挂载的
|
||||
(email, inbound) 组合会被静默地视为空操作。未挂载到任一请求入站的 email 会在 skipped
|
||||
中报告。即使客户端记录因此变为孤立，也会被保留——如需完全移除请使用 bulkDel。返回按
|
||||
email 的 detached/skipped/errors 列表，并在任一目标入站处于运行中时触发一次 Xray
|
||||
重启。
|
||||
id: >-
|
||||
mirror-of-bulkattach-detach-many-existing-clients-from-many-inbounds-in-one-call-for-each-email-intersects-the-clients-current-inbounds-with-the-requested-set-and-detaches-from-those-only-email-inbound-pairs-where-the-client-is-not-currently-attached-are-silently-no-ops-emails-not-attached-to-any-of-the-requested-inbounds-are-reported-under-skipped-client-records-are-kept-even-if-they-become-orphaned--use-bulkdel-for-full-removal-returns-per-email-detachedskippederrors-lists-and-triggers-a-single-xray-restart-if-any-target-inbound-was-running
|
||||
- content: >-
|
||||
在一次调用中将多个客户端的上行/下行计数器清零。循环执行单个重置流程，使每个客户端在其
|
||||
挂载的各入站上被重新启用，并推送到 Xray/远程节点。返回成功重置的客户端数量。
|
||||
id: >-
|
||||
zero-updown-counters-for-many-clients-in-one-call-loops-the-single-reset-path-so-each-client-is-re-enabled-across-its-attached-inbounds-and-pushed-to-xrayremote-nodes-returns-the-count-of-successfully-reset-clients
|
||||
- content: >-
|
||||
列出所有客户端分组及其成员数量。将持久化分组（client_groups 中的记录，包括空占位符）
|
||||
与当前在客户端上设置的去重后的 group_name 值合并。按字母顺序排序（不区分大小写）。
|
||||
id: >-
|
||||
list-all-client-groups-with-their-member-counts-merges-persisted-groups-rows-in-client_groups-including-empty-placeholders-with-the-distinct-group_name-values-currently-set-on-clients-sorted-alphabetically-case-insensitive
|
||||
- content: >-
|
||||
仅返回当前属于指定分组的客户端 email 列表。适用于将单个批量操作扇出到整个分组，而无需
|
||||
往返获取完整的客户端列表。
|
||||
id: >-
|
||||
return-just-the-email-list-of-clients-that-currently-belong-to-the-given-group-useful-for-fanning-a-single-bulk-action-over-an-entire-group-without-round-tripping-the-full-client-list
|
||||
- content: >-
|
||||
创建一个新的空（占位）分组。即使尚未向其添加任何客户端，该分组也会在客户端表单和筛选
|
||||
抽屉中变为可选。若已存在同名分组，则报错。
|
||||
id: >-
|
||||
create-a-new-empty-placeholder-group-the-group-becomes-selectable-in-client-forms-and-the-filter-drawer-even-before-any-client-is-added-to-it-errors-if-a-group-with-the-same-name-already-exists
|
||||
- content: >-
|
||||
重命名分组。新名称会应用到 client_groups 记录，并在单个事务中传播到每个匹配的客户端
|
||||
（包括 clients.group_name 以及每个所属入站的 settings JSON 内的客户端条目）。返回
|
||||
标签被更新的客户端数量。
|
||||
id: >-
|
||||
rename-a-group-the-new-name-is-applied-to-the-client_groups-row-and-propagated-to-every-matching-client-both-clientsgroup_name-and-the-client-entry-inside-every-owning-inbounds-settings-json-in-a-single-transaction-returns-the-number-of-clients-whose-label-was-updated
|
||||
- content: >-
|
||||
移除分组。删除 client_groups 记录，并从每个匹配的客户端清除分组标签（包括
|
||||
clients.group_name 以及入站 settings JSON）。客户端本身不会被删除——如需删除请先按
|
||||
分组筛选后再使用 /bulkDel。返回标签被清除的客户端数量。
|
||||
id: >-
|
||||
remove-a-group-deletes-the-client_groups-row-and-clears-the-group-label-from-every-matching-client-both-clientsgroup_name-and-the-inbound-settings-json-the-clients-themselves-are-not-deleted--use-bulkdel-after-filtering-by-group-for-that-returns-the-count-of-clients-whose-label-was-cleared
|
||||
- content: >-
|
||||
将单个客户端的上行/下行计数器清零。会在每个挂载的入站上重新启用该客户端，并将变更推送
|
||||
到 Xray（或远程节点），使流量耗尽的用户能够立即重新连接。
|
||||
id: >-
|
||||
zero-out-a-single-clients-updown-counters-re-enables-the-client-across-every-attached-inbound-and-pushes-the-change-to-xray-or-the-remote-node-so-depleted-users-can-connect-again-immediately
|
||||
- content: >-
|
||||
手动调整某个客户端的上传 + 下载计数器。适用于从外部计费系统迁移的场景。
|
||||
id: >-
|
||||
manually-adjust-a-clients-upload--download-counters-useful-for-migrations-from-external-accounting-systems
|
||||
- content: >-
|
||||
列出曾使用指定客户端凭据连接过的来源 IP。返回一个 "ip (timestamp)" 字符串数组。
|
||||
id: >-
|
||||
list-source-ips-that-have-connected-with-the-given-clients-credentials-returns-an-array-of-ip-timestamp-strings
|
||||
- content: 重置某个客户端已记录的 IP 列表。
|
||||
id: reset-the-recorded-ip-list-for-a-client
|
||||
- content: >-
|
||||
列出当前已连接的客户端 email（在心跳窗口内最近一次出现过），并跨所有节点去重。
|
||||
id: >-
|
||||
list-the-emails-of-currently-connected-clients-last-seen-within-the-heartbeat-window-deduped-across-every-node
|
||||
- content: >-
|
||||
按实际承载每个客户端的节点的 panelGuid 分组的在线客户端 email。本地面板使用自身的
|
||||
GUID；链路中（任意深度）的每个节点使用其自身的 GUID。让入站页面能将在线状态归因到
|
||||
真实节点，而非它所经由的中间节点。
|
||||
id: >-
|
||||
online-client-emails-grouped-by-the-panelguid-of-the-node-that-physically-hosts-each-client-the-local-panel-uses-its-own-guid-each-node-at-any-depth-in-a-chain-uses-its-guid-lets-the-inbounds-page-attribute-online-status-to-the-real-node-instead-of-the-intermediate-one-it-syncs-through
|
||||
- content: >-
|
||||
按观测到这些 IP 的节点的 panelGuid 分组的按客户端来源 IP。让中央面板能使用每个节点
|
||||
所见的真实访客 IP 来归因并执行按客户端的 IP 限制，而非它所经由的中间面板的地址。
|
||||
id: >-
|
||||
per-client-source-ips-grouped-by-the-panelguid-of-the-node-that-observed-them-lets-the-central-panel-attribute-and-enforce-per-client-ip-limits-using-the-real-visitor-ips-each-node-sees-instead-of-the-address-of-the-intermediate-panel-it-syncs-through
|
||||
- content: >-
|
||||
在心跳窗口内承载过流量的入站标签，按承载节点的 panelGuid 分组。与 onlinesByGuid 配合，
|
||||
使入站页面只在多入站客户端实际使用过的入站上将其标记为在线。不报告按入站活动的节点
|
||||
将被省略。
|
||||
id: >-
|
||||
inbound-tags-that-carried-traffic-within-the-heartbeat-window-grouped-by-the-hosting-nodes-panelguid-pairs-with-onlinesbyguid-so-the-inbounds-page-only-marks-a-multi-inbound-client-online-on-the-inbounds-it-actually-used-nodes-that-do-not-report-per-inbound-activity-are-absent
|
||||
- content: 客户端 email → 最近一次出现的 unix 时间戳的映射。
|
||||
id: map-of-client-email--last-seen-unix-timestamp
|
||||
- content: 按 email 标识的客户端的流量计数器。
|
||||
id: traffic-counters-for-a-client-identified-by-email
|
||||
- content: >-
|
||||
返回与该订阅 ID 匹配的客户端的每个协议 URL（vless://、vmess://、trojan://、ss://、
|
||||
hysteria://、hy2://）。结果集与 /sub/<subId> 相同，但以 JSON 数组形式返回——不含
|
||||
base64。当某入站设置了 streamSettings.externalProxy 时，每个外部代理会发出一条 URL。
|
||||
当该 subId 没有已启用的客户端时返回空数组。
|
||||
id: >-
|
||||
return-every-protocol-url-vless-vmess-trojan-ss-hysteria-hy2-for-clients-matching-the-subscription-id-same-result-set-as-subsubid-but-as-a-json-array--no-base64-when-an-inbound-has-streamsettingsexternalproxy-set-one-url-is-emitted-per-external-proxy-empty-array-when-the-subid-has-no-enabled-clients
|
||||
- content: >-
|
||||
返回单个客户端在所有挂载入站上的每个 URL——与面板 UI 中“复制 URL”按钮所复制的字符串
|
||||
相同。支持的协议：vmess、vless、trojan、shadowsocks、hysteria。若设置了
|
||||
streamSettings.externalProxy，则每个外部代理返回一条 URL。没有 URL 形式的协议
|
||||
（socks、http、mixed、wireguard、dokodemo、tunnel）不产生任何内容。
|
||||
id: >-
|
||||
return-every-url-for-one-client-across-all-attached-inbounds--the-same-strings-the-copy-url-button-copies-in-the-panel-ui-supported-protocols-vmess-vless-trojan-shadowsocks-hysteria-if-streamsettingsexternalproxy-is-set-returns-one-url-per-external-proxy-protocols-without-a-url-form-socks-http-mixed-wireguard-dokodemo-tunnel-contribute-nothing
|
||||
contents: []
|
||||
---
|
||||
|
||||
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
|
||||
|
||||
export default function Layout(props) {
|
||||
const { APIPage, OpenAPIPage } = props.components ?? {};
|
||||
// "APIPage" is the old name from v10, this allows both for backward compatibility
|
||||
const Comp = OpenAPIPage ?? APIPage;
|
||||
return (
|
||||
<>
|
||||
{props.children}
|
||||
<Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/panel/api/clients/list","method":"get"},{"path":"/panel/api/clients/list/paged","method":"get"},{"path":"/panel/api/clients/get/{email}","method":"get"},{"path":"/panel/api/clients/add","method":"post"},{"path":"/panel/api/clients/update/{email}","method":"post"},{"path":"/panel/api/clients/del/{email}","method":"post"},{"path":"/panel/api/clients/{email}/attach","method":"post"},{"path":"/panel/api/clients/{email}/detach","method":"post"},{"path":"/panel/api/clients/{email}/externalLinks","method":"post"},{"path":"/panel/api/clients/resetAllTraffics","method":"post"},{"path":"/panel/api/clients/delDepleted","method":"post"},{"path":"/panel/api/clients/delOrphans","method":"post"},{"path":"/panel/api/clients/export","method":"get"},{"path":"/panel/api/clients/import","method":"post"},{"path":"/panel/api/clients/bulkAdjust","method":"post"},{"path":"/panel/api/clients/bulkEnable","method":"post"},{"path":"/panel/api/clients/bulkDisable","method":"post"},{"path":"/panel/api/clients/bulkDel","method":"post"},{"path":"/panel/api/clients/bulkCreate","method":"post"},{"path":"/panel/api/clients/groups/bulkAdd","method":"post"},{"path":"/panel/api/clients/groups/bulkRemove","method":"post"},{"path":"/panel/api/clients/bulkAttach","method":"post"},{"path":"/panel/api/clients/bulkDetach","method":"post"},{"path":"/panel/api/clients/bulkResetTraffic","method":"post"},{"path":"/panel/api/clients/groups","method":"get"},{"path":"/panel/api/clients/groups/{name}/emails","method":"get"},{"path":"/panel/api/clients/groups/create","method":"post"},{"path":"/panel/api/clients/groups/rename","method":"post"},{"path":"/panel/api/clients/groups/delete","method":"post"},{"path":"/panel/api/clients/resetTraffic/{email}","method":"post"},{"path":"/panel/api/clients/updateTraffic/{email}","method":"post"},{"path":"/panel/api/clients/ips/{email}","method":"post"},{"path":"/panel/api/clients/clearIps/{email}","method":"post"},{"path":"/panel/api/clients/onlines","method":"post"},{"path":"/panel/api/clients/onlinesByGuid","method":"post"},{"path":"/panel/api/clients/clientIpsByGuid","method":"post"},{"path":"/panel/api/clients/activeInbounds","method":"post"},{"path":"/panel/api/clients/lastOnline","method":"post"},{"path":"/panel/api/clients/traffic/{email}","method":"get"},{"path":"/panel/api/clients/subLinks/{subId}","method":"get"},{"path":"/panel/api/clients/links/{email}","method":"get"}]} showTitle />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,108 @@
|
||||
---
|
||||
title: 主机
|
||||
description: >-
|
||||
按入站逐项覆盖的端点。每个启用的主机都会额外生成一条订阅链接/代理，可拥有独立的
|
||||
地址/端口/TLS，从而取代已弃用的 externalProxy 数组。所有端点均位于 /panel/api/hosts
|
||||
之下。
|
||||
full: true
|
||||
_openapi:
|
||||
preload:
|
||||
- ./public/openapi.json
|
||||
toc:
|
||||
- depth: 2
|
||||
title: >-
|
||||
List every host across all inbounds, grouped by inbound then ordered by
|
||||
sort order.
|
||||
url: >-
|
||||
#list-every-host-across-all-inbounds-grouped-by-inbound-then-ordered-by-sort-order
|
||||
- depth: 2
|
||||
title: Fetch a single host by ID.
|
||||
url: '#fetch-a-single-host-by-id'
|
||||
- depth: 2
|
||||
title: Fetch one inbound's hosts, ordered by sort order then id.
|
||||
url: '#fetch-one-inbounds-hosts-ordered-by-sort-order-then-id'
|
||||
- depth: 2
|
||||
title: Distinct, sorted set of tags used across all hosts.
|
||||
url: '#distinct-sorted-set-of-tags-used-across-all-hosts'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Create a host on an inbound. inboundId and remark are required; security
|
||||
defaults to "same" (inherit the inbound).
|
||||
url: >-
|
||||
#create-a-host-on-an-inbound-inboundid-and-remark-are-required-security-defaults-to-same-inherit-the-inbound
|
||||
- depth: 2
|
||||
title: >-
|
||||
Replace a host’s content. The inbound and sort order are immutable here
|
||||
(use /reorder for ordering).
|
||||
url: >-
|
||||
#replace-a-hosts-content-the-inbound-and-sort-order-are-immutable-here-use-reorder-for-ordering
|
||||
- depth: 2
|
||||
title: Delete a host.
|
||||
url: '#delete-a-host'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Enable or disable a single host (disabled hosts are skipped in
|
||||
subscriptions).
|
||||
url: >-
|
||||
#enable-or-disable-a-single-host-disabled-hosts-are-skipped-in-subscriptions
|
||||
- depth: 2
|
||||
title: Set host sort order by the position of each id in the array.
|
||||
url: '#set-host-sort-order-by-the-position-of-each-id-in-the-array'
|
||||
- depth: 2
|
||||
title: Enable or disable many hosts in one call.
|
||||
url: '#enable-or-disable-many-hosts-in-one-call'
|
||||
- depth: 2
|
||||
title: Delete many hosts in one call.
|
||||
url: '#delete-many-hosts-in-one-call'
|
||||
structuredData:
|
||||
headings:
|
||||
- content: >-
|
||||
List every host across all inbounds, grouped by inbound then ordered
|
||||
by sort order.
|
||||
id: >-
|
||||
list-every-host-across-all-inbounds-grouped-by-inbound-then-ordered-by-sort-order
|
||||
- content: Fetch a single host by ID.
|
||||
id: fetch-a-single-host-by-id
|
||||
- content: Fetch one inbound's hosts, ordered by sort order then id.
|
||||
id: fetch-one-inbounds-hosts-ordered-by-sort-order-then-id
|
||||
- content: Distinct, sorted set of tags used across all hosts.
|
||||
id: distinct-sorted-set-of-tags-used-across-all-hosts
|
||||
- content: >-
|
||||
Create a host on an inbound. inboundId and remark are required;
|
||||
security defaults to "same" (inherit the inbound).
|
||||
id: >-
|
||||
create-a-host-on-an-inbound-inboundid-and-remark-are-required-security-defaults-to-same-inherit-the-inbound
|
||||
- content: >-
|
||||
Replace a host’s content. The inbound and sort order are immutable
|
||||
here (use /reorder for ordering).
|
||||
id: >-
|
||||
replace-a-hosts-content-the-inbound-and-sort-order-are-immutable-here-use-reorder-for-ordering
|
||||
- content: Delete a host.
|
||||
id: delete-a-host
|
||||
- content: >-
|
||||
Enable or disable a single host (disabled hosts are skipped in
|
||||
subscriptions).
|
||||
id: >-
|
||||
enable-or-disable-a-single-host-disabled-hosts-are-skipped-in-subscriptions
|
||||
- content: Set host sort order by the position of each id in the array.
|
||||
id: set-host-sort-order-by-the-position-of-each-id-in-the-array
|
||||
- content: Enable or disable many hosts in one call.
|
||||
id: enable-or-disable-many-hosts-in-one-call
|
||||
- content: Delete many hosts in one call.
|
||||
id: delete-many-hosts-in-one-call
|
||||
contents: []
|
||||
---
|
||||
|
||||
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
|
||||
|
||||
export default function Layout(props) {
|
||||
const { APIPage, OpenAPIPage } = props.components ?? {};
|
||||
// "APIPage" is the old name from v10, this allows both for backward compatibility
|
||||
const Comp = OpenAPIPage ?? APIPage;
|
||||
return (
|
||||
<>
|
||||
{props.children}
|
||||
<Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/panel/api/hosts/list","method":"get"},{"path":"/panel/api/hosts/get/{id}","method":"get"},{"path":"/panel/api/hosts/byInbound/{inboundId}","method":"get"},{"path":"/panel/api/hosts/tags","method":"get"},{"path":"/panel/api/hosts/add","method":"post"},{"path":"/panel/api/hosts/update/{id}","method":"post"},{"path":"/panel/api/hosts/del/{id}","method":"post"},{"path":"/panel/api/hosts/setEnable/{id}","method":"post"},{"path":"/panel/api/hosts/reorder","method":"post"},{"path":"/panel/api/hosts/bulk/setEnable","method":"post"},{"path":"/panel/api/hosts/bulk/del","method":"post"}]} showTitle />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,186 @@
|
||||
---
|
||||
title: 入站
|
||||
description: >-
|
||||
管理入站配置及其客户端。所有端点均位于 /panel/api/inbounds 下，需要已登录的会话或 Bearer
|
||||
令牌。生成链接的端点仅在请求来自已配置的受信任代理时，才会采信转发请求头。
|
||||
full: true
|
||||
_openapi:
|
||||
preload:
|
||||
- ./public/openapi.json
|
||||
toc:
|
||||
- depth: 2
|
||||
title: >-
|
||||
列出已认证用户拥有的每个入站，包括每个入站的 clientStats 流量计数器。settings、streamSettings 和
|
||||
sniffing 以嵌套的 JSON 对象形式返回（不含转义字符串）；写入时仍接受以 JSON 编码字符串形式回传这些字段的旧版调用方。
|
||||
url: >-
|
||||
#list-every-inbound-owned-by-the-authenticated-user-including-each-inbounds-clientstats-traffic-counters-settings-streamsettings-and-sniffing-are-returned-as-nested-json-objects-no-escaped-strings-legacy-callers-that-send-them-back-as-json-encoded-strings-are-still-accepted-on-write
|
||||
- depth: 2
|
||||
title: >-
|
||||
与 /list 结构相同，但 settings.clients[] 精简为 {email, enable, comment}，且 ClientStats
|
||||
不附带 UUID/SubId。请将其用于列表页面；当你需要完整的单客户端数据（uuid、password、flow……）时，请调用
|
||||
/get/:id。
|
||||
url: >-
|
||||
#same-shape-as-list-but-with-settingsclients-stripped-down-to-email-enable-comment-and-clientstats-not-enriched-with-uuidsubid-use-this-for-list-pages-fetch-getid-when-you-need-the-full-per-client-payload-uuid-password-flow-
|
||||
- depth: 2
|
||||
title: >-
|
||||
已认证用户入站的轻量级选择器投影。返回 id、remark、tag、protocol、port、由服务端计算的 tlsFlowCapable
|
||||
标志（当 VLESS 在 TCP 上使用 tls 或 reality，或在 XHTTP 上启用 VLESS encryption / vlessenc
|
||||
时为 true），以及 ssMethod（Shadowsocks 加密方式，非 Shadowsocks 入站为空——客户端 UI 用它生成有效的
|
||||
Shadowsocks 2022 PSK）。请将其用于下拉菜单和附加选择器——它会跳过 settings、streamSettings 和
|
||||
clientStats，因此即便在拥有数千客户端的面板上，数据负载也能保持精简。
|
||||
url: >-
|
||||
#lightweight-picker-projection-of-the-authenticated-users-inbounds-returns-id-remark-tag-protocol-port-a-server-computed-tlsflowcapable-flag-true-for-vless-on-tcp-with-tls-or-reality-or-on-xhttp-with-vless-encryption--vlessenc-enabled-and-ssmethod-the-shadowsocks-cipher-empty-for-non-shadowsocks-inbounds--used-by-the-client-ui-to-generate-a-valid-shadowsocks-2022-psk-use-this-for-dropdowns-and-attach-pickers--it-skips-settings-streamsettings-and-clientstats-so-the-payload-stays-small-even-on-panels-with-thousands-of-clients
|
||||
- depth: 2
|
||||
title: 按数字 ID 获取单个入站。
|
||||
url: '#fetch-a-single-inbound-by-numeric-id'
|
||||
- depth: 2
|
||||
title: >-
|
||||
创建一个新入站。发送完整的入站数据（protocol、port、settings、streamSettings、sniffing、remark、expiryTime、total、enable）。settings、streamSettings
|
||||
和 sniffing 可以嵌套 JSON 对象形式发送（推荐），也可以 JSON 编码字符串形式发送（旧版）。
|
||||
url: >-
|
||||
#create-a-new-inbound-send-the-full-inbound-payload-protocol-port-settings-streamsettings-sniffing-remark-expirytime-total-enable-settings-streamsettings-and-sniffing-may-be-sent-as-nested-json-objects-preferred-or-as-json-encoded-strings-legacy
|
||||
- depth: 2
|
||||
title: 按 ID 删除一个入站。同时会移除其关联的客户端统计记录行。
|
||||
url: '#delete-an-inbound-by-id-also-removes-its-associated-client-stats-rows'
|
||||
- depth: 2
|
||||
title: >-
|
||||
在一次调用中删除多个入站。按顺序逐个处理列表；失败会按 id 逐一报告，其余的仍会继续执行。最多重启 xray 一次。
|
||||
url: >-
|
||||
#delete-many-inbounds-in-one-call-processes-the-list-sequentially-failures-are-reported-per-id-and-the-rest-still-proceed-restarts-xray-at-most-once
|
||||
- depth: 2
|
||||
title: >-
|
||||
替换一个入站的配置。请求体结构与 /add 相同。对于拥有数千客户端的入站开销较大——若仅切换 enable，请优先使用 /setEnable。
|
||||
url: >-
|
||||
#replace-an-inbounds-configuration-body-shape-mirrors-add-heavy-on-inbounds-with-thousands-of-clients--prefer-setenable-for-enable-only-flips
|
||||
- depth: 2
|
||||
title: >-
|
||||
仅切换 enable 标志，而无需序列化整个 settings JSON。推荐用于大型入站上的 UI 开关。
|
||||
url: >-
|
||||
#toggle-only-the-enable-flag-without-serialising-the-whole-settings-json-recommended-for-ui-switches-on-large-inbounds
|
||||
- depth: 2
|
||||
title: >-
|
||||
将单个入站的上传 + 下载计数器清零。不会影响单客户端的计数器。
|
||||
url: >-
|
||||
#zero-out-upload--download-counters-for-a-single-inbound-does-not-touch-per-client-counters
|
||||
- depth: 2
|
||||
title: >-
|
||||
移除某个入站上附加的所有客户端，同时保留入站本身。它会从 settings.clients[] 收集 email，并将其送入优化过的批量删除流程（运行时用户移除
|
||||
+ 流量记录行清理 + SyncInbound）。此操作具有破坏性且无法撤销。
|
||||
url: >-
|
||||
#remove-every-client-attached-to-a-single-inbound-while-keeping-the-inbound-itself-collects-emails-from-settingsclients-and-feeds-them-into-the-optimized-bulk-delete-path-runtime-user-removal--traffic-row-cleanup--syncinbound-destructive-and-cannot-be-undone
|
||||
- depth: 2
|
||||
title: >-
|
||||
重置每个入站的上传 + 下载计数器。此操作具有破坏性——统计历史将丢失。
|
||||
url: >-
|
||||
#reset-upload--download-counters-on-every-inbound-destructive--accounting-history-is-lost
|
||||
- depth: 2
|
||||
title: >-
|
||||
从一段 JSON 数据（例如通过 UI 导出的数据）批量导入一个入站。请求体使用表单编码，仅含一个 "data" 字段。
|
||||
url: >-
|
||||
#bulk-import-an-inbound-from-a-json-blob-eg-one-exported-via-the-ui-the-body-uses-form-encoding-with-a-single-data-field
|
||||
- depth: 2
|
||||
title: >-
|
||||
接收主面板聚合后的单客户端用量，以主面板的 GUID 为键。存储在一个仅用于 UI 显示叠加层和本地配额执行的辅助表中——绝不会并入主面板轮询的本地计数器，因此增量统计保持完整。由节点流量同步任务在面板间调用。
|
||||
url: >-
|
||||
#receive-a-master-panels-aggregated-per-client-usage-keyed-by-the-masters-guid-stored-in-a-side-table-used-only-for-the-ui-display-overlay-and-local-quota-enforcement--never-folded-into-the-local-counters-that-masters-poll-so-delta-accounting-stays-intact-called-panel-to-panel-by-the-node-traffic-sync-job
|
||||
- depth: 2
|
||||
title: >-
|
||||
列出附加在主 VLESS/Trojan TCP-TLS 入站上的回落（fallback）规则。每条规则将一个子入站（dest）关联到可选的
|
||||
SNI/ALPN/path/dest/xver 匹配条件。当 dest 为空时，使用子入站的 listen+port。
|
||||
url: >-
|
||||
#list-the-fallback-rules-attached-to-a-master-vlesstrojan-tcp-tls-inbound-each-rule-links-one-child-inbound-the-dest-to-optional-snialpnpathdestxver-match-criteria-when-dest-is-empty-the-child-inbounds-listenport-is-used
|
||||
- depth: 2
|
||||
title: >-
|
||||
替换主入站的整个回落（fallback）列表。请求体为 JSON。会触发 Xray 重启。
|
||||
url: >-
|
||||
#replace-the-entire-fallback-list-for-a-master-inbound-body-is-json-triggers-an-xray-restart
|
||||
structuredData:
|
||||
headings:
|
||||
- content: >-
|
||||
列出已认证用户拥有的每个入站，包括每个入站的 clientStats 流量计数器。settings、streamSettings 和
|
||||
sniffing 以嵌套的 JSON 对象形式返回（不含转义字符串）；写入时仍接受以 JSON 编码字符串形式回传这些字段的旧版调用方。
|
||||
id: >-
|
||||
list-every-inbound-owned-by-the-authenticated-user-including-each-inbounds-clientstats-traffic-counters-settings-streamsettings-and-sniffing-are-returned-as-nested-json-objects-no-escaped-strings-legacy-callers-that-send-them-back-as-json-encoded-strings-are-still-accepted-on-write
|
||||
- content: >-
|
||||
与 /list 结构相同，但 settings.clients[] 精简为 {email, enable, comment}，且
|
||||
ClientStats 不附带 UUID/SubId。请将其用于列表页面；当你需要完整的单客户端数据（uuid、password、flow……）时，请调用
|
||||
/get/:id。
|
||||
id: >-
|
||||
same-shape-as-list-but-with-settingsclients-stripped-down-to-email-enable-comment-and-clientstats-not-enriched-with-uuidsubid-use-this-for-list-pages-fetch-getid-when-you-need-the-full-per-client-payload-uuid-password-flow-
|
||||
- content: >-
|
||||
已认证用户入站的轻量级选择器投影。返回 id、remark、tag、protocol、port、由服务端计算的
|
||||
tlsFlowCapable 标志（当 VLESS 在 TCP 上使用 tls 或 reality，或在 XHTTP 上启用 VLESS
|
||||
encryption / vlessenc 时为 true），以及 ssMethod（Shadowsocks 加密方式，非 Shadowsocks
|
||||
入站为空——客户端 UI 用它生成有效的 Shadowsocks 2022 PSK）。请将其用于下拉菜单和附加选择器——它会跳过
|
||||
settings、streamSettings 和 clientStats，因此即便在拥有数千客户端的面板上，数据负载也能保持精简。
|
||||
id: >-
|
||||
lightweight-picker-projection-of-the-authenticated-users-inbounds-returns-id-remark-tag-protocol-port-a-server-computed-tlsflowcapable-flag-true-for-vless-on-tcp-with-tls-or-reality-or-on-xhttp-with-vless-encryption--vlessenc-enabled-and-ssmethod-the-shadowsocks-cipher-empty-for-non-shadowsocks-inbounds--used-by-the-client-ui-to-generate-a-valid-shadowsocks-2022-psk-use-this-for-dropdowns-and-attach-pickers--it-skips-settings-streamsettings-and-clientstats-so-the-payload-stays-small-even-on-panels-with-thousands-of-clients
|
||||
- content: 按数字 ID 获取单个入站。
|
||||
id: fetch-a-single-inbound-by-numeric-id
|
||||
- content: >-
|
||||
创建一个新入站。发送完整的入站数据（protocol、port、settings、streamSettings、sniffing、remark、expiryTime、total、enable）。settings、streamSettings
|
||||
和 sniffing 可以嵌套 JSON 对象形式发送（推荐），也可以 JSON 编码字符串形式发送（旧版）。
|
||||
id: >-
|
||||
create-a-new-inbound-send-the-full-inbound-payload-protocol-port-settings-streamsettings-sniffing-remark-expirytime-total-enable-settings-streamsettings-and-sniffing-may-be-sent-as-nested-json-objects-preferred-or-as-json-encoded-strings-legacy
|
||||
- content: >-
|
||||
按 ID 删除一个入站。同时会移除其关联的客户端统计记录行。
|
||||
id: delete-an-inbound-by-id-also-removes-its-associated-client-stats-rows
|
||||
- content: >-
|
||||
在一次调用中删除多个入站。按顺序逐个处理列表；失败会按 id 逐一报告，其余的仍会继续执行。最多重启 xray 一次。
|
||||
id: >-
|
||||
delete-many-inbounds-in-one-call-processes-the-list-sequentially-failures-are-reported-per-id-and-the-rest-still-proceed-restarts-xray-at-most-once
|
||||
- content: >-
|
||||
替换一个入站的配置。请求体结构与 /add 相同。对于拥有数千客户端的入站开销较大——若仅切换 enable，请优先使用
|
||||
/setEnable。
|
||||
id: >-
|
||||
replace-an-inbounds-configuration-body-shape-mirrors-add-heavy-on-inbounds-with-thousands-of-clients--prefer-setenable-for-enable-only-flips
|
||||
- content: >-
|
||||
仅切换 enable 标志，而无需序列化整个 settings JSON。推荐用于大型入站上的 UI 开关。
|
||||
id: >-
|
||||
toggle-only-the-enable-flag-without-serialising-the-whole-settings-json-recommended-for-ui-switches-on-large-inbounds
|
||||
- content: >-
|
||||
将单个入站的上传 + 下载计数器清零。不会影响单客户端的计数器。
|
||||
id: >-
|
||||
zero-out-upload--download-counters-for-a-single-inbound-does-not-touch-per-client-counters
|
||||
- content: >-
|
||||
移除某个入站上附加的所有客户端，同时保留入站本身。它会从 settings.clients[] 收集 email，并将其送入优化过的批量删除流程（运行时用户移除
|
||||
+ 流量记录行清理 + SyncInbound）。此操作具有破坏性且无法撤销。
|
||||
id: >-
|
||||
remove-every-client-attached-to-a-single-inbound-while-keeping-the-inbound-itself-collects-emails-from-settingsclients-and-feeds-them-into-the-optimized-bulk-delete-path-runtime-user-removal--traffic-row-cleanup--syncinbound-destructive-and-cannot-be-undone
|
||||
- content: >-
|
||||
重置每个入站的上传 + 下载计数器。此操作具有破坏性——统计历史将丢失。
|
||||
id: >-
|
||||
reset-upload--download-counters-on-every-inbound-destructive--accounting-history-is-lost
|
||||
- content: >-
|
||||
从一段 JSON 数据（例如通过 UI 导出的数据）批量导入一个入站。请求体使用表单编码，仅含一个 "data" 字段。
|
||||
id: >-
|
||||
bulk-import-an-inbound-from-a-json-blob-eg-one-exported-via-the-ui-the-body-uses-form-encoding-with-a-single-data-field
|
||||
- content: >-
|
||||
接收主面板聚合后的单客户端用量，以主面板的 GUID 为键。存储在一个仅用于 UI 显示叠加层和本地配额执行的辅助表中——绝不会并入主面板轮询的本地计数器，因此增量统计保持完整。由节点流量同步任务在面板间调用。
|
||||
id: >-
|
||||
receive-a-master-panels-aggregated-per-client-usage-keyed-by-the-masters-guid-stored-in-a-side-table-used-only-for-the-ui-display-overlay-and-local-quota-enforcement--never-folded-into-the-local-counters-that-masters-poll-so-delta-accounting-stays-intact-called-panel-to-panel-by-the-node-traffic-sync-job
|
||||
- content: >-
|
||||
列出附加在主 VLESS/Trojan TCP-TLS 入站上的回落（fallback）规则。每条规则将一个子入站（dest）关联到可选的
|
||||
SNI/ALPN/path/dest/xver 匹配条件。当 dest 为空时，使用子入站的 listen+port。
|
||||
id: >-
|
||||
list-the-fallback-rules-attached-to-a-master-vlesstrojan-tcp-tls-inbound-each-rule-links-one-child-inbound-the-dest-to-optional-snialpnpathdestxver-match-criteria-when-dest-is-empty-the-child-inbounds-listenport-is-used
|
||||
- content: >-
|
||||
替换主入站的整个回落（fallback）列表。请求体为 JSON。会触发 Xray 重启。
|
||||
id: >-
|
||||
replace-the-entire-fallback-list-for-a-master-inbound-body-is-json-triggers-an-xray-restart
|
||||
contents: []
|
||||
---
|
||||
|
||||
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
|
||||
|
||||
export default function Layout(props) {
|
||||
const { APIPage, OpenAPIPage } = props.components ?? {};
|
||||
// "APIPage" is the old name from v10, this allows both for backward compatibility
|
||||
const Comp = OpenAPIPage ?? APIPage;
|
||||
return (
|
||||
<>
|
||||
{props.children}
|
||||
<Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/panel/api/inbounds/list","method":"get"},{"path":"/panel/api/inbounds/list/slim","method":"get"},{"path":"/panel/api/inbounds/options","method":"get"},{"path":"/panel/api/inbounds/get/{id}","method":"get"},{"path":"/panel/api/inbounds/add","method":"post"},{"path":"/panel/api/inbounds/del/{id}","method":"post"},{"path":"/panel/api/inbounds/bulkDel","method":"post"},{"path":"/panel/api/inbounds/update/{id}","method":"post"},{"path":"/panel/api/inbounds/setEnable/{id}","method":"post"},{"path":"/panel/api/inbounds/{id}/resetTraffic","method":"post"},{"path":"/panel/api/inbounds/{id}/delAllClients","method":"post"},{"path":"/panel/api/inbounds/resetAllTraffics","method":"post"},{"path":"/panel/api/inbounds/import","method":"post"},{"path":"/panel/api/inbounds/pushClientTraffics","method":"post"},{"path":"/panel/api/inbounds/{id}/fallbacks","method":"get"},{"path":"/panel/api/inbounds/{id}/fallbacks","method":"post"}]} showTitle />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,37 @@
|
||||
---
|
||||
title: API 参考
|
||||
description: 3x-ui 面板的 REST API —— 涵盖认证、入站、客户端、服务器状态等，依据 OpenAPI 规范自动生成。
|
||||
icon: Webhook
|
||||
---
|
||||
|
||||
3x-ui 面板提供了一套用于自动化的 REST API。以下页面根据面板的 OpenAPI 规范自动生成，因此始终与所记录的 schema 保持一致。
|
||||
|
||||
## 认证
|
||||
|
||||
请求可使用 **会话 Cookie**（来自 `POST /login`）或 **Bearer token** 进行认证：
|
||||
|
||||
```text
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
在面板中创建 API token；它们拥有完整的管理员权限，因此请妥善保管。参见 [API Tokens](/docs/reference/api/api-tokens)。
|
||||
|
||||
为下方任意端点构建一个已认证的请求：
|
||||
|
||||
<ApiRequestBuilder />
|
||||
|
||||
## 按领域浏览
|
||||
|
||||
<Cards>
|
||||
<Card title="认证" href="/docs/reference/api/authentication" />
|
||||
<Card title="入站" href="/docs/reference/api/inbounds" />
|
||||
<Card title="客户端" href="/docs/reference/api/clients" />
|
||||
<Card title="服务器" href="/docs/reference/api/server" />
|
||||
<Card title="设置" href="/docs/reference/api/settings" />
|
||||
<Card title="Xray 设置" href="/docs/reference/api/xray-settings" />
|
||||
</Cards>
|
||||
|
||||
<Callout type="info">
|
||||
本参考文档由 `public/openapi.json` 通过 `pnpm gen:api` 重新生成。
|
||||
请勿手动编辑自动生成的标签页面。
|
||||
</Callout>
|
||||
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"title": "API 参考",
|
||||
"icon": "Webhook",
|
||||
"pages": [
|
||||
"index",
|
||||
"authentication",
|
||||
"api-tokens",
|
||||
"inbounds",
|
||||
"clients",
|
||||
"server",
|
||||
"settings",
|
||||
"xray-settings",
|
||||
"subscription-server",
|
||||
"hosts",
|
||||
"nodes",
|
||||
"backup",
|
||||
"websocket"
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,182 @@
|
||||
---
|
||||
title: 节点
|
||||
description: >-
|
||||
管理作为中心面板节点的远程 3x-ui 面板。所有端点均位于 /panel/api/nodes 之下。
|
||||
full: true
|
||||
_openapi:
|
||||
preload:
|
||||
- ./public/openapi.json
|
||||
toc:
|
||||
- depth: 2
|
||||
title: >-
|
||||
List every configured node with its connection details, health, and last
|
||||
heartbeat patch.
|
||||
url: >-
|
||||
#list-every-configured-node-with-its-connection-details-health-and-last-heartbeat-patch
|
||||
- depth: 2
|
||||
title: >-
|
||||
This panel's node-auth CA certificate (public, PEM) to paste into a
|
||||
node's mTLS trust setting. Lazily mints the CA and the master client
|
||||
cert on first call. Pair with setting tlsVerifyMode=mtls on the node.
|
||||
url: >-
|
||||
#this-panels-node-auth-ca-certificate-public-pem-to-paste-into-a-nodes-mtls-trust-setting-lazily-mints-the-ca-and-the-master-client-cert-on-first-call-pair-with-setting-tlsverifymodemtls-on-the-node
|
||||
- depth: 2
|
||||
title: >-
|
||||
Set the CA certificate this panel trusts for incoming node-API client
|
||||
certificates (this panel acting as a node). Paste the managing panel's
|
||||
CA (from nodes/mtls/ca). An empty caCert disables it. A non-empty value
|
||||
must be a PEM certificate. Applied on the next panel restart.
|
||||
url: >-
|
||||
#set-the-ca-certificate-this-panel-trusts-for-incoming-node-api-client-certificates-this-panel-acting-as-a-node-paste-the-managing-panels-ca-from-nodesmtlsca-an-empty-cacert-disables-it-a-non-empty-value-must-be-a-pem-certificate-applied-on-the-next-panel-restart
|
||||
- depth: 2
|
||||
title: Fetch a single node by ID.
|
||||
url: '#fetch-a-single-node-by-id'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Fetch a node's own web TLS certificate/key file paths (proxied to the
|
||||
node). Used by the inbound form's "Set Cert from Panel" so a
|
||||
node-assigned inbound gets paths that exist on the node, not the central
|
||||
panel.
|
||||
url: >-
|
||||
#fetch-a-nodes-own-web-tls-certificatekey-file-paths-proxied-to-the-node-used-by-the-inbound-forms-set-cert-from-panel-so-a-node-assigned-inbound-gets-paths-that-exist-on-the-node-not-the-central-panel
|
||||
- depth: 2
|
||||
title: >-
|
||||
Register a new remote node. Provide its URL, apiToken, and optional
|
||||
remark / allowPrivateAddress flag.
|
||||
url: >-
|
||||
#register-a-new-remote-node-provide-its-url-apitoken-and-optional-remark--allowprivateaddress-flag
|
||||
- depth: 2
|
||||
title: Replace a node’s connection details. Same body shape as /add.
|
||||
url: '#replace-a-nodes-connection-details-same-body-shape-as-add'
|
||||
- depth: 2
|
||||
title: Delete a node. Inbounds bound to it are not auto-migrated.
|
||||
url: '#delete-a-node-inbounds-bound-to-it-are-not-auto-migrated'
|
||||
- depth: 2
|
||||
title: Pause or resume traffic sync with this node.
|
||||
url: '#pause-or-resume-traffic-sync-with-this-node'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Probe a node without saving it. Uses the body as connection details and
|
||||
returns the same heartbeat snapshot a registered node would have.
|
||||
url: >-
|
||||
#probe-a-node-without-saving-it-uses-the-body-as-connection-details-and-returns-the-same-heartbeat-snapshot-a-registered-node-would-have
|
||||
- depth: 2
|
||||
title: >-
|
||||
Connect to the node over HTTPS without verifying its certificate and
|
||||
return the leaf certificate's SHA-256 (base64). Used by the Add/Edit
|
||||
Node dialog to fetch and pin a self-signed certificate. Uses the same
|
||||
body as /test.
|
||||
url: >-
|
||||
#connect-to-the-node-over-https-without-verifying-its-certificate-and-return-the-leaf-certificates-sha-256-base64-used-by-the-addedit-node-dialog-to-fetch-and-pin-a-self-signed-certificate-uses-the-same-body-as-test
|
||||
- depth: 2
|
||||
title: >-
|
||||
Use unsaved node connection details to list the remote inbounds
|
||||
available for selective import.
|
||||
url: >-
|
||||
#use-unsaved-node-connection-details-to-list-the-remote-inbounds-available-for-selective-import
|
||||
- depth: 2
|
||||
title: Probe an existing node, updating its cached health state.
|
||||
url: '#probe-an-existing-node-updating-its-cached-health-state'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Trigger the official panel self-updater on each given node (downloads
|
||||
the latest release and restarts). Only enabled, online nodes are
|
||||
updated; offline/disabled ones are reported as skipped. Set "dev": true
|
||||
to move the nodes to the rolling per-commit dev channel instead of the
|
||||
latest stable release. Returns a per-node result list.
|
||||
url: >-
|
||||
#trigger-the-official-panel-self-updater-on-each-given-node-downloads-the-latest-release-and-restarts-only-enabled-online-nodes-are-updated-offlinedisabled-ones-are-reported-as-skipped-set-dev-true-to-move-the-nodes-to-the-rolling-per-commit-dev-channel-instead-of-the-latest-stable-release-returns-a-per-node-result-list
|
||||
- depth: 2
|
||||
title: >-
|
||||
Aggregated metric history for a node — same shape as /server/history,
|
||||
scoped to one node.
|
||||
url: >-
|
||||
#aggregated-metric-history-for-a-node--same-shape-as-serverhistory-scoped-to-one-node
|
||||
structuredData:
|
||||
headings:
|
||||
- content: >-
|
||||
List every configured node with its connection details, health, and
|
||||
last heartbeat patch.
|
||||
id: >-
|
||||
list-every-configured-node-with-its-connection-details-health-and-last-heartbeat-patch
|
||||
- content: >-
|
||||
This panel's node-auth CA certificate (public, PEM) to paste into a
|
||||
node's mTLS trust setting. Lazily mints the CA and the master client
|
||||
cert on first call. Pair with setting tlsVerifyMode=mtls on the node.
|
||||
id: >-
|
||||
this-panels-node-auth-ca-certificate-public-pem-to-paste-into-a-nodes-mtls-trust-setting-lazily-mints-the-ca-and-the-master-client-cert-on-first-call-pair-with-setting-tlsverifymodemtls-on-the-node
|
||||
- content: >-
|
||||
Set the CA certificate this panel trusts for incoming node-API client
|
||||
certificates (this panel acting as a node). Paste the managing panel's
|
||||
CA (from nodes/mtls/ca). An empty caCert disables it. A non-empty
|
||||
value must be a PEM certificate. Applied on the next panel restart.
|
||||
id: >-
|
||||
set-the-ca-certificate-this-panel-trusts-for-incoming-node-api-client-certificates-this-panel-acting-as-a-node-paste-the-managing-panels-ca-from-nodesmtlsca-an-empty-cacert-disables-it-a-non-empty-value-must-be-a-pem-certificate-applied-on-the-next-panel-restart
|
||||
- content: Fetch a single node by ID.
|
||||
id: fetch-a-single-node-by-id
|
||||
- content: >-
|
||||
Fetch a node's own web TLS certificate/key file paths (proxied to the
|
||||
node). Used by the inbound form's "Set Cert from Panel" so a
|
||||
node-assigned inbound gets paths that exist on the node, not the
|
||||
central panel.
|
||||
id: >-
|
||||
fetch-a-nodes-own-web-tls-certificatekey-file-paths-proxied-to-the-node-used-by-the-inbound-forms-set-cert-from-panel-so-a-node-assigned-inbound-gets-paths-that-exist-on-the-node-not-the-central-panel
|
||||
- content: >-
|
||||
Register a new remote node. Provide its URL, apiToken, and optional
|
||||
remark / allowPrivateAddress flag.
|
||||
id: >-
|
||||
register-a-new-remote-node-provide-its-url-apitoken-and-optional-remark--allowprivateaddress-flag
|
||||
- content: Replace a node’s connection details. Same body shape as /add.
|
||||
id: replace-a-nodes-connection-details-same-body-shape-as-add
|
||||
- content: Delete a node. Inbounds bound to it are not auto-migrated.
|
||||
id: delete-a-node-inbounds-bound-to-it-are-not-auto-migrated
|
||||
- content: Pause or resume traffic sync with this node.
|
||||
id: pause-or-resume-traffic-sync-with-this-node
|
||||
- content: >-
|
||||
Probe a node without saving it. Uses the body as connection details
|
||||
and returns the same heartbeat snapshot a registered node would have.
|
||||
id: >-
|
||||
probe-a-node-without-saving-it-uses-the-body-as-connection-details-and-returns-the-same-heartbeat-snapshot-a-registered-node-would-have
|
||||
- content: >-
|
||||
Connect to the node over HTTPS without verifying its certificate and
|
||||
return the leaf certificate's SHA-256 (base64). Used by the Add/Edit
|
||||
Node dialog to fetch and pin a self-signed certificate. Uses the same
|
||||
body as /test.
|
||||
id: >-
|
||||
connect-to-the-node-over-https-without-verifying-its-certificate-and-return-the-leaf-certificates-sha-256-base64-used-by-the-addedit-node-dialog-to-fetch-and-pin-a-self-signed-certificate-uses-the-same-body-as-test
|
||||
- content: >-
|
||||
Use unsaved node connection details to list the remote inbounds
|
||||
available for selective import.
|
||||
id: >-
|
||||
use-unsaved-node-connection-details-to-list-the-remote-inbounds-available-for-selective-import
|
||||
- content: Probe an existing node, updating its cached health state.
|
||||
id: probe-an-existing-node-updating-its-cached-health-state
|
||||
- content: >-
|
||||
Trigger the official panel self-updater on each given node (downloads
|
||||
the latest release and restarts). Only enabled, online nodes are
|
||||
updated; offline/disabled ones are reported as skipped. Set "dev":
|
||||
true to move the nodes to the rolling per-commit dev channel instead
|
||||
of the latest stable release. Returns a per-node result list.
|
||||
id: >-
|
||||
trigger-the-official-panel-self-updater-on-each-given-node-downloads-the-latest-release-and-restarts-only-enabled-online-nodes-are-updated-offlinedisabled-ones-are-reported-as-skipped-set-dev-true-to-move-the-nodes-to-the-rolling-per-commit-dev-channel-instead-of-the-latest-stable-release-returns-a-per-node-result-list
|
||||
- content: >-
|
||||
Aggregated metric history for a node — same shape as /server/history,
|
||||
scoped to one node.
|
||||
id: >-
|
||||
aggregated-metric-history-for-a-node--same-shape-as-serverhistory-scoped-to-one-node
|
||||
contents: []
|
||||
---
|
||||
|
||||
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
|
||||
|
||||
export default function Layout(props) {
|
||||
const { APIPage, OpenAPIPage } = props.components ?? {};
|
||||
// "APIPage" is the old name from v10, this allows both for backward compatibility
|
||||
const Comp = OpenAPIPage ?? APIPage;
|
||||
return (
|
||||
<>
|
||||
{props.children}
|
||||
<Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/panel/api/nodes/list","method":"get"},{"path":"/panel/api/nodes/mtls/ca","method":"post"},{"path":"/panel/api/nodes/mtls/trustCA","method":"post"},{"path":"/panel/api/nodes/get/{id}","method":"get"},{"path":"/panel/api/nodes/webCert/{id}","method":"get"},{"path":"/panel/api/nodes/add","method":"post"},{"path":"/panel/api/nodes/update/{id}","method":"post"},{"path":"/panel/api/nodes/del/{id}","method":"post"},{"path":"/panel/api/nodes/setEnable/{id}","method":"post"},{"path":"/panel/api/nodes/test","method":"post"},{"path":"/panel/api/nodes/certFingerprint","method":"post"},{"path":"/panel/api/nodes/inbounds","method":"post"},{"path":"/panel/api/nodes/probe/{id}","method":"post"},{"path":"/panel/api/nodes/updatePanel","method":"post"},{"path":"/panel/api/nodes/history/{id}/{metric}/{bucket}","method":"get"}]} showTitle />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,381 @@
|
||||
---
|
||||
title: 服务器
|
||||
description: >-
|
||||
系统状态、日志获取、证书生成器、Xray 二进制文件管理以及备份/恢复。所有接口均位于
|
||||
/panel/api/server 下。
|
||||
full: true
|
||||
_openapi:
|
||||
preload:
|
||||
- ./public/openapi.json
|
||||
toc:
|
||||
- depth: 2
|
||||
title: >-
|
||||
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.
|
||||
url: >-
|
||||
#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
|
||||
- depth: 2
|
||||
title: >-
|
||||
Reports whether per-client IP limits can be enforced on this host. The
|
||||
panel uses it to gate the "IP Limit" field, since enforcement depends on
|
||||
Fail2ban being installed.
|
||||
url: >-
|
||||
#reports-whether-per-client-ip-limits-can-be-enforced-on-this-host-the-panel-uses-it-to-gate-the-ip-limit-field-since-enforcement-depends-on-fail2ban-being-installed
|
||||
- depth: 2
|
||||
title: >-
|
||||
Legacy: aggregated CPU history. Use /history/cpu/:bucket instead — same
|
||||
data with a uniform {t, v} shape.
|
||||
url: >-
|
||||
#legacy-aggregated-cpu-history-use-historycpubucket-instead--same-data-with-a-uniform-t-v-shape
|
||||
- depth: 2
|
||||
title: >-
|
||||
Aggregated time-series for one metric. Returns an array of {t, v}
|
||||
samples covering the last ~6 hours.
|
||||
url: >-
|
||||
#aggregated-time-series-for-one-metric-returns-an-array-of-t-v-samples-covering-the-last-6-hours
|
||||
- depth: 2
|
||||
title: >-
|
||||
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.
|
||||
url: >-
|
||||
#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
|
||||
- depth: 2
|
||||
title: >-
|
||||
Time-series history for one Xray runtime metric over the last ~6 hours.
|
||||
Same {t, v} shape as /history/:metric/:bucket.
|
||||
url: >-
|
||||
#time-series-history-for-one-xray-runtime-metric-over-the-last-6-hours-same-t-v-shape-as-historymetricbucket
|
||||
- depth: 2
|
||||
title: >-
|
||||
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.
|
||||
url: >-
|
||||
#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
|
||||
- depth: 2
|
||||
title: >-
|
||||
Time-series of observatory probe results for one outbound tag. Same {t,
|
||||
v} shape as the other history endpoints.
|
||||
url: >-
|
||||
#time-series-of-observatory-probe-results-for-one-outbound-tag-same-t-v-shape-as-the-other-history-endpoints
|
||||
- depth: 2
|
||||
title: List Xray binary versions available for install on this host.
|
||||
url: '#list-xray-binary-versions-available-for-install-on-this-host'
|
||||
- depth: 2
|
||||
title: Check whether a newer 3x-ui release is available on GitHub.
|
||||
url: '#check-whether-a-newer-3x-ui-release-is-available-on-github'
|
||||
- depth: 2
|
||||
title: Return the assembled Xray config that’s currently running on this host.
|
||||
url: '#return-the-assembled-xray-config-thats-currently-running-on-this-host'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Stream the SQLite database file as an attachment. Use as a manual
|
||||
backup.
|
||||
url: '#stream-the-sqlite-database-file-as-an-attachment-use-as-a-manual-backup'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Stream a cross-engine migration file as an attachment: a .dump (SQL
|
||||
text) on SQLite, or a .db SQLite database built from the live data on
|
||||
PostgreSQL.
|
||||
url: >-
|
||||
#stream-a-cross-engine-migration-file-as-an-attachment-a-dump-sql-text-on-sqlite-or-a-db-sqlite-database-built-from-the-live-data-on-postgresql
|
||||
- depth: 2
|
||||
title: Generate a fresh UUID v4. Convenience helper for client IDs.
|
||||
url: '#generate-a-fresh-uuid-v4-convenience-helper-for-client-ids'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Return this panel's own web TLS certificate and key file paths. The
|
||||
central panel calls it on a node (via the node API token) so "Set Cert
|
||||
from Panel" fills a node-assigned inbound with paths that exist on the
|
||||
node.
|
||||
url: >-
|
||||
#return-this-panels-own-web-tls-certificate-and-key-file-paths-the-central-panel-calls-it-on-a-node-via-the-node-api-token-so-set-cert-from-panel-fills-a-node-assigned-inbound-with-paths-that-exist-on-the-node
|
||||
- depth: 2
|
||||
title: >-
|
||||
Read-only summaries (guid, parentGuid, name, address, status, versions)
|
||||
of the nodes this panel manages. A parent panel calls it on a node (via
|
||||
the node API token) to surface transitive sub-nodes in a chained
|
||||
topology. Counts are computed by the parent, not returned here.
|
||||
url: >-
|
||||
#read-only-summaries-guid-parentguid-name-address-status-versions-of-the-nodes-this-panel-manages-a-parent-panel-calls-it-on-a-node-via-the-node-api-token-to-surface-transitive-sub-nodes-in-a-chained-topology-counts-are-computed-by-the-parent-not-returned-here
|
||||
- depth: 2
|
||||
title: Generate a new X25519 keypair for Reality.
|
||||
url: '#generate-a-new-x25519-keypair-for-reality'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Generate a new ML-DSA-65 keypair (post-quantum signature). Returns
|
||||
{privateKey, publicKey, seed}.
|
||||
url: >-
|
||||
#generate-a-new-ml-dsa-65-keypair-post-quantum-signature-returns-privatekey-publickey-seed
|
||||
- depth: 2
|
||||
title: >-
|
||||
Generate a new ML-KEM-768 keypair (post-quantum KEM). Returns
|
||||
{clientKey, serverKey}.
|
||||
url: >-
|
||||
#generate-a-new-ml-kem-768-keypair-post-quantum-kem-returns-clientkey-serverkey
|
||||
- depth: 2
|
||||
title: >-
|
||||
Generate VLESS encryption auth options. Returns an auths array each with
|
||||
id, label, encryption, and decryption fields.
|
||||
url: >-
|
||||
#generate-vless-encryption-auth-options-returns-an-auths-array-each-with-id-label-encryption-and-decryption-fields
|
||||
- depth: 2
|
||||
title: Stop the Xray binary. All proxies go offline immediately.
|
||||
url: '#stop-the-xray-binary-all-proxies-go-offline-immediately'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Reload Xray with the current config. Typically required after structural
|
||||
inbound or routing changes.
|
||||
url: >-
|
||||
#reload-xray-with-the-current-config-typically-required-after-structural-inbound-or-routing-changes
|
||||
- depth: 2
|
||||
title: >-
|
||||
Download and install the specified Xray version. Pass "latest" for the
|
||||
newest release.
|
||||
url: >-
|
||||
#download-and-install-the-specified-xray-version-pass-latest-for-the-newest-release
|
||||
- depth: 2
|
||||
title: >-
|
||||
Self-update the panel to the latest version. The server restarts on
|
||||
success.
|
||||
url: >-
|
||||
#self-update-the-panel-to-the-latest-version-the-server-restarts-on-success
|
||||
- depth: 2
|
||||
title: >-
|
||||
Toggle the panel update channel between stable and the rolling
|
||||
per-commit dev release. Only effective on dev builds.
|
||||
url: >-
|
||||
#toggle-the-panel-update-channel-between-stable-and-the-rolling-per-commit-dev-release-only-effective-on-dev-builds
|
||||
- depth: 2
|
||||
title: >-
|
||||
Refresh the default GeoIP / GeoSite data files. Body can include a
|
||||
fileName, or use the /:fileName variant.
|
||||
url: >-
|
||||
#refresh-the-default-geoip--geosite-data-files-body-can-include-a-filename-or-use-the-filename-variant
|
||||
- depth: 2
|
||||
title: Refresh a single Geo file by filename (e.g. geoip.dat, geosite.dat).
|
||||
url: '#refresh-a-single-geo-file-by-filename-eg-geoipdat-geositedat'
|
||||
- depth: 2
|
||||
title: Return the last N lines of the panel’s own log.
|
||||
url: '#return-the-last-n-lines-of-the-panels-own-log'
|
||||
- depth: 2
|
||||
title: Return the last N lines of the Xray process log.
|
||||
url: '#return-the-last-n-lines-of-the-xray-process-log'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Restore the panel DB from an uploaded SQLite file (multipart form, field
|
||||
name "db"). The panel restarts after restore. Destructive.
|
||||
url: >-
|
||||
#restore-the-panel-db-from-an-uploaded-sqlite-file-multipart-form-field-name-db-the-panel-restarts-after-restore-destructive
|
||||
- depth: 2
|
||||
title: >-
|
||||
Generate a new ECH (Encrypted Client Hello) keypair and config list for
|
||||
the given SNI.
|
||||
url: >-
|
||||
#generate-a-new-ech-encrypted-client-hello-keypair-and-config-list-for-the-given-sni
|
||||
- depth: 2
|
||||
title: >-
|
||||
Compute the hex SHA-256 of a certificate (DER) for pinning
|
||||
(pinnedPeerCertSha256). Provide either a server file path or inline
|
||||
PEM/DER content.
|
||||
url: >-
|
||||
#compute-the-hex-sha-256-of-a-certificate-der-for-pinning-pinnedpeercertsha256-provide-either-a-server-file-path-or-inline-pemder-content
|
||||
- depth: 2
|
||||
title: >-
|
||||
Run `xray tls ping` against a remote server and return its live
|
||||
leaf-certificate SHA-256 hash(es) for pinning (pinnedPeerCertSha256).
|
||||
url: >-
|
||||
#run-xray-tls-ping-against-a-remote-server-and-return-its-live-leaf-certificate-sha-256-hashes-for-pinning-pinnedpeercertsha256
|
||||
- depth: 2
|
||||
title: >-
|
||||
Fetch the fully aggregated inbound_client_ips database table. Used by
|
||||
nodes to sync recently active IPs across the cluster.
|
||||
url: >-
|
||||
#fetch-the-fully-aggregated-inbound_client_ips-database-table-used-by-nodes-to-sync-recently-active-ips-across-the-cluster
|
||||
- depth: 2
|
||||
title: >-
|
||||
Submit a list of recently active IP timestamps. The panel merges them
|
||||
with the existing database to maintain a unified global IP-limit view.
|
||||
url: >-
|
||||
#submit-a-list-of-recently-active-ip-timestamps-the-panel-merges-them-with-the-existing-database-to-maintain-a-unified-global-ip-limit-view
|
||||
structuredData:
|
||||
headings:
|
||||
- content: >-
|
||||
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.
|
||||
id: >-
|
||||
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
|
||||
- content: >-
|
||||
Reports whether per-client IP limits can be enforced on this host. The
|
||||
panel uses it to gate the "IP Limit" field, since enforcement depends
|
||||
on Fail2ban being installed.
|
||||
id: >-
|
||||
reports-whether-per-client-ip-limits-can-be-enforced-on-this-host-the-panel-uses-it-to-gate-the-ip-limit-field-since-enforcement-depends-on-fail2ban-being-installed
|
||||
- content: >-
|
||||
Legacy: aggregated CPU history. Use /history/cpu/:bucket instead —
|
||||
same data with a uniform {t, v} shape.
|
||||
id: >-
|
||||
legacy-aggregated-cpu-history-use-historycpubucket-instead--same-data-with-a-uniform-t-v-shape
|
||||
- content: >-
|
||||
Aggregated time-series for one metric. Returns an array of {t, v}
|
||||
samples covering the last ~6 hours.
|
||||
id: >-
|
||||
aggregated-time-series-for-one-metric-returns-an-array-of-t-v-samples-covering-the-last-6-hours
|
||||
- content: >-
|
||||
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.
|
||||
id: >-
|
||||
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
|
||||
- content: >-
|
||||
Time-series history for one Xray runtime metric over the last ~6
|
||||
hours. Same {t, v} shape as /history/:metric/:bucket.
|
||||
id: >-
|
||||
time-series-history-for-one-xray-runtime-metric-over-the-last-6-hours-same-t-v-shape-as-historymetricbucket
|
||||
- content: >-
|
||||
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.
|
||||
id: >-
|
||||
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
|
||||
- content: >-
|
||||
Time-series of observatory probe results for one outbound tag. Same
|
||||
{t, v} shape as the other history endpoints.
|
||||
id: >-
|
||||
time-series-of-observatory-probe-results-for-one-outbound-tag-same-t-v-shape-as-the-other-history-endpoints
|
||||
- content: List Xray binary versions available for install on this host.
|
||||
id: list-xray-binary-versions-available-for-install-on-this-host
|
||||
- content: Check whether a newer 3x-ui release is available on GitHub.
|
||||
id: check-whether-a-newer-3x-ui-release-is-available-on-github
|
||||
- content: >-
|
||||
Return the assembled Xray config that’s currently running on this
|
||||
host.
|
||||
id: return-the-assembled-xray-config-thats-currently-running-on-this-host
|
||||
- content: >-
|
||||
Stream the SQLite database file as an attachment. Use as a manual
|
||||
backup.
|
||||
id: >-
|
||||
stream-the-sqlite-database-file-as-an-attachment-use-as-a-manual-backup
|
||||
- content: >-
|
||||
Stream a cross-engine migration file as an attachment: a .dump (SQL
|
||||
text) on SQLite, or a .db SQLite database built from the live data on
|
||||
PostgreSQL.
|
||||
id: >-
|
||||
stream-a-cross-engine-migration-file-as-an-attachment-a-dump-sql-text-on-sqlite-or-a-db-sqlite-database-built-from-the-live-data-on-postgresql
|
||||
- content: Generate a fresh UUID v4. Convenience helper for client IDs.
|
||||
id: generate-a-fresh-uuid-v4-convenience-helper-for-client-ids
|
||||
- content: >-
|
||||
Return this panel's own web TLS certificate and key file paths. The
|
||||
central panel calls it on a node (via the node API token) so "Set Cert
|
||||
from Panel" fills a node-assigned inbound with paths that exist on the
|
||||
node.
|
||||
id: >-
|
||||
return-this-panels-own-web-tls-certificate-and-key-file-paths-the-central-panel-calls-it-on-a-node-via-the-node-api-token-so-set-cert-from-panel-fills-a-node-assigned-inbound-with-paths-that-exist-on-the-node
|
||||
- content: >-
|
||||
Read-only summaries (guid, parentGuid, name, address, status,
|
||||
versions) of the nodes this panel manages. A parent panel calls it on
|
||||
a node (via the node API token) to surface transitive sub-nodes in a
|
||||
chained topology. Counts are computed by the parent, not returned
|
||||
here.
|
||||
id: >-
|
||||
read-only-summaries-guid-parentguid-name-address-status-versions-of-the-nodes-this-panel-manages-a-parent-panel-calls-it-on-a-node-via-the-node-api-token-to-surface-transitive-sub-nodes-in-a-chained-topology-counts-are-computed-by-the-parent-not-returned-here
|
||||
- content: Generate a new X25519 keypair for Reality.
|
||||
id: generate-a-new-x25519-keypair-for-reality
|
||||
- content: >-
|
||||
Generate a new ML-DSA-65 keypair (post-quantum signature). Returns
|
||||
{privateKey, publicKey, seed}.
|
||||
id: >-
|
||||
generate-a-new-ml-dsa-65-keypair-post-quantum-signature-returns-privatekey-publickey-seed
|
||||
- content: >-
|
||||
Generate a new ML-KEM-768 keypair (post-quantum KEM). Returns
|
||||
{clientKey, serverKey}.
|
||||
id: >-
|
||||
generate-a-new-ml-kem-768-keypair-post-quantum-kem-returns-clientkey-serverkey
|
||||
- content: >-
|
||||
Generate VLESS encryption auth options. Returns an auths array each
|
||||
with id, label, encryption, and decryption fields.
|
||||
id: >-
|
||||
generate-vless-encryption-auth-options-returns-an-auths-array-each-with-id-label-encryption-and-decryption-fields
|
||||
- content: Stop the Xray binary. All proxies go offline immediately.
|
||||
id: stop-the-xray-binary-all-proxies-go-offline-immediately
|
||||
- content: >-
|
||||
Reload Xray with the current config. Typically required after
|
||||
structural inbound or routing changes.
|
||||
id: >-
|
||||
reload-xray-with-the-current-config-typically-required-after-structural-inbound-or-routing-changes
|
||||
- content: >-
|
||||
Download and install the specified Xray version. Pass "latest" for the
|
||||
newest release.
|
||||
id: >-
|
||||
download-and-install-the-specified-xray-version-pass-latest-for-the-newest-release
|
||||
- content: >-
|
||||
Self-update the panel to the latest version. The server restarts on
|
||||
success.
|
||||
id: >-
|
||||
self-update-the-panel-to-the-latest-version-the-server-restarts-on-success
|
||||
- content: >-
|
||||
Toggle the panel update channel between stable and the rolling
|
||||
per-commit dev release. Only effective on dev builds.
|
||||
id: >-
|
||||
toggle-the-panel-update-channel-between-stable-and-the-rolling-per-commit-dev-release-only-effective-on-dev-builds
|
||||
- content: >-
|
||||
Refresh the default GeoIP / GeoSite data files. Body can include a
|
||||
fileName, or use the /:fileName variant.
|
||||
id: >-
|
||||
refresh-the-default-geoip--geosite-data-files-body-can-include-a-filename-or-use-the-filename-variant
|
||||
- content: Refresh a single Geo file by filename (e.g. geoip.dat, geosite.dat).
|
||||
id: refresh-a-single-geo-file-by-filename-eg-geoipdat-geositedat
|
||||
- content: Return the last N lines of the panel’s own log.
|
||||
id: return-the-last-n-lines-of-the-panels-own-log
|
||||
- content: Return the last N lines of the Xray process log.
|
||||
id: return-the-last-n-lines-of-the-xray-process-log
|
||||
- content: >-
|
||||
Restore the panel DB from an uploaded SQLite file (multipart form,
|
||||
field name "db"). The panel restarts after restore. Destructive.
|
||||
id: >-
|
||||
restore-the-panel-db-from-an-uploaded-sqlite-file-multipart-form-field-name-db-the-panel-restarts-after-restore-destructive
|
||||
- content: >-
|
||||
Generate a new ECH (Encrypted Client Hello) keypair and config list
|
||||
for the given SNI.
|
||||
id: >-
|
||||
generate-a-new-ech-encrypted-client-hello-keypair-and-config-list-for-the-given-sni
|
||||
- content: >-
|
||||
Compute the hex SHA-256 of a certificate (DER) for pinning
|
||||
(pinnedPeerCertSha256). Provide either a server file path or inline
|
||||
PEM/DER content.
|
||||
id: >-
|
||||
compute-the-hex-sha-256-of-a-certificate-der-for-pinning-pinnedpeercertsha256-provide-either-a-server-file-path-or-inline-pemder-content
|
||||
- content: >-
|
||||
Run `xray tls ping` against a remote server and return its live
|
||||
leaf-certificate SHA-256 hash(es) for pinning (pinnedPeerCertSha256).
|
||||
id: >-
|
||||
run-xray-tls-ping-against-a-remote-server-and-return-its-live-leaf-certificate-sha-256-hashes-for-pinning-pinnedpeercertsha256
|
||||
- content: >-
|
||||
Fetch the fully aggregated inbound_client_ips database table. Used by
|
||||
nodes to sync recently active IPs across the cluster.
|
||||
id: >-
|
||||
fetch-the-fully-aggregated-inbound_client_ips-database-table-used-by-nodes-to-sync-recently-active-ips-across-the-cluster
|
||||
- content: >-
|
||||
Submit a list of recently active IP timestamps. The panel merges them
|
||||
with the existing database to maintain a unified global IP-limit view.
|
||||
id: >-
|
||||
submit-a-list-of-recently-active-ip-timestamps-the-panel-merges-them-with-the-existing-database-to-maintain-a-unified-global-ip-limit-view
|
||||
contents: []
|
||||
---
|
||||
|
||||
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
|
||||
|
||||
export default function Layout(props) {
|
||||
const { APIPage, OpenAPIPage } = props.components ?? {};
|
||||
// "APIPage" is the old name from v10, this allows both for backward compatibility
|
||||
const Comp = OpenAPIPage ?? APIPage;
|
||||
return (
|
||||
<>
|
||||
{props.children}
|
||||
<Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/panel/api/server/status","method":"get"},{"path":"/panel/api/server/fail2banStatus","method":"get"},{"path":"/panel/api/server/cpuHistory/{bucket}","method":"get"},{"path":"/panel/api/server/history/{metric}/{bucket}","method":"get"},{"path":"/panel/api/server/xrayMetricsState","method":"get"},{"path":"/panel/api/server/xrayMetricsHistory/{metric}/{bucket}","method":"get"},{"path":"/panel/api/server/xrayObservatory","method":"get"},{"path":"/panel/api/server/xrayObservatoryHistory/{tag}/{bucket}","method":"get"},{"path":"/panel/api/server/getXrayVersion","method":"get"},{"path":"/panel/api/server/getPanelUpdateInfo","method":"get"},{"path":"/panel/api/server/getConfigJson","method":"get"},{"path":"/panel/api/server/getDb","method":"get"},{"path":"/panel/api/server/getMigration","method":"get"},{"path":"/panel/api/server/getNewUUID","method":"get"},{"path":"/panel/api/server/getWebCertFiles","method":"get"},{"path":"/panel/api/server/descendants","method":"get"},{"path":"/panel/api/server/getNewX25519Cert","method":"get"},{"path":"/panel/api/server/getNewmldsa65","method":"get"},{"path":"/panel/api/server/getNewmlkem768","method":"get"},{"path":"/panel/api/server/getNewVlessEnc","method":"get"},{"path":"/panel/api/server/stopXrayService","method":"post"},{"path":"/panel/api/server/restartXrayService","method":"post"},{"path":"/panel/api/server/installXray/{version}","method":"post"},{"path":"/panel/api/server/updatePanel","method":"post"},{"path":"/panel/api/server/setUpdateChannel","method":"post"},{"path":"/panel/api/server/updateGeofile","method":"post"},{"path":"/panel/api/server/updateGeofile/{fileName}","method":"post"},{"path":"/panel/api/server/logs/{count}","method":"post"},{"path":"/panel/api/server/xraylogs/{count}","method":"post"},{"path":"/panel/api/server/importDB","method":"post"},{"path":"/panel/api/server/getNewEchCert","method":"post"},{"path":"/panel/api/server/getCertHash","method":"post"},{"path":"/panel/api/server/getRemoteCertHash","method":"post"},{"path":"/panel/api/server/clientIps","method":"get"},{"path":"/panel/api/server/clientIps","method":"post"}]} showTitle />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: 设置
|
||||
description: >-
|
||||
面板配置与用户凭据。所有端点均位于 /panel/api/setting 之下，需要已登录的会话或 Bearer 令牌。
|
||||
full: true
|
||||
_openapi:
|
||||
preload:
|
||||
- ./public/openapi.json
|
||||
toc:
|
||||
- depth: 2
|
||||
title: >-
|
||||
返回每一项面板设置：Web 服务器、Telegram 机器人、订阅、安全、LDAP。即“设置”页面所编辑的完整 JSON
|
||||
数据。
|
||||
url: >-
|
||||
#return-every-panel-setting-web-server-telegram-bot-subscription-security-ldap-the-full-json-blob-that-the-settings-page-edits
|
||||
- depth: 2
|
||||
title: >-
|
||||
根据请求主机返回计算得出的默认设置。可用于预览全新安装将采用的配置。
|
||||
url: >-
|
||||
#return-the-computed-default-settings-based-on-the-request-host-useful-to-preview-what-a-fresh-install-would-use
|
||||
- depth: 2
|
||||
title: >-
|
||||
一次性保存全部设置。请求体与 /all 返回的结构一致。无效值（端口错误、证书对缺失等）会在写入前被拒绝。
|
||||
url: >-
|
||||
#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
|
||||
- depth: 2
|
||||
title: >-
|
||||
更改面板管理员的用户名和密码。需要提供当前凭据以供验证。成功后会话将以新值刷新。
|
||||
url: >-
|
||||
#change-the-panel-admin-username-and-password-requires-the-current-credentials-for-verification-the-session-is-refreshed-with-the-new-values-on-success
|
||||
- depth: 2
|
||||
title: >-
|
||||
在 3 秒缓冲期后重启整个 3x-ui 进程。连接会立即断开；面板将在约 5-10 秒后重新上线。
|
||||
url: >-
|
||||
#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
|
||||
- depth: 2
|
||||
title: >-
|
||||
测试 SMTP 连接，并按阶段（连接、认证、发送）逐步报告。返回包含阶段和消息的结构化结果。
|
||||
url: >-
|
||||
#test-smtp-connection-with-stage-by-stage-reporting-connect-auth-send-returns-structured-result-with-stage-and-message
|
||||
- depth: 2
|
||||
title: >-
|
||||
通过向已配置的聊天发送一条测试消息来测试 Telegram 机器人连接。
|
||||
url: >-
|
||||
#test-telegram-bot-connection-by-sending-a-test-message-to-the-configured-chat
|
||||
- depth: 2
|
||||
title: >-
|
||||
返回随此面板版本一同提供的内置默认 Xray JSON 配置模板。
|
||||
url: >-
|
||||
#return-the-built-in-default-xray-json-config-template-that-ships-with-this-panel-version
|
||||
structuredData:
|
||||
headings:
|
||||
- content: >-
|
||||
返回每一项面板设置：Web 服务器、Telegram 机器人、订阅、安全、LDAP。即“设置”页面所编辑的完整 JSON
|
||||
数据。
|
||||
id: >-
|
||||
return-every-panel-setting-web-server-telegram-bot-subscription-security-ldap-the-full-json-blob-that-the-settings-page-edits
|
||||
- content: >-
|
||||
根据请求主机返回计算得出的默认设置。可用于预览全新安装将采用的配置。
|
||||
id: >-
|
||||
return-the-computed-default-settings-based-on-the-request-host-useful-to-preview-what-a-fresh-install-would-use
|
||||
- content: >-
|
||||
一次性保存全部设置。请求体与 /all 返回的结构一致。无效值（端口错误、证书对缺失等）会在写入前被拒绝。
|
||||
id: >-
|
||||
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
|
||||
- content: >-
|
||||
更改面板管理员的用户名和密码。需要提供当前凭据以供验证。成功后会话将以新值刷新。
|
||||
id: >-
|
||||
change-the-panel-admin-username-and-password-requires-the-current-credentials-for-verification-the-session-is-refreshed-with-the-new-values-on-success
|
||||
- content: >-
|
||||
在 3 秒缓冲期后重启整个 3x-ui 进程。连接会立即断开；面板将在约 5-10 秒后重新上线。
|
||||
id: >-
|
||||
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
|
||||
- content: >-
|
||||
测试 SMTP 连接，并按阶段（连接、认证、发送）逐步报告。返回包含阶段和消息的结构化结果。
|
||||
id: >-
|
||||
test-smtp-connection-with-stage-by-stage-reporting-connect-auth-send-returns-structured-result-with-stage-and-message
|
||||
- content: >-
|
||||
通过向已配置的聊天发送一条测试消息来测试 Telegram 机器人连接。
|
||||
id: >-
|
||||
test-telegram-bot-connection-by-sending-a-test-message-to-the-configured-chat
|
||||
- content: >-
|
||||
返回随此面板版本一同提供的内置默认 Xray JSON 配置模板。
|
||||
id: >-
|
||||
return-the-built-in-default-xray-json-config-template-that-ships-with-this-panel-version
|
||||
contents: []
|
||||
---
|
||||
|
||||
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
|
||||
|
||||
export default function Layout(props) {
|
||||
const { APIPage, OpenAPIPage } = props.components ?? {};
|
||||
// "APIPage" is the old name from v10, this allows both for backward compatibility
|
||||
const Comp = OpenAPIPage ?? APIPage;
|
||||
return (
|
||||
<>
|
||||
{props.children}
|
||||
<Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/panel/api/setting/all","method":"post"},{"path":"/panel/api/setting/defaultSettings","method":"post"},{"path":"/panel/api/setting/update","method":"post"},{"path":"/panel/api/setting/updateUser","method":"post"},{"path":"/panel/api/setting/restartPanel","method":"post"},{"path":"/panel/api/setting/testSmtp","method":"post"},{"path":"/panel/api/setting/testTgBot","method":"post"},{"path":"/panel/api/setting/getDefaultJsonConfig","method":"get"}]} showTitle />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: 订阅服务器
|
||||
description: >-
|
||||
一个独立的 HTTP/HTTPS 服务器，用于向客户端提供代理订阅链接（标准、JSON 和 Clash）。该服务器监听自己的端口（默认
|
||||
10882），并在“设置 → 订阅”中进行配置。路径可自定义；下方展示的是默认值。所有订阅端点都会设置响应头，供客户端应用读取流量/到期信息。
|
||||
full: true
|
||||
_openapi:
|
||||
preload:
|
||||
- ./public/openapi.json
|
||||
toc:
|
||||
- depth: 2
|
||||
title: >-
|
||||
返回与该订阅 ID 匹配的所有已启用客户端的 base64 编码订阅链接。当请求带有 Accept: text/html
|
||||
头或 ?html=1 时，改为渲染一个带样式的信息页面。默认路径：/sub/:subid。
|
||||
url: >-
|
||||
#return-base64-encoded-subscription-links-for-all-enabled-clients-matching-the-subscription-id-when-the-request-has-an-accept-texthtml-header-or-html1-renders-a-styled-info-page-instead-default-path-subsubid
|
||||
- depth: 2
|
||||
title: >-
|
||||
以代理配置的 JSON 数组形式返回订阅（每个已启用客户端一项）。仅在设置中启用 JSON 订阅时可用。默认路径：/json/:subid。
|
||||
url: >-
|
||||
#return-subscription-as-a-json-array-of-proxy-configs-one-per-enabled-client-only-when-json-subscription-is-enabled-in-settings-default-path-jsonsubid
|
||||
- depth: 2
|
||||
title: >-
|
||||
以兼容 Clash/Mihomo 的 YAML 配置形式返回订阅，其中包含已配置的全局 Clash 路由规则。仅在设置中启用 Clash
|
||||
订阅时可用。默认路径：/clash/:subid。
|
||||
url: >-
|
||||
#return-subscription-as-a-clashmihomo-compatible-yaml-config-including-configured-global-clash-routing-rules-only-when-clash-subscription-is-enabled-in-settings-default-path-clashsubid
|
||||
structuredData:
|
||||
headings:
|
||||
- content: >-
|
||||
返回与该订阅 ID 匹配的所有已启用客户端的 base64 编码订阅链接。当请求带有 Accept:
|
||||
text/html 头或 ?html=1 时，改为渲染一个带样式的信息页面。默认路径：/sub/:subid。
|
||||
id: >-
|
||||
return-base64-encoded-subscription-links-for-all-enabled-clients-matching-the-subscription-id-when-the-request-has-an-accept-texthtml-header-or-html1-renders-a-styled-info-page-instead-default-path-subsubid
|
||||
- content: >-
|
||||
以代理配置的 JSON 数组形式返回订阅（每个已启用客户端一项）。仅在设置中启用 JSON 订阅时可用。默认路径：/json/:subid。
|
||||
id: >-
|
||||
return-subscription-as-a-json-array-of-proxy-configs-one-per-enabled-client-only-when-json-subscription-is-enabled-in-settings-default-path-jsonsubid
|
||||
- content: >-
|
||||
以兼容 Clash/Mihomo 的 YAML 配置形式返回订阅，其中包含已配置的全局 Clash 路由规则。仅在设置中启用 Clash
|
||||
订阅时可用。默认路径：/clash/:subid。
|
||||
id: >-
|
||||
return-subscription-as-a-clashmihomo-compatible-yaml-config-including-configured-global-clash-routing-rules-only-when-clash-subscription-is-enabled-in-settings-default-path-clashsubid
|
||||
contents: []
|
||||
---
|
||||
|
||||
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
|
||||
|
||||
export default function Layout(props) {
|
||||
const { APIPage, OpenAPIPage } = props.components ?? {};
|
||||
// "APIPage" is the old name from v10, this allows both for backward compatibility
|
||||
const Comp = OpenAPIPage ?? APIPage;
|
||||
return (
|
||||
<>
|
||||
{props.children}
|
||||
<Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/{subPath}{subid}","method":"get"},{"path":"/{jsonPath}{subid}","method":"get"},{"path":"/{clashPath}{subid}","method":"get"}]} showTitle />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,44 @@
|
||||
---
|
||||
title: WebSocket
|
||||
description: >-
|
||||
通过 WebSocket 获取实时状态更新。只需在
|
||||
<code>ws://<panel>/ws</code> 建立一次连接，即可接收 JSON 消息流，无需轮询。需要经过身份验证的会话
|
||||
Cookie（不支持 Bearer token 身份验证）。每条消息都带有一个 <code>type</code> 字段，用于标识其载荷结构。
|
||||
full: true
|
||||
_openapi:
|
||||
preload:
|
||||
- ./public/openapi.json
|
||||
toc:
|
||||
- depth: 2
|
||||
title: >-
|
||||
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.
|
||||
url: >-
|
||||
#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
|
||||
structuredData:
|
||||
headings:
|
||||
- content: >-
|
||||
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.
|
||||
id: >-
|
||||
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
|
||||
contents: []
|
||||
---
|
||||
|
||||
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
|
||||
|
||||
export default function Layout(props) {
|
||||
const { APIPage, OpenAPIPage } = props.components ?? {};
|
||||
// "APIPage" is the old name from v10, this allows both for backward compatibility
|
||||
const Comp = OpenAPIPage ?? APIPage;
|
||||
return (
|
||||
<>
|
||||
{props.children}
|
||||
<Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/ws","method":"get"}]} showTitle />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,257 @@
|
||||
---
|
||||
title: Xray 设置
|
||||
description: >-
|
||||
Xray 配置模板、出站管理、Warp/Nord 集成以及配置测试。所有端点均位于 /panel/api/xray
|
||||
下。
|
||||
full: true
|
||||
_openapi:
|
||||
preload:
|
||||
- ./public/openapi.json
|
||||
toc:
|
||||
- depth: 2
|
||||
title: >-
|
||||
Return the Xray config template (JSON string), available inbound tags,
|
||||
client reverse tags, and the configured outbound test URL in one
|
||||
response.
|
||||
url: >-
|
||||
#return-the-xray-config-template-json-string-available-inbound-tags-client-reverse-tags-and-the-configured-outbound-test-url-in-one-response
|
||||
- depth: 2
|
||||
title: >-
|
||||
Return the built-in default Xray config shipped with the panel
|
||||
(identical to /panel/api/setting/getDefaultJsonConfig).
|
||||
url: >-
|
||||
#return-the-built-in-default-xray-config-shipped-with-the-panel-identical-to-panelapisettinggetdefaultjsonconfig
|
||||
- depth: 2
|
||||
title: >-
|
||||
Return traffic statistics for every outbound. Each outbound shows
|
||||
up/down/total counters.
|
||||
url: >-
|
||||
#return-traffic-statistics-for-every-outbound-each-outbound-shows-updowntotal-counters
|
||||
- depth: 2
|
||||
title: >-
|
||||
Return the most recent Xray process stdout/stderr output. Useful to
|
||||
check for startup errors or runtime warnings.
|
||||
url: >-
|
||||
#return-the-most-recent-xray-process-stdoutstderr-output-useful-to-check-for-startup-errors-or-runtime-warnings
|
||||
- depth: 2
|
||||
title: >-
|
||||
Save the Xray JSON config template and optionally the outbound test URL.
|
||||
Both are sent as form fields.
|
||||
url: >-
|
||||
#save-the-xray-json-config-template-and-optionally-the-outbound-test-url-both-are-sent-as-form-fields
|
||||
- depth: 2
|
||||
title: >-
|
||||
Manage Cloudflare Warp integration. The action parameter selects the
|
||||
operation.
|
||||
url: >-
|
||||
#manage-cloudflare-warp-integration-the-action-parameter-selects-the-operation
|
||||
- depth: 2
|
||||
title: Manage NordVPN integration. The action parameter selects the operation.
|
||||
url: '#manage-nordvpn-integration-the-action-parameter-selects-the-operation'
|
||||
- depth: 2
|
||||
title: Reset traffic counters for a specific outbound by tag.
|
||||
url: '#reset-traffic-counters-for-a-specific-outbound-by-tag'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Test an outbound configuration. Sends the outbound JSON (required),
|
||||
optionally all outbounds (to resolve sockopt.dialerProxy dependencies),
|
||||
and a mode flag.
|
||||
url: >-
|
||||
#test-an-outbound-configuration-sends-the-outbound-json-required-optionally-all-outbounds-to-resolve-sockoptdialerproxy-dependencies-and-a-mode-flag
|
||||
- depth: 2
|
||||
title: >-
|
||||
Test a batch of outbounds (max 50) through one shared temp xray
|
||||
instance. Returns an array of results in input order, each with the
|
||||
outbound tag, delay, HTTP status and a connect/TLS/TTFB timing
|
||||
breakdown.
|
||||
url: >-
|
||||
#test-a-batch-of-outbounds-max-50-through-one-shared-temp-xray-instance-returns-an-array-of-results-in-input-order-each-with-the-outbound-tag-delay-http-status-and-a-connecttlsttfb-timing-breakdown
|
||||
- depth: 2
|
||||
title: >-
|
||||
Live state of routing balancers in the running core
|
||||
(RoutingService.GetBalancerInfo): current override and the targets the
|
||||
strategy prefers. Returns a map keyed by balancer tag.
|
||||
url: >-
|
||||
#live-state-of-routing-balancers-in-the-running-core-routingservicegetbalancerinfo-current-override-and-the-targets-the-strategy-prefers-returns-a-map-keyed-by-balancer-tag
|
||||
- depth: 2
|
||||
title: >-
|
||||
Force a balancer in the running core to always pick one outbound
|
||||
(RoutingService.OverrideBalancerTarget). Applied live without a restart;
|
||||
cleared automatically when Xray restarts.
|
||||
url: >-
|
||||
#force-a-balancer-in-the-running-core-to-always-pick-one-outbound-routingserviceoverridebalancertarget-applied-live-without-a-restart-cleared-automatically-when-xray-restarts
|
||||
- depth: 2
|
||||
title: >-
|
||||
Ask the running core which outbound its router would pick for a
|
||||
synthetic connection (RoutingService.TestRoute). No traffic is sent.
|
||||
url: >-
|
||||
#ask-the-running-core-which-outbound-its-router-would-pick-for-a-synthetic-connection-routingservicetestroute-no-traffic-is-sent
|
||||
- depth: 2
|
||||
title: >-
|
||||
List all outbound subscriptions (remote URLs that supply additional
|
||||
outbounds), newest first.
|
||||
url: >-
|
||||
#list-all-outbound-subscriptions-remote-urls-that-supply-additional-outbounds-newest-first
|
||||
- depth: 2
|
||||
title: >-
|
||||
Create an outbound subscription. The URL is fetched, parsed into
|
||||
outbounds with stable tags, and merged additively into the running Xray
|
||||
config.
|
||||
url: >-
|
||||
#create-an-outbound-subscription-the-url-is-fetched-parsed-into-outbounds-with-stable-tags-and-merged-additively-into-the-running-xray-config
|
||||
- depth: 2
|
||||
title: >-
|
||||
Update an existing outbound subscription by id. Accepts the same form
|
||||
fields as create.
|
||||
url: >-
|
||||
#update-an-existing-outbound-subscription-by-id-accepts-the-same-form-fields-as-create
|
||||
- depth: 2
|
||||
title: Delete an outbound subscription by id.
|
||||
url: '#delete-an-outbound-subscription-by-id'
|
||||
- depth: 2
|
||||
title: >-
|
||||
Delete an outbound subscription by id (POST alias of DELETE for
|
||||
axios-friendly clients).
|
||||
url: >-
|
||||
#delete-an-outbound-subscription-by-id-post-alias-of-delete-for-axios-friendly-clients
|
||||
- depth: 2
|
||||
title: >-
|
||||
Force an immediate re-fetch of the subscription and return the parsed
|
||||
outbounds. Signals Xray to reload.
|
||||
url: >-
|
||||
#force-an-immediate-re-fetch-of-the-subscription-and-return-the-parsed-outbounds-signals-xray-to-reload
|
||||
- depth: 2
|
||||
title: >-
|
||||
Reorder a subscription one step up or down in priority (controls its
|
||||
position in the merged outbounds).
|
||||
url: >-
|
||||
#reorder-a-subscription-one-step-up-or-down-in-priority-controls-its-position-in-the-merged-outbounds
|
||||
- depth: 2
|
||||
title: >-
|
||||
Preview a subscription URL: fetch and parse it into outbounds without
|
||||
persisting anything.
|
||||
url: >-
|
||||
#preview-a-subscription-url-fetch-and-parse-it-into-outbounds-without-persisting-anything
|
||||
structuredData:
|
||||
headings:
|
||||
- content: >-
|
||||
Return the Xray config template (JSON string), available inbound tags,
|
||||
client reverse tags, and the configured outbound test URL in one
|
||||
response.
|
||||
id: >-
|
||||
return-the-xray-config-template-json-string-available-inbound-tags-client-reverse-tags-and-the-configured-outbound-test-url-in-one-response
|
||||
- content: >-
|
||||
Return the built-in default Xray config shipped with the panel
|
||||
(identical to /panel/api/setting/getDefaultJsonConfig).
|
||||
id: >-
|
||||
return-the-built-in-default-xray-config-shipped-with-the-panel-identical-to-panelapisettinggetdefaultjsonconfig
|
||||
- content: >-
|
||||
Return traffic statistics for every outbound. Each outbound shows
|
||||
up/down/total counters.
|
||||
id: >-
|
||||
return-traffic-statistics-for-every-outbound-each-outbound-shows-updowntotal-counters
|
||||
- content: >-
|
||||
Return the most recent Xray process stdout/stderr output. Useful to
|
||||
check for startup errors or runtime warnings.
|
||||
id: >-
|
||||
return-the-most-recent-xray-process-stdoutstderr-output-useful-to-check-for-startup-errors-or-runtime-warnings
|
||||
- content: >-
|
||||
Save the Xray JSON config template and optionally the outbound test
|
||||
URL. Both are sent as form fields.
|
||||
id: >-
|
||||
save-the-xray-json-config-template-and-optionally-the-outbound-test-url-both-are-sent-as-form-fields
|
||||
- content: >-
|
||||
Manage Cloudflare Warp integration. The action parameter selects the
|
||||
operation.
|
||||
id: >-
|
||||
manage-cloudflare-warp-integration-the-action-parameter-selects-the-operation
|
||||
- content: >-
|
||||
Manage NordVPN integration. The action parameter selects the
|
||||
operation.
|
||||
id: manage-nordvpn-integration-the-action-parameter-selects-the-operation
|
||||
- content: Reset traffic counters for a specific outbound by tag.
|
||||
id: reset-traffic-counters-for-a-specific-outbound-by-tag
|
||||
- content: >-
|
||||
Test an outbound configuration. Sends the outbound JSON (required),
|
||||
optionally all outbounds (to resolve sockopt.dialerProxy
|
||||
dependencies), and a mode flag.
|
||||
id: >-
|
||||
test-an-outbound-configuration-sends-the-outbound-json-required-optionally-all-outbounds-to-resolve-sockoptdialerproxy-dependencies-and-a-mode-flag
|
||||
- content: >-
|
||||
Test a batch of outbounds (max 50) through one shared temp xray
|
||||
instance. Returns an array of results in input order, each with the
|
||||
outbound tag, delay, HTTP status and a connect/TLS/TTFB timing
|
||||
breakdown.
|
||||
id: >-
|
||||
test-a-batch-of-outbounds-max-50-through-one-shared-temp-xray-instance-returns-an-array-of-results-in-input-order-each-with-the-outbound-tag-delay-http-status-and-a-connecttlsttfb-timing-breakdown
|
||||
- content: >-
|
||||
Live state of routing balancers in the running core
|
||||
(RoutingService.GetBalancerInfo): current override and the targets the
|
||||
strategy prefers. Returns a map keyed by balancer tag.
|
||||
id: >-
|
||||
live-state-of-routing-balancers-in-the-running-core-routingservicegetbalancerinfo-current-override-and-the-targets-the-strategy-prefers-returns-a-map-keyed-by-balancer-tag
|
||||
- content: >-
|
||||
Force a balancer in the running core to always pick one outbound
|
||||
(RoutingService.OverrideBalancerTarget). Applied live without a
|
||||
restart; cleared automatically when Xray restarts.
|
||||
id: >-
|
||||
force-a-balancer-in-the-running-core-to-always-pick-one-outbound-routingserviceoverridebalancertarget-applied-live-without-a-restart-cleared-automatically-when-xray-restarts
|
||||
- content: >-
|
||||
Ask the running core which outbound its router would pick for a
|
||||
synthetic connection (RoutingService.TestRoute). No traffic is sent.
|
||||
id: >-
|
||||
ask-the-running-core-which-outbound-its-router-would-pick-for-a-synthetic-connection-routingservicetestroute-no-traffic-is-sent
|
||||
- content: >-
|
||||
List all outbound subscriptions (remote URLs that supply additional
|
||||
outbounds), newest first.
|
||||
id: >-
|
||||
list-all-outbound-subscriptions-remote-urls-that-supply-additional-outbounds-newest-first
|
||||
- content: >-
|
||||
Create an outbound subscription. The URL is fetched, parsed into
|
||||
outbounds with stable tags, and merged additively into the running
|
||||
Xray config.
|
||||
id: >-
|
||||
create-an-outbound-subscription-the-url-is-fetched-parsed-into-outbounds-with-stable-tags-and-merged-additively-into-the-running-xray-config
|
||||
- content: >-
|
||||
Update an existing outbound subscription by id. Accepts the same form
|
||||
fields as create.
|
||||
id: >-
|
||||
update-an-existing-outbound-subscription-by-id-accepts-the-same-form-fields-as-create
|
||||
- content: Delete an outbound subscription by id.
|
||||
id: delete-an-outbound-subscription-by-id
|
||||
- content: >-
|
||||
Delete an outbound subscription by id (POST alias of DELETE for
|
||||
axios-friendly clients).
|
||||
id: >-
|
||||
delete-an-outbound-subscription-by-id-post-alias-of-delete-for-axios-friendly-clients
|
||||
- content: >-
|
||||
Force an immediate re-fetch of the subscription and return the parsed
|
||||
outbounds. Signals Xray to reload.
|
||||
id: >-
|
||||
force-an-immediate-re-fetch-of-the-subscription-and-return-the-parsed-outbounds-signals-xray-to-reload
|
||||
- content: >-
|
||||
Reorder a subscription one step up or down in priority (controls its
|
||||
position in the merged outbounds).
|
||||
id: >-
|
||||
reorder-a-subscription-one-step-up-or-down-in-priority-controls-its-position-in-the-merged-outbounds
|
||||
- content: >-
|
||||
Preview a subscription URL: fetch and parse it into outbounds without
|
||||
persisting anything.
|
||||
id: >-
|
||||
preview-a-subscription-url-fetch-and-parse-it-into-outbounds-without-persisting-anything
|
||||
contents: []
|
||||
---
|
||||
|
||||
{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}
|
||||
|
||||
export default function Layout(props) {
|
||||
const { APIPage, OpenAPIPage } = props.components ?? {};
|
||||
// "APIPage" is the old name from v10, this allows both for backward compatibility
|
||||
const Comp = OpenAPIPage ?? APIPage;
|
||||
return (
|
||||
<>
|
||||
{props.children}
|
||||
<Comp document="./public/openapi.json" webhooks={[]} operations={[{"path":"/panel/api/xray/","method":"post"},{"path":"/panel/api/xray/getDefaultJsonConfig","method":"get"},{"path":"/panel/api/xray/getOutboundsTraffic","method":"get"},{"path":"/panel/api/xray/getXrayResult","method":"get"},{"path":"/panel/api/xray/update","method":"post"},{"path":"/panel/api/xray/warp/{action}","method":"post"},{"path":"/panel/api/xray/nord/{action}","method":"post"},{"path":"/panel/api/xray/resetOutboundsTraffic","method":"post"},{"path":"/panel/api/xray/testOutbound","method":"post"},{"path":"/panel/api/xray/testOutbounds","method":"post"},{"path":"/panel/api/xray/balancerStatus","method":"post"},{"path":"/panel/api/xray/balancerOverride","method":"post"},{"path":"/panel/api/xray/routeTest","method":"post"},{"path":"/panel/api/xray/outbound-subs","method":"get"},{"path":"/panel/api/xray/outbound-subs","method":"post"},{"path":"/panel/api/xray/outbound-subs/{id}","method":"post"},{"path":"/panel/api/xray/outbound-subs/{id}","method":"delete"},{"path":"/panel/api/xray/outbound-subs/{id}/del","method":"post"},{"path":"/panel/api/xray/outbound-subs/{id}/refresh","method":"post"},{"path":"/panel/api/xray/outbound-subs/{id}/move","method":"post"},{"path":"/panel/api/xray/outbound-subs/parse","method":"post"}]} showTitle />
|
||||
</>
|
||||
);
|
||||
}
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
title: 数据库
|
||||
description: 3x-ui 的存储后端——SQLite（默认）与 PostgreSQL——涵盖数据库路径、连接池以及从 SQLite 到 PostgreSQL 的迁移。
|
||||
icon: Database
|
||||
---
|
||||
|
||||
3x-ui 将所有内容——入站、客户端、设置——都存储在数据库中。你在安装时
|
||||
选择后端；两者都是一等支持。
|
||||
|
||||
## SQLite（默认）
|
||||
|
||||
位于 `/etc/x-ui/x-ui.db` 的单个文件。无需任何配置，适合中小型
|
||||
部署。该文件夹可通过
|
||||
[`XUI_DB_FOLDER`](/docs/reference/env-vars#database) 配置（在 Windows 上默认
|
||||
紧挨着二进制文件存放）。
|
||||
|
||||
## PostgreSQL
|
||||
|
||||
推荐用于客户端数量庞大或多节点的部署。安装程序既可以为你在本地
|
||||
安装 PostgreSQL，也可以接受指向现有服务器的 DSN。运行时通过环境变量
|
||||
选择后端，安装程序会将这些变量写入 `/etc/default/x-ui`：
|
||||
|
||||
```bash title="/etc/default/x-ui"
|
||||
XUI_DB_TYPE=postgres
|
||||
XUI_DB_DSN=postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable
|
||||
```
|
||||
|
||||
使用 `XUI_DB_MAX_OPEN_CONNS` 和 `XUI_DB_MAX_IDLE_CONNS` 调优连接池。
|
||||
|
||||
### Docker
|
||||
|
||||
`docker compose up -d` 仍然使用 SQLite。若要配合内置的 PostgreSQL
|
||||
服务运行，请取消 `docker-compose.yml` 中两行 `XUI_DB_*` 的注释，并使用
|
||||
对应的 profile 启动：
|
||||
|
||||
```bash
|
||||
docker compose --profile postgres up -d
|
||||
```
|
||||
|
||||
## 从 SQLite 迁移到 PostgreSQL
|
||||
|
||||
使用内置命令将现有的 SQLite 安装迁移到 PostgreSQL：
|
||||
|
||||
```bash
|
||||
x-ui migrate-db --dsn "postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable"
|
||||
```
|
||||
|
||||
然后在 `/etc/default/x-ui` 中设置 `XUI_DB_TYPE` 和 `XUI_DB_DSN` 并重启：
|
||||
|
||||
```bash
|
||||
systemctl restart x-ui
|
||||
```
|
||||
|
||||
<Callout type="info">
|
||||
源 SQLite 文件不会被改动——只有在你确认新后端正常工作后，才手动
|
||||
将其删除。
|
||||
</Callout>
|
||||
|
||||
## 备份
|
||||
|
||||
无论使用哪种后端，都要定期备份——参见
|
||||
[备份与恢复](/docs/operations/backup-restore)。
|
||||
@@ -0,0 +1,82 @@
|
||||
---
|
||||
title: 环境变量
|
||||
description: 3x-ui 的 XUI_* 环境变量完整参考——涵盖数据库、面板、日志、内存以及隧道健康监测器。
|
||||
icon: Variable
|
||||
---
|
||||
|
||||
3x-ui 从 `XUI_*` 环境变量中读取其运行时配置。使用脚本安装时，安装程序会将
|
||||
这些变量写入服务环境文件（`/etc/default/x-ui`，或视发行版而定的
|
||||
`/etc/conf.d/x-ui` / `/etc/sysconfig/x-ui`）；使用 Docker 时，则在
|
||||
`docker-compose.yml` 或 `docker run -e` 中设置。默认值已足够合理——只需设置
|
||||
你需要更改的项，然后重启即可：`systemctl restart x-ui`。
|
||||
|
||||
## 数据库
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ------------------------ | ----------- | -------------------------------------------------------------------- |
|
||||
| `XUI_DB_TYPE` | `sqlite` | 后端：`sqlite`，或 `postgres`（也接受 `postgresql` / `pg`）。 |
|
||||
| `XUI_DB_FOLDER` | `/etc/x-ui` | SQLite 数据库文件（`x-ui.db`）所在的文件夹。 |
|
||||
| `XUI_DB_DSN` | — | PostgreSQL 连接字符串（当 `XUI_DB_TYPE=postgres` 时使用）。 |
|
||||
| `XUI_DB_MAX_OPEN_CONNS` | — | PostgreSQL 连接池中的最大打开连接数。 |
|
||||
| `XUI_DB_MAX_IDLE_CONNS` | — | PostgreSQL 连接池中的最大空闲连接数。 |
|
||||
|
||||
默认的 SQLite 数据库路径为 `/etc/x-ui/x-ui.db`。有关 SQLite ↔ PostgreSQL 的
|
||||
细节，参见 [数据库](/docs/reference/database)。
|
||||
|
||||
## 面板
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ------------------------ | ------- | ------------------------------------------------------------------------ |
|
||||
| `XUI_PORT` | — | 覆盖面板端口（1–65535）。优先级高于已存储的设置。 |
|
||||
| `XUI_INIT_WEB_BASE_PATH` | `/` | **首次**启动时的初始 Web 根路径（例如 `/panel`）。 |
|
||||
| `XUI_ENABLE_FAIL2BAN` | `true` | 启用基于 Fail2ban 的 IP 限制强制执行。 |
|
||||
| `XUI_SKIP_HSTS` | `false` | 跳过 HSTS 标头——当 TLS 由反向代理终结时设为 `true`。 |
|
||||
|
||||
## 日志与二进制文件
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ---------------- | ---------------- | ----------------------------------------------------------- |
|
||||
| `XUI_LOG_LEVEL` | `info` | `debug`、`info`、`notice`、`warning` 或 `error`。 |
|
||||
| `XUI_DEBUG` | `false` | 调试模式（强制将日志级别设为 `debug`）。 |
|
||||
| `XUI_LOG_FOLDER` | `/var/log/x-ui` | 日志输出目录。 |
|
||||
| `XUI_BIN_FOLDER` | `bin` | 存放 Xray-core 二进制文件及 geosite/geoip 文件的文件夹。 |
|
||||
|
||||
## 内存与性能分析
|
||||
|
||||
面板通过 `GOGC` 和定期释放来保持低内存占用。这些是高级调节项——除非你正在
|
||||
为受限主机做调优，否则请保持不设置。
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ----------------------------- | ------- | ----------------------------------------------------------------- |
|
||||
| `XUI_GOGC` | — | Go GC 目标百分比；值越低 = 占用 RAM 越少，CPU 略增。 |
|
||||
| `XUI_MEMORY_RELEASE_INTERVAL` | — | 两次 `FreeOSMemory` 调用之间的分钟数；`0` 表示禁用。 |
|
||||
| `XUI_MEMORY_LIMIT` | — | Go 软内存限制，单位 **MiB**。 |
|
||||
| `GOMEMLIMIT` | — | Go 语法的软限制（例如 `400MiB`）；优先级高于上一项。 |
|
||||
| `XUI_PPROF` | `false` | 在 `127.0.0.1:6060` 上暴露 pprof 性能分析。 |
|
||||
|
||||
## Xray
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ------------------------ | ------- | --------------------- |
|
||||
| `XRAY_VMESS_AEAD_FORCED` | `false` | 强制启用 VMess AEAD。 |
|
||||
|
||||
## 隧道健康监测器
|
||||
|
||||
可选的看门狗：它探测一个 URL（可选择**经由**本地 Xray 入站进行），并在反复
|
||||
失败后重启 Xray。重启会断开所有已连接的客户端，因此请审慎启用。
|
||||
|
||||
| Variable | Default | Description |
|
||||
| ----------------------------- | -------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| `XUI_TUNNEL_HEALTH_MONITOR` | `false` | 启用监测器。 |
|
||||
| `XUI_TUNNEL_HEALTH_PROXY` | — | 用于发送探测的代理，例如 `socks5://127.0.0.1:1080`。留空 = 仅检查主机连通性。 |
|
||||
| `XUI_TUNNEL_HEALTH_URL` | `https://www.cloudflare.com/cdn-cgi/trace` | 要探测的 URL。 |
|
||||
| `XUI_TUNNEL_HEALTH_INTERVAL` | `30s` | 探测之间的间隔。 |
|
||||
| `XUI_TUNNEL_HEALTH_TIMEOUT` | `10s` | 单次探测的超时时间。 |
|
||||
| `XUI_TUNNEL_HEALTH_FAILURES` | `3` | 触发重启前的连续失败次数。 |
|
||||
| `XUI_TUNNEL_HEALTH_COOLDOWN` | `5m` | 两次重启之间的最小延迟。 |
|
||||
|
||||
## 无人值守安装
|
||||
|
||||
| Variable | Description |
|
||||
| -------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| `XUI_NONINTERACTIVE` | 设为 `1`（或在无 TTY 的环境下运行）即可在零提示的情况下完成安装；生成的凭据会写入 `/etc/x-ui/install-result.env`。参见 [安装](/docs/guide/installation#unattended--cloud-init)。 |
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"title": "参考",
|
||||
"icon": "BookMarked",
|
||||
"pages": ["env-vars", "database", "ports-firewall", "api"]
|
||||
}
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: 端口与防火墙
|
||||
description: 3x-ui 默认使用的端口，以及用于开放这些端口的现成 ufw / nftables 规则。
|
||||
icon: Network
|
||||
---
|
||||
|
||||
只开放你实际会用到的端口。下面列出了常用端口，并提供了一个用于生成
|
||||
`ufw` 和 `nftables` 规则的生成器。
|
||||
|
||||
## 常用端口
|
||||
|
||||
| Port (default) | Purpose |
|
||||
| -------------- | ----------------------------------------- |
|
||||
| `22` | SSH（务必保持开放！）。 |
|
||||
| `2053` | 面板（可配置）。 |
|
||||
| `2096` | 订阅服务器（如果单独部署）。 |
|
||||
| `443` | 常用的入站端口（TLS / REALITY）。 |
|
||||
| `80` / `443` | 反向代理（如果你运行了反向代理）。 |
|
||||
|
||||
实际的入站端口取决于你创建的入站配置。
|
||||
|
||||
## 生成防火墙规则
|
||||
|
||||
<FirewallRulesGenerator />
|
||||
|
||||
<Callout type="warn">
|
||||
在启用默认拒绝策略之前，请始终保持 SSH 处于允许状态，并在另一个会话中进行测试，以免把自己锁在外面。
|
||||
</Callout>
|
||||
|
||||
## 相关内容
|
||||
|
||||
<Cards>
|
||||
<Card title="安全" href="/docs/operations/security" description="Fail2ban、IP 限制与安全加固。" />
|
||||
<Card title="环境变量" href="/docs/reference/env-vars" description="XUI_PORT 及相关变量。" />
|
||||
</Cards>
|
||||
Reference in New Issue
Block a user