Pannello Marzban per VPN: come installare e configurare da zero, più confronto con 3X-UI e Hiddify

1. Introduzione

In questa guida passo passo installerai e configurerai il pannello Marzban per gestire il tuo server VPN basato su Xray. Alla fine otterrai un pannello amministrativo funzionante con HTTPS, configurazioni pronte da fornire agli utenti, piani tariffari base e una serie chiara di comandi per la manutenzione. Percorreremo insieme tutto il percorso dalla scelta del server e del dominio fino a backup regolari e aggiornamenti. Nel frattempo, comprenderai le differenze chiave tra Marzban, 3X-UI e Hiddify, scegliendo la soluzione più adatta alle tue esigenze.

Chi dovrebbe seguire questa guida: amministratori alle prime armi, proprietari di progetti che vogliono controllare la propria VPN e chi configura per la prima volta un pannello Xray. Le sezioni avanzate sono segnalate separatamente.

Cosa serve sapere prima: comandi base Linux, come connettersi via SSH, modificare file e gestire pacchetti. Tutti i comandi sono chiaramente indicati e accompagnati da verifiche.

Tempo previsto: da 60 a 120 minuti su un server pulito. Se hai già un dominio e esperienza con Linux, sarai più veloce.

2. Preparazione preliminare

Strumenti e accessi necessari

• VPS o server dedicato con Ubuntu 22.04 o 24.04 LTS.
• Un nome di dominio da usare per accedere al pannello (es. panel.example.com).
• Accesso SSH al server con utente con permessi sudo.
• Capacità di aprire le porte 80 e 443 nel firewall e nel pannello del provider.

Requisiti di sistema

• 1 vCPU, 1-2 GB RAM per iniziare; per oltre 100 utenti attivi consigliati 2 vCPU, 4 GB RAM.
• Porte 80 e 443 libere per HTTPS; porta 22 per SSH.
• Spazio libero su disco di almeno 10 GB.

Software da installare

• Aggiornamenti di sistema e utility base.
• Docker e plugin docker compose.
• Nginx e Certbot per emettere certificati TLS, oppure automazione integrata via reverse proxy in Docker.

Backup

Se ci sono dati importanti sul server, crea un backup prima. Su un server nuovo puoi saltare questo passaggio, ma poi configureremo backup regolari per il pannello.

Consiglio: tieni un file locale con appunti dove annotare password, chiavi e comandi importanti. Questo facilita il recupero in caso di trasferimenti o problemi.

3. Concetti base

Termini chiave

• Marzban — pannello di gestione VPN basato su Xray. Permette di creare utenti, fornire configurazioni, limitare traffico e durata, gestire più nodi.
• Xray — componente server con protocolli VLESS, VMess, Trojan e altri. Gestisce trasporto e crittografia.
• Reverse Proxy — proxy inverso (es. Nginx o Traefik), riceve HTTPS sulla porta 443 e instrada le richieste al servizio interno.
• SSL/TLS — crittografia HTTPS per accesso sicuro al pannello.
• Docker — containerizzazione, semplifica installazione e aggiornamenti.

Come funziona

Gli utenti si connettono al tuo server tramite protocolli Xray. Il pannello Marzban conserva e distribuisce configurazioni, conta traffico e scadenze, e può gestire più nodi. Per abilitare l’accesso HTTPS al pannello usiamo un dominio e un certificato. Per stabilità e semplicità di aggiornamenti applichiamo Docker sia al server che al pannello.

Da ricordare: il dominio deve puntare all’IP del server; porte 80 e 443 aperte; certificato valido; Docker funzionante senza errori; pannello avviato come servizio e riavviabile dopo crash.

4. Passo 1: prepariamo server e accessi

Obiettivo

Aggiornare il sistema, includere sicurezza base, assicurarsi che SSH funzioni e porte richieste siano aperte.

Istruzioni dettagliate

1. Connettiti via SSH con utente sudo.
2. Aggiorna pacchetti con: sudo apt update e poi sudo apt upgrade -y.
3. Installa utility di base: sudo apt install -y ca-certificates curl gnupg lsb-release ufw jq.
4. Verifica la connettività internet: ping -c 4 1.1.1.1, confermando assenza di perdite.
5. Abilita firewall UFW: sudo ufw allow OpenSSH, poi sudo ufw allow 80, sudo ufw allow 443, quindi sudo ufw enable e conferma.
6. Controlla le regole attive: sudo ufw status — dovresti vedere Allow per porte 22, 80, 443.
7. Verifica IP esterno: curl -4 ifconfig.co oppure ip a e identifica l’indirizzo provider se il pannello lo mostra.

⚠️ Attenzione: Se il provider ha firewall aggiuntivo, apri porte 80 e 443 anche lì. Altrimenti l’emissione del certificato fallirà.

Consiglio: Se usi un cloud con snapshot, crea uno snapshot dopo la configurazione base. Risparmierai tempo in reinstallazioni successive.

Risultato atteso

Server aggiornato, porte 80 e 443 aperte, SSH accessibile, internet stabile.

✅ Verifica: Comando curl -I http://tuo_IP_esterno deve restituire un HTTP status di risposta temporanea provider o errore di connessione vuoto. L’importante è che non ci siano blocchi firewall su porta 80.

Problemi comuni e soluzioni

• SSH non raggiungibile — controlla IP e utente corretti. Verifica che provider non blocchi porta 22. Apri porta 22 nel pannello provider.
• UFW non si installa — aggiorna lista pacchetti e riprova.
• Porte 80 e 443 occupate — ferma altri servizi che le usano con sudo lsof -i :80 -i :443 e disabilita quelli inutili.

5. Passo 2: configuriamo dominio e DNS

Obiettivo

Associa il dominio al server per accesso HTTPS al pannello.

Istruzioni dettagliate

1. Accedi al registrar e apri l’editor dei record DNS.
2. Crea un record A per il sottodominio del pannello, es. panel.example.com, indicando l’IP del tuo server.
3. Salva e attendi 5-15 minuti, può servire fino a 1 ora a seconda del TTL.
4. Controlla la propagazione: esegui ping panel.example.com dal tuo computer. Deve rispondere con l’IP del server.

Consiglio: Usa TTL basso durante la configurazione per accelerare i cambiamenti. A fine lavori aumenta il TTL per stabilità.

Risultato atteso

Il dominio panel.example.com punta all’IP del server.

✅ Verifica: Comando dig panel.example.com mostra il tuo IP nella sezione ANSWER. Se dig non è disponibile, usa ping o nslookup.

Problemi comuni e soluzioni

• Dominio non risolto — controlla correttezza record A, assicurati assenza di spazi o errori nel sottodominio.
• Dominio punta a IP vecchio — attendi il TTL e riprova.
• Provider usa proxy — disattiva proxy durante il rilascio del certificato per permettere chiamate HTTP dirette al server.

6. Passo 3: installiamo Docker e docker compose

Obiettivo

Installare l’ambiente containerizzato per facilitare lancio e aggiornamento di Marzban e servizi connessi.

Istruzioni dettagliate

1. Installa Docker dal repository Ubuntu: sudo apt install -y docker.io.
2. Installa plugin docker compose: sudo apt install -y docker-compose-plugin.
3. Aggiungi il tuo utente al gruppo docker: sudo usermod -aG docker $USER. Disconnettiti e riconnettiti via SSH per applicare i permessi.
4. Verifica le versioni: docker --version e docker compose version, senza errori.
5. Attiva l’avvio automatico: sudo systemctl enable docker.
6. Controlla che il servizio sia attivo: systemctl is-active docker, atteso 'active'.

Consiglio: Per isolamento configura un utente dedicato nel gruppo docker e utilizza quello per eseguire i container.

Risultato atteso

Docker installato e funzionante, docker compose disponibile come plugin, container avviabili senza sudo.

✅ Verifica: Esegui docker run --rm hello-world. Dovresti vedere messaggio di corretta installazione Docker.

Problemi comuni e soluzioni

• Comando docker non disponibile — disconnettiti e riconnettiti a SSH oppure esegui newgrp docker per aggiornare gruppi utente.
• Servizio non si avvia — controlla log con sudo journalctl -u docker, verifica pacchetti vecchi o conflitti tra demoni.

7. Passo 4: prepariamo reverse proxy e SSL

Obiettivo

Emettere certificato TLS e configurare reverse proxy per accesso sicuro al pannello. Vedremo due opzioni: Nginx sull’host o Traefik in Docker. Scegli una.

Opzione A: Nginx sull’host

1. Installa Nginx: sudo apt install -y nginx.
2. Permetti Nginx Full sul firewall se necessario: sudo ufw allow 'Nginx Full'.
3. Installa Certbot: sudo apt install -y certbot python3-certbot-nginx.
4. Verifica che il dominio punti al server: ping panel.example.com deve restituire il tuo IP.
5. Rilascio certificato: sudo certbot --nginx -d panel.example.com. Inserisci email, accetta condizioni. Scegli redirect da HTTP a HTTPS quando richiesto.
6. Verifica configurazione certificato: sudo nginx -t e poi systemctl reload nginx. Apri nel browser l’indirizzo https del pannello (anche se ancora vuoto) per assicurarti che HTTPS funzioni.

Opzione B: Traefik in Docker

1. Crea rete Docker condivisa per proxy: docker network create web.
2. Avvia container Traefik esponendo porte 80 e 443, collegandolo alla rete web, abilitando rilascio automatico certificati per il dominio. La logica: un container ascolta 80 e 443, conserva certificati in volume, instrada richieste ai servizi tramite label.
3. Verifica container Traefik attivo: docker ps mostra lo stato Up del container.

⚠️ Attenzione: Usa un solo reverse proxy attivo su porte 80 e 443. Se scegli Nginx sull’host, non avviare Traefik e viceversa.

Consiglio: In produzione Traefik o Caddy in Docker offrono più facilità con configurazioni vicine ai servizi e portabilità. Per iniziare Nginx è più familiare.

Risultato atteso

Dominio accessibile via HTTPS. Il reverse proxy accetta connessioni e instrada le richieste a Marzban.

✅ Verifica: Accedi via browser al dominio con https e controlla che il certificato sia valido con lucchetto verde. È normale se il pannello è ancora vuoto in questa fase.

Problemi comuni e soluzioni

• Certificato non emesso — controlla che il dominio punti all’IP server e che la porta 80 sia aperta. Disattiva proxy dal registrar durante la validazione.
• Conflitto porte — ferma servizi che occupano 80 e 443 prima di avviare il proxy.

8. Passo 5: installiamo e avviamo Marzban

Obiettivo

Lanciare pannello Marzban in Docker, collegarlo al reverse proxy, creare admin e accedere all’interfaccia web.

Istruzioni dettagliate

1. Crea una cartella progetto, ad es. mkdir -p ~/marzban, poi cd ~/marzban.
2. Crea file docker compose con servizi per pannello e database. Se vuoi minime dipendenze esterne, usa SQLite integrata. Per carichi seri meglio un database separato, ma partiamo da SQLite per semplicità.
3. Apri l'editor di testo e crea il file di configurazione docker compose. Descrivi due servizi: marzban e opzionalmente il reverse proxy se usi Traefik. Se usi Nginx sull’host, marzban ascolta localmente porta 8000, Nginx proxy verso 127.0.0.1:8000.
4. Compila variabili d’ambiente per il pannello: chiave segreta, indirizzo host e porta server interno web, percorso database, fuso orario, e URL del pannello per link corretti. Es: SECRET_KEY con stringa casuale di 32-64 caratteri, UVICORN_HOST=0.0.0.0, UVICORN_PORT=8000, DATABASE_URL su SQLite, TIMEZONE il tuo fuso, BASE_URL con l’URL https del pannello.
5. Se usi Nginx sull’host, aggiungi nel suo config il blocco server per ascoltare 443 su tuo dominio e proxy verso 127.0.0.1:8000. Includi header X-Forwarded-Proto e X-Forwarded-For. Verifica config e ricarica Nginx.
6. Se usi Traefik, collega il container pannello alla rete web e aggiungi label di routing per dominio, attiva redirect automatico HTTPS se non già fatto.
7. Avvia servizi: docker compose up -d. Aspetta 10-30 secondi perché i container si alzino.
8. Controlla log pannello: docker logs -f nome_container_marzban. Assicurati che server ascolti porta 8000 e non dia errori.
9. Apri browser all’indirizzo https del pannello. Dovresti vedere login o wizard di prima configurazione.
10. Crea admin via CLI container o tramite wizard interno. Via CLI: esegui comando nel container per creare admin con login e password sicura. Conserva i dati nelle note.

Consiglio: Se la pagina non si apre, verifica che il reverse proxy invii correttamente l’header X-Forwarded-Proto con valore https, essenziale per generare link corretti.

Risultato atteso

Pannello accessibile via HTTPS, puoi effettuare login admin, visualizzi dashboard con statistiche zero e lista utenti vuota.

✅ Verifica: Esegui docker ps. Devono essere attivi container pannello e reverse proxy. Aprendo pannello nel browser non si devono vedere errori certificato e il login funziona.

Problemi comuni e soluzioni

• 502 Bad Gateway — controlla che container ascolti porta 8000 e sia accessibile internamente, proxy configurato correttamente.
• Schermo vuoto — guarda console del browser e log container. Potrebbe mancare migrazione database; esegui migrazione dal container.
• Admin non creato — ripeti comando di creazione e assicurati password sia conforme a requisiti di lunghezza e complessità.

9. Passo 6: configuriamo protocolli, piani e utenti

Obiettivo

Rendere il pannello utile concretamente: attiva protocolli Xray necessari, crea piani tariffari con limiti, aggiungi utenti di test, ottieni configurazioni e verifica connessione da telefono e PC.

Istruzioni dettagliate

1. Accedi al pannello come admin e apri sezione configurazioni. Attiva protocolli che userai: VLESS Reality, VMess, Trojan. All’inizio vanno bene uno o tre, in base ai client.
2. Configura porte in ingresso. Se 443 è già occupato da HTTPS pannello, usa domini diversi o SNI, oppure configura ingressi separati con dominio dedicato. Segui istruzioni in interfaccia.
3. Crea un piano con limiti ragionevoli: es. 50 GB traffico, durata 30 giorni. Attiva disattivazione automatica al termine se supportato.
4. Aggiungi il primo utente: inserisci login, associa piano, imposta se necessario limitazioni su dispositivo o protocollo di connessione.
5. Salva configurazioni generate. Di solito il pannello crea link, codici QR ed esportazioni per client. Copia link VLESS o Trojan o scarica file JSON se usi OpenVPN o WireGuard opzionali via altri nodi.
6. Testa connessione da telefono: installa client Xray o V2RayNG, scansiona QR, collega e controlla che internet funzioni col tuo nodo. Visita pagina check IP per vedere IP server.
7. Verifica connessione da PC: usa client per Windows o macOS, importa link o file config, connetti e prova velocità.
8. Crea altri 2-3 utenti con casi diversi: limiti minori, illimitato per test, protocolli diversi. Questo aiuta a verificare conteggi e scenari differenziati.

Consiglio: Parti da un solo protocollo, per esempio VLESS con TLS, assicurati funzioni stabile, poi aggiungi Reality o Trojan. Più facile individuare problemi così.

Risultato atteso

Almeno un utente operativo che si connette correttamente e naviga tramite il tuo server. Traffico e tempo sono tracciati nel pannello, stati si aggiornano.

✅ Verifica: Nel pannello, nella scheda utente, vedi sessione attiva o traffico appena registrato. Sul client appare IP esterno del server.

Problemi comuni e soluzioni

• Client non si connette — controlla dominio, certificato, porta e corrispondenza protocollo client-server. Assicurati config provenga dal pannello.
• Bassa velocità — verifica limiti piano, carico CPU e rete sul server. Modifica modalità tunnel nel client per escludere problemi locali.
• Statistiche non aggiornate — assicurati che pannello e nodo comunichino, controlla orario e fuso, riavvia servizi.

10. Verifica del risultato

Checklist

• Dominio raggiungibile in HTTPS, certificato valido.
• Pannello accessibile, login admin funzionante.
• Piani e utenti creati.
• Connessione client riuscita, IP esterno corrisponde al server.
• Statistiche mostrano sessioni e traffico.
• Container attivi e riavviano automaticamente.

Come testare

• Simula reboot: sudo reboot. Controlla che pannello e proxy si avviano da soli.
• Controlla rinnovo certificato automatico (per Certbot timer systemd predefinito).
• Verifica limiti piani: imposta limiti bassi e scarica file. Pannello deve conteggiare e bloccare accesso se configurato.

Indicatori di successo

• Tempo di risposta pannello sotto 300 ms nella regione.
• Connessioni client stabili per ore senza interruzioni.
• Minimi log di errore in pannello e proxy, solo info.

Consiglio: Pianifica backup settimanali e aggiornamenti mensili dei container. Eviterai accumulo di debito tecnico.

11. Errori tipici e soluzioni

• Problema: certificato non emesso. Motivo: dominio non punta a server o porta 80 chiusa. Soluzione: verifica record A, apri porte 80 e 443 in UFW e nel pannello provider, disattiva proxy in fase di validazione.
• Problema: 502 Bad Gateway in browser. Motivo: pannello non ascolta porta giusta, upstream proxy errato. Soluzione: assicurati container ascolti porta 8000, proxy punti a 127.0.0.1:8000, controlla log.
• Problema: client non si connette VPN. Motivo: discrepanza protocollo o dominio, config datato. Soluzione: ricrea config nel pannello, verifica protocollo e porta, riavvia client.
• Problema: pannello non parte dopo reboot. Motivo: Docker non abilitato all’avvio o compose non attivato. Soluzione: sudo systemctl enable docker, usa docker compose up -d in unit systemd o cron @reboot.
• Problema: certificato scaduto. Motivo: rinnovo automatico non funzionante. Soluzione: rinnova manualmente, verifica timer Certbot o automazione proxy, assicurati porta 80 disponibile per validazione.
• Problema: bassa velocità per alcuni utenti. Motivo: routing debole, area congestionata, CPU limitata. Soluzione: assegna protocollo o porta alternativa, considera server vicino all’utente.
• Problema: statistiche non corrispondono. Motivo: fuso orario o cache errati. Soluzione: imposta TIMEZONE corretto nel container, sincronizza orario, controlla impostazioni conteggio nel pannello.

12. Funzionalità aggiuntive

Configurazioni avanzate

• Architettura multinodo: collega nodi in regioni diverse per instradare utenti verso il percorso migliore automaticamente.
• Protocollo Reality: riduce visibilità traffico, utile per reti filtrate. Segui istruzioni pannello assicurandoti corretto SNI e chiavi.
• Quota e disattivazione automatica: piani dettagliati per gestire carico.

Ottimizzazione

• Scelta regione: posiziona server vicino utenti, migliora RTT e velocità.
• Compressione e tuning TCP: parametri kernel e buffer influenzano velocità di picco. Modifica con cautela e misura.
• Cache DNS per client: riduce latency su richieste ripetute.

Ulteriori consigli

• Backup: crea cron job che archivia ogni giorno la cartella dati del pannello e salva su storage oggetti. Mantieni 7-14 rotazioni.
• Monitoraggio: metriche container e health check, alert su Telegram per caduta container o spazio esaurito.
• Aggiornamenti CI: riavvia periodicamente container con immagini aggiornate dopo test in staging.

Consiglio: Fai modifiche piccole e singole, così torni facilmente a configurazioni precedenti funzionanti.

13. Confronto con 3X-UI e Hiddify

Quando scegliere Marzban

• Serve gestione di piani, quote, statistiche avanzate e multinodi.
• Se usi Docker e reverse proxy per flessibilità e aggiornamenti.
• Importa scalabilità e controllo protocolli Xray.

3X-UI: pro e contro

• Pro: avvio molto semplice, poche dipendenze, rapido su server pulito. Ideale per nodo singolo e scenari base.
• Contro: meno funzionalità per piani e multinodi. Aggiornamenti e sicurezza richiedono disciplina.

Hiddify: pro e contro

• Pro: installazione amichevole, automatizza molti passaggi, buona partenza per principianti. Spesso include preset per protocolli diversi.
• Contro: meno flessibile per topologie complesse e restrizioni specifiche. Alcune configurazioni sono astratte.

Conclusione confronto

Se vuoi un pannello con logiche avanzate di gestione utenti, tariffazione, multinodi e buona integrazione Xray, Marzban è fra le opzioni più bilanciate. 3X-UI è ottimo per scenari singolo nodo senza logica billing complessa. Hiddify è comodo ma meno adatto a installazioni grandi e precise.

Consiglio: Parti da un nodo unico Marzban. Capite carichi e schemi, aggiungi secondo nodo in altra regione e distribuisci utenti.

14. Verifica finale

Checklist definitiva

• Dominio risolve IP server.
• Certificato emesso e si rinnova automaticamente.
• Marzban accessibile in HTTPS, login funzionante.
• Utenti e piani creati, configurazioni scaricabili.
• Connessioni client stabili, velocità adeguata.
• Backup configurati e verificati con restore su server test.
• Aggiornamenti container documentati.

Come testare

• Disponibilità: curl -I https indirizzo pannello restituisce 200 o 302.
• Metriche: monitora traffico utente prima e dopo il download di file da 1-2 GB. Verifica che il conteggio funzioni.
• Test reboot: riavvia server, controlla avvio automatico servizi.

✅ Verifica: Se tutto è ok, la tua infrastruttura è pronta per distribuire accessi agli utenti.

15. FAQ

Domanda: Posso fare senza Docker?
Risposta: Sì, ma rende complicati aggiornamenti e portabilità. Docker accelera avvio, recupero e isola dipendenze.

Domanda: Quale protocollo scegliere da principiante?
Risposta: Parti da VLESS con TLS su tuo dominio. È ampiamente supportato, stabile e compatibile con la maggior parte dei client.

Domanda: Meglio un server potente unico o diversi in vari Paesi?
Risposta: Per utenti distribuiti è meglio più server vicini, riduce latenza e migliora stabilità.

Domanda: Come impostare diversi limiti di traffico?
Risposta: Crea più piani nel pannello con quote e durate diverse. Associa il piano all’utente in creazione o modifica successivamente.

Domanda: Come tornare indietro dopo aggiornamento fallito?
Risposta: Usa backup cartella dati e versioni precedenti delle immagini. Prima dell’update crea backup e annota tag Docker usati.

Domanda: Cosa fare se la velocità scende di sera?
Risposta: Passa a protocollo o porta alternativa, suggerisci nodo in altra regione, verifica carico CPU e rete, controlla routing.

Domanda: Posso dividere pannello e nodo su server diversi?
Risposta: Sì. Il pannello gestisce molti nodi in Paesi diversi, schema tipico per scalabilità.

Domanda: Marzban supporta WireGuard e OpenVPN?
Risposta: Il core Marzban è focalizzato su famiglia Xray. WireGuard e OpenVPN si possono lanciare a parte e fornire link o istruzioni dal pannello come servizi esterni.

Domanda: Serve un IP dedicato?
Risposta: Consigliato. Un IP dedicato riduce rischi di blocchi e migliora predicibilità routing.

Domanda: Se il dominio è protetto da registrar?
Risposta: Disattiva proxy per emissione certificato, poi riattivalo. Valuta modalità di validazione.

16. Conclusione

Hai completato il ciclo completo: preparato server, configurato dominio e HTTPS, lanciato Marzban, creato piani e utenti, testato accesso da telefono e PC, aggiunto pratiche base di backup e aggiornamenti. Ora disponi di un servizio VPN gestito con statistiche trasparenti e configurazioni Xray flessibili. Se il carico cresce, aggiungi nodi in regioni adatte e distribuisci utenti per migliore qualità.

⚠️ Attenzione: Manutenere un sistema DIY richiede tempo: aggiornamenti regolari, monitoraggio, backup e interventi rapidi in caso di problemi. Prevedi alcune ore al mese, più durante cambi di configurazione.

Consiglio esperto: se ti serve subito un server VPN personale senza risorse condivise e IP dedicato, senza sporcarsi la console, valuta il servizio vpn.how. Offrono protocolli WireGuard, OpenVPN, IKEv2, L2TP, SSTP secondo necessità, server a Mosca, San Pietroburgo, Amsterdam, Francoforte, Londra, New York, San Jose, Chicago, Singapore, Sydney, Madrid, Helsinki, Stoccolma, Varsavia, Copenaghen e Stavanger. Accettano carte russe, SBP, USDT o BTC; tariffe da 490 ₽ al giorno e 2490 ₽ al mese con sconti su periodi lunghi. Server si avviano in circa 5 minuti dopo pagamento, policy no-log. Soluzione comoda per chi vuole rapido, stabile, senza installare e mantenere.

Puoi proseguire verso architetture multinodo, automazione deployment, integrazione billing e robustezza. La tua base attuale è già solida per avanzare con serenità verso scenari più complessi.