Cómo Configurar una Lista Blanca Discord para tu Servidor

Audiencia: Propietarios y desarrolladores de servidores FiveM
Dificultad: Fácil → Intermedio
Resultado: Lista blanca basada en roles que utiliza roles de Discord (con lista negra opcional), mantenimiento mínimo y comentarios claros de los jugadores.

Nota sobre las versiones:El repositorio de código abierto FAXES/DiscordWhitelist Es un servicio mantenido por la comunidad y su última actualización fue en 2022. Sigue funcionando en muchos servidores. Existe una versión comercial con mantenimiento; si necesita soporte o un acuerdo de nivel de servicio (SLA), considérelo. Esta guía cubre la versión gratuita de GitHub.

Resumen

Crear un Discord Bot → habilitar Intención de los miembros del servidor → invítalo a tu Discord.
Copia tu Guild (Server) ID y ID de rol(es).
Descargar: FAXES/DiscordLista blanca en GitHub → ponerlo en resources/ → configurar server.js.
Agregar ensure DiscordWhitelist a server.cfg (o iniciar en txAdmin).
Prueba: unirse sin el rol (bloqueado) → agregar rol → volver a unirse (permitido).

Tutoriales relacionados:
• Lista blanca de FiveM: guía completa (txAdmin, scripts, base de datos)
• Cómo crear niveles de donación en Discord

¿Por qué listas blancas basadas en Discord?

Dinámica:Otorgar o denegar acceso agregando o quitando un rol de Discord (sin ediciones de ACE o DB).
Escalable:Los mods pueden administrar el acceso desde Discord en dispositivos móviles.
Auditable:El historial de roles + los registros de moderación muestran quién permitió a quién.

Prerrequisitos

Un servidor de Discord (eres administrador/propietario).
Servidor FiveM con txAdmin o control manual.
Los jugadores deben tener la Aplicación de escritorio Discord en ejecución al conectarse (por lo que FiveM expone una discord: identificador).

Paso 1: Crea un bot de Discord y habilita las intenciones

Ir a la Portal para desarrolladores de Discord → Nueva aplicación → nombrarlo (por ejemplo, FiveMX Whitelist Bot).
Agregar un bot (Pestaña del bot) → Restablecer token → copiar el Token de bot (guárdelo de forma segura).
Bajo Intenciones de puerta de enlace privilegiada, permitir Intención de los miembros del servidor. (No se requiere intención de presencia).
Invitar al bot a tu Discord: OAuth2 → Generador de URL → Ámbitos: botPermisos: mínimos (solo se permiten los de unirse). Usa la URL generada y agrégala a tu gremio.

Seguridad: Trata el token del bot como si fuera una contraseña. no Confírmalo en Git o compártelo en capturas de pantalla. Rota la información si se filtra.

Paso 2: Obtén tus identificaciones (gremio y roles)

En Discord → Configuración de usuario → Avanzado → Modo de desarrollador: EN.
Haga clic derecho en su nombre del servidor → Copiar ID del servidor.
Configuración del servidor → Roles → haga clic derecho en el rol que usará como lista blanca (por ejemplo, Whitelisted) → Copiar ID de rol.
(Opcional) Copie los ID de cualquier rol que desee lista negra (p.ej, Banned).

Tenga estos a mano:

GUILD_ID = 123456789012345678
WHITELIST_ROLE_IDS = ["111111111111111111", "222222222222222222"]
BLACKLIST_ROLE_IDS = ["333333333333333333"]

Paso 3: Descargue e instale el recurso

Descargar El código postal de Lista blanca de FAXES/Discord (GitHub).
Extraer a su servidor en:
resources/[discord]/DiscordWhitelist
Verifique que la carpeta contenga al menos:
- fxmanifest.lua
- server.js
- package.json

servidor.cfg (o txAdmin Receta / Inicio):

# Start after your identifier providers and before join‑logic that depends on it
ensure DiscordWhitelist

En txAdmin → Recursos, marca Lista blanca de Discord para iniciar al arrancar (si gestionas los recursos a través de UI).

¿Está planificando su estrategia de acceso? Lea nuestra guía más amplia: Lista blanca de FiveM: guía completa (txAdmin, scripts, base de datos) para alternativas (ACE, DB, híbrido) y cuándo utilizar cada una.

Paso 4 — Configurar `server.js`

Abierto resources/[discord]/DiscordWhitelist/server.js y configure el bloque de configuración. Es posible que el archivo ya muestre un objeto de configuración simple; ajuste los valores según corresponda. Una configuración típica se ve así:

// DiscordWhitelist configuration — example
const config = {
 botToken: "PASTE_YOUR_DISCORD_BOT_TOKEN_HERE",
 guildId: "123456789012345678", // Your server (guild) ID

 // Players must have at least ONE of these role IDs to join
 whitelistRoles: [
 "111111111111111111", // Whitelisted
 // "222222222222222222", // Staff (optional)
 ],

 // If a player has ANY of these roles, reject the connection
 blacklistRoles: [
 // "333333333333333333", // Banned
 ],

 // Cache fetched role data to reduce Discord API calls (seconds)
 cacheMaxTime: 90,

 // Deferral messages
 messages: {
 noDiscord: "Open Discord and rejoin. Your Discord app must be running.",
 notWhitelisted: "You are not whitelisted. Join our Discord: discord.gg/yourinvite",
 blacklisted: "Access denied. Please contact staff.",
 welcome: "Welcome — you are verified. Loading…"
 },
};

Consejo de monetización: Si su servidor utiliza ventajas, combine esto con Niveles de donación de Discord para automatizar los beneficios basados en roles para los simpatizantes/donantes.

Guarde el archivo.

Paso 5: reiniciar y probar

Reanudar solo el recurso o todo el servidor: txAdmin → Restart resource o consola refresh entonces restart DiscordWhitelist.
Prueba negativa:Intenta conectarte sin el rol de lista blanca → deberías ver el mensaje de aplazamiento y ser expulsado.
Prueba positiva: Concédase el rol de lista blanca → reconéctese → debería poder ingresar.

Opcional: Funciones múltiples y omisión de personal

Agregar varios roles de lista blanca para permitir múltiples embudos (por ejemplo, Donator, Police, EMS).
Agregar roles en la lista negra para bloqueos duros independientemente de la lista blanca (por ejemplo, Banned).
Puedes incluir un rol del personal en whitelistRoles para verificar el acceso de los administradores.

Consejos operativos

Automatización: Conecte la asignación de roles de Discord a su formularios de solicitud o aprobaciones de tickets (por ejemplo, con un bot, Formularios de Google → webhook → agregar rol).
Experiencia de usuario del jugador:Pincha un #how-to-whitelist Publicación con ✅ requisitos del rol y la invitación de tu servidor.
Moderación:Registrar cambios de roles en un registro privado #mod-logs canal.

Solución de problemas

“Bot desconectado” o nunca actualiza los roles

Token incorrecto o bot no invitado al gremio correcto.
Intención de los miembros del servidor no habilitado
El firewall bloquea el protocolo HTTPS saliente desde el host de tu juego (permite la API de Discord).

“No se encontró ningún identificador de Discord” / todos bloqueados

Los jugadores deben ejecutar el Aplicación de escritorio de Discord Antes de iniciar FiveM, pídeles que reinicien Discord y luego FiveM.

Los cambios de roles solo se aplican después de un reinicio

Reducir cacheMaxTime entre 30 y 60 segundos.
Si lo configura extremadamente bajo y aún ve demoras, verifique los límites de velocidad y evite reiniciar con frecuencia.

403/Error de permisos al obtener miembros del gremio

Asegúrese de que el bot esté en el gremio objetivo y La intención de los miembros del servidor está habilitada.
El bot lo hace no Necesita permisos de administrador para leer los roles de los miembros.

Alto uso de API/limitación de velocidad

Aumentar cacheMaxTime. Evite reinicios/expulsiones masivas que generan spam en las llamadas API.

Mejores prácticas de seguridad

Almacenar el Token de bot Fuera del control de versiones. Si alojas tus propias configuraciones, considera leerlas desde una variable de entorno o una variable de configuración server.cfg, no en texto plano enviado a Git.
Girar el token si se filtró.
Restringir quién tiene acceso de escritura al recurso.

Desinstalar / Deshabilitar

Eliminar ensure DiscordWhitelist de server.cfg (o deshabilitar en txAdmin → Recursos).
Eliminar la carpeta de resources/ Si lo estás desmantelando.

Preguntas frecuentes

¿Los jugadores necesitan que Discord esté en funcionamiento?
Sí. Sin el discord: Identificador, el script no puede verificar roles.

¿Qué intenciones necesito?
Solo Intención de los miembros del servidor.

¿Puedo utilizar múltiples roles de lista blanca?
Sí. Se concede acceso si el usuario tiene cualquier de los roles enumerados.

¿Puedo rechazar categóricamente ciertos roles?
Sí. Agrégalos a blacklistRoles.

Dejó de funcionar después de que cambié los roles.
Más bajo cacheMaxTimeLuego, prueba de nuevo. Asegúrate de que el bot esté conectado con el token y el gremio correctos.

¿Existe una versión mantenida?
Sí. Existe una edición comercial con mantenimiento activo si necesita actualizaciones o soporte.

Apéndice — Ejemplo `server.cfg`

# Discord whitelist
ensure DiscordWhitelist

# (Optional) put related Discord resources here as a block
# ensure discord_perms
# ensure discordrolesync

Apéndice: Ejemplo de mensajes para jugadores (aplazamientos)

Mantenga los mensajes breves y prácticos:

messages: {
 noDiscord: "Open Discord and rejoin. Your Discord app must be running.",
 notWhitelisted: "Not whitelisted. Apply in #how-to-whitelist → discord.gg/yourinvite",
 blacklisted: "Access denied. Contact staff via ticket.",
 welcome: "Verified — loading city…"
}

Registro de cambios (de cara al editor)

v1.1 — Se agregaron enlaces internos naturales a los niveles de donación, la guía completa de la lista blanca de FiveM y la descarga de GitHub.
v1.0 — Guía inicial: creación de bots, intenciones, ID, instalación, configuración, pruebas, preguntas frecuentes.