Como Configurar um Bot do Discord para Operações com Sharding em Vários Servidores

Se o seu bot do Discord está em mais de 2.500 servidores, o Discord exige o uso de sharding para manter a conexão. Sem sharding, o bot falhará ao fazer login ou desconectará com frequência por não conseguir lidar com a carga de eventos de tantos servidores. O sharding divide seu bot em vários processos independentes, ou shards, cada um lidando com um subconjunto de servidores. Este artigo explica por que o sharding é obrigatório em escala, como configurá-lo usando Discord.js ou Pycord, e o que fazer quando os shards param de responder.

Por que Bots do Discord Precisam de Sharding em Escala

A API Gateway do Discord limita quantos servidores uma única conexão de bot pode atender. Quando seu bot está em menos de 2.500 servidores, ele se conecta a uma sessão gateway e recebe todos os eventos de cada servidor. Quando o bot ultrapassa 2.500 servidores, o Discord exige sharding. O bot deve abrir várias conexões gateway, cada uma lidando com uma faixa de IDs de servidores.

A razão técnica é a taxa de transferência de eventos. Uma única conexão gateway pode processar cerca de 1.000 a 1.500 servidores antes que picos de latência e desconexões se tornem comuns. O sharding distribui a carga de eventos entre várias conexões, cada uma com seu próprio limite de taxa e cache. Sem sharding, o bot receberá um erro 4004 Disallowed Intents ao fazer login ou desconectará com um erro 1006 Abnormal Closure após alguns minutos.

Como o Discord Atribui Servidores aos Shards

O Discord usa a fórmula: shard_id = (guild_id >> 22) % num_shards. Cada servidor é permanentemente atribuído a um shard com base em seu ID. Isso significa que você não pode escolher manualmente quais servidores vão para qual shard. O número de shards é determinado dividindo o total de servidores do bot por 1.000 e arredondando para cima. Por exemplo, um bot em 6.500 servidores precisa de 7 shards.

Passos para Configurar Sharding no Discord.js v14

O Discord.js fornece a classe ShardingManager que gerencia a inicialização e comunicação entre shards. Siga estes passos para configurá-la.

1. Crie um arquivo gerenciador de shards
   Na raiz do seu projeto, crie um arquivo chamado index.js ou shard.js. Importe ShardingManager do discord.js e aponte para seu arquivo principal do bot. Exemplo: const { ShardingManager } = require('discord.js'); const manager = new ShardingManager('./bot.js', { totalShards: 'auto', token: 'SEU_TOKEN_DO_BOT' });
2. Defina totalShards como ‘auto’
   Usar 'auto' instrui o gerenciador a consultar a API do Discord para obter o número recomendado de shards com base na quantidade de servidores do seu bot. Isso é mais seguro do que definir um número fixo, pois se adapta conforme seu bot cresce.
3. Inicie todos os shards
   Chame manager.spawn() para iniciar todos os processos de shard. Use manager.on('shardCreate', shard => console.log(`Shard ${shard.id} iniciado`)); para monitorar a inicialização. O método spawn retorna uma promise que resolve quando todos os shards estiverem prontos.
4. Lide com eventos de shard no arquivo do bot
   Em bot.js, use client.shard para transmitir operações. Por exemplo, para obter o total de servidores em todos os shards: const guildCount = await client.shard.fetchClientValues('guilds.cache.size');
5. Ative as intenções de gateway corretas
   Em bot.js, defina intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildMembers, GatewayIntentBits.MessageContent]. Sem essas intenções, eventos dos servidores não alcançarão seus shards.

Usando o AutoShardedClient do Pycord

O Pycord simplifica o sharding com a classe AutoShardedClient. Nenhum arquivo gerenciador é necessário. A biblioteca detecta a quantidade necessária de shards e os inicia automaticamente.

1. Substitua discord.Client por AutoShardedClient
   Em seu arquivo principal do bot, altere client = discord.Client(intents=intents) para client = discord.AutoShardedClient(intents=intents). Todos os listeners de eventos existentes funcionam sem alterações.
2. Use métodos cientes de shard para operações globais
   Para obter o total de membros em todos os shards, chame await client.fetch_guilds().flatten() e some as contagens de membros. O Pycord lida com o roteamento de shards internamente.
3. Monitore a saúde dos shards
   Escute o evento on_shard_ready: @client.event async def on_shard_ready(shard_id): print(f'Shard {shard_id} está pronto'). Isso ajuda a detectar se um shard falha ao iniciar.

Se os Shards Pararem de Responder Após a Configuração

Um Shard Desconecta a Cada Poucos Minutos

Isso geralmente significa que o shard está atingindo o limite de taxa do Discord para conexões gateway. Cada shard tem seu próprio limite de 60 solicitações de identificação a cada 60 segundos. Se você iniciar todos os shards de uma vez, os primeiros podem esgotar seu limite. Corrija isso adicionando um atraso entre as inicializações. No Discord.js, use manager.spawn({ delay: 5500 }) para esperar 5,5 segundos entre cada inicialização de shard.

O Bot Não Responde a Comandos em Alguns Servidores

Isso acontece quando o cache do bot está incompleto em certos shards. Os shards armazenam em cache apenas os servidores atribuídos a eles. Se o seu manipulador de comandos espera dados de todos os servidores em um único processo, ele falhará. Use client.shard.broadcastEval() no Discord.js ou client.broadcast() no Pycord para executar código em todos os shards e coletar resultados.

Erro de Intenções de Gateway Após Ativar o Sharding

Se você vir um erro 4014 Disallowed Intents, significa que não ativou as intenções necessárias no Portal do Desenvolvedor Discord. Vá até sua aplicação, selecione Bot e ative Server Members Intent e Message Content Intent. Salve as alterações e reinicie todos os shards. Cada shard deve usar as mesmas intenções.

Discord.js v14 ShardingManager vs Pycord AutoShardedClient

Item	Discord.js v14 ShardingManager	Pycord AutoShardedClient
Complexidade de configuração	Requer um arquivo gerenciador separado e encaminhamento manual de eventos	Substituição de um único arquivo — nenhum gerenciador necessário
Controle do número de shards	Suporta contagem automática, manual ou dinâmica	Apenas automática — não é possível sobrescrever a contagem
Comunicação entre shards	BroadcastEval e fetchClientValues integrados	Requer requisições HTTP manuais ou um banco de dados compartilhado
Gerenciamento de limite de taxa	Opção de atraso integrada no spawn	Automático, mas sem atraso configurável
Melhor para	Bots que precisam de lógica de shard personalizada ou análises em larga escala	Bots pequenos a médios que desejam sharding rápido sem código extra

Agora você sabe como configurar sharding para seu bot do Discord em vários servidores. Comece ativando as intenções de gateway necessárias no Portal do Desenvolvedor. Em seguida, escolha entre Discord.js com ShardingManager ou Pycord com AutoShardedClient com base na sua necessidade de controle personalizado. Para bots de produção com mais de 5.000 servidores, adicione uma verificação de saúde que reinicie shards que não respondem usando a URL de retomada do shard.