Ligbox Spec Hub 1f340ef924 docs(dns): sincronizar Spec 037/035 com deploy V1–V3 e V4 pendente

Actualiza dns-viewer, exec/rollback, fichas VM112/122/123, API Console
proxy, token interno wizard e verify script para evitar drift documental.

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-06-25 16:42:07 +00:00

7 KiB

Raw Blame History

DNS Viewer — Rollback (Spec 037-DNS-VIEWER)

Data: 2026-06-25
Spec: 037 · Exec: DNS-VIEWER-V1-20260625
Ambiente: VM122 Desk · VM112 Wizard · VM123 Console (fases V3+) · CT130 Spec Hub

O que muda por fase

Fase	VM	Alteração	Rollback isolado?
V0 (baseline)	VM122	`cloudflare_dns.py` + modal CF em `app.js`	— baseline actual
V1	VM122	`dns_viewer.py` + `GET /api/v1/dns/viewer/{domain}`	✅ feature flag
V1b	VM122	`dns-viewer.js` + UI unificada Desk	✅ frontend only
V2	VM122	`openpanel_dns.py` + provider BIND	✅ desactivar provider
V3	VM123	`/admin/dominio` consome viewer API	✅ frontend Console
V4	VM112	`GET /api/onboarding/dns/viewer/{domain}`	✅ wizard only

Nunca alterado pelo DNS Viewer: CT114 Traefik, pfSense, /etc/network/interfaces Proxmox, zonas Cloudflare reais, OpenPanel BIND dados.

Feature flag (rollback sem redeploy completo)

Variável no .env VM122 (/opt/ligbox-ops-platform/.env):

# 1 = endpoint + UI novo; 0 = só legado CF
DNS_VIEWER_ENABLED=1

Com DNS_VIEWER_ENABLED=0:

GET /api/v1/dns/viewer/{domain} → 404 ou redirect interno para legado
Desk UI usa fetchCloudflareDns + htmlCloudflareDnsCard (V0)
Endpoint legado GET /api/v1/dns/cloudflare/records mantém-se sempre activo até cutover final

Reinício rápido:

ssh root@10.10.10.122
cd /opt/ligbox-ops-platform
sed -i 's/^DNS_VIEWER_ENABLED=.*/DNS_VIEWER_ENABLED=0/' .env
docker compose -f docker-compose.mvp.yml up -d api frontend
# Se alterou ficheiros no host: docker cp api/app/. ligbox-ops-platform_api_1:/app/app/
docker restart ligbox-ops-platform_api_1

Pré-requisitos rollback — verificar backups

Backups criados antes de cada deploy (script preflight-dns-viewer.sh):

ssh root@10.10.10.122
ls -la /opt/ligbox-ops-platform/.backups/dns-viewer-*
docker images | grep -E 'ops-platform|ligbox-ops'

Git CT130:

ssh root@10.10.10.130
cd /opt/ligbox-spec-hub/repos/ligbox-ops-platform
git log --oneline -5
git tag -l 'dns-viewer-*'

Rollback rápido — só frontend Desk (V1b)

Quando a API está OK mas a UI partiu (SyntaxError, modal vazio, «Carregando…» infinito):

ssh root@10.10.10.122
cd /opt/ligbox-ops-platform
BACKUP=$(ls -td .backups/dns-viewer-*/frontend/assets 2>/dev/null | head -1)
if [ -n "$BACKUP" ]; then
  rm -rf frontend/assets/app.js frontend/assets/dns-viewer.js 2>/dev/null
  cp -a "$BACKUP"/. frontend/assets/
fi
docker compose -f docker-compose.mvp.yml build --no-cache frontend
docker compose -f docker-compose.mvp.yml up -d frontend
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8091/

Cache browser: incrementar app.js?v= em frontend/index.html no backup ou manualmente.

Rollback rápido — API Desk (V1)

Quando /dns/viewer devolve 500 ou bloqueia Overview:

ssh root@10.10.10.122
cd /opt/ligbox-ops-platform
BACKUP=$(ls -td .backups/dns-viewer-*/api/app 2>/dev/null | head -1)
if [ -n "$BACKUP" ]; then
  cp -a "$BACKUP"/cloudflare_dns.py api/app/ 2>/dev/null || true
  rm -f api/app/dns_viewer.py api/app/openpanel_dns.py
  # Restaurar main.py do tarball se existir
  if [ -f "$BACKUP/../main.py.bak" ]; then
    cp -a "$BACKUP/../main.py.bak" api/app/main.py
  fi
fi
grep -q DNS_VIEWER_ENABLED=0 .env || echo 'DNS_VIEWER_ENABLED=0' >> .env
docker compose -f docker-compose.mvp.yml build --no-cache api
docker compose -f docker-compose.mvp.yml up -d api
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080/health

Validar legado:

# Com token JWT staff — ou curl interno documentado em verify-dns-viewer.sh
curl -sS 'http://127.0.0.1:8080/api/v1/dns/cloudflare/records?domain=ligbox.com.br' \
  -H "Authorization: Bearer $TOKEN" | head -c 200

Rollback imagem Docker (VM122)

ssh root@10.10.10.122
cd /opt/ligbox-ops-platform
docker tag ligbox-ops-platform-api:pre-dns-viewer-YYYYMMDD ligbox-ops-platform-api:latest
docker compose -f docker-compose.mvp.yml up -d api

Substituir YYYYMMDD pela data do backup em docker images.

Rollback VM112 Wizard (V4 apenas)

ssh root@10.10.10.112
cd /opt/ligbox-wizard
BACKUP=$(ls -td .backups/dns-viewer-* 2>/dev/null | head -1)
if [ -n "$BACKUP" ]; then
  cp -a "$BACKUP"/backend/. backend/
fi
systemctl restart ligbox-wizard 2>/dev/null || docker compose restart backend
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8090/health

Passo DNS wizard volta ao comportamento pré-viewer; provision-zone / apply não são revertidos (só UI/API leitura).

Rollback VM123 Console `/admin/dominio` (V3 apenas)

ssh root@10.10.10.123
cd /opt/ligbox-ops-console
BACKUP=$(ls -td frontend.bak-dns-viewer-* 2>/dev/null | head -1)
if [ -n "$BACKUP" ]; then
  rm -rf frontend
  cp -a "$BACKUP" frontend
fi
docker compose build --no-cache && docker compose up -d
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8100/health

Rota /admin/dominio pode mostrar placeholder ou 404 — não afecta Desk nem wizard apply.

Rollback código (CT130 / monorepo)

cd /opt/ligbox-spec-hub/repos/ligbox-ops-platform
git log --oneline --grep='dns-viewer' -5
git revert <commit-dns-viewer> --no-edit
# ou checkout tag pré-deploy:
git checkout dns-viewer-pre-v1-YYYYMMDD -- projects/ops-desk/

./portal/refresh-spec-driver.sh 2>/dev/null || true
rsync -a specs/037-dns-multi-cloudflare-orchestration/ \
  /opt/ligbox-spec-hub/obsidian-vault/ligbox-ops-platform/specs/037-dns-multi-cloudflare-orchestration/ 2>/dev/null || true

Re-deploy VM122 após revert git (rsync ou pull no host).

Sintomas → acção

Sintoma	Causa provável	Acção
Desk «Carregando…» em todo o site	SyntaxError em `app.js`	Rollback frontend V1b
Modal domínio sem DNS	API 500 viewer	`DNS_VIEWER_ENABLED=0` + rollback API
Overview OK, viewer vazio	CF token / zona	Não rollback — corrigir env; legado igual
403 no viewer	RBAC	Ajustar role, não rollback
Wizard passo DNS partido	V4 VM112	Rollback wizard only
Console `/admin/dominio` branco	V3 VM123	Rollback Console frontend

Validação pós-rollback

# VM122 — script completo
bash specs/037-dns-multi-cloudflare-orchestration/deploy/scripts/verify-dns-viewer.sh \
  --host 10.10.10.122 --legacy-only

Esperado:

GET /health → 200
GET /api/v1/dns/cloudflare/records?domain=... → 200 ou 403 (auth)
Desk Overview abre modal domínio sem erro consola browser
Nenhuma zona Cloudflare alterada (viewer é read-only)

Referências

Exec deploy: DNS-VIEWER-EXEC-20260625.md
Preflight backup: scripts/preflight-dns-viewer.sh
Spec: dns-viewer.md
Console v2 rollback (padrão): specs/019-.../deploy/CONSOLE-V2-ROLLBACK.md

7 KiB Raw Blame History