Como fazer backup e restaurar o Immich em um VPS

O que um backup do Immich deve conter

Um backup do Immich consiste em três elementos capturados no mesmo momento. Os originais em UPLOAD_LOCATION. Um dump SQL da base de dados Postgres. Os ficheiros .env e docker-compose.yml que descrevem a stack. Restaurar significa reaplicar esse dump numa base de dados nova com o servidor Immich parado e iniciar o restante da stack apenas depois disso. Se inverter a ordem, pode acabar com um Immich funcional a mostrar uma cronologia vazia sobre um disco cheio.

Esta separação é importante porque o Immich mantém o estado em dois locais que não têm conhecimento um do outro. O Postgres contém todos os álbuns, todos os clusters de rostos, todas as ligações partilhadas, todas as contas de utilizador e chaves de API, além do caminho armazenado de cada recurso. O sistema de ficheiros contém os píxeis. Se restaurar os ficheiros sem a base de dados, o Immich não mostra nada. Se restaurar a base de dados sem os ficheiros, cada recurso abre como uma imagem danificada.

Os comandos apresentados foram escritos para o Immich v3.1.0, a versão atual no início de agosto de 2026. Em 2026-10-25, a versão atual é a v3.3.5, uma atualização de segurança publicada em 2026-10-21, e o seu ficheiro compose, a imagem da base de dados e os passos documentados de backup e restauro correspondem ao que esta página utiliza. O projeto publica versões rapidamente e o procedimento documentado de backup mudou mais do que uma vez. Por isso, confirme a versão que está efetivamente a executar antes de copiar qualquer coisa. Se a stack ainda não estiver em execução, comece pelo guia de instalação do Immich e volte depois.

Saiba para onde apontam os seus caminhos

Duas variáveis em .env determinam tudo nesta página. UPLOAD_LOCATION é o diretório-pai onde o Immich grava todos os ficheiros multimédia. DB_DATA_LOCATION é o diretório de dados do Postgres.

O example.env predefinido define UPLOAD_LOCATION=./library, que é um valor predefinido confuso, porque o Immich cria depois uma pasta chamada library dentro desse diretório. Os originais ficam em ./library/library. Defina um caminho absoluto, para que um script de backup nunca dependa do diretório a partir do qual foi executado.

UPLOAD_LOCATION=/srv/immich/data
DB_DATA_LOCATION=/srv/immich/postgres
DB_USERNAME=postgres
DB_DATABASE_NAME=immich
IMMICH_VERSION=v3.1.0

Dentro de UPLOAD_LOCATION, o Immich cria várias pastas. Três delas contêm dados que nenhum processo consegue reconstruir:

• library: os originais, organizados de acordo com o seu modelo de armazenamento
• upload: originais que ainda não foram movidos para a estrutura do modelo, além de uploads em curso
• profile: fotografias de perfil dos utilizadores

Se perder library, a fotografia desaparece. O Immich não mantém uma segunda cópia de nenhum original.

Porque copiar o diretório de dados do Postgres não é um backup

DB_DATA_LOCATION parece um alvo simples. É um diretório, rsync consegue copiá-lo e a cópia termina sem erro. Se o copiar enquanto o Postgres está em execução, a cópia não é um backup. Se o copiar com o Postgres parado, é um backup, mas é frágil. Existem duas razões para isso, e pode observar ambas a falhar.

A primeira é a inconsistência dos ficheiros. O Postgres escreve primeiro cada alteração no write-ahead log (WAL) e só depois a aplica aos ficheiros das tabelas, durante um checkpoint. Assim, em qualquer instante, os ficheiros no disco podem estar num estado intermédio. Uma cópia progressiva que demora quatro minutos lê o primeiro ficheiro às 02:00 e o último às 02:04. Esses dois ficheiros não pertencem à mesma transação. Quando inicia o Postgres com o resultado, ele recusa arrancar com PANIC: could not locate a valid checkpoint record ou inicia e termina ao ler pela primeira vez uma página danificada, com invalid page in block 1234 of relation base/16384/.... Nenhum dos casos pode ser recuperado a partir dessa cópia.

A segunda razão aplica-se à cópia feita com tudo parado. O PostgreSQL documenta uma cópia completa de um diretório de dados encerrado como um backup válido, mas esse diretório só pode ser aberto por binários que partilhem o mesmo formato de armazenamento. O Immich fixa a imagem da base de dados por digest, atualmente ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0. Trata-se do Postgres 14 com as extensões de pesquisa vetorial VectorChord, pgvector e pgvecto.rs incorporadas. O próprio Immich utiliza agora o VectorChord; o pgvecto.rs permanece nessa imagem apenas para permitir que instalações antigas migrem a partir dele e que backups antigos continuem a ser restaurados. Uma versão minor posterior do Postgres 14 pode abrir o diretório sem alterações, mas uma versão major diferente não pode. As extensões das quais as tabelas dependem também têm de estar presentes, em versões compatíveis. O host de restauro tem de executar uma imagem compatível. Um dump SQL não tem essa limitação: é texto e qualquer servidor compatível pode reaplicá-lo.

pg_dump elimina diretamente o problema da inconsistência dos ficheiros. Lê toda a base de dados dentro de um único snapshot MVCC (multi-version concurrency control), pelo que vê a base de dados exatamente como estava num determinado instante, enquanto outras escritas continuam. Por isso, não é necessário parar o Postgres para criar o dump.

O que pode ficar fora da cópia de segurança

Estes dados são regenerados, por isso podem ser excluídos:

• thumbs: imagens de pré-visualização e miniaturas
• encoded-video: vídeo transcodificado
• DB_DATA_LOCATION: recriado a partir do dump
• o volume Docker model-cache: modelos de machine learning, descarregados novamente quando necessário

Excluir estes dados é uma escolha com custos, não uma vantagem sem contrapartidas. Recriar miniaturas e transcodificações para uma biblioteca grande pode consumir horas de CPU num VPS pequeno, e a linha temporal mostra marcadores cinzentos durante todo esse período. Pode executar novamente estas tarefas em Administração > Tarefas, definindo "Gerar miniaturas" e "Transcodificar vídeos" para serem executadas nos recursos em falta. Se o destino da cópia de segurança tiver espaço, inclua estes dados e evite a espera. Se estiver perto do limite de armazenamento, exclua-os e planeie a recriação. Dimensionar uma biblioteca Immich explica como o tamanho destas pastas cresce em relação aos originais.

Há mais uma pasta que convém conhecer. UPLOAD_LOCATION/backups contém os dumps automáticos da base de dados do Immich, gravados diariamente às 02:00, mantendo os últimos 14. Esta opção pode ser configurada em Administração > Definições > Definições de dump da base de dados. Estes dumps não têm custo adicional e são realmente úteis. Também ficam no mesmo disco que a biblioteca que protegem. Por isso, ajudam a corrigir uma migração com problemas, mas não protegem contra a falha do servidor. Crie o seu próprio dump na mesma, porque um dump iniciado por si é criado ao mesmo tempo que o snapshot de ficheiros correspondente.

Faça o dump da base de dados

docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres \
  | gzip > /srv/immich/backup/immich.sql.gz

Substitua immich e postgres por DB_DATABASE_NAME e DB_USERNAME se os tiver alterado. --clean --if-exists coloca um DROP ... IF EXISTS antes de cada CREATE, para que o dump seja restaurado numa base de dados que já contém objetos, em vez de parar no primeiro objeto.

Agora, o detalhe que estraga silenciosamente os scripts de backup. Esse comando é um pipeline, e uma shell comunica o código de saída do último comando do pipeline. Se pg_dump falhar, devido a uma palavra-passe incorreta ou a um contentor que não está em execução, gzip recebe um fluxo vazio, escreve um ficheiro gzip perfeitamente válido e termina com o código 0. O script regista sucesso e fica com um backup de 20 bytes. Coloque pipefail no início de todos os scripts de backup:

#!/usr/bin/env bash
set -euo pipefail

Depois, verifique o resultado em vez de confiar no código de saída:

ls -lh /srv/immich/backup/immich.sql.gz
gunzip -c /srv/immich/backup/immich.sql.gz | head -n 3

A primeira linha de um dump válido é -- PostgreSQL database dump. Um ficheiro com algumas centenas de bytes é um dump falhado, independentemente do que o script indicou.

Registe qual foi a release que o escreveu, junto ao dump, consultando o servidor em execução:

curl -fsS http://localhost:2283/api/server/version > /srv/immich/backup/immich-version.txt

Esse endpoint não requer autenticação e devolve a release em execução como números major, minor e patch; por isso, 3, 1 e 0 significam v3.1.0. Não dependa de .env para isto, nem de docker inspect --format '{{.Config.Image}}' immich_server, que apenas repete a referência da imagem configurada. O ficheiro padrão define IMMICH_VERSION=v3, uma tag flutuante que acompanha todas as releases 3.x. Por isso, um registo terminado em :v3 não indica qual foi o build que efetivamente escreveu o dump. Fixe também a tag exata em .env.

Pause o servidor e faça um snapshot com restic

Os ficheiros em UPLOAD_LOCATION não são imutáveis enquanto o Immich está em execução. O servidor grava novos uploads, e o job de modelo de armazenamento move ficheiros entre diretórios. Se uma ferramenta de backup ler um ficheiro a meio de uma gravação, armazena esses bytes como se fossem o ficheiro completo, sem que seja reportado qualquer erro. Pare o contentor do servidor durante a execução:

docker stop immich_server

Deixe immich_postgres em execução, porque o dump precisa dele. A interface web e a aplicação móvel ficam indisponíveis até iniciar novamente o servidor. Numa instância doméstica, às 03:00, isto costuma ser aceitável.

restic é adequado neste caso porque deduplica e cifra os dados antes de estes saírem do servidor. Aponte-o para um repositório que não esteja neste servidor:

export RESTIC_REPOSITORY=sftp:backup@backup.example.com:/srv/restic/immich
export RESTIC_PASSWORD_FILE=/root/.restic-password
restic init

O armazenamento de objetos funciona da mesma forma e é a melhor opção se quiser manter a cópia totalmente fora do seu próprio hardware:

export RESTIC_REPOSITORY=s3:https://s3.example.com/immich-backup
export AWS_ACCESS_KEY_ID=your-access-key
export AWS_SECRET_ACCESS_KEY=your-secret-key
restic init

Esse endpoint pode ser um bucket MinIO que gere num segundo computador ou qualquer fornecedor compatível com S3. Um repositório no mesmo disco da biblioteca protege contra uma eliminação acidental, mas não contra mais nada.

Depois, crie o snapshot, listando exatamente o que importa:

restic backup \
  /srv/immich/backup/immich.sql.gz \
  /srv/immich/backup/immich-version.txt \
  /srv/immich/data/library \
  /srv/immich/data/upload \
  /srv/immich/data/profile \
  /srv/immich/.env \
  /srv/immich/docker-compose.yml
docker start immich_server

O restic lê toda a árvore em cada execução, mas só carrega blocos que ainda não encontrou. Assim, o primeiro snapshot transfere toda a biblioteca e cada snapshot seguinte transfere apenas as fotografias novas do dia.

Retenção e as chaves que devem ficar noutro local

restic forget --prune --keep-daily 7 --keep-weekly 5 --keep-monthly 12

forget remove snapshots do índice. --prune é a parte que elimina os dados para os quais esses snapshots eram a última referência. Execute forget sem --prune e o custo do armazenamento nunca diminui.

As verificações de estrutura são rápidas, por isso execute uma vez por semana:

restic check

Isto verifica se os metadados do repositório são consistentes. Não lê os seus dados. Uma vez por mês, volte a ler uma amostra e compare-a com os hashes registados:

restic check --read-data-subset=5%

Esta é a única verificação que deteta corrupção silenciosa no backend de armazenamento, porque descarrega blocos reais e recalcula os respetivos checksums. Um --read-data completo numa biblioteca de fotografias implica descarregar todo o repositório. Num armazenamento de objetos com tarifação por utilização, isso tem um custo real. Por isso, um subconjunto rotativo é a opção que as pessoas realmente usam.

Agora, a parte que muitas pessoas ignoram. A palavra-passe de um repositório restic não pode ser recuperada. Não existe reposição nem pedido de suporte. Se a única cópia estiver em /root/.restic-password no servidor que está a tentar restaurar, os seus backups são dados encriptados sem utilidade. O mesmo se aplica à chave de acesso ao armazenamento de objetos e a DB_PASSWORD de .env. Guarde todos esses dados num local que não dependa de esta máquina estar ativa: impressos e guardados numa gaveta, ou num gestor de palavras-passe executado noutro hardware. Se esse gestor também for self-hosted, precisa do mesmo tratamento, e fazer backup do Vaultwarden é uma tarefa independente.

Restaure o Immich pela ordem correta

A ordem da restauração é o que transforma backups válidos em cronologias vazias. Siga esta sequência no novo host.

Recupere primeiro a configuração. Ela indica qual versão deve executar e para onde apontam os caminhos.

restic restore latest --target /restore \
  --include /srv/immich/.env \
  --include /srv/immich/docker-compose.yml \
  --include /srv/immich/backup

Fixe a versão antes de iniciar qualquer componente. Leia immich-version.txt, defina IMMICH_VERSION em .env com essa versão exata (v3.1.0 para major 3, minor 1, patch 0) e deixe a versão mais recente de lado por enquanto. O Immich não suporta downgrade, nem mesmo entre versões patch. Se um servidor mais recente arrancar com um dump antigo e executar as migrações, não há forma de voltar atrás.

Restaure os ficheiros multimédia.

restic restore latest --target /restore --include /srv/immich/data

Depois, mova library, upload e profile para ficarem diretamente dentro do caminho indicado por UPLOAD_LOCATION neste host. O caminho no host pode mudar, porque o ficheiro compose associa esse diretório a um caminho fixo dentro do container. O layout interno não pode mudar.

Inicie apenas a base de dados. Deixe DB_DATA_LOCATION vazio para que o Postgres inicialize um cluster novo.

cd /srv/immich
docker compose pull
docker compose create
docker start immich_postgres
docker exec immich_postgres pg_isready --username=postgres

pg_isready imprime accepting connections depois de concluir a configuração inicial, o que demora alguns segundos. docker compose create cria todos os containers sem os iniciar, e esse é o objetivo desta etapa: o servidor Immich ainda não pode executar. Um servidor que arranca com uma base de dados vazia executa as migrações, cria um schema novo e pede que crie uma conta de administrador nova. Nesse momento, estará a restaurar um dump por baixo de uma aplicação em execução.

Restaure o dump.

gunzip --stdout /restore/srv/immich/backup/immich.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

Duas partes deste comando são essenciais. sed existe porque pg_dump grava um search_path vazio no output como medida de segurança. Assim, os nomes não qualificados no dump não podem ser resolvidos para um schema inesperado. Os tipos de pesquisa vetorial do Immich estão em public. Com um search path vazio, a restauração chega à primeira coluna declarada com um tipo vector e o psql termina com ERROR: type "vector" does not exist. Voltar a colocar public no path resolve o problema.

--single-transaction --set ON_ERROR_STOP=on envolve toda a restauração numa única transação que é abortada no primeiro erro. O resultado é uma base de dados completa ou uma base de dados intacta. Sem esta opção, uma falha a meio deixa uma base de dados que arranca, aceita o seu login e tem um número desconhecido de álbuns em falta. O problema pode só ser descoberto semanas mais tarde.

Agora inicie tudo.

docker compose up -d
docker compose ps
docker logs -f immich_server

Aguarde uma linha de arranque como Immich Server is listening on. Depois, abra a porta 2283 e inicie sessão com as credenciais antigas, porque as contas de utilizador foram restauradas com o dump. Se a página de login oferecer a criação da primeira conta de administrador, a base de dados não foi restaurada. Pare e volte a consultar o output do psql.

Existe um aviso sobre as instruções oficiais de restauração pela linha de comandos, que começam com docker compose down -v. -v remove volumes nomeados. No ficheiro compose padrão, UPLOAD_LOCATION e DB_DATA_LOCATION são bind mounts, por isso sobrevivem ao comando. Se tiver alterado algum deles para um volume nomeado, esse comando elimina as suas fotografias. Leia o ficheiro compose antes de o executar.

Por que a linha do tempo fica vazia depois de uma restauração

A linha do tempo é criada a partir das linhas da base de dados. O Immich nunca percorre upload/ no arranque para redescobrir fotografias, porque um ficheiro sem uma linha não tem proprietário, data nem álbum. Por isso, o problema mais comum numa restauração é ter os ficheiros de volta, mas não a base de dados. O Immich arranca, cria um esquema vazio e disponibiliza uma instância funcional sem conteúdo, enquanto o disco está cheio das suas fotografias. Nada foi perdido. Mas também nada fica visível. A correção é reproduzir o dump com o servidor parado, exatamente como acima.

A segunda variante é mais silenciosa. A base de dados é restaurada, a linha do tempo é preenchida com entradas, mas todos os recursos falham ao abrir. Isso significa que as linhas apontam para ficheiros que o contentor não consegue ver, normalmente porque library, upload e profile ficaram um nível demasiado abaixo depois de um restic restore --target /restore que ninguém colocou no local correto. Verifique a partir de dentro do contentor em vez de tentar adivinhar:

docker exec immich_server ls /data

O ficheiro compose padrão monta UPLOAD_LOCATION em /data, portanto essa listagem deve mostrar library, upload e profile. Se mostrar um diretório vazio ou uma pasta srv inesperada, a sua montagem bind aponta para o nível errado e as linhas estão corretas.

Compatibilidade de versões entre o backup e o restauro

O Immich publica versões com frequência e o esquema acompanha essas versões. Por isso, um dump contém o esquema do servidor que o criou.

Normalmente, restaurar um dump antigo num servidor mais recente funciona, porque o servidor aplica as migrações pendentes ao arrancar e atualiza progressivamente o esquema. A própria documentação de backup do Immich recomenda restaurar numa versão compatível sempre que possível, porque uma incompatibilidade de versões faz com que as migrações sejam executadas durante o restauro. O projeto reserva as alterações incompatíveis para as versões major e documenta-as nas notas de versão. Por isso, um restauro que atravesse uma versão major é o caso que deve ser analisado primeiro.

Restaurar um dump mais recente num servidor antigo não funciona. O dump contém tabelas e colunas que o código antigo não conhece, e o Immich indica que o downgrade não é suportado, nem mesmo entre versões patch. Não existe um comando de rollback para utilizar.

Por isso, o restauro seguro é previsível. Execute exatamente a versão que criou o dump, reaplique-o, inicie sessão, confirme que a cronologia está completa e só depois faça o upgrade. Faça o upgrade conforme descrito na página oficial de upgrade: leia as notas de versão para identificar alterações incompatíveis, defina IMMICH_VERSION em .env com a versão pretendida e execute docker compose pull && docker compose up -d. Manter uma semana de dumps também ajuda neste caso: se o mais recente tiver sido criado durante um upgrade que falhou, o dump do dia anterior continua disponível no repositório.

Verifique o backup todos os meses

Um backup que nunca foi restaurado é apenas uma suposição. Uma vez por mês, restaure-o numa instância descartável e veja uma fotografia. O teste demora cerca de vinte minutos e é a única coisa que transforma o resto desta página num plano de recuperação.

restic snapshots
restic stats latest

snapshots deve listar a execução da noite anterior. stats latest deve indicar um tamanho próximo do da sua biblioteca, não apenas alguns megabytes.

Restaure o backup num diretório temporário, idealmente num host sobressalente:

restic restore latest --target /tmp/immich-drill

Copie docker-compose.yml e .env para fora do conjunto restaurado e altere três coisas na cópia. Aponte UPLOAD_LOCATION e DB_DATA_LOCATION para diretórios dentro de /tmp/immich-drill. Publique a porta Web noutro local, 12283:2283 em vez de 2283:2283. Elimine as linhas container_name:, porque o ficheiro compose fornecido define nomes fixos como immich_server. Assim, uma segunda stack no mesmo host entra em conflito com a primeira e o Docker recusa-se a criá-la.

Execute a sequência de restauração apresentada acima: apenas a base de dados, reproduza o dump e, depois, docker compose up -d. Em seguida, faça as quatro verificações que comprovam o resultado.

1. Inicie sessão com a palavra-passe que utilizava antes do teste. Contas funcionais significam que o dump foi restaurado.
2. Abra a linha temporal e avance até ao mês mais antigo. A existência de ativos em todo o intervalo de datas significa que todas as linhas foram restauradas, não apenas as recentes.
3. Abra uma fotografia no tamanho máximo e transfira o original.
4. Compare-a com o mesmo ficheiro na sua biblioteca ativa usando sha256sum. Hashes iguais significam que os bytes sobreviveram ao percurso de ida e volta através do restic.

Em seguida, desmonte o teste com docker compose down -v no diretório do teste e elimine /tmp/immich-drill. Registe a data num local onde a veja, porque o valor deste procedimento está inteiramente em repeti-lo no mês seguinte. Se ainda estiver a decidir qual servidor de fotografias utilizar, a comparação entre PhotoPrism e Immich explica como os dois diferem precisamente neste aspeto.

FAQ

Tenho de parar o Immich para fazer uma cópia de segurança?

Pare immich_server e deixe immich_postgres em execução. A base de dados não precisa de ser parada, porque pg_dump lê dentro de um snapshot MVCC e vê um único instante consistente, independentemente das outras operações de escrita. A razão para parar são os ficheiros: o servidor escreve novos uploads e o job do template de armazenamento move ficheiros entre diretórios. Por isso, uma ferramenta de backup pode ler um ficheiro a meio de uma escrita e guardar uma cópia truncada sem apresentar qualquer erro. docker stop immich_server antes do snapshot e docker start immich_server depois dele elimina essa condição de corrida.

Posso copiar a pasta de dados do Postgres em vez de executar pg_dump?

Não enquanto o Postgres estiver em execução. Uma cópia progressiva de um diretório de dados ativo lê ficheiros diferentes em instantes diferentes. O resultado não representa um estado consistente, e o Postgres rejeita-o no arranque com PANIC: could not locate a valid checkpoint record ou falha mais tarde ao encontrar uma página danificada. Uma cópia completa feita com o Postgres parado é um backup válido, mas só pode ser aberta com a mesma versão principal do Postgres e com extensões compatíveis. O Immich fixa uma imagem do Postgres 14 que inclui VectorChord, pgvector e pgvecto.rs, e o diretório não será aberto por uma versão principal diferente. Um dump SQL é texto simples e pode ser restaurado em qualquer servidor compatível. Continua, por isso, a ser a cópia que deve manter.

Porque é que a minha timeline do Immich está vazia depois de uma restauração?

Porque a timeline é construída a partir de linhas da base de dados e restaurou os ficheiros sem a base de dados. O Immich nunca analisa upload/ para voltar a descobrir fotografias. Por isso, os ficheiros sem linhas correspondentes permanecem invisíveis. As fotografias em si não foram alteradas. Pare o servidor, restaure o dump numa instância do Postgres inicializada de novo e, em seguida, inicie a stack. Se, pelo contrário, a timeline estiver completa mas todas as fotografias falharem ao abrir, o problema é inverso: library, upload e profile não estão diretamente dentro do diretório montado no container. Verifique com docker exec immich_server ls /data.

Que pastas do Immich posso excluir de um backup?

thumbs e encoded-video são regenerados a partir dos originais, e DB_DATA_LOCATION é reconstruído a partir do dump. Por isso, nenhum deles precisa de fazer parte do conjunto de backup. Excluí-los transfere o custo para depois da restauração, em vez de consumir armazenamento antes dela. A reconstrução de previews e transcodificações para uma biblioteca grande pode consumir horas de CPU e é executada em Administration > Jobs para os assets em falta. O que nunca pode excluir é library, upload e profile, que contêm a única cópia de cada original.

Posso restaurar um dump do Immich numa versão mais recente?

Normalmente, sim, porque o servidor aplica as migrações pendentes no arranque e atualiza progressivamente o schema. O inverso falha: o Immich não suporta downgrades, nem mesmo entre versões de patch. Por isso, um dump de uma versão mais recente não pode ser carregado num servidor mais antigo. Faça a restauração com IMMICH_VERSION fixado na versão que escreveu o dump, confirme que a timeline está completa e só depois atualize. Registe a versão junto de cada dump com curl -fsS http://localhost:2283/api/server/version, porque docker inspect apenas mostra a referência da imagem configurada, e o valor predefinido de IMMICH_VERSION=v3 é uma tag flutuante que não fornece qualquer informação útil.