3x-ui/README.md

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

3X-UI — advanced, open-source web-based control panel designed for managing Xray-core server. It offers a user-friendly interface for configuring and monitoring various VPN and proxy protocols.

Important

This project is only for personal usage, please do not use it for illegal purposes, and please do not use it in a production environment.

As an enhanced fork of the original X-UI project, 3X-UI provides improved stability, broader protocol support, and additional features.

Custom GeoSite / GeoIP DAT sources

Administrators can add custom GeoSite and GeoIP .dat files from URLs in the panel (same workflow as updating built-in geofiles). Files are stored under the same directory as the Xray binary (XUI_BIN_FOLDER, default bin/) with deterministic names: geosite_<alias>.dat and geoip_<alias>.dat.

Routing: Xray resolves extra lists using the ext: form, for example ext:geosite_myalias.dat:tag or ext:geoip_myalias.dat:tag, where tag is a list name inside that DAT file (same pattern as built-in regional files such as ext:geoip_IR.dat:ir).

Reserved aliases: Only for deciding whether a name is reserved, the panel compares a normalized form of the alias (strings.ToLower, - → _). User-entered aliases and generated file names are not rewritten in the database; they must still match ^[a-z0-9_-]+$. For example, geoip-ir and geoip_ir collide with the same reserved entry.

Quick Start

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

For full documentation, please visit the project Wiki.

Database Backends

3X-UI supports both SQLite and PostgreSQL as interchangeable backends. All application logic is written against GORM — Go's database-agnostic ORM — so queries work identically on either engine. You can switch backends at any time through the panel UI without data loss.

Choosing a Backend

	SQLite	PostgreSQL
Setup	Zero config, file-based	Requires a running PG server
Best for	Single-node, low traffic	Multi-node, high concurrency
Backups	Portable + native file export	Portable export

Switching Backends (Panel UI)

1. Open Settings → General → Database.
2. Select a backend (SQLite or PostgreSQL) and fill in connection details.
3. Click Test Connection to verify.
4. Click Switch Database — the panel will:
   • Save a portable backup of current data automatically.
   • Migrate all data to the new backend.
   • Restart itself.

The target database must be empty before switching. Use Test Connection before switching to catch misconfigurations early.

Local PostgreSQL (panel-managed)

When selecting Local (panel-managed) mode, the panel installs and manages PostgreSQL automatically (Linux, root only):

# The panel uses postgres-manager.sh internally.
# No manual PostgreSQL setup required.

External PostgreSQL

Point the panel at any existing PostgreSQL 13+ server:

1. Create a dedicated database and user.
2. Enter the connection details in Settings → Database.
3. Use Test Connection, then Switch Database.

Environment Variable Override

For Docker and infrastructure-as-code deployments, set these environment variables to control the backend without touching the UI:

XUI_DB_DRIVER=postgres        # or: sqlite
XUI_DB_HOST=127.0.0.1
XUI_DB_PORT=5432
XUI_DB_NAME=x-ui
XUI_DB_USER=x-ui
XUI_DB_PASSWORD=change-me
XUI_DB_SSLMODE=disable        # or: require, verify-ca, verify-full
XUI_DB_MODE=external          # or: local
XUI_DB_PATH=/etc/x-ui/db/x-ui.db   # SQLite only

When any XUI_DB_* variable is set, the Database section in the panel UI becomes read-only.

Backup & Restore

Format	Works with	When to use
Portable (.xui-backup)	SQLite + PostgreSQL	Switching backends, Telegram bot backups, long-term storage
Native SQLite (.db)	SQLite only	Quick raw file backup while on SQLite

• The Telegram bot sends a portable backup automatically — this works regardless of which backend is active.
• Portable backups can be imported back on either SQLite or PostgreSQL.
• Legacy .db files from older 3x-ui versions can be imported even while PostgreSQL is active.

A Special Thanks to

• alireza0

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.

Support project

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

Stargazers over Time