Installer le panneau 3X-UI sur un VPS

3X-UI est un panneau web pour Xray-core. Il permet de gérer les inbounds (VLESS, VMess, Trojan, Shadowsocks et d’autres), d’émettre des liens d’abonnement, de fixer des limites de trafic et des dates d’expiration, et de suivre les connexions en direct sans éditer du JSON à la main. Pour qui possède déjà un VPS, c’est l’un des moyens les plus rapides d’obtenir une pile proxy maintenable plutôt qu’une config jetable que plus personne n’osera toucher six mois plus tard.

Ce guide s’adresse à un VPS Ubuntu 22.04 ou 24.04 tout neuf, comme la plupart des images Linux Hiddence après le premier démarrage. Nous installerons la version MHSanaei de 3X-UI, largement utilisée, changerons chaque secret par défaut dès la première connexion, placerons le panneau derrière HTTPS, n’ouvrirons que les ports nécessaires, créerons un inbound VLESS + Reality, puis passerons aux applications clientes. Si vous avez déjà suivi notre article Marzban, l’idée est proche — un panneau au-dessus de Xray — mais le chemin d’installation, l’arborescence et le quotidien diffèrent : ne mélangez pas les deux sur le même serveur tant que vous ne savez pas séparer les ports.

Pourquoi 3X-UI plutôt qu’un fichier de config Xray brut

Une config Xray brute convient à un utilisateur et un inbound. Dès que vous ajoutez des amis, faites tourner les clés Reality ou avez besoin d’une URL d’abonnement que les téléphones importent d’un tap, un panneau fait gagner des heures. 3X-UI stocke les utilisateurs dans une base locale, redémarre Xray proprement après les changements et offre un tableau de bord compact pour le trafic et le statut en ligne. Ce n’est pas une couche d’anonymat magique : l’emplacement du VPS, l’empreinte TLS, le type d’inbound et votre hygiène opérationnelle décident encore du comportement sur le réseau.

• Interface web pour inbounds, clients, trafic et expiration au lieu d’un JSON édité à la main
• Liens d’abonnement intégrés pour v2rayN, v2rayNG, Streisand, Happ et clients similaires
• Installation en une commande et chemin de mise à jour documenté
• Fonctionne bien sur un petit VPS (1 vCPU / 1 Go de RAM suffisent pour un usage personnel)
• Vous gardez root sur votre serveur — le panneau n’envoie pas les configs vers un cloud tiers

Ce qu’il vous faut avant de commencer

Ne sautez pas le domaine ni le pare-feu. Un panneau laissé en HTTP sur le port 2053 avec le mot de passe par défaut est scanné par des robots en quelques heures. Préparez les éléments suivants, puis connectez-vous en root (ou utilisateur sudo) via SSH.

• Un VPS Linux avec une adresse IPv4 publique (Ubuntu 22.04/24.04 recommandé)
• Au moins 1 Go de RAM et 10 Go de disque ; 2 Go de RAM sont plus confortables si d’autres services tournent aussi
• Accès root ou sudo via SSH
• Un domaine ou sous-domaine dont l’enregistrement A pointe vers l’IP du VPS (nécessaire pour un vrai certificat du panneau)
• Environ 20 à 30 minutes, plus le délai DNS si vous venez de créer l’enregistrement A

Étape 1 : Mettre à jour le système et régler le fuseau horaire

Un VPS tout neuf a souvent des mises à jour de sécurité en attente et l’horloge en UTC. Mettez d’abord les paquets à jour pour que l’installeur ne se batte pas avec un OpenSSL ou un curl obsolète. Le fuseau horaire est facultatif pour Xray lui-même, mais il rend les journaux du panneau et les dates d’expiration des certificats bien plus lisibles.

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

Étape 2 : Installer 3X-UI

Le script d’installation officiel de la version MHSanaei de 3X-UI télécharge la dernière version, installe Xray-core, crée un service systemd et affiche l’URL de première connexion. Lisez la sortie avec attention : elle contient un chemin aléatoire et un identifiant/mot de passe générés. Copiez-les immédiatement dans un gestionnaire de mots de passe. Si le script demande le port du panneau, gardez 2053 ou choisissez un port élevé libre ; retenez-le pour l’étape pare-feu.

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

Étape 3 : Première connexion et durcissement immédiat

Ouvrez l’URL affichée par l’installeur, en général http://YOUR_IP:2053/<chemin-aléatoire>. Connectez-vous avec les identifiants générés, puis allez dans les paramètres du panneau (Panel Settings ou Configuration). Changez le nom d’utilisateur et le mot de passe pour des valeurs uniques. Si le panneau permet de changer le chemin de base web, faites-le : un long chemin aléatoire élimine une grande partie des scans opportunistes. Réglez le port d’écoute si vous voulez autre chose que 2053. Enregistrez, redémarrez le panneau depuis l’interface ou avec systemctl restart x-ui, puis reconnectez-vous sur la nouvelle URL.

Ensuite, activez l’authentification à deux facteurs si votre version la propose, et désactivez les modèles d’inbound dont vous n’aurez jamais besoin. Dans les paramètres Xray, laissez la version du cœur livrée avec le panneau sauf raison précise d’en épingler une autre. N’exposez pas encore le panneau sur les ports 80/443 si ceux-ci serviront plus tard à Reality ou à un reverse proxy — choisissez une stratégie et tenez-vous-y.

• Remplacez immédiatement l’identifiant administrateur généré
• Conservez le chemin web secret ; ne déplacez pas le panneau vers /
• Préférez un port de panneau non par défaut et notez-le
• Ne réutilisez jamais ce mot de passe sur d’autres services

Étape 4 : Certificat TLS pour le panneau

Les navigateurs avertissent en HTTP, et envoyer le mot de passe administrateur en clair sur un réseau public est une mauvaise idée. 3X-UI peut demander un certificat Let's Encrypt si le port 80 est libre et que le domaine pointe vers ce VPS. Dans le panneau, ouvrez la section certificat / SSL, saisissez panel.example.com et demandez le certificat. Si le port 80 est déjà pris, utilisez un flux DNS-01 ou placez Caddy/Nginx devant et reverse-proxiez vers 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
# }

Étape 5 : Créer un inbound VLESS Reality

Dans Inbounds, créez un nouvel inbound. Un défaut solide pour beaucoup de réseaux est VLESS avec Reality et TCP. Choisissez un port qui n’est pas celui du panneau — 443 est courant si rien d’autre n’y est lié ; sinon un port TCP élevé, et soyez cohérent dans le pare-feu. Générez un UUID pour le premier client, des paires de clés Reality dans l’interface, et réglez dest / serverNames sur une cible légitime que vous avez le droit d’imiter (un site connu qui prend en charge TLS 1.3). Enregistrez l’inbound et confirmez que Xray se recharge sans erreur dans les journaux du panneau.

Ajoutez ensuite d’autres clients sur cet inbound si besoin : chaque utilisateur reçoit un UUID, une étiquette e-mail optionnelle et une limite de trafic ou de durée optionnelle. Copiez le lien de connexion ou l’URL d’abonnement depuis la ligne utilisateur. Ne publiez pas ces liens dans des discussions publiques ; ils équivalent à un mot de passe.

# 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

Étape 6 : Pare-feu — uniquement les ports nécessaires

UFW sur Ubuntu suffit. Autorisez d’abord SSH pour ne pas vous enfermer dehors, puis le port du panneau et le port d’inbound. Si vous avez demandé un certificat Let's Encrypt depuis le panneau, autorisez aussi 80/tcp pendant l’émission. Un inbound Reality sur 443 nécessite 443/tcp (et pas le panneau sur le même port).

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

Connecter les clients

Sous Windows, v2rayN peut importer un lien VLESS depuis le presse-papiers. Sous Android, v2rayNG ou des clients Xray similaires font de même à partir d’un QR code. Sous iOS, utilisez un client qui prend en charge VLESS Reality (par exemple Streisand ou Happ, selon ce qui est disponible dans votre région). Après l’import, activez le profil et vérifiez la liste en ligne du panneau. Si le client reste hors ligne, les causes habituelles sont un port erroné, l’UDP laissé actif sur un inbound TCP uniquement, un serverName Reality qui ne correspond pas à dest, ou un pare-feu local sur l’ordinateur portable.

• Windows : v2rayN — importer le lien VLESS, régler le routage selon vos besoins (global ou par règles)
• Android : v2rayNG — scanner le QR depuis la page utilisateur du panneau
• macOS / iOS : un client avec prise en charge VLESS + Reality ; coller le même lien
• URL d’abonnement : l’ajouter dans le client pour que les rotations d’UUID ne demandent pas un réimport manuel

Mises à jour, sauvegarde et réinstallation sans casse

Avant chaque mise à jour du panneau, téléchargez une sauvegarde depuis l’interface (base + configuration). Stockez-la hors du VPS. Les mises à jour passent en général par x-ui puis l’option de mise à jour du menu, ou par le même script d’installation qui détecte une install existante. Après une mise à jour, confirmez que le service systemd est actif et que les inbounds écoutent encore. Si vous réinstallez le système, restaurez la sauvegarde dans le panneau plutôt que de recréer chaque UUID à la main.

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

Dépannage

La plupart des échecs du premier jour viennent du DNS, des ports ou des champs Reality. Parcourez cette liste avant de réinstaller le panneau. Réinstaller sans sauvegarde, c’est perdre tous les UUID clients.

• Impossible d’ouvrir l’interface web : vérifiez systemctl status x-ui, ss -tulpn et UFW. Confirmez que l’URL contient le chemin secret.
• Mot de passe administrateur oublié : lancez x-ui sur le serveur et utilisez l’option de réinitialisation.
• Le client se connecte puis se fige : port d’inbound bloqué, ou UDP activé sur un inbound Reality TCP.
• Erreurs TLS sur le panneau : l’enregistrement A du domaine ne pointe pas encore ici, ou le port 80 est occupé pendant ACME.
• Échec du handshake Reality : dest/serverNames ne correspondent pas, ou un autre service occupe déjà 443.
• CPU élevé : trop d’inbounds sur une offre 1 vCPU, ou un scan/flood sur un port ouvert — vérifiez ss et le compteur en ligne du panneau.

Notes de sécurité qui comptent vraiment

Traitez le panneau comme un logiciel d’administration de production. Il peut créer de nouveaux utilisateurs et lire chaque UUID. Limitez qui peut atteindre le port web : si vous avez une IP de bureau stable, n’autorisez que cette IP dans UFW pour 2053/tcp. SSH par clés, pas par mots de passe. N’hébergez pas de sites publics sans rapport sur la même IP si vous utilisez Reality sur 443 — des piles TLS concurrentes sur un même port sont une cause classique de pannes. Changez le mot de passe administrateur si une capture d’écran du panneau a jamais fuité dans une discussion.

• Clés SSH uniquement ; désactivez la connexion par mot de passe une fois les clés opérationnelles
• Restreignez le port du panneau dans le pare-feu lorsque c’est possible
• Sauvegardez /etc/x-ui hors du serveur selon un calendrier
• Ne partagez pas les URL d’abonnement dans des groupes Telegram publics
• Surveillez le disque : journaux et statistiques de trafic grandissent sur un inbound chargé

Conseils pratiques

• Un inbound avec beaucoup de clients est plus simple à opérer que dix inbounds presque identiques
• Nommez les clients par appareil (laptop-anna, phone-ben) pour que les graphiques de trafic aient un sens
• S’il vous faut aussi un reverse proxy pour un site, placez le site sur une autre IP ou un autre port — ne disputez pas 443 à Reality
• Après tout redémarrage de x-ui, testez un client avant de quitter la session SSH
• Lisez le journal des changements avant de mettre à jour ; évitez les sauts vers latest un vendredi soir

Vous avez désormais 3X-UI installé comme service systemd, une URL d’administration verrouillée, TLS sur le panneau, un inbound VLESS Reality, des règles de pare-feu alignées sur ces ports, et l’habitude de sauvegarder. Ajoutez des clients depuis la page inbound, importez le lien sur chaque appareil, et ne mettez à jour le panneau qu’après une sauvegarde. Si quelque chose casse, le menu x-ui sur le VPS est la voie de récupération — pas une réinstallation complète.