Mise à jour de la documentation
This commit is contained in:
parent
74555524b0
commit
56326530cb
1 changed files with 77 additions and 150 deletions
227
README.md
227
README.md
|
|
@ -1,153 +1,47 @@
|
||||||
# 🖥️ Discord Status Bot
|
# 🛠️ Mission : Dev GameurBot v2
|
||||||
|
## Centralisation du Monitoring et de la Gestion PM2 Sécurisée
|
||||||
|
|
||||||
Bot Discord de monitoring serveur en temps réel.
|
**Objectif :** Faire évoluer/créer un bot composé de deux éléments : un agent de télémétrie distant (`agent.py`) qui remonte les métriques du serveur, et le bot Discord principal (`bot.py`) qui gère un tableau de bord en temps réel (embed épinglé) tout en permettant aux utilisateurs autorisés de relancer des services via une passerelle Linux ultra-sécurisée.
|
||||||
Affiche et met à jour automatiquement un message épinglé dans chaque serveur Discord
|
|
||||||
avec l'état des ressources, la cause des ralentissements, et une ETA de retour à la normale.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Architecture
|
## 📐 Architecture Générale
|
||||||
|
|
||||||
```
|
```
|
||||||
[Serveur de jeux] [n'importe où]
|
[Serveur de Jeux / Minecraft] [Hébergement du Bot]
|
||||||
agent.py ──── HTTP POST ────▶ bot.py
|
agent.py (psutil) bot.py
|
||||||
(psutil) /metrics ├── serveur aiohttp (port 8765)
|
│ ├── Serveur aiohttp (Port 8765)
|
||||||
├── StatusEngine (analyse)
|
│─── HTTP POST (/metrics avec Secret) ───▶├── StatusEngine (Analyse & Seuils)
|
||||||
└── discord.py (mise à jour embed épinglé)
|
│ └── discord.py / disnake
|
||||||
│
|
│ │ (Mise à jour Embed Épinglé)
|
||||||
┌─────────┼─────────┐
|
[Wrapper Bash local & PM2] │
|
||||||
Guilde 1 Guilde 2 Guilde 3 ...
|
/usr/local/bin/manage_minecraft.sh ◀──── Applique Sudo ────────┘ (Commandes Slash /minecraft)
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Installation
|
## 1. L'Agent de Télémétrie (`agent.py`)
|
||||||
|
|
||||||
### 1. Dépendances
|
À installer sur le serveur de jeux. Il s'exécute en tâche de fond (`PUSH_INTERVAL = 15s`) pour remonter les infos systèmes au bot principal.
|
||||||
|
|
||||||
```bash
|
|
||||||
pip install -r requirements.txt
|
|
||||||
```
|
|
||||||
|
|
||||||
### 2. Configuration
|
|
||||||
|
|
||||||
```bash
|
|
||||||
cp config.example.json config.json
|
|
||||||
```
|
|
||||||
|
|
||||||
Remplis `config.json` :
|
|
||||||
|
|
||||||
| Clé | Description |
|
|
||||||
|-----------------|--------------------------------------------------------------------|
|
|
||||||
| `discord_token` | Token de ton bot (https://discord.com/developers/applications) |
|
|
||||||
| `api_secret` | Mot de passe partagé entre le bot et l'agent (chaîne aléatoire) |
|
|
||||||
| `api_port` | Port HTTP du bot (défaut : 8765) |
|
|
||||||
|
|
||||||
> ⚠️ Le même `api_secret` doit être renseigné dans `agent.py` (`API_SECRET`) et dans `config.json`.
|
|
||||||
|
|
||||||
### 3. Adapter l'agent
|
|
||||||
|
|
||||||
Dans `agent.py`, modifie :
|
|
||||||
|
|
||||||
```python
|
|
||||||
BOT_API_URL = "http://ADRESSE_DU_BOT:8765/metrics"
|
|
||||||
API_SECRET = "le_meme_secret_que_dans_config.json"
|
|
||||||
```
|
|
||||||
|
|
||||||
Si le bot et l'agent tournent sur la même machine, laisse `http://localhost:8765/metrics`.
|
|
||||||
|
|
||||||
Si le bot est sur une autre machine (VPS dédié Discord), utilise son IP/domaine.
|
|
||||||
|
|
||||||
### 4. Ajouter les mots-clés de tes services
|
|
||||||
|
|
||||||
Dans `agent.py`, `SERVICE_KEYWORDS` :
|
|
||||||
|
|
||||||
|
- **Sécurité :** Authentification obligatoire via un header contenant un `API_SECRET` partagé.
|
||||||
|
- **Filtrage des processus :** L'agent utilise `psutil` pour calculer la charge des services selon cette table de mots-clés :
|
||||||
```python
|
```python
|
||||||
SERVICE_KEYWORDS = {
|
SERVICE_KEYWORDS = {
|
||||||
"minecraft": ["java", "minecraft", "paper"],
|
"minecraft": ["java", "minecraft", "paper"],
|
||||||
"satisfactory": ["factoryserver"],
|
"satisfactory": ["factoryserver"],
|
||||||
"ollama": ["ollama"],
|
"ollama": ["ollama"],
|
||||||
# Ajoute tes propres services ici
|
|
||||||
"mon_jeu": ["mon_process_name"],
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Lancement
|
## 2. Le Bot & Serveur d'Écoute (`bot.py`)
|
||||||
|
|
||||||
### Bot (à lancer en premier)
|
Le code principal doit faire tourner un serveur Web léger (`aiohttp`) sur le port `8765` en parallèle du client Discord pour intercepter les requêtes de l'agent.
|
||||||
|
|
||||||
```bash
|
|
||||||
python bot.py
|
|
||||||
```
|
|
||||||
|
|
||||||
Ou en service systemd :
|
|
||||||
|
|
||||||
```ini
|
|
||||||
[Unit]
|
|
||||||
Description=Discord Status Bot
|
|
||||||
After=network.target
|
|
||||||
|
|
||||||
[Service]
|
|
||||||
WorkingDirectory=/chemin/vers/discord-status-bot
|
|
||||||
ExecStart=/usr/bin/python3 bot.py
|
|
||||||
Restart=always
|
|
||||||
|
|
||||||
[Install]
|
|
||||||
WantedBy=multi-user.target
|
|
||||||
```
|
|
||||||
|
|
||||||
### Agent (sur le serveur de jeux)
|
|
||||||
|
|
||||||
```bash
|
|
||||||
python agent.py
|
|
||||||
```
|
|
||||||
|
|
||||||
Idem, peut être lancé en service systemd.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Configuration Discord
|
|
||||||
|
|
||||||
### Créer le bot Discord
|
|
||||||
|
|
||||||
1. Aller sur https://discord.com/developers/applications
|
|
||||||
2. **New Application** → donne-lui un nom
|
|
||||||
3. Onglet **Bot** → **Reset Token** → copier le token dans `config.json`
|
|
||||||
4. Activer **Server Members Intent** et **Message Content Intent** si nécessaire
|
|
||||||
5. Onglet **OAuth2 > URL Generator** :
|
|
||||||
- Scopes : `bot`, `applications.commands`
|
|
||||||
- Bot Permissions : `Send Messages`, `Manage Messages`, `Embed Links`, `Read Message History`
|
|
||||||
6. Copier l'URL générée et l'ouvrir pour inviter le bot sur tes serveurs
|
|
||||||
|
|
||||||
### Configurer chaque serveur Discord
|
|
||||||
|
|
||||||
Une fois le bot invité sur un serveur et lancé localement :
|
|
||||||
|
|
||||||
1. Va dans le salon où tu veux le tableau de bord
|
|
||||||
2. Tape `/setup`
|
|
||||||
3. Le bot envoie et épingle le premier message de statut
|
|
||||||
4. Répète sur chaque serveur Discord
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Commandes slash disponibles
|
|
||||||
|
|
||||||
| Commande | Description | Permissions |
|
|
||||||
|--------------|--------------------------------------------------|-------------|
|
|
||||||
| `/status` | Affiche l'état actuel (message éphémère) | Tous |
|
|
||||||
| `/services` | Détail de chaque service détecté | Tous |
|
|
||||||
| `/setup` | Configure le salon actuel comme tableau de bord | Admin |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Personnalisation
|
|
||||||
|
|
||||||
### Seuils d'alerte
|
|
||||||
|
|
||||||
Dans `status_engine.py`, modifie `THRESHOLDS` :
|
|
||||||
|
|
||||||
|
- **Route `POST /metrics` :** Vérifie le secret. Si incorrect ──▶ renvoie un code `401`.
|
||||||
|
- **StatusEngine :** Analyse la charge selon les seuils suivants :
|
||||||
```python
|
```python
|
||||||
THRESHOLDS = {
|
THRESHOLDS = {
|
||||||
"cpu": {"warning": 70, "critical": 85},
|
"cpu": {"warning": 70, "critical": 85},
|
||||||
|
|
@ -155,38 +49,71 @@ THRESHOLDS = {
|
||||||
"swap": {"warning": 40, "critical": 70},
|
"swap": {"warning": 40, "critical": 70},
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
*Si un seuil est franchi, le bot doit automatiquement trouver le processus coupable via la table des mots-clés et générer une explication claire (ex: "CPU à 82% — principal consommateur : Minecraft").*
|
||||||
### Fréquence de mise à jour
|
|
||||||
|
|
||||||
- **Agent** → `PUSH_INTERVAL` dans `agent.py` (défaut : 15s)
|
|
||||||
- **Bot** → `@tasks.loop(seconds=20)` dans `bot.py`
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Exemple de rendu
|
## 3. La Passerelle de Gestion PM2 (Sécurité Maximale)
|
||||||
|
|
||||||
|
Pour le redémarrage des serveurs via Discord, **il est strictement interdit de manipuler directement le terminal ou d'utiliser `shell=True` / `os.system`**. Tout doit passer par ce script Bash intermédiaire à placer sur la machine dans `/usr/local/bin/manage_minecraft.sh` (Droits `755`, propriétaire `root`) :
|
||||||
|
|
||||||
|
```bash
|
||||||
|
#!/bin/bash
|
||||||
|
|
||||||
|
USER_MINECRAFT="discord"
|
||||||
|
PM2_PATH="/home/discord/.nvm/versions/node/v24.15.0/bin/pm2"
|
||||||
|
export PM2_HOME="/home/discord/.pm2"
|
||||||
|
|
||||||
|
# Whitelist stricte des applications PM2 gérables
|
||||||
|
SERVEURS_AUTORISES=("survie" "skyblock" "creatif")
|
||||||
|
|
||||||
|
ACTION=$1 # 'restart' ou 'status'
|
||||||
|
SERVEUR=$2 # ex: 'survie'
|
||||||
|
|
||||||
|
# 1. Validation de l'action
|
||||||
|
if [[ "$ACTION" != "restart" && "$ACTION" != "status" ]]; then
|
||||||
|
echo "Erreur : Action non valide." >&2
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 2. Validation du serveur (Contre les injections d'arguments ou de flags)
|
||||||
|
IN_LIST=false
|
||||||
|
for s in "${SERVEURS_AUTORISES[@]}"; do
|
||||||
|
if [[ "$s" == "$SERVEUR" ]]; then
|
||||||
|
IN_LIST=true
|
||||||
|
break
|
||||||
|
fi
|
||||||
|
done
|
||||||
|
|
||||||
|
if [ "$IN_LIST" = false ]; then
|
||||||
|
echo "Erreur : Serveur non autorisé." >&2
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# 3. Exécution propre avec switch d'utilisateur
|
||||||
|
case "$ACTION" in
|
||||||
|
restart)
|
||||||
|
sudo -u $USER_MINECRAFT $PM2_PATH restart "$SERVEUR"
|
||||||
|
;;
|
||||||
|
status)
|
||||||
|
sudo -u $USER_MINECRAFT $PM2_PATH describe "$SERVEUR"
|
||||||
|
;;
|
||||||
|
esac
|
||||||
```
|
```
|
||||||
🔴 Serveur — Surchargé
|
|
||||||
|
|
||||||
📊 Ressources
|
> ⚙️ *Note Système : L'utilisateur Linux du bot (`gameurbot`) possédera la règle `gameurbot ALL=(ALL) NOPASSWD: /usr/local/bin/manage_minecraft.sh *` dans le fichier `/etc/sudoers`.*
|
||||||
CPU ████████░░ 82% 🌡️ 74°C
|
|
||||||
RAM █████████░ 91% (14.6/16.0 GB)
|
|
||||||
SWAP ████░░░░░░ 43%
|
|
||||||
|
|
||||||
📈 Charge (1m / 5m / 15m) : 7.42 / 6.80 / 5.12
|
---
|
||||||
|
|
||||||
🎮 Services actifs
|
## 4. Interface Discord & Commandes attendues
|
||||||
▸ ⛏️ Minecraft 🔥 — CPU 45% | RAM 4.2 GB
|
|
||||||
▸ 🤖 Ollama (IA) 🔥 — CPU 38% | RAM 8.1 GB
|
|
||||||
▸ 🏭 Satisfactory ⚡ — CPU 12% | RAM 2.1 GB
|
|
||||||
|
|
||||||
🔍 Pourquoi ça rame ?
|
Tu dois implémenter ces 3 commandes d'interaction (en utilisant exclusivement des listes de choix `choices`, **aucune saisie de texte libre** pour les arguments) :
|
||||||
• CPU à 82% — principal consommateur : Minecraft (45%)
|
|
||||||
• RAM à 91% (14.6/16.0 GB) — Ollama (IA) occupe 8.1 GB
|
|
||||||
• 💡 Conflit probable : Ollama (IA) et Minecraft, Satisfactory se partagent les ressources
|
|
||||||
|
|
||||||
⏱️ Retour à la normale
|
1. `/setup` *(Admin seulement)* : Initialise le salon actuel. Le bot y envoie un Embed et l'**épingle**. C'est cet embed précis qui sera édité dynamiquement toutes les 15-20 secondes avec le rapport d'état de l'infrastructure (graphiques en barres ASCII textuelles, charge système, alertes de goulot d'étranglement).
|
||||||
⏱️ Retour à la normale dans ~8 min
|
2. `/status` *(Tous)* : Affiche le statut complet sous forme de message éphémère (invisible pour les autres joueurs).
|
||||||
|
3. `/minecraft action [choices: restart, status] serveur [choices: survie, skyblock, creatif]` :
|
||||||
|
- Exécute le script système via un appel `subprocess.run(..., shell=False)`.
|
||||||
|
- Utilise impérativement `inter.response.defer()` dès le début de la commande pour éviter les déconnexions/timeouts de 3 secondes de Discord pendant les redémarrages d'instances Java.
|
||||||
|
|
||||||
Dernière mise à jour 26/02/2026 21:34
|
### 📜 Traçabilité (Logs d'Audit)
|
||||||
```
|
Dès qu'un utilisateur clique sur une commande `/minecraft action`, le bot doit instantanément envoyer un rapport détaillé dans notre salon privé de logs administrateur : `[Audit] Qui a cliqué / Quelle heure / Quel serveur / Statut final de la commande`.
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue