test 1 de la récupération de pp discord sur site web
This commit is contained in:
parent
9d0bb77225
commit
ee31269209
9 changed files with 591 additions and 0 deletions
412
BOT_DOCUMENTATION.md
Normal file
412
BOT_DOCUMENTATION.md
Normal file
|
|
@ -0,0 +1,412 @@
|
|||
# Documentation du Bot Kuby
|
||||
|
||||
## Table des matières
|
||||
1. [Présentation générale](#présentation-générale)
|
||||
2. [Architecture du bot](#architecture-du-bot)
|
||||
3. [Installation et configuration](#installation-et-configuration)
|
||||
4. [Modules et fonctionnalités](#modules-et-fonctionnalités)
|
||||
5. [Système de sécurité](#système-de-sécurité)
|
||||
6. [Gestion des tickets](#gestion-des-tickets)
|
||||
7. [Système de logs](#système-de-logs)
|
||||
8. [API REST](#api-rest)
|
||||
9. [Commandes disponibles](#commandes-disponibles)
|
||||
10. [Base de données](#base-de-données)
|
||||
11. [Dépannage](#dépannage)
|
||||
|
||||
---
|
||||
|
||||
## Présentation générale
|
||||
|
||||
Kuby est un bot Discord multifonctionnel développé en Python utilisant la bibliothèque `discord.py`. Il est conçu pour offrir une gestion complète de serveur Discord avec des fonctionnalités de modération, sécurité, gestion de tickets, et bien plus encore.
|
||||
|
||||
### Caractéristiques principales
|
||||
- **Système de whitelist** pour contrôler l'accès aux commandes
|
||||
- **Gestion de tickets** avancée avec permissions configurables
|
||||
- **Système de sécurité** anti-spam et anti-raid
|
||||
- **Logs détaillés** des activités du serveur
|
||||
- **Messages de bienvenue/départ** personnalisables
|
||||
- **Modération** avec blacklist et scan de sécurité
|
||||
- **Système de rôles automatique** pour les membres rejoignant
|
||||
- **API REST** pour intégration externe et monitoring
|
||||
|
||||
---
|
||||
|
||||
## Architecture du bot
|
||||
|
||||
### Fichiers principaux
|
||||
|
||||
#### `kuby.py` - Point d'entrée
|
||||
- Charge les variables d'environnement
|
||||
- Initialise et démarre le bot
|
||||
- Gère les erreurs critiques de démarrage
|
||||
|
||||
#### `bot.py` - Classe principale du bot
|
||||
- Définit la classe `MyBot` héritant de `commands.Bot`
|
||||
- Configure les intents Discord
|
||||
- Charge toutes les extensions/modules
|
||||
- Implémente les événements Discord principaux
|
||||
|
||||
### Structure des dossiers
|
||||
|
||||
```
|
||||
kuby/
|
||||
├── bot.py # Classe principale du bot
|
||||
├── kuby.py # Point d'entrée
|
||||
├── commandes/ # Modules de commandes
|
||||
│ ├── ticket/ # Système de tickets
|
||||
│ ├── modules_security/ # Modules de sécurité
|
||||
│ ├── whitelist.py # Gestion whitelist
|
||||
│ ├── blacklist.py # Gestion blacklist
|
||||
│ └── ...
|
||||
├── src/ # Utilitaires et core
|
||||
│ ├── api/ # API REST module
|
||||
│ │ ├── app.py # Application Flask
|
||||
│ │ ├── routes.py # Routes API
|
||||
│ │ └── config.py # Configuration API
|
||||
│ ├── logger.py # Système de logging
|
||||
│ └── advanced_logger.py # Logs avancés
|
||||
├── data/ # Données de configuration
|
||||
├── utils/ # Fonctions utilitaires
|
||||
└── requirements.txt # Dépendances Python
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Installation et configuration
|
||||
|
||||
### Prérequis
|
||||
- Python 3.8+
|
||||
- Un token de bot Discord
|
||||
|
||||
### Installation
|
||||
1. Cloner le repository
|
||||
2. Installer les dépendances :
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Configuration
|
||||
Créer un fichier `.env` avec les variables suivantes :
|
||||
```env
|
||||
# Discord Configuration
|
||||
DISCORD_TOKEN=votre_token_discord
|
||||
APPLICATION_ID=votre_id_application
|
||||
|
||||
# API Configuration
|
||||
API_HOST=127.0.0.1
|
||||
API_PORT=5000
|
||||
API_DEBUG=False
|
||||
API_SECRET_KEY=votre-cle-secrete-api
|
||||
|
||||
# Partner Server IDs (for API)
|
||||
PARTNER_IDS=111111111111111111,222222222222222222,333333333333333333
|
||||
```
|
||||
|
||||
### Dépendances principales
|
||||
- `discord.py>=2.3.0` - API Discord
|
||||
- `python-dotenv>=1.0.0` - Gestion variables d'environnement
|
||||
- `Pillow>=10.0.0` - Traitement d'images
|
||||
- `aiohttp>=3.8.0` - Requêtes HTTP asynchrones
|
||||
- `flask>=2.3.0` - Framework API REST
|
||||
- `flask-cors>=4.0.0` - Support CORS pour l'API
|
||||
|
||||
---
|
||||
|
||||
## Modules et fonctionnalités
|
||||
|
||||
### 1. Système de Whitelist (`whitelist.py`, `whitelist_monitor.py`)
|
||||
- **Fonction** : Contrôle l'accès aux commandes du bot
|
||||
- **Mécanisme** : Vérification globale avant l'exécution de toute commande
|
||||
- **Exceptions** :
|
||||
- Propriétaire du bot (bypass automatique)
|
||||
- Utilisateurs avec permissions tickets pour commandes spécifiques
|
||||
|
||||
### 2. Messages de bienvenue/départ (`welcome.py`, `goodbye.py`)
|
||||
- **Fonctionnalités** :
|
||||
- Messages personnalisables avec images
|
||||
- Templates de bannières
|
||||
- Support de polices personnalisées
|
||||
- Restauration automatique des rôles
|
||||
|
||||
### 3. Système de sécurité (`security.py`)
|
||||
- **Scan de sécurité** : Analyse des comptes suspects
|
||||
- **Gestion des menaces** : Actions automatiques configurables
|
||||
- **Logs de sécurité** : Traçabilité des incidents
|
||||
|
||||
### 4. Modules de sécurité avancés (`modules_security/`)
|
||||
- **Anti-spam** : Détection et blocage des spams
|
||||
- **Anti-raid** : Protection contre les raids massifs
|
||||
- **Logs manager** : Gestion centralisée des logs
|
||||
- **Rules** : Gestion des règles du serveur
|
||||
|
||||
### 5. Gestion des tickets (`ticket/`)
|
||||
- **Création de tickets** : Interface complète pour les utilisateurs
|
||||
- **Permissions** : Système granulaire d'accès
|
||||
- **Configuration** : Paramètres par serveur
|
||||
- **Support** : Outils de modération intégrés
|
||||
|
||||
---
|
||||
|
||||
## Système de sécurité
|
||||
|
||||
### Niveaux de protection
|
||||
1. **Whitelist globale** : Contrôle d'accès aux commandes
|
||||
2. **Anti-spam** : Détection de messages répétitifs
|
||||
3. **Anti-raid** : Protection contre les arrivées massives
|
||||
4. **Scan de sécurité** : Analyse des comptes suspects
|
||||
5. **Blacklist** : Bannissement automatique
|
||||
|
||||
### Configuration de sécurité
|
||||
- Paramètres stockés par serveur
|
||||
- Actions configurables (kick, ban, avertissement)
|
||||
- Logs détaillés pour audit
|
||||
|
||||
---
|
||||
|
||||
## Gestion des tickets
|
||||
|
||||
### Fonctionnalités
|
||||
- **Création** : Interface utilisateur simple
|
||||
- **Catégories** : Organisation par type de demande
|
||||
- **Permissions** : Accès contrôlé par rôles
|
||||
- **Transcription** : Sauvegarde des conversations
|
||||
- **Statistiques** : Suivi des tickets
|
||||
|
||||
### Configuration
|
||||
```python
|
||||
# Exemple de configuration ticket
|
||||
config = {
|
||||
"category_id": 123456789,
|
||||
"support_role_id": 987654321,
|
||||
"log_channel_id": 555666777,
|
||||
"transcript_channel_id": 888999000
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## API REST
|
||||
|
||||
Le bot Kuby inclut une API REST basée sur Flask qui permet d'accéder à certaines fonctionnalités du bot via des requêtes HTTP.
|
||||
|
||||
### Configuration de l'API
|
||||
|
||||
L'API se configure via les variables d'environnement :
|
||||
- `API_HOST` : Adresse d'écoute (défaut: 127.0.0.1)
|
||||
- `API_PORT` : Port d'écoute (défaut: 5000)
|
||||
- `API_DEBUG` : Mode debug (défaut: False)
|
||||
- `API_SECRET_KEY` : Clé secrète pour la sécurité
|
||||
|
||||
### Endpoints disponibles
|
||||
|
||||
#### `GET /api/user/<user_id>`
|
||||
Retourne les informations d'un utilisateur Discord.
|
||||
|
||||
**Réponse :**
|
||||
```json
|
||||
{
|
||||
"username": "Nom d'utilisateur",
|
||||
"avatar_url": "https://cdn.discordapp.com/avatars/user_id/avatar.png"
|
||||
}
|
||||
```
|
||||
|
||||
#### `GET /api/partners`
|
||||
Retourne la liste des serveurs partenaires configurés.
|
||||
|
||||
**Réponse :**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"name": "Nom du serveur",
|
||||
"icon_url": "https://cdn.discordapp.com/icons/guild_id/icon.png",
|
||||
"member_count": 150
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### `GET /api/status`
|
||||
Retourne le statut actuel du bot.
|
||||
|
||||
**Réponse :**
|
||||
```json
|
||||
{
|
||||
"status": "online",
|
||||
"username": "Kuby",
|
||||
"guild_count": 5,
|
||||
"total_members": 1250
|
||||
}
|
||||
```
|
||||
|
||||
#### `GET /api/guilds`
|
||||
Retourne la liste des serveurs où le bot est présent.
|
||||
|
||||
**Réponse :**
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 123456789,
|
||||
"name": "Serveur Discord",
|
||||
"icon_url": "https://cdn.discordapp.com/icons/guild_id/icon.png",
|
||||
"member_count": 250,
|
||||
"owner_id": 987654321
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Utilisation
|
||||
|
||||
L'API démarre automatiquement avec le bot et est accessible sur `http://127.0.0.1:5000` par défaut.
|
||||
|
||||
**Exemple d'utilisation :**
|
||||
```bash
|
||||
# Obtenir les infos d'un utilisateur
|
||||
curl http://127.0.0.1:5000/api/user/123456789
|
||||
|
||||
# Obtenir le statut du bot
|
||||
curl http://127.0.0.1:5000/api/status
|
||||
```
|
||||
|
||||
### Sécurité
|
||||
|
||||
- L'API utilise CORS pour permettre les requêtes cross-origin
|
||||
- Les logs d'accès sont enregistrés via le système de logging du bot
|
||||
- L'API s'exécute dans un thread séparé pour ne pas bloquer le bot Discord
|
||||
|
||||
---
|
||||
|
||||
## Système de logs
|
||||
|
||||
### Types de logs
|
||||
1. **Logs standards** (`kuby_logs.log`) : Activités générales
|
||||
2. **Audit logs** (`kuby_audit.log`) : Actions de modération
|
||||
3. **Error logs** (`kuby_errors.log`) : Erreurs et exceptions
|
||||
4. **Performance logs** : Métriques de performance
|
||||
|
||||
### Fonctionnalités avancées
|
||||
- **Advanced Logger** : Suivi détaillé des événements
|
||||
- **Restauration de rôles** : Mémorisation des rôles des membres
|
||||
- **Notifications** : Messages de départ/arrivée
|
||||
- **Voice tracking** : Suivi des salons vocaux
|
||||
|
||||
---
|
||||
|
||||
## Commandes disponibles
|
||||
|
||||
### Commandes de modération
|
||||
- `!whitelist` : Gestion de la whitelist
|
||||
- `!blacklist` : Gestion de la blacklist
|
||||
- `!scan` : Analyse de sécurité
|
||||
- `!security` : Configuration sécurité
|
||||
|
||||
### Commandes de tickets
|
||||
- `!ticket` : Gestion des tickets
|
||||
- `!ticketconfig` : Configuration du système
|
||||
- `!ticketsetup` : Initialisation rapide
|
||||
|
||||
### Commandes utilitaires
|
||||
- `!snipe` : Récupération de messages supprimés
|
||||
- `!bug_report` : Rapport de bugs
|
||||
- `!sendbotmessages` : Messages automatisés
|
||||
|
||||
### Commandes de configuration
|
||||
- `!welcome` : Messages de bienvenue
|
||||
- `!goodbye` : Messages de départ
|
||||
- `!nolink` : Filtrage des liens
|
||||
|
||||
---
|
||||
|
||||
## Base de données
|
||||
|
||||
### Fichiers de données
|
||||
- `config.db` : Configuration principale (SQLite)
|
||||
- `whitelist.json` : Liste des utilisateurs autorisés
|
||||
- Données par serveur dans le dossier `data/`
|
||||
|
||||
### Structure de la base de données
|
||||
```sql
|
||||
-- Tables principales
|
||||
- guilds : Configuration par serveur
|
||||
- users : Données utilisateurs
|
||||
- tickets : Historique des tickets
|
||||
- audit_logs : Logs de modération
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dépannage
|
||||
|
||||
### Problèmes courants
|
||||
|
||||
#### Token Discord invalide
|
||||
```
|
||||
❌ Erreur: Token Discord non trouvé
|
||||
```
|
||||
**Solution** : Vérifier le fichier `.env` et le token Discord
|
||||
|
||||
#### Extensions non chargées
|
||||
```
|
||||
❌ Erreur lors du chargement de l'extension
|
||||
```
|
||||
**Solution** : Vérifier les imports et la syntaxe dans les modules
|
||||
|
||||
#### Permissions manquantes
|
||||
```
|
||||
❌ Vous n'êtes pas autorisé à utiliser cette commande
|
||||
```
|
||||
**Solution** : Ajouter l'utilisateur à la whitelist ou vérifier les permissions
|
||||
|
||||
### Logs utiles pour le dépannage
|
||||
- `kuby_errors.log` : Erreurs détaillées avec stack traces
|
||||
- `debug.log` : Informations de débogage
|
||||
- Console output : Logs en temps réel
|
||||
|
||||
### Commandes de maintenance
|
||||
```python
|
||||
# Redémarrage du bot
|
||||
!restart
|
||||
|
||||
# Vérification du statut
|
||||
!status
|
||||
|
||||
# Rechargement des modules
|
||||
!reload <module_name>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Bonnes pratiques
|
||||
|
||||
### Sécurité
|
||||
- Garder le token Discord secret
|
||||
- Utiliser la whitelist pour limiter l'accès
|
||||
- Configurer correctement les permissions
|
||||
- Surveiller régulièrement les logs
|
||||
|
||||
### Performance
|
||||
- Limiter le nombre de commandes simultanées
|
||||
- Optimiser les requêtes base de données
|
||||
- Utiliser le cache pour les données fréquemment accédées
|
||||
- Surveiller l'utilisation mémoire
|
||||
|
||||
### Maintenance
|
||||
- Sauvegarder régulièrement la base de données
|
||||
- Mettre à jour les dépendances
|
||||
- Nettoyer les anciens logs
|
||||
- Documenter les modifications
|
||||
|
||||
---
|
||||
|
||||
## Support et développement
|
||||
|
||||
### Pour obtenir de l'aide
|
||||
1. Consulter les logs d'erreurs
|
||||
2. Vérifier la configuration
|
||||
3. Tester avec des commandes simples
|
||||
4. Contacter le développeur si nécessaire
|
||||
|
||||
### Contributeurs
|
||||
Le bot Kuby est développé avec une architecture modulaire pour faciliter l'ajout de nouvelles fonctionnalités. Chaque module est indépendant et peut être maintenu séparément.
|
||||
|
||||
---
|
||||
|
||||
*Document généré automatiquement - Dernière mise à jour : 2025*
|
||||
Loading…
Add table
Add a link
Reference in a new issue