Guia: checklist de pré‑deploy e plano de rollback rápido para aplicações PHP em produção

Por Kevin Marcondes · Publicado em 15/10/2026 · 8 min de leitura

Este guia traz um checklist de pré‑deploy e um plano de rollback rápido para aplicações PHP em produção. Você terá etapas objetivas, critérios de go/no‑go e um runbook simples para reverter com segurança quando algo sair do esperado. Copie, adapte ao seu time e use antes do próximo deploy.

Quando usar este checklist e para quem serve

Use este checklist antes de qualquer release que altere código, dependências, configuração, banco de dados ou infraestrutura. Serve para monólitos ou microserviços PHP, em VMs, bare metal ou containers. O foco é reduzir risco operacional com validações claras e um plano de rollback rápido, já ensaiado.

Ele complementa seu pipeline de CI/CD e políticas de mudança. Adapte nomes e comandos ao seu framework e ambiente. Não prometa zero risco: prepare-se para detectar falha cedo e reverter rápido.

Pré‑deploy: validações técnicas obrigatórias

Congele a versão alvo com tag e artefatos imutáveis. Gere o build e dependências fora dos servidores. Cheque versões de PHP, extensões e configurações de OPCache. Garanta healthcheck de aplicação e readiness do PHP‑FPM.

Valide variáveis de ambiente e segredos. Compile assets, gere caches e execute smoke tests. Se um passo falhar, não force o deploy: investigue e reprocesse o artefato. Para segurança do servidor, veja o checklist de hardening.

Integre as checagens ao pipeline para padronizar. Se usa GitHub Actions em projetos PHP, este guia de CI/CD ajuda a estruturar etapas reprodutíveis.

• Tag de release criada e assinada
• Composer install reprodutível (sem dev), build idempotente
• PHP e extensões compatíveis; OPCache com warmup
• Env vars e segredos presentes no runtime
• Assets versionados e caches regenerados
• Healthcheck HTTP 200 e erro tracing habilitado
• Smoke tests passam contra staging/parcial

Banco de dados: migrações seguras e reversão

Planeje migrações em duas fases para compatibilidade retroativa. Evite bloqueios longos em tabelas quentes. Crie índices de forma assíncrona quando possível. Teste com dados realistas e meça o tempo de execução.

Tenha rollback documentado: como desfazer colunas, índices e dados. Backups testados são obrigatórios. Ensaiar um restore pontual reduz pânico. Para estratégias, veja o guia de migrations e rollbacks.

• Evite DDL destrutivo em janela de pico
• Divida renomes em adicionar+preencher+alternar+remover
• Colete plano de execução antes/depois
• Acompanhe locks e deadlocks durante o deploy
• Registre comandos de rollback por change

Plano de rollback rápido: critérios e passos práticos

Defina critérios objetivos de rollback: aumento de erros, p95 de latência, taxa de timeouts, falhas em endpoints críticos ou filas crescendo. Defina responsáveis e tempo máximo entre decisão e execução.

Mantenha releases versionadas por diretório e um symlink atual. O rollback troca o symlink para a versão anterior conhecida e recarrega os serviços. Se houver migração irreversível, prefira roll‑forward corretivo controlado.

• Critérios de rollback claros e observáveis
• Releases imutáveis e rastreáveis
• Symlink atômico para alternar versão
• Recarregar PHP‑FPM e HTTP sem derrubar conexões
• Passos de reversão de schema/dados documentados

# Exemplo genérico de rollback via symlink atômico
# Ajuste caminhos e nomes de serviços ao seu ambiente

export PREV_RELEASE="/var/www/releases/2026-10-07_2230"  # versão estável
ln -sfn "$PREV_RELEASE" /var/www/current

# Recarregar serviços para pegar novo path/opcache
sudo systemctl reload nginx 2>/dev/null || true
sudo systemctl reload php-fpm 2>/dev/null || sudo systemctl reload php8.2-fpm 2>/dev/null || true

# Opcional: limpar cache da aplicação (depende do framework)
# php /var/www/current/artisan cache:clear  # Laravel (exemplo)

Janela de deploy, comunicação e monitoramento pós‑release

Combine janela com negócios e suporte. Avise canais internos e tenha mensagem pronta para clientes se necessário. Modo de manutenção derruba sessões, use somente para tarefas que exigem exclusividade.

Monitore erros, latência, filas, CPU/memória e logs. Defina marcos de observação: T+5, T+15, T+60. Tenha um plano de roll‑forward se o problema for pequeno e isolado.

• Comunicação antes, durante e depois
• Pontos de aprovação e go/no‑go
• Dashboards e alertas ativados
• War room e responsáveis nomeados
• Checklist de validação funcional pós‑deploy

Estratégias que reduzem risco: blue/green, canary e feature flags

Blue/green alterna tráfego entre dois ambientes idênticos. Reversão é rápida e previsível. Canary libera para uma fração de usuários, reduzindo impacto de falhas.

Feature flags desacoplam deploy de lançamento. Você ativa funcionalidades gradualmente e desativa em segundos se algo sair errado. Veja como aplicar em feature flags para monólitos PHP.

Se você usa orquestradores, padrões de rollout ajudam a minimizar indisponibilidade. Este comparativo de estratégias em Kubernetes explica trade‑offs aplicáveis a qualquer stack.

• Blue/green: troca de rota rápida, reversão simples
• Canary: impacto limitado e métricas direcionadas
• Flags: controle fino e rollback lógico
• Gatekeepers para endpoints críticos
• Observabilidade orientando decisões

Checklist consolidado para copiar e colar

Use esta visão rápida como última validação antes do go/no‑go. Adapte nomes, níveis de severidade e responsáveis. Mantenha uma cópia no repositório da aplicação, versionada junto ao código.

Templates de runbook e comandos úteis (adapte)

Mantenha um runbook curto, acionável e testado. Inclua responsáveis, comandos exatos, checkpoints e critérios de sucesso. Para Laravel, confira manutenção e caches na documentação oficial. Veja também o guia de deploy Laravel.

Documente equivalentes para seu framework. Para CLI e sintaxes, consulte as docs do PHP/OPCache em php.net e do Laravel em laravel.com.

• Pré‑check: métricas verdes, backups OK, comunicação enviada
• Deploy: publicar release e aquecer caches
• Verificação: smoke tests e dashboards
• Decisão: manter, roll‑forward ou rollback
• Rollback: comandos prontos e checklist de validação

# Exemplo genérico de passos (adapte ao seu ambiente)
# 1) Criar tag e build
# git tag -a release-2026-10-08 -m "Release"
# 2) Instalar dependências no build server
composer install --no-dev --prefer-dist --no-interaction --optimize-autoloader
# 3) Publicar release versionada
rsync -a --delete ./build/ /var/www/releases/2026-10-08_1530/
ln -sfn /var/www/releases/2026-10-08_1530 /var/www/current
# 4) Recarregar serviços
systemctl reload nginx 2>/dev/null || true
systemctl reload php-fpm 2>/dev/null || systemctl reload php8.2-fpm 2>/dev/null || true
# 5) Backup do banco (exemplo; escolha seu SGBD)
# PostgreSQL: pg_dump -Fc -h HOST -U USER DB > /backups/app_$(date +%F_%H%M).dump
# MySQL: mysqldump -h HOST -u USER -p DB > /backups/app_$(date +%F_%H%M).sql
# 6) Rollback rápido (se necessário)
# ln -sfn /var/www/releases/ULTIMA_ESTAVEL /var/www/current && systemctl reload nginx php-fpm

Perguntas frequentes

Qual a diferença entre rollback e roll‑forward?

Rollback volta para um estado anterior conhecido bom, geralmente trocando a versão em produção. Roll‑forward aplica um novo fix para corrigir o problema atual. Escolha rollback quando o impacto é alto e o caminho de reversão é simples.

Devo sempre ativar modo de manutenção no deploy?

Não. Para a maioria dos deploys use alternância atômica (symlink ou blue/green) e recarregamento do PHP‑FPM. O modo de manutenção é útil apenas quando há operações exclusivas, como migrações que não podem conviver com tráfego.

Como decidir o momento do rollback?

Defina métricas limiares antes do deploy, como erro 5xx, p95 de latência, taxa de timeouts e estabilidade de filas. Se ultrapassar o limiar por um período curto definido, execute o rollback sem discutir. Critérios objetivos evitam indecisão.

Como garantir que o backup de banco está válido?

Faça restauração de teste regular. Restaure o backup em um ambiente isolado, rode migrações e smoke tests. Documente tempo de recuperação e passos. Backup sem restauração testada não é confiável.

Posso usar esse checklist em containers Docker?

Sim. Construa a imagem de forma reprodutível, publique uma tag imutável, aqueça caches no entrypoint e use readiness probes. O rollback pode apontar o serviço para a imagem anterior ou o slot verde em um blue/green.

Como aquecer o OPCache após o deploy?

Você pode usar preloading, mapear scripts críticos no cache e executar uma chamada inicial aos endpoints mais usados. Recarregar o PHP‑FPM também ajuda. Ajuste tamanho de memória e validação de timestamps conforme a carga da aplicação.

Veja também

• Checklist de segurança para pipelines CI/CD com runners self‑hosted e secrets management
• Guia: centralização de logs com Fluentd e Elasticsearch para aplicações PHP em VPS
• Guia: organizar migrations e rollbacks em PostgreSQL para equipes pequenas
• Checklist de segurança para VPS Linux antes de colocar serviços em produção: hardening, SSH, backups e monitoramento