安装
通过官方脚本(稳定版、指定版本或开发最新版)、无人值守 / 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,
覆盖 amd64、386、arm64、armv7、armv6、armv5 和 s390x 架构。
请以 root 身份(或使用 sudo)运行脚本安装程序。它会安装服务、
配置 x-ui 管理命令,并将面板设为开机自启。
官方脚本是推荐的安装方式。安装过程中,它会生成一个随机的用户名、密码和访问(Web 根)路径,配置服务,
并安装 x-ui 管理命令。
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.4.0传入 dev-latest 可安装滚动更新的开发版构建(来自 main 的最新逐提交预发布版本
——并非稳定版):
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh) dev-latest默认的 Compose 配置使用 SQLite。克隆仓库(或复制其
docker-compose.yml 和 Dockerfile)并启动:
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 -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:latestdb/ 卷保存 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.
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)。

3x-ui