Deploy, saúde e incidentes

Regra de versão

Toda entrega em main precisa de versão SemVer maior que a última publicada. O comando local abaixo cria automaticamente um patch quando a versão ainda é igual à remota. Ele só deve ser usado em main; branches de trabalho continuam usando git push normal.

npm run release:push

CLI de releases

No servidor, a CLI usa uma raiz externa, com releases separadas e runtime compartilhado. O bootstrap é executado uma única vez por uma pessoa com acesso ao VPS:

npm install
npm run cli:install
export ARTMETA_ECOMM_PM2_APP=nome-do-processo-atual
artmeta ecomm init

Antes da primeira publicação, mantenha .env.local em shared/ e preserve o diretório configurado em ECOM_RUNTIME_ROOT fora de releases/.

Transição inicial

O primeiro deploy que contém esta CLI ainda usa o procedimento anterior, pois a CLI ainda não existe no servidor. Depois dele, instale o comando, execute init, copie o ambiente para shared/ e publique a primeira release. A promoção passa o PM2 a usar current; os deploys seguintes não usam mais git pull no diretório ativo.

O sistema guarda até três releases. A ativa e sua anterior são protegidas; quando uma quarta é publicada, a mais antiga elegível é removida automaticamente. O arquivo shared/release-index.json impede publicar uma versão menor ou igual à maior versão já registrada, mesmo que releases antigas tenham sido removidas.

Na primeira promoção após migrar de um checkout tradicional, o CLI recria somente o processo PM2 da aplicação para trocar o diretório de execução para current. Isso causa uma interrupção de poucos segundos uma única vez. Nas promoções seguintes, o processo é apenas recarregado e o healthcheck aguarda a inicialização do Next.js por até 30 segundos antes de considerar rollback.

Republicar uma versão

Versões são imutáveis enquanto existem em releases/. Se uma publicação recente precisa ser refeita com o mesmo número, por exemplo para incluir documentação que também é servida pelo site, use este fluxo controlado:

artmeta ecomm rollback 5.4.2
artmeta ecomm discard 5.4.3
artmeta ecomm deploy

discard recusa remover a release ativa e também recusa versões que não sejam a mais recente. O diretório da build é removido, mas o manifesto é preservado em manifests/retired/ com commit, data e motivo. Isso evita apagar a trilha operacional e permite que a mesma versão seja publicada novamente após a main ser atualizada.

Compatibilidade de banco

Build nunca consulta ou evolui PostgreSQL: ECOMMPANEL_ALLOW_DB_DURING_BUILD=false. Criações idempotentes ocorrem somente no runtime. Para preservar rollback:

1. uma release pode adicionar tabela, índice ou coluna opcional;
2. a versão anterior deve continuar aceitando a estrutura nova;
3. remoções, renomes e mudança de semântica são feitas somente em release posterior;
4. mudança incompatível exige backup e confirmação manual antes de promover.

Ensaio isolado de restauração

O pacote de setup pode ser validado no próprio VPS sem apontar o PM2, o runtime ou a aplicação para uma base diferente. O comando cria uma role sem privilégios administrativos e uma base temporária, replica apenas o schema das tabelas incluídas no pacote, restaura os dados, confere checksum, contagens e entidades dinâmicas do Data Studio e remove a base e a role ao final.

cd /var/www/artmeta-ecomm/repository
npm run backup:verify-restore -- --env=/var/www/artmeta-ecomm/shared/.env.local

Para validar um JSON exportado pelo painel em vez de gerar o pacote diretamente da origem, informe seu caminho absoluto. O arquivo deve permanecer fora do repositório e com permissão restrita.

npm run backup:verify-restore -- \
  --env=/var/www/artmeta-ecomm/shared/.env.local \
  --input=/var/lib/artmeta/backups/artmeta-store-setup-2026-07-12.json

Pré-requisitos: executar como root, PostgreSQL local ativo, psql e pg_dump instalados e credenciais APP_DB_* válidas. O teste lê a origem, mas não altera a base ativa; usuários, sessões, pedidos, analytics, chaves de API e binários de mídia continuam fora do escopo desse pacote. Uma falha deixa o relatório no terminal e também aciona a limpeza da base temporária.

O pacote de mídia é verificado separadamente para não substituir a biblioteca publicada. Ele exporta os arquivos e metadados atuais, restaura em diretórios de /tmp, compara o checksum final e remove esses diretórios ao terminar.

cd /var/www/artmeta-ecomm/repository
npm run backup:verify-media -- --env=/var/www/artmeta-ecomm/shared/.env.local

Para validar um arquivo .json.gz exportado pelo painel:

npm run backup:verify-media -- \
  --env=/var/www/artmeta-ecomm/shared/.env.local \
  --input=/var/lib/artmeta/backups/artmeta-media-library-2026-07-12.json.gz

Arquivos preservados

• .env.local e demais segredos do servidor;
• diretório apontado por ECOM_RUNTIME_ROOT;
• mídia e metadados externos;
• configuração Nginx e certificados;
• banco PostgreSQL;
• estado do PM2 fora do repositório.

Worker PostgreSQL

Jobs assíncronos usam a tabela system_jobs no PostgreSQL. O worker não é público: defina um segredo exclusivo no ambiente compartilhado e execute somente a partir do VPS.

ARTMETA_WORKER_TOKEN=gere-um-segredo-longo-e-exclusivo

Teste manual:

cd /var/www/artmeta-ecomm/current
npm run jobs:run

Para operação contínua, agende a cada minuto com o usuário que executa a aplicação. O worker faz lock transacional, usa retry para falhas do job e ignora duplicidades por chave de deduplicação.

* * * * * cd /var/www/artmeta-ecomm/current && /usr/bin/npm run jobs:run >> /var/log/artmeta-jobs.log 2>&1

O primeiro job é back-in-stock.scan: ele envia uma vez o aviso de reposição para inscrições pendentes cujo produto esteja ativo e disponível. Antes de habilitar cron, confirme SMTP e execute o teste manual.

Smoke test

1. pm2 status mostra processo online.
2. home e storefront respondem 200.
3. login administrativo cria sessão persistente.
4. /ecommpanel/admin autenticado responde 200 e não possui x-nextjs-prerender.
5. API pública responde com contrato esperado.
6. painel de saúde confirma banco, runtime, storage e SMTP.
7. uma leitura de catálogo e uma simulação comercial funcionam.
8. X-Powered-By não aparece, CSP está em Report-Only e o health público não expõe caminhos ou contagens internas.

Primeiro deploy desta camada de segurança

O cookie de sessão passa a usar o prefixo __Host- em produção. Usuários já autenticados precisarão entrar novamente uma única vez. Antes do restart, confirme no Nginx:

proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
server_tokens off;

Não abra a porta do Node no firewall. Somente Nginx deve alcançar a aplicação local.

Diagnóstico rápido

Incidente

Preserve evidências, limite impacto, evite apagar runtime, identifique a fonte de verdade, aplique correção mínima, valide e documente. Rollback de código não deve restaurar automaticamente um banco para estado anterior.