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
2026-07-07 23:07:14 +02:00
parent 2c49dbf54e
commit 9b91f0f42e
283 changed files with 44179 additions and 0 deletions
@@ -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>
+12
View File
@@ -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>