README
¶
English | فارسی | العربية | 中文 | Español | Русский | Türkçe
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
- Multi-protocol inbounds — VLESS, VMess, Trojan, Shadowsocks, WireGuard, Hysteria2, HTTP, SOCKS (Mixed), Dokodemo-door / Tunnel, and TUN.
- Modern transports & security — TCP (Raw), mKCP, WebSocket, gRPC, HTTPUpgrade, and XHTTP, secured with TLS, XTLS, and REALITY.
- Fallbacks — serve multiple protocols on a single port (e.g. VLESS and Trojan on 443) using Xray's fallback support.
- Per-client management — traffic quotas, expiry dates, IP limits, live online status, and one-click share links, QR codes, and subscriptions.
- Traffic statistics — per inbound, per client, and per outbound, with reset controls.
- Multi-node support — manage and scale across multiple servers from a single panel.
- Outbound & routing — WARP, NordVPN, custom routing rules, load balancers, and outbound proxy chaining.
- Built-in subscription server with multiple output formats and custom page templates.
- Telegram bot for remote monitoring and management.
- RESTful API with in-panel Swagger documentation.
- Flexible storage — SQLite (default) or PostgreSQL.
- 13 UI languages with dark and light themes.
- Fail2ban integration for enforcing per-client IP limits.
Screenshots
Click to expand
Quick Start
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)
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.
For full documentation, please visit the project Wiki.
Unattended install & cloud images
The installer also runs non-interactively for cloud-init and golden images.
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:
- Cloud-init user-data — unattended install on any cloud (Hetzner/AWS/DO/Vultr/GCP/Azure/Oracle)
- Packer golden image — build an AWS EC2 AMI + qcow2 (amd64/arm64) with per-instance credentials generated on first boot
- Amazon Lightsail — launch script + reusable snapshot builder
- AWS Marketplace checklist
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:
- SQLite (default) — a single file at
/etc/x-ui/x-ui.db. Zero setup, ideal for small and medium deployments. - PostgreSQL — recommended for high client counts or multi-node setups. The installer can install PostgreSQL locally for you, or accept a DSN to an existing server.
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:password@127.0.0.1:5432/xui?sslmode=disable
Migrating an existing SQLite install to PostgreSQL
x-ui migrate-db --dsn "postgres://xui:password@127.0.0.1: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 |
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
- Iran v2ray rules (License: GPL-3.0): Enhanced v2ray/xray and v2ray/xray-clients routing rules with built-in Iranian domains and a focus on security and adblocking.
- Russia v2ray rules (License: GPL-3.0): This repository contains automatically updated V2Ray routing rules based on data on blocked domains and addresses in Russia.
Community Tools
Tools and integrations built by the community around 3x-ui.
- terraform-provider-3x-ui (License: MIT): Manage inbounds, clients, panel settings, and Xray configuration as code with Terraform / OpenTofu.
Support project
If this project is helpful to you, you may wish to give it a🌟
Stargazers over Time
Documentation
¶
Overview ¶
Package main is the entry point for the 3x-ui web panel application. It initializes the database, web server, and handles command-line operations for managing the panel.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
internal
|
|
|
config
Package config provides configuration management utilities for the 3x-ui panel, including version information, logging levels, database paths, and environment variable handling.
|
Package config provides configuration management utilities for the 3x-ui panel, including version information, logging levels, database paths, and environment variable handling. |
|
database
Package database provides database initialization, migration, and management utilities for the 3x-ui panel using GORM with SQLite or PostgreSQL.
|
Package database provides database initialization, migration, and management utilities for the 3x-ui panel using GORM with SQLite or PostgreSQL. |
|
database/model
Package model defines the database models and data structures used by the 3x-ui panel.
|
Package model defines the database models and data structures used by the 3x-ui panel. |
|
logger
Package logger provides logging functionality for the 3x-ui panel with dual-backend logging (console/syslog and file) and buffered log storage for web UI.
|
Package logger provides logging functionality for the 3x-ui panel with dual-backend logging (console/syslog and file) and buffered log storage for web UI. |
|
mtproto
Package mtproto manages mtg (github.com/9seconds/mtg) sidecar processes that serve MTProto FakeTLS proxies.
|
Package mtproto manages mtg (github.com/9seconds/mtg) sidecar processes that serve MTProto FakeTLS proxies. |
|
performance
Package performance provides profiling, caching, concurrency, and benchmarking infrastructure for X-UI PRO.
|
Package performance provides profiling, caching, concurrency, and benchmarking infrastructure for X-UI PRO. |
|
sub
Package sub provides subscription server functionality for the 3x-ui panel, including HTTP/HTTPS servers for serving subscription links and JSON configurations.
|
Package sub provides subscription server functionality for the 3x-ui panel, including HTTP/HTTPS servers for serving subscription links and JSON configurations. |
|
util/common
Package common provides common utility functions for error handling, formatting, and multi-error management.
|
Package common provides common utility functions for error handling, formatting, and multi-error management. |
|
util/crypto
Package crypto provides cryptographic utilities for password hashing and verification.
|
Package crypto provides cryptographic utilities for password hashing and verification. |
|
util/json_util
Package json_util provides JSON utilities including a custom RawMessage type.
|
Package json_util provides JSON utilities including a custom RawMessage type. |
|
util/link
Package link provides parsers for VPN share links (vmess://, vless://, etc.) and subscription bodies (typically base64-encoded newline lists of such links).
|
Package link provides parsers for VPN share links (vmess://, vless://, etc.) and subscription bodies (typically base64-encoded newline lists of such links). |
|
util/netproxy
Package netproxy builds HTTP clients that route the panel's own outbound requests through an admin-configured proxy, used to reach GitHub and Telegram from servers where those services are filtered.
|
Package netproxy builds HTTP clients that route the panel's own outbound requests through an admin-configured proxy, used to reach GitHub and Telegram from servers where those services are filtered. |
|
util/random
Package random provides utilities for generating random strings and numbers.
|
Package random provides utilities for generating random strings and numbers. |
|
util/reflect_util
Package reflect_util provides reflection utilities for working with struct fields and values.
|
Package reflect_util provides reflection utilities for working with struct fields and values. |
|
util/sys
Package sys provides system utilities for monitoring network connections and CPU usage.
|
Package sys provides system utilities for monitoring network connections and CPU usage. |
|
util/wirecodec
Package wirecodec holds the shared envelope codec for node-to-node config transport: zstd (de)compression, SHA-256 integrity hashing, and the header / capability constants both the panel (sender) and node (receiver) agree on.
|
Package wirecodec holds the shared envelope codec for node-to-node config transport: zstd (de)compression, SHA-256 integrity hashing, and the header / capability constants both the panel (sender) and node (receiver) agree on. |
|
web
Package web provides the main web server implementation for the 3x-ui panel, including HTTP/HTTPS serving, routing, templates, and background job scheduling.
|
Package web provides the main web server implementation for the 3x-ui panel, including HTTP/HTTPS serving, routing, templates, and background job scheduling. |
|
web/controller
Package controller provides HTTP request handlers and controllers for the 3x-ui web management panel.
|
Package controller provides HTTP request handlers and controllers for the 3x-ui web management panel. |
|
web/entity
Package entity defines data structures and entities used by the web layer of the 3x-ui panel.
|
Package entity defines data structures and entities used by the web layer of the 3x-ui panel. |
|
web/global
Package global provides global variables and interfaces for accessing web and subscription servers.
|
Package global provides global variables and interfaces for accessing web and subscription servers. |
|
web/job
Package job provides background job implementations for the 3x-ui web panel, including traffic monitoring, system checks, and periodic maintenance tasks.
|
Package job provides background job implementations for the 3x-ui web panel, including traffic monitoring, system checks, and periodic maintenance tasks. |
|
web/locale
Package locale provides internationalization (i18n) support for the 3x-ui web panel, including translation loading, localization, and middleware for web and bot interfaces.
|
Package locale provides internationalization (i18n) support for the 3x-ui web panel, including translation loading, localization, and middleware for web and bot interfaces. |
|
web/middleware
Package middleware provides HTTP middleware functions for the 3x-ui web panel, including domain validation utilities.
|
Package middleware provides HTTP middleware functions for the 3x-ui web panel, including domain validation utilities. |
|
web/network
Package network provides network utilities for the 3x-ui web panel, including automatic HTTP to HTTPS redirection functionality.
|
Package network provides network utilities for the 3x-ui web panel, including automatic HTTP to HTTPS redirection functionality. |
|
web/service
Package service implements the panel's business-logic layer.
|
Package service implements the panel's business-logic layer. |
|
web/service/panel
Package service: WebSocketService owns the per-connection pump goroutines and bridges the HTTP-layer controller to the broadcast hub.
|
Package service: WebSocketService owns the per-connection pump goroutines and bridges the HTTP-layer controller to the broadcast hub. |
|
web/websocket
Package websocket provides a WebSocket hub for real-time updates and notifications.
|
Package websocket provides a WebSocket hub for real-time updates and notifications. |
|
xray
Package xray provides integration with the Xray proxy core.
|
Package xray provides integration with the Xray proxy core. |
|
tools
|
|
|
openapigen
command
|