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 backup | O banco operacional inteiro, em um arquivo. |
| O que não entra | input/, processing/, output/, error/, logs/, os seus certificados e os seus appsettings.*.json. Faça snapshot deles à parte (Retenção). |
| Qual banco | Só Database:Provider = Sqlite. Com SqlServer, Backup:Enabled = true impede o serviço de iniciar — veja abaixo. |
| Para onde vai | Backup:Destination = Disk, S3 ou AzureBlob. Um destino por implantação. |
| O que é um backup | bulksigner-<yyyyMMdd-HHmmss>Z.db (o início da execução em UTC) — um arquivo SQLite comum, não criptografado. |
| Quando roda | A 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 mantidos | Backup: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 é registrado | Uma 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:
| Banco | Use |
|---|---|
| SQL Server (on-premises ou em uma VM) | BACKUP DATABASE … TO DISK = …, com o seu agendamento e a sua retenção. |
| Azure SQL Database | Os 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
.dbgravado ali seria capturado, assinado e depois excluído da pasta como qualquer outra entrada — o pipeline consumiria o backup. - Dentro de
processing/,output/,error/oudb/. O serviço cria, varre e remove essas árvores. - Um local
azurefiles://. Monte o compartilhamento e informe o caminho da montagem, ou useAzureBlob.
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ó comStorage Blob Data Readerfalha no primeiro backup. ManagedIdentityé a identidade atribuída pelo sistema, e não guarda nada no host.AccountKeydá 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:RetainCountmais 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ãoFailed. - 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étodo | Caminho | Finalidade |
|---|---|---|
GET | /api/backup | A 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/backup | Inicia uma execução. 202 assim que ela é aceita — consulte o GET para saber o resultado. |
POST | /api/backup/cancel | Pede 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
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étrica | Tipo | O que ela acompanha |
|---|---|---|
bulksigner_backup_runs_total{result} | Counter | Execuções concluídas: Succeeded, Failed, Canceled. |
bulksigner_backup_duration_seconds | Histogram | Duração das execuções bem-sucedidas. |
bulksigner_backup_last_size_bytes | Gauge | Tamanho do último backup que esta instância gravou. |
bulksigner_backup_last_success_timestamp_seconds | Gauge | Horário Unix do último backup bem-sucedido deste processo; 0 até haver um. |
bulksigner_backup_prune_failures_total | Counter | Execuçõ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.
| Sintoma | Causa | Correção |
|---|---|---|
Inicialização recusada: Backup:Enabled = true is not supported when Database:Provider = SqlServer | O provider foi trocado e o backup ficou ligado | Defina Backup:Enabled = false e use os backups do seu banco. |
Inicialização recusada: Backup:Disk:Path is required | Não há padrão | Indique 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 backup | Escolha 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 banco | O serviço varre essas árvores | Escolha um diretório fora do Storage:Root. |
Inicialização recusada em Backup:S3:Region, Backup:S3:Credential, ou por uma chave definida com InstanceRole | A região e a credencial nunca têm padrão; uma chave não usada é recusada | Escreva 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 container | Foi colada uma URL com SAS ou a URL de um blob | Informe a URL simples do container; coloque um caminho em Prefix. |
Execução Failed citando s3:PutObject, s3:GetObject and s3:DeleteObject | Falta uma ação no IAM — normalmente a s3:ListBucket no bucket | Aplique a política acima. |
Execução Failed no Azure, com uma identidade que tem Storage Blob Data Reader | O role de leitura lista, mas não grava | Conceda Storage Blob Data Contributor. |
Execução Failed: The backup container '…' does not exist | Containers não são criados automaticamente | Crie-o e então conceda o role. |
Execução Failed: The backup directory '…' refused a write | A conta do serviço não tem permissão de escrita | Conceda escrita à conta com que o serviço roda. |
Execução Failed: The operational store '…' does not exist | ConnectionStrings:Default aponta para um arquivo inexistente | Corrija a connection string. |
Execução Failed: An artifact named '…' is already at '…' | Duas implantações compartilham um destino, ou o relógio voltou | Dê a cada implantação o próprio destino ou Prefix. |
| Um backup agendado não rodou, e não há entrada no histórico | O processo parou no meio da execução; só execuções concluídas são registradas | Leia o log daquela execução. |
409 backup.already-running em toda tentativa | Um banco grande em um link lento ainda está sendo enviado | Acompanhe phase no GET /api/backup; cancele se o destino estiver fora do ar. |
| Um cancelamento foi aceito e a execução continuou | O cancelamento não é atendido durante a cópia local | Espere a entrada Canceled. |
Mais backups no destino do que RetainCount | Uma exclusão falhou | Confira 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ção | Exclua-o — ele é uma cópia completa do banco. |
A seguir: Retenção. Anterior: Aprovações.