Edit README.md

This commit is contained in:
Loïc 2025-10-24 07:55:38 +02:00
parent 8ffe6bc5d4
commit 2f3c8e04d2

505
README.md
View File

@ -1,435 +1,136 @@
# Bot Discord - Gestion Serveur Minecraft
Un bot Discord complet pour gérer la whitelist et le contrôle d'un serveur Minecraft hébergé sur VPS.
Ce bot Discord permet de gérer la whitelist et le contrôle d'un serveur Minecraft hébergé sur un VPS.
## 🚀 Fonctionnalités
### 🎯 Système de demandes d'accès automatique
- Message automatique avec bouton de demande d'accès
- Attribution automatique du rôle "En attente"
- Mise à jour du statut serveur toutes les 2 minutes
- Interface avec embeds et emojis personnalisés
### 👥 Gestion de la whitelist
- Ajout/suppression de joueurs avec récupération automatique d'UUID
- Rechargement automatique de la whitelist sur le serveur
- Liste des joueurs whitelistés
- Formatage correct des UUID pour Minecraft
### 🎮 Contrôle complet du serveur
- Démarrage/arrêt/redémarrage via systemctl
- Envoi de commandes directes au serveur
- Consultation des logs en temps réel
- Sauvegarde automatique du monde
- Vérification du statut en temps réel
### 🎨 Interface utilisateur
- Emojis personnalisés configurables
- Embeds Discord avec couleurs et formatage
- Messages d'erreur informatifs
- Gestion des permissions par propriétaire
## 📋 Prérequis
- **Node.js** v16+
- **Serveur Minecraft** configuré avec systemctl
- **Bot Discord** avec permissions appropriées
- **Accès sudo** sur le VPS (pour contrôle serveur)
## 🛠️ Installation
### 1. Sur votre VPS
```bash
# Cloner et installer (ou uploader vos fichiers)
cd /home/votre-user/bots/
# ... copier vos fichiers ici ...
cd mcgestionbot
npm install
```
### 2. Configuration automatique
```bash
# Génération automatique du .env
./configure.sh
# Éditer avec vos tokens Discord
nano .env
```
### 3. Lancement
```bash
# Le bot configure automatiquement tout au démarrage !
node start.js
```
**C'est tout ! 🎉** Le bot se charge de :
- ✅ Créer l'utilisateur `minecraft`
- ✅ Configurer les permissions
- ✅ Activer la whitelist dans server.properties
- ✅ Créer les dossiers nécessaires
- ✅ Configurer les sauvegardes
## 🎮 Utilisation
### Démarrage du bot
```bash
node start.js
```
### Commandes disponibles
#### `/minecraft` - Gestion du serveur (Owner only)
**Gestion whitelist :**
- `/minecraft list` - Liste des joueurs whitelistés
- `/minecraft add <pseudo>` - Ajouter un joueur
- `/minecraft remove <pseudo>` - Retirer un joueur
- `/minecraft reload` - Recharger la whitelist
**Contrôle serveur :**
- `/minecraft status` - Statut du serveur
- `/minecraft start` - Démarrer le serveur
- `/minecraft stop` - Arrêter le serveur
- `/minecraft restart` - Redémarrer le serveur
- `/minecraft logs [lines]` - Afficher les logs
- `/minecraft command <cmd>` - Envoyer une commande
- `/minecraft backup` - Sauvegarder le monde
- `/minecraft setup` - Configuration automatique du serveur
### Système de demandes automatique
Le bot gère automatiquement :
1. **Message persistant** dans le channel configuré
2. **Bouton de demande** toujours disponible
3. **Attribution du rôle** "En attente" automatique
4. **Mise à jour du statut** serveur toutes les 2 minutes
## 🎨 Personnalisation
### Emojis personnalisés
Modifiez `emojis.json` pour vos emojis :
```json
{
"online": "<:online:123456789>",
"offline": "<:offline:123456789>",
"addedWhitelist": "<:added:123456789>",
"removedWhitelist": "<:removed:123456789>",
"success": "✅",
"error": "❌",
"info": ""
}
```
## 🔧 Dépannage
### Problèmes courants
**1. "Command not found" node**
```bash
# Installer Node.js
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
```
**2. "Permission denied" systemctl**
```bash
# Configurer sudo
sudo ./setup-sudo.sh
./test-permissions.sh
```
**3. "Whitelist not enforced"**
```bash
# Vérifier server.properties
grep "enforce-whitelist" /opt/minecraft/server/server.properties
# Doit être : enforce-whitelist=true
```
**4. "UUID format incorrect"**
- Le bot formate automatiquement les UUID
- Utilise l'API Mojang pour récupérer les UUID
### Logs et debug
```bash
# Logs du bot
node start.js
# Logs du serveur Minecraft
sudo journalctl -u minecraft -f
# Test des permissions
./test-permissions.sh
# Test de la whitelist
node test-whitelist.js
```
## 📁 Structure du projet
```
mc-acces-bot/
├── start.js # Point d'entrée
├── package.json # Dépendances
├── .env # Configuration
├── emojis.json # Emojis personnalisés
├── setup-sudo.sh # Config permissions
├── test-permissions.sh # Test sudo
└── src/
├── commands/
│ └── minecraft.js # Commandes serveur
├── events/
│ ├── ready.js # Démarrage bot
│ └── interactionCreate.js # Gestion interactions
├── handlers/
│ └── interactionHandler.js # Boutons/modals
└── utils/
├── whitelistManager.js # Gestion whitelist
├── minecraftServer.js # Statut serveur
├── serverControlManager.js # Contrôle VPS
├── autoMessageManager.js # Messages auto
└── emojiManager.js # Gestion emojis
```
## 🚀 Déploiement en production
### Avec PM2 (recommandé)
```bash
# Installer PM2
npm install -g pm2
# Démarrer le bot
pm2 start start.js --name "mc-bot"
# Configurer auto-start
pm2 startup
pm2 save
```
### Avec systemctl
```bash
# Créer le service
sudo nano /etc/systemd/system/mc-bot.service
# Contenu :
[Unit]
Description=Minecraft Discord Bot
After=network.target
[Service]
Type=simple
User=loicv
WorkingDirectory=/home/loicv/Documents/Wors/mc-acces-bot
ExecStart=/usr/bin/node start.js
Restart=always
Environment=NODE_ENV=production
[Install]
WantedBy=multi-user.target
# Activer le service
sudo systemctl enable mc-bot
sudo systemctl start mc-bot
```
## 📝 Notes importantes
- **Sécurité :** Le bot a accès sudo - utilisez uniquement sur un serveur dédié
- **Permissions :** Seul le propriétaire (OWNER_ID) peut utiliser les commandes
- **Backup :** Les sauvegardes sont stockées dans `/opt/minecraft/backups/`
- **Logs :** Tous les logs sont visibles via `journalctl` et dans Discord
## 🤝 Support
En cas de problème :
1. Vérifiez les logs : `sudo journalctl -u minecraft -f`
2. Testez les permissions : `./test-permissions.sh`
3. Vérifiez la configuration : fichier `.env` complet
4. Validez le service : `sudo systemctl status minecraft`
**Important : Pour que le bot fonctionne correctement, il doit être hébergé sur le même serveur que le serveur Minecraft.**
## Fonctionnalités
### 🎮 Système de demande d'accès
- **Message simple automatique** avec bouton pour demander l'accès
- **Embed de status du serveur** mis à jour automatiquement toutes les 2 minutes
- Modal pour saisir le pseudo Minecraft
- **Attribution automatique du rôle "Waiter"** lors de la demande
- Vérification automatique si le joueur est déjà whitelisté
- Envoi de la demande au canal staff avec boutons Accept/Refuse
- **Gestion automatique des rôles** : Verified (accepté) ou suppression du Waiter (refusé)
- **Emojis personnalisés** pour tous les messages
- Système de demande d'accès automatique avec bouton et gestion des rôles
- Ajout et suppression de joueurs dans la whitelist avec récupération automatique de l'UUID
- Rechargement automatique de la whitelist sur le serveur
- Démarrage, arrêt, redémarrage du serveur Minecraft
- Envoi de commandes directes au serveur via screen
- Consultation des logs et sauvegarde du monde
- Mise à jour automatique du statut serveur dans Discord
- Interface personnalisable via emojis.json
### ⚙️ Commandes administrateur
- `/minecraft list` - Affiche la liste des joueurs whitelistés
- `/minecraft add <pseudo>` - Ajoute un joueur à la whitelist
- `/minecraft remove <pseudo>` - Retire un joueur de la whitelist
- `/minecraft status` - Affiche le statut du serveur Minecraft
- `/minecraft reload` - Instructions pour recharger la whitelist sur le serveur
- `/setup-access` - Envoie le message de demande d'accès (facultatif)
## Prérequis
- Node.js v16 ou supérieur
- Un serveur Minecraft (Fabric, Paper, Vanilla, etc.)
- Un serveur Discord et un bot Discord
- Accès sudo sur le VPS
- Le bot et le serveur Minecraft doivent être sur la même machine
## Installation
1. **Cloner le projet et installer les dépendances :**
```bash
npm install
```
1. **Cloner le projet et installer les dépendances**
```bash
git clone <repo>
cd mc-acces-bot
npm install
```
2. **Configurer le fichier .env :**
Assurez-vous que votre fichier `.env` contient toutes les variables nécessaires :
```env
TOKEN=votre_token_bot_discord
CLIENT_ID=id_du_bot
OWNER_ID=votre_id_discord
2. **Configurer le fichier .env**
- Copiez `.env.example` en `.env` et remplissez toutes les variables selon votre configuration (token Discord, IDs, chemins, etc.)
- Exemple :
```bash
cp .env.example .env
nano .env
```
SUPPORT_SERVER_ID=id_du_serveur_discord
CHANNEL_REQUEST_ACCESS_ID=id_canal_demandes_publiques
CHANNEL_ACCESS_STAFF_REQUESTS_ID=id_canal_staff_demandes
3. **Configurer le fichier emojis.json**
- Copiez `emojis.json.example` en `emojis.json` et personnalisez les valeurs si besoin.
- Exemple :
```bash
cp emojis.json.example emojis.json
nano emojis.json
```
ROLE_WAITER_ID=id_role_attente
ROLE_VERIFIED_ID=id_role_verifie
ROLE_ADMIN_ID=id_role_admin
4. **Lancer le bot**
```bash
node start.js
```
MINECRAFT_SERVER_IP=adresse:port
MINECRAFT_WHITELIST_PATH=/chemin/vers/whitelist.json
```
## Utilisation
3. **Lancer le bot :**
```bash
npm start
```
### Démarrage
Pour le développement :
```bash
npm run dev
```
- Le bot envoie automatiquement un message de demande d'accès dans le canal configuré.
- Les utilisateurs peuvent cliquer sur le bouton pour demander l'accès et remplir leur pseudo Minecraft.
- Le bot attribue le rôle "Waiter" à l'utilisateur et envoie la demande au staff.
- Le staff peut accepter ou refuser la demande via des boutons.
- Si accepté, le joueur est ajouté à la whitelist et reçoit le rôle "Verified".
- Si refusé, le rôle "Waiter" est retiré.
Pour tester le formatage UUID :
```bash
npm run test-uuid
```
### Commandes administrateur
Pour tester la connexion au serveur Minecraft :
```bash
npm run test-server
```
Seul l'utilisateur OWNER_ID peut utiliser ces commandes :
Pour tester la whitelist :
```bash
npm run test-whitelist
```
- `/minecraft list` : Affiche la liste des joueurs whitelistés
- `/minecraft add <pseudo>` : Ajoute un joueur à la whitelist
- `/minecraft remove <pseudo>` : Retire un joueur de la whitelist
- `/minecraft reload` : Recharge la whitelist sur le serveur
- `/minecraft status` : Affiche le statut du serveur Minecraft
- `/minecraft start` : Démarre le serveur Minecraft
- `/minecraft stop` : Arrête le serveur Minecraft
- `/minecraft restart` : Redémarre le serveur Minecraft
- `/minecraft logs [lines]` : Affiche les logs du serveur
- `/minecraft command <cmd>` : Envoie une commande au serveur
- `/minecraft backup` : Sauvegarde le monde du serveur
- `/minecraft setup` : Configure automatiquement le serveur pour le bot
## Structure du projet
```
├── start.js # Point d'entrée principal
├── emojis.json # Configuration des emojis personnalisés
├── src/
│ ├── commands/
│ │ ├── minecraft.js # Commandes /minecraft
│ │ └── setup-access.js # Commande /setup-access
│ ├── events/
│ │ └── ready.js # Événement de démarrage
│ ├── handlers/
│ │ ├── commandHandler.js # Chargeur de commandes
│ │ ├── eventHandler.js # Chargeur d'événements
│ │ └── interactionHandler.js # Gestionnaire d'interactions
│ └── utils/
│ ├── accessRequestManager.js # Gestionnaire de demandes d'accès
│ ├── emojiManager.js # Gestionnaire d'emojis personnalisés
│ ├── roleManager.js # Gestionnaire de rôles Discord
│ ├── minecraftServer.js # Utilitaires serveur Minecraft
│ └── whitelistManager.js # Gestionnaire de whitelist
mc-acces-bot/
├── start.js
├── package.json
├── .env.example
├── .env
├── emojis.json.example
├── emojis.json
└── src/
├── commands/
│ └── minecraft.js
├── events/
│ └── ready.js
├── handlers/
│ └── interactionHandler.js
└── utils/
├── whitelistManager.js
├── minecraftServer.js
├── serverControlManager.js
├── autoMessageManager.js
└── emojiManager.js
```
## Utilisation
## Configuration
### Configuration initiale
1. **Inviter le bot sur votre serveur** avec les permissions nécessaires
2. **Le message de demande d'accès est envoyé automatiquement** au démarrage dans le canal configuré
3. **Configurer les rôles** dans votre serveur Discord selon les IDs dans le `.env`
> ⚠️ **Note :** Il n'est plus nécessaire d'utiliser `/setup-access` manuellement. Le bot gère automatiquement l'envoi et la mise à jour du message de demande d'accès.
### Workflow des demandes
1. **Utilisateur :** Clique sur le bouton "Demander l'accès"
2. **Système :** Attribue automatiquement le rôle "Waiter" à l'utilisateur
3. **Utilisateur :** Remplit le modal avec son pseudo Minecraft
4. **Système :** Vérifie si le joueur est déjà whitelisté
5. **Système :** Envoie la demande au canal staff avec emojis personnalisés
6. **Staff :** Clique sur "Accepter" ou "Refuser"
7. **Système (si accepté) :** Ajoute le joueur à la whitelist + donne le rôle "Verified" + retire le rôle "Waiter"
8. **Système (si refusé) :** Retire simplement le rôle "Waiter"
9. **Système :** Notifie l'utilisateur par MP avec les emojis appropriés
### Commandes administrateur
Seul l'OWNER_ID peut utiliser les commandes `/minecraft` :
- **Lister les joueurs :** `/minecraft list`
- **Ajouter un joueur :** `/minecraft add pseudo:NomDuJoueur`
- **Retirer un joueur :** `/minecraft remove pseudo:NomDuJoueur`
- **Status du serveur :** `/minecraft status`
## Permissions requises
Le bot a besoin des permissions Discord suivantes :
- `Send Messages` - Envoyer des messages
- `Use Slash Commands` - Utiliser les commandes slash
- `Embed Links` - Incorporer des liens
- `Manage Messages` - Gérer les messages
- `Read Message History` - Lire l'historique des messages
- `Manage Roles` - Gérer les rôles (pour attribuer Waiter/Verified)
## Configuration des rôles
Assurez-vous que ces rôles existent sur votre serveur Discord :
- **Rôle Waiter** (`ROLE_WAITER_ID`) : Attribué automatiquement lors d'une demande
- **Rôle Verified** (`ROLE_VERIFIED_ID`) : Attribué quand l'accès est accepté
- **Rôle Admin** (`ROLE_ADMIN_ID`) : Requis pour traiter les demandes d'accès
## Notes importantes
- Le fichier `whitelist.json` doit être accessible en lecture/écriture
- Le serveur Minecraft doit être accessible pour la vérification du statut
- Les IDs Discord dans le `.env` doivent être valides
- Le bot vérifie automatiquement les pseudos via l'API Mojang
- `.env.example` contient toutes les variables à renseigner pour le bot et le serveur Minecraft.
- `emojis.json.example` contient la structure des emojis personnalisés à utiliser dans les embeds Discord.
- Adaptez les chemins, IDs et tokens à votre environnement.
## Dépannage
### Le bot ne répond pas aux commandes
- Vérifiez que le TOKEN est correct
- Vérifiez que les permissions sont accordées
- Consultez les logs dans la console
- Vérifiez que le bot et le serveur Minecraft sont sur la même machine.
- Vérifiez les permissions sudo pour les commandes systemctl et screen.
- Vérifiez que le fichier `whitelist.json` est accessible en lecture/écriture.
- Consultez les logs du bot et du serveur Minecraft pour toute erreur.
- Utilisez les scripts `test-permissions.sh` et `diagnostic.sh` pour vérifier la configuration système.
### Erreurs de whitelist
- Vérifiez le chemin vers `whitelist.json`
- Vérifiez les permissions de fichier
- Assurez-vous que le format JSON est valide
## Notes importantes
### Problèmes d'UUID
- Les UUIDs sont automatiquement formatés au bon format (avec tirets)
- Si un joueur n'est pas trouvé, vérifiez que le pseudo existe sur Minecraft
- Utilisez `npm run test-uuid` pour tester le formatage
- Format attendu: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`
- Le bot doit avoir accès aux fichiers et dossiers du serveur Minecraft.
- Les rôles Discord doivent être correctement configurés et renseignés dans `.env`.
- Le serveur Minecraft doit être lancé via screen ou systemctl selon la configuration.
- Les commandes envoyées par le bot utilisent la session screen existante.
- Pour toute modification, redémarrez le bot pour appliquer la nouvelle configuration.
### Problèmes de serveur Minecraft
- Vérifiez que l'adresse IP et le port sont corrects
- Assurez-vous que le serveur est en ligne
- Vérifiez les paramètres du pare-feu
- Utilisez `npm run test-server` pour tester la connexion
- Le timeout de connexion est de 10 secondes
## Support
### Messages automatiques
- Le message de demande d'accès est envoyé automatiquement au démarrage
- Les anciens messages sont supprimés automatiquement
- Un seul message actif est maintenu par canal
- **Le status du serveur se met à jour automatiquement toutes les 2 minutes**
### Configuration serveur Minecraft
- Assurez-vous que `white-list=true` dans server.properties
- **IMPORTANT**: `enforce-whitelist=true` doit être activé pour que la whitelist soit appliquée
- Utilisez `/whitelist reload` dans la console serveur après modifications
- Ou utilisez la commande `/minecraft reload` du bot pour avoir les instructions
En cas de problème :
- Vérifiez les logs du bot et du serveur
- Vérifiez la configuration des fichiers `.env` et `emojis.json`
- Vérifiez les permissions système