Guía: checklist de pre‑deploy y plan de rollback rápido para aplicaciones PHP en producción

Por Kevin Marcondes · Publicado el 15/10/2026 · 9 min de lectura

Esta guía ofrece un checklist de pre‑deploy y un plan de rollback rápido para aplicaciones PHP en producción. Incluye pasos objetivos, criterios de go/no‑go y un runbook simple para revertir con seguridad cuando algo no salga como esperado. Copia, adapta a tu equipo y úsalo antes del próximo deploy.

Cuándo usar este checklist y a quién va dirigido

Utiliza este checklist antes de cualquier release que modifique código, dependencias, configuración, base de datos o infraestructura. Sirve para monolitos o microservicios PHP, en VMs, bare metal o contenedores. El objetivo es reducir el riesgo operativo mediante validaciones claras y un plan de rollback rápido, ya ensayado.

Complementa tu pipeline de CI/CD y las políticas de cambio. Adapta nombres y comandos a tu framework y entorno. No prometas riesgo cero: prepárate para detectar fallos temprano y revertir con rapidez.

Pre‑deploy: validaciones técnicas obligatorias

Congela la versión objetivo con una tag y artefactos inmutables. Genera el build y las dependencias fuera de los servidores. Verifica versiones de PHP, extensiones y configuración de OPCache. Asegura healthchecks de la aplicación y readiness de PHP‑FPM.

Valida variables de entorno y secretos. Compila assets, genera caches y ejecuta smoke tests. Si algún paso falla, no fuerces el deploy: investiga y reprocesa el artefacto. Para seguridad del servidor, consulta el checklist de hardening.

Integra las comprobaciones en el pipeline para estandarizar. Si usas GitHub Actions en proyectos PHP, esta guía de CI/CD ayuda a estructurar pasos reproducibles.

• Tag de release creada y firmada
• Composer install reproducible (sin dev), build idempotente
• PHP y extensiones compatibles; OPCache con warmup
• Variables de entorno y secretos presentes en runtime
• Assets versionados y caches regenerados
• Healthcheck HTTP 200 y tracing de errores habilitado
• Smoke tests pasan contra staging/parcial

Base de datos: migraciones seguras y reversión

Planifica migraciones en dos fases para compatibilidad hacia atrás. Evita bloqueos largos en tablas calientes. Crea índices de forma asíncrona cuando sea posible. Prueba con datos realistas y mide el tiempo de ejecución.

Ten a mano el rollback documentado: cómo deshacer columnas, índices y datos. Los backups testados son obligatorios. Ensayar una restauración puntual reduce el pánico. Para estrategias, consulta la guía de migraciones y rollbacks.

• Evita DDL destructivo en ventanas de pico
• Divide renombres en agregar+llenar+alternar+eliminar
• Recolecta plan de ejecución antes/después
• Supervisa locks y deadlocks durante el deploy
• Registra comandos de rollback por cambio

Plan de rollback rápido: criterios y pasos prácticos

Define criterios objetivos de rollback: incremento de errores, p95 de latencia, tasa de timeouts, fallos en endpoints críticos o colas creciendo. Asigna responsables y un tiempo máximo entre la decisión y la ejecución.

Mantén releases versionadas por directorio y un symlink actual. El rollback cambia el symlink a la versión anterior conocida y recarga los servicios. Si hay migraciones irreversibles, prioriza un roll‑forward correctivo controlado.

• Criterios de rollback claros y observables
• Releases inmutables y rastreables
• Symlink atómico para alternar versión
• Recargar PHP‑FPM y HTTP sin derribar conexiones
• Pasos de reversión de esquema/datos 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)

Ventana de deploy, comunicación y monitorización post‑release

Acorda la ventana con negocio y soporte. Informa a los canales internos y ten un mensaje listo para clientes si hace falta. El modo de mantenimiento corta sesiones, úsalo solo para tareas que requieran exclusividad.

Monitorea errores, latencia, colas, CPU/memoria y logs. Define puntos de observación: T+5, T+15, T+60. Ten un plan de roll‑forward si el problema es pequeño y aislado.

• Comunicación antes, durante y después
• Puntos de aprobación y go/no‑go
• Dashboards y alertas activadas
• War room y responsables asignados
• Checklist de validación funcional post‑deploy

Estrategias que reducen riesgo: blue/green, canary y feature flags

Blue/green alterna tráfico entre dos entornos idénticos. La reversión es rápida y predecible. Canary libera a una fracción de usuarios, reduciendo el impacto de fallos.

Feature flags desacoplan el deploy del lanzamiento. Activas funcionalidades gradualmente y desactivas en segundos si algo falla. Consulta cómo aplicarlas en feature flags para monolitos PHP.

Si usas orquestadores, los patrones de rollout ayudan a minimizar la indisponibilidad. Esta comparativa de estrategias en Kubernetes explica trade‑offs aplicables a cualquier stack.

• Blue/green: cambio de ruta rápido, reversión simple
• Canary: impacto limitado y métricas focalizadas
• Flags: control fino y rollback lógico
• Gatekeepers para endpoints críticos
• Observabilidad guiando decisiones

Checklist consolidado para copiar y pegar

Usa esta vista rápida como la validación final antes del go/no‑go. Adapta nombres, niveles de severidad y responsables. Mantén una copia en el repositorio de la aplicación, versionada junto al código.

Plantillas de runbook y comandos útiles (adapta)

Mantén un runbook corto, accionable y probado. Incluye responsables, comandos exactos, checkpoints y criterios de éxito. Para Laravel, consulta mantenimiento y caches en la documentación oficial. También revisa la guía de deploy de Laravel.

Documenta equivalentes para tu framework. Para CLI y sintaxis, consulta las docs de PHP/OPCache en php.net y de Laravel en laravel.com.

• Pre‑check: métricas verdes, backups OK, comunicación enviada
• Deploy: publicar release y calentar caches
• Verificación: smoke tests y dashboards
• Decisión: mantener, roll‑forward o rollback
• Rollback: comandos listos y checklist de validación

# 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

Preguntas frecuentes

¿Cuál es la diferencia entre rollback y roll‑forward?

Rollback vuelve a un estado anterior conocido bueno, generalmente cambiando la versión en producción. Roll‑forward aplica un nuevo fix para corregir el problema actual. Elige rollback cuando el impacto es alto y la reversión es sencilla.

¿Debo activar siempre el modo de mantenimiento en el deploy?

No. Para la mayoría de deploys usa alternancia atómica (symlink o blue/green) y recarga del PHP‑FPM. El modo de mantenimiento es útil solo cuando hay operaciones exclusivas, como migraciones que no pueden convivir con tráfico.

¿Cómo decidir el momento del rollback?

Define umbrales métricos antes del deploy, como errores 5xx, p95 de latencia, tasa de timeouts y estabilidad de colas. Si se supera el umbral durante el período definido, ejecuta el rollback sin discusión. Criterios objetivos evitan la indecisión.

¿Cómo garantizar que el backup de la base de datos es válido?

Realiza restauraciones de prueba regularmente. Restaura el backup en un entorno aislado, ejecuta migraciones y smoke tests. Documenta el tiempo de recuperación y los pasos. Un backup no probado no es confiable.

¿Puedo usar este checklist en contenedores Docker?

Sí. Construye la imagen de forma reproducible, publica una tag inmutable, calienta caches en el entrypoint y usa readiness probes. El rollback puede apuntar el servicio a la imagen anterior o al slot verde en un blue/green.

¿Cómo calentar OPCache tras el deploy?

Puedes usar preloading, mapear scripts críticos en el cache y ejecutar una llamada inicial a los endpoints más usados. Recargar PHP‑FPM también ayuda. Ajusta el tamaño de memoria y la validación de timestamps según la carga de la aplicación.

Ver también

• Checklist de seguridad para pipelines CI/CD con runners self‑hosted y gestión de secretos
• Guía: centralización de logs con Fluentd y Elasticsearch para aplicaciones PHP en VPS
• Guía: organizar migraciones y rollbacks en PostgreSQL para equipos pequeños
• Guía práctica: cómo autoescalar runners self‑hosted en GitHub Actions para pipelines CI de proyectos PHP