MHSanaei/3x-ui

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, AmneziaWG, TUIC v5, Hysteria2, MTProto, 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.
• AmneziaWG integrado — WireGuard resistente al DPI se ejecuta dentro del panel sobre una pila de red en espacio de usuario, sin módulo del kernel, DKMS ni paquetes adicionales que instalar.
• TUIC v5 integrado — Proxy de alto rendimiento basado en QUIC con medición de tráfico mediante retransmisión UDP nativa, handshakes 0-RTT y control de congestión BBR.
• Proxies MTProto — secretos FakeTLS, ad-tags y cuotas por cliente, aplicados en caliente sin cortar las conexiones existentes.
• 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 con exenciones para direcciones de confianza, límites de dispositivos (HWID), ciclos de renovación programados, 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, incluida la clonación de entradas en otros nodos.
• Salida y enrutamiento — WARP, NordVPN, PIA, reglas de enrutamiento personalizadas, balanceadores de carga con conmutación por error entre balanceadores y encadenamiento de proxy de salida. Las categorías geosite y geoip incluidas se pueden explorar directamente desde el editor de reglas.
• Servidor de suscripción integrado — salida raw, JSON y Clash, seleccionada automáticamente según el User-Agent del cliente, además de plantillas de página personalizables.
• Bots de Telegram y Discord para monitorización y gestión remotas.
• API RESTful con tokens de alcance limitado y caducidad opcional, y una referencia de la API dentro del panel.
• Panel instalable (PWA) — ancla 3X-UI al escritorio o a la pantalla de inicio del móvil.
• Almacenamiento flexible — SQLite (predeterminado) o PostgreSQL.
• 14 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 <(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.7.0):

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

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

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.

Cada recurso de la publicación se publica con una suma .sha256 junto a él. Tanto install.sh como el actualizador verifican el archivo contra esa suma y abortan si no coincide.

Para la documentación completa —instalación, configuración, operación y la referencia completa de la API— visita docs.sanaei.dev.

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:

• User-data de cloud-init — instalación desatendida en cualquier nube (Hetzner/AWS/DO/Vultr/GCP/Azure/Oracle)
• Notas de Hetzner Cloud — despliegue basado en cloud-init en Hetzner

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

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

Migrar una instalación de SQLite existente a PostgreSQL

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:

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:

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
NODE_TOKEN_ENCRYPTION	Cifrado en reposo de los tokens de API de los nodos: off, migration o required (sin el prefijo XUI_)	off
XUI_NODE_TOKEN_KEY_FILE	Llavero JSON (modo 0600) con el id de la clave activa y sus claves de 32 bytes en base64	/etc/x-ui/node_token_key.json
XUI_NODE_TOKEN_KEY	Una única clave de 32 bytes en base64, usada solo si no se puede cargar el archivo de claves	—

La lista completa está en la referencia de variables de entorno.

Idiomas Compatibles

La interfaz del panel está disponible en 14 idiomas:

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

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

• alireza0

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.
• 3X-UI Manager (Licencia: MIT): Cliente nativo de Android para 3x-ui — panel de control, inbounds, clientes con compartición por QR, nodos y gestión de múltiples paneles. Disponible en F-Droid.

Apoyar el Proyecto

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

Historial de estrellas