WebDashboard DE

WebDashboard

🌐 English · Deutsch

WebDashboard ist der Companion-Cog, der Red über den Browser verwaltbar macht. Er läuft im Bot-Prozess und stellt ein kleines, sicheres JSON-RPC-Gateway auf localhost bereit, eine Integrations-Registry, die Widgets, Panels und Seiten anderer Cogs einsammelt, sowie ein persistentes Audit-Log für schreibende Aktionen. Die eigentliche Browser-Oberfläche — mit Discord-OAuth2-Login, Widget-Board und kontextuellen Panels — liegt in einem separaten Repository: PDC_Redbot_Webapp. Dieser Cog ist die Bot-Seite, die Web-App das Frontend.

Das System läuft parallel zum AAA3A Red-Web-Dashboard (die Befehlsgruppe heißt pdcdashboard, nicht dashboard), beide können also nebeneinander betrieben werden. Autor: pd-codes · benötigt Red 3.5.0+ · Status: Release.

Wie es zusammenspielt

Zwei getrennt deploybare Teile sprechen über eine Token-authentifizierte JSON-RPC-Verbindung:

Red-DiscordBot (Python)                 Web-App (Node / SvelteKit)
┌───────────────────────────┐          ┌───────────────────────────┐
│ pdc_webdashboard (dieser Cog) │  JSON-   │ SvelteKit-Server (BFF)    │
│  ├─ RPC-Gateway (aiohttp) │◄─ RPC ──►│  ├─ Discord-OAuth2        │
│  ├─ Integrations-Registry │  + WS    │  ├─ Session / Cookies     │
│  ├─ Core-Provider         │ (Token)  │  └─ RPC-Client            │
│  └─ Permission-Mapper     │          └───────────┬───────────────┘
└───────────────────────────┘                      │ HTTP/WS
┌───────────────────────────┐          ┌───────────▼───────────────┐
│ Dritt-Cogs                │          │ SPA (Svelte + Tailwind)   │
│  (DashboardIntegration)   │          │  Widget-Board / Panels    │
└───────────────────────────┘          └───────────────────────────┘

• Dieser Cog stellt das Gateway, die Registry, in die sich Cogs eintragen, und einen Permission-Mapper bereit, der einen Discord-User auf eine Red-Rechtestufe abbildet.
• Die SvelteKit-Web-App ist ein Backend-for-Frontend (BFF): Sie übernimmt Discord-OAuth2, hält die Session und ist der einzige Client, der das Gateway-Token kennt. Das Browser-SPA spricht nie direkt mit dem Bot.

Installation

[p]repo add PDC_Redbot_Cogs https://github.com/pd-codes/PDC_Redbot_Cogs
[p]cog install PDC_Redbot_Cogs pdc_webdashboard
[p]load pdc_webdashboard

[p] ist das Präfix deines Bots. Die vollständige Downloader-Anleitung findest du unter Installation. Beim Laden startet das Gateway automatisch (Autostart ist standardmäßig aktiv) auf 127.0.0.1:6970.

Einrichtung

1. Gateway prüfen

[p]pdcdashboard status

Zeigt, ob das Gateway läuft, dessen Adresse und die Anzahl registrierter Beiträge. Adresse ändern mit bind (Neustart nötig), steuern mit stop / start:

[p]pdcdashboard bind 127.0.0.1 6970
[p]pdcdashboard stop
[p]pdcdashboard start

Sicherheit: Lass das Gateway auf 127.0.0.1 gebunden. Binde es nicht direkt an 0.0.0.0 — mache es nur über einen Reverse-Proxy oder Tunnel mit TLS erreichbar.

2. Token abrufen

[p]pdcdashboard token

Das Token wird dir per DM geschickt (taucht also nie in einem Kanal auf). Nur das BFF der Web-App sollte es kennen. Falls es jemals durchsickert, erneuere es:

[p]pdcdashboard regen

regen erzeugt ein frisches Token und startet das Gateway neu — danach musst du die Web-App aktualisieren und den neuen Wert mit [p]pdcdashboard token abholen.

3. Web-App-.env konfigurieren

Im Projekt PDC_Redbot_Webapp:

GATEWAY_URL=http://127.0.0.1:6970
GATEWAY_TOKEN=<Token aus [p]pdcdashboard token>
DISCORD_CLIENT_ID=...
DISCORD_CLIENT_SECRET=...
DISCORD_REDIRECT_URI=https://deine-domain/auth/callback
SESSION_SECRET=<openssl rand -hex 32>

Die komplette Einrichtung der Web-App ist in deren eigenem Wiki dokumentiert: https://github.com/pd-codes/PDC_Redbot_Webapp/wiki.

Owner-Befehle

Die Gruppe pdcdashboard (Alias pdcdash) ist nur für den Bot-Owner.

Befehl	Funktion
[p]pdcdashboard status	Zeigt Laufstatus, Adresse (http://host:port) und die Anzahl registrierter Beiträge (sowie aus wie vielen Cogs).
[p]pdcdashboard start	Startet das Gateway.
[p]pdcdashboard stop	Stoppt das Gateway.
[p]pdcdashboard bind <host> <port>	Speichert Host und Port. Ein Reload/Neustart ist nötig, damit es wirkt.
[p]pdcdashboard token	Schickt dir das aktuelle Gateway-Token per DM (erzeugt eines, falls keines existiert).
[p]pdcdashboard regen	Erzeugt ein neues Token und startet das Gateway neu. Danach Web-App aktualisieren.

Der Name pdcdashboard ist bewusst gewählt, damit der Cog parallel zu AAA3As [p]dashboard läuft.

Das Gateway

Das Gateway ist eine aiohttp-Anwendung, standardmäßig an localhost gebunden. Es bietet sowohl eine Request/Response- als auch eine Streaming-Oberfläche:

Endpunkt	Methode	Zweck
/api/health	GET	Liveness-Probe. Liefert {"status":"ok", "bot_ready": …, "time": …} ohne Token.
/api/manifest	GET	Komfort-Spiegel von manifest.get. Benötigt das Token.
/rpc	POST	JSON-RPC 2.0 Request/Response (auch Batches). Benötigt das Token.
/rpc	GET (WebSocket)	JSON-RPC 2.0 über WS für Streams/Server-Push (Live-Logs, Stats). Authentifiziert sich im ersten connection_init-Frame.

Die Authentifizierung zwischen BFF und Gateway nutzt ein geteiltes Secret, das in konstanter Zeit verglichen wird (hmac.compare_digest). Das Token wandert im Header X-Dashboard-Token (HTTP) bzw. im connection_init-Frame (WebSocket). Jeder Endpunkt außer /api/health und dem WS-Upgrade verlangt es.

Die Web-App reicht den verifizierten Discord-User-Kontext mit (z. B. X-User-Id, X-Guild-Id); das Gateway leitet daraus die effektive Red-Rechtestufe serverseitig bei jedem Call ab. Das Frontend-Filtering ist rein kosmetisch.

Berechtigungsstufen

Der Zugriff wird auf Reds eigenes Rechtesystem abgebildet. Die Stufen sind geordnet — eine höhere Stufe erfüllt jede niedrigere.

Stufe	Erfüllt, wenn …
bot_owner	bot.is_owner(user) zutrifft.
guild_owner	Der User der Server-Owner ist (guild.owner_id == user.id).
guild_admin	Der User Reds Admin-Rolle oder die Discord-Berechtigung Server verwalten hat.
guild_mod	Der User Reds Mod-Rolle hat.
guild_member	Der User Mitglied des Servers ist.
authenticated	Der User eingeloggt ist (kein Guild-Kontext, oder kein/kein Mitglied mehr).

Tipp: Sind trotz Berechtigung keine Server oder Widgets sichtbar, aktiviere den Server Members Intent im Discord Developer Portal. Ohne ihn kennt Red die Mitglieder nicht und die Rechteauflösung fällt auf authenticated zurück.

Audit-Log

Schreibende Aktionen werden auditiert. Jeder Eintrag erfasst die Aktion, den handelnden User, den Server, eine Detail-Nutzlast und einen Zeitstempel; der Cog speichert die letzten 1000 Einträge in seiner Config. Audit-Einträge werden zusätzlich ins Bot-Log geschrieben.

Sicherheit im Überblick

• Gateway standardmäßig nur localhost; Token-Auth (konstant-Zeit) zwischen BFF und Cog.
• Discord-OAuth2 läuft im BFF; Berechtigungen werden serverseitig pro Call erzwungen.
• Cogs liefern nur deklarative Schemas (kein rohes HTML) → keine XSS-Fläche.
• Keine Geheimnisse im Frontend: Discord-Client-Secret und Gateway-Token bleiben serverseitig.

Für Entwickler

Willst du deinen eigenen Cog im Dashboard anzeigen? Siehe Dashboard Integration für den Contract (@dashboard_widget, @dashboard_panel, @dashboard_page und register_third_party). Ein fertiger Nutzer der Stats-Methoden des Gateways ist Web DashboardStats.

Verwandte Seiten

• Dashboard Integration — deinen Cog ins Board einbinden
• Web DashboardStats — Server-Statistiken für die /stats-Seite des Dashboards
• Web-App-Wiki: https://github.com/pd-codes/PDC_Redbot_Webapp/wiki
• Start