Pular para o conteúdo principal

Backup do banco de dados

O Bulk Signer pode fazer backup do banco operacional — o histórico dos jobs, os eventos operacionais, as aprovações registradas e as regras de aprovação congeladas em cada job — em um diretório, em um bucket do S3 (ou de um serviço compatível com S3) ou em um container do Azure Blob Storage, por agendamento ou sob demanda. Ele vem desligado por padrão, e só funciona com SQLite.

Cada backup é um arquivo de banco SQLite comum, que qualquer ferramenta SQLite abre; assim, uma restauração nunca depende do próprio Bulk Signer. Não há botão nem endpoint de restauração: restaurar é um procedimento do operador, feito com o serviço parado, e está descrito abaixo.

O que entra no backupO banco operacional inteiro, em um arquivo.
O que não entrainput/, processing/, output/, error/, logs/, os seus certificados e os seus appsettings.*.json. Faça snapshot deles à parte (Retenção).
Qual bancoSó Database:Provider = Sqlite. Com SqlServer, Backup:Enabled = true impede o serviço de iniciar — veja abaixo.
Para onde vaiBackup:Destination = Disk, S3 ou AzureBlob. Um destino por implantação.
O que é um backupbulksigner-<yyyyMMdd-HHmmss>Z.db (o início da execução em UTC) — um arquivo SQLite comum, não criptografado.
Quando rodaA cada Backup:IntervalHours, mais o Fazer backup agora do dashboard e o POST /api/backup. Sem intervalo, os backups são só manuais.
Quantos são mantidosBackup:RetainCount, padrão 14. 0 mantém todos, para um bucket ou container cujas próprias regras de ciclo de vida fazem a limpeza.
O que é registradoUma entrada de histórico por execução concluída — Succeeded, Failed ou Canceled — com o SHA-256 do arquivo de backup.

Todas as chaves estão em Configuração; a página /backup está descrita em Dashboard.

Com SQL Server, use os backups do seu banco​

Com Database:Provider = SqlServer, esta funcionalidade não se aplica, e Backup:Enabled = true impede o serviço de iniciar, com uma mensagem que cita as duas chaves, em vez de não fazer nada em silêncio. Faça o backup do banco com as ferramentas do próprio SGBD:

BancoUse
SQL Server (on-premises ou em uma VM)BACKUP DATABASE … TO DISK = …, com o seu agendamento e a sua retenção.
Azure SQL DatabaseOs backups automáticos dele, mais um ponto de restauração criado antes de cada atualização do Bulk Signer.

O login do serviço no banco tem só db_datareader, db_datawriter e db_ddladmin em um banco — não as permissões de servidor que um backup exige. A página /backup continua existindo em uma implantação assim e informa de quem é a tarefa do backup.

Ligando o backup​

Três coisas decidem tudo: a chave de ativação, o destino e se há agendamento.

Em um diretório — Disk​

"Backup": {
"Enabled": true,
"Destination": "Disk",
"IntervalHours": 24,
"RetainCount": 14,
"Disk": { "Path": "/backup/bulksigner" } // um volume que não seja o do banco
}

Backup:Disk:Path não tem padrão, e o serviço não inicia sem ele: qualquer padrão plausível poria o backup no mesmo disco do banco. A conta com que o serviço roda precisa de permissão de escrita nele — bulksigner na unit do Linux, NT SERVICE\LacunaBulkSigner no Windows, ou o UID 1654 no container. O diretório é criado se não existir. Um caminho UNC ou um volume de rede montado funciona.

Três caminhos são recusados na inicialização:

  • Dentro de uma pasta de entrada monitorada. Um arquivo .db gravado ali seria capturado, assinado e depois excluído da pasta como qualquer outra entrada — o pipeline consumiria o backup.
  • Dentro de processing/, output/, error/ ou db/. O serviço cria, varre e remove essas árvores.
  • Um local azurefiles://. Monte o compartilhamento e informe o caminho da montagem, ou use AzureBlob.

Em um bucket do S3 — S3​

"Backup": {
"Enabled": true,
"Destination": "S3",
"IntervalHours": 24,
"RetainCount": 30,
"S3": {
"BucketName": "contoso-bulksigner-backups",
"Region": "sa-east-1",
"Prefix": "bulksigner/",
"Credential": "AccessKey", // ou InstanceRole
"AccessKeyId": "AKIA…"
}
}

com Backup__S3__SecretAccessKey no ambiente. O modo de credencial nunca tem padrão: escreva AccessKey ou InstanceRole. Com InstanceRole, deixar uma chave de acesso configurada é recusado.

A política do IAM precisa de quatro ações. A s3:ListBucket vale para o bucket, e não para as chaves dele, e é a que mais se esquece; a s3:GetObject é necessária porque o serviço confere se um nome já existe antes de gravar.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
"Resource": "arn:aws:s3:::contoso-bulksigner-backups/bulksigner/*"
},
{
"Effect": "Allow",
"Action": "s3:ListBucket",
"Resource": "arn:aws:s3:::contoso-bulksigner-backups"
}
]
}

Para um serviço compatível com S3 (MinIO, Ceph, Wasabi, Backblaze B2), defina ServiceUrl com o endpoint da API dele — não o console web — e, em quase todos, ForcePathStyle: true. A Region passa a ser opcional. As mesmas ações da política valem.

Em um container do Azure Blob — AzureBlob​

"Backup": {
"Enabled": true,
"Destination": "AzureBlob",
"IntervalHours": 24,
"RetainCount": 30,
"AzureBlob": {
"ContainerUrl": "https://contoso.blob.core.windows.net/bulksigner-backups",
"Prefix": "prod/",
"Credential": "ManagedIdentity" // ou ServicePrincipal / AccountKey
}
}

ContainerUrl é a URL do container como o botão Copy URL do portal a fornece: https://, exatamente um container e nenhuma query string — uma shared access signature não é aceita. Coloque qualquer caminho dentro do container em Prefix.

  • O role é Storage Blob Data Contributor. Um backup é gravado, listado e limpo; por isso, o role de leitura de que um blob de certificado precisa não basta: uma identidade só com Storage Blob Data Reader falha no primeiro backup.
  • ManagedIdentity é a identidade atribuída pelo sistema, e não guarda nada no host. AccountKey dá acesso à conta de armazenamento inteira; prefira as outras duas.
  • O container não é criado para você. Crie-o, com a política de acesso e o ciclo de vida que você quiser, e então conceda o role.

Segredos​

Backup__S3__SecretAccessKey, Backup__AzureBlob__AppSecret e Backup__AzureBlob__AccountKey ficam em variáveis de ambiente (ou em um appsettings.Production.json fora do controle de versão). Eles protegem cópias completas do banco — veja Segurança.

O que o banner de inicialização mostra​

O resumo de inicialização traz uma linha backup, que nunca mostra uma credencial:

backup = Disk → /backup/bulksigner (every 24h, keeping 14)
backup = S3 → backups/bulksigner/ at minio.internal:9000 (manual only, keeping every artifact)
backup = disabled
backup = not applicable (Database:Provider = SqlServer — your DBMS regime's job)

Como os backups rodam​

  • Uma cópia consistente. A cópia usa o backup online do SQLite; assim, um backup feito com jobs em andamento é o retrato de um único estado confirmado. Um arquivo de banco ausente é informado como falha, nunca copiado como um banco vazio.
  • Nunca sobrescrito. Um nome de backup que já existe no destino faz a execução falhar. Dê a cada implantação o próprio diretório, bucket ou container, ou pelo menos o próprio Prefix.
  • Um intervalo, não um horário. Backup:IntervalHours (de 1 a 8760) conta a partir do último backup bem-sucedido, lido do histórico — então um serviço que reinicia toda noite continua fazendo um backup por intervalo, e uma execução que falhou é repetida um intervalo depois do último sucesso, e não da falha. Uma implantação que nunca fez backup está atrasada desde já. Intervalos perdidos são pulados, nunca acumulados. Um backup pode começar até cinco minutos depois da hora.
  • Retenção por quantidade. Depois de cada execução bem-sucedida, todos os backups menos os Backup:RetainCount mais novos são excluídos. Só arquivos que seguem o padrão de nome acima são excluídos. Uma exclusão que falha não faz a execução falhar — ela é registrada como aviso no log e contada (veja Monitoramento).
  • Uma execução por vez. Um segundo Fazer backup agora com outro em andamento é recusado com backup.already-running.
  • Cancelar é um pedido. Ele é atendido entre as etapas e durante todo o envio e a limpeza, mas não durante a cópia local, que leva segundos em um banco típico. O dashboard mostra cancelamento solicitado até a execução parar; um host que está desligando cancela a execução da mesma forma. Os dois casos ficam registrados como Canceled, e não Failed.
  • Só execuções concluídas são registradas. Um processo encerrado no meio da execução não deixa entrada no histórico; o log tem o que ele fez. Nada exclui entradas do histórico.

Fazendo um backup agora​

No dashboard, a página /backup tem Fazer backup agora quando nada está rodando e Cancelar execução quando algo está. Por REST, com a chave de API do operador:

MétodoCaminhoFinalidade
GET/api/backupA configuração, a execução em andamento (se houver), a última execução bem-sucedida e as 50 execuções concluídas mais recentes.
POST/api/backupInicia uma execução. 202 assim que ela é aceita — consulte o GET para saber o resultado.
POST/api/backup/cancelPede que a execução em andamento pare.
curl -X POST https://bulksigner.example.com/api/backup -H "X-API-Key: $BULK_SIGNER_API_KEY"
curl -s https://bulksigner.example.com/api/backup -H "X-API-Key: $BULK_SIGNER_API_KEY"

As recusas são backup.disabled (a chave está desligada, ou o provider é SqlServer), backup.already-running e backup.not-running, todas 409. O formato completo da resposta está em API REST.

Restaurando um backup​

Restaurar volta o registro no tempo

Tudo o que o banco registrou depois do backup se perde: jobs, histórico, eventos operacionais, as aprovações registradas e as regras de aprovação congeladas, e o próprio histórico de backups. Guarde o arquivo que você substituir — ele é a única cópia de tudo o que foi registrado desde então.

1. Encontre a execução e o SHA-256 dela. Na página /backup, ou:

curl -s https://bulksigner.example.com/api/backup -H "X-API-Key: $BULK_SIGNER_API_KEY" \
| jq -r '.history[] | select(.status=="Succeeded") | "\(.completedAtUtc) \(.artifactName) \(.sha256)"'

2. Pare o serviço. Um arquivo SQLite não pode ser substituído com o serviço rodando.

sudo systemctl stop bulksigner # Linux
Stop-Service LacunaBulkSigner # Windows (PowerShell)
docker compose stop bulksigner # Docker

3. Busque o backup.

# Disk — já é um arquivo
cp /backup/bulksigner/bulksigner-20260812-021530Z.db /tmp/restore.db

# S3
aws s3 cp s3://contoso-bulksigner-backups/bulksigner/bulksigner-20260812-021530Z.db /tmp/restore.db

# Compatível com S3 (MinIO)
aws --endpoint-url https://minio.internal:9000 \
s3 cp s3://bulksigner-backups/bulksigner-20260812-021530Z.db /tmp/restore.db

# Azure Blob Storage
az storage blob download --account-name contoso --container-name bulksigner-backups \
--name prod/bulksigner-20260812-021530Z.db --file /tmp/restore.db --auth-mode login

4. Confira o SHA-256 com a entrada do histórico — antes de substituir qualquer coisa.

sha256sum /tmp/restore.db
(Get-FileHash .\restore.db -Algorithm SHA256).Hash.ToLower()

Uma diferença significa que este não é o arquivo que a entrada do histórico descreve — um download truncado, o arquivo errado —, e ele não deve ser restaurado. Depois, confira se ele abre:

sqlite3 /tmp/restore.db "pragma integrity_check; select count(*) from Jobs;"

5. Coloque-o no lugar, guardando o arquivo que você substituir:

sudo -u bulksigner mv /var/lib/bulksigner/db/bulksigner.db \
/var/lib/bulksigner/db/bulksigner.db.replaced-$(date -u +%Y%m%dT%H%M%SZ)
sudo install -o bulksigner -g bulksigner -m 0640 /tmp/restore.db /var/lib/bulksigner/db/bulksigner.db

Exclua os arquivos bulksigner.db-wal e bulksigner.db-shm que tenham ficado ao lado do banco antigo — eles pertencem ao arquivo que você tirou do lugar. No Windows, o banco fica em C:\ProgramData\Lacuna\BulkSigner\data\db\bulksigner.db; na árvore do Docker, em data/db/bulksigner.db, com o UID 1654 como dono.

6. Inicie o serviço e confira a prontidão. As migrações rodam na inicialização; assim, um backup de uma versão anterior é atualizado nesta inicialização — sem volta, como toda atualização.

sudo systemctl start bulksigner
curl -s https://bulksigner.example.com/api/ready

7. Reconcilie o processing/. A recuperação na inicialização trabalha a partir dos registros de jobs, e o banco restaurado tem outro conjunto deles: um diretório que sobrou de um job que o banco restaurado não conhece não é limpo por nada, então inspecione e limpe-o manualmente. Um job que aguardava aprovação quando o backup foi feito volta aguardando aprovação, sem as decisões tomadas depois.

Pratique. Copie um backup para um host de teste, confira o digest, abra-o e leia o histórico de um job nele. A primeira restauração não deve ser a que importa.

O que um backup contém​

Um backup é uma cópia completa do banco operacional e, por isso, a maior concentração de dados pessoais que o Bulk Signer grava em um único arquivo: todas as aprovações registradas (quem, quando, de qual endereço IP e navegador), o nome, o e-mail e o CPF de cada aprovador, as linhas de pagamento CNAB240 dos arquivos ainda em andamento (nomes dos favorecidos, CPF/CNPJ e contas) e o nome do arquivo e o histórico de cada job. O mascaramento na página de aprovação é uma regra de exibição; nada é mascarado no banco nem no backup.

  • O controle de acesso do destino faz parte do seu perímetro de segurança. Use um bucket, container ou diretório que ninguém mais use, e restrinja o role ou a ACL a ele.
  • As credenciais dele são as mais sensíveis do produto — elas abrem todos os backups de uma vez.
  • Ligue a criptografia em repouso no destino: SSE-S3 ou SSE-KMS no bucket, a criptografia do Azure Storage (com uma chave gerenciada pelo cliente, se a sua política pedir) no container. O arquivo de backup em si não é criptografado, para que ninguém nunca tenha um backup que não consegue abrir.

Monitoramento​

Cinco instrumentos Prometheus em /api/metrics:

MétricaTipoO que ela acompanha
bulksigner_backup_runs_total{result}CounterExecuções concluídas: Succeeded, Failed, Canceled.
bulksigner_backup_duration_secondsHistogramDuração das execuções bem-sucedidas.
bulksigner_backup_last_size_bytesGaugeTamanho do último backup que esta instância gravou.
bulksigner_backup_last_success_timestamp_secondsGaugeHorário Unix do último backup bem-sucedido deste processo; 0 até haver um.
bulksigner_backup_prune_failures_totalCounterExecuções cujo backup foi gravado, mas cuja limpeza dos backups antigos falhou.

O alerta a criar é sobre o horário, que continua envelhecendo mesmo se o próprio serviço parou:

# Nenhum backup bem-sucedido em 48 horas (use com for: 30m para que uma reinicialização não dispare)
bulksigner_backup_last_success_timestamp_seconds > 0
and time() - bulksigner_backup_last_success_timestamp_seconds > 172800

# O destino passou a recusar gravações
increase(bulksigner_backup_runs_total{result="Failed"}[6h]) > 0

# Os backups funcionam, mas os antigos não estão sendo excluídos
increase(bulksigner_backup_prune_failures_total[24h]) > 0

O gauge é por processo e volta a 0 depois de uma reinicialização; a resposta durável é o lastSuccessAtUtc do GET /api/backup e o histórico da página /backup. Em uma implantação SqlServer, os cinco ficam em zero.

Diagnóstico de problemas​

Comece pela /backup. Quando você a abre ou atualiza, a página confere o destino e diz o que está errado — um diretório em que não consegue gravar, um bucket que respondeu 403, um container ausente, uma credencial que não conseguiu obter. Essa conferência não prova uma gravação no S3 nem no Azure Blob, e um problema no destino nunca impede o serviço de iniciar: depois de configurar, use Fazer backup agora — a primeira execução é o teste de verdade.

SintomaCausaCorreção
Inicialização recusada: Backup:Enabled = true is not supported when Database:Provider = SqlServerO provider foi trocado e o backup ficou ligadoDefina Backup:Enabled = false e use os backups do seu banco.
Inicialização recusada: Backup:Disk:Path is requiredNão há padrãoIndique um diretório em um volume diferente do do banco.
Inicialização recusada: Backup:Disk:Path … is inside the watched input folder …O pipeline assinaria e depois excluiria o backupEscolha um diretório fora de todas as pastas monitoradas.
Inicialização recusada: Backup:Disk:Path … is inside the pipeline's processing/output/error folder ou no diretório do próprio bancoO serviço varre essas árvoresEscolha um diretório fora do Storage:Root.
Inicialização recusada em Backup:S3:Region, Backup:S3:Credential, ou por uma chave definida com InstanceRoleA região e a credencial nunca têm padrão; uma chave não usada é recusadaEscreva a região (ou defina ServiceUrl), escreva AccessKey ou InstanceRole e remova as chaves que o modo não usa.
Inicialização recusada: Backup:AzureBlob:ContainerUrl … must not carry a query string ou must name exactly one containerFoi colada uma URL com SAS ou a URL de um blobInforme a URL simples do container; coloque um caminho em Prefix.
Execução Failed citando s3:PutObject, s3:GetObject and s3:DeleteObjectFalta uma ação no IAM — normalmente a s3:ListBucket no bucketAplique a política acima.
Execução Failed no Azure, com uma identidade que tem Storage Blob Data ReaderO role de leitura lista, mas não gravaConceda Storage Blob Data Contributor.
Execução Failed: The backup container '…' does not existContainers não são criados automaticamenteCrie-o e então conceda o role.
Execução Failed: The backup directory '…' refused a writeA conta do serviço não tem permissão de escritaConceda escrita à conta com que o serviço roda.
Execução Failed: The operational store '…' does not existConnectionStrings:Default aponta para um arquivo inexistenteCorrija a connection string.
Execução Failed: An artifact named '…' is already at '…'Duas implantações compartilham um destino, ou o relógio voltouDê a cada implantação o próprio destino ou Prefix.
Um backup agendado não rodou, e não há entrada no históricoO processo parou no meio da execução; só execuções concluídas são registradasLeia o log daquela execução.
409 backup.already-running em toda tentativaUm banco grande em um link lento ainda está sendo enviadoAcompanhe phase no GET /api/backup; cancele se o destino estiver fora do ar.
Um cancelamento foi aceito e a execução continuouO cancelamento não é atendido durante a cópia localEspere a entrada Canceled.
Mais backups no destino do que RetainCountUma exclusão falhouConfira bulksigner_backup_prune_failures_total e o log; conceda a permissão de exclusão (s3:DeleteObject, ou Contributor).
Um arquivo .db grande em data/backup-staging/Um processo foi encerrado no meio da execuçãoExclua-o — ele é uma cópia completa do banco.

A seguir: Retenção. Anterior: Aprovações.

Ver em Markdown