---
title: "Backup do banco de dados"
description: "Faça backup do banco operacional SQLite do Bulk Signer em um diretório, um bucket do S3 ou um container do Azure Blob, monitore-o e restaure um backup manualmente."
canonical: "https://docs.lacunasoftware.com/articles/bulk-signer/backup"
locale: "pt-BR"
product: "Bulk Signer"
last_updated: "2026-11-18"
---

# 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](https://docs.lacunasoftware.com/articles/bulk-signer/backup#restaurando-um-backup).

| | |
|---|---|
| **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](https://docs.lacunasoftware.com/articles/bulk-signer/retention#disciplina-de-backup)). |
| **Qual banco** | Só `Database:Provider = Sqlite`. Com `SqlServer`, `Backup:Enabled = true` impede o serviço de iniciar — [veja abaixo](https://docs.lacunasoftware.com/articles/bulk-signer/backup#com-sql-server-use-os-backups-do-seu-banco). |
| **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](https://docs.lacunasoftware.com/articles/bulk-signer/configuration#backup); a página `/backup` está descrita em
[Dashboard](https://docs.lacunasoftware.com/articles/bulk-signer/dashboard#backup--backup-do-banco-de-dados).

## 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`

```jsonc
"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`

```jsonc
"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.

```json
{
  "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`

```jsonc
"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](https://docs.lacunasoftware.com/articles/bulk-signer/security).

### O que o banner de inicialização mostra

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

```text
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](https://docs.lacunasoftware.com/articles/bulk-signer/backup#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é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. |

```bash
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](https://docs.lacunasoftware.com/articles/bulk-signer/rest-api#backup).

## Restaurando um backup

> **Perigo: 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:

```bash
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.

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

**3. Busque o backup.**

```bash
# 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.**

```bash
sha256sum /tmp/restore.db
```

```powershell
(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:

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

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

```bash
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.

```bash
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:

```promql
# 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](https://docs.lacunasoftware.com/articles/bulk-signer/backup#com-sql-server-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](https://docs.lacunasoftware.com/articles/bulk-signer/backup#em-um-bucket-do-s3--s3). |
| 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](https://docs.lacunasoftware.com/articles/bulk-signer/retention).
**Anterior:** [Aprovações](https://docs.lacunasoftware.com/articles/bulk-signer/approvals).
