Implantação com Zero Downtime

1. Visão Geral do Conceito e Problema Sistêmico

A atualização primitiva de serviços por meio do reinício do processo (systemctl restart app ou docker restart container) resulta em indisponibilidade (Downtime). Durante os 5 a 30 segundos necessários para que o novo processo inicialize o ambiente de execução, conecte-se aos bancos de dados e compile código JIT:

• Todas as requisições HTTP ativas são interrompidas no meio da transmissão de dados.
• O balanceador de carga ou proxy reverso retorna erros 502 Bad Gateway ou 504 Gateway Timeout aos usuários.
• Transações do usuário (pagamentos, persistência de estado, geração via LLM) permanecem em um estado semi-corrompido.

O Zero-Downtime Deployment elimina a indisponibilidade através da orquestração do ciclo de vida dos processos. A nova versão da aplicação é iniciada paralelamente à antiga. O tráfego é comutado somente após o novo instância responder com sucesso às sondas de Health Check, enquanto a instância antiga finaliza corretamente todas as operações iniciadas durante o Graceful Shutdown.

Fase 1: Versão ativa v1.0
[Clientes] ---> [Reverse Proxy / Nginx] ---> [Container v1.0 (Ativo)]

Fase 2: Início da v1.1 e Healthcheck
[Clientes] ---> [Reverse Proxy / Nginx] ---> [Container v1.0 (Ativo)]
                                             [Container v1.1 (Iniciando... /healthz: 200 OK)]

Fase 3: Alternância de tráfego e Encerramento gracioso da v1.0
[Clientes] ---> [Reverse Proxy / Nginx] ---> [Container v1.1 (Ativo)]
                                       \---> [Container v1.0 (Finalizando requisições ativas... SIGTERM)]

Fase 4: Conclusão (v1.0 desativado)
[Clientes] ---> [Reverse Proxy / Nginx] ---> [Container v1.1 (Ativo)]

2. Taxonomia Arquitetural e Modelo Mental

Estratégias de atualização contínua:

1. Blue/Green Deployment:
   • Duplicação completa da camada de infraestrutura.
   • Comutação instantânea e atômica do tráfego na camada Nginx, Traefik ou DNS/ALB.
   • Maior confiabilidade e rollback mais simples, porém exige o dobro de memória RAM e recursos do host.
2. Rolling Update:
   • Os contêineres são atualizados sequencialmente, um por vez ou em grupos.
   • Mantém a capacidade constante do cluster (por exemplo, mínimo de 3 réplicas operacionais de um total de 4).
   • Economia de recursos de hardware; padrão default no Kubernetes e Docker Swarm.
3. Canary Release:
   • A nova versão recebe uma porcentagem fixa e micro do tráfego real (por exemplo, 2-5%) ou usuários de um grupo interno específico.
   • Métricas sistêmicas (Error Rate, Latency) são monitoradas. Se nenhuma anomalia for detectada, a parcela de tráfego aumenta gradualmente até 100%.

3. Pipeline Técnico e Mecânica Interna

Implementação de Graceful Shutdown em Node.js / TypeScript

O processo deve interceptar corretamente os sinais do sistema operacional SIGTERM e SIGINT:

import express from "express";
import http from "http";

const app = express();
let isShuttingDown = false;

// Healthcheck ендпоінт для оркестратора
app.get("/healthz", (req, res) => {
  if (isShuttingDown) {
    // Сигнал балансувальнику не направляти сюди нові запити
    return res.status(503).json({ status: "shutting_down" });
  }
  return res.status(200).json({ status: "healthy" });
});

const server = http.createServer(app);
server.listen(3000);

// Перехоплення сигналу завершення від Docker / systemd
process.on("SIGTERM", () => {
  console.log("SIGTERM received. Starting graceful shutdown...");
  isShuttingDown = true;

  // 1. Припиняємо прийом нових HTTP-з'єднань
  server.close(async () => {
    console.log("Closed all remaining HTTP connections.");

    try {
      // 2. Закриваємо пули з'єднань з базами даних та Redis
      await dbPool.end();
      await redisClient.quit();
      console.log("Infrastructure connections closed. Exiting process.");
      process.exit(0);
    } catch (err) {
      console.error("Error during teardown:", err);
      process.exit(1);
    }
  });

  // 3. Запобіжник (Fail-safe): примусове завершення при зависанні сокетів
  setTimeout(() => {
    console.error("Forced termination: active connections timed out.");
    process.exit(1);
  }, 20000); // 20 секунд ліміту
});

Configuração de Healthcheck no Docker Compose

Para garantir a comutação de tráfego pelo orquestrador, configura-se o parâmetro de verificação de saúde:

services:
  api:
    image: my-company/api:v1.2.0
    restart: always
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/healthz"]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 10s
    stop_grace_period: 30s # Час на виконання Graceful Shutdown

4. Cenários Práticos de Engenharia em Produção

01. Deploy via Coolify sem interrupção de tráfego

A plataforma Coolify utiliza o proxy reverso integrado Traefik. Ao clicar em Deploy, ela constrói uma nova imagem Docker, inicia um novo contêiner em uma porta aleatória, consulta seu endpoint de healthcheck e, somente após confirmar a viabilidade, reconfigura o roteamento do Traefik dinamicamente, enviando em seguida o sinal SIGTERM à réplica antiga.

02. Hot Configuration Reload do Nginx (nginx -s reload)

Ao atualizar certificados SSL ou adicionar novas configurações upstream, o processo master do Nginx inicia um novo conjunto de worker processes com a nova configuração. Os workers antigos param de aceitar novas conexões, finalizam a transmissão dos arquivos ativos para os clientes atuais e só então se auto-eliminam sem descartar um único pacote.

03. Deploy de migrações de banco de dados sem bloqueio de tabelas no PostgreSQL

Ao adicionar índices a tabelas grandes (milhões de linhas), o comando padrão CREATE INDEX bloqueia a tabela para escrita (EXCLUSIVE LOCK), fazendo a fila de consultas travar. Engenheiros utilizam a opção CREATE INDEX CONCURRENTLY, que constrói o índice em background sem bloquear operações paralelas de leitura e escrita.

5. Armadilhas, Erros Comuns e Segurança

1. Ausência de stop_grace_period no Docker: Por default, o Docker concede ao contêiner apenas 10 segundos para tratar o SIGTERM, após o qual envia o fatal SIGKILL (morte imediata do processo). Se uma longa requisição a uma LLM ou um webhook de pagamento durar 12 segundos, a operação será abortada com corrupção de dados. Aumente o limite para 30–60 segundos.
2. Incompatibilidade de versões de código com o banco de dados: Tentar renomear uma coluna da tabela (ALTER TABLE users RENAME COLUMN email TO contact_email) quebra imediatamente a versão antiga do código, que continua rodando em paralelo durante o deploy. Aplique sempre o padrão Expand-and-Contract em dois releases separados.
3. Endpoints de Health Check falsos positivos: Se o endpoint /healthz verificar a disponibilidade de todas as APIs externas de terceiros (por exemplo, OpenAI ou Twitter API) e elas apresentarem lentidão temporária, o orquestrador considerará o próprio serviço morto e entrará em um loop infinito de reinícios (CrashLoopBackOff / Healthcheck Storm), destruindo um sistema de produção funcional. A sonda liveness deve verificar exclusivamente o processo local.