3x-ui README

The project's README from github.com/MHSanaei/3x-ui. As one markdown file: README.md.

English | فارسی | العربية | 中文 | Español | Русский | Türkçe

3x-ui

Release Build GO Version Downloads License Go Reference Documentation

3X-UI is an advanced, open-source web control panel for managing Xray-core servers. It provides a clean, multi-language interface for deploying, configuring, and monitoring a wide range of proxy and VPN protocols — from a single VPS to multi-node deployments.

Built as an enhanced fork of the original X-UI project, 3X-UI adds broader protocol support, improved stability, per-client traffic accounting, and many quality-of-life features.

[!IMPORTANT] This project is intended for personal use only. Please do not use it for illegal purposes or in a production environment.

Features

Screenshots

Click to expand Overview Inbounds Add client Configs

Quick Start

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

To install a specific version, append its tag (e.g. v3.7.0):

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

To install the rolling dev build (latest per-commit pre-release from main, not a stable release), pass dev-latest:

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

During installation a random username, password, and access path are generated. After installation, run x-ui to open the management menu, where you can start/stop the service, view or reset your login credentials, manage SSL certificates, and more.

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.

For full documentation — installation, configuration, operations, and the complete API reference — visit docs.sanaei.dev.

Unattended install

The installer also runs non-interactively for cloud-init. Set XUI_NONINTERACTIVE=1 (or pipe with no TTY) and it installs end-to-end with zero prompts, generating random credentials and writing them to /etc/x-ui/install-result.env. See deploy/ for:

Supported Platforms

Operating systems: Ubuntu, Debian, Armbian, Fedora, CentOS, RHEL, AlmaLinux, Rocky Linux, Oracle Linux, Amazon Linux, Virtuozzo, Arch, Manjaro, Parch, openSUSE (Tumbleweed / Leap), Alpine, and Windows.

Architectures: amd64 · 386 · arm64 (aarch64) · armv7 · armv6 · armv5 · s390x.

Database Options

3X-UI supports two backends, chosen during the install:

At runtime the backend is selected via environment variables (the installer writes these to /etc/default/x-ui for you):

XUI_DB_TYPE=postgres
XUI_DB_DSN=postgres://xui:[email protected]:5432/xui?sslmode=disable

Migrating an existing SQLite install to PostgreSQL

x-ui migrate-db --dsn "postgres://xui:[email protected]:5432/xui?sslmode=disable"
# then set XUI_DB_TYPE and XUI_DB_DSN in /etc/default/x-ui and restart:
systemctl restart x-ui

The source SQLite file is left untouched; remove it manually once you have verified the new backend.

Docker

The default docker compose up -d keeps using SQLite. To run with the bundled PostgreSQL service, uncomment the two XUI_DB_* env lines in docker-compose.yml and start with the profile:

docker compose --profile postgres up -d

The image bundles Fail2ban (enabled by default) to enforce per-client IP limits. Fail2ban bans offenders with iptables, which requires the NET_ADMIN capability. docker-compose.yml already grants it via cap_add; if you start the container with docker run instead, add the capabilities yourself, otherwise bans are logged but never applied:

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

Environment Variables

Variable Description Default
XUI_DB_TYPE Database backend: sqlite or postgres sqlite
XUI_DB_DSN PostgreSQL connection string (when XUI_DB_TYPE=postgres) —
XUI_DB_FOLDER Directory for the SQLite database file /etc/x-ui
XUI_DB_MAX_OPEN_CONNS Maximum open connections (PostgreSQL pool) —
XUI_DB_MAX_IDLE_CONNS Maximum idle connections (PostgreSQL pool) —
XUI_INIT_WEB_BASE_PATH The initial URI path for the web panel /
XUI_ENABLE_FAIL2BAN Enable Fail2ban-based IP-limit enforcement true
XUI_LOG_LEVEL Log verbosity (debug, info, warning, error) info
XUI_DEBUG Enable debug mode false
XUI_TUNNEL_HEALTH_MONITOR Enable the tunnel health monitor (probes a URL and restarts xray after repeated failures; a restart drops all clients) false
XUI_TUNNEL_HEALTH_PROXY Proxy the probe is sent through; point it at a local xray inbound so the probe tests the tunnel (e.g. socks5://127.0.0.1:1080). Empty means the probe only checks host connectivity —
XUI_TUNNEL_HEALTH_URL URL probed for tunnel health https://www.cloudflare.com/cdn-cgi/trace
XUI_TUNNEL_HEALTH_INTERVAL Interval between probes 30s
XUI_TUNNEL_HEALTH_TIMEOUT Per-probe timeout 10s
XUI_TUNNEL_HEALTH_FAILURES Consecutive failures before a restart is triggered 3
XUI_TUNNEL_HEALTH_COOLDOWN Minimum delay between consecutive restarts 5m
NODE_TOKEN_ENCRYPTION Encryption at rest for node API tokens: off, migration, or required (note: no XUI_ prefix) off
XUI_NODE_TOKEN_KEY_FILE JSON keyring (mode 0600) holding the active key id and its base64 32-byte keys /etc/x-ui/node_token_key.json
XUI_NODE_TOKEN_KEY A single base64 32-byte key, used only when the key file cannot be loaded —

The complete list is on the environment variables reference.

Supported Languages

The panel UI is available in 13 languages:

English · فارسی · العربية · 中文（简体） · 中文（繁體） · Español · Русский · Українська · Türkçe · Tiếng Việt · 日本語 · Bahasa Indonesia · Português (Brasil)

Contributing

Contributions are welcome. Please read the Contributing Guide before opening an issue or pull request.

A Special Thanks to

Acknowledgment

Community Tools

Tools and integrations built by the community around 3x-ui.

Support project

If this project is helpful to you, you may wish to give it a:star2:

Buy Me A Coffee
Crypto donation button by NOWPayments

Stargazers over Time

Stargazers over time

3x-ui (MHSanaei/3x-ui)

Searching Database…

48.3K ·GitHub
3x-ui
Что это такое?3X-UI — это веб-панель с открытым исходным кодом для управления серверами на базе Xray-core. Она позволяет развертывать, настраивать и отслеживать множество прокси- и VPN-протоколов с одного VPS или сразу на нескольких узлах.
Это настольное приложение или то, что открывается в браузере?Это веб-панель, которую разворачивают на своем сервере. После установки на Linux (или Windows) вы открываете ее в браузере. Установка также добавляет на сервер консольное меню 'x-ui' для запуска и остановки службы и управления учетными данными.
Как установить это на свой VPS?Запустите скрипт установки из раздела Quick Start (при желании можно указать тег версии или dev-latest для текущей сборки). Скрипт автоматически создаст случайные логин, пароль и путь для доступа к панели.
Какие операционные системы и архитектуры поддерживаются?Работает на большинстве популярных дистрибутивов Linux (Ubuntu, Debian, Fedora, CentOS, Arch, Alpine и других), а также в Windows. Поддерживаются архитектуры amd64, 386, arm64, armv7/6/5 и s390x.
Можно ли использовать это в продакшене?Проект прямо указывает, что он предназначен только для личного использования, и предупреждает против применения в продакшене или в незаконных целях. Поэтому относитесь к нему как к инструменту для энтузиастов и личного хостинга, а не как к готовому корпоративному продукту.
Что такое AmneziaWG и зачем его включили?AmneziaWG — это вариант WireGuard, устойчивый к DPI-блокировкам. Он работает полностью внутри панели, на сетевом стеке пользовательского пространства, поэтому вы получаете WireGuard, устойчивый к цензуре, без установки какого-либо модуля ядра или дополнительных пакетов.
Можно ли управлять панелью без входа в веб-интерфейс?Да, есть встроенный Telegram-бот для удаленного мониторинга и управления панелью.
Какую базу данных выбрать: SQLite или PostgreSQL?SQLite используется по умолчанию и не требует настройки, подходит для небольших и средних развертываний. PostgreSQL рекомендуется при большом количестве клиентов или многоузловой конфигурации, а установщик может настроить её за вас.
What are similar projects?nyx, Xray-core, v2ray-agent, 3X-UI_KIT, hiddify-app, Cloudflare-vless-trojan, Open-Box, mtproto.zig
Which topics is it in?post-quantum, reality, mtproto, hysteria2, vmess, vless, wireguard, trojan, shadowsocks, tunnel, grpc, self-hosting
Creator
MHSanaei
Size
75.8 MB
Stars
48.3K
Updated
CommitOct 17Releasev3.10.2Oct 14
Age
3y
Commits · 90 Days