Sanaei
6214ff4edc
* fix(mtproto): split the mtg fingerprint into structural and secrets parts A reordered clients array in the stored settings used to read as a config change because the fingerprint concatenated secrets in array order, and one opaque fingerprint could not tell a restart-worthy change (bind address, fronting, throttle) from a secret-set change a reload-capable mtg can absorb in place. Sort the secret pairs so order stops mattering, and split the value so the upcoming hot-reload path can decide between keeping, reloading, and restarting the process. * fix(mtproto): stop restarting mtg on every inbound edit Saving an mtproto inbound tore down and respawned its mtg sidecar even when nothing material changed, dropping every live Telegram connection: the update path pushed DelInbound+AddInbound, and Remove deletes the manager's map entry, so Ensure's fingerprint no-op gate could never fire. Route mtproto updates through a single Ensure call so an edit that leaves the generated TOML alone keeps the process, and only real config changes restart it. Capturing the pre-edit protocol also fixes a latent leak: changing an inbound's protocol away from mtproto never stopped the sidecar, because the snapshot handed to the runtime already carried the new protocol and the removal took the xray branch, leaving an orphaned mtg holding the port. An mtproto push failure no longer requests an xray restart - xray cannot fix the sidecar, and the 10s reconcile job self-heals it. The regression test fakes mtg by re-executing the test binary, counting spawns through a pid file: an unchanged save and a remark-only edit must keep the process, a re-keyed secret must restart it. * fix(mtproto): exclude depleted clients from the reconcile job to match the sync push The 10s reconcile job derived mtg secret sets from raw inbound settings while the interactive push filtered clients through buildRuntimeInboundForAPI, which drops client_traffics-disabled (depleted or expired) clients. The two paths therefore disagreed on the fingerprint - each disagreement one needless mtg restart dropping live connections - and worse, the job kept serving depleted clients' secrets indefinitely, so running out of traffic never actually cut an mtproto client's access. DesiredMtprotoInstances now builds the job's desired state with the same depletion overlay the push uses (one bulk client_traffics query), drops inbounds whose every secret is filtered away so their sidecar stops, and AddInbound pushes the filtered payload too so an imported inbound carrying disabled stats does not seed a fingerprint the next reconcile disagrees with. * feat(mtproto): hot-reload mtg secrets in place instead of restarting A client add, removal, re-key, or enable-toggle changes only the [secrets] section of the generated config, yet the panel could apply it only by killing and respawning the mtg sidecar, dropping every Telegram connection on that inbound. Split the ensure decision three ways: an identical config is a no-op, a secrets-only change rewrites the TOML on the same api port and asks mtg to hot-swap it via POST /reload, and a structural change (or a failed reload) falls back to the full stop-and-start. The reload endpoint is served by the mhsanaei/mtg-multi fork; against an older binary the POST 404s and the manager restarts exactly as before, so panel and binary upgrades stay order-independent. * feat(mtproto): apply single-client edits to the sidecar immediately Client CRUD on an mtproto inbound was a runtime no-op, so an add, delete, re-key, or enable-toggle only reached mtg on the next 10s reconcile. With the sidecar now able to hot-reload, push the change straight after the edit commits: applyLocalMtproto rebuilds the inbound's filtered client set and re-applies it, so a new client works within a moment (and, on a reload-capable binary, without disturbing the others) and deleting the last client stops the process. The three interactive single-client paths (add, update, delete) call it; bulk operations still ride the reconcile job, which converges to the same state. * chore(mtproto): pin mtg-multi to the mhsanaei fork v1.13.3 The reload endpoint the panel now uses lives in the mhsanaei/mtg-multi fork, so point the source-build pin (DockerInit.sh + both release.yml matrices) at it and bump to v1.13.3. The install still produces the same mtg-multi binary name, so the mtg-<os>-<arch> rename and everything downstream are unchanged. Docs and the package comment note the hot-reload path and its restart fallback. * feat(mtproto): apply live secret updates via the management API and add ad-tag Two capabilities the mhsanaei/mtg-multi v1.13.3 fork exposes are now surfaced by the sidecar manager. Live updates go through PUT /secrets on the fork's management API instead of POST /reload: the panel already holds the whole desired set per inbound, so it sends secrets and the advertising tag as one JSON call that mtg applies atomically, keeping every unchanged connection and closing only removed or re-keyed ones. The config file is still written first so a restart or crash recovery reproduces the state, and any non-200 (an older binary, a refused connection) still falls back to a full restart. Per-inbound ad-tag adds an optional 32-hex Telegram advertising tag plus public-ipv4/public-ipv6 overrides. The ad-tag rides the reloadable secrets fingerprint, so changing it hot-applies without dropping connections; the public IPs are proxy-construction parameters and sit in the structural fingerprint, so a change there restarts the process. Empty public IPs are omitted so mtg auto-detects the reachable address. * feat(inbounds): expose the mtproto ad-tag and public IP in the inbound form Adds an Ad-tag field (validated as 32 hex characters) plus optional Public IPv4 and Public IPv6 overrides to the MTProto inbound form, backed by the same-named settings the sidecar writes into the mtg config. The public IPs are optional — left blank, mtg auto-detects the reachable address the ad-tag middle proxy needs. English strings are added to every locale; the non-English ones carry the English text until translated and fall back to it meanwhile. * ci(mtproto): install mtg-multi from prebuilt release binaries The fork now publishes release archives for every platform we package, so download and unpack the matching mtg-multi-<ver>-<os>-<arch> binary instead of compiling it from source with go install. Faster builds and no toolchain step, and the archive's platform labels line up with our matrix; the produced mtg-<os>-<arch> filenames are unchanged. * i18n(mtproto): localize the ad-tag and public IP strings The six mtgAdTag*/mtgPublicIp* keys shipped with English text in every locale as a placeholder. Translate them into the twelve non-English locales (Arabic, Spanish, Persian, Indonesian, Japanese, Portuguese-BR, Russian, Turkish, Ukrainian, Vietnamese, and Simplified/Traditional Chinese); en-US is unchanged. * retired goreportcard.com
12 KiB
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 <(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 <(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 <(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:
- 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:password@127.0.0.1:5432/xui?sslmode=disable
Migrar una instalación de SQLite existente a PostgreSQL
x-ui migrate-db --dsn "postgres://xui:password@127.0.0.1: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 |
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🌟
Estrellas a lo Largo del Tiempo
