3x-ui Documentation

Xray panel supporting multi-protocol multi-user expire day & traffic & IP limit (Vmess, Vless, Trojan, ShadowSocks, Wireguard, Hysteria, Tunnel, Mixed,...

44,515 stars Go Go 1 file · ~13,707 tokens #ech#fail2ban#http#hysteria2#mixed#mtproto#nodes#post-quantum
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy 3x-ui on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name 3x-ui -p 2053:2053 --restart always postgres:16-alpine
Configured Services & Ports
⚙️ 3xui
image: build locally
🔌 Ports: 2053:2053
⚙️ postgres
image: postgres:16-alpine
docker-compose.yml
yaml (docker-compose.yml) 
services:
  3xui:
    build:
      context: .
      dockerfile: ./Dockerfile
    container_name: 3xui_app
    # hostname: yourhostname <- optional
    # Optional hard memory cap. When set, the panel derives its Go soft limit
    # (GOMEMLIMIT, ~90% of this cap) so it GCs before the OOM killer fires.
    # mem_limit: 512m
    # The bundled Fail2ban (XUI_ENABLE_FAIL2BAN below) enforces the IP limit
    # with iptables, which needs NET_ADMIN. Without these caps a ban is logged
    # and shown in fail2ban status but never actually applied. NET_RAW covers
    # ip6tables. If you disable Fail2ban, you can drop cap_add.
    #
    # AmneziaWG works in this image: it runs embedded in the panel process
    # (amneziawg-go over a gVisor userspace netstack), so it needs no kernel
    # module and no host tooling. Publish its UDP listen port to use it.
    cap_add:
      - NET_ADMIN
      - NET_RAW
    volumes:
      - $PWD/db/:/etc/x-ui/
      - $PWD/cert/:/root/cert/
      # Persists acme.sh state so certificate auto-renewal survives container
      # recreation (the entrypoint re-registers the renewal cron job from it).
      - $PWD/acme/:/root/.acme.sh/
    environment:
      XRAY_VMESS_AEAD_FORCED: "false"
      XUI_ENABLE_FAIL2BAN: "true"
      # Memory tuning. The panel keeps RAM low via GOGC + periodic release; it no
      # longer sets a soft limit from total host RAM (no benefit, risks GC thrash).
      # XUI_GOGC: "75"              # lower = less RAM, slightly more CPU; GOGC env overrides
      # XUI_MEMORY_RELEASE_INTERVAL: "10"  # minutes between FreeOSMemory; 0 disables
      # Go memory soft limit, only applied from an explicit budget below (or a
      # real cgroup/mem_limit cap). Pin it with one of:
      # XUI_MEMORY_LIMIT: "400"      # in MiB
      # GOMEMLIMIT: "400MiB"         # Go syntax, takes precedence
      # XUI_PPROF: "true"           # expose pprof on 127.0.0.1:6060 for profiling
      # XUI_INIT_WEB_BASE_PATH: "/"
      # XUI_PORT: "8080"
      # To use PostgreSQL instead of the default SQLite, run:
      #   docker compose --profile postgres up -d
      # and uncomment the two lines below.
      # XUI_DB_TYPE: "postgres"
      # XUI_DB_DSN: "postgres://xui:xui@postgres:5432/xui?sslmode=disable"
    tty: true
    ports:
      # When XUI_PORT is set, publish the same container port (for example "8080:8080").
      - "2053:2053"
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    container_name: 3xui_postgres
    profiles: ["postgres"]
    environment:
      POSTGRES_USER: xui
      POSTGRES_PASSWORD: xui
      POSTGRES_DB: xui
    volumes:
      - $PWD/pgdata/:/var/lib/postgresql/data
    restart: unless-stopped

File: README.md

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
bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)

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

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

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

bash
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.

For full documentation, please visit the project Wiki.

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:

  • 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):

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

Migrating an existing SQLite install to PostgreSQL

bash
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:

bash
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:

bash
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

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:star2:

Stargazers over Time

File: README.ar_EG.md

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

3X-UI هي لوحة تحكم ويب متقدمة ومفتوحة المصدر لإدارة خوادم Xray-core. توفّر واجهة نظيفة ومتعددة اللغات لنشر وتكوين ومراقبة مجموعة واسعة من بروتوكولات الوكيل وVPN — من خادم VPS واحد إلى عمليات النشر متعددة العقد.

تم بناء 3X-UI كنسخة محسّنة (fork) من مشروع X-UI الأصلي، وتضيف دعمًا أوسع للبروتوكولات، واستقرارًا محسّنًا، ومحاسبة للترافيك لكل عميل، والعديد من ميزات تحسين تجربة الاستخدام.

[!IMPORTANT]
هذا المشروع مخصص للاستخدام الشخصي فقط. يرجى عدم استخدامه لأغراض غير قانونية أو في بيئة إنتاجية.

الميزات

  • اتصالات واردة متعددة البروتوكولات — VLESS، VMess، Trojan، Shadowsocks، WireGuard، Hysteria2، HTTP، SOCKS (Mixed)، Dokodemo-door / Tunnel و TUN.
  • وسائل نقل وأمان حديثة — TCP (Raw)، mKCP، WebSocket، gRPC، HTTPUpgrade و XHTTP، مؤمَّنة بـ TLS و XTLS و REALITY.
  • Fallback — تقديم عدة بروتوكولات على منفذ واحد (مثل VLESS و Trojan على المنفذ 443) باستخدام ميزة fallback في Xray.
  • إدارة لكل عميل — حصص الترافيك، تواريخ انتهاء الصلاحية، حدود IP، حالة الاتصال المباشرة، وروابط مشاركة وأكواد QR واشتراكات بنقرة واحدة.
  • إحصائيات الترافيك — لكل اتصال وارد، ولكل عميل، ولكل اتصال صادر، مع عناصر تحكم لإعادة التعيين.
  • دعم العقد المتعددة — إدارة وتوسيع عبر عدة خوادم من لوحة واحدة.
  • الاتصالات الصادرة والتوجيه — WARP، NordVPN، قواعد توجيه مخصصة، موازنات تحميل، وتسلسل الوكلاء الصادرة.
  • خادم اشتراك مدمج بصيغ إخراج متعددة وقوالب صفحات مخصصة.
  • روبوت تيليجرام للمراقبة والإدارة عن بُعد.
  • واجهة RESTful API مع توثيق Swagger داخل اللوحة.
  • تخزين مرن — SQLite (افتراضي) أو PostgreSQL.
  • 13 لغة لواجهة المستخدم مع سمات داكنة وفاتحة.
  • تكامل مع Fail2ban لفرض حدود IP لكل عميل.

لقطات الشاشة

انقر للتوسيع

البدء السريع

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

لتثبيت إصدار محدد، أضِف وسمه (مثل v3.4.0):

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

لتثبيت بنية dev المتجددة (أحدث إصدار أولي لكل التزام (commit) من main، وليس إصدارًا مستقرًا)، مرّر dev-latest:

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

أثناء التثبيت، يتم إنشاء اسم مستخدم وكلمة مرور ومسار وصول عشوائية. بعد التثبيت، شغّل x-ui لفتح قائمة الإدارة، حيث يمكنك بدء/إيقاف الخدمة، وعرض أو إعادة تعيين بيانات تسجيل الدخول، وإدارة شهادات SSL، والمزيد.

للحصول على الوثائق الكاملة، يرجى زيارة ويكي المشروع.

التثبيت غير التفاعلي

يعمل المثبِّت أيضًا بشكل غير تفاعلي لـ cloud-init.
عيّن XUI_NONINTERACTIVE=1 (أو مرّره عبر أنبوب دون TTY) وسيتولى التثبيت من البداية إلى النهاية
دون أي مطالبات، مُنشئًا بيانات اعتماد عشوائية وكاتبًا إياها في
/etc/x-ui/install-result.env. راجع deploy/ لـ:

المنصات المدعومة

أنظمة التشغيل: Ubuntu، Debian، Armbian، Fedora، CentOS، RHEL، AlmaLinux، Rocky Linux، Oracle Linux، Amazon Linux، Virtuozzo، Arch، Manjaro، Parch، openSUSE (Tumbleweed / Leap)، Alpine و Windows.

المعماريات: amd64 · 386 · arm64 (aarch64) · armv7 · armv6 · armv5 · s390x.

خيارات قاعدة البيانات

يدعم 3X-UI خلفيتين (backends) يتم اختيارهما أثناء التثبيت:

  • SQLite (افتراضي) — ملف واحد في /etc/x-ui/x-ui.db. بدون إعداد، مثالي لعمليات النشر الصغيرة والمتوسطة.
  • PostgreSQL — موصى به لأعداد العملاء الكبيرة أو الإعدادات متعددة العقد. يمكن للمثبِّت تثبيت PostgreSQL محليًا لك، أو قبول DSN لخادم موجود.

في وقت التشغيل، يتم اختيار الخلفية عبر متغيرات البيئة (يكتبها المثبِّت لك في /etc/default/x-ui):

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

ترحيل تثبيت SQLite موجود إلى PostgreSQL

bash
x-ui migrate-db --dsn "postgres://xui:[email protected]:5432/xui?sslmode=disable"
# ثم عيّن XUI_DB_TYPE و XUI_DB_DSN في /etc/default/x-ui وأعد التشغيل:
systemctl restart x-ui

يبقى ملف SQLite الأصلي دون تغيير؛ احذفه يدويًا بعد التحقق من الخلفية الجديدة.

Docker

يستمر الأمر الافتراضي docker compose up -d في استخدام SQLite. للتشغيل مع خدمة PostgreSQL المرفقة، أزِل التعليق عن سطري متغيرات البيئة XUI_DB_* في docker-compose.yml وشغّل باستخدام البروفايل:

bash
docker compose --profile postgres up -d

تتضمن الصورة Fail2ban (مُفعَّل افتراضيًا) لفرض حدود IP لكل عميل. يحظر Fail2ban المخالفين باستخدام iptables، الذي يتطلب صلاحية NET_ADMIN. يمنح docker-compose.yml هذه الصلاحية مسبقًا عبر cap_add؛ إذا شغّلت الحاوية باستخدام docker run بدلاً من ذلك، فأضِف الصلاحيات بنفسك، وإلا فسيتم تسجيل عمليات الحظر دون تطبيقها أبدًا:

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

متغيرات البيئة

المتغير الوصف الافتراضي
XUI_DB_TYPE خلفية قاعدة البيانات: sqlite أو postgres sqlite
XUI_DB_DSN سلسلة اتصال PostgreSQL (عندما XUI_DB_TYPE=postgres) —
XUI_DB_FOLDER مجلد ملف قاعدة بيانات SQLite /etc/x-ui
XUI_DB_MAX_OPEN_CONNS الحد الأقصى للاتصالات المفتوحة (تجمّع PostgreSQL) —
XUI_DB_MAX_IDLE_CONNS الحد الأقصى للاتصالات الخاملة (تجمّع PostgreSQL) —
XUI_INIT_WEB_BASE_PATH مسار URI الأولي للوحة الويب /
XUI_ENABLE_FAIL2BAN تفعيل فرض حدود IP المعتمد على Fail2ban true
XUI_LOG_LEVEL مستوى السجل (debug، info، warning، error) info
XUI_DEBUG تفعيل وضع التصحيح false
XUI_TUNNEL_HEALTH_MONITOR تفعيل مراقب صحة النفق (يفحص عنوان URL ويعيد تشغيل xray بعد فشل متكرر؛ إعادة التشغيل تقطع جميع العملاء) false
XUI_TUNNEL_HEALTH_PROXY الوكيل الذي يُرسَل عبره الفحص؛ وجّهه إلى اتصال xray وارد محلي ليختبر الفحص النفق (مثل socks5://127.0.0.1:1080). القيمة الفارغة تعني أن الفحص يتحقق فقط من اتصال المضيف —
XUI_TUNNEL_HEALTH_URL عنوان URL الذي يُفحَص لمعرفة صحة النفق https://www.cloudflare.com/cdn-cgi/trace
XUI_TUNNEL_HEALTH_INTERVAL الفترة بين عمليات الفحص 30s
XUI_TUNNEL_HEALTH_TIMEOUT مهلة كل عملية فحص 10s
XUI_TUNNEL_HEALTH_FAILURES عدد حالات الفشل المتتالية قبل تشغيل إعادة التشغيل 3
XUI_TUNNEL_HEALTH_COOLDOWN الحد الأدنى للتأخير بين عمليات إعادة التشغيل المتتالية 5m

اللغات المدعومة

تتوفر واجهة اللوحة بـ 13 لغة:

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

المساهمة

المساهمات مرحب بها. يرجى قراءة دليل المساهمة قبل فتح مشكلة (issue) أو طلب سحب (pull request).

شكر خاص إلى

الاعتراف

  • Iran v2ray rules (الترخيص: GPL-3.0): قواعد توجيه v2ray/xray و v2ray/xray-clients المحسنة مع النطاقات الإيرانية المدمجة وتركيز على الأمان وحظر الإعلانات.
  • Russia v2ray rules (الترخيص: GPL-3.0): يحتوي هذا المستودع على قواعد توجيه V2Ray محدثة تلقائيًا بناءً على بيانات النطاقات والعناوين المحظورة في روسيا.

أدوات المجتمع

أدوات وتكاملات بناها المجتمع حول 3x-ui.

  • terraform-provider-3x-ui (الترخيص: MIT): إدارة الاتصالات الواردة والعملاء وإعدادات اللوحة وتكوين Xray كرمز باستخدام Terraform / OpenTofu.

دعم المشروع

إذا كان هذا المشروع مفيدًا لك، فقد ترغب في إعطائه:star2:

النجوم عبر الزمن

File: README.es_ES.md

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

3X-UI es un panel de control web avanzado y de código abierto para gestionar servidores Xray-core. Ofrece una interfaz limpia y multilingüe para desplegar, configurar y monitorear una amplia gama de protocolos de proxy y VPN — desde un único VPS hasta despliegues multinodo.

Construido como un fork mejorado del proyecto X-UI original, 3X-UI añade un soporte de protocolos más amplio, mayor estabilidad, contabilidad de tráfico por cliente y muchas funciones que mejoran la experiencia de uso.

[!IMPORTANT]
Este proyecto está destinado únicamente al uso personal. Por favor, no lo uses para fines ilegales ni en un entorno de producción.

Características

  • Entradas multiprotocolo — VLESS, VMess, Trojan, Shadowsocks, WireGuard, Hysteria2, HTTP, SOCKS (Mixed), Dokodemo-door / Tunnel y TUN.
  • Transportes y seguridad modernos — TCP (Raw), mKCP, WebSocket, gRPC, HTTPUpgrade y XHTTP, protegidos con TLS, XTLS y REALITY.
  • Fallbacks — sirve varios protocolos en un solo puerto (p. ej. VLESS y Trojan en el 443) usando la función de fallback de Xray.
  • Gestión por cliente — cuotas de tráfico, fechas de caducidad, límites de IP, estado en línea en tiempo real y enlaces de compartición, códigos QR y suscripciones con un solo clic.
  • Estadísticas de tráfico — por entrada, por cliente y por salida, con controles de reinicio.
  • Soporte multinodo — gestiona y escala a través de varios servidores desde un único panel.
  • Salida y enrutamiento — WARP, NordVPN, reglas de enrutamiento personalizadas, balanceadores de carga y encadenamiento de proxy de salida.
  • Servidor de suscripción integrado con múltiples formatos de salida y plantillas de página personalizables.
  • Bot de Telegram para monitorización y gestión remotas.
  • API RESTful con documentación Swagger dentro del panel.
  • Almacenamiento flexible — SQLite (predeterminado) o PostgreSQL.
  • 13 idiomas de interfaz con temas oscuro y claro.
  • Integración con Fail2ban para aplicar límites de IP por cliente.

Capturas de pantalla

Haz clic para expandir

Inicio Rápido

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

Para instalar una versión específica, añade su etiqueta (p. ej. v3.4.0):

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

Para instalar la versión dev continua (la última prelanzamiento por commit desde main, no una versión estable), pasa dev-latest:

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

Durante la instalación se generan un nombre de usuario, una contraseña y una ruta de acceso aleatorios. Tras la instalación, ejecuta x-ui para abrir el menú de gestión, donde puedes iniciar/detener el servicio, ver o restablecer tus credenciales de acceso, gestionar certificados SSL y mucho más.

Para la documentación completa, visita la Wiki del proyecto.

Instalación desatendida

El instalador también se ejecuta de forma no interactiva para cloud-init.
Define XUI_NONINTERACTIVE=1 (o canalízalo sin TTY) y realizará la instalación de principio a fin sin
ninguna pregunta, generando credenciales aleatorias y escribiéndolas en
/etc/x-ui/install-result.env. Consulta deploy/ para:

Plataformas Compatibles

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

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

Opciones de Base de Datos

3X-UI admite dos backends, que se eligen durante la instalación:

  • SQLite (predeterminado) — un único archivo en /etc/x-ui/x-ui.db. Sin configuración, ideal para despliegues pequeños y medianos.
  • PostgreSQL — recomendado para un gran número de clientes o configuraciones multinodo. El instalador puede instalar PostgreSQL localmente por ti, o aceptar un DSN a un servidor existente.

En tiempo de ejecución, el backend se selecciona mediante variables de entorno (el instalador las escribe por ti en /etc/default/x-ui):

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

Migrar una instalación de SQLite existente a PostgreSQL

bash
x-ui migrate-db --dsn "postgres://xui:[email protected]:5432/xui?sslmode=disable"
# luego define XUI_DB_TYPE y XUI_DB_DSN en /etc/default/x-ui y reinicia:
systemctl restart x-ui

El archivo SQLite de origen permanece intacto; elimínalo manualmente una vez que hayas verificado el nuevo backend.

Docker

El comando predeterminado docker compose up -d sigue usando SQLite. Para ejecutarlo con el servicio PostgreSQL incluido, descomenta las dos líneas de variables de entorno XUI_DB_* en docker-compose.yml e inícialo con el perfil:

bash
docker compose --profile postgres up -d

La imagen incluye Fail2ban (habilitado de forma predeterminada) para aplicar límites de IP por cliente. Fail2ban banea a los infractores con iptables, lo que requiere la capacidad NET_ADMIN. docker-compose.yml ya la concede mediante cap_add; si en su lugar inicias el contenedor con docker run, añade tú mismo las capacidades, de lo contrario los baneos se registran pero nunca se aplican:

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

Variables de Entorno

Variable Descripción Predeterminado
XUI_DB_TYPE Backend de base de datos: sqlite o postgres sqlite
XUI_DB_DSN Cadena de conexión de PostgreSQL (cuando XUI_DB_TYPE=postgres) —
XUI_DB_FOLDER Directorio del archivo de base de datos SQLite /etc/x-ui
XUI_DB_MAX_OPEN_CONNS Máximo de conexiones abiertas (pool de PostgreSQL) —
XUI_DB_MAX_IDLE_CONNS Máximo de conexiones inactivas (pool de PostgreSQL) —
XUI_INIT_WEB_BASE_PATH La ruta URI inicial para el panel web /
XUI_ENABLE_FAIL2BAN Habilitar la aplicación de límites de IP basada en Fail2ban true
XUI_LOG_LEVEL Nivel de registro (debug, info, warning, error) info
XUI_DEBUG Habilitar el modo de depuración false
XUI_TUNNEL_HEALTH_MONITOR Habilitar el monitor de salud del túnel (sondea una URL y reinicia xray tras fallos repetidos; un reinicio desconecta a todos los clientes) false
XUI_TUNNEL_HEALTH_PROXY Proxy a través del cual se envía el sondeo; apúntalo a una entrada local de xray para que el sondeo pruebe el túnel (p. ej. socks5://127.0.0.1:1080). Vacío significa que el sondeo solo comprueba la conectividad del host —
XUI_TUNNEL_HEALTH_URL URL sondeada para verificar la salud del túnel https://www.cloudflare.com/cdn-cgi/trace
XUI_TUNNEL_HEALTH_INTERVAL Intervalo entre sondeos 30s
XUI_TUNNEL_HEALTH_TIMEOUT Tiempo de espera por sondeo 10s
XUI_TUNNEL_HEALTH_FAILURES Fallos consecutivos antes de que se active un reinicio 3
XUI_TUNNEL_HEALTH_COOLDOWN Retardo mínimo entre reinicios consecutivos 5m

Idiomas Compatibles

La interfaz del panel está disponible en 13 idiomas:

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

Contribuir

Las contribuciones son bienvenidas. Por favor, lee la Guía de contribución antes de abrir una incidencia (issue) o una solicitud de incorporación (pull request).

Un Agradecimiento Especial a

Reconocimientos

  • Iran v2ray rules (Licencia: GPL-3.0): Reglas de enrutamiento mejoradas para v2ray/xray y v2ray/xray-clients con dominios iraníes incorporados y un enfoque en seguridad y bloqueo de anuncios.
  • Russia v2ray rules (Licencia: GPL-3.0): Este repositorio contiene reglas de enrutamiento V2Ray actualizadas automáticamente basadas en datos de dominios y direcciones bloqueadas en Rusia.

Herramientas de la Comunidad

Herramientas e integraciones construidas por la comunidad alrededor de 3x-ui.

  • terraform-provider-3x-ui (Licencia: MIT): Gestiona inbounds, clientes, configuración del panel y configuración de Xray como código con Terraform / OpenTofu.

Apoyar el Proyecto

Si este proyecto te es útil, puedes darle una:star2:

Estrellas a lo Largo del Tiempo

File: README.fa_IR.md

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

3X-UI یک پنل کنترل وب پیشرفته و متن‌باز برای مدیریت سرورهای Xray-core است. این پنل یک رابط کاربری تمیز و چندزبانه برای استقرار، پیکربندی و نظارت بر طیف گسترده‌ای از پروتکل‌های پراکسی و VPN ارائه می‌دهد — از یک VPS تکی تا استقرارهای چندنودی.

‏3X-UI که به‌عنوان یک فورک بهبودیافته از پروژه‌ی اصلی X-UI ساخته شده است، پشتیبانی گسترده‌تر از پروتکل‌ها، پایداری بهتر، حسابداری ترافیک به‌ازای هر کلاینت و بسیاری از ویژگی‌های رفاهی را اضافه می‌کند.

[!IMPORTANT]
این پروژه فقط برای استفاده‌ی شخصی در نظر گرفته شده است. لطفاً از آن برای اهداف غیرقانونی یا در محیط تولید (production) استفاده نکنید.

ویژگی‌ها

  • اینباندهای چندپروتکلی — VLESS، VMess، Trojan، Shadowsocks، WireGuard، Hysteria2، HTTP، SOCKS (Mixed)، Dokodemo-door / Tunnel و TUN.
  • ترنسپورت‌ها و امنیت مدرن — TCP (Raw)، mKCP، WebSocket، gRPC، HTTPUpgrade و XHTTP، ایمن‌شده با TLS، XTLS و REALITY.
  • فال‌بک (Fallback) — ارائه‌ی چند پروتکل روی یک پورت واحد (مثلاً VLESS و Trojan روی پورت 443) با استفاده از قابلیت fallback در Xray.
  • مدیریت به‌ازای هر کلاینت — سهمیه‌ی ترافیک، تاریخ انقضا، محدودیت IP، وضعیت آنلاینِ زنده و لینک‌های اشتراک‌گذاری، کدهای QR و سابسکریپشن‌ها با یک کلیک.
  • آمار ترافیک — به‌ازای هر اینباند، هر کلاینت و هر اوتباند، همراه با کنترل بازنشانی (reset).
  • پشتیبانی از چند نود — مدیریت و مقیاس‌دهی روی چندین سرور از یک پنل واحد.
  • اوتباند و مسیریابی — WARP، NordVPN، قوانین مسیریابی سفارشی، متعادل‌کننده‌های بار (load balancer) و زنجیره‌کردن پراکسی اوتباند.
  • سرور سابسکریپشن داخلی با چندین فرمت خروجی و قالب‌های صفحه‌ی سفارشی.
  • ربات تلگرام برای نظارت و مدیریت از راه دور.
  • ‏RESTful API همراه با مستندات Swagger درون‌پنل.
  • ذخیره‌سازی منعطف — SQLite (پیش‌فرض) یا PostgreSQL.
  • ‏۱۳ زبان رابط کاربری با تم‌های تیره و روشن.
  • یکپارچگی با Fail2ban برای اعمال محدودیت IP به‌ازای هر کلاینت.

اسکرین‌شات‌ها

برای باز شدن کلیک کنید

شروع سریع

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

برای نصب یک نسخه‌ی مشخص، تگ آن را در انتها اضافه کنید (مثلاً v3.4.0):

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

برای نصب نسخه‌ی غلتانِ dev (آخرین پیش‌انتشار به‌ازای هر کامیت از شاخه‌ی main، نه یک انتشار پایدار)، مقدار dev-latest را پاس دهید:

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

در حین نصب، یک نام کاربری، رمز عبور و مسیر دسترسی تصادفی تولید می‌شود. پس از نصب، دستور x-ui را اجرا کنید تا منوی مدیریت باز شود؛ در آنجا می‌توانید سرویس را شروع/متوقف کنید، اطلاعات ورود خود را ببینید یا بازنشانی کنید، گواهی‌های SSL را مدیریت کنید و کارهای دیگری انجام دهید.

برای مستندات کامل، لطفاً به ویکی پروژه مراجعه کنید.

نصب بدون نظارت

نصب‌کننده به‌صورت غیرتعاملی نیز برای cloud-init اجرا می‌شود.
‏XUI_NONINTERACTIVE=1 را تنظیم کنید (یا بدون TTY از طریق pipe اجرا کنید) تا نصب به‌صورت سرتاسری و بدون
هیچ پرسشی انجام شود، اطلاعات ورود تصادفی تولید کرده و آن‌ها را در
/etc/x-ui/install-result.env می‌نویسد. برای موارد زیر به deploy/ مراجعه کنید:

پلتفرم‌های پشتیبانی‌شده

سیستم‌عامل‌ها: Ubuntu، Debian، Armbian، Fedora، CentOS، RHEL، AlmaLinux، Rocky Linux، Oracle Linux، Amazon Linux، Virtuozzo، Arch، Manjaro، Parch، openSUSE (Tumbleweed / Leap)، Alpine و Windows.

معماری‌ها: amd64 · 386 · arm64 (aarch64) · armv7 · armv6 · armv5 · s390x.

گزینه‌های پایگاه‌داده

‏3X-UI از دو بک‌اند پشتیبانی می‌کند که در حین نصب انتخاب می‌شوند:

  • SQLite (پیش‌فرض) — یک فایل واحد در مسیر /etc/x-ui/x-ui.db. بدون نیاز به تنظیمات، ایده‌آل برای استقرارهای کوچک و متوسط.
  • PostgreSQL — برای تعداد کلاینت بالا یا راه‌اندازی‌های چندنودی توصیه می‌شود. نصب‌کننده می‌تواند PostgreSQL را به‌صورت محلی برایتان نصب کند، یا یک DSN به یک سرور موجود را بپذیرد.

در زمان اجرا، بک‌اند از طریق متغیرهای محیطی انتخاب می‌شود (نصب‌کننده این موارد را برای شما در /etc/default/x-ui می‌نویسد):

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

انتقال یک نصب موجود SQLite به PostgreSQL

bash
x-ui migrate-db --dsn "postgres://xui:[email protected]:5432/xui?sslmode=disable"
# سپس XUI_DB_TYPE و XUI_DB_DSN را در /etc/default/x-ui تنظیم کرده و ری‌استارت کنید:
systemctl restart x-ui

فایل اصلی SQLite دست‌نخورده باقی می‌ماند؛ پس از اطمینان از صحت بک‌اند جدید، آن را به‌صورت دستی حذف کنید.

Docker

دستور پیش‌فرض docker compose up -d همچنان از SQLite استفاده می‌کند. برای اجرا با سرویس PostgreSQL همراه، دو خط متغیر محیطی XUI_DB_* را در docker-compose.yml از حالت کامنت خارج کنید و با پروفایل زیر اجرا کنید:

bash
docker compose --profile postgres up -d

این ایمیج، Fail2ban را (که به‌صورت پیش‌فرض فعال است) برای اعمال محدودیت‌های IP به‌ازای هر کلاینت همراه دارد. ‏Fail2ban متخلفان را با iptables مسدود می‌کند که به مجوز NET_ADMIN نیاز دارد. فایل docker-compose.yml این مجوز را از قبل از طریق cap_add می‌دهد؛ اگر به‌جای آن کانتینر را با docker run اجرا می‌کنید، خودتان مجوزها را اضافه کنید، در غیر این صورت مسدودسازی‌ها فقط ثبت می‌شوند اما هرگز اعمال نمی‌شوند:

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

متغیرهای محیطی

متغیر توضیحات پیش‌فرض
XUI_DB_TYPE بک‌اند پایگاه‌داده: sqlite یا postgres sqlite
XUI_DB_DSN رشته‌ی اتصال PostgreSQL (وقتی XUI_DB_TYPE=postgres) —
XUI_DB_FOLDER پوشه‌ی فایل پایگاه‌داده‌ی SQLite /etc/x-ui
XUI_DB_MAX_OPEN_CONNS حداکثر اتصالات باز (استخر PostgreSQL) —
XUI_DB_MAX_IDLE_CONNS حداکثر اتصالات بی‌کار (استخر PostgreSQL) —
XUI_INIT_WEB_BASE_PATH مسیر URI اولیه برای پنل وب /
XUI_ENABLE_FAIL2BAN فعال‌سازی اعمال محدودیت IP مبتنی بر Fail2ban true
XUI_LOG_LEVEL سطح گزارش‌گیری (debug، info، warning، error) info
XUI_DEBUG فعال‌سازی حالت دیباگ false
XUI_TUNNEL_HEALTH_MONITOR فعال‌سازی پایشگر سلامت تونل (یک URL را پروب می‌کند و پس از خطاهای مکرر، xray را ری‌استارت می‌کند؛ یک ری‌استارت همه‌ی کلاینت‌ها را قطع می‌کند) false
XUI_TUNNEL_HEALTH_PROXY پراکسی‌ای که پروب از طریق آن ارسال می‌شود؛ آن را به یک اینباند محلی xray اشاره دهید تا پروب خودِ تونل را آزمایش کند (مثلاً socks5://127.0.0.1:1080). خالی بودن یعنی پروب فقط اتصال به هاست را بررسی می‌کند —
XUI_TUNNEL_HEALTH_URL URL ای که برای سلامت تونل پروب می‌شود https://www.cloudflare.com/cdn-cgi/trace
XUI_TUNNEL_HEALTH_INTERVAL فاصله‌ی زمانی بین پروب‌ها 30s
XUI_TUNNEL_HEALTH_TIMEOUT مهلت زمانی هر پروب 10s
XUI_TUNNEL_HEALTH_FAILURES تعداد خطاهای متوالی پیش از آن‌که یک ری‌استارت فعال شود 3
XUI_TUNNEL_HEALTH_COOLDOWN حداقل تأخیر بین ری‌استارت‌های متوالی 5m

زبان‌های پشتیبانی‌شده

رابط کاربری پنل به ۱۳ زبان در دسترس است:

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

مشارکت

از مشارکت‌ها استقبال می‌شود. لطفاً پیش از باز کردن issue یا pull request، راهنمای مشارکت را مطالعه کنید.

تشکر ویژه از

قدردانی

  • Iran v2ray rules (مجوز: GPL-3.0): قوانین مسیریابی بهبود یافته v2ray/xray و v2ray/xray-clients با دامنه‌های ایرانی داخلی و تمرکز بر امنیت و مسدود کردن تبلیغات.
  • Russia v2ray rules (مجوز: GPL-3.0): این مخزن شامل قوانین مسیریابی V2Ray به‌روزرسانی شده خودکار بر اساس داده‌های دامنه‌ها و آدرس‌های مسدود شده در روسیه است.

ابزارهای جامعه

ابزارها و یکپارچه‌سازی‌هایی که توسط جامعه پیرامون 3x-ui ساخته شده‌اند.

  • terraform-provider-3x-ui (مجوز: MIT): مدیریت اینباندها، کلاینت‌ها، تنظیمات پنل و پیکربندی Xray به‌صورت کد با Terraform / OpenTofu.

پشتیبانی از پروژه

اگر این پروژه برای شما مفید است، می‌توانید به آن یک:star2: بدهید

ستاره‌ها در طول زمان

File: README.ru_RU.md

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

3X-UI — продвинутая веб-панель управления с открытым исходным кодом для управления серверами Xray-core. Она предоставляет аккуратный многоязычный интерфейс для развёртывания, настройки и мониторинга широкого спектра протоколов прокси и VPN — от одного VPS до развёртываний с несколькими узлами.

Созданный как улучшенный форк оригинального проекта X-UI, 3X-UI добавляет более широкую поддержку протоколов, повышенную стабильность, учёт трафика по каждому клиенту и множество функций для удобства использования.

[!IMPORTANT]
Этот проект предназначен только для личного использования. Пожалуйста, не используйте его в незаконных целях или в производственной среде.

Возможности

  • Многопротокольные входящие подключения — VLESS, VMess, Trojan, Shadowsocks, WireGuard, Hysteria2, HTTP, SOCKS (Mixed), Dokodemo-door / Tunnel и TUN.
  • Современные транспорты и безопасность — TCP (Raw), mKCP, WebSocket, gRPC, HTTPUpgrade и XHTTP, защищённые с помощью TLS, XTLS и REALITY.
  • Fallback — обслуживание нескольких протоколов на одном порту (например, VLESS и Trojan на 443) с помощью функции fallback в Xray.
  • Управление по каждому клиенту — квоты трафика, даты истечения, лимиты IP, статус «онлайн» в реальном времени, а также ссылки для общего доступа, QR-коды и подписки в один клик.
  • Статистика трафика — по каждому входящему, по каждому клиенту и по каждому исходящему, с возможностью сброса.
  • Поддержка нескольких узлов — управление и масштабирование на несколько серверов из одной панели.
  • Исходящие подключения и маршрутизация — WARP, NordVPN, пользовательские правила маршрутизации, балансировщики нагрузки и цепочки исходящих прокси.
  • Встроенный сервер подписок с несколькими форматами вывода и пользовательскими шаблонами страниц.
  • Telegram-бот для удалённого мониторинга и управления.
  • RESTful API с документацией Swagger внутри панели.
  • Гибкое хранилище — SQLite (по умолчанию) или PostgreSQL.
  • 13 языков интерфейса с тёмной и светлой темами.
  • Интеграция с Fail2ban для применения лимитов IP по каждому клиенту.

Скриншоты

Нажмите, чтобы развернуть

Быстрый старт

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

Чтобы установить конкретную версию, добавьте её тег (например, v3.4.0):

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

Чтобы установить скользящую dev-сборку (новейший предварительный релиз по каждому коммиту из ветки main, а не стабильный релиз), передайте dev-latest:

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

Во время установки генерируются случайные имя пользователя, пароль и путь доступа. После установки выполните x-ui, чтобы открыть меню управления, где можно запускать/останавливать сервис, просматривать или сбрасывать учётные данные для входа, управлять SSL-сертификатами и многое другое.

Полную документацию смотрите в вики проекта.

Автоматическая установка

Установщик также работает в неинтерактивном режиме для cloud-init.
Задайте XUI_NONINTERACTIVE=1 (или передайте по конвейеру без TTY), и установка пройдёт от начала до конца
без единого запроса: будут сгенерированы случайные учётные данные и записаны в
/etc/x-ui/install-result.env. Смотрите deploy/ для:

Поддерживаемые платформы

Операционные системы: Ubuntu, Debian, Armbian, Fedora, CentOS, RHEL, AlmaLinux, Rocky Linux, Oracle Linux, Amazon Linux, Virtuozzo, Arch, Manjaro, Parch, openSUSE (Tumbleweed / Leap), Alpine и Windows.

Архитектуры: amd64 · 386 · arm64 (aarch64) · armv7 · armv6 · armv5 · s390x.

Варианты базы данных

3X-UI поддерживает два бэкенда, выбираемых при установке:

  • SQLite (по умолчанию) — единый файл по пути /etc/x-ui/x-ui.db. Без настройки, идеально для небольших и средних развёртываний.
  • PostgreSQL — рекомендуется при большом числе клиентов или конфигурациях с несколькими узлами. Установщик может установить PostgreSQL локально за вас или принять DSN к существующему серверу.

Во время выполнения бэкенд выбирается через переменные окружения (установщик записывает их за вас в /etc/default/x-ui):

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

Перенос существующей установки SQLite в PostgreSQL

bash
x-ui migrate-db --dsn "postgres://xui:[email protected]:5432/xui?sslmode=disable"
# затем задайте XUI_DB_TYPE и XUI_DB_DSN в /etc/default/x-ui и перезапустите:
systemctl restart x-ui

Исходный файл SQLite остаётся нетронутым; удалите его вручную после проверки нового бэкенда.

Docker

Команда по умолчанию docker compose up -d продолжает использовать SQLite. Чтобы запустить со встроенным сервисом PostgreSQL, раскомментируйте две строки переменных окружения XUI_DB_* в docker-compose.yml и запустите с профилем:

bash
docker compose --profile postgres up -d

Образ включает Fail2ban (включён по умолчанию) для применения лимитов IP по каждому клиенту. Fail2ban блокирует нарушителей с помощью iptables, что требует возможности NET_ADMIN. docker-compose.yml уже предоставляет её через cap_add; если вы вместо этого запускаете контейнер через docker run, добавьте возможности самостоятельно, иначе блокировки будут регистрироваться, но никогда не применяться:

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

Переменные окружения

Переменная Описание По умолчанию
XUI_DB_TYPE Бэкенд базы данных: sqlite или postgres sqlite
XUI_DB_DSN Строка подключения PostgreSQL (когда XUI_DB_TYPE=postgres) —
XUI_DB_FOLDER Каталог для файла базы данных SQLite /etc/x-ui
XUI_DB_MAX_OPEN_CONNS Максимум открытых соединений (пул PostgreSQL) —
XUI_DB_MAX_IDLE_CONNS Максимум простаивающих соединений (пул PostgreSQL) —
XUI_INIT_WEB_BASE_PATH Начальный URI-путь для веб-панели /
XUI_ENABLE_FAIL2BAN Включить применение лимитов IP на основе Fail2ban true
XUI_LOG_LEVEL Уровень логирования (debug, info, warning, error) info
XUI_DEBUG Включить режим отладки false
XUI_TUNNEL_HEALTH_MONITOR Включить монитор состояния туннеля (опрашивает URL и перезапускает xray после многократных сбоев; перезапуск отключает всех клиентов) false
XUI_TUNNEL_HEALTH_PROXY Прокси, через который отправляется проба; укажите локальный входящий xray, чтобы проба проверяла туннель (например, socks5://127.0.0.1:1080). Пустое значение означает, что проба проверяет только связь с хостом —
XUI_TUNNEL_HEALTH_URL URL, опрашиваемый для проверки состояния туннеля https://www.cloudflare.com/cdn-cgi/trace
XUI_TUNNEL_HEALTH_INTERVAL Интервал между пробами 30s
XUI_TUNNEL_HEALTH_TIMEOUT Таймаут на одну пробу 10s
XUI_TUNNEL_HEALTH_FAILURES Число последовательных сбоев до запуска перезапуска 3
XUI_TUNNEL_HEALTH_COOLDOWN Минимальная задержка между последовательными перезапусками 5m

Поддерживаемые языки

Интерфейс панели доступен на 13 языках:

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

Участие в разработке

Вклад приветствуется. Пожалуйста, прочитайте руководство по участию, прежде чем открывать issue или pull request.

Особая благодарность

Благодарности

  • Iran v2ray rules (Лицензия: GPL-3.0): Улучшенные правила маршрутизации для v2ray/xray и v2ray/xray-clients со встроенными иранскими доменами и фокусом на безопасность и блокировку рекламы.
  • Russia v2ray rules (Лицензия: GPL-3.0): Этот репозиторий содержит автоматически обновляемые правила маршрутизации V2Ray на основе данных о заблокированных доменах и адресах в России.

Инструменты сообщества

Инструменты и интеграции, созданные сообществом вокруг 3x-ui.

  • terraform-provider-3x-ui (Лицензия: MIT): Управление входящими, клиентами, настройками панели и конфигурацией Xray через код с помощью Terraform / OpenTofu.

Поддержка проекта

Если этот проект полезен для вас, вы можете поставить ему:star2:

Звезды с течением времени

File: README.zh_CN.md

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

3X-UI 是一个先进的开源 Web 控制面板，用于管理 Xray-core 服务器。它提供简洁、多语言的界面，用于部署、配置和监控各种代理与 VPN 协议——从单台 VPS 到多节点部署。

3X-UI 作为原始 X-UI 项目的增强分支（fork），增加了更广泛的协议支持、更好的稳定性、按客户端的流量统计以及许多提升使用体验的功能。

[!IMPORTANT]
本项目仅供个人使用。请勿将其用于非法目的，也请勿在生产环境中使用。

功能特性

  • 多协议入站 — VLESS、VMess、Trojan、Shadowsocks、WireGuard、Hysteria2、HTTP、SOCKS (Mixed)、Dokodemo-door / Tunnel 和 TUN。
  • 现代传输与安全 — TCP (Raw)、mKCP、WebSocket、gRPC、HTTPUpgrade 和 XHTTP，并通过 TLS、XTLS 和 REALITY 加密。
  • 回落 (Fallback) — 通过 Xray 的 fallback 功能在单个端口上提供多种协议（例如在 443 端口上同时使用 VLESS 和 Trojan）。
  • 按客户端管理 — 流量配额、到期日期、IP 限制、实时在线状态，以及一键分享链接、二维码和订阅。
  • 流量统计 — 按入站、按客户端、按出站统计，并支持重置控制。
  • 多节点支持 — 从单一面板管理并扩展到多台服务器。
  • 出站与路由 — WARP、NordVPN、自定义路由规则、负载均衡器和出站代理链。
  • 内置订阅服务器，支持多种输出格式和自定义页面模板。
  • Telegram 机器人，用于远程监控和管理。
  • RESTful API，带有面板内置的 Swagger 文档。
  • 灵活的存储 — SQLite（默认）或 PostgreSQL。
  • 13 种界面语言，支持深色和浅色主题。
  • Fail2ban 集成，用于强制执行按客户端的 IP 限制。

截图

点击展开

快速开始

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

若要安装特定版本，请在命令后附加对应的标签（例如 v3.4.0）：

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

若要安装滚动更新的 dev 版本（来自 main 的最新逐次提交预发布版本，而非稳定版本），请传入 dev-latest：

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

安装过程中会生成随机的用户名、密码和访问路径。安装完成后，运行 x-ui 打开管理菜单，您可以在其中启动/停止服务、查看或重置登录凭据、管理 SSL 证书等。

完整文档请参阅 项目Wiki。

无人值守安装

安装程序也可以非交互式运行，适用于 cloud-init。
设置 XUI_NONINTERACTIVE=1（或在无 TTY 的情况下通过管道传入），它就会全程
零提示地完成端到端安装，生成随机凭据并写入
/etc/x-ui/install-result.env。请参阅 deploy/：

支持的平台

操作系统： Ubuntu、Debian、Armbian、Fedora、CentOS、RHEL、AlmaLinux、Rocky Linux、Oracle Linux、Amazon Linux、Virtuozzo、Arch、Manjaro、Parch、openSUSE (Tumbleweed / Leap)、Alpine 和 Windows。

架构： amd64 · 386 · arm64 (aarch64) · armv7 · armv6 · armv5 · s390x。

数据库选项

3X-UI 支持两种后端，可在安装时选择：

  • SQLite（默认）— 位于 /etc/x-ui/x-ui.db 的单个文件。无需配置，适合中小型部署。
  • PostgreSQL — 推荐用于大量客户端或多节点设置。安装程序可以为您在本地安装 PostgreSQL，或接受指向现有服务器的 DSN。

运行时通过环境变量选择后端（安装程序会为您写入 /etc/default/x-ui）：

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

将现有的 SQLite 安装迁移到 PostgreSQL

bash
x-ui migrate-db --dsn "postgres://xui:[email protected]:5432/xui?sslmode=disable"
# 然后在 /etc/default/x-ui 中设置 XUI_DB_TYPE 和 XUI_DB_DSN 并重启：
systemctl restart x-ui

源 SQLite 文件保持不变；在确认新后端正常工作后，请手动删除它。

Docker

默认的 docker compose up -d 仍使用 SQLite。若要使用捆绑的 PostgreSQL 服务运行，请取消注释 docker-compose.yml 中的两行 XUI_DB_* 环境变量，并使用该 profile 启动：

bash
docker compose --profile postgres up -d

该镜像捆绑了 Fail2ban（默认启用），用于强制执行按客户端的 IP 限制。Fail2ban 使用 iptables 封禁违规者，这需要 NET_ADMIN 权限。docker-compose.yml 已通过 cap_add 授予该权限；如果您改用 docker run 启动容器，请自行添加这些权限，否则封禁只会被记录而永远不会生效：

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

环境变量

变量 说明 默认值
XUI_DB_TYPE 数据库后端：sqlite 或 postgres sqlite
XUI_DB_DSN PostgreSQL 连接字符串（当 XUI_DB_TYPE=postgres 时） —
XUI_DB_FOLDER SQLite 数据库文件所在目录 /etc/x-ui
XUI_DB_MAX_OPEN_CONNS 最大打开连接数（PostgreSQL 连接池） —
XUI_DB_MAX_IDLE_CONNS 最大空闲连接数（PostgreSQL 连接池） —
XUI_INIT_WEB_BASE_PATH Web 面板的初始 URI 路径 /
XUI_ENABLE_FAIL2BAN 启用基于 Fail2ban 的 IP 限制 true
XUI_LOG_LEVEL 日志级别（debug、info、warning、error） info
XUI_DEBUG 启用调试模式 false
XUI_TUNNEL_HEALTH_MONITOR 启用隧道健康监控（探测某个 URL，在连续多次失败后重启 xray；重启会断开所有客户端） false
XUI_TUNNEL_HEALTH_PROXY 探测请求所经过的代理；将其指向本地 xray 入站，使探测能够测试隧道（例如 socks5://127.0.0.1:1080）。留空表示探测仅检查主机连通性 —
XUI_TUNNEL_HEALTH_URL 用于检测隧道健康状况的探测 URL https://www.cloudflare.com/cdn-cgi/trace
XUI_TUNNEL_HEALTH_INTERVAL 两次探测之间的间隔 30s
XUI_TUNNEL_HEALTH_TIMEOUT 单次探测的超时时间 10s
XUI_TUNNEL_HEALTH_FAILURES 触发重启前的连续失败次数 3
XUI_TUNNEL_HEALTH_COOLDOWN 两次连续重启之间的最小间隔 5m

支持的语言

面板界面提供 13 种语言：

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

贡献

欢迎贡献。在提交 issue 或 pull request 之前，请阅读贡献指南。

特别感谢

致谢

  • Iran v2ray rules (许可证: GPL-3.0): 增强的 v2ray/xray 和 v2ray/xray-clients 路由规则，内置伊朗域名，专注于安全性和广告拦截。
  • Russia v2ray rules (许可证: GPL-3.0): 此仓库包含基于俄罗斯被阻止域名和地址数据自动更新的 V2Ray 路由规则。

社区工具

社区围绕 3x-ui 构建的工具和集成。

  • terraform-provider-3x-ui (许可证: MIT): 使用 Terraform / OpenTofu 通过代码管理入站、客户端、面板设置和 Xray 配置。

支持项目

如果这个项目对您有帮助，您可以给它一个:star2:

随时间变化的星标数

File: docs/README.md

3x-ui Documentation

Overview

This directory (docs/ in the 3x-ui monorepo) contains
the source for docs.sanaei.dev — a static-first documentation and
marketing site built with Fumadocs on Next.js. It has no backend,
no database, and no auth: every page is prerendered and every tool runs entirely in the
browser.

What's inside

The documentation walks you through 3x-ui from first install to day-to-day operation:

  • Getting Started — installation, first login, and updating or uninstalling the panel.
  • Configuration — the panel, inbounds, REALITY, transports, clients, subscriptions, and share links.
  • Operations — reverse proxy, multi-node setups, outbounds & routing, backup/restore, the Telegram bot, and security.
  • Reference — environment variables, the database, ports & firewall, and the HTTP API.
  • Help — troubleshooting, FAQ, migration, and how to contribute.

Interactive tools

The site ships with in-browser helpers that generate configuration for you — no data
ever leaves your browser:

Tool What it does
REALITY Config Generator Build a valid REALITY inbound configuration.
Share Link Inspector Decode and inspect vless:// / vmess:// share links.
Install Command Builder Assemble the right install command for your setup.
Reverse Proxy Generator Generate reverse-proxy configs (Nginx / Caddy).
Protocol Wizard Pick and configure the right protocol for your needs.
Firewall Rules Generator Produce firewall rules for your ports.

Tech stack

Layer Technology
Framework Next.js 16 (App Router) · React 19
Docs Fumadocs (-ui / -core / -mdx)
Styling Tailwind CSS v4
Search Orama static index
Language TypeScript (strict)
Tests Vitest for the pure lib/xray logic
Tooling pnpm · oxlint · oxfmt

Quick start

This project uses pnpm (npm lockfiles are gitignored). Run everything
from the docs/ directory:

bash
cd docs
pnpm install
pnpm dev        # http://localhost:3000

Useful scripts:

Script Description
pnpm dev Start the dev server
pnpm build Production build (also typechecks)
pnpm typecheck Generate MDX/route types and tsc --noEmit
pnpm lint Run oxlint (.oxlintrc.json)
pnpm test Run unit tests (Vitest)

See CONTRIBUTING.md for the full list and project conventions.

Project structure

text
app/             # Next.js App Router — layouts, home, docs, OG images, search, llms.txt
components/      # React components — interactive tools, home sections, MDX bindings
content/docs/    # MDX documentation, one folder per locale (en · fa · ru · zh)
lib/             # source config, i18n, GitHub stats, and the unit-tested lib/xray logic
public/          # static assets — logos, favicon, openapi.json, CNAME
scripts/         # build-time scripts (API reference generation)
source.config.ts # Fumadocs MDX schema & collection config
next.config.mjs  # Next.js config (static-export gating)
proxy.ts         # i18n middleware

Internationalization

Documentation is authored in English. Persian (fa, RTL), Russian (ru), and
Chinese (zh) locales are wired up; untranslated pages fall back to English so they
never 404. English URLs are unprefixed; other locales live under /fa, /ru, /zh.

Deployment

The site builds for two targets:

  • Vercel / Node — pnpm build (static search index + prerendered OG images).
  • GitHub Pages (static export) — DEPLOY_TARGET=static pnpm build → out/.

Contributing

Contributions are welcome! Setup, scripts, and project conventions live in
CONTRIBUTING.md.

License

Licensed under GPL-3.0.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#ech Browse ech catalog → #fail2ban Browse fail2ban catalog → #http Browse http catalog → #hysteria2 Browse hysteria2 catalog → #mixed Browse mixed catalog → #mtproto Browse mtproto catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →