Ir para o conteúdo principal

Backup e Restauração

Uma estratégia de backup 3-2-1 é recomendada para proteger seus dados. Você deve manter cópias das fotos/vídeos enviados, assim como o banco de dados do Immich para uma solução de backup abrangente. Esta página fornece uma visão geral de como fazer backup do banco de dados e da localização das imagens e vídeos enviados pelos usuários. Um script bash de modelo que pode ser executado como um cron job é fornecido aqui.

perigo

As instruções desta página mostram como preparar sua instância do Immich para ser feita o backup, e quais arquivos copiar. Você ainda precisará utilizar uma ferramenta real de backup para criar o backup você mesmo.

Banco de Dados​

cuidado

O Immich salva caminhos de arquivos no banco de dados, não escaneia a pasta da biblioteca para atualizar o banco de dados, por isso os backups são cruciais.

informação

Consulte a documentação oficial do postgres para obter detalhes sobre como fazer o backup e a restauração de um banco de dados postgres.

cuidado

Não é recomendado fazer backup diretamente da pasta DB_DATA_LOCATION. Fazer isso com o banco de dados em execução pode gerar um backup corrompido que não pode ser restaurado.

Dumps Automáticos do Banco de Dados​

aviso

Os dumps automáticos do banco de dados podem ser utilizados para restaurar o banco de dados em caso de danos aos arquivos do banco de dados Postgres. Não há monitoramento desses dumps e você não será notificado se forem malsucedidos.

cuidado

Os dumps do banco de dados NÃO contêm fotos ou vídeos, somente metadados. Eles só podem ser usados junto com uma cópia dos outros arquivos em UPLOAD_LOCATION, conforme indicado abaixo.

Para fins de recuperação de desastres, o Immich criará automaticamente dumps do banco de dados. Os dumps são armazenados em UPLOAD_LOCATION/backups. Certifique-se de fazer seu próprio backup independente do banco de dados junto com as pastas de ativos mencionadas abaixo. Você pode ajustar a programação e a quantidade de dumps do banco de dados mantidos nas configurações do administrador. Por padrão, o Immich manterá os últimos 14 dumps de banco de dados e criará um novo dump todos os dias às 2:00 da manhã.

Gatilho de Dump​

Você pode acionar um dump do banco de dados na página de status de tarefas do administrador. Visite a página, abra o modal "Criar tarefa" no canto superior direito, selecione "Criar Dump do Banco de Dados" e clique em "Confirmar". Uma tarefa será executada e acionará um dump, você pode verificar se isso funcionou corretamente consultando os logs ou a pasta backups/. Esses dumps contarão para os últimos X dumps que serão mantidos com base em suas configurações.

Restaurando​

Esperamos tornar a restauração mais simples em versões futuras, por enquanto, você pode encontrar os dumps do banco de dados na pasta UPLOAD_LOCATION/backups no seu host. Em seguida, siga as etapas na seção seguinte para restaurar o banco de dados.

Backup e Restauração Manual​

Backup
docker exec -t immich_postgres pg_dumpall --clean --if-exists --username=<DB_USERNAME> | gzip > "/path/to/backup/dump.sql.gz"
Restauração
docker compose down -v  # ATENÇÃO! Exclui todos os dados do Immich para começar do zero
## Descomente a próxima linha e substitua DB_DATA_LOCATION pelo caminho do Postgres para redefinir permanentemente o banco de dados Postgres
# rm -rf DB_DATA_LOCATION # ATENÇÃO! Exclui todos os dados do Immich para começar do zero
docker compose pull             # Atualizar para a versão mais recente do Immich (se desejado)
docker compose create           # Criar contêineres Docker para aplicativos Immich sem executá-los
docker start immich_postgres    # Iniciar o servidor Postgres
sleep 10                        # Aguarde o servidor Postgres iniciar
# Verifique o usuário do banco de dados se você se desviou do padrão
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=postgres --username=<DB_USERNAME>  # Restaurar Backup
docker compose up -d            # Iniciar o restante dos aplicativos Immich

Observe que, para que a restauração do banco de dados prossiga corretamente, é necessário uma instalação completamente nova (ou seja, o servidor Immich nunca foi executado desde a criação dos contêineres Docker). Se o aplicativo Immich tiver sido executado, podem ocorrer conflitos no Postgres durante a restauração do banco de dados (relação já existe, violação de restrições de chave estrangeira, múltiplas chaves primárias, etc.), caso em que você precisará excluir a pasta DB_DATA_LOCATION para redefinir o banco de dados.

dica

Alguns métodos de implantação dificultam o início do banco de dados sem também iniciar o servidor. Nesses casos, você pode configurar a variável de ambiente DB_SKIP_MIGRATIONS=true antes de iniciar os serviços. Isso impedirá que o servidor execute migrações que interfiram no processo de restauração. Certifique-se de remover essa variável e reiniciar os serviços após a restauração do banco de dados.

Sistema de Arquivos​

O Immich armazena dois tipos de conteúdo no sistema de arquivos: (a) ativos originais, não modificados (fotos e vídeos), e (b) conteúdo gerado. Recomendamos fazer backup de todo o conteúdo de UPLOAD_LOCATION, mas apenas o conteúdo original é crítico, que está armazenado nas seguintes pastas:

  1. UPLOAD_LOCATION/library
  2. UPLOAD_LOCATION/upload
  3. UPLOAD_LOCATION/profile

Se você optar por fazer backup apenas dessas pastas, precisará executar novamente os trabalhos de transcodificação e geração de miniaturas para todos os ativos após restaurar de um backup.

cuidado

Se você moveu algumas dessas pastas para um dispositivo de armazenamento diferente, como profile/, certifique-se de ajustar o caminho do backup para corresponder à sua configuração.

Tipos de Ativos e Localizações de Armazenamento​

Algumas localizações de armazenamento são afetadas pelo Template de Armazenamento. Veja abaixo mais detalhes.

nota

A pasta UPLOAD_LOCATION/library não é utilizada por padrão em novas máquinas executando a versão 1.92.0. Ela é usada apenas se o administrador do sistema ativou o mecanismo de template de armazenamento, para mais informações, leia as notas de lançamento.

1. Pastas Específicas de Usuário:

  • Cada usuário possui uma string única que o representa.
  • Você pode encontrar seu ID de usuário em Configurações da Conta -> Conta -> ID do Usuário.

2. Tipos de Ativos e Localizações de Armazenamento:

  • Ativos de Origem:

    • Ativos originais enviados pela interface do navegador, mobile e CLI.
    • Armazenados em UPLOAD_LOCATION/upload/<userID>.

  • Imagens de Avatar:

    • Imagens do perfil do usuário.
    • Armazenadas em UPLOAD_LOCATION/profile/<userID>.

  • Imagens de Miniaturas:

    • Imagens de visualização (miniaturas pequenas e pré-visualizações grandes) para cada ativo e miniaturas para rostos reconhecidos.
    • Armazenadas em UPLOAD_LOCATION/thumbs/<userID>.

  • Ativos Codificados:

    • Vídeos que foram recodificados do original para maior compatibilidade. O original não é removido.
    • Armazenados em UPLOAD_LOCATION/encoded-video/<userID>.

  • Postgres

    • O banco de dados do Immich contendo todas as informações necessárias para o funcionamento adequado do sistema.
      Nota: Esta pasta aparecerá apenas para usuários que realizaram as alterações mencionadas em v1.102.0 (uma alteração opcional, não obrigatória) ou que começaram com esta versão.
    • Armazenado em DB_DATA_LOCATION.
    perigo

    Um backup desta pasta não constitui um backup do seu banco de dados! Siga as instruções listadas aqui para aprender como realizar um backup adequado.

perigo

Não toque nos arquivos dentro dessas pastas sob nenhuma circunstância, exceto ao fazer um backup. Alterar ou remover um ativo pode causar arquivos não rastreados e ausentes. Você pode pensar nisso como um App-Cujo-Nome-Não-Deve-Ser-Mencionado, o único acesso para visualizar, alterar e excluir ativos é apenas por meio da interface móvel ou do navegador.

Ordem do backup​

Um backup do Immich deve conter tanto o banco de dados quanto os arquivos de ativos. Ao fazer esses backups, é possível que eles fiquem fora de sincronização, potencialmente resultando em ativos corrompidos após a restauração. A melhor forma de lidar com isso é parar o contêiner do immich-server enquanto você realiza um backup. Se nada estiver mudando, o backup estará sempre sincronizado.

Se não for possível parar o contêiner, a ordem recomendada é fazer o backup do banco de dados primeiro e, em seguida, do sistema de arquivos. Dessa forma, o pior cenário é que existam arquivos no sistema de arquivos que o banco de dados não conhece. Se necessário, esses podem ser (re)enviados manualmente após a restauração. Se o backup for feito na ordem inversa, começando pelo sistema de arquivos e depois o banco de dados, é possível que o banco de dados restaurado faça referência a arquivos que não estão no backup do sistema de arquivos, resultando assim em ativos corrompidos.