GGyHackPERSONAL JOURNAL · EST.2026
服务器 · JOURNAL

3x-ui使用教程

2026-08-06·9 阅读· 约 21 分钟#Linux#VPN

本文基于官方仓库 MHSanaei/3x-ui 的最新稳定版 v3.6.0（内置 xray-core v26.7.28）编写，教程时间为 2026 年 8 月。
3x-ui 更新很快，安装前建议先到 Releases 页面确认最新版本号。

一、3x-ui 是什么

3x-ui 是一个开源、免费、基于 Web 的 Xray-core 服务器管理面板，是原版 X-UI 项目的增强分支。它让你不用手写 JSON 配置，就能在浏览器里完成节点创建、用户管理、流量统计、订阅分发等全部操作。

一句话总结：买一台 VPS，装 3x-ui，几分钟就能开出自己的代理节点，并且支持多协议、多用户、多节点、订阅分发。

⚠️ 官方声明：项目仅限个人合法使用，请勿用于非法用途。

二、核心特性

支持的协议（入站）

  • VLESS（推荐，配合 XTLS/REALITY 使用）
  • VMess（配合 TLS/WebSocket/CDN 使用）
  • Trojan
  • Shadowsocks
  • WireGuard（多客户端）
  • Hysteria2
  • HTTP / SOCKS（Mixed）
  • Dokodemo-door / Tunnel
  • TUN
  • MTProto（Telegram 专用，FakeTLS）

支持的传输方式与安全

  • 传输：TCP（Raw）、mKCP、WebSocket、gRPC、HTTPUpgrade、XHTTP
  • 安全：TLS、XTLS、REALITY（当前最推荐的免域名伪装方案）
  • 流控：xtls-rprx-vision
  • Fallback：单端口多协议（如 443 端口同时跑 VLESS 和 Trojan）

管理能力

  • 每个客户端独立管理：流量配额、到期时间、IP 数量限制、在线状态
  • 一键生成分享链接、二维码、订阅
  • 内置订阅服务器，支持原生 / Clash / JSON 等多种输出格式和自定义页面模板
  • 出入站流量统计（按入站、客户端、出站）
  • 多节点管理（一个面板管理多台服务器）
  • 出站与路由：WARP、自定义规则、负载均衡、出站代理链
  • Telegram 机器人远程管理、事件通知（TG / SMTP）
  • RESTful API（面板内 Swagger 文档）
  • 存储：SQLite（默认）或 PostgreSQL
  • 13 种界面语言（含简体中文）、明暗主题
  • Fail2ban 原生集成，用于强制按客户端 IP 限制

三、系统要求与支持范围

操作系统

Linux：Ubuntu、Debian、Armbian、Fedora、CentOS、RHEL、AlmaLinux、Rocky Linux、Oracle Linux、Amazon Linux、Virtuozzo、Arch、Manjaro、Parch、openSUSE、Alpine；另有 Windows 版本。

架构

amd64、386、arm64（aarch64）、armv7、armv6、armv5、s390x。

推荐配置

  • 个人使用：1 核 512MB 内存的 VPS 完全够用
  • 内存建议至少 512MB，面板 + Xray 运行更稳定
  • 系统推荐 Debian/Ubuntu 最新 LTS

四、安装与首次初始化

4.1 一键脚本安装（推荐）

SSH 登录服务器（root 或可 sudo 用户），执行：

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.6.0

安装滚动开发版（非稳定版，仅测试用）：

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

4.2 安装过程中的交互选项

安装脚本会询问：

  1. 数据库选择：SQLite（默认，适合 < 500 客户端）或 PostgreSQL（适合大量客户端/多节点）
  2. 面板凭据：是否自定义端口？是否使用随机生成？默认会生成随机端口 + 随机用户名 + 随机密码 + 随机访问路径
  3. SSL 证书：是否申请 Let's Encrypt 证书（现在支持域名和 IP 地址）
  4. 监听方式：是否将面板只绑定到 127.0.0.1（推荐，配合 SSH 隧道或反代访问）

🔴 新版重要变化：v3.x 安装时默认生成随机凭据，不再是老的 admin/admin、端口 54321。安装完成后界面会直接打印：

Username:    xxxxxxxx
Password:    xxxxxxxx
Port:        3xxxx
WebBasePath: xxxxxxxxxxxxxxxxxx
Access URL:  http://IP:端口/路径
API Token:   xxxx

请务必截图保存这些信息，忘记后可通过 x-ui 菜单找回/重置。

4.3 非交互安装（云服务器初始化）

用于 cloud-init 或自动化脚本，设置 XUI_NONINTERACTIVE=1 后全程无提示，凭据写入 /etc/x-ui/install-result.env：

XUI_NONINTERACTIVE=1 \
XUI_USERNAME=myadmin \
XUI_PASSWORD=myStrongPass \
XUI_PANEL_PORT=54321 \
XUI_WEB_BASE_PATH=/panel \
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)

常用环境变量：

变量说明默认
XUI_NONINTERACTIVE非交互模式0
XUI_USERNAME / XUI_PASSWORD面板登录账号/密码随机生成
XUI_PANEL_PORT面板端口随机生成
XUI_WEB_BASE_PATH面板访问路径随机生成
XUI_DB_TYPEsqlite / postgressqlite
XUI_DB_DSNPostgreSQL 连接串—
XUI_INIT_WEB_BASE_PATH初始 Web 路径/
XUI_ENABLE_FAIL2BAN启用 fail2ban IP 限制true

4.4 安装完成后

浏览器打开安装结束时的 Access URL，输入用户名密码登录。首次登录建议立刻：

  1. 进入 面板设置 → 安全设定：开启 2FA（两步验证）
  2. 确认/修改账号密码
  3. 配置 SSL 证书或反代，避免明文 HTTP 暴露

五、x-ui 命令行管理菜单

服务器上运行 x-ui 即可打开管理菜单（v3.x 当前选项 0-28）：

选项功能
0退出脚本
1安装
2更新（稳定版）
3更新到 Dev 通道（滚动开发版）
4更新菜单脚本
5Legacy 旧版本
6卸载
7重置用户名与密码
8重置 Web Base Path
9重置面板设置（账号数据保留）
10修改面板端口
11查看当前设置
12-17启动 / 停止 / 重启面板、重启 Xray、查看状态、日志管理
18-19启用 / 禁用开机自启
20SSL 证书管理（acme.sh）
21Cloudflare SSL 证书
22IP 限制管理（fail2ban）
23防火墙管理
24SSH 端口转发管理
25PostgreSQL 管理
26启用 BBR
27更新 Geo 数据库文件
28Ookla 测速

常用子命令（无需进菜单）：

x-ui start          # 启动
x-ui stop           # 停止
x-ui restart        # 重启
x-ui restart-xray   # 只重启 Xray 核心
x-ui status         # 状态
x-ui settings       # 查看当前设置
x-ui log            # 查看日志
x-ui update         # 更新到最新稳定版
x-ui update-dev     # 更新到 Dev 通道
x-ui migrateDB      # SQLite .db <-> .dump 互转
x-ui uninstall      # 卸载

六、面板界面总览

登录后的主要模块（新版 React 界面）：

模块说明
概览（Overview）系统状态、在线客户端、实时速率、流量图表
入站列表（Inbounds）管理所有节点（添加/编辑/删除、客户端、分享、二维码）
出站列表（Outbounds）出站配置（WARP、自定义出站、负载均衡）
规则列表（Routing）路由规则、DNS、出站代理链
节点（Nodes）多节点同步与管理
订阅（Subscription）订阅服务开关、端口、路径、格式模板
面板设置（Settings）Web 服务、安全、TG 机器人、订阅、通知、LDAP
统计（Statistics）流量统计、在线列表
日志（Logs）Xray 运行日志、访问日志
备份（Backup & Restore）数据库备份与恢复

七、创建第一个节点：VLESS + XTLS Reality（推荐，免域名）

VLESS + Reality 是目前最推荐的方案：不需要域名、不需要申请证书、伪装成正常 TLS 流量、抗封锁能力强。

7.1 准备工作

  • 记下服务器 IP 和公网端口（如 443、8443）
  • 确认面板能正常访问
  • 准备一个要伪装的网站（目标网站），推荐选择稳定的大站，如：
    • www.apple.com
    • www.microsoft.com
    • dl.google.com
    • www.cloudflare.com

7.2 添加入站

  1. 左侧进入 入站列表 → 点击 添加入站
  2. 填写：
    • 备注：如 vless-reality-443
    • 协议：VLESS
    • 端口：443（或自定义，如 8443）
  3. 点击 客户 区域的 添加客户：
    • 备注/邮箱（Email）：建议填唯一标识，如 user1
    • UUID（ID）：点击生成
    • 流量限制：按需设置（如 100GB）
    • 到期时间：按需设置
    • IP 限制：按需设置（如 1 表示同一时间只能一个 IP 在线）
  4. 传输 保持默认 TCP（RAW）
  5. 安全 选择 REALITY：
    • 点击 获取新证书/生成 生成密钥对，得到 公钥（PublicKey） 和 私钥（PrivateKey）
    • Dest（目标网站）：填伪装目标，如 www.apple.com:443
    • Server Names（SNI）：填与 Dest 对应的域名，如 www.apple.com
    • Short IDs：点击生成一个（如 0123456789abcdef）
    • 流控（Flow）：选 xtls-rprx-vision
  6. 点击 保存，然后点击 重启 Xray 使配置生效

7.3 客户端连接

回到入站列表，点击该入站客户端的 二维码/分享链接，用 v2rayN、v2rayNG、Nekoray、Shadowrocket、Clash（Mihomo）等客户端扫码或复制导入。

手动填写的客户端参数对照：

参数值
地址你的服务器 IP
端口入站端口（如 443）
协议VLESS
UUID客户端的 ID
流控（Flow）xtls-rprx-vision
传输TCP
安全Reality
SNI（Server Name）伪装域名（如 www.apple.com）
公钥（PublicKey）面板生成的公钥
Short ID面板生成的 Short ID
指纹（Fingerprint）chrome

💡 连接不上时，先检查防火墙是否放行了节点端口，再检查 SNI/Dest/公钥/Short ID 是否与面板一致。

八、其他常用协议速览

VMess + WebSocket + TLS（配合 CDN 隐藏 IP）

适合有域名且想套 CDN 的场景：

  1. 入站协议选 VMess，传输选 WebSocket，路径随意（如 /ws）
  2. 安全选 TLS，绑定域名证书（面板设置里申请或上传）
  3. 域名解析到 Cloudflare 等 CDN，开启代理（橙云）
  4. 客户端地址填域名，SNI 填域名，路径与面板一致

Trojan + TLS

与 VMess 类似，协议选 Trojan，TLS 证书绑定域名，配置简单，识别度低。

Hysteria2

基于 QUIC 的新协议，抗丢包能力强，适合弱网环境；3x-ui 原生支持，配置时填密码和端口即可。

Shadowsocks

轻量老牌协议，协议选 Shadowsocks，填密码和加密方式（推荐 2022-blake3-aes-256-gcm）。

WireGuard

3x-ui 的 WireGuard 入站已原生支持多客户端，按对等节点（Peer）管理，每个客户端在子网内分配 IP。

MTProto（Telegram）

通过内置 mtg 边车提供 FakeTLS 支持，每个客户端独立密钥与配额，适合直连 Telegram。

九、客户端管理与订阅

9.1 客户端管理

在入站编辑页的 客户 列表可以：

  • 添加/删除客户端
  • 一键生成 UUID
  • 设置流量限制、到期时间、IP 限制
  • 单独禁用/启用某个客户端
  • 查看在线状态与实时速率
  • 批量操作（批量启用/禁用、批量设置 XTLS Flow）
  • 导出分享链接、二维码、订阅链接

9.2 订阅功能

订阅让你一次配置，长期自动更新，客户端不需要手动改节点。

  1. 进入 面板设置 → 订阅设置：
    • 开启订阅服务（Enable Subscription）
    • 订阅端口（默认 2096）、路径（默认 /sub/）
    • JSON 路径（默认 /json/）
    • 按需勾选输出格式：原生 / Clash / JSON
  2. 回到客户端列表，复制该客户的 订阅链接
  3. 在 v2rayN / v2rayNG / Nekoray / Shadowrocket / Clash 等客户端中 从剪贴板导入订阅 URL

订阅地址格式类似：

http://服务器IP:2096/sub/xxxxxxxx

🔒 订阅链接里包含服务器信息和 UUID，等于节点凭据，不要公开分享。

9.3 自定义订阅模板

面板支持自定义订阅落地页模板、Clash 模板、JSON 模板，还可以用 {{EMAIL}}、{{TRAFFIC_USED}} 等变量动态生成展示内容，适合做分发页。

十、Telegram 机器人通知

  1. 在 Telegram 里找 @BotFather，发送 /newbot 创建机器人，拿到 Bot Token
  2. 把机器人拉进一个群或给自己发消息，获取 Chat ID（可搜索 @userinfobot）
  3. 面板 设置 → Telegram 设置：
    • 开启机器人（Enable）
    • 填入 Token 和 Chat ID
    • 设置定时上报（支持 cron 表达式，如 @daily）
  4. 保存后点 测试 验证能否收到消息

机器人支持：登录提醒、到期提醒、流量提醒、CPU/内存告警、远程查询、一键备份等。

十一、备份与恢复

备份的本质是备份数据库，3x-ui 的数据（节点、用户、流量、设置）都存在数据库里。

11.1 面板内备份（推荐）

进入 备份（Backup & Restore）：

  • 点击 备份，下载数据库文件（SQLite 为 .db，PostgreSQL 为 .dump）
  • 需要恢复时，上传备份文件点恢复

11.2 SQLite 文件备份

默认数据库路径：/etc/x-ui/x-ui.db

# 先停面板再拷贝，避免写到一半的脏数据（v3.6 已支持在线快照，但仍建议停机拷贝）
x-ui stop
cp /etc/x-ui/x-ui.db /root/x-ui-backup-$(date +%F).db
x-ui start

11.3 SQLite <-> dump 互转

x-ui migrateDB /etc/x-ui/x-ui.db /root/x-ui.dump
x-ui migrateDB /root/x-ui.dump /root/x-ui-restored.db

11.4 迁移到 PostgreSQL

x-ui migrate-db --dsn "postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable"

然后把 /etc/default/x-ui（Debian 系）中的数据库环境变量改为：

XUI_DB_TYPE=postgres
XUI_DB_DSN=postgres://xui:password@127.0.0.1:5432/xui?sslmode=disable

重启生效：

systemctl restart x-ui

迁移完成并验证无误后再删除原 SQLite 文件。

十二、升级与日常维护

12.1 升级面板

升级不会丢数据（数据库独立于二进制）：

x-ui update            # 升级到最新稳定版
x-ui update-dev        # 升级到 Dev 通道（滚动开发版）

也可以在面板 概览 页面点更新。

12.2 日常维护命令

x-ui status            # 状态
x-ui restart           # 重启面板 + Xray
x-ui restart-xray      # 只重启 Xray
x-ui log               # 面板/Xray 日志
x-ui banlog            # fail2ban 封禁日志
x-ui update-all-geofiles  # 更新 geo 数据库（geoip/geosite）

12.3 启用 BBR 加速

x-ui 菜单选 26. Enable BBR，或手动：

echo "net.core.default_qdisc=fq" >> /etc/sysctl.conf
echo "net.ipv4.tcp_congestion_control=bbr" >> /etc/sysctl.conf
sysctl -p

12.4 防火墙

x-ui 菜单选 23. Firewall Management 可管理防火墙。手动放行示例（ufw）：

ufw allow 443/tcp        # 节点端口
ufw allow 54321/tcp      # 面板端口（按实际）
ufw allow 2096/tcp       # 订阅端口（如开启）

十三、安全加固最佳实践

以下措施按优先级排列，建议逐条执行：

  1. 尽快修改默认随机凭据并保存：新版安装虽然生成随机密码，但有人会改回简单密码；建议使用强密码 + 独立随机端口 + 随机路径
  2. 开启 2FA：面板设置 → 安全设定 → 两步验证（敏感设置变更还会要求二次确认 2FA）
  3. 使用 HTTPS：
    • 安装时申请 Let's Encrypt 证书（支持域名和 IP）
    • 或安装后用 x-ui 菜单 20. SSL Certificate Management 申请
    • 或前面套 Nginx/Caddy 反代终结 TLS
  4. 面板只绑定本机：安装时选择只监听 127.0.0.1，通过 ssh -L 隧道或反代访问；面板永不直接暴露公网
  5. 节点端口与面板端口分开：不要用同一个端口
  6. 客户端 IP 限制 + fail2ban：给每个客户端设置 IP 数量限制，暴力破解会被 fail2ban 自动封禁（安装时已默认启用）
  7. API Token 只写一次：v3.x 的节点 API Token 是只读展示的（创建后不再返回），请创建时保存；新版 openapi.json 已要求登录后才能访问
  8. 订阅链接保密：订阅地址 = 节点凭据，泄露后别人可直接用
  9. 定期备份数据库：可以配 cron 每天备份到本地/对象存储
  10. 保持更新：3x-ui 几乎每个版本都有安全修复（如日志路径写入漏洞修复），不要长期停在旧版本

十四、常见问题排查

现象排查方向
登录不了面板端口/路径是否正确？防火墙是否放行？服务是否运行（x-ui status）？
忘记账号密码x-ui 菜单选 7 重置用户名密码（会关闭 2FA）
忘记面板路径x-ui settings 查看，或菜单 8 重置 Web Base Path
节点连不上服务器防火墙放行节点端口；客户端与面板的端口/SNI/公钥/Short ID/Flow 是否完全一致
REALITY 连不上Dest 与 ServerNames 是否匹配且可访问；换一个伪装目标试试
客户端能连但无法上网检查 DNS 与路由规则；确认服务器可正常访问外网；试 curl -v https://www.google.com
流量不统计确认 Xray 正常运行；新版在线状态从 Xray 在线 API 读取，不再解析 access.log
订阅不更新订阅服务是否开启、端口是否放行、路径是否正确
升级后配置丢了先检查数据库文件是否还在（/etc/x-ui/x-ui.db）；有备份就恢复
IP 限制不生效fail2ban 是否安装并运行（x-ui banlog 查看封禁日志）

十五、Docker 部署

3x-ui 提供官方 Docker 镜像 ghcr.io/mhsanaei/3x-ui，适合容器化环境：

git clone https://github.com/MHSanaei/3x-ui.git
cd 3x-ui
docker compose up -d

要点：

  • 默认使用 SQLite，数据卷挂载到容器内 /etc/x-ui/

  • 需要 PostgreSQL 时启用 profile：

    docker compose --profile postgres up -d

  • 镜像内置 fail2ban（默认开启），用 iptables 封禁需要 NET_ADMIN 能力，docker-compose.yml 已通过 cap_add 配置；如果手动 docker run，要加上：

    docker run -d --cap-add=NET_ADMIN --cap-add=NET_RAW ghcr.io/mhsanaei/3x-ui

  • 容器内面板是主进程，重启用 docker restart <容器名>，不要用 systemctl

十六、声明

本教程仅用于学习与技术交流。请遵守当地法律法规，3x-ui 仅限个人合法使用，请勿将其用于任何非法用途或生产环境。使用代理访问的服务同样必须符合所在地区法律与目标平台服务条款。

附：重要链接