Quem faz o backup de um servidor Immich e como você recupera tudo?

Em 19 de outubro de 2026, apagamos tudo em um servidor Immich de teste, incluindo o repositório Borg local. Sobraram apenas o repositório Borg externo e a chave exportada dele. Uma instalação nova recuperou a biblioteca inteira a partir desses dois.

Em uma VPS da DreamHost, fazer esses backups é tarefa sua. O suporte da DreamHost está disponível 24/7 para hardware, rede e conectividade, e você gerencia o sistema operacional, o software e a configuração. A Central de Ajuda da DreamHost informa que, como você tem controle total da VPS, a DreamHost não pode acessar, fazer backup nem recuperar os seus dados nela. O Immich faz o próprio dump do banco de dados toda noite às 2h. Mas esses dumps guardam apenas metadados, nunca fotos ou vídeos. Em um servidor Immich da DreamHost, o utilitário immich-backup faz o dump do banco de dados e avisa que você precisa copiar o diretório da biblioteca para fora do servidor separadamente. Se você ainda está migrando do Google Fotos, guarde os arquivos do Takeout até o primeiro backup abaixo ser executado. Se ainda não escolheu um app de fotos, comece vendo como o Immich se compara ao PhotoPrism, ao Ente e ao Nextcloud.

O que o backup precisa incluir

A documentação do Immich diz que ele guarda os caminhos dos arquivos e os metadados dos usuários no banco de dados e não varre a pasta da biblioteca. Por isso, um backup precisa dos dois, feitos na mesma noite. Álbuns, compartilhamentos e edições ficam nesses metadados. Se você restaurar as fotos sem o banco de dados, terá arquivos soltos e nenhum álbum. Se restaurar o banco de dados sem as fotos, o Immich vai apontar para arquivos que não existem. Os tamanhos abaixo são do segundo backup da nossa biblioteca de teste.

Deixar de fora as duas pastas que podem ser recriadas nos poupou 214 MB de uma pasta de 1,39 GB. O preço foi recriar as miniaturas depois da restauração. Seus arquivos .env e docker-compose.yml ficam fora da pasta de upload, então copie-os para fora do servidor uma vez. Restauramos sem os nossos, a partir de cópias novas e com uma nova senha do banco de dados, mas os seus vão poupar você de procurar os caminhos e a versão.

Como restauramos um servidor apagado

O servidor de teste (que não era um servidor da DreamHost) tinha duas contas: um administrador e um membro da família. Juntas, elas tinham 401 fotos e 4 vídeos, somando 1,06 GB, além de mais 5 fotos na lixeira. Configuramos o servidor com o que faria falta para uma família se sumisse. Algumas fotos eram favoritas e tinham descrições e classificações por estrelas, outras estavam arquivadas, e algumas tinham datas e locais editados. Um álbum era compartilhado com a segunda conta. Um link de compartilhamento tinha senha e data de expiração.

Cada backup seguiu o script do Borg do Immich, com o Borg 1.4.0. Ele fazia o dump do banco de dados na pasta de upload e depois copiava essa pasta para um repositório criptografado fora da VM, sem as miniaturas e os vídeos transcodificados. Depois de apagar tudo, reconstruímos o servidor nesta ordem.

1. Instale o Immich de novo a partir dos arquivos dele

   Baixe cópias novas de docker-compose.yml e example.env do guia de início rápido do Immich. Defina IMMICH_VERSION em .env com a versão que você usava, já que o padrão v3 baixa a versão v3 mais recente. Você encontra a versão no nome de cada dump automático. Também definimos uma senha do banco de dados diferente da do servidor antigo, e docker compose pull levou 16,4 segundos na nossa conexão.

2. Extraia o arquivo mais recente do repositório externo

   Execute borg extract para o arquivo mais recente e mova as pastas para o novo local de upload. O nosso, de 1,15 GB, foi extraído em 4,8 segundos. Se você deixou thumbs/ e encoded-video/ fora do backup, a página de integridade do Immich orienta a criar um arquivo .immich vazio em cada uma dessas pastas, porque o Immich verifica a existência dele ao iniciar.

3. Restaure o banco de dados antes de o Immich iniciar

   A restauração pela linha de comando do Immich exige uma instalação nova, em que o servidor Immich nunca tenha sido executado desde a criação dos contêineres. Por isso, inicie apenas o Postgres. Estes são os comandos do Immich, com o nome e o usuário padrão do banco de dados de example.env. Troque gunzip --stdout por cat quando o dump for em SQL puro, como o script do Immich gera.

   bashCopiar

   docker compose create
   docker start immich_postgres
   sleep 10
   gunzip --stdout "/path/to/backup/dump.sql.gz" \
   | sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" \
   | docker exec -i immich_postgres psql --dbname=immich --username=postgres --single-transaction --set ON_ERROR_STOP=on

   Esta etapa, incluindo a espera de 10 segundos, levou 19,9 segundos.

4. Inicie o Immich

   Execute docker compose up -d. O nosso respondeu em 3,9 segundos, e a senha antiga do administrador funcionou. Contando meio segundo para criar a pasta e mover os arquivos para o lugar, as etapas da restauração somaram 46 segundos.

5. Recrie as miniaturas com a opção All

   A linha do tempo não mostrava miniaturas, porque elas não estavam no backup. A página de integridade do Immich sugere executar a tarefa de miniaturas para os itens ausentes, e esperávamos que isso funcionasse. Mas, no nosso servidor restaurado, essa opção não colocou nada na fila, já que o banco de dados ainda listava o caminho de cada miniatura. Em Administração, abra as filas de tarefas e execute a tarefa de miniaturas com a opção All. Ela recriou 810 miniaturas e prévias em 100 segundos, cerca de 8 arquivos por segundo na nossa VM com 2 vCPUs. Fotos reais de celular são maiores, então espere uma velocidade menor em uma biblioteca de família.

Em um servidor real, a extração roda na velocidade da conexão com o seu repositório externo, então uma biblioteca grande leva muito mais tempo que a nossa. Comparamos o servidor restaurado com um snapshot feito antes de apagar tudo.

A restauração pela web do Immich

No Immich v3, você também pode restaurar pela tela de boas-vindas de um servidor novo, e o Immich recomenda o caminho pela web para a maioria das pessoas. Testamos em uma segunda instalação apagada, depois de copiar de volta a pasta de upload inteira, com miniaturas e backups/, 1,39 GB no total.

A tela de boas-vindas oferece Getting Started ou Restore From Backup. Clique na segunda opção e o Immich reinicia em modo de manutenção. Nosso navegador de teste sem interface ficou parado em Server is restarting por 2 minutos, então entramos pelo link de login de manutenção que o servidor registra no log, exibido pelo comando docker logs immich_server. Um navegador comum talvez se atualize sozinho, mas não testamos isso. Em seguida, o Immich verificou se cada pasta permitia leitura e gravação e listou os dumps encontrados em backups/, com data, versão e tamanho.

Escolhemos o mais recente, um dump que o servidor restaurado tinha feito sozinho às 2h. Antes de tudo, o Immich salvou um ponto de restauração de 9,5 MB do banco de dados atual. A página de login voltou 20 segundos depois da confirmação, e todas as verificações da tabela acima passaram de novo. Desta vez, as miniaturas apareceram sem precisar recriá-las, porque a cópia da pasta as incluía.

Onde ficam as três cópias

O README do Immich recomenda seguir sempre um plano de backup 3-2-1 para suas fotos e vídeos.

Em um servidor alugado, o próprio servidor é a primeira cópia (ele já fica longe da sua casa). A segunda cópia vai para um disco ou NAS em casa. A terceira vai para um repositório Borg externo. Um repositório no próprio disco do servidor não conta, porque consome o disco do seu plano e desaparece junto com o servidor. Uma segunda VPS da DreamHost fica fora do servidor, mas a Central de Ajuda da DreamHost informa que todas as VPS ficam no data center US East, em Ashburn, Virgínia, então ela não conta como cópia externa.

O BorgBase, que a página do script do Immich indica para backups externos, hospeda repositórios Borg. Quando consultamos os planos em 19 de outubro, ele oferecia 10 GB grátis, cobrava US$ 30 por ano por 250 GB ou US$ 110 por ano por 1 TB e não cobrava por transferência. Fotos quase não se comprimem, então você vai precisar de um repositório mais ou menos do tamanho dos seus originais. Nosso segundo arquivo passou de 1.150 MB para 1.130 MB.

O Borg só guarda o que mudou. Nossa primeira execução adicionou 852 MB ao repositório externo. Depois que adicionamos 110 fotos, a segunda execução adicionou 304,7 MB (as fotos novas mais o dump alterado do banco de dados). O script inteiro rodou em 8,8 segundos. Uma tarefa de cópia simples enviaria tudo de novo. Uma sincronização também não é backup, porque uma foto apagada no servidor some também da cópia sincronizada, enquanto o Borg mantém os arquivos antigos.

A primeira cópia para fora do servidor é a mais demorada. Pense em uma biblioteca de 165 GB, mais ou menos o máximo que nosso guia do Google Photos coloca no Stack 16. Isso dá 1.320 gigabits (165 x 8), ou cerca de 44 minutos a uma taxa de exemplo de 500 Mbps. A cópia em casa é baixada na velocidade de download da sua internet residencial. Se um dia você restaurar a partir dessa cópia em casa, ela volta para o servidor na velocidade de upload da sua internet residencial e, com um upload de 20 Mbps, isso leva cerca de 18 horas. A largura de banda na hospedagem VPS para Immich é ilimitada, sem cobrança por excedente (sujeita a uso justo).

Configure o backup noturno

Você vai precisar de um acesso SSH ao servidor e de um repositório vazio no seu serviço externo.

1. Instale o Borg

   No Debian 13, sudo apt install borgbackup instala o Borg 1.4.0, a versão que testamos, segundo a lista de pacotes do Debian. O guia de início rápido do Borg explica os comandos abaixo em mais detalhes.

2. Permita que o servidor acesse o repositório sem pedir senha

   O cron não consegue digitar uma senha, então adicione a chave SSH pública do servidor no seu serviço externo e salve a frase-senha do repositório em um arquivo que só o root pode ler.

   bashCopiar

   sudo sh -c 'umask 077; printf "%s" "YOUR-PASSPHRASE" > /root/.borg-passphrase'

3. Crie o repositório com criptografia

   O script do Immich cria os repositórios com --encryption=none. Nós ativamos a criptografia na cópia externa. O Borg pede a frase-senha.

   bashCopiar

   borg init --encryption=repokey-blake2 ssh://USER@HOST/./immich-borg

4. Exporte a chave e guarde-a fora do servidor

   Guarde a chave e a frase-senha no seu próprio computador ou no seu gerenciador de senhas, porque sem elas você não consegue abrir o repositório. No nosso teste, a chave exportada e o repositório foram as únicas coisas que sobreviveram ao servidor.

   bashCopiar

   borg key export ssh://USER@HOST/./immich-borg immich-borg-key.txt

5. Salve o script de backup

   Este é o script do Immich com criptografia, um único repositório, sete arquivos diários mantidos e sem o -t no comando de dump. Com -t, nosso dump ganhou 242.266 retornos de carro. O dump ainda foi restaurado sem erro, mas uma tarefa executada pelo cron não tem terminal com que se comunicar, então removemos a opção. O script do Immich mantém apenas arquivos semanais e mensais, então uma foto adicionada e apagada na mesma semana pode ficar de fora de todos os arquivos. Por isso adicionamos --keep-daily=7. Crie a pasta database-backup dentro da pasta de upload uma vez, antes da primeira execução.

   bashCopiar

   #!/bin/sh
   set -eu
   UPLOAD_LOCATION="/path/to/immich/upload"   # UPLOAD_LOCATION from Immich's .env
   REPO="ssh://USER@HOST/./immich-borg"
   export BORG_PASSCOMMAND="cat /root/.borg-passphrase"
   
   # Database first
   docker exec immich_postgres pg_dump --clean --if-exists --dbname=immich --username=postgres \
     > "$UPLOAD_LOCATION/database-backup/immich-database.sql"
   
   # Then the files, without the rebuildable folders
   borg create "$REPO::{now}" "$UPLOAD_LOCATION" \
     --exclude "$UPLOAD_LOCATION/thumbs/" --exclude "$UPLOAD_LOCATION/encoded-video/"
   
   # Keep 7 daily, 4 weekly and 3 monthly archives
   borg prune --keep-daily=7 --keep-weekly=4 --keep-monthly=3 "$REPO"
   borg compact "$REPO"

   Em um servidor Immich da DreamHost, execute immich-backup no lugar da linha docker exec e adicione o dump que ele gera à linha borg create. Não executamos esse utilitário no nosso teste, então confira na saída dele onde ficam o dump e a pasta da biblioteca e aponte UPLOAD_LOCATION para lá.

6. Adicione a cópia em casa

   Repita as linhas create, prune e compact para um segundo repositório em uma máquina em casa, do mesmo jeito que o script do Immich faz com as cópias local e remota. O servidor precisa acessar essa máquina por SSH, seja por um redirecionamento de porta no roteador de casa, seja por um túnel de rede privada entre os dois. Achamos o túnel a opção mais fácil, já que ele não exige um endereço fixo em casa.

7. Execute uma vez e depois agende com o cron

   Execute o script manualmente e leia a saída. Depois, execute sudo crontab -e e adicione uma linha que o execute toda noite, aqui às 4h, depois do dump noturno do próprio Immich.

   bashCopiar

   0 4 * * * /usr/local/bin/immich-borg.sh >> /var/log/immich-borg.log 2>&1

8. Receba um aviso quando uma noite falhar

   Adicione ao script uma última linha que chame uma URL de check-in, para você ficar sabendo quando o backup de alguma noite não terminar. A página do Uptime Kuma da DreamHost diz que os monitores push dele permitem que seus próprios cron jobs façam check-in. Depois das duas primeiras noites, borg list deve mostrar um novo arquivo para cada noite: o primeiro com mais ou menos o tamanho da sua biblioteca e os seguintes bem menores.

Recupere uma foto de um arquivo mais antigo

Se você não ativou o modelo de armazenamento do Immich (desativado por padrão), suas fotos em upload/ ficam com nomes aleatórios gerados pelo Immich. Para encontrar uma, extraia o dump SQL em texto puro do mesmo arquivo e procure nele o nome original do arquivo da foto. O caminho armazenado fica na mesma linha. Depois, extraia só esse arquivo.

borg extract "$REPO::ARCHIVE-NAME" path/inside/the/archive/photo.jpg

Extrair um original do arquivo da nossa primeira noite levou 0,5 segundo. O SHA-256 dele bateu com o do arquivo de antes do backup. Envie-o de novo pelo app ou pela página web do Immich. Não testamos o que uma foto reenviada mantém, então conte com a necessidade de adicioná-la de volta aos álbuns você mesmo.

Faça backup antes de cada atualização do Immich

O Immich não oferece suporte a downgrade, nem dentro de uma versão secundária, então o backup que você faz antes de uma atualização é sua única forma de voltar atrás. A página do Immich da DreamHost orienta a executar immich-backup para o banco de dados antes de atualizar. Anote também a versão que você está usando. O Immich a coloca no nome de cada dump automático, logo antes da versão do Postgres, e uma restauração em uma versão diferente tenta executar as migrações do banco de dados automaticamente.

A cada poucos meses, faça uma restauração de teste. O borg check passou no nosso repositório em 1,8 segundo, mas só uma restauração de verdade mostra que o Immich volta a funcionar a partir dele. O teste que vale é a restauração acima em um servidor descartável, seguida das verificações de integridade do Immich, que a v3 executa todas as noites às 3h. Você vai ver miniaturas faltando para tudo o que estiver na lixeira, o que é normal. Depois, abra um álbum compartilhado e algumas fotos editadas e confira se elas estão do jeito que você deixou.

Como medimos

A DreamHost fez o teste em 19 e 20 de outubro de 2026, com o Immich v3.3.3. A VM de teste rodava Ubuntu 24.04.4 em arm64, com 2 vCPUs e 7.922 MB de memória, no Colima em um Mac com Apple silicon. Ela não é um servidor da DreamHost e tem metade dos núcleos do Stack 16. O Immich rodou a partir do próprio arquivo compose e do example.env, alterados apenas nos caminhos, no fuso horário, na versão fixada e na senha do banco de dados. O Borg 1.4.0 rodou em um contêiner Debian 13. A biblioteca era composta de JPEGs sintéticos com datas e GPS nos dados EXIF, além de quatro clipes curtos de vídeo em 1080p, em contas descartáveis. Cada etapa foi executada uma vez.

O teste não abrange a imagem do Immich da DreamHost nem o utilitário immich-backup, uma transferência por uma rede real (o repositório externo era uma pasta no mesmo Mac), uma biblioteca de centenas de gigabytes nem um backup de uma versão mais antiga do Immich restaurado em uma mais nova. O Immich v3.3.4 saiu em 20 de outubro. As notas de versão citam consultas de pessoas mais rápidas e uma tradução que faltava, nada sobre backup ou restauração. Ainda não repetimos o teste nessa versão.

Perguntas frequentes sobre backup do Immich