Aqui mantemos os arquivos de versões diferentes em pastas separadas e fazemos a troca dos processos com sobreposição. É uma forma de blue-green dentro de um servidor, sem exigir Kubernetes.

current normalmente é um link simbólico, não uma pasta independente. Trocar esse link muda o caminho dos arquivos; não substitui automaticamente uma API Node.js, Python ou .NET que já está rodando.

Estrutura e papéis

Elemento Exemplo e responsabilidade
Release antiga /app/releases/1.8.0/ — arquivos preservados da aplicação anterior.
Release nova /app/releases/1.9.0/ — resultado do build homologado.
current Aponta para a release escolhida; serve como referência operacional.
shared Uploads e outros dados persistentes apropriados; configurações sensíveis via mecanismo seguro. Não misturar arquivos gerados de versões incompatíveis.
Processos e proxy Aplicação antiga na porta 3001, nova na 3002; proxy controla quem recebe novas requisições.
Banco Compartilhado, mantendo compatibilidade com as duas aplicações durante a janela de transição.

Um servidor: duas versões durante a troca

Os processos usam caminhos fixos de suas releases. O proxy realiza a transição; current não transfere conexões.

Fluxo completo

  1. Homologar o build e reservar memória, CPU e portas para as duas versões simultâneas. Garantir que uma única execução do pipeline controle a troca.
  2. Enviar o artefato para uma pasta nova e conferir sua identificação. Não fazer build ou instalação diferente em cada versão sem rastreabilidade.
  3. Executar migração aditiva/compatível uma vez. Avaliar locks e impacto; mesmo adicionar uma coluna pode afetar atendimento conforme a operação e o banco.
  4. Iniciar a aplicação nova em outra porta, fixada no caminho absoluto da sua release. Desabilitar tarefas agendadas duplicadas ou usar eleição/lock para só um executor quando necessário.
  5. Verificar readiness e rotas internas: banco, configuração, autorização e jornadas essenciais. Não permitir que um simples processo vivo seja considerado pronto.
  6. Validar a configuração do proxy antes de aplicá-la. Transferir novas conexões pelo proxy e substituir o link current sem uma etapa intermediária em que o link fique ausente. São passos coordenados: registrar o resultado de cada um, pois não existe uma transação única que cubra link, proxy e processo.
  7. Aguardar requisições antigas terminarem. Preparar reconexão para WebSocket e streaming, com limites de espera coerentes.
  8. Observar erros e indicadores de negócio. Manter a versão antiga executável durante a janela de retorno e encerrar seus processos quando seguro.
  9. Limpar releases antigas só depois do prazo de retenção e das necessidades de arquivos ainda utilizados por clientes.

Banco: exemplo de mudança incompatível em etapas

  1. Adicionar nome_completo opcional sem remover nome.
  2. Publicar uma versão intermediária que ainda lê nome, mas mantém ambos os campos coerentes nas escritas relevantes.
  3. Aguardar todos os escritores adotarem essa versão; incluir jobs e integrações, não apenas a API.
  4. Preencher e reconciliar dados existentes com controle de concorrência, para não sobrescrever uma alteração recente com valor antigo.
  5. Publicar a versão que lê nome_completo, mantendo compatibilidade de escrita durante a janela de rollback.
  6. Remover nome somente em entrega posterior, após nenhum consumidor ou versão de retorno precisar dele.

Nem toda mudança exige duas colunas. O exemplo ilustra expand-and-contract. Duas escritas também podem falhar parcialmente: quando precisam ser consistentes, usar a transação adequada e verificar todos os caminhos de atualização.

Falhas e recuperação por ponto

Falha Resposta
Falha ao enviar ou preparar a release Não alterar o destino ativo. A versão antiga continua atendendo.
Migração falha Parar a publicação; avaliar efeitos no serviço antigo. Se a estrutura ou lock afetou produção, conter e recuperar o banco.
Nova aplicação não inicia ou falha nos testes Manter tráfego na antiga. Encerrar ou corrigir o candidato; registrar o motivo.
Troca de proxy falha Manter ou restabelecer a configuração conhecida. Conferir destino real; current pode estar diferente do processo que atende.
Bug após transferência Confirmar saúde e compatibilidade da versão antiga, retornar novas conexões a ela, drenar a nova e ajustar current. Não encerrar processos antes de haver destino saudável.
Nova aplicação corrompeu dados Rollback pode parar novas gravações erradas, mas é necessário reparar os registros e avaliar se a antiga consegue ler os dados já escritos.
Perda do servidor ou esgotamento de recursos As duas versões podem cair. Não há alta disponibilidade por estarem na mesma máquina; planejar restauração e capacidade.

Arquivos estáticos, sessões e tecnologias diferentes

  • Frontend: manter arquivos com nomes versionados/hash por tempo suficiente. Uma aba antiga pode pedir um arquivo que não existe na pasta nova. Evitar caches incompatíveis e não tratar só a página HTML como toda a aplicação.
  • Sessões: se ficam apenas na memória de um processo, a troca pode desconectar usuários. Usar armazenamento adequado ou aceitar e comunicar o comportamento.
  • PHP: runtimes por requisição e caches como OPcache têm particularidades; caminhos precisam ser consistentes por requisição. Troca de link não elimina todos os riscos de misturar arquivos.
  • PM2 em cluster pode fazer reload gracioso, mas timeouts podem causar fallback para restart. Gunicorn e outros runtimes têm seus próprios mecanismos.
  • Uploads persistem fora da pasta descartável da release. Nunca removê-los ao limpar versões antigas.

Bugfix e hotfix

Cada correção gera uma nova versão em outra pasta, como 1.9.1. Se a antiga continua compatível, retornar o tráfego pode conter o incidente antes do patch. Se não houver compatibilidade ou capacidade para sobreposição, usar manutenção programada. Propagar correções às linhas de código necessárias.

Limites e checklist de saída

  • Mesmo build aprovado e configuração conferida.
  • Readiness, jornadas, logs e destino real verificados.
  • Banco compatível e migrações registradas.
  • Plano de drenagem, retomada e rollback testado.
  • Sem agendadores duplicados nem arquivos persistentes dentro de releases descartáveis.
  • Não confundir deploy sem parada com proteção contra falha do servidor.

Fontes e aprofundamento

Referências consultadas em 2 de novembro de 2026. Os procedimentos são modelos conceituais: parâmetros, comandos e garantias dependem da tecnologia e precisam ser ensaiados.

Outros artigos da série