Add multi-guild Discord bot support with auto-setup
- Bot creates category and channels automatically when joining a server - Channel structure: info, status, alerts, updates, diskussion, requests (forum) - Add guild_settings database table for per-server configuration - Add Discord bot invite button to Dashboard - Add display settings API functions - Add comprehensive Discord bot documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Alexander Zielonka
197
docs/discord-bot.md
Normal file
197
docs/discord-bot.md
Normal file
@@ -0,0 +1,197 @@
|
||||
# Discord Bot
|
||||
|
||||
Der GSM Discord Bot bietet Live-Status-Updates für alle Gameserver direkt in Discord. Der Bot kann auf mehreren Discord-Servern gleichzeitig laufen.
|
||||
|
||||
## Features
|
||||
|
||||
- **Live-Status**: Automatisch aktualisiertes Embed mit Server-Status, Spielerzahlen und Metriken
|
||||
- **Alerts**: Benachrichtigungen wenn Server online/offline gehen oder Spieler joinen/leaven
|
||||
- **Multi-Guild**: Kann auf beliebig vielen Discord-Servern eingesetzt werden
|
||||
- **Auto-Setup**: Erstellt automatisch alle nötigen Channels beim Beitreten
|
||||
|
||||
## Bot einladen
|
||||
|
||||
### Invite-Link
|
||||
|
||||
```
|
||||
https://discord.com/oauth2/authorize?client_id=1458251194806833306&permissions=34359831568&integration_type=0&scope=bot+applications.commands
|
||||
```
|
||||
|
||||
Der Link ist auch im GSM Dashboard unter den Server-Cards verfügbar.
|
||||
|
||||
### Benötigte Permissions
|
||||
|
||||
| Permission | Verwendung |
|
||||
|------------|------------|
|
||||
| View Channels | Channels sehen |
|
||||
| Manage Channels | Channels erstellen |
|
||||
| Send Messages | Nachrichten senden |
|
||||
| Manage Messages | Eigene Nachrichten bearbeiten |
|
||||
| Embed Links | Rich Embeds für Status |
|
||||
| Read Message History | Alte Nachrichten lesen |
|
||||
| Create Public Threads | Forum-Threads erstellen |
|
||||
|
||||
## Automatisch erstellte Channel-Struktur
|
||||
|
||||
Wenn der Bot einem Server beitritt, erstellt er automatisch folgende Struktur:
|
||||
|
||||
```
|
||||
🎮 Gameserver (Kategorie)
|
||||
├── ℹ️│info - Informationen zum GSM System
|
||||
├── 📊│status - Live-Status aller Gameserver (Auto-Update)
|
||||
├── 📢│alerts - Server-Events und Spieler-Benachrichtigungen
|
||||
├── 📰│updates - Ankündigungen zu neuen Gameservern
|
||||
├── 💬│diskussion - Diskussions-Channel (User können schreiben)
|
||||
└── 💡│requests - Forum für Gameserver-Vorschläge
|
||||
```
|
||||
|
||||
### Channel-Permissions
|
||||
|
||||
| Channel | @everyone | Bot |
|
||||
|---------|-----------|-----|
|
||||
| Kategorie | Lesen | Schreiben |
|
||||
| info | Lesen | Schreiben |
|
||||
| status | Lesen | Schreiben |
|
||||
| alerts | Lesen | Schreiben |
|
||||
| updates | Lesen | Schreiben |
|
||||
| diskussion | Lesen + Schreiben | Schreiben |
|
||||
| requests | Lesen + Threads erstellen | Schreiben |
|
||||
|
||||
## Datenbank
|
||||
|
||||
### guild_settings Tabelle
|
||||
|
||||
Speichert die Channel-IDs für jeden Discord-Server:
|
||||
|
||||
```sql
|
||||
CREATE TABLE guild_settings (
|
||||
guild_id TEXT PRIMARY KEY,
|
||||
category_id TEXT,
|
||||
info_channel_id TEXT,
|
||||
status_channel_id TEXT,
|
||||
status_message_id TEXT,
|
||||
alerts_channel_id TEXT,
|
||||
updates_channel_id TEXT,
|
||||
discussion_channel_id TEXT,
|
||||
requests_channel_id TEXT,
|
||||
requests_info_thread_id TEXT,
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
|
||||
);
|
||||
```
|
||||
|
||||
### DB-Funktionen
|
||||
|
||||
In `backend/db/init.js`:
|
||||
|
||||
```javascript
|
||||
initGuildSettings() // Tabelle erstellen
|
||||
getGuildSettings(guildId) // Settings für einen Server
|
||||
getAllGuildSettings() // Alle Server-Settings
|
||||
setGuildSettings(guildId, {}) // Settings speichern
|
||||
deleteGuildSettings(guildId) // Settings löschen (bei Bot-Kick)
|
||||
```
|
||||
|
||||
## Bot-Events
|
||||
|
||||
### guildCreate
|
||||
|
||||
Wird ausgelöst wenn der Bot einem neuen Server beitritt:
|
||||
|
||||
1. Erstellt Kategorie und alle Channels
|
||||
2. Postet Info-Nachricht im `ℹ️│info` Channel
|
||||
3. Erstellt Info-Thread im `💡│requests` Forum
|
||||
4. Speichert alle Channel-IDs in der Datenbank
|
||||
5. Sendet erste Status-Nachricht
|
||||
|
||||
### guildDelete
|
||||
|
||||
Wird ausgelöst wenn der Bot von einem Server entfernt wird:
|
||||
|
||||
1. Löscht alle Settings aus der Datenbank
|
||||
|
||||
## Status-Updates
|
||||
|
||||
Der Bot aktualisiert die Status-Nachricht in allen registrierten Guilds alle 30 Sekunden:
|
||||
|
||||
```javascript
|
||||
async function updateAllGuildStatus() {
|
||||
const guilds = getAllGuildSettings();
|
||||
for (const guild of guilds) {
|
||||
await updateGuildStatus(guild);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Jeder Server bekommt ein eigenes Embed mit:
|
||||
- Server-Name und Status (Online/Offline)
|
||||
- Aktuelle Spielerzahl
|
||||
- CPU und RAM Auslastung
|
||||
- Verbindungsadresse
|
||||
|
||||
## Konfiguration
|
||||
|
||||
### Umgebungsvariablen (.env)
|
||||
|
||||
```env
|
||||
DISCORD_CLIENT_ID=1458251194806833306
|
||||
DISCORD_CLIENT_SECRET=xxx
|
||||
DISCORD_BOT_TOKEN=xxx
|
||||
DISCORD_GUILD_ID=729865854329815051 # Haupt-Server für Login
|
||||
DISCORD_ADMIN_ROLE_ID=1024693717434650736
|
||||
DISCORD_MOD_ROLE_ID=1024693170958766141
|
||||
```
|
||||
|
||||
**Hinweis**: `DISCORD_GUILD_ID` wird nur für den Discord OAuth Login verwendet, nicht für den Bot selbst.
|
||||
|
||||
### Developer Portal Einstellungen
|
||||
|
||||
1. Gehe zu https://discord.com/developers/applications
|
||||
2. Wähle die Bot-Application
|
||||
3. **Bot** Tab:
|
||||
- "Public Bot" aktivieren (damit andere einladen können)
|
||||
- Privileged Gateway Intents:
|
||||
- Server Members Intent: Optional
|
||||
- Message Content Intent: Nicht benötigt
|
||||
|
||||
## Dateien
|
||||
|
||||
| Datei | Beschreibung |
|
||||
|-------|--------------|
|
||||
| `backend/services/discordBot.js` | Bot-Logik und Event-Handler |
|
||||
| `backend/db/init.js` | Guild-Settings DB-Funktionen |
|
||||
| `frontend/src/pages/Dashboard.jsx` | Invite-Button im Dashboard |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bot erstellt keine Channels
|
||||
|
||||
- Prüfen ob Bot "Manage Channels" Permission hat
|
||||
- Prüfen ob Bot-Rolle hoch genug in der Rollen-Hierarchie ist
|
||||
|
||||
### Status-Nachricht wird nicht aktualisiert
|
||||
|
||||
```bash
|
||||
pm2 logs gameserver-backend --lines 50
|
||||
```
|
||||
|
||||
Suche nach `[DiscordBot]` Log-Einträgen.
|
||||
|
||||
### Bot aus Datenbank entfernen
|
||||
|
||||
```bash
|
||||
sqlite3 /opt/gameserver-monitor/backend/users.sqlite
|
||||
DELETE FROM guild_settings WHERE guild_id = 'xxx';
|
||||
```
|
||||
|
||||
## Login vs. Bot
|
||||
|
||||
| Feature | Login (OAuth) | Bot |
|
||||
|---------|--------------|-----|
|
||||
| Erfordert Mitgliedschaft | Haupt-Discord | Nein |
|
||||
| Server-Steuerung | Ja (je nach Rolle) | Nein |
|
||||
| Status sehen | Ja | Ja |
|
||||
| Alerts erhalten | Nein | Ja |
|
||||
| Verfügbar für | Haupt-Discord Mitglieder | Alle mit Bot |
|
||||
|
||||
Der Login zur Webapp erfordert Mitgliedschaft im Haupt-Discord-Server (DISCORD_GUILD_ID). Der Bot ist davon unabhängig und zeigt nur passive Status-Updates.
|
||||
Reference in New Issue
Block a user