O Immich pode consumir muito mais armazenamento do que a unidade do sistema do ZimaOS foi concebida para suportar, especialmente quando os carregamentos do telemóvel, as miniaturas, os vídeos codificados, os modelos de aprendizagem automática e a base de dados PostgreSQL começam a crescer. O guia original da IceWhale Community resolveu este problema em abril de 2025, alterando mapeamentos de volumes selecionados durante uma instalação personalizada do ZimaOS, para que os dados do Immich ficassem num volume RAID em vez da unidade do ZimaOS.
Essa solução alternativa é útil para compreender como o contentor está ligado, mas não deve ser tratada como uma receita universal atual. Respostas posteriores relataram instalações falhadas, reinícios repetidos, um contentor PostgreSQL não íntegro e até carregamentos de fotografias corrompidos após experiências com os mapeamentos. O ZimaOS também adicionou e aperfeiçoou ferramentas de migração integradas, enquanto as versões atuais do Docker Compose do Immich utilizam variáveis do lado do anfitrião, como UPLOAD_LOCATION e DB_DATA_LOCATION. Num sistema atual, utilize primeiro o percurso de migração integrado do ZimaOS, quando este se adequar ao seu objetivo, e reserve a edição manual de volumes para os casos em que necessite especificamente de uma disposição de armazenamento personalizada para o Immich.
O que o guia original do Immich no ZimaOS de 2025 alterou
O tutorial da comunidade utilizava a instalação personalizada do ZimaOS ou o ecrã Definições da aplicação após a instalação, e percorria os separadores do serviço um a um. O objetivo era redirecionar os dados persistentes do Immich para uma localização RAID com maior capacidade, mantendo os caminhos do lado do contentor esperados pelo Immich.
Base de dados: mover o caminho do anfitrião, manter o caminho do contentor
No separador da base de dados, o autor alterou a localização de armazenamento do lado do ZimaOS para um caminho RAID e manteve o sufixo do diretório da base de dados. O princípio importante era não reescrever o caminho do lado direito dentro do contentor. Alterar o destino do contentor pode interromper o serviço, porque o PostgreSQL espera encontrar os seus dados no caminho definido pelo pacote Immich ou pela configuração do Compose.
A documentação atual do Docker Compose do Immich expõe esta localização no anfitrião através de DB_DATA_LOCATION. O Immich também avisa que as partilhas de rede não são suportadas para a base de dados PostgreSQL, pelo que a base de dados deve permanecer num armazenamento local fiável e diretamente ligado, em vez de uma partilha SMB ou NFS.
Aprendizagem automática: redirecione a cache de modelos apenas se necessário
O guia original também redirecionava a cache de modelos de aprendizagem automática no anfitrião, mantendo inalterado o caminho da cache no contentor. Mover esta cache pode libertar espaço no disco do sistema, que é pequeno, embora seja menos importante do que proteger a biblioteca de fotografias e a base de dados, uma vez que os modelos transferidos podem normalmente ser recriados.
Servidor Immich: a secção de volumes mais sensível
O separador do servidor Immich foi a parte que o autor considerou mais fácil de danificar. Foram adicionados mapeamentos de anfitrião extra para que os diretórios de carregamentos e outros diretórios multimédia persistentes apontassem para o armazenamento RAID. O tópico salienta repetidamente que só devem ser alteradas as localizações pretendidas no anfitrião e que os caminhos no contentor não devem ser alterados de forma leviana.
O separador Redis não exigia alterações ao armazenamento no tutorial original. Este é outro motivo para não aplicar uma substituição indiscriminada a todas as entradas de volumes: os diferentes serviços do Immich têm requisitos de persistência diferentes.
Utilize primeiro a migração de dados do ZimaOS nos sistemas atuais
A atualização mais importante da discussão posterior é que o ZimaOS disponibiliza agora um fluxo de migração dedicado. Uma resposta da equipa da IceWhale no tópico alertou especificamente que copiar manualmente os dados das aplicações pode causar erros e recomendou utilizar a função de migração na maioria dos casos.
O guia atual de migração de dados do ZimaOS apresenta três categorias de armazenamento que podem ser movidas: imagens Docker, dados de aplicações Docker e bases de dados de utilizador. O procedimento normal é:
- Abra Definições > Migração de dados.
- Selecione a categoria de armazenamento que pretende mover.
- Escolha Modificar localização.
- Selecione o disco de destino ou o espaço de armazenamento.
- Consulte o aviso, inicie a migração e aguarde pelo relatório de conclusão.
Esta migração integrada é o melhor ponto de partida quando o seu objetivo é simplesmente manter os dados das aplicações Docker afastados da unidade do sistema ZimaOS. Também reduz a probabilidade de deixar caminhos, permissões ou ligações simbólicas inconsistentes após uma transferência manual.
E se quiser o Immich no SSD, mas as fotografias em RAID?
Uma pergunta posterior no tópico levantou uma disposição a longo prazo mais útil: manter a aplicação e os componentes sensíveis ao desempenho no SSD, mas colocar a grande biblioteca de fotografias em RAID. O autor original ainda não tinha testado essa configuração dividida, pelo que o próprio tópico não fornece uma receita ZimaOS verificada para a mesma.
A documentação atual do Immich disponibiliza, de facto, dois conceitos que ajudam a definir a disposição correta. Para multimédia carregado para o Immich, a configuração oficial do Docker Compose utiliza UPLOAD_LOCATION como caminho no anfitrião para o armazenamento multimédia. Para uma coleção existente de fotografias que o Immich deve indexar sem a importar para a sua área de carregamentos geridos, o Immich suporta bibliotecas externas.
Numa implementação padrão atual do Immich com Compose, os valores de ambiente relevantes são conceptualmente semelhantes a estes:
UPLOAD_LOCATION=/path/to/large-media-storage
DB_DATA_LOCATION=/path/to/local-database-storageNão cole esses caminhos cegamente numa definição de aplicação ZimaOS mais antiga. Primeiro, inspecione a configuração de Compose ou de instalação personalizada utilizada pelo pacote exato do Immich que tem instalado. O ficheiro Compose oficial atual do Immich monta ${UPLOAD_LOCATION} para o contentor do servidor e ${DB_DATA_LOCATION} para o PostgreSQL, enquanto versões mais antigas e pacotes da comunidade podem utilizar destinos internos diferentes.
Para obter informações atualizadas da origem, consulte o guia de instalação do Immich com Docker Compose e o guia do Immich para bibliotecas externas.
Porque é que as alterações manuais aos volumes podem fazer o Immich deixar de funcionar
As respostas mostram vários modos de falha depois de os utilizadores alterarem os mapeamentos de armazenamento. Um participante referiu inicialmente que a aplicação deixou de funcionar e disse mais tarde que começou a funcionar após vários reinícios. Outro utilizador afirmou que experiências repetidas fizeram o Immich deixar de funcionar e que alguns carregamentos a partir do telemóvel ficaram corrompidos. Um relato posterior descreveu falhas repetidas de instalação relacionadas com um serviço PostgreSQL não íntegro.
Esses relatos não provam a existência de um único erro partilhado. Contudo, mostram por que motivo a migração do armazenamento deve ser tratada como uma operação de integridade de dados, e não como uma simples alteração cosmética de caminho. Entre as causas comuns que vale a pena verificar incluem-se:
- Destino incorreto no contentor: o caminho no anfitrião pode ser personalizado, mas o caminho dentro do contentor tem de corresponder ao esperado por essa implementação do Immich.
- Permissões: o destino tem de permitir a escrita pelo utilizador do contentor ou pelo serviço proprietário dos ficheiros.
- Localização da base de dados: o PostgreSQL necessita de armazenamento local fiável e não deve ser colocado numa partilha de rede não suportada.
- Migrações incompletas: copiar manualmente apenas parte de uma árvore de dados existente do Immich pode deixar a base de dados e o armazenamento multimédia dessincronizados.
- Incompatibilidade de versões: a disposição dos volumes do Immich evoluiu, pelo que as instruções escritas para um pacote mais antigo podem não corresponder ao Immich v2, v3 ou a uma definição posterior da App Store do ZimaOS.
Lista de verificação para uma migração mais segura do armazenamento do Immich
- Faça uma cópia de segurança da base de dados do Immich e dos ficheiros multimédia insubstituíveis antes de alterar qualquer mapeamento de volumes.
- Confirme qual a versão do Immich e qual o pacote da App Store do ZimaOS que está a utilizar.
- Decida se pretende mover todos os dados da aplicação ou apenas a grande biblioteca multimédia.
- Se estiver a mover dados gerais de aplicações do ZimaOS, experimente Definições > Migração de dados antes de editar os caminhos de contentores individuais.
- Se utilizar uma configuração personalizada do Immich, registe todos os caminhos existentes no anfitrião e os destinos nos contentores antes de alterar qualquer coisa.
- Mantenha inalterados os destinos no contentor, salvo se a documentação da sua versão exata do Immich exigir explicitamente um caminho diferente.
- Certifique-se de que o sistema de ficheiros de destino está montado e permite escrita antes de recriar os contentores.
- Não coloque o diretório de dados do PostgreSQL numa partilha de rede não suportada.
- Após a migração, carregue um pequeno conjunto de teste e verifique os originais, as miniaturas, a reprodução de vídeos, os metadados e os novos carregamentos a partir do telemóvel antes de mover o resto da sua biblioteca.
- Mantenha a cópia antiga até ter verificado a base de dados e os ficheiros multimédia no novo armazenamento.
O que as respostas da comunidade acrescentaram ao guia original
As respostas mais úteis alteraram a interpretação do tutorial original de três formas. Primeiro, mostraram que o mapeamento manual podia funcionar, mas era sensível à versão exata da aplicação, às permissões de armazenamento e ao estado após o reinício. Segundo, os utilizadores queriam uma configuração dividida entre SSD e RAID, em vez de moverem todos os componentes do Immich para a mesma matriz. Terceiro, um membro da equipa da IceWhale recomendou a função de migração integrada e alertou para o facto de a cópia manual poder gerar erros.
Assim, a publicação original de 2025 deve ser entendida como um exemplo funcional da comunidade para a época, e não como uma especificação imutável para todas as versões posteriores do Immich ou do ZimaOS. Se a interface atual do ZimaOS já não apresentar os mesmos campos de «Instalação personalizada» mostrados nas capturas de ecrã, siga a interface de migração atual e consulte a configuração Compose da aplicação instalada, em vez de tentar recriar campos antigos.
Perguntas frequentes sobre o armazenamento do Immich no ZimaOS
Posso instalar o Immich numa unidade RAID em vez da unidade de sistema do ZimaOS?
Sim, mas distinga entre mover os dados da aplicação no ZimaOS e conceber uma estrutura multimédia personalizada para o Immich. Nas versões atuais do ZimaOS, utilize primeiro a função integrada de Migração de dados quando o objetivo for realocar os dados das aplicações Docker. Os mapeamentos manuais de volumes devem ser reservados para um desenho deliberado de armazenamento dividido.
Devo alterar o caminho do volume do Immich no lado direito, em «Instalação personalizada»?
Não, a menos que a documentação da sua implementação exata do Immich indique que o deve fazer. O guia original da comunidade alterava as localizações no anfitrião, preservando os destinos dentro do contentor. Reescrever um destino interno pode impedir o serviço de encontrar os diretórios esperados da base de dados, da cache ou dos ficheiros multimédia.
Posso manter o Immich no SSD e armazenar apenas as fotografias no RAID?
Sim, em princípio, e as versões atuais do Immich permitem escolher uma localização de carregamento no anfitrião, bem como montar Bibliotecas Externas. O mapeamento exato no ZimaOS depende do pacote e da versão do Immich instalados, por isso verifique a definição Compose atual antes de alterar os caminhos.
Porque é que o PostgreSQL fica com estado não íntegro depois de alterar a localização do armazenamento?
As possíveis causas incluem um destino de montagem incorreto, permissões em falta, ficheiros de base de dados incompletos ou armazenamento não suportado. Verifique se todo o diretório da base de dados foi transferido corretamente, se o destino é local e permite escrita e se o destino do contentor continua a corresponder à configuração Compose instalada.
Posso simplesmente copiar a pasta AppData do Immich para outro disco?
Esse não é o procedimento atualmente recomendado no ZimaOS. Um membro da equipa da IceWhale avisou especificamente na discussão que a cópia manual pode causar erros e recomendou a função de migração para a maioria das transferências de aplicações.
O guia ilustrado de abril de 2025 ainda está atualizado?
Continua a ser útil como explicação histórica dos mapeamentos de volumes do ZimaOS, mas tanto as funcionalidades de migração do ZimaOS como a configuração Compose do Immich mudaram desde então. Considere as capturas de ecrã como uma referência à configuração original e, em seguida, verifique os campos e caminhos apresentados na sua instalação atual antes de aplicar qualquer alteração.
