Come installare il pannello 3X-UI su un VPS

3X-UI è un pannello web per Xray-core. Permette di gestire gli inbound (VLESS, VMess, Trojan, Shadowsocks e altri), emettere link di sottoscrizione, impostare limiti di traffico e date di scadenza e osservare le connessioni in tempo reale senza modificare JSON a mano. Per chi ha già un VPS è uno dei modi più rapidi per ottenere uno stack proxy manutenibile, invece di una configurazione usa-e-getta che nessuno vorrà toccare sei mesi dopo.

Questa guida è pensata per un VPS Ubuntu 22.04 o 24.04 appena installato, come appaiono la maggior parte delle immagini Linux Hiddence dopo il primo avvio. Installiamo la build MHSanaei di 3X-UI, molto diffusa, cambiamo ogni segreto predefinito al primo accesso, mettiamo il pannello dietro HTTPS, apriamo solo le porte davvero necessarie, creiamo un inbound VLESS + Reality e poi passiamo alle app client. Se hai già seguito l’articolo su Marzban, l’idea è simile — un pannello sopra Xray — ma percorso di installazione, layout dei file e lavoro quotidiano sono diversi: non mescolare i due sullo stesso server finché non sai davvero come separare le porte.

Perché 3X-UI invece di un config Xray grezzo

Un config Xray grezzo va bene per un utente e un inbound. Quando aggiungi amici, ruoti le chiavi Reality o ti serve un URL di sottoscrizione che i telefoni importano con un tocco, un pannello fa risparmiare ore. 3X-UI memorizza gli utenti in un database locale, riavvia Xray in modo pulito dopo le modifiche e offre una dashboard compatta per traffico e stato online. Non è uno strato magico di anonimato: posizione del VPS, fingerprint TLS, tipo di inbound e la tua igiene operativa decidono ancora come si comporta l’impianto in rete.

• Interfaccia web per inbound, client, traffico e scadenze invece di JSON modificato a mano
• Link di sottoscrizione integrati per v2rayN, v2rayNG, Streisand, Happ e client simili
• Installazione con un comando e un percorso di aggiornamento documentato
• Funziona bene su un VPS piccolo (1 vCPU / 1 GB di RAM bastano per uso personale)
• Conservi root sul tuo server: il pannello non invia i config a un cloud di terze parti

Cosa serve prima di iniziare

Non saltare dominio e firewall. Un pannello lasciato in HTTP sulla porta 2053 con la password predefinita viene scansionato dai bot in poche ore. Prepara questi elementi, poi connettiti come root (o utente sudo) via SSH.

• Un VPS Linux con indirizzo IPv4 pubblico (consigliato Ubuntu 22.04/24.04)
• Almeno 1 GB di RAM e 10 GB di disco; 2 GB di RAM sono più comodi se girano anche altri servizi
• Accesso root o sudo via SSH
• Un dominio o sottodominio con record A puntato all’IP del VPS (necessario per un certificato decente del pannello)
• Circa 20–30 minuti, più l’attesa DNS se hai appena creato il record A

Passo 1: Aggiornare il sistema e impostare il fuso orario

Un VPS nuovo ha spesso aggiornamenti di sicurezza in sospeso e l’orologio in UTC. Aggiorna prima i pacchetti, così l’installer non litiga con un OpenSSL o curl obsoleti. Il fuso orario è facoltativo per Xray in sé, ma rende molto più leggibili i log del pannello e le date di scadenza dei certificati.

ssh root@YOUR_VPS_IP

apt update && apt -y upgrade
apt -y install curl wget ca-certificates gnupg socat tar unzip

timedatectl set-timezone UTC
hostnamectl set-hostname panel

# Confirm DNS for your subdomain (should print your VPS IP):
dig +short panel.example.com

Passo 2: Installare 3X-UI

Lo script di installazione ufficiale della build MHSanaei di 3X-UI scarica l’ultima versione, installa Xray-core, crea un servizio systemd e stampa l’URL del primo accesso. Leggi l’output con attenzione: contiene un percorso casuale e un nome utente/password generati. Copiali subito in un gestore di password. Se lo script chiede la porta del pannello, tieni 2053 o scegli una porta alta libera; ricordala per il passo del firewall.

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

# After install, useful commands:
x-ui                    # interactive menu (start/stop/restart, reset, update)
systemctl status x-ui    # confirm the service is active
ss -tulpn | grep x-ui    # see which port the panel listens on

Passo 3: Primo accesso e hardening immediato

Apri l’URL stampato dall’installer, di solito http://YOUR_IP:2053/<percorso-casuale>. Accedi con le credenziali generate, poi vai alle impostazioni del pannello (Panel Settings o Configuration). Cambia nome utente e password con valori unici. Se il pannello consente di cambiare il percorso base web, fallo: un percorso lungo e casuale taglia una mole enorme di scansioni opportunistiche. Imposta la porta di ascolto se vuoi qualcosa di diverso da 2053. Salva, riavvia il pannello dall’interfaccia o con systemctl restart x-ui, poi accedi di nuovo sul nuovo URL.

Poi attiva l’autenticazione a due fattori se la tua build la offre e disattiva i modelli di inbound che non userai mai. Nelle impostazioni Xray lascia la versione del core fornita col pannello, a meno che tu non abbia un motivo preciso per fissarne un’altra. Non esporre ancora il pannello sulle porte 80/443 se quelle porte serviranno in seguito a Reality o a un reverse proxy: scegli una strategia e tienila.

• Sostituisci subito l’accesso amministratore generato
• Mantieni il percorso web segreto; non spostare il pannello su /
• Preferisci una porta del pannello non predefinita e annotala
• Non riutilizzare questa password su altri servizi

Passo 4: Certificato TLS per il pannello

I browser avvisano su HTTP e inviare la password amministratore in chiaro su una rete pubblica è una cattiva idea. 3X-UI può richiedere un certificato Let's Encrypt se la porta 80 è libera e il dominio punta a questo VPS. Nel pannello apri la sezione certificato / SSL, inserisci panel.example.com e richiedi il certificato. Se la porta 80 è già occupata, usa un flusso DNS-01 oppure metti Caddy/Nginx davanti e fai reverse proxy verso 127.0.0.1:2053.

# Quick check that port 80 is free before the panel ACME challenge:
ss -tulpn | grep ':80'

# If you terminate TLS on Caddy instead of inside 3X-UI:
# Caddyfile example (panel stays on 127.0.0.1:2053):
# panel.example.com {
#     reverse_proxy 127.0.0.1:2053
# }

Passo 5: Creare un inbound VLESS Reality

In Inbounds crea un nuovo inbound. Un default solido per molte reti è VLESS con Reality e TCP. Scegli una porta che non sia quella del pannello: 443 è comune se nient’altro è associato lì; altrimenti una porta TCP alta e sii coerente nel firewall. Genera un UUID per il primo client, coppie di chiavi Reality nell’interfaccia e imposta dest / serverNames su un bersaglio legittimo che sei autorizzato a imitare (un sito noto che supporta TLS 1.3). Salva l’inbound e conferma nei log del pannello che Xray si ricarica senza errori.

Poi aggiungi altri client su quell’inbound se ti servono: ogni utente ottiene un UUID, un’etichetta email opzionale e un limite di traffico o di tempo opzionale. Copia il link di connessione o l’URL di sottoscrizione dalla riga utente. Non pubblicare quei link in chat pubbliche: equivalgono a una password.

# On the server, confirm Xray is listening on the inbound port (example: 443):
ss -tulpn | grep -E ':443|:2053'

# Follow Xray logs if a client cannot connect:
journalctl -u x-ui -f

Passo 6: Firewall — solo le porte che ti servono

UFW su Ubuntu basta. Consenti prima SSH per non chiuderti fuori, poi la porta del pannello e quella dell’inbound. Se hai richiesto un certificato Let's Encrypt dal pannello, consenti anche 80/tcp durante l’emissione. Un inbound Reality su 443 richiede 443/tcp (e non il pannello sulla stessa porta).

ufw allow OpenSSH
ufw allow 2053/tcp comment '3x-ui panel (change if you picked another port)'
ufw allow 443/tcp comment 'VLESS Reality inbound'
# ufw allow 80/tcp comment 'only if panel ACME needs it'
ufw enable
ufw status verbose

Collegare i client

Su Windows, v2rayN può importare un link VLESS dagli appunti. Su Android, v2rayNG o client Xray simili fanno lo stesso da un codice QR. Su iOS usa un client che supporta VLESS Reality (per esempio Streisand o Happ, a seconda di cosa è disponibile nella tua zona). Dopo l’importazione attiva il profilo e controlla l’elenco online del pannello. Se il client resta offline, le cause usuali sono una porta sbagliata, UDP lasciato attivo su un inbound solo TCP, un serverName Reality che non coincide con dest, o un firewall locale sul portatile.

• Windows: v2rayN — importa il link VLESS, imposta il routing come ti serve (globale o basato su regole)
• Android: v2rayNG — scansiona il QR dalla pagina utente del pannello
• macOS / iOS: un client con supporto VLESS + Reality; incolla lo stesso link
• URL di sottoscrizione: aggiungilo nel client così le rotazioni UUID non richiedono un reimport manuale

Aggiornamenti, backup e reinstallazione sicura

Prima di ogni aggiornamento del pannello scarica un backup dall’interfaccia (database + configurazione). Conservalo fuori dal VPS. Gli aggiornamenti passano in genere da x-ui e dall’opzione di aggiornamento nel menu, o dallo stesso script di installazione che rileva un’installazione esistente. Dopo un aggiornamento conferma che il servizio systemd è attivo e che gli inbound ascoltano ancora. Se reinstalli il sistema, ripristina il backup nel pannello invece di ricreare ogni UUID a mano.

x-ui   # choose update when prompted, or:
# bash <(curl -Ls https://raw.githubusercontent.com/mhsanaei/3x-ui/master/install.sh)

# Backup files commonly live under /etc/x-ui/ — copy them off-box:
ls -la /etc/x-ui/
# Example offsite copy:
# scp -r /etc/x-ui/ you@backup-host:~/x-ui-backup-$(date +%F)/

Risoluzione dei problemi

La maggior parte dei fallimenti del primo giorno sono DNS, porte o campi Reality. Percorri questo elenco prima di reinstallare il pannello. Reinstallare senza backup è il modo in cui si perdono tutti gli UUID dei client.

• Non si apre l’interfaccia web: controlla systemctl status x-ui, ss -tulpn e UFW. Conferma di aver incluso il percorso segreto nell’URL.
• Password amministratore dimenticata: esegui x-ui sul server e usa l’opzione di reset.
• Il client si collega e poi si blocca: porta inbound bloccata, oppure UDP attivo su un inbound Reality TCP.
• Errori TLS sul pannello: il record A del dominio non punta ancora qui, o la porta 80 è occupata durante ACME.
• Handshake Reality fallito: dest/serverNames non coincidono, o un altro servizio è già associato a 443.
• CPU alta: troppi inbound su un piano 1 vCPU, o una scansione/flood su una porta aperta — controlla ss e il conteggio online del pannello.

Note di sicurezza che contano davvero

Tratta il pannello come software di amministrazione di produzione. Può creare nuovi utenti e leggere ogni UUID. Limita chi può raggiungere la porta web: se hai un IP d’ufficio stabile, consenti solo quell’IP in UFW per 2053/tcp. SSH con chiavi, non con password. Non ospitare siti pubblici non correlati sullo stesso IP se usi Reality su 443: stack TLS in competizione sulla stessa porta sono una causa classica di interruzioni. Ruota la password amministratore se uno screenshot del pannello è mai finito in una chat.

• Solo chiavi SSH; disattiva l’accesso con password quando le chiavi funzionano
• Restringi la porta del pannello nel firewall quando puoi
• Esegui il backup di /etc/x-ui fuori dal server con cadenza regolare
• Non condividere URL di sottoscrizione in gruppi Telegram pubblici
• Tieni d’occhio il disco: log e statistiche di traffico crescono su un inbound trafficato

Consigli pratici

• Un inbound con molti client è più facile da gestire di dieci inbound quasi identici
• Nomina i client per dispositivo (laptop-anna, phone-ben) così i grafici di traffico hanno un senso
• Se ti serve anche un reverse proxy per un sito, metti il sito su un altro IP o un’altra porta: non contendere 443 a Reality
• Dopo ogni riavvio di x-ui, testa un client prima di chiudere la sessione SSH
• Leggi il changelog prima di aggiornare; evita i salti a latest un venerdì sera

Ora hai 3X-UI installato come servizio systemd, un URL di amministrazione protetto, TLS sul pannello, un inbound VLESS Reality, regole firewall allineate a quelle porte e l’abitudine del backup. Aggiungi client dalla pagina inbound, importa il link su ogni dispositivo e aggiorna il pannello solo dopo un backup. Se qualcosa si rompe, il menu x-ui sul VPS è la via di recupero, non una reinstallazione completa.