Troubleshooting de deployment: conflitos de porta, automação de config e validação segura

Em deploy de aplicação web, dois incidentes aparecem com frequência: serviço anterior ainda preso na porta e substituição de configuração feita de forma manual e insegura. O resultado é indisponibilidade, erro humano e rollback improvisado. Este guia é o fluxo que aplico para resolver de forma padronizada.

Cenário de incidente

Erro recebido no start do Node.js:

Error: listen EADDRINUSE: address already in use :::3000

Esse erro indica que a porta já tem processo em escuta. Em ambiente com restarts frequentes, isso costuma ser processo órfão, instância duplicada de PM2/systemd ou container antigo.

Etapa 1: diagnóstico preciso da porta

ss -lntp | grep ':3000'
# fallback
lsof -i :3000

Eu sempre identifico PID e comando antes de matar processo:

ps -fp <PID>

Isso evita derrubar serviço errado em host compartilhado.

Etapa 2: correção controlada

Encerrar PID específico:

kill -15 <PID>
sleep 2
kill -9 <PID> 2>/dev/null || true

Encerrar qualquer processo na porta (apenas quando validado):

fuser -k 3000/tcp

Depois, confirmar liberação:

ss -lntp | grep ':3000' || echo 'porta 3000 livre'

Etapa 3: evitar recorrência com process manager

Não use node app.js & em produção. Use pm2 ou systemd.

Exemplo com PM2:

pm2 start ecosystem.config.js --env production
pm2 save
pm2 startup

Exemplo com systemd (resumo):

[Service]
ExecStart=/usr/bin/node /opt/app/server.js
Restart=always
RestartSec=3

Etapa 4: automação segura de configuração

Em migração, é comum alterar prefixos/usuário em wp-config.php ou .env. O erro clássico é usar aspas simples e não expandir variável.

Errado:

sed -i 's/$OLD/$NEW/g' wp-config.php

Certo:

sed -i "s/$OLD/$NEW/g" wp-config.php

Exemplo real com validação

OLD_VAL=$(grep DB_NAME wp-config.php | cut -d"'" -f4 | cut -d_ -f1)
NEW_VAL=$(pwd | cut -d/ -f3)

# dry-run
sed "s/$OLD_VAL/$NEW_VAL/g" wp-config.php | head -n 20

# aplica após validar
sed -i "s/$OLD_VAL/$NEW_VAL/g" wp-config.php

Proteções adicionais que adotei

backup antes de substituir:

cp wp-config.php wp-config.php.bak.$(date +%F-%H%M)

validar sintaxe PHP após edição:

php -l wp-config.php

versionar alterações de infraestrutura em Git.

Rollback rápido

Se a configuração nova falhar:

cp wp-config.php.bak.YYYY-MM-DD-HHMM wp-config.php
systemctl restart php-fpm

Conclusão

Deploy estável depende de método, não de tentativa e erro. No meu fluxo, eu sempre sigo: identificar processo correto, liberar porta com controle, automatizar substituições com dry-run, validar sintaxe e manter rollback pronto. Esse padrão reduziu incidentes repetidos e padronizou entregas no time.

Este post está licenciado sob CC BY-NC.