NodaroAccount
Docs do Nodaro
DocumentaçãoReferência de nósModelosTemplatesAgentes de IA (MCP)DesenvolvedoresAuto-hospedagemPesquisaComparações

Solução de problemas

Resolva problemas do Nodaro auto-hospedado a partir de /setup: sintomas e correções de inicialização, portas, CORS, migrações, armazenamento, filas e chaves.

Esta página lista os problemas mais comuns de um Nodaro auto-hospedado, cada um com o sintoma e a correção. Comece pela página /setup, que mostra a maioria deles de relance.

Começar por /setup

As instalações auto-hospedadas servem uma tela de integridade em tempo real em http://<your-host>/setup. Ela não exige login e só mostra se cada parte está presente e funcionando, nunca um segredo.

  • Cartões verdes ou vermelhos para o banco de dados, o Redis, o armazenamento, a chave de criptografia e as chaves de provedor. O cartão do banco de dados tem um estado próprio, migrações ausentes.
  • Uma dica em cada cartão com falha, com as variáveis a verificar.
  • Atualizações em tempo real: a página verifica de novo a cada 5 segundos.

Quando a página mostra API inacessível, o servidor web está no ar, mas a API não está respondendo. Leia os registros do contêiner com docker compose -f docker-compose.community.yml logs -f e verifique se nada bloqueia a porta 3000.

A instalação não inicia

Missing or invalid env vars na inicialização. A mensagem lista as variáveis que falharam na validação. As causas comuns são uma SUPABASE_SERVICE_ROLE_KEY vazia e um INTERNAL_ORCHESTRATOR_SECRET com menos de 32 caracteres.

port is already allocated no docker compose up. O conjunto de serviços só publica duas portas do host: a 3000, para o app, e a 9001, para o console do MinIO, esta só no loopback. O Redis e o banco de dados nunca usam uma porta do host. Mude o lado do host do mapeamento em conflito no docker-compose.community.yml, por exemplo "3001:3000". Para a porta do app, defina também PUBLIC_URL de acordo.

As migrações falharam na inicialização. O registro do app indica o arquivo exato. A API se recusa a iniciar com um banco de dados migrado pela metade. Corrija a causa e rode docker compose -f docker-compose.community.yml up de novo: os arquivos já aplicados são pulados.

password authentication failed for user "supabase_auth_admin" nos registros do serviço de login. O volume db-data é mais antigo que a configuração das roles do banco de dados, ou você mudou a POSTGRES_PASSWORD depois da primeira inicialização. As senhas das roles só acompanham a POSTGRES_PASSWORD na primeira inicialização. Apague o volume com docker compose -f docker-compose.community.yml down -v, o que apaga os seus dados, ou altere as senhas das roles manualmente como supabase_admin.

A compilação do Docker não consegue baixar ou verificar o arquivo do ffmpeg. Isso só afeta você quando compila a imagem por conta própria. O Dockerfile fixa uma compilação estática exata do ffmpeg por arquitetura, com ARG FFMPEG_TARBALL_URL_* e ARG FFMPEG_TARBALL_SHA256_*, porque o áudio e o vídeo renderizados mudam entre as versões do ffmpeg. Um download que falha ou um checksum que não confere interrompe a compilação, em vez de mudar a sua saída em silêncio. A versão fixada é uma versão de nodaroai/ffmpeg-static no GitHub: o ffmpeg original mais uma correção do agendador, compilado a partir do código-fonte, com o código-fonte e as licenças publicados ao lado. Escolha uma versão publicada e atualize tanto a URL quanto o SHA-256 para as duas arquiteturas. Trate isso como uma atualização real do ffmpeg e confira a saída renderizada depois.

A imagem leva as licenças do binário do ffmpeg em /usr/local/share/doc/ffmpeg-static/: LICENSE, SOURCE, LINK-TRACE.txt e uma pasta LICENSES/ com o texto da licença de cada biblioteca vinculada estaticamente. O binário do ffmpeg é GPL-3.0-or-later, e o código-fonte dele é publicado como arquivos da mesma versão.

O navegador mostra erros

O editor é renderizado, mas fica em branco ou mostra “Carregando…” para sempre. Abra o console do navegador.

  • Erros de CORS: veja o próximo item.
  • Erros de login: abra /config.js na sua instalação. Ele precisa indicar uma URL do Supabase que o seu navegador consiga acessar, PUBLIC_URL/supabase no conjunto de serviços incluído, e a chave anon. O contêiner grava esse arquivo na inicialização a partir de PUBLIC_URL, FRONTEND_SUPABASE_URL e SUPABASE_ANON_KEY: corrija essas variáveis e reinicie.

Erros de CORS no navegador. http://localhost:3000 e PUBLIC_URL são sempre permitidos, então você abriu o app em outra origem, como um endereço da LAN ou outra porta. Defina PUBLIC_URL com essa origem, ou liste as origens extras, separadas por vírgula, em CORS_ORIGIN, por exemplo CORS_ORIGIN=http://192.168.1.20:3000. Depois, rode docker compose -f docker-compose.community.yml up -d.

A ação Editar no NodarCut, ou Editar em um resultado de vídeo de um app, mostra um painel em vez do editor. O editor de vídeo hospedado só aceita ser incorporado a partir de http://localhost:3000. Em outra origem, rode o seu próprio editor e defina FREECUT_URL. Veja Editores de vídeo e de áudio.

A ação Editar, em um resultado de áudio, não faz nada ou mostra um painel em vez do editor. Não existe um editor de áudio hospedado. Rode o seu próprio AudioMass e defina AUDIOMASS_URL.

Banco de dados

Uma migração falha com “relation … does not exist”. Uma migração rodou fora de ordem. Aplique os arquivos de supabase/migrations/ na ordem dos nomes, por exemplo no SQL editor do Supabase. Cada um pode rodar de novo em um banco de dados em que já foi aplicado.

Um callback OAuth retorna 500. As tabelas dos apps OAuth estão faltando porque uma migração não foi aplicada. Aplique todas as migrações na ordem dos nomes dos arquivos. Veja Banco de dados.

A API reinicia em loop. Ela não consegue acessar o Postgres. Isso é esperado enquanto o banco de dados está fora do ar. Quando o Postgres voltar, rode docker compose -f docker-compose.community.yml restart nodaro.

Armazenamento

Os uploads falham no conjunto de serviços incluído. Abra o console do MinIO em http://localhost:9001. As credenciais padrão estão no arquivo do Compose.

Os uploads para o Cloudflare R2 respondem 401 ou 403. Verifique se o token de API tem a permissão Object Read & Write no bucket. Com um domínio personalizado na frente do R2, verifique também a configuração de acesso público do bucket: o Nodaro entrega ao navegador URLs públicas de mídia, então as leituras precisam funcionar sem autenticação.

Toda requisição ao armazenamento falha com um erro de autorização ou de endpoint. Defina R2_REGION como a região do armazenamento. A AWS, o DigitalOcean Spaces e um Supabase local rejeitam o padrão auto, e o erro deles não menciona a região.

Todo upload falha depois que você define STORAGE_OBJECT_ACL. As chaves do armazenamento não têm permissão para definir ACLs de objeto. Deixe a variável vazia, a menos que o seu armazenamento recuse uma política de bucket.

[storage] failed to create bucket no registro de inicialização com o R2. Inofensivo. Os tokens do R2 não podem criar buckets, e o seu já existe.

Execuções e nós

Os workflows entram na fila, mas nunca começam. Leia os registros com docker compose -f docker-compose.community.yml logs nodaro. O orquestrador pega o trabalho dele no Redis, então nada é executado quando o Redis não pode ser acessado. Verifique REDIS_URL e rode docker compose -f docker-compose.community.yml exec redis redis-cli ping, que deve responder PONG.

Um nó falha com Missing API key. O nó chama um provedor que não tem chave. Adicione a chave em /setup ou no .env. Veja Chaves de provedor.

Imagens e vídeos funcionam, mas todos os recursos de texto falham. KIE_API_BASE_URL aponta para um proxy que só encaminha os caminhos de mídia. Veja Passar o tráfego dos provedores pelo seu próprio proxy.

Colar uma chave ou conectar ao Nodaro Cloud falha com EncryptionKeyMissingError. A instalação não tem uma chave de criptografia. Com um projeto gerenciado no Supabase, defina NODARO_ENCRYPTION_KEY, com 64 caracteres hexadecimais gerados por openssl rand -hex 32.

As chaves de provedor aparecem como missing (ausente) depois de uma restauração. O banco de dados foi restaurado sem a chave de criptografia correspondente. Veja Backup e restauração.

Um nó falha com 503 nodaro_connection_required. Ele é um nó exclusivo do Nodaro, que precisa de uma conexão com o Nodaro Cloud. Veja Conectar ao Nodaro Cloud.

As execuções na nuvem falham com Token expired. O token de 90 dias da conexão expirou. Clique em Desconectar e depois em Conectar.

As execuções na nuvem falham com 402 instance_cap_reached. A instalação atingiu o limite de gastos mensal dela. Aumente o limite no app.nodaro.ai, em Cobrança › Instâncias conectadas.

Execuções saudáveis são marcadas como Execution orphaned. Duas instalações compartilham um banco de dados, com instâncias separadas do Redis. Dê a cada instalação um RUNTIME_ENV próprio. Veja Escalonamento.

O nó Renderização 3D Pro responde 503 SCENE_CAPABILITY_UNAVAILABLE. O Renderização 3D Pro roda em um serviço de compilação hospedado e não faz parte das edições auto-hospedadas. Ele nunca recorre em silêncio a outro renderizador. Use o Gerar cena 3D e o Renderizar vídeo, que rodam no seu servidor.

Login e MCP

As rotas de SSO respondem 404 unknown_provider. Nenhum provedor está configurado. Verifique EXTERNAL_SSO_PROVIDERS e, no conjunto de serviços do Compose, adicione essa variável em environment: do serviço nodaro. Veja Login único (SSO).

Toda chamada à API responde 403 sso_required. O perfil de superfície só permite SSO, e a conta não foi criada nem vinculada pelo SSO. Veja Métodos de login.

Um cliente MCP recebe 405 wrong_mcp_host. O cliente usa o endereço principal do app. Em vez dele, informe ao cliente o endereço do seu host MCP. Veja MCP.

Um cliente MCP é mandado de volta com unauthorized_client, ou recebe 403 mcp_client_not_allowed. MCP_ALLOWED_CLIENT_IDS está definida, e o cliente não está na lista. Só os apps de desenvolvedor da lista podem usar o MCP na instalação. Adicione o client_id do cliente à lista e reinicie, ou conecte-se por um cliente da lista. Veja MCP só pelo seu próprio cliente.

A API não inicia depois que você define MCP_ALLOWED_CLIENT_IDS ou MCP_ASSERTION_EXCHANGE_CLIENT_IDS. Uma entrada não é o client_id de um app de desenvolvedor (app_ e 32 caracteres hexadecimais minúsculos). Ou um cliente da troca não está em MCP_ALLOWED_CLIENT_IDS, ou nenhum provedor de SSO define um exchangeAudience. O log indica o problema. Veja A troca de asserção.

Atualizações

O rótulo da versão só mostra a versão embutida, e as notas da versão estão vazias. A verificação de atualizações não consegue ler o GitHub. A linha de registro [update-check] … read failed: HTTP 403 (rate limit: 0 of 60 left…) significa que o seu endereço de saída gastou a cota anônima do GitHub. Defina NODARO_UPDATE_CHECK_TOKEN. Veja Atualização.

Obter ajuda

Se você ainda não conseguir resolver, abra um chamado no GitHub com os registros do Docker do contêiner do app.

Perguntas frequentes

Por onde começo quando o meu Nodaro auto-hospedado apresenta problemas?

Abra /setup na sua instalação. A página mostra cartões verdes ou vermelhos, em tempo real, para o banco de dados, o Redis, o armazenamento, a chave de criptografia e as chaves de provedor, com uma dica em cada cartão com falha, e não exige login.

O que significa port is already allocated no docker compose up?

Outro programa usa a porta 3000 ou 9001 na sua máquina. Mude o lado do host desse mapeamento no docker-compose.community.yml, por exemplo para "3001:3000", e defina PUBLIC_URL de acordo.

Por que o editor fica em branco ou mostra Carregando… para sempre?

Abra o console do navegador. Erros de CORS significam que a origem que você abriu não é permitida, então defina PUBLIC_URL ou CORS_ORIGIN. Erros de login significam que o /config.js indica uma URL do Supabase ou uma chave anon que o navegador não consegue usar.

Por que os meus workflows nunca começam a ser executados?

O orquestrador pega o trabalho dele no Redis. Verifique os registros com docker compose logs nodaro, verifique REDIS_URL e rode docker compose exec redis redis-cli ping, que deve responder PONG.

Onde consigo ajuda com uma instalação auto-hospedada?

Abra um chamado em github.com/nodaroai/app.nodaro.ai com os registros do Docker do contêiner do app.

Última atualização

Nesta página