Corrigir erro 500 do servidor interno do painel Greenlight do BigBlueButton

Um 500 Internal Server Errorerro 500 significa que uma solicitação do lado do servidor falhou; não identifica qual componente falhou. Para um painel do BigBlueButton Greenlight, comece encontrando a solicitação com falha nos logs do aplicativo Greenlight. O guia de solução de problemas do BigBlueButton indica que um erro 500 provavelmente é um erro do Greenlight. A exceção é útil: se apenas alguns computadores em uma rede local a virem e o log reportar um "Erro de Host Inseguro", uma configuração de proxy do navegador pode estar envolvida.

O Greenlight v3 é a versão documentada atual e utiliza um layout de implantação diferente da versão anterior, v2. Este guia ajuda você a identificar sua versão, coletar as evidências necessárias e verificar as causas comuns em uma ordem segura. Ele pressupõe uma implantação do Greenlight baseada em Docker. Use os comandos como administrador do servidor e adapte o nome e o caminho do contêiner caso sua instalação seja diferente.

Entenda qual componente está retornando 500.

O Greenlight é o aplicativo web usado para fazer login, gerenciar salas e iniciar reuniões do BigBlueButton. Um proxy reverso , como o Nginx, recebe as solicitações do navegador e as encaminha para o Greenlight. O Greenlight, por sua vez, se comunica com a API do BigBlueButton e depende de serviços como PostgreSQL e Redis. Um erro 500 pode ter origem no Greenlight, em um proxy ou em uma dependência; reiniciar os serviços de mídia do BigBlueButton não corrigirá uma exceção de banco de dados ou de aplicativo.

Primeiramente, observe qual ação desencadeia o erro: abrir o painel de controle, fazer login, carregar uma lista de salas ou iniciar uma reunião. Registre o caminho da URL, o horário aproximado, se todos os usuários são afetados e qualquer alteração recente, como uma atualização, edição de DNS, alteração de proxy ou rotação de credenciais. Se a página inicial carregar, mas apenas uma ação retornar o erro 500, isso restringe a investigação à solicitação em questão.

Prepare-se antes de alterar qualquer coisa.

• Confirme se a imagem é bigbluebutton/greenlight:v3uma imagem v2 ou uma compilação personalizada. Não aplique as instruções da v2 à v3.
• Antes de editá-los, guarde uma cópia do arquivo Docker Compose e do arquivo de ambiente relevantes em um local seguro. Eles contêm credenciais.
• Registre o horário do erro e inspecione apenas um pequeno intervalo de logs em torno dele. Oculte senhas, tokens de acesso, segredos de API, endereços de e-mail e links de reuniões privadas antes de compartilhar os logs.
• Não execute o comando docker compose down -v, remova volumes de banco de dados ou exclua o armazenamento do Greenlight para "redefinir" o painel. Essas ações podem destruir contas, configurações ou ativos carregados.

Etapa 1: Verifique os contêineres em execução e capture a exceção.

No host Docker, liste os contêineres relacionados ao Greenlight, suas imagens e respectivos status:

sudo docker ps -a --filter name=greenlight \
  --format 'table {{.Names}}\t{{.Image}}\t{{.Status}}'

Para a instalação padrão do Greenlight v3, o contêiner do aplicativo geralmente é nomeado como greenlight-v3. Leia a saída recente dele próxima ao momento da falha:

sudo docker logs --since=15m --tail=200 greenlight-v3

Se sua instalação usa o Compose, execute `composer install` docker compose pse `composer install` docker compose logs --since=15m --tail=200a partir do diretório que contém o arquivo Compose. A instalação do BigBlueButton pode manter os arquivos da versão 3 em `/usr/ ~/greenlight-v3local/bin`; instalações independentes podem ser diferentes. Use o local e os nomes de contêiner reais informados pelo seu host. Para instalações mais antigas da versão 2, verifique o log do Rails montado, geralmente log/production.logdentro do diretório de instalação do Greenlight, ou inspecione /usr/src/app/log/production.logo arquivo `/etc/rails.d/` no contêiner, caso ele não esteja montado.

Procure pela primeira exceção no momento da requisição com falha, não apenas pela resposta final 500. Erros de conexão com o banco de dados, erros do Redis, falhas em requisições à API, erros de validação de certificado e exceções do Rails apontam para correções diferentes. Se o contêiner tiver sido encerrado, seus logs ainda podem estar disponíveis através de docker logs.

Etapa 2: Verifique a conexão do Greenlight com o BigBlueButton

Quando o painel de controle falhar ao carregar salas ou iniciar uma reunião, verifique o URL do BigBlueButton e o segredo compartilhado usados ​​pelo Greenlight. Para a versão 3, o arquivo de ambiente inclui `<env>` BIGBLUEBUTTON_ENDPOINTe `<env>` BIGBLUEBUTTON_SECRET. O endpoint deve ser o URL da API da sua implantação, não um host presumido ou um URL de reunião exclusivo para navegador. Se você usa um balanceador de carga como o Scalelite, use o endpoint e as credenciais fornecidas para essa configuração.

No servidor BigBlueButton, sudo bbb-conf --secretsão exibidos o URL e o segredo configurados. Compare-os de forma privada com os valores do Greenlight. Não cole o segredo em um ticket, transcrição de shell ou chat público. Um segredo desatualizado após uma reinstalação ou rotação de credenciais pode fazer com que as chamadas à API falhem, mesmo que o contêiner do painel esteja íntegro.

Este comando também deve ser executado sudo bbb-conf --checkno host do BigBlueButton. Ele verifica os serviços do BigBlueButton e problemas comuns de configuração; não substitui a inspeção dos logs do Greenlight. Se o Greenlight estiver em um host independente separado, este comando deve ser executado no servidor BBB onde o BigBlueButton bbb-confestá instalado.

Etapa 3: Verifique o banco de dados, o Redis e as atualizações recentes.

O ambiente de exemplo do Greenlight v3 define conexões de banco de dados e cache com `--database` DATABASE_URLe REDIS_URL​​`--cache`. Confirme se os contêineres do PostgreSQL e do Redis estão em execução e se os valores no ambiente do aplicativo correspondem aos nomes de serviço, portas, nome do banco de dados e credenciais do Compose. Um contêiner do Greenlight aparentemente saudável ainda pode retornar 500 se não conseguir acessar uma dessas dependências.

Se o erro começou após uma atualização, compare a tag da imagem implantada, o arquivo Compose e o arquivo de ambiente com o procedimento de lançamento que você seguiu. Evite usar uma imagem arbitrária ou alterar manualmente o esquema do banco de dados durante o diagnóstico em produção. Faça backup do banco de dados primeiro e, em seguida, use o processo de atualização do Greenlight documentado para sua instalação. Verifique também o espaço em disco: um volume cheio pode impedir gravações no PostgreSQL, gravações de logs ou atualizações no armazenamento de ativos.

Etapa 4: Verifique as configurações de proxy, nome do host e subcaminho.

Se o erro aparecer apenas no nome de host público, verifique o caminho do navegador até o Greenlight através do proxy reverso. Confirme se o proxy está encaminhando para a porta interna correta e preservando os cabeçalhos de host e protocolo esperados. Teste a configuração do proxy antes de recarregar o Nginx com `nginx reset` sudo nginx -t, e então inspecione o log de erros do proxy no horário correspondente.

Por padrão, o Greenlight v3 espera ser executado no diretório raiz. Se for publicado em um caminho como `/var/www/html` /gl, suas RELATIVE_URL_ROOTregras de proxy reverso e de URL relativa devem ser compatíveis. O guia de instalação oficial afirma que uma alteração na raiz da URL relativa requer uma atualização/reconfiguração por meio do procedimento de instalação; definir uma variável de ambiente por si só não corrige uma incompatibilidade em uma implantação existente. Uma incompatibilidade geralmente causa redirecionamentos ou ativos quebrados, mas uma solicitação proxy com falha pode se revelar um erro de aplicativo.

BigBlueButton documenta um caso específico de LAN: se apenas alguns computadores atrás de um proxy receberem o erro 500 e o log do Greenlight contiver a mensagem "Erro de rede local (500 Error::Unsafe Host Error)", verifique se o Windows está configurado para ignorar o proxy para endereços locais ou da intranet. Este é um problema no caminho da rede do cliente, não um motivo para desativar a validação de host globalmente.

Etapa 5: Revise as alterações de autenticação e e-mail.

Se o erro 500 ocorrer durante o login, verifique as alterações recentes nas configurações do OpenID Connect, nos URLs de retorno de chamada ou no provedor de identidade. O Greenlight v3 usa valores como `<username>` OPENID_CONNECT_ISSUER, OPENID_CONNECT_CLIENT_ID`<username>` e OPENID_CONNECT_REDIRECT`<username>` quando a autenticação externa está configurada. Confirme se o URL de redirecionamento corresponde ao URL público do Greenlight, incluindo qualquer subcaminho configurado, e revise os logs do Greenlight e do provedor de identidade para verificar se o registro de data e hora coincide.

A documentação da versão 3 do Greenlight indica que o e-mail é necessário para as funcionalidades básicas da plataforma. Se o painel de controle falhar durante um convite, cadastro, redefinição de senha ou outra ação relacionada a e-mail, verifique a conectividade e as credenciais SMTP, as configurações de TLS e o log do aplicativo. Mantenha as informações SMTP confidenciais. Uma falha restrita a ações relacionadas a e-mail indica a necessidade de investigar a configuração de e-mail antes de alterar as credenciais da API do BigBlueButton.

Reinicie somente após identificar a causa provável.

Após corrigir um problema confirmado de ambiente ou proxy, reinicie o serviço Greenlight afetado usando o arquivo Compose dessa instalação. Por exemplo, a partir do diretório de instalação da versão 3:

cd ~/greenlight-v3
sudo docker compose ps
sudo docker compose restart greenlight-v3

Os nomes dos serviços do Compose podem ser diferentes dos nomes dos contêineres. Se o comando de reinicialização indicar que o serviço é desconhecido, inspecione docker compose config --servicese reinicie o serviço Greenlight listado ou use o comando de atualização documentado da implantação. Evite reiniciar o PostgreSQL ou remover volumes, a menos que os logs mostrem um problema de dependência e você tenha um plano de recuperação.

Verifique a correção e saiba quando escalar o problema.

Repita a ação exata que falhou anteriormente e verifique a resposta no navegador e no log do Greenlight no novo horário. Confirme se os usuários conseguem carregar o painel e, se a falha original envolveu uma reunião, inicie uma reunião de teste. Se bbb-conf --checka operação for bem-sucedida, mas o aplicativo ainda retornar o erro 500, isso direciona a investigação para o Greenlight, suas dependências ou o proxy.

Caso o problema persista, forneça a versão ou tag da imagem do Greenlight, o tipo de implantação, o caminho da URL afetada, o horário da falha, a exceção relevante (com informações confidenciais ocultadas), o status do contêiner e as alterações recentes. Não compartilhe arquivos de ambiente completos, segredos de API, senhas de banco de dados, cookies de sessão do usuário ou logs não editados.

Use o guia de solução de problemas do BigBlueButton para a interpretação oficial dos erros 500 e a documentação de instalação e configuração do Greenlight v3 para o modelo de implantação atual da v3. O arquivo de ambiente de exemplo do Greenlight v3 do projeto lista as variáveis ​​de ambiente suportadas. O Greenlight v2 e a v3 são diferentes, portanto, use a documentação que corresponda à sua versão implantada.