Solução de problemas

A maioria dos problemas se resume a poucas causas: versão do PHP, permissões de arquivos, credenciais do banco de dados, reescrita do servidor web ou um worker ausente. Esta página lista os sintomas mais comuns enfrentados pelos operadores e como resolver cada um. Na dúvida, o log de erros do PHP é o caminho mais rápido para a verdade.

Problemas de instalação

"Your PHP version is not supported"

TubePress requer PHP 8.2 ou superior, aplicado por um guard de versão seguro que é executado antes de qualquer outra coisa. Altere a versão do PHP no painel de hospedagem (ou aponte o vhost para um socket PHP-FPM mais recente) e recarregue. Veja Requisitos.

"Could not connect to the database"

Durante a etapa de banco de dados do instalador, verifique novamente o host (geralmente localhost ou 127.0.0.1), o nome do banco de dados, o usuário e a senha, e se o usuário tem privilégios nesse banco de dados. O banco de dados já deve existir — o instalador cria as tabelas, não o schema em si.

O instalador não consegue gravar a configuração / erro "não gravável"

O servidor web precisa de acesso de escrita a config/ e storage/ durante a configuração. Torne esses diretórios graváveis pelo usuário PHP e tente novamente. Veja a orientação sobre permissões em Instalação.

Concluí a instalação, mas /install ainda carrega

A instalação grava config/installed.php. Se estiver ausente, o aplicativo pensa que está desinstalado; se a configuração foi concluída, esse arquivo deve existir e o instalador se bloqueia. Verifique novamente se config/ estava gravável.

O site carrega, mas as páginas retornam 404

Se a página inicial funciona, mas todas as outras URLs retornam 404, a reescrita de URL não está chegando ao controlador frontal.

• Apache — confirme que mod_rewrite está habilitado e que AllowOverride All está definido para que o .htaccess incluído seja respeitado.
• Nginx — seu location / deve passar para o controlador frontal, ex.: try_files $uri $uri/ /index.php?$query_string;. Veja Arquitetura para as notas sobre o servidor web.

Login & acesso administrativo

Não consigo encontrar o login do painel administrativo

Se você definiu uma URL administrativa personalizada por segurança, o painel não está mais em /admin — ele responde apenas no seu caminho secreto. Recupere-o na tabela settings se tiver acesso ao banco de dados. Veja Segurança.

A autenticação de dois fatores está me bloqueando

Se você perder o autenticador, desative o TOTP do usuário no banco de dados (a coluna relevante na tabela users) para recuperar o acesso e, em seguida, registre-se novamente. Detalhes em Segurança.

Uploads & mídia

Uploads grandes falham ou expiram

Aumente os limites do PHP upload_max_filesize e post_max_size, e no Nginx aumente client_max_body_size. A demo permite uploads de vários gigabytes via um alto client_max_body_size; replique isso no seu servidor para arquivos grandes.

Um vídeo não reproduz

Vídeos recém-enviados podem ainda estar em processamento até o término da transcodificação. Confirme se o formato é compatível com entrega web, se os arquivos de rendição existem no armazenamento e se o servidor envia o tipo MIME correto para .mp4/.webm. Veja Player.

Miniaturas ou pré-visualizações estão faltando

A geração de miniaturas e pré-visualizações requer a extensão GD ou Imagick (e FFmpeg para frames derivados de vídeo). Verifique se estão instalados e se uploads/ está gravável.

A transcodificação está travada

Se os jobs ficam na fila e nunca são concluídos:

• Confirme que o FFmpeg está instalado onde quer que a transcodificação seja executada (servidor local ou worker remoto).
• Se você usar servidores de transcodificação remotos, verifique se o worker está em execução e se a chave de API corresponde à configurada no painel administrativo.
• Certifique-se de que o agendador está funcionando (veja abaixo) — o despacho e a repetição de jobs são executados no pseudo-cron.

O trabalho agendado não está sendo executado

O pseudo-cron só dispara em renderizações de página. Em um site com pouco tráfego, o heartbeat o mantém ativo — certifique-se de que heartbeat_enabled está como 1. Se você o desativou, reative-o ou adicione uma entrada de cron do sistema que acesse seu site periodicamente.

O e-mail não está sendo enviado

Configure o SMTP em E-mail & notificações e use o botão integrado Enviar e-mail de teste para confirmar. Se os testes falharem, verifique o host/porta/credenciais SMTP e se o host permite e-mail de saída; para melhor entregabilidade, configure SPF/DKIM no seu domínio.

Desempenho

Para um site rápido em escala: habilite o OPcache, forneça memória suficiente ao PHP, mantenha o MySQL na mesma rede que o PHP e deixe o recálculo de CTR e outras tarefas agendadas em execução. TubePress é fornecido com os índices e jobs em chunks necessários para bibliotecas grandes — veja Manutenção.

As atualizações falham

Se uma atualização não for aplicada, confirme que os arquivos do núcleo são graváveis pelo usuário PHP e que você está no PHP 8.2+. Sempre faça backup antes de atualizar para poder reverter. Veja Atualizações.

Ainda com problemas?

Reúna a mensagem de erro exata e as linhas de log relevantes e, em seguida, abra um ticket no seu painel ou no widget de suporte no painel administrativo. Quanto mais contexto você incluir — versão do PHP, servidor web e o que estava fazendo — mais rapidamente será resolvido. Veja Anúncios & suporte.