Rode isto depois de uma primeira instalação, depois de um upgrade e depois de uma restauração. Cada passo exercita um subsistema diferente, então uma falha diz exatamente onde procurar.
Checklist
| # | Faça isto | Prova | Se falhar |
|---|---|---|---|
| 1 | Abra a URL do seu Studio e crie uma conta | App, banco de dados, TLS, migrations | kubectl logs deploy/studio-app — e verifique o init container migrations |
| 2 | Saia da conta e entre novamente | Tratamento de sessão, BETTER_AUTH_SECRET, BETTER_AUTH_URL | As URLs precisam corresponder exatamente à sua origem real |
| 3 | Abra um workflow e arraste dois blocks para o workflow builder | Conexão websocket do realtime | Console do navegador em busca de erros de socket; veja Rede |
| 4 | Abra o mesmo workflow em uma segunda janela do navegador e edite | Colaboração entre réplicas | Com mais de 1 réplica, isso exige Redis |
| 5 | Cole uma chave de API de modelo nas configurações e execute um workflow de dois blocks | Motor de execução, encriptação de credenciais, rede de saída | Logs do app; confirme que ENCRYPTION_KEY está definida e que a saída de rede é permitida |
| 6 | Envie um arquivo pequeno em Files | Armazenamento de arquivos de ponta a ponta | Com armazenamento de objetos configurado: URL pré-assinada + CORS do bucket. Em disco local: o upload passa pelo app |
| 7 | Envie um arquivo maior que 50 MB | Caminho de upload multipart (só armazenamento de objetos) | Verifique nos logs do app erros de listagem de partes ou de finalização no provedor |
| 8 | Crie uma knowledge base e envie um PDF | Parsing de documentos, embeddings, pgvector | Precisa de um provedor de embeddings hospedado — veja abaixo |
| 9 | Convide alguém do time nas configurações do workspace | Entrega de e-mail | Logs do app para o mailer; veja E-mail |
| 10 | Conecte uma conta de integração | Configuração de OAuth | URI de redirecionamento divergente → veja Integrações e OAuth |
| 11 | Crie um workflow com um trigger Schedule definido para cada minuto, faça o deploy e espere 2 minutos | Jobs em background | Confira os logs do agendador — veja Jobs em Background |
| 12 | Dispare um workflow pela API com uma chave de API | API pública e autenticação por chave de API | Confirme que a chave foi criada com sucesso nas configurações |
O passo 11 é o que mais gente pula e o que mais costuma ser descoberto quebrado semanas depois. Workflows agendados e todo trigger de polling dependem do agendador, e um CRON_SECRET errado ou ausente faz tudo falhar silenciosamente do lado do app.
Checagens de infraestrutura
Antes de percorrer a interface, confirme que o deployment em si está saudável.
# Everything running?
kubectl get pods -n studio
# Migrations completed
kubectl logs -n studio deploy/studio-app -c migrations --tail=50
# Health endpoints
curl -fsS https://studio.yourdomain.com/api/health
# Background jobs scheduled
kubectl get cronjobs -n studio
# Redis configured (multi-replica deployments) — confirms the variable is set,
# not that Redis answers. Steps 3 and 4 below are the real reachability test.
kubectl exec -n studio deploy/studio-app -- printenv REDIS_URL# Docker Compose
docker compose -f docker-compose.prod.yml ps
docker compose -f docker-compose.prod.yml logs migrations
curl -fsS http://localhost:3000/api/healthTodos os seis devem estar presentes no Compose: studio, realtime, db, redis, cron e um migrations concluído.
Lendo as falhas
Passo 1 falha — o app não carrega. Quase sempre migrations ou conectividade com o banco de dados. Verifique primeiro o init container de migrations; uma migration que falha bloqueia o rollout deliberadamente.
Passo 2 falha — o login entra em loop ou é rejeitado. NEXT_PUBLIC_APP_URL ou BETTER_AUTH_URL não corresponde à origem que você está acessando. As duas precisam ser a URL pública exata, com o esquema e sem barra no final.
Passo 3 falha — sem atualizações ao vivo. O proxy reverso não está repassando os upgrades de websocket, ou /socket.io não está roteado para o serviço de realtime. Se o realtime está em outro hostname, NEXT_PUBLIC_SOCKET_URL precisa apontar para ele e o ALLOWED_ORIGINS do realtime precisa incluir a origem do app.
Passo 4 falha — as edições não sincronizam entre janelas. Com mais de uma réplica, isso é Redis. Confirme que REDIS_URL está presente nos dois pods.
Passo 5 falha — erros de execução. Verifique a conectividade de saída com o provedor de modelo e depois os logs do app. Se o erro fala sobre descriptografar uma credencial, a ENCRYPTION_KEY é diferente da que encriptou o dado.
Passo 6 ou 7 falha. Com armazenamento de objetos configurado, um erro de CORS no console do navegador significa que a política do bucket não permite a sua origem do Studio ou os headers assinados do upload. Se o passo 7 falha apenas na finalização, verifique os logs do app e confirme que a identidade do servidor consegue listar as partes do multipart (na S3, s3:ListMultipartUploadParts). No armazenamento em disco local não há CORS envolvido — os uploads passam pelo app, então olhe os logs do app e o limite de tamanho de corpo do proxy.
Passo 8 falha — erros no upload da knowledge base. Bases de conhecimento precisam de um provedor de embeddings hospedado — OpenAI, Azure OpenAI ou Gemini. Não existe backend local de embeddings. Se uma chave estiver definida, confirme que o pgvector está instalado no banco de dados.
Passo 9 falha — nenhum e-mail chega. Sem provedor configurado, os e-mails são gravados nos logs do app em vez de enviados — verifique lá primeiro para confirmar que a mensagem foi gerada, e só depois investigue o provedor.
Passo 11 falha — o agendamento nunca dispara. Leia os logs do agendador (docker compose logs cron, ou kubectl get cronjobs -n studio). Um 401 ali significa que o app e o agendador discordam sobre o CRON_SECRET.
Depois de um upgrade
Repita, no mínimo, os passos 1, 3, 5, 6 e 11. Eles cobrem o app, o realtime, a execução, o armazenamento e os jobs em background — as cinco coisas que um upgrade ruim quebra.
Depois de uma restauração
Rode a lista completa e preste atenção especial ao passo 5 com uma integração baseada em OAuth. É isso que prova que a ENCRYPTION_KEY corresponde ao backup. Um app que carrega e faz login mas não consegue descriptografar credenciais parece saudável até o momento em que alguém executa um workflow de verdade.