Skip to content

features

Tirada de miembros

Retirar miembros verificados a un nuevo servidor con asignación automática de roles. Entender cómo los tokens OAuth2 habilitan la extracción, los límites de velocidad, los enfriamientos, los filtros, la asignación de roles y el pull worker.

Visión general

La incorporación de miembros es el proceso de añadir miembros que se han verificado a través de uno de tus servidores a un servidor diferente. Cuando los miembros se verifican a través de Restore Hub, conceden el ámbito OAuth2 guilds.join, que autoriza a Restore Hub a añadirlos a cualquier servidor en el que tengas un bot. Pulling utiliza estos tokens almacenados para añadir miembros a tu servidor de destino y asignarles un rol.

Se trata de un modelo de consentimiento único: el miembro autoriza durante la verificación y puede revocar el acceso en cualquier momento a través de la configuración de aplicaciones autorizadas de Discord. Restore Hub no vuelve a solicitar el consentimiento.

Cómo los tokens OAuth2 permiten el pulling

Cuando un miembro completa la verificación, Restore Hub almacena su token de acceso OAuth2 y su token de actualización (ambos encriptados con AES-256). El token de acceso es válido durante 7 días. El token de actualización es válido durante 30 días.

Cuando se ejecuta una tarea de extracción, Restore Hub utiliza el ámbito guilds.join con el token de acceso del miembro para añadirlo al servidor de destino a través del punto final PUT /guilds/{guild_id}/members/{user_id} de Discord. Este punto final también acepta una matriz de roles, lo que permite la asignación inmediata de roles al unirse.

Si el token de acceso ha caducado, Restore Hub lo actualiza automáticamente utilizando el token de actualización antes de intentar la extracción. Si el token de actualización también ha caducado (el miembro no ha reverificado en 30 días) o el miembro ha revocado el acceso, el miembro se marca como "no extraíble".

Mecanismo de actualización de fichas

Restore Hub actualiza proactivamente los tokens 5 minutos antes de que caduquen (TOKEN_REFRESH_BUFFER_MS = 5 minutos). Durante un trabajo de extracción, si un token está a 5 minutos de caducar, Restore Hub lo actualiza antes de utilizarlo.

Cuando una actualización tiene éxito, el nuevo token de acceso, el token de actualización y la fecha de caducidad se guardan (encriptados) en la base de datos. Cuando una actualización falla (el usuario revocó el acceso, el token caducó después de la renovación, error de la API de Discord), el indicador isPullable del miembro se establece en false.

Consejo: Los miembros pueden recuperar el estado "pullable" reverificando. Los nuevos tokens OAuth2 sustituyen a los antiguos.

Qué significa "extraíble

Un miembro se marca como "pullable" (isPullable = true) cuando tiene tokens OAuth2 válidos y no caducados. Un miembro se convierte en "no extraíble" cuando:

  • Su token de acceso caducó Y el token de actualización también caducó (sin reverificación en ~30 días)
  • Revocan el acceso de Restore Hub en Ajustes de Discordia → Apps autorizadas
  • Un intento de actualización de token falló debido a un error de la API de Discord
  • El propietario del servidor los marcó manualmente como no extraíbles

Iniciar una tirada

Puedes iniciar un pull desde tres lugares: el panel de control, un comando de barra Discord o la API REST.

  1. Desde el salpicadero - Vaya a su servidor de origen → Miembros → Extraer miembros. Seleccione el servidor de destino, establezca opcionalmente un rol, un límite y filtros y, a continuación, haga clic en "Iniciar extracción".
  2. Desde Discord (Premium+) - Utilice el comando /pull en su servidor de origen. Especifique el ID del servidor de destino y el rol opcional.
  3. A través de la API - POST /api/v1/servers/:id/pull con un cuerpo JSON especificando targetGuildId, roleId, limit, preserveRoles, roleMapping y filter.
POST /api/v1/servidores/:id/pull
{
  "targetGuildId": "123456789012345678",
  "roleId": "987654321098765432",
  "limit": 500,
  "preserveRoles": false,
  "roleMapping": {
    "111111111111111111": "222222222222222222"
  },
  "filter": {
    "roleIds": ["333333333333333333"],
    "memberIds": ["444444444444444444"]
  }
}

Limitación de velocidad

La API de Discord tiene límites de velocidad estrictos en el punto final PUT /guilds/{guild_id}/members/{user_id}. Restore Hub procesa aproximadamente 50 miembros por minuto (PULL_RATE_LIMIT = 50) para mantenerse dentro de los límites de Discord.

Esto significa que una extracción de 1.000 miembros tarda aproximadamente 20 minutos. Un pull de 5.000 miembros tarda aproximadamente 100 minutos. El pull worker gestiona el tiempo automáticamente, no tienes que preocuparte por alcanzar los límites de velocidad de Discord.

Advertencia: Exceder los límites de velocidad de Discord puede resultar en que tu bot sea baneado temporal o permanentemente. El límite de velocidad integrado de Restore Hub evita esto, pero ten en cuenta que los pulls grandes llevan tiempo.

Enfriamientos por Plan

Para evitar abusos, cada plan tiene un periodo de enfriamiento entre extracciones para el mismo servidor de origen:

| Plan de enfriamiento entre tirones
|---|---|
| Gratis 6 horas
| Premium 1 hora
| Business 15 minutos
| Enterprise Sin enfriamiento

Consejo: El enfriamiento es por servidor fuente, no global. Si tienes dos servidores de origen, puedes tirar de ambos simultáneamente incluso en el plan gratuito.

Asignación de funciones

Al extraer miembros, puede asignar opcionalmente funciones del servidor de origen a funciones del servidor de destino. Esto resulta útil cuando se desea conservar las funciones de los miembros en los distintos servidores.

El campo roleMapping es un objeto JSON en el que las claves son los ID de rol del servidor de origen y los valores son los ID de rol en el servidor de destino. Cuando se extrae un miembro, Restore Hub busca sus roles en el servidor de origen y asigna los roles mapeados correspondientes en el de destino.

Si preserveRoles se establece en true sin roleMapping, Restore Hub intenta hacer coincidir los roles por nombre. Los roles con nombres idénticos en ambos servidores se asignan automáticamente.

Filtros pull

Puede restringir los miembros que se incluyen en una extracción utilizando filtros:

| Filtro Descripción
|---|---|
| RolIds: Sólo seleccionar miembros que tengan al menos uno de los roles especificados en el servidor de origen
| memberIds | Sólo extraer miembros específicos por sus IDs de usuario de Discord | | Limite | Número máximo de miembros en el servidor fuente
| límite | Número máximo de miembros que se pueden extraer (por ejemplo, 500). Si no se establece, se incluirán todos los miembros extraíbles

Extraer estados de trabajos

Cada pull job pasa por una serie de estados. Puede supervisar el progreso en el panel de control o mediante GET /api/v1/pulls/:id.

| Estado | Significado |
|---|---|
| Pendiente: Trabajo creado, a la espera de ser puesto en cola
| QUEUED | Trabajo añadido a la cola del trabajador, esperando a que un trabajador lo recoja | | RUNNING | El trabajador está procesando miembros activamente (pulledCue)
| En ejecución: el trabajador está procesando miembros activamente (PullCount aumenta en tiempo real)
| Completado Todos los miembros procesados (algunos pueden haber fallado o haber sido omitidos)
| FALLÓ | Todo el trabajo falló debido a un error crítico (por ejemplo, bot eliminado del servidor de destino)
| CANCELADO: El trabajo ha sido cancelado por el usuario antes de su finalización

Contadores Pull Job

Durante y después de una extracción, los siguientes contadores siguen el progreso:

  • totalMiembros - El número total de miembros que se procesarán (en función de los filtros y el límite).
  • pulledCount - Número de miembros añadidos correctamente al servidor de destino.
  • failedCount - Número de miembros que no se han podido extraer (token caducado, usuario que ha revocado el acceso, error de la API de Discord).
  • skippedCount - Número de miembros omitidos (ya en el servidor de destino, expulsados del servidor de destino, etc.).
  • progreso - Calculado como (pulledCount + failedCount + skippedCount) / totalMembers * 100.

El trabajador del tirón

Los trabajos pull son procesados por un trabajador en segundo plano (cola de trabajos BullMQ). El trabajador:

  • Dequeues the next pending pull job.
  • Carga todos los miembros extraíbles del servidor de origen (aplicando filtros).
  • Para cada miembro: comprueba si su token es válido, lo actualiza si es necesario, llama a la API de Discord para añadirlo al servidor de destino con el rol o roles especificados y actualiza los contadores.
  • Respeta el límite de velocidad de 50 minutos espaciando las llamadas a la API.
  • Maneja los errores con elegancia: si falla un solo miembro, el trabajo continúa con el siguiente.
  • Actualiza el estado del trabajo a COMPLETADO o FALLIDO cuando está hecho.
  • Registra todos los errores en el campo JSON errorLog para depuración.

Qué ocurre cuando caducan las fichas

Si el token de acceso de un miembro ha caducado pero su token de actualización sigue siendo válido, el trabajador actualiza automáticamente el token y vuelve a intentarlo. Si el token de actualización también ha caducado o se ha revocado, el miembro se marca como no extraíble (isPullable = false) y se cuenta en failedCount.

Para minimizar los problemas de caducidad de tokens, anime a los miembros a reverificar periódicamente, o configure alertas para controlar su porcentaje de miembros extraíbles.

Tirón multiservidor (Enterprise)

En el plan Enterprise, puede extraer miembros de varios servidores de origen a un único servidor de destino en una sola operación. Esto resulta útil para consolidar comunidades. La extracción de varios servidores respeta los límites de velocidad individuales y procesa los miembros de cada servidor de origen de forma secuencial.

Activación automática de alertas (Business+)

En Business y superiores, puede configurar alertas (nuke, raid, eliminación) para activar automáticamente una extracción a un servidor de copia de seguridad. Si su servidor se ve comprometido, Restore Hub puede empezar a extraer automáticamente sus miembros verificados a un servidor seguro sin intervención manual.

Tirada de miembros — Restore Hub Docs | Restore Hub