Skip to content

features

Mitglied Pulling

Ziehen Sie verifizierte Mitglieder auf einen neuen Server mit automatischer Rollenzuweisung. Verstehen Sie, wie OAuth2-Tokens das Pulling, Ratenbegrenzungen, Cooldowns, Filter, Rollenzuordnung und den Pull Worker ermöglichen.

Übersicht

Beim Member Pulling werden Mitglieder, die sich über einen Ihrer Server verifiziert haben, einem anderen Server hinzugefügt. Wenn sich Mitglieder über Restore Hub verifizieren, gewähren sie den OAuth2-Bereich guilds.join, der Restore Hub autorisiert, sie zu jedem Server hinzuzufügen, auf dem Sie einen Bot haben. Pulling verwendet diese gespeicherten Token, um Mitglieder zu Ihrem Zielserver hinzuzufügen und ihnen eine Rolle zuzuweisen.

Dies ist ein einmaliges Zustimmungsmodell: Das Mitglied autorisiert während der Verifizierung und kann den Zugriff jederzeit über die Einstellungen für autorisierte Apps von Discord widerrufen. Restore Hub fragt nicht erneut nach der Zustimmung.

Wie OAuth2-Tokens das Pulling ermöglichen

Wenn ein Mitglied die Überprüfung abgeschlossen hat, speichert Restore Hub sein OAuth2-Zugangs-Token und sein Refresh-Token (beide mit AES-256 verschlüsselt). Das Zugriffstoken ist 7 Tage lang gültig. Das Aktualisierungs-Token ist 30 Tage lang gültig.

Wenn ein Pull-Auftrag ausgeführt wird, verwendet Restore Hub den Bereich guilds.join mit dem Zugriffstoken des Mitglieds, um es über den Discord-Endpunkt PUT /guilds/{guild_id}/members/{user_id} dem Zielserver hinzuzufügen. Dieser Endpunkt akzeptiert auch ein roles-Array, das eine sofortige Rollenzuweisung beim Beitritt ermöglicht.

Wenn das Zugriffs-Token abgelaufen ist, aktualisiert Restore Hub es automatisch mit dem Refresh-Token, bevor der Pull-Versuch durchgeführt wird. Wenn das Aktualisierungs-Token ebenfalls abgelaufen ist (das Mitglied hat sich seit 30 Tagen nicht mehr reverifiziert) oder das Mitglied den Zugriff widerrufen hat, wird das Mitglied als "nicht abrufbar" markiert.

Mechanismus der Token-Aktualisierung

Restore Hub aktualisiert Token proaktiv 5 Minuten vor ihrem Verfall (TOKEN_REFRESH_BUFFER_MS = 5 Minuten). Wenn ein Token während eines Pull-Jobs innerhalb von 5 Minuten abläuft, aktualisiert Restore Hub es, bevor es verwendet wird.

Wenn eine Aktualisierung erfolgreich ist, werden das neue Zugriffstoken, das Aktualisierungs-Token und der Zeitstempel des Ablaufs in der Datenbank gespeichert (verschlüsselt). Wenn eine Aktualisierung fehlschlägt (Benutzer hat den Zugriff widerrufen, Token ist nach der Erneuerung abgelaufen, Discord-API-Fehler), wird das isPullable-Flag des Mitglieds auf false gesetzt.

Tipp: Mitglieder können den Status "abrufbar" wiedererlangen, indem sie ihn erneut bestätigen. Die neuen OAuth2-Tokens ersetzen die alten.

Was bedeutet "abziehbar"?

Ein Mitglied wird als "abrufbar" markiert (isPullable = true), wenn es über gültige, nicht abgelaufene OAuth2-Tokens verfügt. Ein Mitglied wird "nicht abrufbar", wenn:

  • Ihr Zugangstoken ist abgelaufen UND das Refresh-Token ist ebenfalls abgelaufen (keine erneute Überprüfung in ~30 Tagen)
  • Sie haben den Zugriff auf Restore Hub in den Discord-Einstellungen → Autorisierte Apps widerrufen
  • Ein Token-Aktualisierungsversuch ist aufgrund eines Discord-API-Fehlers fehlgeschlagen
  • Sie wurden vom Eigentümer des Servers manuell als nicht abrufbar markiert

Starten eines Pulls

Sie können einen Pull von drei Stellen aus starten: dem Dashboard, einem Discord-Slash-Befehl oder der REST-API.

  1. Vom Dashboard aus - Navigieren Sie zu Ihrem Quellserver → Mitglieder → Mitglieder abrufen. Wählen Sie den Zielserver aus, legen Sie optional eine Rolle, ein Limit und Filter fest und klicken Sie dann auf "Start Pull".
  2. Von Discord (Premium+) - Verwenden Sie den Befehl /pull auf Ihrem Quellserver. Geben Sie die Zielserver-ID und optional die Rolle an.
  3. Über die API - POST /api/v1/servers/:id/pull mit einem JSON-Körper, der targetGuildId, roleId, limit, preserveRoles, roleMapping und filter angibt.
POST /api/v1/servers/:id/pull
{
  "targetGuildId": "123456789012345678",
  "roleId": "987654321098765432",
  "limit": 500,
  "preserveRoles": false,
  "roleMapping": {
    "111111111111111111": "222222222222222222"
  },
  "filter": {
    "roleIds": ["333333333333333333"],
    "memberIds": ["444444444444444444"]
  }
}

Ratenbegrenzung

Die API von Discord hat strenge Ratenbeschränkungen für den Endpunkt PUT /guilds/{guild_id}/members/{user_id}. Restore Hub verarbeitet etwa 50 Mitglieder pro Minute (PULL_RATE_LIMIT = 50), um die Grenzen von Discord einzuhalten.

Das bedeutet, dass ein Pull von 1.000 Mitgliedern etwa 20 Minuten dauert. Ein Pull von 5.000 Mitgliedern dauert etwa 100 Minuten. Der Pull-Worker verwaltet den Zeitplan automatisch - Sie müssen sich keine Sorgen machen, dass Sie die Ratenlimits von Discord erreichen.

Warnung: Das Überschreiten der Discord-Rate-Limits kann dazu führen, dass Ihr Bot vorübergehend oder dauerhaft gebannt wird. Die integrierte Ratenbegrenzung von Restore Hub verhindert dies, aber beachten Sie, dass große Pulls Zeit brauchen.

Abklingzeiten pro Plan

Um Missbrauch vorzubeugen, hat jeder Plan eine Abklingzeit zwischen Abrufen für denselben Quellserver:

| Plan | Abkühlung zwischen den Zügen |
|---|---|
| Frei | 6 Stunden |
| Premium | 1 Stunde |
| Business | 15 Minuten |
| Unternehmen | Keine Abklingzeit |

Tipp: Die Abklingzeit gilt pro Quellserver, nicht global. Wenn Sie zwei Quellserver haben, können Sie auch mit dem Free-Tarif von beiden gleichzeitig abrufen.

Rollen-Mapping

Beim Ziehen von Mitgliedern können Sie optional Rollen vom Quellserver den Rollen auf dem Zielserver zuordnen. Dies ist nützlich, wenn Sie Mitgliederrollen serverübergreifend beibehalten wollen.

Das roleMapping-Feld ist ein JSON-Objekt, dessen Schlüssel die Rollen-IDs des Quell-Servers und dessen Werte die Rollen-IDs des Ziel-Servers sind. Wenn ein Mitglied gezogen wird, sucht Restore Hub nach seinen Rollen auf dem Quellserver und weist die entsprechenden zugeordneten Rollen auf dem Zielserver zu.

Wenn preserveRoles ohne roleMapping auf true gesetzt ist, versucht Restore Hub, Rollen anhand ihres Namens abzugleichen. Rollen mit identischen Namen auf beiden Servern werden automatisch zugeordnet.

Zieh-Filter

Mit Hilfe von Filtern können Sie eingrenzen, welche Mitglieder in einem Pull enthalten sind:

| Filter | Beschreibung |
|---|---|
| roleIds | Nur Mitglieder ziehen, die mindestens eine der angegebenen Rollen auf dem Quellserver haben |
| memberIds | Nur bestimmte Mitglieder anhand ihrer Discord-Benutzer-IDs abrufen |
| limit | Maximale Anzahl der zu ziehenden Mitglieder (z.B. 500). Wenn nicht festgelegt, werden alle abrufbaren Mitglieder einbezogen

Job-Status abrufen

Jeder Pull-Auftrag durchläuft eine Reihe von Status. Sie können den Fortschritt im Dashboard oder über GET /api/v1/pulls/:id überwachen.

| Status | Bedeutung |
|---|---|
| PENDING | Auftrag erstellt, wartet auf Warteschlange |
| QUEUED | Auftrag wurde in die Warteschlange aufgenommen und wartet auf einen Arbeiter, der ihn abholt |
| RUNNING | Worker verarbeitet aktiv Mitglieder (pulledCount wird in Echtzeit erhöht) |
| COMPLETED | Alle Mitglieder verarbeitet (einige können fehlgeschlagen sein oder übersprungen worden sein) |
| FAILED | Der gesamte Auftrag ist aufgrund eines kritischen Fehlers fehlgeschlagen (z. B. Bot wurde vom Zielserver entfernt) |
| CANCELLED | Der Auftrag wurde vom Benutzer vor Abschluss abgebrochen |

Auftragszähler ziehen

Während und nach einem Abruf verfolgen die folgenden Zähler den Fortschritt:

  • totalMembers - Die Gesamtzahl der Mitglieder, die verarbeitet werden (basierend auf Filtern und Limit).
  • pulledCount - Anzahl der Mitglieder, die dem Zielserver erfolgreich hinzugefügt wurden.
  • failedCount - Anzahl der Mitglieder, die nicht abgerufen werden konnten (Token abgelaufen, Benutzer hat Zugriff widerrufen, Discord-API-Fehler).
  • skippedCount - Anzahl der übersprungenen Mitglieder (bereits auf dem Zielserver, vom Zielserver verbannt usw.).
  • fortschritte - Berechnet als (pulledCount + failedCount + skippedCount) / totalMembers * 100.

Der Pull-Worker

Pull-Aufträge werden von einem Hintergrund-Worker (BullMQ-Warteschlange) verarbeitet. Der Arbeiter:

  • Dequalifiziert den nächsten anstehenden Pull-Auftrag.
  • Lädt alle abrufbaren Mitglieder vom Quellserver (unter Anwendung von Filtern).
  • Für jedes Mitglied: prüft, ob sein Token gültig ist, aktualisiert es bei Bedarf, ruft die Discord-API auf, um es mit der/den angegebenen Rolle(n) zum Zielserver hinzuzufügen, und aktualisiert die Zähler.
  • Die 50-Minuten-Rate wird durch die Aufteilung der API-Aufrufe eingehalten.
  • Behandelt Fehler zuverlässig - wenn ein einzelnes Mitglied ausfällt, wird der Auftrag mit dem nächsten Mitglied fortgesetzt.
  • Aktualisiert den Auftragsstatus auf KOMPLETT oder FEHLGESCHLAGEN, wenn er abgeschlossen ist.
  • Protokolliert alle Fehler in das errorLog JSON-Feld zur Fehlersuche.

Was passiert, wenn Token ablaufen?

Wenn das Zugriffs-Token eines Mitglieds abgelaufen ist, das Refresh-Token aber noch gültig ist, aktualisiert der Worker das Token automatisch und versucht es erneut. Ist das Aktualisierungs-Token ebenfalls abgelaufen oder widerrufen, wird das Mitglied als nicht abrufbar markiert (isPullable = false) und in failedCount gezählt.

Um Probleme mit dem Verfall von Token zu minimieren, sollten Sie Ihre Mitglieder dazu auffordern, sich regelmäßig neu zu registrieren, oder Sie können Warnmeldungen einrichten, um den Prozentsatz Ihrer abrufbaren Mitglieder zu überwachen.

Multi-Server-Pull (Unternehmen)

Mit dem Enterprise-Plan können Sie Mitglieder von mehreren Quellservern in einem Arbeitsgang auf einen einzigen Zielserver ziehen. Dies ist nützlich für die Konsolidierung von Gemeinschaften. Der Pull-Vorgang für mehrere Server respektiert individuelle Ratenbeschränkungen und verarbeitet die Mitglieder der einzelnen Quellserver nacheinander.

Automatisches Ziehen bei Alarmen (Business+)

Ab Business können Sie Alarme (Nuke, Raid, Löschung) konfigurieren, um automatisch einen Pull auf einen Backup-Server auszulösen. Wenn Ihr Server gefährdet ist, kann Restore Hub automatisch damit beginnen, Ihre verifizierten Mitglieder auf einen sicheren Server zu ziehen, ohne dass Sie manuell eingreifen müssen.

Mitglied Pulling — Restore Hub Docs | Restore Hub