Immich: wymagania RAM, bezpieczna aktualizacja i błędy

Co budujesz

Immich to samodzielnie hostowana usługa do tworzenia kopii zapasowych zdjęć i filmów, stanowiąca realną alternatywę dla Google Photos. Posiada aplikację mobilną, która przesyła zawartość rolki aparatu w tle, oś czasu, albumy, rozpoznawanie twarzy oraz wyszukiwanie oparte na uczeniu maszynowym, które znajduje "plażę" lub konkretną osobę bez konieczności ręcznego tagowania. Uruchamiasz ją na własnym VPS, oryginalne pliki pozostają na Twoim dysku i nikt ich nie skanuje w celach reklamowych. Jeśli nadal rozważasz wybór między tym rozwiązaniem a innym oczywistym kandydatem, nasze porównanie PhotoPrism i Immich zestawia ich wymagania pamięciowe, aplikacje mobilne oraz polecenia tworzenia kopii zapasowych.

Instalacja obejmuje cztery kontenery z oficjalnego pliku Docker Compose projektu. Ta część zajmuje dziesięć minut. Reszta tego przewodnika dotyczy kwestii problematycznych: kontener uczenia maszynowego jest zasobożerny na małych maszynach, oryginały szybko zajmują miejsce na dysku, aplikacja mobilna wymaga dokładnego adresu URL serwera, a przed wystawieniem usługi poza sieć lokalną należy skonfigurować HTTPS. Ponadto Immich często wprowadza zmiany powodujące niekompatybilność, więc nieostrożne docker compose pull może uniemożliwić uruchomienie serwera. Potraktuj te cztery aspekty poważnie, a Immich będzie działać stabilnie. Zignoruj je, a stracisz cały weekend.

Wymagania wstępne i istotne uwagi

• RAM: oficjalna dokumentacja wskazuje 6 GB jako minimum i 8 GB jako wartość zalecaną; 4 GB wraz z plikiem wymiany (swap) należy traktować jako absolutne minimum. Kontenery immich-server oraz Postgres mają umiarkowane wymagania. Kontener immich-machine-learning jest najbardziej zasobożerny; ładuje on modele CLIP oraz rozpoznawania twarzy do pamięci RAM w celu budowania indeksów wyszukiwania, co na maszynie z 2 GB RAM prowadzi do jego ubicia przez jądro systemu. Dodaj swap, nawet jeśli dysponujesz 4 GB pamięci.
• Dysk: zaplanuj przestrzeń na całą bibliotekę z zapasem. Oryginalne pliki są kopiowane w całości, a Immich generuje dodatkowo miniatury oraz podglądy (zajmujące około 10–20% rozmiaru biblioteki). Kolekcja zdjęć o rozmiarze 200 GB wymaga wolumenu o pojemności 300 GB. Baza Postgres zajmuje w porównaniu z tym niewiele miejsca.
• CPU: każdy nowoczesny VPS typu KVM jest wystarczający, jednak przetwarzanie ML na procesorze jest powolne. Indeksowanie inteligentnego wyszukiwania przy dużym imporcie może działać w tle przez wiele godzin. Jest to zachowanie normalne i nie wymaga obecności GPU.
• Nazwa domeny skierowana na VPS. Aplikacja mobilna zdecydowanie preferuje punkt końcowy HTTPS, dlatego zaleca się umieszczenie przed nią reverse proxy. Jest to konfiguracja analogiczna do własnej instancji Nextcloud z Docker, TLS i kopiami zapasowymi; Immich jest odpowiednikiem tego serwera plików w kategorii zdjęć.
• Docker oraz wtyczka Compose zainstalowane; Docker Engine oraz wtyczka Compose v2 z oficjalnego repozytorium apt firmy Docker, zgodnie z opisem w naszym przewodniku po podstawach Docker Compose.

Krok 1: Dodanie przestrzeni wymiany (swap) przed wykonaniem innych czynności

Najczęstszą przyczyną awarii Immich na małych serwerach VPS jest zakończenie procesu kontenera ML przez mechanizm OOM-killer. Należy najpierw zapewnić systemowi operacyjnemu dodatkową przestrzeń operacyjną.

sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -h

Polecenie free -h powinno teraz wyświetlać linię Swap: o wartości 4.0Gi. Nie przyspieszy to działania modelu ML i stanowi jedynie bufor, a nie gwarancję wydajności, jednak znacząco zmniejsza prawdopodobieństwo nagłego przerwania pracy kontenera podczas indeksowania na maszynie z 4 GB pamięci RAM.

Krok 2: Pobranie oficjalnych plików compose oraz env, korzystanie z plików źródłowych zamiast kopii

Immich przypisuje wersje usług oraz, co kluczowe, obraz bazy danych wewnątrz plików, które udostępnia w ramach wydania. Nie należy wklejać pliku compose z blogów (w tym z tego) jako jedynego źródła prawdy. Należy pobrać zasoby wydania:

sudo mkdir -p /opt/immich && cd /opt/immich
sudo wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
sudo wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

Pochodzą one z otagowanego wydania, dzięki czemu odwołania do obrazów są zgodne. Plik compose definiuje cztery usługi; warto wiedzieć, za co odpowiada każda z nich, zanim wprowadzi się jakiekolwiek zmiany:

• immich-server (ghcr.io/immich-app/immich-server, kontener immich_server), API oraz interfejs webowy, nasłuchujący na porcie 2283. Montuje katalog z przesłanymi plikami w /data.
• immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, kontener immich_machine_learning), wyszukiwanie CLIP oraz rozpoznawanie twarzy. Przechowuje pobrane modele w wolumenie model-cache. Jest to usługa o największym zapotrzebowaniu na pamięć RAM.
• database (kontener immich_postgres), Postgres z rozszerzeniem wektorowym VectorChord, które obsługuje wyszukiwanie podobieństwa. Tag obrazu jest przypięty za pomocą skrótu (digest) bezpośrednio w pliku compose, na przykład ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:.... Starsze instalacje korzystały z pgvecto.rs; wsparcie dla niego zostało usunięte w Immich v3.0, więc każda obecnie instalowana wersja korzysta z VectorChord. Nigdy nie należy ręcznie edytować tego tagu.
• redis (kontener immich_redis), instancja Valkey/Redis służąca do obsługi kolejek zadań.

Krok 3: Konfiguracja .env, gdzie przechowywane są zdjęcia i baza danych

Otwórz .env i skonfiguruj cztery parametry. Wszystko poniżej oznaczonej linii pozostaje bez zmian.

# Where original uploads are stored on the host
UPLOAD_LOCATION=/opt/immich/library

# Where the Postgres data lives. NEVER put this on an NFS/network share.
DB_DATA_LOCATION=/opt/immich/postgres

# "v3" is a floating tag that tracks the latest v3.x. Pin a full tag like
# v3.0.2 instead; then you upgrade on purpose, not by surprise.
IMMICH_VERSION=v3.0.2

# Change this to a long random string. Letters and digits only.
DB_PASSWORD=REPLACE_WITH_A_LONG_RANDOM_STRING

# Set your timezone so timestamps and "on this day" line up
TZ=Europe/London

###################################################################################
DB_USERNAME=postgres
DB_DATABASE_NAME=immich

Dwie zasady, które pozwolą uniknąć problemów. UPLOAD_LOCATION powinno wskazywać na duży dysk. Jeśli planujesz podpiąć wolumen danych później, ustaw tę ścieżkę od razu na punkt montowania, ponieważ późniejsza zmiana wymaga przeniesienia miniatur i aktualizacji ścieżek do zasobów. Z kolei DB_DATA_LOCATION musi znajdować się na dysku lokalnym: Postgres na udziale NFS lub SMB ulega uszkodzeniu, co jest wyraźnie zaznaczone w dokumentacji. Używanie wyłącznie liter i cyfr w DB_PASSWORD pozwala uniknąć błędów związanych z ucieczką znaków w ciągu połączeniowym.

Krok 4: Pierwsze uruchomienie i utworzenie konta administratora

cd /opt/immich
sudo docker compose up -d
sudo docker compose ps

Poprawny wynik to cztery kontenery, wszystkie w stanie running, a docelowo healthy:

NAME                      STATUS
immich_machine_learning   Up (healthy)
immich_postgres           Up (healthy)
immich_redis              Up (healthy)
immich_server             Up (healthy)

Pierwsze polecenie up pobiera obrazy o rozmiarze kilku gigabajtów, więc proces ten wymaga czasu. Postęp można monitorować za pomocą sudo docker compose logs -f immich-server; serwer zarejestruje informację o nasłuchiwaniu na porcie 2283, gdy będzie gotowy. Teraz otwórz http://YOUR_SERVER_IP:2283 w przeglądarce. Pierwsza wizyta wyświetli kreator Getting Started, a pierwsze utworzone konto będzie kontem administratora. Ustaw silne hasło; to konto zarządza ustawieniami serwera, użytkownikami oraz konfiguracją ML, która będzie potrzebna w późniejszym czasie.

Krok 5: Aplikacja mobilna i kopia zapasowa w tle

Zainstaluj aplikację "Immich" ze sklepu App Store lub Play Store. Na ekranie logowania wymagane jest podanie adresu Server Endpoint URL. Wprowadź pełny adres URL wraz ze schematem, na przykład https://photos.example.com (aplikacja automatycznie doda /api). Zaloguj się na utworzone konto, a następnie otwórz ekran Backup w aplikacji. Wybierz albumy do zabezpieczenia (zazwyczaj Camera oraz Screenshots) i włącz opcję Background backup. Kopia zapasowa w tle na systemie iOS jest ograniczana przez system operacyjny; przesyłanie na pierwszym planie działa zawsze, natomiast operacje w tle odbywają się wtedy, gdy zezwoli na to system.

To jest etap, na którym użytkownicy najczęściej napotykają problemy, dlatego przed przystąpieniem do konfiguracji aplikacji należy zapoznać się z krokiem 6.

Krok 6: HTTPS przez reverse proxy i zasada pełnego adresu URL

Aplikacja mobilna wymaga protokołu HTTPS po opuszczeniu sieci domowej. Należy umieścić reverse proxy przed portem 2283 i tam zakończyć terminację TLS. Jeśli uruchomionych jest już kilka kontenerów, Traefik z automatycznym TLS dla wielu aplikacji Docker stanowi najbardziej uporządkowane rozwiązanie; jeden blok etykiet kieruje ruch photos.example.com do kontenera immich-server i automatycznie pobiera certyfikat. W przypadku wyboru nginx, przewodnik Let's Encrypt z Certbot i nginx pozwala uzyskać certyfikat oraz blok proxy_pass http://127.0.0.1:2283;. Gdy proxy jest już skonfigurowane, dodanie kolejnej usługi sprowadza się głównie do utworzenia nowej subdomeny. W ten sposób interfejs multimedialny, taki jak Halcyon, skórka wideo z lat 90. dla Jellyfin, może działać obok Immich na tym samym serwerze. To samo dotyczy własnego HarnessRouter udostępniającego Codex i Claude Code za jednym API, który domyślnie wiąże się z interfejsem loopback i staje się dostępny dopiero po terminacji TLS przez proxy. Przed przypisaniem do niego subdomeny należy zmienić domyślne dane logowania. Nie każdy kontener wymaga publicznej nazwy hosta: narzędzie administracyjne, takie jak własny skaner bezpieczeństwa open-kritt, powinno pozostać poza proxy i być dostępne przez tunel SSH w rzadkich przypadkach korzystania z interfejsu. Inne usługi pomijają proxy, ponieważ nie używają protokołu HTTP; własny serwer przekaźnikowy RustDesk jest tego najlepszym przykładem, gdyż nasłuchuje na kilku surowych portach TCP i UDP i wymaga reguł firewalla, a nie subdomeny. Jedno ustawienie proxy jest kluczowe dla Immich: należy zwiększyć limit rozmiaru przesyłanych plików, ponieważ filmy z telefonów są duże. W nginx odpowiada za to parametr client_max_body_size 50000M; w bloku server; domyślna wartość 1 MB powoduje odrzucenie przesyłanych plików wideo z błędem 413 Request Entity Too Large. Jeśli proxy obsługuje również wyzwania Let's Encrypt HTTP-01, należy upewnić się, że /.well-known/immich jest nadal kierowane do Immich, a nie do modułu obsługi wyzwań.

Zasada wymuszana przez aplikację: punkt końcowy musi być dostępny dokładnie pod wpisanym adresem URL. Aplikacja zaakceptuje zwykłe http://YOUR_SERVER_IP:2283 (podpowiedź logowania to http://your-server-ip:port), jednak każde połączenie przechodzące przez Internet powinno używać HTTPS. Błędny schemat lub bezpośredni adres IP z pominięciem portu są przyczynami komunikatu "aplikacja nie może połączyć się z serwerem", co opisano w sekcji błędów poniżej.

Krok 7: Biblioteki zewnętrzne a przesyłanie plików, importowanie istniejącej struktury zdjęć

Istnieją dwa sposoby dodawania zdjęć do Immich i nie są one tożsame.

• Przesyłanie (Uploads) to zasoby, których właścicielem jest Immich. Aplikacja lub narzędzie do przesyłania przez przeglądarkę kopiuje plik do UPLOAD_LOCATION. Immich może zmieniać ich nazwy, przenosić je oraz usuwać.
• Biblioteki zewnętrzne (External libraries) to importy plików w trybie tylko do odczytu, które znajdują się już w folderze na serwerze, starej strukturze Pictures lub zasobie sieciowym NAS. Immich indeksuje je w miejscu przechowywania i wyświetla na osi czasu, ale nigdy nie modyfikuje ani nie usuwa plików źródłowych.

Aby zaimportować istniejącą strukturę, należy zamontować ją w trybie tylko do odczytu w kontenerze serwera. Edytuj docker-compose.yml w sekcji immich-server: i dodaj wolumen:

  immich-server:
    volumes:
      - ${UPLOAD_LOCATION}:/data
      - /etc/localtime:/etc/localtime:ro
      - /srv/photos:/mnt/media/photos:ro

Flaga :ro gwarantuje, że Immich nigdy nie zmodyfikuje plików źródłowych. Odtwórz kontener za pomocą sudo docker compose up -d, a następnie w interfejsie WWW przejdź do swojego awatara → Administration → External Libraries → Create Library, wybierz właściciela, kliknij Add w sekcji Folders i wprowadź ścieżkę wewnątrz kontenera, /mnt/media/photos, a nie ścieżkę hosta /srv/photos. Kliknij Scan. Użycie ścieżki hosta zamiast ścieżki kontenera to najczęstszy błąd przy konfiguracji bibliotek zewnętrznych; skanowanie nie znajduje żadnych plików i raportuje zero zasobów.

Krok 8: Dyscyplina aktualizacji wymagana przez Immich

To etap, który odróżnia poprawnie działającą instancję Immich od uszkodzonej. Immich wydaje nowe wersje szybko, nie stosuje backportów poprawek i nie wspiera procedury downgrade. Pływający tag v3 jest oficjalnie wspieranym sposobem śledzenia wydań, a Immich dąży do ograniczania zmian powodujących niekompatybilność (breaking changes) do wydań głównych. Niemniej jednak, każda operacja pull wymusza aktualizację, niezależnie od tego, czy zapoznano się z informacjami o wydaniu, a nieplanowanej aktualizacji nie można cofnąć. Nawyk przypinania wersji, a następnie czytania informacji o wydaniu, warto stosować do każdego długo działającego kontenera na serwerze. Z tego powodu agent KiroCrew w środowisku self-hosted jest przypięty do konkretnego, sprawdzonego tagu, zamiast pozwalać na automatyczną zmianę wersji przy kolejnym restarcie. Zasady dyscypliny:

1. Przypnij wersję. Utrzymuj IMMICH_VERSION ustawione na konkretny tag, taki jak v3.0.2, a nie na pływający v3, który zawsze pobiera najnowszą wersję v3.x.
2. Zawsze czytaj informacje o wydaniu przed aktualizacją. Zmiany powodujące niekompatybilność, zwłaszcza w bazie danych lub rozszerzeniach wektorowych, są tam wyszczególnione. Wydanie v3.0 jest tego oczywistym przykładem: całkowicie usunięto pgvecto.rs, więc każdy użytkownik korzystający ze starego rozszerzenia musiał ukończyć migrację do VectorChord (wprowadzoną w v1.133) przed aktualizacją.
3. Najpierw wykonaj kopię zapasową bazy danych (Krok 9). Zawsze, a w szczególności, gdy informacje o wydaniu wspominają o bazie danych.
4. Pobierz również nowy plik compose. IMMICH_VERSION przypina tylko obrazy serwera i ML. Obraz Postgres jest przypięty za pomocą skrótu (digest) wewnątrz docker-compose.yml, dlatego wersja wymagająca nowszego rozszerzenia bazy danych dostarczana jest z nowym plikiem compose. Pobierz ponownie oba zasoby wydania, zastosuj ponownie swoje wartości .env, a następnie przeprowadź aktualizację.
5. Najpierw zaktualizuj klientów mobilnych. Serwer komunikuje się tylko z pasującą wersją główną, a aplikacja jest zazwyczaj kompatybilna z bieżącą i poprzednią wersją główną. Gdy serwer jest nowszy od aplikacji, bieżące wydania (v3.3.1, stan na 2026-10-10) wyświetlają powiadomienie App update is available z przyciskiem Update na telefonie. Immich zaleca aktualizację wszystkich klientów mobilnych przed serwerem.

Właściwe polecenia, po umieszczeniu nowych plików w odpowiednim miejscu:

cd /opt/immich
sudo docker compose pull
sudo docker compose up -d
sudo docker image prune

Krok 9: Kopie zapasowe, zrzut bazy danych ORAZ oryginały, a następnie test

Kopia zapasowa Immich składa się z dwóch elementów; jeden bez drugiego jest bezużyteczny. Baza danych przechowuje strukturę albumów, rozpoznane twarze, indeksy wyszukiwania oraz mapowanie zasobów na pliki. Katalog oryginałów zawiera właściwe zdjęcia. Przywrócenie tylko jednego z nich skutkuje albo zdjęciami bez żadnej organizacji, albo pustą powłoką wskazującą na nieistniejące pliki. Ta dwuczęściowa struktura nie jest specyfiką Immich: własna instancja systemu obsługi zgłoszeń Chatwoot wymaga identycznej pary, czyli zrzutu Postgres oraz katalogu przesłanych plików, w przeciwnym razie przywrócona skrzynka odbiorcza będzie pozbawiona wszystkich załączników. Kopiowanie katalogu danych Postgres jako drzewa plików wygląda na skrót, ale nie jest użyteczną kopią zapasową; to pułapka, którą pełny przewodnik po tworzeniu i przywracaniu kopii zapasowej Immich omawia wraz z błędem przywracania, który pozostawia użytkownika z pustą osią czasu.

Wykonaj zrzut bazy danych za pomocą pg_dump z wnętrza kontenera Postgres, konkretnie bazy immich, a nie całego klastra:

sudo docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres | gzip > /opt/immich/immich-db-$(date +%F).sql.gz

Następnie wykonaj kopię zapasową UPLOAD_LOCATION, całego drzewa /opt/immich/library, a w szczególności podkatalogów library/, upload/ oraz profile/, używając restic, rsync lub borg, przesyłając dane na inną maszynę lub do pamięci obiektowej. Niezależnie od tego, co uruchamia to zadanie – wpis w cron czy timer systemd – musi ono mieć możliwość powiadomienia o awarii. Jednostka OnFailure= systemu systemd skierowana na własny serwer powiadomień ntfy wyśle wiadomość na telefon w nocy, gdy zrzut się nie powiedzie, zamiast pozwalać na odkrycie tego dopiero podczas próby przywracania. Najpierw wykonaj kopię bazy danych, a następnie plików, aby zrzut nigdy nie odwoływał się do zdjęcia, którego kopia plików jeszcze nie skopiowała. Biblioteki zewnętrzne należy kopiować oddzielnie w ich źródłowej lokalizacji; Immich nie jest ich właścicielem.

Teraz część, którą wszyscy pomijają: przetestuj przywracanie. Przywracanie musi zostać wykonane na świeżym stosie, którego serwer nigdy nie był uruchamiany, na obrazie Postgres z rozszerzeniem wektorowym kompatybilnym ze zrzutem – dlatego nigdy nie należy improwizować z tagiem obrazu bazy danych. Na czystej maszynie z tym samym plikiem compose i .env, usuń wszelkie stare stany, uruchom tylko bazę danych, a następnie załaduj zrzut:

cd /opt/immich
sudo docker compose down -v
sudo docker compose pull
sudo docker compose create
sudo docker start immich_postgres
sleep 10
gunzip --stdout immich-db-2026-07-15.sql.gz |
  sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" |
  sudo docker exec -i immich_postgres psql --dbname=immich --username=postgres --single-transaction --set ON_ERROR_STOP=on
sudo docker compose up -d

Nadpisanie sed w search_path nie jest opcjonalne w przypadku bazy danych VectorChord; pominięcie tego kroku spowoduje przerwanie przywracania w trakcie. Gdy stos zostanie uruchomiony z umieszczonymi na miejscu oryginałami, otwórz interfejs WWW: jeśli zdjęcia i albumy są widoczne, kopia zapasowa działa. Jeśli nigdy tego nie przeprowadziłeś, nie masz kopii zapasowej – masz tylko nadzieję.

Tryby awaryjne i komunikaty błędów

Kontener ML zostaje zabity przez OOM-killer. sudo docker compose logs immich-machine-learning kończy się nagle, docker compose ps wskazuje na Restarting, a kod wyjścia to 137. sudo dmesg | grep -i oom potwierdza to poprzez: Out of memory: Killed process ... (python3). Zadania wyszukiwania i rozpoznawania twarzy zawieszają się. Przyczyną jest niewystarczająca ilość pamięci RAM dla modeli. Rozwiązania w kolejności: dodanie swap (Krok 1); zwiększenie pamięci RAM serwera VPS; lub, jeśli nie ma innej możliwości, przejście do Administration → Settings → Machine Learning Settings i wyłączenie głównego przełącznika uczenia maszynowego, co wyłącza wszystkie funkcje ML jednocześnie. Wyłączenie tylko Smart Search oraz Facial Recognition jest niewystarczające, ponieważ OCR i inne typy modeli pozostają domyślnie włączone. Kopie zapasowe i albumy zostają zachowane, tracona jest natomiast możliwość wyszukiwania po zawartości. Usunięcie usługi immich-machine-learning z pliku compose daje ten sam efekt.

Serwer Immich nie uruchamia się po aktualizacji. Kontener Postgres może działać poprawnie; to immich_server sprawdza wersję rozszerzenia wektorowego podczas startu i odmawia uruchomienia, a jego logi zapętlają się z linią typu The database currently has VectorChord 0.5.3 activated, but the Postgres instance only has 0.4.2 available. This most likely means the extension was downgraded. lub, w starszych wersjach, The pgvecto.rs extension is not available in this Postgres instance.. Przyczyną jest obraz bazy danych z wersją rozszerzenia starszą niż ta, do której zaktualizowano dane, co niemal zawsze wynika z ręcznej edycji tagu obrazu lub przywrócenia nowszego zrzutu na starszy obraz. Rozwiązaniem jest użycie pasującego obrazu Postgres, pobranie pliku compose z wersji odpowiadającej bazie danych, unikanie downgrade'u oraz przywracanie danych wyłącznie na kompatybilny obraz.

Aplikacja mobilna nie może połączyć się z serwerem. Ekran logowania wyświetla błąd połączenia, taki jak Could not connect to server po wprowadzeniu adresu URL. Typowe przyczyny: wpisano http://, podczas gdy proxy obsługuje tylko https://; nawiązano połączenie bezpośrednio z backendem, ale pominięto port, więc próbowano użyć example.com (port 443) zamiast example.com:2283; reverse proxy nie przekazuje /api; lub proxy obsługujące wyzwania Let's Encrypt HTTP-01 kieruje /.well-known/immich w inne miejsce niż Immich. Rozwiązaniem jest wprowadzenie pełnego adresu https://photos.example.com URL i sprawdzenie, czy ładuje się on w przeglądarce telefonu. Jeśli przeglądarka działa, a aplikacja nie, oznacza to, że proxy usuwa ścieżkę lub błędnie kieruje /.well-known/immich, albo certyfikat jest samopodpisany, co aplikacja odrzuca błędem handshake, chyba że w jej ustawieniach włączono obsługę certyfikatów samopodpisanych.

Brak miejsca na dysku w trakcie importu. Przesyłanie plików zaczyna kończyć się niepowodzeniem, miniatury stają się puste, a logi pokazują ENOSPC: no space left on device lub, w przypadku Postgres, could not extend file ... No space left on device. df -h pokazuje, że wolumen UPLOAD_LOCATION jest zapełniony w 100%. Dlatego należy określić rozmiar dysku przed importem dużej biblioteki. Odzyskiwanie polega na podłączeniu większego wolumenu, zatrzymaniu stosu, przeniesieniu UPLOAD_LOCATION na nowy dysk, aktualizacji .env i ponownym uruchomieniu, lub rozszerzeniu istniejącego dysku, jeśli dostawca na to pozwala. Postgres może ulec zablokowaniu po zapełnieniu miejsca, więc przed założeniem uszkodzenia danych należy zwolnić miejsce i zrestartować kontener bazy danych.

FAQ

Ile pamięci RAM i miejsca na dysku wymaga Immich?

Oficjalne wymagania Immich to minimum 6 GB pamięci RAM, przy czym zalecane jest 8 GB. W praktyce 4 GB z aktywnym swapem to absolutne minimum dla małej biblioteki. Niezależnie od ilości RAM, należy skonfigurować swap, ponieważ kontener uczenia maszynowego powoduje nagłe skoki zapotrzebowania na pamięć. W kwestii dysku należy zarezerwować miejsce równe rozmiarowi całej biblioteki plus około 10–20% na wygenerowane miniatury i podglądy. Należy używać pamięci lokalnej; nigdy nie umieszczaj katalogu danych Postgres na zasobie sieciowym. Jeśli nadal planujesz, co uruchomić, przewodnik po usługach do self-hostingu w 2026 przedstawia zapotrzebowanie Immich na tle innych usług.

Czy mogę uruchomić Immich bez GPU?

Tak. Kontener uczenia maszynowego działa poprawnie na procesorze (CPU). GPU jedynie przyspiesza indeksowanie inteligentnego wyszukiwania oraz, przy odpowiednim wariancie obrazu, transkodowanie wideo. Na samym CPU wstępne indeksowanie dużej biblioteki może zająć wiele godzin w tle, ale nie blokuje to tworzenia kopii zapasowych ani przeglądania zdjęć. Jeśli serwer jest zbyt słaby na obsługę ML, można całkowicie wyłączyć uczenie maszynowe za pomocą przełącznika w ustawieniach administratora, zachowując przy tym pełną funkcjonalność pozostałych elementów.

Jak bezpiecznie aktualizować Immich?

Przypnij IMMICH_VERSION do konkretnego tagu, takiego jak v3.0.2, przed każdą aktualizacją przeczytaj informacje o wydaniu (release notes) i wykonaj kopię zapasową bazy danych. Ponieważ obraz Postgres jest przypięty wewnątrz docker-compose.yml, a nie przez IMMICH_VERSION, pobierz ponownie zarówno plik compose, jak i example.env dla docelowej wersji, zastosuj ponownie swoje wartości, a następnie uruchom docker compose pull && docker compose up -d. Nigdy nie pozostawiaj wersji bez nadzoru; Immich nie wspiera procedury przywracania starszej wersji (downgrade), więc aktualizacja, z którą nie zapoznano się wcześniej, jest nieodwracalna.

Co dokładnie należy zabezpieczyć kopią zapasową?

Dwie rzeczy jednocześnie: pg_dump bazy danych immich oraz cały katalog UPLOAD_LOCATION z oryginalnymi plikami. Baza danych przechowuje informacje o albumach, twarzach oraz mapowanie zasobów na pliki; katalog zawiera właściwe zdjęcia. Przywrócenie danych wymaga obu tych elementów oraz obrazu bazy danych z kompatybilnym rozszerzeniem wektorowym. Najpierw wykonaj zrzut bazy danych, a następnie kopię plików. Przetestuj proces przywracania na osobnym środowisku przynajmniej raz; niesprawdzona kopia zapasowa nie jest kopią zapasową.

Jak zaimportować istniejący folder ze zdjęciami?

Zamontuj folder w trybie tylko do odczytu w kontenerze immich-server jako dodatkowy wolumen (na przykład - /srv/photos:/mnt/media/photos:ro), zrestartuj kontener, a następnie w Administration → External Libraries utwórz bibliotekę i dodaj ścieżkę kontenera /mnt/media/photos. Immich indeksuje pliki w ich bieżącej lokalizacji i nigdy ich nie modyfikuje ani nie usuwa. Najczęstszym błędem jest podanie ścieżki hosta zamiast ścieżki kontenera, co sprawia, że skanowanie nie znajduje żadnych plików.