3x-ui 到底怎么用：装完之后每一步该点哪里

00先花 30 秒：三句话 + 按你的处境直接抄

读完这一篇，你能做到三件事：在一台全新的服务器上把它装起来并锁好；建出一个能连上的代理入口，把链接发给别人；在它坏掉的那天知道该先看哪个文件、敲哪条命令。

按你的处境，直接用这个

一条可执行的上手路径

四个数字，先有个量级

013x-ui 到底是什么（先破三个最容易搞错的理解）

它不是协议。你听到的 VLESS、Trojan、Shadowsocks 是协议（可以理解成「双方约定的对暗号方式」），3x-ui 一个都不是。它不改协议、不发明协议，只是给你一个网页界面去生成协议的配置。

它不是内核。真正干活的是 Xray-core——那个负责加解密、监听端口、转发流量的可执行程序（俗称「内核」，意思是干实际工作的那部分）。3x-ui 是它的控制面板：把 Xray-core 当子进程拉起来、给它写配置文件、看它的流量统计。

它不是给终端用户用的。你手机上的 v2rayNG、Hiddify、Mihomo 是客户端（装在用户设备上、替用户发起连接的程序）；3x-ui 装在那台服务器上，是服务端管理台。两者之间靠一条「分享链接」或一个「订阅地址」对接。

那它是什么

一句话：3x-ui 是一个开源的网页控制面板，把你手写 Xray JSON 配置这件事，变成在浏览器里点选协议、填端口、加用户。官方 README 的原话是 「an advanced, open-source web control panel for managing Xray-core servers」（一个用来管理 Xray-core 服务器的高级开源网页控制面板），并且写明它是老项目 X-UI 的增强分支（fork，指从别人的项目复制一份出来自己继续开发）。

这里有个术语要花一句话解释：JSON 配置就是一份「用大括号和引号写的设置清单」，长得像 {"port": 443, "protocol": "vless"}。手写它容易漏括号、错一层缩进，而且错了没有任何提示——面板帮你做的就是把这份清单变成表单和勾选框。

你手上其实有四个东西，分工如下

机制：改动一次配置，面板到底做了什么

理解这一层，后面所有的「为什么改了没生效」「为什么连接会断」都不用猜。3x-ui 的 Go 后端是唯一真相源，流程固定四步：

1. 你在面板上的每次改动，先写进数据库（/etc/x-ui/x-ui.db）；
2. 后端重新渲染一份完整的 Xray 配置（内存里的 JSON 对象）；
3. 它先尝试热应用（hot apply，意思是「不重启进程，把变化直接推给正在运行的程序」）：把新旧配置做差，只把「加了哪个用户、删了哪个入站」这类增量通过 Xray 的管理接口推过去——客户端连接不会断；
4. 差量无法热应用时（结构性改动），它退化成整进程重启 Xray——所有连接会断一下。这个重启被一个「30 秒防抖标志」合并：窗口内改十次也只重启一次。

所以「为什么我改了个备注，连接全断了」的答案通常是：这次改动落到了第 4 步。这条链路在官方仓库的架构文档里有明确记载（docs/architecture.md §5.1）。

02它解决什么问题：手写配置到底难在哪

要讲清「没有它会怎样」，最直接的办法是看看有它之前，一个最普通的操作长什么样。

没有它的世界：改一个用户的配额

Xray 本身只认一份 JSON 配置。假设你要给用户 alice 设 100 GB 配额，在纯 Xray 的世界里你要做的事是：打开配置文件、找到对应入站、找到那个客户端条目、手写 email 字段、保存、重启 Xray——而「100 GB 配额」这件事 Xray 根本不管，配额、到期时间、按用户统计流量都不在 Xray 的职责里。你得另外准备一套脚本去读日志、累加流量、超了就改配置重启。

3x-ui 把这一整套做成了界面和定时任务。这就是它存在的理由，可以拆成四件事：

它不解决什么（这几件事它真的不管）

• 它不帮你绕过网络策略：如果你的环境不允许开放入站端口，面板没有任何办法。
• 它不是计费 / 工单 / 用户自助注册系统：它有流量统计和限额，但没有账单、没有续费、没有注册页。
• 它不替你运维服务器：升级、证书到期、防火墙、被封 IP，全是你的事。
• 它不提供「本地代理」：如果你只是想给自己电脑挂一个代理出去，你要的是客户端程序，不是服务端面板。

03什么场景该用它（以及什么时候别用）

这一段本该被放在开头——但它回答的是「我该不该读」，而你能点进这一页，其实已经回答了。所以它挪到这里，等你看完它是什么、解决什么之后再核对一遍。

这四种处境，它是对的工具

• 你有一台自己的 Linux 服务器（VPS，指你租来的那台远端机器），想在上面跑代理服务，并且不想手写 JSON；
• 你要管理多个用户：给每个人单独的流量配额、到期时间、分享链接和订阅地址；
• 你在多台机器上部署，希望一个面板看全部（多节点功能）；
• 你需要一个能看的界面来回答「谁在用、用了多少、什么时候到期」。

前置知识只需要三样：会用 SSH 登录服务器（SSH 就是「在本地终端里操作远端机器」的工具）、知道「端口 = 门牌号」、知道域名和证书大概是怎么回事。其余本文都会给到可照抄的命令——所以难度定在 🟡 进阶，而不是 🟢 入门。

这四种处境，别用它

• 你不想承担服务器运维：这东西装在你自己的机器上，升级、证书到期、防火墙、被封 IP，全是你的事；
• 你只想在自己电脑上开一个本地代理：那你需要的是客户端，不是服务端面板；
• 你要的是团队级的多租户计费系统：面板有流量统计和限额，但它不是计费/工单系统，也不做用户自助注册；
• 你的环境不允许你开放入站端口（例如公司或校园网策略）：3x-ui 帮不了你绕过网络策略。

04怎么装：三条路 + 装之前先看一个真实发现

官方给三条路：安装脚本（推荐）、Docker、手动解压。三条路的产物是一样的——一个开机自启的系统服务 + 一个 x-ui 管理命令 + 一份数据库。

方式一：安装脚本（推荐）

官方 README 给的一行命令是：

bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)

装指定版本，把标签追加在后面（推荐这么做，理由见本节末尾）：

bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) v3.7.0

装滚动开发版（main 分支的最新逐提交预发布版，不是稳定版）：

bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest

这三条命令里的 <( ... ) 是 shell 的「进程替换」写法，意思是「把这条命令的输出当成一个文件交给 bash 去执行」。你不需要理解它的细节，整行复制即可。

链接里的 master 和 main：我实测过

curl -sL https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh -o a.sh
curl -sL https://raw.githubusercontent.com/mhsanaei/3x-ui/main/install.sh  -o b.sh
md5 a.sh b.sh   # 两个摘要相同

装之前值得知道的一件事：校验和实际上被跳过了

README 宣称：「Every release asset is published with a .sha256 sum next to it. Both install.sh and the updater verify the archive against that sum and abort on a mismatch.」（每个发布资产旁边都会带一个 .sha256 校验和文件；安装器和更新器都会核对它，对不上就中止安装。）

.sha256 是什么：一段由文件内容算出来的「指纹」，下载完自己再算一遍，两边一样就说明文件在传输途中没被改动过。

但截至 2026-09-13，这句话对稳定版不成立。用 GitHub API 把最近 100 个 release 的资产名单全查一遍，结果是：只有 dev-latest 这一个预发布版发布了 .sha256 伴随文件（16 个资产），其余 99 个稳定版（含 v3.7.0，8 个资产）一个都没有。两条自查命令：

# ① 最近 100 个 release 里，有几个带 sha256 资产
curl -s "https://api.github.com/repos/MHSanaei/3x-ui/releases?per_page=100" | grep -c sha256

# ② 直接问 v3.7.0 有没有校验和文件（预期 404）
curl -sIL https://github.com/MHSanaei/3x-ui/releases/download/v3.7.0/x-ui-linux-amd64.tar.gz.sha256

而 install.sh 对这种情况的处理写在源码里：拿到 HTTP 404 就打印 「No checksum published for this release, skipping verification」（这个发布没有发布校验和，跳过校验）并继续安装。也就是说，装当前的稳定版时，这一步校验是被静默跳过的。

我不删掉官方那句话、而是把它和实测结果并列摆着——因为这是发布流程的实现问题，随时可能被补上；一旦上游补了校验和文件，脚本的校验分支就会真的生效（源码里那段是「下载失败或对不上就中止安装」，只有 404 被容忍）。

方式二：Docker

仓库自带 docker-compose.yml，所以最省事的是直接用它：

docker compose up -d
# 想用内置的 PostgreSQL：
docker compose --profile postgres up -d

也可以直接用预构建镜像。这里有个真实的坑：镜像内置 Fail2ban（一个「按日志自动封 IP」的小工具），它靠 iptables（Linux 内核里的防火墙工具）执行封禁，因此必须有 NET_ADMIN 权能（IPv6 还要 NET_RAW），否则封禁只会被记录而不会真正生效：

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

逐项解释这份命令里你会想改的部分：-v $PWD/db/:/etc/x-ui/ 把数据库目录挂到宿主机（容器删了数据还在）；-v $PWD/cert/:/root/cert/ 持久化证书；--network=host 让容器直接用宿主机的网络（否则你还得逐个映射入站端口）；--restart=unless-stopped 是开机自启。

compose 文件里还有第三个卷值得抄：$PWD/acme/:/root/.acme.sh/——把 acme.sh 的状态持久化（acme.sh 是自动申请和续期证书的工具），容器重建后证书自动续期的定时任务才不会丢。

方式三：手动（不推荐，除非你有理由）

从 release 页面下载对应架构的归档（例如 https://github.com/MHSanaei/3x-ui/releases/download/v3.7.0/x-ui-linux-amd64.tar.gz），解压后自己写系统服务单元。安装脚本做的就是这些步骤的自动化——而它顺手做对了几件手工容易漏的事。

安装脚本实际做了什么

把 install.sh（v3.7.0 对应版本，当前 1854 行）读一遍，它落地的路径如下，这张表建议收藏：

它还做了两件「手工装容易漏」的事：把服务设成开机自启，以及把仓库里对应标签的服务单元文件按发行版（debian / arch / rhel）装进去。脚本注释解释了为什么必须「按标签取配套文件」：

# 源码注释原文：
# Older tags predate some of these files (x-ui.rc arrived in v2.8.4).
# Serving main's copy against an old binary is the mismatch this pinning exists to prevent.

翻译过来就是：拿 main 分支的配套文件去配一个旧版本的二进制，会产生不匹配，所以脚本按你安装的标签去取配套文件（x-ui.rc 是 Alpine 专用的一份），取不到就直接拒绝安装这个标签，而不是凑合装上去。手工安装时最容易漏掉的正是这一点。

05装完先做这五步，再去建入站

顺序是有讲究的：面板本身就是攻击面。建完入站才去改密码，等于把家门开着装修。下面五步做完再谈功能。

cat /etc/x-ui/install-result.env
# 或者敲 x-ui 进菜单看第 11 项

ssh -L 8080:127.0.0.1:2053 root@你的服务器IP
# 然后本地浏览器打开 http://127.0.0.1:8080/<你的web路径>/

那串随机凭据到底有多强（我按源码的字符集算了一遍）

安装脚本生成随机串的函数是：openssl rand -base64 (长度×2) 字节 | tr -dc 'a-zA-Z0-9' | head -c 长度。把这条管道在本机跑几轮，确认过滤后留下的字符集正好是 62 个（数字 0–9 + 大写 A–Z + 小写 a–z）。据此可以算出：

• 11 位的用户名 / 密码 → 10 × log₂62 ≈ 59.5 bit；
• 19 位的网页访问路径 → 18 × log₂62 ≈ 107.2 bit；
• 随机端口是在 1024–62000 之间的 60,977 个取值里挑（shuf -i 1024-62000 -n 1），单独看并不强——它只是不给扫描器省事，真正的强度来自上面两项。

作为量级参照：以每秒 100 万次猜测穷举 59.5 bit，期望耗时约 2.6 万年；而 107 bit 已经远超任何暴力手段。所以脚本生成的默认凭据本身不弱——真正把它变弱的是人：把它改成 admin123，或者把路径改回 /。

复核方式（三条，都能自己跑）：

# ① 确认字符集正好 62 个，应输出 62
openssl rand -base64 400 | tr -dc 'a-zA-Z0-9' | fold -w1 | sort -u | wc -l

# ② 算 10 位与 18 位的比特数
python3 -c "import math;print(10*math.log2(62), 18*math.log2(62))"

# ③ 算随机端口的取值个数，应输出 60977
python3 -c "print(62000-1024+1)"

内置的登录保护（很多人不知道它已经存在）

06装完之后，命令行里多了个 x-ui：它才是主控制台

装完脚本后，命令行里多了一个 x-ui。不带参数就是交互菜单；带参数就是单次命令——做自动化时用后者，别去模拟菜单输入。

菜单项 0–28（照源码抄的）

菜单的编号和名字直接决定你在教程里看到「菜单 7」时该点哪个，所以原样列出：

两个名词一句话解释：BBR 是 Linux 的一种拥塞控制算法（决定「网络堵了该发多快」），在跨国链路上常常能改善速度；geoip/geosite 是两份「IP 和域名属于哪个地区/哪个类别」的对照表，写路由规则时会引用它们。菜单 20 里的 acme.sh 是一个开源脚本，专门替你向 Let's Encrypt 申请证书并按时自动续期——证书过期是「昨天还好今天全断」的头号原因，所以这个自动续期值得留着。

子命令：写进脚本里的那些

下面这些是从 x-ui.sh 的命令分派表里读出来的，全部可用：

x-ui start | stop | restart      # 面板服务
x-ui restart-xray                # 只重载 Xray
x-ui status                      # 状态
x-ui settings                    # 打印当前设置
x-ui enable | disable            # 开机自启
x-ui log                         # 跟踪调试日志
x-ui banlog                      # 看 Fail2ban 封禁日志
x-ui update | update-dev         # 升级稳定版 / 开发版
x-ui legacy                      # 装指定旧版本
x-ui update-all-geofiles         # 更新全部 geo 文件
x-ui migrateDB [file.db|file.dump] [输出]
x-ui pgclient [ver]              # 升级 pg_dump/pg_restore
x-ui install | uninstall
x-ui setup-fail2ban   # 配置 Fail2ban 的 IP 限制规则（菜单 22 的等价命令）

官方文档在这里和代码对不上：migrate-db 不是 x-ui 的子命令

# ① 走包装脚本（推荐）：
x-ui migrateDB /root/x-ui.db /root/x-ui.dump
# ② 直接调二进制：
/usr/local/x-ui/x-ui migrate-db --src /etc/x-ui/x-ui.db --dump /root/x-ui.sql
# ③ 文档里的 x-ui migrate-db ... —— 只会打印用法，不干活

另外，migrateDB 在把 SQL 还原成 .db 时会检查目标路径：如果目标是正在使用中的 /etc/x-ui/x-ui.db 且面板正在运行，它会直接拒绝，提示你先 x-ui stop 或换个输出路径。这个检查很值钱——省掉一次「运行时替换数据库文件」的事故。

日志与状态：出事先看这三处

日志级别默认是 info，需要更啰嗦时把它调到 debug。查完记得调回去——debug 日志会长得很快。另外面板自带一个清理任务：Xray 的 access/error 日志任一超过 64 MiB 就会被截断（架构文档 §5.4 里的 PruneXrayLogsJob），所以你不用担心它把磁盘写满，但也别指望半年前的访问日志还在。

07文件与目录地图：哪些文件真的在动

这件事在 3x-ui 上比在别的面板上更要紧，因为它的全部状态只有一个数据库文件，而它管着的 Xray 又有自己的配置文件。分不清这两者，备份会备错、排障会找错地方。

一张表管全部

数据库 vs 配置打印件：一条必须分清的分界线

cp /etc/x-ui/x-ui.db /root/x-ui-backup-$(date +%F).db

# 想加一条路由规则
vim /usr/local/x-ui/bin/config.json
systemctl restart x-ui
# 过一会儿规则没了——被面板重新渲染覆盖

# 面板 → Xray 设置 → 直接编辑配置模板
# 保存后面板重载 Xray
# 验证生成结果：
cat /usr/local/x-ui/bin/config.json

08最小例子：十分钟从零到客户端连上

下面这条路径是建议的第一次上手顺序：先把安全和身份做完，再建入站。每一步都给了「点哪里」和「填什么」。

# 在服务器上确认 443 真的在监听
ss -lntp | grep 443
# 确认本机防火墙放行了它（如果用了 ufw）
ufw status

它生成的配置长什么样

服务端那段 streamSettings（Xray 配置里管「传输与安全」的那一块）大致如下，这是最小可用的一部分，其余字段面板会补默认值：

{
  "network": "tcp",
  "security": "reality",
  "realitySettings": {
    "dest": "www.microsoft.com:443",
    "serverNames": ["www.microsoft.com"],
    "privateKey": "<x25519 私钥，只留在服务器上>",
    "shortIds": ["<十六进制 short id>"],
    "fingerprint": "chrome"
  }
}

而给客户端的链接里，携带的是公开参数：

vless://<uuid>@<server>:443?security=reality&pbk=<公钥>&sid=<short-id>&sni=www.microsoft.com&fp=chrome&spx=%2F&flow=xtls-rprx-vision#my-reality

五个参数记一下就够了：pbk 是公钥、sid 是 short id、sni 是对外声称的域名、fp 是客户端指纹、flow 是 xtls-rprx-vision。这条链接本身就是凭据，等于密码。

手工生成一对密钥（不使用面板时）

REALITY 用的是一对「私钥 + 公钥」。面板会替你生成，但知道底层命令在排障时有用：

/usr/local/x-ui/bin/xray-linux-amd64 x25519
# 输出 Private key 与 Public key；私钥填服务端，公钥进分享链接的 pbk=

连上之后怎么确认「真的通了」

四个信号，按可信度从高到低：

前两个是面板给的，后两个是你自己测的。如果面板显示一切正常但网页打不开，去核对客户端的传输与安全设置是否与服务端逐字一致——这是「连上了但没网」最常见的原因。

09入站：配置的最小单位，你要反复回来改的就是它

回落：让一个 443 端口服务多个协议

回落（fallback）是 3x-ui 里最能省事、也最容易被忽略的功能：把一个 TLS 端口上「握手指纹不匹配」的流量，转发给另一个子入站——于是 443 可以同时是 VLESS 和 Trojan，甚至转发给本机的 Nginx 伪装站。

但它有明确的适用条件，官方文档写得很清楚：主入站必须是 VLESS 或 Trojan、必须用裸 TCP、安全层必须是 TLS 或 REALITY。每条回落规则指向一个子入站，可以按 path（路径）、alpn（协议协商结果）、dest（目标）匹配。而且——这点很好——回落子入站的分享链接会被自动改写，对外公布主入站的地址、端口和 TLS，你不需要手工改链接。

443  VLESS + TLS
8443 Trojan + TLS
2096 面板
# 结果：防火墙要开三个口，
# 屏蔽方看到的端口特征明显

443  VLESS + REALITY (主入站)
  └─ fallback → Trojan 子入站
  └─ fallback → 本机 Nginx（伪装站）
# 只开一个端口，子入站链接自动改写

10协议怎么挑：一张表回答「我这个场景选哪个」

面板支持的协议比大多数人用到的多。与其背清单，不如按「你要解决什么」来挑——下表按「定位 / 什么时候选它 / 别当什么用」三列给。

三个容易绕晕的命名

11传输层与安全层：真正决定「像不像正常流量」的一层

协议决定「怎么认证」（怎么证明你是你），传输决定「数据包怎么装」（一次连接里数据长什么样），安全层决定「怎么加密与伪装」。三者是正交的（各管各的，可以自由组合），所以组合数量看起来吓人——但面板只提供有效组合，把不合法的搭配直接藏起来了。

七种传输方式

三个名词一句话带过：CDN 是「分布在全世界的缓存节点，用户连最近的节点，由节点回源到你的服务器」；多路复用是「一条连接里同时跑好几股数据，不用为每个请求重新握手」；QUIC 是跑在 UDP 上的新一代传输协议，把握手和加密揉在一起。

安全层的适用矩阵

两条例外记一下：mKCP 和 Hysteria 没有独立的 TLS/REALITY 层——mKCP 明文运行（用 FinalMask 混淆），而 Hysteria 本身就是 QUIC/TLS。

XTLS-Vision 与后量子加密

xtls-rprx-vision 是一种流控（flow），它又快又抗 DPI。可用条件有两个：裸 TCP + TLS/REALITY 的经典组合，或者 XHTTP 且启用了 VLESS 加密（ML-KEM / mlkem768x25519，也就是所谓「后量子加密」——用一类新的数学难题来加密，目的是防住未来的量子计算机）。

入站：VLESS + TCP + REALITY
前置：Cloudflare 橙云（HTTP 层代理）
# 结果：REALITY 的握手机制
# 需要看到真实 TLS 握手，
# 而 CDN 已经替你终结了 TLS

直连（无中间层）：
  VLESS + TCP + REALITY + Vision

过 CDN / 反向代理：
  VLESS + WS 或 XHTTP + TLS
  （证书用 CDN 的或自己签）

12组合怎么搭：四套推荐 + 三种别用

协议 × 传输 × 安全层的组合很多，但实际值得用的就那几套。下面四套覆盖了绝大多数场景，按「你的约束是什么」来挑。

组合 A：VLESS + TCP + REALITY + Vision（无域名、无证书的首选）

它解决什么：你没有域名、不想管证书，但仍要让流量看起来像访问某个正常网站。什么时候别用：你前面垫了 CDN 或四层转发（见上一节的对比）。

组合 B：VLESS/Trojan + TLS + XHTTP 或 WebSocket（要过 CDN）

把真实服务器地址藏在 CDN 后面，客户端连 CDN 边缘节点。这里用 Host 覆盖（受管主机） 告诉订阅「对外公布的地址是 CDN 域名而不是源站 IP」——这正是「受管主机」这个功能存在的理由（18）。

代价：多一跳，延迟上升；CDN 免费套餐对非 HTTP 流量有条款限制，需要你自己确认合规性。

客户端填订阅地址时，如果 CDN 要求特定 Host 头，面板里对应的是「请求头」一类的字段，例如：

# 受管主机里给某个入口单独指定 Host 与 SNI
Host: cdn.example.com
SNI:  cdn.example.com
Path: /ws        # WebSocket / XHTTP 的秘密路径

组合 C：Shadowsocks-2022 / Hysteria2（要极简或要抗丢包）

• Shadowsocks-2022：客户端支持极广、配置极简。选 2022-blake3-* 加密方式；注意 2022-blake3-chacha20-poly1305 只能单用户。
• Hysteria2：走 UDP/QUIC，在丢包严重的移动网络上体验明显更好。防火墙记得放行 UDP——这是它最常见的「装好了却连不上」原因。

# Hysteria2 客户端拿到的链接形态（端口必须 UDP 放行）
hysteria2://<密码>@<服务器>:8443/?sni=<域名>&insecure=0#hy2

组合 D：WireGuard / AmneziaWG（要整机隧道）

不是「给浏览器挂个代理」，而是把设备的全部流量送进隧道。AmneziaWG 额外做混淆，参数含义如下：垃圾包（Jc/Jmin/Jmax）、握手填充（S1/S2）、改写消息类型魔数（H1–H4）。它跑在面板进程内、用户态网络栈上，所以容器里和裸机上行为一致。

# AmneziaWG 混淆参数（两端必须一致）
Jc = 4        # 每个包前塞几个垃圾包
Jmin = 40     # 垃圾包最小字节
Jmax = 70     # 垃圾包最大字节
S1 = 50       # 握手包填充长度
S2 = 100
H1 = 5        # 消息类型魔数，必须 > 4 且四个互不重叠
H2 = 6
H3 = 7
H4 = 8

三种别用的组合

13客户端与限额：真正决定「谁能用、能用多少」的地方

入站是「门」，客户端是「钥匙」。在当前版本的 3x-ui 里，客户端已经是一等记录——一个客户端可以同时关联到多个入站，并按客户端单独统计流量。这一点跟老版本差别很大，老教程里「一个用户在每个入站里各建一份」的做法已经过时。

alice@vless-443   配额 100GB
alice@trojan-8443 配额 100GB
# 两个 Email → 两套统计
# 用户实际能用 200GB，你还以为限住了

alice@example.com  配额 100GB
  ├─ 关联 vless-443
  └─ 关联 trojan-8443
# 一套统计、一条订阅、一个到期日

14订阅服务器：把一堆链接变成一个地址

分享链接是一条一条发；订阅是「一个 URL 装下这个客户端的全部配置」。客户端定期刷新它，于是你改入站、加节点、换域名，用户不用重新导入任何东西。

# 自己看看订阅服务器会返回什么（换成你的域名/路径/ID）
curl -s "https://你的域名:2096/<subPath>/<subId>" | head -5
# 要人看的页面：
curl -s "https://你的域名:2096/<subPath>/<subId>?html=1" | head -20

# 看响应头，验证用量与刷新间隔真的发出去了
curl -sI "https://你的域名:2096/<subPath>/<subId>" | grep -i "subscription-userinfo\|profile-update"

15分享链接与备注模板：一条 URL 里的全部信息

面板为每个客户端的每个入站生成分享链接与二维码。看懂链接的结构，排障时会快很多——因为客户端连不上时，第一件事就是解出这条链接，逐项核对。

# 后面那段是备注（客户端列表里显示的名字），它不参与连接，只是给人看的。前面那段 userinfo@host:port 才是真正的连接信息。

备注模板：让链接自己说明状态

链接里 # 后面那一段不是手填死的，而是由模板生成。默认值是：

{{INBOUND}}-{{EMAIL}}|📊{{TRAFFIC_LEFT}}|⏳{{DAYS_LEFT}}D

于是你的客户端里会直接显示「入站-邮箱 | 剩余流量 | 剩余天数」。常用占位符有 {{EMAIL}}、{{INBOUND}}、{{STATUS}}（active/expired/depleted/disabled）、{{TRAFFIC_LEFT}}、{{DAYS_LEFT}}、{{PROTOCOL}}/{{TRANSPORT}}/{{SECURITY}} 等。

16出站与路由：决定流量「从哪出去」

入站负责收，出站负责发。默认只有两个出站：freedom（直连到目标）和 blackhole（丢弃，用来挡广告和种子）。要让某些流量走别的线路，就需要出站 + 路由规则。

{
  "outbounds": [
    { "tag": "direct", "protocol": "freedom", "settings": {} },
    { "tag": "block",  "protocol": "blackhole", "settings": {} }
  ]
}

tag 是「这段配置的名字」，路由规则靠它指认「这条流量交给谁」。名字随便起，但必须和规则里写的一致。

路由规则的核心语义：自上而下，第一个匹配者胜出

每条规则是一个 field 匹配器，可以按 domain、ip、port、network、protocol、inboundTag、sourceIP 等匹配，然后指向一个 outboundTag 或 balancerTag。因为先匹配先赢，具体的规则一定要放在通用规则上面——顺序错了，后面那条永远不生效。

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      { "type": "field", "domain": ["geosite:category-ads-all"], "outboundTag": "block" },
      { "type": "field", "ip": ["geoip:private"], "outboundTag": "direct" }
    ]
  }
}

上面这两条的读法是：先把「广告域名」丢进 block，再把「私有网段」走 direct 直连。每一条规则的第三个字段就是「匹配到之后交给谁」。

三条常用出口

• WARP：让你的服务器从 Cloudflare 网络出去。面板能替你注册 WARP 账户并填好一个 tag 为 warp 的 WireGuard 出站，还能按天自动轮换 IP。
• NordVPN / PIA：面板可以按账号拉取服务器列表并生成 WireGuard 出站。要点是标签规则：Nord 用 nord-<hostname>，PIA 用 pia-<region>-<server>，同一台服务器不能重复添加；登出只清除凭据，已生成的出站还在，不再用的要自己去出站列表里删。
• 出站订阅（服务器池）：给一个远程订阅 URL，面板把里面的服务器作为出站动态注入到运行中的配置里，而不改你保存的模板。导入的出站标签是稳定的——同一台服务器多次刷新保持同一个标签，所以按精确标签写的路由不会失效。

均衡器与健康监视器

后两种策略的监视器要放在配置的顶层，不能塞进 routing 里面——这是很常见的一个「配置看着对、但均衡器不工作」的原因。

17多节点与受管主机：一台面板管多台机器

两个功能经常一起被提起，但解决的问题完全不同：节点是「管另一台机器的 3x-ui」，受管主机是「同一个入站，对外公布多个地址」。

节点：通过 API 管理另一个面板

在主面板添加节点时填：名称（如 de-fra-1）、https/http、地址与端口、对方的面板路径、API 令牌（一串长随机字符串，让主面板能免密调用对方的管理接口，所以它等于对方的密码）、TLS 校验模式（verify 默认 / skip / pin 固定证书指纹 / mtls），以及同步哪些入站。之后主面板每隔几秒发一次心跳（定期打个招呼确认对方还活着），更新节点在线状态，并在掉线时发 node.down 事件（可推到 Telegram）。

三个值得知道的机制：

• 身份用 GUID 而不是本地 ID：GUID 是一串全局唯一的随机标识，节点重启后仍保持身份；而且节点还能再管节点，主面板会把更下层呈现为只读的传递性子节点（1 → 2 → 3）。
• 离线期间的修改不会丢：主面板用「dirty」标记记下待同步的改动，节点重新上线后把改动收敛过去。
• 令牌可以加密落盘：NODE_TOKEN_ENCRYPTION 取 off（默认）/ migration / required；注意这个变量没有 XUI_ 前缀，别和别的环境变量写混。开启后若密钥加载失败，面板会拒绝启动——这是刻意的「失败即拒绝」。密钥用下面这条命令生成，且只能写在密钥文件里，不能通过命令行参数传：

openssl rand -base64 32

受管主机：一个入站，多个对外地址

附加在入站上的「覆盖端点」。订阅时，每个启用的主机会用自己的地址、端口、TLS、SNI、Host 头、路径各渲染出一条额外链接。典型用途是：让源站 IP 保持私密（对外公布 CDN 地址）、按地区公布不同端点、为不同端点单独调 ALPN/指纹/ECH/mux。每条主机可以排除特定订阅格式、限定到特定节点。

mTLS：把「拿令牌」升级为「拿证书」

18安全加固：按这个顺序做，别跳步

代理面板是高价值目标：它同时是「入口」和「凭据库」。下面的顺序是有讲究的——先减少暴露面，再加强认证，最后才谈功能。（第 1–5 步与 05 是同一件事的两处表述：那里是「装完先做什么」，这里是「为什么按这个顺序」。）

# 确认 BBR 真的生效（应看到 tcp_congestion_control 为 bbr）
sysctl net.ipv4.tcp_congestion_control

真实客户端 IP：CDN 后面最容易忽略的一环

入站前面垫了 CDN 或四层中转时，Xray 看到的源 IP 是中转方的——于是「在线 IP 列表」和「IP 限制」双双失效。3x-ui 在入站的「传输设置 → Sockopt」里给了两个预设。先解释这两个字段名：trustedXForwardedFor 的意思是「我信任谁在请求头里写的来访者 IP」，它填的是那个头的名字（Cloudflare 用的是 CF-Connecting-IP）；acceptProxyProtocol 的意思是「接受上游用 PROXY 协议把真实 IP 附在连接最前面告诉我」。

docker run -d -p 2053:2053 \
  ghcr.io/mhsanaei/3x-ui:latest
# fail2ban 记录到封禁，但 iptables
# 没有权限执行 → 限制形同虚设

docker run -d \
  --cap-add=NET_ADMIN --cap-add=NET_RAW \
  -e XUI_ENABLE_FAIL2BAN=true \
  ghcr.io/mhsanaei/3x-ui:latest
# 不用 IP 限制就设 false 并去掉 cap_add

19备份、升级、卸载：三件迟早要做的事

备份：只要两样东西

全部配置 = 数据库 + 证书（/root/cert/，如果你用了 TLS）。最简做法就是复制文件：

# 数据库（必须）
cp /etc/x-ui/x-ui.db /root/x-ui-backup-$(date +%F).db
# 证书目录（用了 TLS 就要）
tar czf /root/cert-backup-$(date +%F).tar.gz /root/cert/

面板概览页也能下载备份；配了 Telegram 机器人并开启 tgBotBackup 的话，它会在周期性报告里附上数据库 + Xray 配置，于是你天然拥有一份服务器之外的副本（管理员也能在机器人菜单里按需拉一份）。

还有一种「可读、可搬」的形式——把 SQLite 导成纯文本 SQL：

# 走包装脚本（注意子命令是 migrateDB）
x-ui migrateDB /etc/x-ui/x-ui.db /root/x-ui.dump
# 或直接调二进制
/usr/local/x-ui/x-ui migrate-db --dump /root/x-ui.sql
/usr/local/x-ui/x-ui migrate-db --restore /root/x-ui.sql --out /root/restored.db

恢复的顺序是：先 x-ui stop，把备份文件放回 /etc/x-ui/x-ui.db，再 x-ui start。别在面板运行时替换数据库文件。

升级

跨大版本升级前一定先备份——新版会对数据库做结构迁移，回退需要旧库。

curl -s https://api.github.com/repos/MHSanaei/3x-ui/releases/tags/dev-latest \
  | grep -E '"published_at"|"updated_at"' | head

卸载

菜单 6 或 x-ui uninstall：停服务、禁用自启、移除服务单元、删除 /etc/x-ui/ 与安装目录。如果你装了本地 PostgreSQL，它还会单独问一次是否一并清除。

20连不上时怎么查：按症状分诊

先做一个动作分类：问题在面板侧，还是在链路侧？面板能打开 = 面板侧基本没问题；那么 90% 的故障在链路或配置匹配上。

五条命令，覆盖大多数排障场景

# ① 服务和内核都活着吗
x-ui status

# ② 实时看面板日志（Ctrl+C 退出）
x-ui log

# ③ 只重载 Xray，判断问题在哪一层
x-ui restart-xray

# ④ 我是不是被封了
x-ui banlog

# ⑤ 面板打印当前端口/路径/证书位置
x-ui settings

证书相关的三条硬检查

• 签证书之前，域名必须已经解析到这台服务器——DNS 没生效，验证必然失败；
• HTTP 验证需要 80 端口可被公网访问且当前空闲；否则走 DNS 验证（Cloudflare 那条路）；
• 证书续期时原地续期、不要移动文件：面板读的是固定路径下的文件，原地换掉它，重启后自动加载新证书。

21最常见的坑与常见问题

十个坑，一条一条对

bash <(curl .../install.sh)   # 一路回车
# 面板：2053 + 路径 / + 默认凭据
# 入站：443 VLESS+REALITY

# 1 装完先改身份与入口
x-ui    # 菜单 7 重设凭据 · 开启 2FA
# 菜单 8 随机路径 · 菜单 10 改端口
# 2 上 TLS（菜单 20）
# 3 再建入站 443 / 加客户端 / 放行端口

常见问题

docker exec -it <容器名> x-ui setting -show

22术语对照表：回头查的时候看这一张

99一句话总结