Gameur/Kuby
1
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions
Kuby/BOT_DOCUMENTATION.md

11 KiB
Raw Permalink Blame History

Documentation du Bot Kuby

Table des matières

  1. Présentation générale
  2. Architecture du bot
  3. Installation et configuration
  4. Modules et fonctionnalités
  5. Système de sécurité
  6. Gestion des tickets
  7. Système de logs
  8. API REST
  9. Commandes disponibles
  10. Base de données
  11. 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 : 
    pip install -r requirements.txt

Configuration

Créer un fichier .env avec les variables suivantes :

# 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

# 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 :

{
  "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 :

[
  {
    "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 :

{
  "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 :

[
  {
    "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 :

# 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

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

# 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