Pular para conteúdo

Runbook de publicação, backup e rollback do SIGESC Docs

Objetivo

Definir o procedimento canônico para publicar docs.sigesc.aprenderdigital.top com rastreabilidade, backup incremental, validação, recuperação do estado operacional e possibilidade de reversão.

Este runbook separa claramente:

  1. aprovação do conteúdo no GitHub;
  2. preparação ou recuperação de uma estação operacional;
  3. dry-run da publicação;
  4. autorização humana para execução real;
  5. backup e deploy incremental;
  6. validação pública;
  7. rollback quando necessário.

Princípios obrigatórios

  • main é a fonte canônica aprovada.
  • Nenhuma publicação deve partir de branch não integrada.
  • O GitHub Actions valida a documentação, mas não publica em produção.
  • Toda publicação real exige autorização humana explícita.
  • Toda reversão real exige autorização humana explícita.
  • Credenciais FTPS nunca devem ser gravadas em Git, .env, script, log ou documentação.
  • O dry-run é obrigatório antes de -Execute.
  • Alterados e removidos devem possuir backup validado antes de qualquer mutação remota.
  • Drift entre manifesto e servidor interrompe a operação em modo fail-closed.

Componentes canônicos

Publicação:

scripts/publish-docs-incremental.py
scripts/publish-docs-incremental.ps1

Rollback:

scripts/rollback-docs-incremental.py
scripts/rollback-docs-incremental.ps1

Estado do manifesto:

scripts/production-manifest-state.py

Homologação sem FTPS:

scripts/homologate-clean-workstation.py

O manifesto operacional que representa o último estado validado em produção é:

artifacts/production/production-manifest.json

Ele é ignorado pelo Git porque pertence ao estado operacional da publicação, não ao código-fonte.

1. Estação limpa e recuperação do manifesto

Um clone limpo consegue instalar dependências e executar mkdocs build --strict, mas não consegue calcular o delta real de produção enquanto não possuir o production-manifest.json correspondente ao último estado validado do portal.

Essa dependência é intencional e agora possui procedimento explícito.

1.1 Exportar o manifesto de uma estação operacional

Em uma estação que contenha o manifesto válido:

python .\scripts\production-manifest-state.py export `
    --output "<DESTINO_SEGURO>\production-manifest.json"

O utilitário:

  • valida estrutura, caminhos, tamanhos e SHA-256;
  • exige index.html;
  • impede caminhos absolutos e ..;
  • copia o arquivo de forma atômica;
  • confirma SHA-256 da cópia.

O manifesto não contém senha FTPS. Mesmo assim, deve ser tratado como estado operacional e preservado junto às evidências de publicação.

1.2 Validar uma cópia portátil

python .\scripts\production-manifest-state.py validate `
    --source "<COPIA>\production-manifest.json"

1.3 Importar em um clone limpo

python .\scripts\production-manifest-state.py import `
    --source "<COPIA>\production-manifest.json"

Destino padrão:

artifacts/production/production-manifest.json

O comando falha se o destino já existir. --force só deve ser usado depois de confirmar que a cópia representa um estado mais recente e validado.

1.4 Homologação automatizada

O CI executa:

python scripts/homologate-clean-workstation.py

Esse teste roda em checkout limpo e usa somente fixtures sintéticas. Ele prova:

  • mkdocs build --strict;
  • criação de um manifesto operacional sintético;
  • dry-run real do publicador canônico;
  • ausência de conexão FTPS e de solicitação de senha;
  • geração de delta;
  • validação local de backup sintético;
  • dry-run real do rollback canônico;
  • limpeza dos artefatos de teste.

O teste nunca usa --execute e não altera produção.

2. Pré-condições para uma publicação real

Antes de publicar:

  • PR correspondente integrado em main;
  • Docs CI verde;
  • repositório local sincronizado com origin/main;
  • ambiente Python/MkDocs funcional;
  • production-manifest.json existente e validado;
  • nenhuma credencial armazenada em arquivo.

No PowerShell:

git status
git switch main
git pull --ff-only origin main
python .\scripts\production-manifest-state.py validate `
    --source .\artifacts\production\production-manifest.json

O git status deve estar limpo quanto às fontes versionadas. Artefatos ignorados em site/ e artifacts/ podem existir.

3. Dry-run obrigatório

Execute:

.\scripts\publish-docs-incremental.ps1

O controlador executará:

  1. mkdocs build --strict;
  2. validação dos arquivos críticos;
  3. leitura do manifesto de produção;
  4. cálculo de SHA-256 do build;
  5. geração do delta;
  6. classificação em novos, alterados, removidos e inalterados.

Sem -Execute:

  • não abre conexão FTPS quando há alterações;
  • não solicita senha;
  • não baixa arquivos;
  • não envia arquivos;
  • não remove arquivos.

O delta fica em:

artifacts/deploy-delta/deploy-delta-v2-*.json

Gate humano

Antes da execução real, revisar especialmente:

  • quantidade de arquivos novos;
  • quantidade de alterados;
  • quantidade de removidos;
  • lista de removidos;
  • presença inesperada de grandes deltas.

Qualquer remoção não compreendida deve interromper a publicação.

4. Execução real

Somente após autorização explícita:

.\scripts\publish-docs-incremental.ps1 -Execute

A senha FTPS é solicitada uma única vez e permanece apenas em memória do processo.

Ordem operacional

O controlador executa:

  1. build estrito novamente;
  2. novo cálculo do delta;
  3. conexão FTPS;
  4. backup dos arquivos alterados e removidos;
  5. validação SHA-256 do backup contra o manifesto anterior;
  6. verificação de que arquivos classificados como novos realmente não existem remotamente;
  7. upload de novos e alterados;
  8. index.html por último;
  9. remoção dos arquivos previstos no delta;
  10. validação pública;
  11. atualização atômica do manifesto de produção apenas após PASS.

Após uma publicação validada, exporte uma nova cópia portátil do manifesto para que outra estação possa assumir a operação sem depender do computador atual.

5. Backup incremental

Para cada publicação com alterações, o controlador cria:

artifacts/delta-backups/delta-backup-v2-YYYYMMDD_HHMMSS/

Estrutura:

delta-backup-v2-.../
├── delta-backup-manifest.json
└── files/
    └── <arquivos anteriores alterados/removidos>

Arquivos novos não precisam de backup porque não existiam no estado anterior; em rollback, eles são removidos.

6. Validação pública

A publicação só é considerada concluída quando o controlador confirma:

  • HTTP 200 na página inicial;
  • HTTP 200 no índice de busca;
  • HTTP 200 no sitemap;
  • HTTP 200 no SKF;
  • SHA-256 do index.html público igual ao index.html do build local.

Somente depois disso production-manifest.json é substituído pelo manifesto do novo estado.

7. Quando acionar rollback

Rollback é indicado quando:

  • a validação pública falha;
  • uma página crítica fica inconsistente;
  • o deploy é interrompido depois de alguma mutação remota;
  • uma publicação validada precisa ser revertida por decisão operacional.

Não tente corrigir manualmente arquivos individuais no servidor antes de preservar os artefatos do delta e do backup.

8. Identificar o par delta + backup

Get-ChildItem .\artifacts\deploy-delta\deploy-delta-v2-*.json |
    Sort-Object LastWriteTime -Descending |
    Select-Object -First 5 FullName, LastWriteTime

Get-ChildItem .\artifacts\delta-backups\delta-backup-v2-* -Directory |
    Sort-Object LastWriteTime -Descending |
    Select-Object -First 5 FullName, LastWriteTime

Confirme o vínculo lendo:

Get-Content "<PASTA_BACKUP>\delta-backup-manifest.json"

O campo delta deve corresponder ao delta da publicação que será revertida.

9. Dry-run do rollback

.\scripts\rollback-docs-incremental.ps1 `
    -Delta "<DELTA_JSON>" `
    -Backup "<PASTA_DELTA_BACKUP>"

O controlador verificará localmente:

  • integridade estrutural do delta;
  • presença do manifesto de backup;
  • cobertura de todos os arquivos alterados/removidos;
  • tamanho e SHA-256 dos arquivos de backup;
  • conjunto de arquivos novos que serão removidos;
  • reconstrução do manifesto anterior.

Nenhuma conexão FTPS é aberta no dry-run.

10. Execução do rollback

Somente após autorização explícita:

.\scripts\rollback-docs-incremental.ps1 `
    -Delta "<DELTA_JSON>" `
    -Backup "<PASTA_DELTA_BACKUP>" `
    -Execute

O rollback:

  1. restaura os arquivos alterados;
  2. restaura os arquivos removidos;
  3. remove arquivos novos da publicação revertida;
  4. restaura index.html por último entre os recuperados;
  5. valida a página pública contra o SHA-256 anterior;
  6. somente após validação atualiza o manifesto local para o estado anterior.

11. Logs e evidências

artifacts/incremental-deploy-logs/
artifacts/rollback-logs/
artifacts/deploy-delta/
artifacts/delta-backups/
artifacts/production/production-manifest.json

Esses artefatos não pertencem ao Git, mas devem ser preservados pelo período necessário à rastreabilidade operacional. O manifesto deve possuir ao menos uma cópia portátil validada para recuperação de estação.

12. Scripts depreciados

Não usar para novas publicações:

scripts/publish-docs.ps1
scripts/backup-docs-ftps.py
scripts/deploy-docs-ftps.py
scripts/calculate-deploy-delta.py
scripts/backup-deploy-delta.py
scripts/deploy-deploy-delta.py

cleanup-docs-ftps.py é uma ferramenta histórica específica de limpeza SKF e não faz parte da publicação normal.

Os antigos scripts FTPS da raiz já foram removidos após a consolidação do fluxo canônico.

13. Proibições

Não:

  • executar mkdocs gh-deploy para produção;
  • editar diretamente site/ e enviar arquivos avulsos;
  • remover arquivo remoto fora do delta calculado;
  • ignorar drift apontado pelo controlador;
  • registrar senha FTPS em comando, script, print, captura ou documento;
  • substituir manualmente o manifesto de produção antes da validação pública;
  • executar a homologação de estação limpa sobre uma estação que já contenha artifacts/ operacional.

14. Critério de publicação concluída

Uma publicação está concluída somente quando:

  • build estrito: PASS;
  • delta revisado;
  • backup incremental: PASS, quando necessário;
  • deploy incremental: PASS;
  • validação pública: PASS;
  • SHA-256 público: PASS;
  • manifesto de produção atualizado pelo controlador;
  • cópia portátil do manifesto atualizada;
  • log final preservado.

Se qualquer item falhar depois de uma mutação remota, tratar a execução como incompleta e avaliar rollback antes de nova publicação.