Tutoriais de VPS
Immich auto-hospedado em VPS (2026): Docker Compose, sincronização móvel, armazenamento e armadilhas de backup
Este tutorial é para usuários que querem criar o próprio serviço de backup de fotos em um VPS. Você vai aprender a implantar o Immich com o Docker Compose oficial, configurar o diretório de upload, o diretório do banco de dados, a versão e a senha, servir HTTPS por meio de um proxy reverso, conectar o app móvel para backup automático e, acima de tudo, entender as armadilhas fáceis de ignorar: capacidade de armazenamento, backup do banco de dados, atualizações e segurança na rede pública.
Immich auto-hospedado em VPS (2026): Docker Compose, sincronização móvel, armazenamento e armadilhas de backup
À medida que as fotos do celular se acumulam, muita gente começa a se debater com a mesma pergunta: continuar comprando espaço no iCloud, Google Photos ou OneDrive, ou trazer as fotos de volta para o próprio servidor? Se você já tem um VPS, o Immich é hoje uma das opções de código aberto mais próximas de um "Google Photos auto-hospedado": backup automático do celular, navegação por linha do tempo, reconhecimento facial, compartilhamento de álbuns, prévia de vídeos e interface web de administração são bastante completos.
Mas o Immich não é uma ferramentinha que se resolve "rodando um contêiner e esquecendo". Fotos e vídeos consomem disco continuamente, tanto o banco de dados quanto o diretório de upload precisam de backup, os componentes de machine learning consomem memória e as atualizações exigem mais cuidado do que um site estático comum. Este artigo não traz apenas comandos de instalação; ele também explica as armadilhas mais fáceis de cair ao implantar o Immich em um VPS: onde colocar o armazenamento, como expor as portas, como os celulares sincronizam, o que deve ser incluído no backup e quando um VPS pequeno não é o lugar certo para o Immich.
Resposta direta: sim, mas depende do tamanho da sua fototeca e do seu orçamento.
Casos em que a implantação em VPS faz sentido:
- Você quer um ponto de entrada privado de backup de fotos para você ou para os membros da família.
- Suas fotos ocupam de dezenas de GB a algumas centenas de GB e você aceita expandir o disco conforme a necessidade.
- Você quer que o app móvel faça upload automático, sem rsync ou SFTP manual.
- Você está disposto a fazer backup periódico do banco de dados e do diretório de upload.
- Você tem um domínio e pode acessar por HTTPS.
Casos em que faz menos sentido:
- Você já tem vários TB de fotos e vídeos, mas comprou apenas um disco de VPS pequeno.
- Você quer que ele seja seu único backup, sem uma segunda cópia.
- A máquina tem apenas 512 MB de memória e você ainda quer rodar muitos serviços nela.
- Você não quer manter Docker, PostgreSQL, proxy reverso e um processo de atualização.
A experiência do Immich é boa, mas backup de fotos é um negócio de dados de longo prazo. O que você realmente precisa considerar não é "se ele inicia hoje", mas se conseguirá recuperá-lo daqui a seis meses, quando o disco encher, uma atualização falhar ou o banco de dados quebrar.
Se for apenas um teste pessoal:
| Uso | Configuração sugerida |
|---|---|
| Testar com poucas fotos | 2 vCPU / 2 GB RAM / 40 GB SSD |
| Uso pessoal de longo prazo | 2-4 vCPU / 4 GB RAM / 100 GB+ SSD |
| Uso familiar com várias pessoas | 4 vCPU / 8 GB RAM / 300 GB+ SSD ou armazenamento extra montado |
O Immich inclui componentes como server, machine learning, Redis/Valkey e PostgreSQL. Com pouca memória ele até inicia com dificuldade, mas as tarefas em segundo plano de miniaturas, transcodificação de vídeo, reconhecimento facial e machine learning pioram a experiência.
Se o disco do VPS não for grande, não convém importar todas as fotos originais do celular logo de início. Primeiro teste com um álbum de teste o fluxo de upload, navegação, backup e restauração, e depois decida se migra a fototeca principal.
Antes de começar, prepare:
- Um VPS com Ubuntu 22.04 / 24.04 ou Debian 12.
- Docker Engine e o plugin do Docker Compose instalados.
- Um domínio, por exemplo
photos.example.com. - Um firewall que abra apenas as portas necessárias.
- Um diretório de disco grande o suficiente, por exemplo
/opt/immich/library.
Confirme que o Docker está disponível:
docker version
docker compose version
Se você usar o Docker antigo dos repositórios do sistema, pode encontrar incompatibilidades de sintaxe do Compose. A documentação oficial do Immich também lembra: o comando correto é docker compose, não o antigo docker-compose. Se aparecer um erro estranho do Compose, instale primeiro a versão do repositório oficial do Docker.
Recomenda-se colocar o Immich em /opt/immich:
sudo mkdir -p /opt/immich
sudo chown -R "$USER":"$USER" /opt/immich
cd /opt/immich
Todos os arquivos de configuração ficarão nesse diretório, o que facilita o backup e a migração.
O Immich recomenda oficialmente a implantação com Docker Compose e exige o arquivo compose correspondente à release atual.
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env
Após o download, o diretório deve conter:
ls -la
No mínimo você deve ver:
docker-compose.yml
.env
Não copie diretamente para produção o arquivo compose da branch main do GitHub, porque a branch main pode ser incompatível com a release mais recente. Usar o link de download da release é mais estável.
Abra .env:
nano .env
Concentre-se nestas variáveis:
UPLOAD_LOCATION=/opt/immich/library
DB_DATA_LOCATION=/opt/immich/postgres
TZ=Asia/Shanghai
IMMICH_VERSION=v2
DB_PASSWORD=换成一串随机密码
O que essas variáveis significam:
UPLOAD_LOCATION: diretório de upload de fotos e vídeos, precisa ter espaço suficiente.DB_DATA_LOCATION: diretório de dados do PostgreSQL. O exemplo oficial avisa que o diretório do banco de dados não é compatível com compartilhamentos de rede.TZ: fuso horário; usuários da China continental costumam usarAsia/Shanghai.IMMICH_VERSION: versão do Immich usada. Você pode usarv2; a abordagem mais cautelosa é fixar uma versão específica.DB_PASSWORD: senha do PostgreSQL. Recomenda-se uma string aleatória contendo apenas letras e números, para evitar problemas quando o Docker interpreta caracteres especiais.
Gere uma senha aleatória simples:
openssl rand -base64 24 | tr -dc 'A-Za-z0-9' | head -c 24
Crie os diretórios de armazenamento:
mkdir -p /opt/immich/library /opt/immich/postgres
No diretório /opt/immich, execute:
docker compose up -d
Verifique o status dos contêineres:
docker compose ps
Veja os logs:
docker compose logs -f --tail=100
O compose oficial expõe 2283:2283 por padrão, então você pode acessar temporariamente:
http://服务器IP:2283
Se a página abrir, o serviço está no ar. No primeiro acesso, crie a conta de administrador e depois vá para as configurações do sistema.
Acessar diretamente IP:2283 durante os testes não tem problema, mas para uso a longo prazo não é recomendado expor o Immich em uma porta pública.
Mais recomendado:
公网用户 -> Caddy/Nginx :443 -> 127.0.0.1:2283 -> Immich
Você pode alterar a porta no compose para escutar apenas no localhost:
ports:
- '127.0.0.1:2283:2283'
Depois reinicie:
docker compose up -d
Assim, o exterior não consegue acessar IP:2283 diretamente; só é possível chegar pelo domínio do proxy reverso.
Supondo que o domínio seja photos.example.com, o Caddyfile pode ser escrito assim:
photos.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:2283
}
Após modificar, valide e recarregue:
sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
Depois acesse:
https://photos.example.com
Se você usa Nginx, também pode fazer proxy reverso para 127.0.0.1:2283. O ponto não é Caddy versus Nginx, mas não expor a entrada de administração e a de upload diretamente em portas sem controle.
O Immich tem clientes para Android e iOS. O fluxo geral é:
- Instale o app do Immich no celular.
- No Server URL, informe seu endereço HTTPS, por exemplo
https://photos.example.com. - Faça login com a conta que você acabou de criar.
- Selecione os álbuns que deseja incluir no backup.
- Ative opções como backup em segundo plano e backup somente por Wi-Fi.
O primeiro backup pode ser muito lento, especialmente se o celular já tiver muitas fotos e vídeos. Sugestões:
- Comece com apenas um álbum de teste.
- Confirme que as fotos aparecem na web.
- Confirme que o crescimento do disco do VPS corresponde ao esperado.
- Depois ative aos poucos o backup de todos os álbuns.
Não envie de uma vez dezenas de milhares de fotos. A primeira importação é a fase em que problemas de disco, largura de banda, aquecimento e permissões em segundo plano aparecem com mais facilidade.
O Immich guarda fotos e vídeos no diretório indicado por UPLOAD_LOCATION. Ao planejar a capacidade, não olhe apenas o tamanho atual do álbum do celular; considere também:
- Novas fotos e vídeos do próximo ano.
- Arquivos de vídeo costumam ser muito maiores que as fotos.
- Miniaturas, arquivos transcodificados e caches de machine learning também ocupam espaço.
- Os arquivos de backup também precisam de espaço extra.
Verifique o uso do diretório:
du -sh /opt/immich/library
Verifique o disco:
df -h
Se você prevê que a fototeca vai ultrapassar rapidamente o disco do sistema do VPS, convém colocar UPLOAD_LOCATION desde o início em um disco de dados montado separadamente, por exemplo:
UPLOAD_LOCATION=/mnt/photos/immich-library
Mas o diretório do banco de dados DB_DATA_LOCATION não é recomendado em compartilhamento de rede. Bancos de dados são mais sensíveis a latência e consistência e devem ficar em SSD local ou armazenamento em bloco confiável.
O Immich não é em si uma ferramenta de backup; é um serviço de gerenciamento e sincronização de fotos. Um backup de verdade precisa incluir pelo menos duas partes:
- O diretório de upload:
UPLOAD_LOCATION - O diretório do banco de dados ou uma exportação do PostgreSQL
Se você fizer backup apenas dos arquivos de fotos e não do banco de dados, após a restauração os álbuns, usuários, metadados e resultados de reconhecimento podem ficar incompletos. Se fizer backup apenas do banco de dados e não do diretório de upload, também não faz sentido.
Uma ideia simples de arquivamento:
mkdir -p /opt/backups/immich
tar czf /opt/backups/immich/immich-library-$(date +%F).tar.gz -C /opt/immich library
Para o banco de dados, é melhor exportar com as ferramentas do PostgreSQL do que copiar o diretório de dados em execução. Você pode entrar no contêiner do banco de dados e executar:
docker compose exec database pg_dump -U postgres immich > /opt/backups/immich/immich-db-$(date +%F).sql
Depois que o backup terminar, use rclone, armazenamento de objetos ou outro servidor para guardar uma segunda cópia. O que mais assusta em backup de fotos é "ter só uma cópia, e ainda na mesma máquina".
O Immich é atualizado com bastante frequência, então não se recomenda atualização automática sem critério. Antes de atualizar:
- Leia as notas da release.
- Faça backup de
.envedocker-compose.yml. - Faça backup do banco de dados e do diretório de upload.
- Baixe o novo compose ou atualize a variável de versão.
- Execute
docker compose pull. - Depois
docker compose up -d.
Comandos básicos:
cd /opt/immich
cp .env .env.bak.$(date +%F)
cp docker-compose.yml docker-compose.yml.bak.$(date +%F)
docker compose pull
docker compose up -d
Veja os logs após a atualização:
docker compose logs -f --tail=100
Se você usar uma tag de versão específica, o ritmo de atualização fica mais controlável; se seguir diretamente v2 ou release, dá menos trabalho, mas as mudanças chegam mais rápido.
Verifique os contêineres:
docker compose ps
docker compose logs --tail=100 immich-server
Verifique as portas:
ss -lntp | grep 2283
Se você vinculou a porta a 127.0.0.1, o acesso público a IP:2283 não vai funcionar de qualquer forma; é preciso acessar pelo domínio do proxy reverso.
Causas comuns:
- Largura de banda do VPS muito pequena.
- Permissões em segundo plano do celular restritas.
- Arquivos demais no primeiro upload.
- I/O de disco do VPS fraco.
- Limite de tamanho de upload do proxy reverso muito pequeno.
Teste primeiro com poucas fotos e vá liberando aos poucos.
Verifique os diretórios:
du -h --max-depth=1 /opt/immich | sort -h
Observe principalmente library, postgres, o overlay do Docker e os logs. Não apague sem critério os diretórios internos do Immich; primeiro confirme quais são cache e quais são arquivos de upload originais.
O componente de machine learning do Immich é usado para busca, reconhecimento facial e funções semelhantes. Se a configuração do VPS for muito baixa, a primeira varredura elevará o uso de CPU e memória. Você pode deixá-la terminar em horários de pouco movimento ou reduzir temporariamente o volume de importação.
Se suas fotos já passam de 1 TB e continuam crescendo todos os dias, um VPS pequeno pode não ser o lugar mais adequado. Você precisa considerar:
- O custo de expansão do armazenamento em bloco.
- O custo do tráfego de saída.
- O custo de fazer backup em um segundo local.
- As limitações do provedor de VPS para tráfego intenso de longo prazo.
- O tempo de recuperação dos dados.
Nesses casos, um NAS doméstico, armazenamento de objetos, um servidor dedicado de disco grande ou uma solução híbrida podem ser mais adequados. O Immich pode ser implantado em um VPS, mas, em um negócio como uma fototeca que cresce a longo prazo, o gargalo final costuma ser o armazenamento e o backup, não os comandos de instalação.
Implantar o Immich em um VPS não é complicado: baixe o docker-compose.yml e o .env oficiais, configure o diretório de upload, o diretório do banco de dados, a versão e a senha, e execute docker compose up -d para ele rodar.
O que realmente merece atenção é a segunda parte: não exponha portas, use um domínio HTTPS; não coloque o banco de dados em compartilhamento de rede; não faça backup apenas das fotos sem o banco de dados; não atualize automaticamente sem critério; não importe todas as fotos de uma vez em um VPS com pouco disco.
Se você só quer experimentar o backup de fotos auto-hospedado, o Immich é muito adequado para começar com um VPS de 2-4 GB de memória; se quiser transformá-lo em um centro familiar de fotos de longo prazo, planeje juntos o armazenamento, o backup, os testes de restauração e o processo de atualização.