Ir para o conteúdo

Preparar e enviar o seu bot do Discord

O seu serviço de bot do Discord executa o código que enviar. A Zaroz fornece o ambiente de execução, o armazenamento persistente e a supervisão do processo que mantém o seu bot online; você fornece os ficheiros de origem do bot. Esta página explica o que acontece em cada arranque, onde os seus ficheiros devem ficar e o que muda entre os runtimes Node.js, Python, Bun, Deno, Java e Outro.

Como decorre um arranque

Sempre que o seu bot arranca (o primeiro arranque, um reinício após uma falha ou uma nova implementação), o contentor faz as mesmas três coisas, todas a partir da pasta de armazenamento do seu bot:

  1. Entra na pasta de armazenamento. É onde ficam os ficheiros que enviou e é o diretório de trabalho para tudo o resto.
  2. Executa o passo de instalação do seu runtime (por exemplo npm install no Node.js). Alguns runtimes não têm passo de instalação; consulte O que é executado em cada runtime.
  3. Executa o seu comando de arranque (por exemplo node index.js). É o processo que se mantém ativo e liga ao Discord.

Se o processo terminar, o contentor reinicia-o e o ciclo recomeça. É por isso que uma dependência danificada ou um comando de arranque errado se manifesta como um ciclo de falhas e não como um erro pontual.

Onde ficam os seus ficheiros

Os seus ficheiros têm de ficar na pasta raiz, e não dentro de uma subpasta.

Abra o separador Ficheiros do seu serviço para os enviar através do navegador, ou ligue-se por SFTP com as credenciais aí apresentadas. Em ambos os casos, a raiz do armazenamento do seu bot é /, apresentada como / Home no gestor de ficheiros. A sua estrutura deve ser assim:

/                     ← a pasta raiz, apresentada como "/ Home"
├── index.js          ← o seu ficheiro de entrada, diretamente na raiz
├── package.json
├── package-lock.json
└── src/
    └── ...

Porque também vê /data

Dentro do contentor, essa mesma pasta está montada em /data, por isso os registos e as mensagens de erro do seu bot mostram muitas vezes caminhos como /data/index.js. É o mesmo sítio: a raiz / do separador Ficheiros é /data dentro do contentor. Envie para / e o seu bot lê-a como /data.

Não coloque o seu projeto dentro de uma subpasta

O passo de instalação e o comando de arranque são executados na raiz do seu armazenamento. Se os seus ficheiros ficarem um nível abaixo, por exemplo /o-meu-bot/index.js, o comando node index.js é executado na raiz, não encontra nada e o bot entra em ciclo de falhas.

É um dos problemas mais comuns que vemos e acontece normalmente quando um .zip é extraído para uma pasta com o nome do projeto. Se isso acontecer, abra a pasta extraída no separador Ficheiros, selecione todo o conteúdo e mova-o um nível acima, para que os ficheiros fiquem diretamente em /.

Enviar um zip

Pode enviar um .zip e extraí-lo a partir do separador Ficheiros. Depois de extrair, confirme que o index.js (ou o seu ficheiro de entrada) está na raiz e não dentro de uma pasta aninhada. Não envie a pasta node_modules/: é reinstalada no servidor e apenas torna o envio mais lento.

O que é executado em cada runtime

Escolheu um runtime durante a configuração. Ele determina a imagem base, o passo de instalação e o comando de arranque predefinido. Pode consultar e alterar o runtime e o comando de arranque atuais a qualquer momento no separador Configuração.

  • Passo de instalação: npm install --if-present (ignorado se não existir package.json).
  • Comando de arranque predefinido: node index.js.
  • As dependências vêm do seu package.json. Inclua um package-lock.json para instalações reproduzíveis.
  • Comandos de arranque alternativos comuns: npm start, node bot.js, node src/index.js.
  • Passo de instalação: pip install . quando existe um pyproject.toml, caso contrário pip install -r requirements.txt.
  • Comando de arranque predefinido: python main.py.
  • Liste todas as dependências no requirements.txt com versões fixas. A cache do pip fica guardada no seu volume, por isso as dependências inalteradas não são novamente descarregadas no arranque seguinte.
  • Comandos de arranque alternativos comuns: python bot.py, python -m bot.
  • Passo de instalação: bun install --production.
  • Comando de arranque predefinido: bun run index.js.
  • As dependências vêm do seu package.json.
  • Comandos de arranque alternativos comuns: bun start, bun run src/index.ts.
  • Passo de instalação: nenhum. O Deno descarrega e coloca em cache os seus imports na primeira execução.
  • Comando de arranque predefinido: deno run --allow-all main.ts.
  • --allow-all é a opção predefinida mais simples. Restrinja-a (por exemplo --allow-net --allow-env) assim que souber de que permissões o seu bot realmente precisa.
  • Passo de instalação: nenhum. Não existe passo de compilação no servidor, por isso envie um .jar já compilado.
  • Comando de arranque predefinido: java -jar bot.jar.
  • Mude o nome do seu jar para bot.jar ou altere o comando de arranque no separador Configuração para corresponder ao seu nome de ficheiro, por exemplo java -jar o-meu-bot-1.0.jar.
  • Passo de instalação: nenhum automático. Tornamos o start.sh executável e executamo-lo.
  • Comando de arranque predefinido: ./start.sh.
  • Obtém uma shell simples: Alpine na imagem Leve e Debian na Padrão. Instale o que precisar a partir do próprio script, usando apk no Alpine ou apt-get no Debian.

Versões dos runtimes

As versões principais são fixas: Node 22, Python 3.13, Java 21 e as versões atuais de Bun/Deno. A escolha de compatibilidade (Leve ou Padrão) altera a base do sistema operativo, não a versão da linguagem. Consulte Escolher a compatibilidade certa para saber quando optar pela Padrão.

Escolher o seu comando de arranque

Durante a configuração, escolhe uma das predefinições do seu runtime ou escreve um comando personalizado. Se manteve o valor predefinido e o seu ficheiro de entrada tem outro nome, o bot não arranca.

Para o alterar mais tarde, abra o separador Configuração, atualize o comando de arranque e reinicie. O novo comando entra em vigor no arranque seguinte.

O comando de arranque é executado por uma shell na raiz do seu armazenamento, por isso a sintaxe habitual de shell funciona. Mantenha-o como um único processo em primeiro plano que se mantenha ativo: não o coloque em segundo plano com &, ou o contentor assumirá que o bot terminou e reinicia-o.

Mantenha o token do seu bot em segurança

O token do seu bot é uma palavra-passe. Quem o tiver pode controlar o seu bot.

  • Nunca escreva o token diretamente num ficheiro que possa enviar para o Git ou partilhar num pedido de suporte.
  • Leia-o a partir de uma variável de ambiente ou de um ficheiro de configuração que permaneça no servidor.
  • Se um token for exposto, reponha-o de imediato no Portal de Programadores do Discord em Bot → Reset Token e atualize-o no servidor.

Não cole o seu token em conversas nem em capturas de ecrã

O suporte nunca lhe pedirá o token do seu bot. Se precisar de ajuda, descreva antes o erro do separador Consola: não precisa de incluir o token.

O que sobrevive a um reinício

Tudo o que está na sua pasta de armazenamento é persistente. Sobrevive a reinícios, recuperações após falhas e novas implementações. Isso inclui:

  • Os ficheiros de origem que enviou.
  • As dependências instaladas (node_modules/, a cache do pip, a cache de módulos do Deno).
  • Quaisquer ficheiros que o seu bot escreva, como uma base de dados SQLite ou uma configuração JSON.

Como as dependências instaladas persistem, um arranque que falha a meio pode deixar um node_modules/ danificado (ou __pycache__/, um ambiente virtual incompleto, etc.). Se um bot continuar a falhar na instalação depois de ter corrigido a causa original:

  1. Abra o separador Ficheiros.
  2. Elimine node_modules/ (ou o diretório danificado equivalente).
  3. Reinicie. O passo de instalação reconstrói tudo de raiz.

Acompanhar o arranque

Abra o separador Consola para acompanhar um arranque em tempo real. Verá o passo de instalação a decorrer, depois o seu comando de arranque e a seguir os registos do próprio bot. Quando algo corre mal, o erro está aqui: um módulo em falta, um erro de sintaxe, um token inválido ou um comando de arranque a apontar para um ficheiro inexistente.

Corrija o problema nos seus ficheiros, reinicie, e o contentor aplica a alteração no arranque seguinte.

Passos seguintes