Configuração¶

Esta página cobre as variáveis de ambiente do container, as montagens que o template fornece, o backup de VMs por SSH e a configuração do externo. Os caminhos de repositório de backup são configurados dentro da aplicação (Definições, Armazenamento, Caminhos de backup), não através de variáveis de ambiente.

Variáveis de ambiente¶

Variável	Obrigatória	Descrição
`APP_KEY`	Sim	Segredo hexadecimal de 32 bytes (64 caracteres hex) usado para derivar a palavra-passe do repo restic. Gere com `openssl rand -hex 32`. Guarde-a em segurança: perdê-la torna os backups encriptados irrecuperáveis.
`LIBVIRT_HOST`	Para VMs e conjuntos de dados ZFS	Host do Unraid alcançado por SSH para o backup de VMs (predefinição `host.docker.internal`; o template pré-preenche um placeholder de IP LAN). Use o IP LAN do seu Unraid, obrigatório numa rede `br0.x` personalizada. Também usado pelas cópias de conjuntos de dados ZFS (campo do template Host SSH: Address); o marcador `192.168.x.x` conta como não definido.
`LIBVIRT_SSH_PORT`	Não	Porta SSH do host para o backup de VMs (predefinição `22`). Campo do template Host SSH: Port, também para conjuntos de dados ZFS.
`LIBVIRT_SSH_USER`	Não	Utilizador SSH no host para o backup de VMs (predefinição `root`). Campo do template Host SSH: User, também para conjuntos de dados ZFS.
`LIBVIRT_URI`	Não	URI de ligação libvirt completo, usado textualmente em vez de o construir a partir das três variáveis `LIBVIRT_*` acima (que são então ignoradas para a string de ligação). Não definido por predefinição. Necessário no TrueNAS Scale, cujo libvirtd escuta num socket não padrão que a forma construída não consegue exprimir: `qemu+ssh://<user>@<truenas-host>/system?socket=/run/truenas_libvirt/libvirt-sock`. Consulte a secção do TrueNAS Scale em docs/vm-backup-ssh-setup.md. Se for um URI `qemu+ssh://`, cada uma de `LIBVIRT_HOST`, `LIBVIRT_SSH_USER` e `LIBVIRT_SSH_PORT` que não esteja definida é tirada dele, também para os próprios comandos SSH do BombVault (transferência de NVRAM, conjuntos de dados ZFS).
`PORT`	Não	Porta HTTP (predefinição `3000`; usada apenas com `HTTP_ONLY=true`).
`HTTPS_PORT`	Não	Porta HTTPS (predefinição `3443`; o template publica-a 1:1, por isso a WebUI responde em `https://<ip>:3443`).
`HTTP_ONLY`	Não	Defina `true` para desativar o listener HTTPS autoassinado e servir apenas HTTP simples (para uso por trás de um proxy reverso que termina o TLS).
`BIND_HOST`	Não	Endereço em que a WebUI escuta (predefinição `0.0.0.0`, todas as interfaces). Deixe-o por definir no contentor, cujas portas publicadas precisam de todas as interfaces; `127.0.0.1` serve para uma execução fora do Docker. O healthcheck consulta o mesmo endereço.
`TRUSTED_PROXY`	Não	Endereços ou intervalos CIDR, separados por vírgulas, do proxy reverso à frente do BombVault (por exemplo `192.168.20.11` ou `10.0.0.0/8`). Só a partir desses saltos o `X-Forwarded-For` é acreditado, e o travão de início de sessão passa a contar falhas por cliente real em vez de juntar todos os que estão atrás do proxy no mesmo balde. Por definir (o padrão) ninguém é acreditado: um cabeçalho acreditado sem condições deixaria qualquer chamador escolher o seu próprio balde.
`HOST_SOURCE_ROOT`	Não	O caminho do host montado como Host Data (predefinição `/mnt`). O BombVault traduz as origens de bind-mount que o Docker reporta em caminhos sob esta montagem. Altere apenas se montou uma raiz de host diferente.
`DATA_ROOT_SEGMENTS`	Não	Nomes de segmentos de caminho, separados por vírgula, que marcam uma origem de bind-mount como dados de backup (predefinição `appdata`, seguindo a convenção do Unraid `/mnt/user/appdata/<container>`). O bind-mount de um container é automaticamente selecionado para backup quando QUALQUER segmento listado aparece como um segmento de caminho completo da sua origem no host, por exemplo `DATA_ROOT_SEGMENTS=appdata,config` também apanha um bind `.../config`. Consulte Deteção da origem de backup para as outras formas, sempre ativas, de encontrar a pasta de dados de um container.
`PLATFORM`	Não	Força a plataforma que o BombVault assume estar a correr, em vez de a detetar automaticamente: `unraid`, `generic` ou `truenas` (não definido por predefinição, deteta automaticamente o Unraid ao procurar o seu marcador `dockerMan` sob a montagem flash, caso contrário `generic`; um valor não reconhecido também recai em `generic`, registado no log). Defina-o explicitamente num host Docker genérico ou no TrueNAS Scale em vez de depender da autodeteção exclusiva do Unraid, o ficheiro compose genérico já faz isto. Altera a convenção de recurso de appdata, as predefinições de destino de restauro entre instâncias, e se os passos de notificação/plugin complementar exclusivos do Unraid sequer são tentados (ver `internal/platform`).
`BOMBVAULT_SELF_CONTAINER`	Não	O nome do próprio container BombVault, para que nunca faça backup (e assim pare) de si próprio.
`BACKUP_MAX_HOURS`	Não	Máximo de horas de relógio que uma única execução de backup pode reter o bloqueio do seu domínio antes de ser forçada a cancelar (uma salvaguarda para que uma execução encravada não possa bloquear o domínio para sempre). Vazio (a predefinição) usa `48`. Aumente-o para backups em nuvem muito grandes ou lentos (uma execução cancelada no limite falha com `context deadline exceeded`). Defina `0` para desativar o limite por completo.
`BACKUP_STALL_HOURS`	Não	Horas que um backup pode passar sem qualquer progresso antes de ser cancelado. Vazio (a predefinição) usa `2`; defina `0` para nunca cancelar por paragem. É a mais fina das duas salvaguardas e normalmente a que dispara: observa se ainda está a acontecer alguma coisa em vez de quanto tempo a execução já leva, por isso um backup de vários terabytes lento mas saudável é deixado em paz, enquanto um encravado numa partilha que não responde é parado em horas em vez de dias. É registado um aviso após 30 minutos de silêncio, antes de qualquer cancelamento. A análise conta como progresso: o restic não escreve bytes enquanto percorre uma árvore grande, e essa fase é vigiada através dos seus totais de ficheiros e bytes em vez dos bytes escritos. As duas variáveis são independentes, e `BACKUP_MAX_HOURS` continua a limitar as fases depois do backup propriamente dito (retenção, estatísticas, cópia externa), onde não há contadores para vigiar.
`DB_DUMP_MAX_HOURS`	Não	Horas que um dump automático de base de dados pode correr antes de ser parado. Vazio (a predefinição) usa `6`; são aceites valores de `1` a `48`, e o limite fica uma hora abaixo de `BACKUP_MAX_HOURS` (em metade dele quando este é inferior a duas horas), para que um dump longo seja cortado pelo seu próprio limite e relatado como tal, em vez de levar o backup atrás. Um dump que deixa de avançar é parado mais cedo, ao fim de `BACKUP_STALL_HOURS`. Um dump parado falha por si e o backup do container continua. No Unraid, acrescente a variável ao container BombVault com Add another Path, Port, Variable.
`TZ`	Não	Fuso horário para o agendador (por exemplo `Europe/Berlin`). Se não for definido, todos os agendamentos são executados em UTC: um agendamento às 02:30 é então iniciado às 02:30 UTC e não na hora local. No Unraid você nunca define isto: o sistema passa o próprio fuso horário para cada contêiner. O registo de arranque indica que fuso foi aplicado. Um fuso com hora de verão salta uma execução na primavera e faz uma duas vezes no outono; o UTC não faz nenhuma das duas coisas, mas desvia-se uma hora face ao seu relógio duas vezes por ano.

Montagens¶

Monte o socket Docker, o flash (/boot) e a raiz Host Data (/mnt) como mostrado no template CA. As origens e os destinos de backup vivem ambos sob Host Data, e é montada em slave para que uma partilha remota que monte depois de o container arrancar (por exemplo sob /mnt/remotes) fique visível sem um reinício.

As cópias de conjuntos de dados ZFS também precisam deste modo: o host só monta o instantâneo de um conjunto depois de o container ter arrancado. Veja Conjuntos de dados ZFS.

Os caminhos de repositório de backup assumem por predefinição /mnt/user/bombvault/{container,vms,flash,config,files,zfs}, criados no primeiro backup. Altere a localização a qualquer momento em Definições, Armazenamento, Caminhos de backup. Cada campo de caminho tem também um interruptor Local / Remoto integrado: um caminho pode ser um remoto restic (s3:..., rest:..., sftp:..., rclone:...) em vez de uma pasta local, e o backup vai diretamente para lá, sem cópia local separada; consulte Repositórios primários remotos.

Verificação de integração com o host

Abra /spike na interface web depois de o container arrancar. Sonda cada montagem e CLI (socket Docker, libvirt, restic, qemu-img, rclone) e reporta quaisquer peças em falta.

Deteção das fontes de cópia¶

Para cada contentor, o BombVault escolhe por si que bind mounts e volumes nomeados são copiados. Um caminho é aceite assim que um dos pontos seguintes se aplique (o resultado pode sempre ser corrigido por contentor nas suas Pastas a copiar):

Correspondência de um segmento de raiz de dados: a origem no anfitrião do bind contém um dos segmentos de DATA_ROOT_SEGMENTS como componente completo do caminho (por omissão apenas appdata).
Os volumes Docker nomeados são sempre incluídos, porque não têm equivalente descartável e portanto não há nada a filtrar, mas só quando o caminho real de armazenamento do volume no anfitrião é alcançável através da montagem Host Data, tal como qualquer outro caminho do anfitrião que o BombVault copia. O controlador local por omissão guarda um volume sob a raiz de dados do próprio daemon, ou seja /var/lib/docker/volumes/<nome>/_data salvo personalização (confirma com docker info -f '{{.DockerRootDir}}'). Esse local NÃO está coberto pela montagem Host Data estreita, de um único diretório, que o docker-compose.yml genérico usa por omissão. Um volume inalcançável é ignorado em silêncio, não é um erro. Para copiar mesmo os volumes nomeados num anfitrião genérico, aponta o Host Data (e HOST_SOURCE_ROOT) para um antecessor comum que cubra também a raiz de dados do Docker: vê o comentário Host Data no ficheiro compose para o compromisso (o Unraid contorna isto montando todo o /mnt, a sua própria convenção universal de topo, pela mesma razão).
Diretório de projeto do Docker Compose: se o contentor tiver a etiqueta padrão com.docker.compose.project.working_dir (posta automaticamente pelo docker compose up), esse diretório é acrescentado também, independentemente de algum bind ter correspondido a um segmento de raiz de dados.
Substituição pela etiqueta bombvault.data: põe a etiqueta bombvault.data=true num contentor para incluir TODOS os seus bind mounts, para uma disposição que nenhuma das duas convenções acima apanha (por exemplo um único bind /srv/plex/config sem projeto Compose). Qualquer valor não vazio diferente de false conta como verdadeiro; uma etiqueta ausente ou bombvault.data=false não muda nada.
Etiqueta bombvault.dbdump: põe bombvault.dbdump=false num container para desligar o seu dump automático de base de dados (0, no e off fazem o mesmo), ou indica o motor (postgres, mysql, mariadb) para despejar um container que o BombVault não reconhece sozinho. A etiqueta manda sobre o interruptor no cartão do container, que no Unraid é o caminho habitual.

Modelo de segurança¶

Controlo do host equivalente a root

Através do socket Docker, o BombVault pode parar, remover e recriar containers e ler/escrever appdata, e para o backup de VMs inicia sessão no host por SSH (qemu+ssh://, root por predefinição) para correr virsh. Qualquer pessoa que consiga alcançar a sua interface web tem, efetivamente, root no host.

Proteção por palavra-passe opcional (Definições, Segurança): define uma palavra-passe para exigir início de sessão, limpa-a para desativar. Desativada por omissão para uso numa LAN de confiança. A palavra-passe é guardada com Argon2id sobre um valor apimentado com APP_KEY, por isso um /config copiado não vale nada sem a chave e é lento de atacar com ela. Uma palavra-passe nova precisa de pelo menos 12 caracteres; uma mais curta já existente continua a funcionar até ser alterada. As sessões são assinadas (HMAC derivado de APP_KEY) e alterar a palavra-passe invalida-as; os inícios de sessão estão limitados a cinco falhas por minuto e por cliente.
Autenticação de dois fatores (Definições): um código temporal de uma aplicação de autenticação além da palavra-passe, mais oito códigos de recuperação de uso único entregues uma vez ao ativar. O segredo partilhado é guardado cifrado com APP_KEY, e desligar o fator outra vez exige um código atual.
Chaves de acesso (WebAuthn): têm um cartão próprio assim que há uma palavra-passe definida, ao lado da palavra-passe e nunca em vez dela, por isso remover todas as chaves de acesso não deixa ninguém de fora. Precisam de um nome de domínio real e de um certificado em que o browser confie. O endereço predefinido https://<ip>:3443 é exatamente o que o WebAuthn recusa, e o cartão di-lo em vez de oferecer um botão que falharia.
As alterações exigem JSON. Um pedido que altera algo tem de enviar Content-Type: application/json e não pode ser marcado pelo browser como vindo de outro site, para que uma página de outro site não consiga pôr o seu browser a alterar definições num endereço da LAN. Um script que use a API envia esse cabeçalho; tudo o resto é recusado com 415.
Como o controlo é opcional, quando não está definido, toda a interface e API (incluindo a configuração do externo, as rotas de teste de adulteração e o kit de recuperação) ficam acessíveis a qualquer pessoa que consiga alcançar a porta. Ative o controlo assim que estiver a usar externo, backups imutáveis ou encriptação.
Corra o BombVault apenas numa rede de confiança e não exposta. Para acesso remoto, coloque-o por trás de um proxy reverso que adicione autenticação e TLS. As respostas transportam cabeçalhos de segurança de base (CSP, nosniff, X-Frame-Options, Referrer-Policy).
Atrás de um proxy reverso cada pedido traz o endereço do proxy, por isso sem TRUSTED_PROXY o travão conta todos os clientes no mesmo balde e as falhas de um atacante também te trancam de fora. Indica o proxy em TRUSTED_PROXY para voltar a contar por cliente.
Um proxy inverso à frente do BombVault tem de passar o cabeçalho Authorization ou X-API-Key para /mcp e não pode reter as respostas em buffer; caso contrário os assistentes não conseguem ligar-se. Ver Servidor MCP.
O endpoint MCP /mcp responde 404 enquanto não existir nenhuma chave nem estiver ativado o início de sessão por OAuth, e pede a cada cliente a sua chave ou o seu token mesmo com a palavra-passe de início de sessão desligada; nenhum endereço fica isento, nem sequer localhost. Não tem ferramentas de restauro nem de eliminação, e restaurar um backup da configuração revoga todas as chaves. Ver Servidor MCP.
Com HTTP_ONLY=true, o cookie de sessão perde a sua flag Secure (tem de perder, para funcionar sobre HTTP simples), por isso ative a palavra-passe por trás de um proxy que termina o TLS apenas se a confidencialidade importar.
A ligação SSH do backup de VMs confia na chave do host no primeiro contacto (TOFU) e fixa-a a partir daí. Verifique a chave do host fora de banda se o seu caminho container-para-host não for de confiança.
Os backups são encriptados pelo restic quando a encriptação está ativada (Definições; ligada por predefinição), com a chave derivada da APP_KEY.

Servidor MCP¶

O servidor MCP não precisa de nenhuma variável de ambiente. Ativa-o criando uma chave em Definições, Integrações, Servidor MCP, e ele responde em /mcp na mesma porta da interface web (por exemplo https://192.168.1.10:3443/mcp). Sem uma chave ativa, esse caminho responde 404. Clientes, certificados e limites estão descritos em Servidor MCP.

Backup de VMs por SSH¶

O BombVault faz backup de VMs KVM/libvirt sem montar qualquer caminho de libvirt. Corre virsh no host por SSH (qemu+ssh://), por isso nunca pode afetar o VM Manager do seu host.

Montar o socket libvirt do host dentro de um container é frágil no Unraid: esses caminhos pertencem ao VM Manager, e alternar "Enable VMs" pode deixar o libvirt sem conseguir arrancar. A chave SSH dá acesso root ao host, o mesmo nível de confiança que o socket Docker que o BombVault já usa.

Configuração rápida:

Definições, Integrações, SSH do anfitrião: copie a chave pública mostrada.
Adicione-a ao /root/.ssh/authorized_keys do Unraid (também persistida no flash para sobreviver a reinícios).
Clique em Testar ligação.

O template adiciona --add-host=host.docker.internal:host-gateway para que o container possa alcançar o host. Defina LIBVIRT_HOST para o IP LAN do seu Unraid se esse nome não resolver (por exemplo quando o container corre numa rede br0.x personalizada). Se alterou a porta SSH do Unraid, defina LIBVIRT_SSH_PORT para corresponder. Os instantâneos a quente precisam adicionalmente do agente convidado qemu na VM e do disco em /mnt/cache (não /mnt/user).

Guia completo de configuração e rede de VMs

O guia completo passo a passo (ativação de SSH, autorização persistente da chave, encaminhamento de rede personalizada e VLAN, método por VM e resolução de problemas no lado do host) está em docs/vm-backup-ssh-setup.md no GitHub.

Configuração do externo¶

Configure uma réplica externa na página Definições, Externo. Consulte Externo e recuperação para o fluxo de trabalho completo (imutável/append-only, teste de adulteração e ensaios de DR). Em resumo:

Backends: SMB/CIFS e NFS (monte a partilha e aponte-lhe um Caminho de backup), backends restic nativos sem rclone (s3:..., rest:http://host:8000/repo, sftp:user@host:/repo), ou qualquer remoto rclone (rclone:<remote>:<bucket>/path). O Backblaze B2 não tem aqui um backend nativo: acede-se através do seu endpoint S3 (s3:https://s3.<region>.backblazeb2.com/<bucket>/<path>), com o ID da chave e a chave de aplicação como credenciais S3.
Credenciais de nuvem partilhadas são guardadas encriptadas em Definições, Acesso à nuvem, Credenciais de nuvem partilhadas.
Os destinos SSH não precisam de nada instalado do outro lado. O sftp: só precisa de um servidor SSH. Adicione a chave pública de Definições, Integrações, SSH do anfitrião (também em /config/ssh/id_ed25519.pub) ao ~/.ssh/authorized_keys do utilizador de destino.
Cópia externa: o BombVault replica novos instantâneos com restic copy numa base de melhor esforço, além de um repositório primário (normalmente local). Cada domínio tem o seu próprio agendamento externo, mais um botão Replicar agora.
Vários destinos externos por domínio: cada domínio pode replicar para vários destinos externos de uma só vez. Adicione destinos extra em Definições, Externo, cada um com o seu próprio repositório, classe de armazenamento S3, flag append-only, retenção e orçamento de crescimento; todos replicam no agendamento externo desse domínio. Uma configuração externa única existente é transferida como o primeiro destino.
Destinos: os destinos externos são configurados uma só vez em Definições, Externo, Destinos, através de um assistente que lista todos os serviços suportados. Consulte Destinos.
Localização por item: cada container, VM e conjunto de ficheiros acende Local e os destinos que recebem os seus backups. Definições, Armazenamento, Localizações padrão define isto por domínio para os itens sem escolha própria. Consulte Localização por item.
Retenção por origem: as políticas local e externa vivem ambas em Definições, Retenção (deixe a política externa toda a zero para nunca aparar automaticamente os instantâneos externos). Os cartões Retenção local e Retenção externa têm cada um Regras de retenção por origem, que dá aos contentores, VMs, flash, pastas, ZFS ou à autocópia regras de retenção próprias, para as cópias locais e para o seu repo externo. Uma origem sem regras próprias segue as partilhadas, e a retenção após cada cópia, a cópia externa, uma limpeza manual e a pré-visualização da retenção usam todas as regras da origem em causa. Os destinos externos adicionais mantêm as regras definidas para eles em Definições, Externo.
Limites de largura de banda: limite a taxa de envio/receção do restic em Definições, Externo.
Primeiro o streaming: em Definições, Externo, escolhe os servidores multimédia (Plex, Jellyfin e Emby vêm pré-selecionados pelo nome da imagem), a taxa de envio a partir da qual um conta como em streaming, o limite de envio durante o streaming e quanto tempo depois de um stream volta o limite normal.
Classe de armazenamento fria e de arquivo (S3): para um repo externo S3 nativo, escolha um nível legível para restauro (Standard, Standard-IA, One Zone-IA, Intelligent-Tiering, Glacier Instant Retrieval). Os remotos rclone definem a sua classe na configuração do rclone.
Primário remoto em vez de local: o Caminho de backup de um domínio pode ser ele próprio um dos backends acima, sem cópia local nem passo de replicação; consulte Repositórios primários remotos para o interruptor Local/Remoto integrado e as suas definições de segurança (largura de banda, append-only, orçamento de crescimento).

Anomalias¶

A deteção de anomalias configura-se no cartão Anomalias em Definições, Integridade. Cada controlo guarda assim que o altera, e os três abaixo do interruptor ficam ocultos enquanto a deteção está desligada.

Definição	Predefinição	O que faz
Detetar anomalias	Ligado	Compara cada backup com o histórico próprio do elemento. Desligado, nada de novo é verificado e a entrada Anomalias sai da barra lateral; o cartão continua a apontar para as deteções anteriores.
Sensibilidade	Equilibrada	Rigorosa comunica alterações mais pequenas, Permissiva só as grandes.
Enviar uma notificação para	Só achados críticos	A gravidade mínima que envia uma mensagem pelos canais configurados em Notificações. As falhas repetidas de backups e dumps e as verificações de restauro agendadas falhadas já enviam a sua própria mensagem e não são enviadas duas vezes.
Manter os backups antigos quando uma origem encolhe muito ou é reescrita	Ligado	Enquanto um elemento tiver uma deteção aberta por uma origem quase vazia, um encolhimento forte ou a maior parte dos dados guardada de novo, a retenção e a limpeza deixam os seus backups antigos em paz. Confirme a deteção ou marque-a como esperada para os libertar.

Cada elemento pode ter a sua própria sensibilidade e o seu próprio mínimo de notificação. Defina-os na página Anomalias, onde um elemento com deteções abertas os tem em Monitorização no seu cartão e qualquer outro elemento os abre a partir do cartão Nada em aberto, ou no painel do próprio elemento: a secção de pastas de um contentor e as definições de uma VM (ambas no modo avançado), o editor de pastas de um conjunto de pastas e as páginas Flash e Auto-backup. Num elemento ZFS estão no seu editor na página ZFS e aplicam-se a cada conjunto de dados da sua árvore.

Definições portáteis (exportar e importar)¶

O cartão Exportar / importar configurações na página Definições, Sistema escreve toda a sua configuração BombVault (definições de domínio, destinos externos, agendamentos, retenção, notificações) para um ficheiro JSON portátil que pode importar noutra instância, para que mudar para uma máquina nova ou clonar uma configuração não signifique reintroduzir tudo à mão. A importação mostra uma pré-visualização e pede confirmação, e nunca toca nos seus dados ou histórico de backup.

A exportação pode conter credenciais

Escolhe se inclui as credenciais externas, de notificação e do broker MQTT no ficheiro. Com as credenciais incluídas, a exportação é tão sensível como o seu kit de recuperação, por isso guarde-a num local seguro. Sem elas, o ficheiro contém apenas definições não secretas.