Atualizando o Strapi da v4 para a v5 em produção
O Strapi v5 é uma versão maior incompatível, com uma nova API de acesso a dados no seu núcleo. Veja como atualizei um CMS em produção da v4 para a v5 sem perder conteúdo nem ter downtime: um caminho em etapas, 19 hooks de ciclo de vida reescritos, um banco de dados clonado para ensaiar e uma virada que deixou a produção por último.
Mudanças de versão maior incluíram hooks de ciclo de vida e verificações de comportamento antes da virada em produção.
Contribuição em resumo
- Minha responsabilidade
- Atualização em etapas da aplicação/runtime, mudanças nos hooks de ciclo de vida e verificações de compatibilidade.
- Escopo
- A migração de versão maior de uma plataforma de conteúdo com estado.
- Colaboração & limites
- Atuei na compatibilidade da aplicação e na validação de deployment; a preservação do conteúdo e do comportamento existente eram restrições de aceitação.
- Resultado
- Adaptei o comportamento de ciclo de vida e validei a compatibilidade antes da virada; o desempenho contínuo do serviço precisa de observação separada.
Atualizações de versão maior de uma aplicação com estado, que carrega conteúdo, são onde o "é só um bump de versão" morre. O Strapi v5 muda o modelo de acesso a dados, então a atualização não é só novas dependências: é reescrever como a aplicação lê e grava o próprio conteúdo. O conteúdo no banco de dados tinha que sobreviver, e o site não podia sair do ar. Foi assim que eu fiz.
Primeiro, avance até a última v4
O primeiro erro teria sido pular direto de uma v4 antiga para a v5. Atualizei a base de código em etapas: v4 antiga, depois a última v4 e então a v5. Chegar primeiro à última v4 elimina as depreciações e expõe as mudanças incompatíveis enquanto você ainda está em uma versão maior familiar, de modo que o salto final para a v5 é a única coisa que resta depurar. A mesma passagem moveu o runtime para o Node 20 e trocou o driver de banco de dados pelo que tem manutenção ativa.
A verdadeira mudança incompatível: o Document Service
O Strapi v5 substitui a antiga API de dados em nível de entidade por um novo Document Service, e isso afeta cada pedaço de lógica personalizada. A parte mais pesada da migração foi reescrever todos os 19 hooks de ciclo de vida para a nova API. Os hooks de ciclo de vida são o comportamento personalizado que roda quando um conteúdo é criado, atualizado ou excluído, então errá-los é o jeito de corromper dados silenciosamente. Cada um foi migrado e verificado individualmente.
Ensaie em um clone, não em produção
Antes de tocar em qualquer coisa no ar, clonei o banco de dados de desenvolvimento em um schema v5 isolado e rodei a migração inteira contra ele. A migração de dados ou funciona em uma cópia de conteúdo real ou não funciona; descobrir isso em um clone descartável é de graça, descobrir isso em produção não é.
Faça a virada em fases, produção por último
O build v5 rodou como um novo fluxo ao lado do fluxo v4 existente. Fiz a virada ambiente por ambiente, começando pelos de menor risco (sandbox / legado) e validando cada um antes de seguir. A produção foi preparada e então retida, com a virada feita somente após aprovação explícita. Em nenhum momento houve uma única troca big-bang sem caminho de volta.
A atualização também deixou o serviço mais resiliente
Trabalhar tão de perto com a aplicação revelou uma fragilidade latente: os pods entravam em crash-loop quando o upstream do CMS tinha uma breve instabilidade, e uma rajada de tráfego em um endpoint podia saturá-lo. Adicionei um handler de erros compartilhado em cada handler de requisição e reforcei o pool de conexões do banco de dados contra instabilidades transitórias de rede, além de alertas de uptime. A atualização deixou o serviço não apenas mais novo, mas mais difícil de derrubar.
O que eu diria a quem está começando isto
- Suba até a última versão menor da sua versão maior atual antes do grande salto. Elimine as depreciações onde o terreno é familiar.
- Trate a mudança na API de acesso a dados como o trabalho de verdade. No Strapi v5, isso é o Document Service e cada hook de ciclo de vida, não o bump de dependências.
- Ensaie a migração de dados em um clone de conteúdo real. Uma cópia conta a verdade de graça.
- Faça a virada em fases e deixe a produção por último, atrás de um aval explícito. Rode o novo fluxo ao lado do antigo para que sempre haja um caminho de volta.
Decisões e próximos passos
Uma visão retrospectiva da abordagem e seus limites. A próxima melhoria é uma proposta, não um resultado entregue.
Alternativa e justificativa
Um salto direto de versão maior combina depreciações e o novo comportamento da API. Chegar primeiro à última v4 isola parte desse risco.
Trade-off
Mudanças na API de acesso a dados podem preservar a saúde HTTP enquanto alteram o comportamento de negócio. Valide conteúdo e hooks, não apenas a inicialização.
O que eu melhoraria a seguir
Próxima melhoria: manter conteúdo representativo e verificações de regressão de ciclo de vida para atualizações subsequentes.