3x-ui3x-ui
快速开始

安装

通过官方脚本(稳定版、指定版本或开发最新版)、无人值守 / cloud-init 或 Docker 安装 3x-ui,并选择 SQLite 或 PostgreSQL。

3x-ui 可运行在多种 Linux 发行版上——Ubuntu、Debian、Armbian、 Fedora、CentOS、RHEL、AlmaLinux、Rocky Linux、Oracle Linux、Amazon Linux、 Virtuozzo、Arch、Manjaro、openSUSE(Tumbleweed/Leap)、Alpine——以及 Windows, 覆盖 amd64386arm64armv7armv6armv5s390x 架构。

请以 root 身份(或使用 sudo)运行脚本安装程序。它会安装服务、 配置 x-ui 管理命令,并将面板设为开机自启。

官方脚本是推荐的安装方式。安装过程中,它会生成一个随机的用户名、密码和访问(Web 根)路径,配置服务, 并安装 x-ui 管理命令。

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

在命令后附加标签即可安装指定版本

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

传入 dev-latest 可安装滚动更新的开发版构建(来自 main 的最新逐提交预发布版本 ——并非稳定版):

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

安装完成后,记下打印出的登录信息并运行 x-ui 打开 管理菜单,然后 继续阅读首次登录

默认的 Compose 配置使用 SQLite。克隆仓库(或复制其 docker-compose.ymlDockerfile)并启动:

docker compose up -d

如需使用内置的 PostgreSQL 服务,请取消 docker-compose.yml 中两行 XUI_DB_* 的注释,并使用对应 profile 启动:

docker compose --profile postgres up -d

更想用预构建镜像?它已发布到 GitHub Container Registry。该镜像内置了 Fail2ban(用于 IP 限制),其封禁通过 iptables 实现,因此需要 NET_ADMIN (IPv6 还需 NET_RAW)—— 否则封禁只会被记录,而不会实际生效:

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 证书,因此你的数据可在升级后保留。

高级用户可从发布页面 下载适用于你架构的发布归档包,解压后 将二进制文件作为 systemd 服务运行。安装脚本正是将这些步骤自动化, 因此除非你有特定理由要手动安装,否则更推荐使用脚本。

构建你的安装命令

根据你的环境定制命令:

Install command builder

Build the exact install command for your setup. It is assembled in your browser.

blank = latest stable · a tag like v3.4.0 · or dev-latest for the rolling dev build
Run on your server
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)

选择数据库

你在安装时选择存储后端:

  • SQLite(默认)——位于 /etc/x-ui/x-ui.db 的单个文件。无需任何配置。
  • PostgreSQL——适用于客户端数量庞大或多节点的部署。安装程序 可以在本地安装它,也可以使用你提供的 DSN。

详情及 SQLite→PostgreSQL 迁移请参见数据库

无人值守 / cloud-init

安装程序也可非交互式运行,用于自动化。设置 XUI_NONINTERACTIVE=1(或在无 TTY 的环境下运行),它便会全程零提示地完成 端到端安装,生成随机凭据并写入 /etc/x-ui/install-result.env

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

仓库的 deploy/ 目录提供了现成的 cloud-init user-data,可用于在任意云平台上进行无人值守安装 (Hetzner、AWS、DigitalOcean、Vultr、GCP、Azure、Oracle)。

后续步骤

On this page