Skip to content

features

メンバー引き抜き

検証済みのメンバーを新しいサーバーにプルし、自動的にロールを割り当てます。OAuth2 トークンがどのようにプル、レート制限、クールダウン、フィルタ、ロールマッピング、プルワーカーを可能にするかを理解します。

概要

メンバーの引き抜きは、あなたのサーバーの1つを通して認証したメンバーを別のサーバーに追加するプロセスです。メンバーがRestore Hub経由で認証すると、guilds.join OAuth2スコープが付与され、Restore Hubがボットのあるどのサーバーにもメンバーを追加できるようになります。Pullingは、これらの保存されたトークンを使用して、メンバーをターゲットサーバーに追加し、ロールを割り当てます。

これは1回限りの同意モデルです：メンバーは認証時に承認し、DiscordのAuthorized Apps設定からいつでもアクセスを取り消すことができます。Restore Hubは同意を再度求めません。

OAuth2トークンがプリングを可能にする仕組み

メンバーが認証を完了すると、Restore HubはOAuth2アクセストークンとリフレッシュトークン（どちらもAES-256で暗号化）を保存します。アクセストークンは7日間有効です。リフレッシュトークンは30日間有効です。

プルジョブが実行されると、Restore Hubはメンバーのアクセストークンを持つguilds.joinスコープを使用して、DiscordのPUT /guilds/{guild_id}/members/{user_id}エンドポイント経由でターゲットサーバーに追加します。このエンドポイントはロール配列も受け取ることができ、参加時に即座にロールを割り当てることができます。

アクセストークンの有効期限が切れている場合、Restore Hubはプルを実行する前にリフレッシュトークンを使用して自動的にリフレッシュします。リフレッシュトークンも有効期限が切れている場合（メンバーが30日間リベリファイしていない場合）、またはメンバーがアクセスを取り消した場合、そのメンバーは「プル不可」とマークされます。

トークン・リフレッシュ・メカニズム

Restore Hubは、トークンの有効期限が切れる5分前に、積極的にトークンをリフレッシュします（TOKEN_REFRESH_BUFFER_MS = 5分）。プルジョブ中、トークンの有効期限が5分以内の場合、Restore Hubはそれを使用する前にリフレッシュします。

リフレッシュに成功すると、新しいアクセストークン、リフレッシュトークン、有効期限タイムスタンプがデータベースに保存されます（暗号化されます）。リフレッシュに失敗した場合 (ユーザがアクセスを取り消した、トークンの有効期限が切れた、Discord API のエラー) は、そのメンバーの isPullable フラグが false に設定されます。

ヒント：メンバーは、元に戻すことで「引き出し可能」ステータスを回復できます。新しい OAuth2 トークンが古いトークンを置き換えます。

プルラブル」の意味

有効で期限切れでない OAuth2 トークンがある場合、メンバーは "pullable" (isPullable = true) とマークされます。メンバーは、以下の場合に "プル可能ではない" となります：

  • アクセストークンが失効し、リフレッシュトークンも失効した（～30日経っても回復しない）
  • Discordの設定→許可されたアプリで、Restore Hubのアクセス権を剥奪した。
  • Discord APIエラーによりトークンの更新に失敗しました。
  • サーバーの所有者が手動で引き出せないようにマークしていた。

プルの開始

ダッシュボード、Discordのスラッシュコマンド、REST APIです。

  1. ダッシュボードから- ソースサーバー → メンバー → メンバーをプル に移動します。対象となるサーバーを選択し、オプションでロール、制限、フィルターを設定し、"Start Pull "をクリックします。
  2. Discordより（Premium+)- ソース・サーバーで /pull コマンドを使用します。ターゲット・サーバーIDとオプションのロールを指定します。
  3. API経由- targetGuildId、roleId、limit、preserveRoles、roleMapping、およびfilterを指定したJSONボディで/api/v1/servers/:id/pullをPOSTする。
POST /api/v1/servers/:id/pull
{
  "targetGuildId"："123456789012345678",
  "roleId"："987654321098765432",
  "limit"：500,
  "preserveRoles": false、
  "roleMapping"：{
    "111111111111111111":"222222222222222222"
  },
  "filter"：{
    "roleIds"：["333333333333333333"],
    "memberIds"：["444444444444444444"]
  }
}

レート制限

DiscordのAPIはPUT /guilds/{guild_id}/members/{user_id}エンドポイントに厳しいレート制限があります。Restore Hubは、Discordの制限内に安全に収まるように、1分あたり約50人のメンバーを処理します (PULL_RATE_LIMIT = 50)。

つまり、1,000人の会員を集めるのに約20分。5,000人のプルには約100分かかります。プルワーカーが自動的にタイミングを管理するので、Discordのレート制限を気にする必要はありません。

警告Discordのレート制限を超えると、ボットが一時的または永久にBANされる可能性があります。Restore Hubのビルトインレート制限はこれを防ぎますが、大きなプルには時間がかかることに注意してください。

プランごとのクールダウン

不正使用を防ぐため、各プランには、同じソースサーバーのプル間のクールダウン期間があります：


|---|---|
| フリー｜6時間
| プレミアム｜1時間
| ビジネス｜15分
| エンタープライズ｜クールダウンなし

ヒント：クールダウンはソースサーバー単位であり、グローバルではありません。ソースサーバーが2つある場合、Freeプランでも両方から同時に引き出すことができます。

役割マッピング

メンバをプルするとき、オプションでソース・サーバのロールをターゲット・サーバのロールにマップすることができます。これは、サーバ間でメンバのロールを保持したい場合に便利です。

roleMappingフィールドはJSONオブジェクトで、キーはソースサーバーのロールID、値はターゲットサーバーのロールIDです。メンバーがプルされると、Restore Hubはソースサーバでロールを検索し、ターゲットで対応するマッピングされたロールを割り当てます。

roleMappingを指定せずにpreserveRolesをtrueに設定すると、Restore Hubは名前によるロールの一致を試みます。両方のサーバで同じ名前のロールが自動的にマップされます。

プルフィルター

フィルタを使用して、プルに含まれるメンバーを絞り込むことができます：

| フィルター | 説明 |
|---|---|
| roleIds｜ソースサーバーで指定されたロールの少なくとも1つを持っているメンバーのみを引き出します。
| memberIds｜Discord ユーザー ID によって特定のメンバーのみを引き出します。
| limit | プルするメンバーの最大数（例：500）。設定されていない場合、すべてのプル可能なメンバーが含まれます。

プルジョブステータス

各プル・ジョブは一連のステータスを通過します。ダッシュボードまたはGET /api/v1/pulls/:idで進捗を監視できます。

| ステータス
|---|---|
| PENDING｜ ジョブが作成され、キューに入れられるのを待っている。
| QUEUED | ジョブがワーカーキューに追加され、ワーカーがそれをピックアップするのを待っている。
| RUNNING｜ワーカーがアクティブにメンバーを処理している（pullCountはリアルタイムで増加する）｜COMPLETED｜すべてのメンバーが処理された。
| COMPLETED｜ すべてのメンバーが処理された（一部は失敗またはスキップされた可能性があります）。
| FAILED｜ 重大なエラー（ボットがターゲット・サーバーから削除されたなど）により、ジョブ全体が失敗しました。
| CANCELLED | ジョブが完了する前にユーザーによってキャンセルされました。

プル・ジョブ・カウンター

プル中とプル後には、以下のカウンターが進行状況を追跡する：

  • 合計会員数- 処理されるメンバーの総数 (フィルターと制限に基づく)。
  • プルカウント- 対象サーバーに正常に追加されたメンバーの数。
  • 失敗カウント- プルできなかったメンバーの数（トークンの有効期限切れ、ユーザーがアクセスを取り消した、Discord APIエラー）。
  • スキップ回数- スキップされたメンバーの数（すでに対象サーバーにいる、対象サーバーから追放されたなど）。
  • 進歩- (pulledCount + failedCount + skippedCount) / totalMembers * 100として計算されます。

プル・ワーカー

Pullジョブは、バックグラウンドワーカー（BullMQジョブキュー）によって処理されます。ワーカーは

  • 次の保留中のプル・ジョブをデキューします。
  • ソース・サーバからプル可能なすべてのメンバをロードします (フィルタを適用します)。
  • 各メンバーについて: トークンが有効かどうかをチェックし、必要であればリフレッシュし、DiscordのAPIを呼び出して指定されたロールでターゲットサーバーに追加し、カウンターを更新します。
  • APIコールの間隔を空けることで、50/分のレート制限を尊重する。
  • エラーを潔く処理する - 1つのメンバーが失敗しても、ジョブは次のメンバーで続行される。
  • ジョブが完了すると、ジョブ・ステータスをCOMPLETEDまたはFAILEDに更新する。
  • デバッグのために、すべてのエラーを errorLog JSON フィールドに記録します。

トークンの有効期限が切れるとどうなるか

メンバーのアクセストークンが期限切れでリフレッシュトークンがまだ有効な場合、 ワーカーは自動的にトークンをリフレッシュして再試行します。リフレッシュトークンも期限切れか失効している場合、そのメンバーは pullable ではない (isPullable = false) とマークされ、failedCount にカウントされます。

トークンの有効期限切れの問題を最小限に抑えるには、メンバーに定期的なリベリファイを促すか、アラートを設定して引き出し可能なメンバーの割合を監視します。

マルチサーバープル（エンタープライズ）

Enterpriseプランでは、1回の操作で複数のソースサーバーから1つのターゲットサーバーにメンバーをプルできます。これはコミュニティの統合に便利です。複数サーバーのプルでは、個々のレート制限が尊重され、各ソースサーバーのメンバーが順次処理されます。

アラート自動プル（Business+)

Business以上では、アラート（nuke、raid、削除）を設定して、バックアップサーバーへのプルを自動的にトリガーすることができます。サーバーが危険にさらされた場合、Restore Hubは手動で操作することなく、検証済みのメンバーを安全なサーバーに自動的にプルすることができます。

メンバー引き抜き — Restore Hub Docs | Restore Hub