Immich Kurulumu: 6 GB RAM ve Güvenli Güncelleme Rehberi

Ne inşa ediyorsunuz

Immich, Google Photos'un gerçek bir alternatifi olan, kendi kendine barındırılan bir fotoğraf ve video yedekleme servisidir. Kamera rulosunu arka planda yükleyen bir telefon uygulamasına, zaman çizelgesine, albümlere, yüz tanıma özelliğine ve siz hiçbir şeyi etiketlemeden "plaj" veya belirli bir kişiyi bulan makine öğrenimi tabanlı aramaya sahiptir. Servisi kendi sahip olduğunuz bir VPS üzerinde çalıştırırsınız; orijinal dosyalar diskinizde kalır ve hiç kimse size bir şeyler satmak için onları taramaz. Eğer hala diğer bariz aday ile kıyaslama yapıyorsanız, PhotoPrism ve Immich karşılaştırmamız her iki servisin RAM gereksinimlerini, telefon uygulamalarını ve yedekleme komutlarını yan yana getirir.

Kurulum, projenin kendi Docker Compose dosyasından gelen dört container'dan oluşur. Bu kısım on dakika sürer. Bu kılavuzun geri kalanı ise zorlukların yaşandığı yerdir: makine öğrenimi container'ı küçük bir sunucuda yüksek bellek tüketir, orijinal dosyalar diski hızla doldurur, mobil uygulama tam sunucu URL'sine ihtiyaç duyar ve ağınızın dışına çıkmadan önce önünde HTTPS olmasını istersiniz. Ayrıca Immich, dikkatsiz bir docker compose pull komutunun sunucunuzun başlatılamaz hale gelmesine neden olabileceği kadar sık köklü değişiklikler (breaking changes) yayınlar. Bu dört konuyu ciddiye alırsanız Immich son derece kararlı çalışır. Bunları görmezden gelirseniz bir hafta sonunuzu kaybedersiniz.

Ön koşullar ve dikkat edilmesi gerekenler

• RAM: Resmi belgeler minimum 6 GB ve önerilen 8 GB değerini belirtse de, 4 GB ve swap alanı mutlak alt sınır olarak kabul edilmelidir. immich-server ve Postgres container'ları mütevazı kaynak tüketir. immich-machine-learning container'ı ise en çok kaynak tüketen bileşendir; arama dizinlerini oluşturmak için CLIP ve yüz tanıma modellerini RAM'e yükler. 2 GB RAM'e sahip bir sunucuda çekirdek (kernel) bu süreci sonlandıracaktır. 4 GB RAM'iniz olsa dahi swap alanı ekleyin.
• Disk: Tüm kütüphanenizi ve üzerine ek bir payı kapsayacak şekilde boyutlandırın. Orijinal dosyalarınızın tamamı kopyalanır; ayrıca Immich küçük resimler ve önizleme görselleri oluşturur (toplam boyutun yaklaşık %10-20'si kadar). 200 GB'lık bir fotoğraf koleksiyonu için 300 GB'lık bir disk alanı gereklidir. Postgres, bu boyuta kıyasla oldukça küçüktür.
• CPU: Modern herhangi bir KVM VPS yeterlidir, ancak CPU üzerinde makine öğrenimi (ML) işlemleri yavaştır. Büyük bir içe aktarma işleminde akıllı arama dizinleme süreci arka planda saatlerce sürebilir. Bu normaldir; GPU kullanımı zorunlu değildir.
• VPS'e yönlendirilmiş bir alan adı. Mobil uygulama, HTTPS uç noktasını kesinlikle tercih eder ve ön tarafta bir reverse proxy kullanmanız gerekir. Bu kurulum, Docker, TLS ve yedekleme ile self-hosted Nextcloud kurulumu ile aynı yapıdadır; Immich, bu dosya sunucusunun fotoğraf tarafındaki karşılığıdır.
• Docker ve Compose eklentisi: Docker Engine ve Docker'ın kendi apt deposundan sağlanan Compose v2 eklentisi, Docker Compose temel rehberimizde anlatıldığı şekilde kurulmalıdır.

Adım 1: Her şeyden önce swap ekleyin

Küçük bir VPS üzerinde Immich'in en sık karşılaşılan başarısızlık nedeni, ML container'ının OOM-killed (bellek yetersizliği nedeniyle sonlandırılma) durumuna düşmesidir. Çekirdeğe nefes alacak bir alan sağlayın.

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

free -h komutu artık 4.0Gi boyutunda bir Swap: satırı göstermelidir. Bu işlem ML performansını artırmaz ve bir garanti değil, yalnızca bir tampon bellek görevi görür; ancak 4 GB belleğe sahip bir makinede container'ın indeksleme sırasında sonlanma olasılığını önemli ölçüde azaltır.

Adım 2: Resmi compose ve env dosyalarını alın, kopyalamak yerine orijinalini kullanın

Immich, servis sürümlerini ve kritik olarak veritabanı imajını, dağıttığı dosyaların içinde sabitler. Bir blogdan (bu blog dahil) kopyaladığınız bir compose dosyasını tek doğru kaynak olarak kabul etmeyin. Yayınlanan varlıkları indirin:

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

Bunlar etiketlenmiş sürümlerden geldiği için imaj referansları eşleşir. Compose dosyası dört servis tanımlar; herhangi bir değişiklik yapmadan önce her birinin ne olduğunu bilmek faydalıdır:

• immich-server (ghcr.io/immich-app/immich-server, container immich_server): API ve web arayüzü; 2283 numaralı portu dinler. Yüklemelerinizi /data dizinine bağlar.
• immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, container immich_machine_learning): CLIP arama ve yüz tanıma servisi. İndirilen modelleri bir model-cache volume alanında önbelleğe alır. Bellek tüketimi en yüksek olan servistir.
• database (container immich_postgres): Benzerlik aramasına güç veren VectorChord vektör eklentisine sahip Postgres. İmaj etiketi, compose dosyası içerisinde doğrudan digest ile sabitlenmiştir; örneğin ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:.... Eski kurulumlar pgvecto.rs kullanıyordu; bunun desteği Immich v3.0 ile kaldırıldı, bu nedenle bugün kurduğunuz her şey VectorChord kullanır. Bu etiketi asla manuel olarak düzenlemeyin.
• redis (container immich_redis): İş kuyrukları için bir Valkey/Redis örneği.

Adım 3: Fotoğraflarınızın ve veritabanınızın bulunduğu .env yapılandırması

.env dosyasını açın ve dört ayarı yapılandırın. İşaretli satırın altındaki her şey olduğu gibi kalmalıdır.

# 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

Sorun yaşamamanızı sağlayacak iki kural. UPLOAD_LOCATION, büyük disk alanınızı işaret etmelidir; eğer daha sonra bir veri birimi (data volume) bağlarsanız, bunu en baştan ilgili bağlama noktasına (mount path) ayarlayın. Çünkü bu işlemi sonradan yapmak, küçük resimlerin taşınmasını ve varlık yollarının güncellenmesini gerektirir. Ayrıca DB_DATA_LOCATION yerel disk üzerinde bulunmalıdır: NFS veya SMB paylaşımı üzerinde çalışan Postgres bozulmaya uğrar; belgelerde bu durum açıkça belirtilmiştir. DB_PASSWORD içerisinde yalnızca harf ve rakam kullanırsanız, bağlantı dizgisi kaçış karakterlerinden kaynaklanan bir hata sınıfını önlemiş olursunuz.

Adım 4: İlk çalıştırma ve yönetici kullanıcısının oluşturulması

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

Doğru bir sonuç, tamamı running durumunda olan ve nihayetinde healthy durumuna geçen dört adet container'dır:

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

İlk up işlemi birkaç gigabaytlık imajı çeker, bu nedenle tamamlanması için zaman tanıyın. İlerlemeyi sudo docker compose logs -f immich-server ile izleyin; sunucu hazır olduğunda 2283 portunu dinlediğine dair bir kayıt düşecektir. Şimdi tarayıcınızda http://YOUR_SERVER_IP:2283 adresini açın. İlk ziyarette bir Başlarken sihirbazı görüntülenecektir; oluşturacağınız ilk hesap yönetici hesabıdır. Güçlü bir parola belirleyin; bu hesap sunucu ayarlarının, kullanıcı yönetiminin ve daha sonra ihtiyaç duyacağınız ML yapılandırmasının sahibidir.

Adım 5: Mobil uygulama ve arka plan yedekleme

App Store veya Play Store üzerinden "Immich" uygulamasını yükleyin. Giriş ekranında sizden bir Server Endpoint URL istenecektir. Şema dahil tam URL'yi girin; örneğin https://photos.example.com (uygulama /api kısmını kendisi ekler). Az önce oluşturduğunuz hesapla giriş yapın, ardından uygulamanın Backup ekranını açın, yedeklenecek albümleri seçin (genellikle Camera ve Screenshots) ve Background backup seçeneğini etkinleştirin. iOS arka plan yedekleme işlemi işletim sistemi tarafından kısıtlanır; ön plan yüklemeleri her zaman çalışır, arka plan yüklemeleri ise işletim sistemi izin verdiğinde gerçekleşir.

Kullanıcıların en çok zorlandığı nokta burasıdır, bu yüzden uygulama ile uğraşmadan önce Adım 6'yı okuyun.

Adım 6: Bir reverse proxy üzerinden HTTPS ve tam URL kuralı

Mobil uygulama, ev ağınızın dışına çıktığında HTTPS bağlantısı gerektirir. 2283 portunun önüne bir reverse proxy yerleştirin ve TLS termination işlemini burada gerçekleştirin. Eğer halihazırda birden fazla container çalıştırıyorsanız, birden fazla Docker uygulaması için otomatik TLS ile Traefik en düzenli seçenektir; tek bir etiket bloğu photos.example.com trafiğini immich-server container'ına yönlendirir ve sizin için sertifikayı alır. Nginx tercih ederseniz, Certbot ve nginx ile Let's Encrypt kılavuzu size bir sertifika ve bir proxy_pass http://127.0.0.1:2283; bloğu sağlar. Bu proxy kurulduğunda, yeni bir servis eklemek genellikle sadece yeni bir alt alan adı tanımlamaktan ibarettir; Jellyfin için 90'lar video mağazası arayüzü olan Halcyon gibi bir medya arayüzü, aynı sunucuda Immich'in yanına bu şekilde yerleşir. Aynı durum, Codex ve Claude Code'u tek bir API arkasına alan self-hosted HarnessRouter için de geçerlidir; bu araç varsayılan olarak loopback üzerinde dinleme yapar ve ancak proxy önünde TLS'i sonlandırdığında erişilebilir hale gelir, bu nedenle bir alt alan adı tanımlamadan önce varsayılan giriş bilgilerini değiştirin. Ancak her container bir genel ana bilgisayar adını hak etmez: self-hosted open-kritt güvenlik tarayıcısı gibi yalnızca yöneticiye özel araçların proxy dışında tutulması ve arayüzüne ihtiyaç duyulduğunda SSH tüneli üzerinden erişilmesi daha güvenlidir. Bazı servisler ise HTTP dilini hiç kullanmadıkları için proxy'yi atlar; self-hosted RustDesk relay sunucusu bunun en net örneğidir, birkaç ham TCP ve UDP portu üzerinde dinleme yapar ve alt alan adından ziyade güvenlik duvarı kurallarına ihtiyaç duyar. Immich için bir proxy ayarı kritiktir: yükleme boyutu sınırını artırın, çünkü telefon videoları büyük boyutludur. Nginx'te bu ayar server bloğu içinde client_max_body_size 50000M; parametresidir; varsayılan 1 MB değeri, video yüklemelerini 413 Request Entity Too Large hatasıyla reddeder. Proxy'niz aynı zamanda Let's Encrypt HTTP-01 sınamalarına yanıt veriyorsa, /.well-known/immich yolunun sınama işleyicisine değil, Immich'e yönlendirildiğinden emin olun.

Uygulamanın uyguladığı kural şudur: uç nokta, tam olarak yazdığınız URL'de erişilebilir olmalıdır. Uygulama düz bir http://YOUR_SERVER_IP:2283 adresini kabul eder (kendi giriş ipucu http://your-server-ip:port şeklindedir), ancak internet üzerinden geçen her şey HTTPS olmalıdır. Yanlış şema veya portu belirtilmemiş doğrudan bir IP adresi kullanımı, aşağıda adlandırılmış bir hata olarak ele alınan "uygulama sunucuya ulaşamıyor" sorununun kaynağıdır.

Adım 7: Harici kütüphaneler ve yüklemeler, mevcut bir fotoğraf ağacını içe aktarma

Fotoğrafların Immich'e aktarılmasının iki yolu vardır ve bunlar aynı şey değildir.

• Yüklemeler, Immich'in sahipliğinde olan varlıklardır. Uygulama veya web yükleyicisi, dosyayı UPLOAD_LOCATION dizinine kopyalar. Immich bu dosyaları yeniden adlandırabilir, taşıyabilir ve silebilir.
• Harici kütüphaneler, sunucunuzda halihazırda bulunan bir klasörde, eski bir Pictures ağacında veya bir NAS dışa aktarımında yer alan dosyaların salt okunur şekilde içe aktarılmasıdır. Immich bunları yerinde indeksler ve zaman çizelgesinde gösterir, ancak orijinallerini asla değiştirmez veya silmez.

Mevcut bir ağacı içe aktarmak için, onu sunucu container'ına salt okunur olarak bağlayın (mount). immich-server: altındaki docker-compose.yml dosyasını düzenleyin ve bir volume ekleyin:

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

:ro ifadesi, Immich'in orijinallere asla dokunamayacağını garanti eder. Container'ı sudo docker compose up -d ile yeniden oluşturun, ardından web arayüzünde avatarınıza gidin → Administration → External Libraries → Create Library yolunu izleyin, sahip kullanıcıyı seçin, Folders altındaki Add butonuna tıklayın ve ana makine yolu olan /srv/photos yerine container yolu olan /mnt/media/photos değerini girin. Scan butonuna tıklayın. Ana makine yolunu container yolu yerine kullanmak, harici kütüphanelerle ilgili yapılan bir numaralı hatadır; tarama hiçbir şey bulamaz ve sıfır varlık rapor eder.

Adım 8: Immich'in gerektirdiği yükseltme disiplini

Bu bölüm, sorunsuz çalışan bir Immich kurulumu ile bozulan bir kurulum arasındaki farkı belirler. Immich hızlı sürümler yayınlar; düzeltmeleri eski sürümlere taşımaz (backport) ve sürüm düşürmeyi desteklemez. Değişken v3 etiketi, sürümleri takip etmek için resmi olarak desteklenen bir yöntemdir. Immich, köklü değişiklikleri ana sürümlere saklamayı hedefler; ancak siz pull komutunu çalıştırdığınız anda, sürüm notlarını okuyup okumadığınıza bakılmaksızın yükseltme gerçekleşir ve planlanmamış bir yükseltme geri alınamaz. Sürümü sabitleme ve ardından sürüm notlarını okuma alışkanlığı, sunucudaki tüm uzun ömürlü container'lar için uygulanmalıdır. KiroCrew agent'ının bir sonraki yeniden başlatmada kendiliğinden değişmesi yerine, bilinen iyi bir etikete sabitlenmesinin nedeni budur. Disiplin kuralları şunlardır:

1. Sürümü sabitleyin. IMMICH_VERSION değerini, her zaman en yeni v3.x sürümünü çeken değişken v3 etiketi yerine, v3.0.2 gibi somut bir etikete sabitleyin.
2. Yükseltme yapmadan önce her seferinde sürüm notlarını okuyun. Özellikle veritabanı veya vektör eklentisi değişiklikleri gibi köklü değişiklikler burada belirtilir. v3.0 sürümü buna net bir örnektir; pgvecto.rs eklentisini tamamen kaldırmıştır. Bu nedenle, eski eklentiyi kullanan herkesin, yükseltme yapmadan önce (v1.133 ile gelen) VectorChord geçişini tamamlaması gerekmiştir.
3. Önce veritabanını yedekleyin (Adım 9). Bu her zaman gereklidir, ancak sürüm notlarında veritabanından bahsediliyorsa iki kat daha önemlidir.
4. Yeni compose dosyasını da alın. IMMICH_VERSION yalnızca server ve ML imajlarını sabitler. Postgres imajı, docker-compose.yml içindeki bir özet (digest) ile sabitlenmiştir. Bu nedenle, daha yeni bir veritabanı eklentisine ihtiyaç duyan bir sürüm, yeni bir compose dosyası ile gelir. Her iki sürüm varlığını da yeniden indirin, .env değerlerinizi tekrar uygulayın ve ardından yükseltmeyi gerçekleştirin.
5. Önce mobil istemcilerinizi güncelleyin. Sunucu yalnızca kendi ana sürümüyle uyumlu çalışır; uygulama ise genellikle mevcut ve bir önceki ana sürümle uyumludur. Sunucu uygulamadan daha yeni olduğunda, güncel sürümler (v3.3.1, 2026-10-10 tarihinde kontrol edilmiştir) telefonda App update is available uyarısı ve bir Update butonu gösterir. Immich, sunucudan önce tüm mobil istemcilerin yükseltilmesini önerir.

Yeni dosyaları yerleştirdikten sonra çalıştırılacak komutlar şunlardır:

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

Adım 9: Yedeklemeler, veritabanı dökümü ARTI orijinaller ve test süreci

Immich yedeklemesi iki parçadan oluşur; biri olmadan diğeri işe yaramaz. Veritabanı albüm yapısını, yüzleri, arama dizinlerini ve varlık ile dosya arasındaki eşleşmeyi tutar. Orijinaller dizini ise fotoğrafların kendisini barındırır. Birini yedekleyip diğerini yedeklemezseniz, ya organizasyonu olmayan fotoğraflarınız ya da eksik dosyalara işaret eden boş bir kabuğunuz olur. Bu iki parçalı yapı sadece Immich'e özgü değildir: self-hosted bir Chatwoot destek masası da aynı şekilde bir Postgres dökümü ve uploads dizini eşleşmesine ihtiyaç duyar; aksi takdirde geri yüklenen gelen kutusundaki tüm ekler kaybolur. Postgres veri dizinini bir dosya ağacı olarak kopyalamak, döküm adımını atlamak için bir kısayol gibi görünse de kullanılabilir bir yedekleme değildir; bu, tam Immich yedekleme ve geri yükleme kılavuzunun boş bir zaman çizelgesiyle sonuçlanan geri yükleme hatalarının yanında ele aldığı bir tuzaktır.

Veritabanını, Postgres container'ı içerisinden pg_dump ile dökün; tüm kümeyi değil, özellikle immich veritabanını hedefleyin:

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

Ardından UPLOAD_LOCATION'i, tüm /opt/immich/library ağacını ve özellikle library/, upload/ ve profile/ alt klasörlerini restic, rsync veya borg kullanarak başka bir makineye ya da nesne depolama alanına yedekleyin. Bu işi zamanlayan her ne ise (bir cron girdisi veya systemd timer), başarısız olduğunda uyarı gönderebileceği bir yere ihtiyaç duyar. Kendi ntfy push sunucunuza yönlendirilmiş bir systemd OnFailure= birimi, döküm işlemi bozulduğunda bunu geri yükleme sırasında fark etmenizi beklemek yerine, o gece telefonunuza bir mesaj gönderir. Önce veritabanını, sonra dosyaları yedekleyin; böylece döküm, dosya yedeklemesinin henüz kopyalamadığı bir fotoğrafa referans vermez. Harici kütüphaneleri kendi gerçek kaynaklarında ayrı olarak yedekleyin; Immich bunların sahibi değildir.

Şimdi herkesin atladığı kısım: geri yüklemeyi test edin. Geri yükleme, sunucusu hiç başlatılmamış temiz bir yığın üzerinde ve vektör uzantısı döküm ile uyumlu bir Postgres imajı üzerinde çalışmalıdır; veritabanı imaj etiketini asla doğaçlama yapmamanızın nedeni tam olarak budur. Aynı compose ve .env dosyasına sahip boş bir makinede, eski durumları temizleyin, sadece veritabanını ayağa kaldırın ve ardından dökümü yükleyin:

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

search_path'un sed ile yeniden yazılması, VectorChord veritabanında isteğe bağlı değildir; bunu atlarsanız geri yükleme yarıda kesilir. Yığın, orijinalleriniz yerindeyken tekrar ayağa kalktığında web arayüzünü açın: fotoğraflarınız ve albümleriniz oradaysa yedeklemeniz çalışıyor demektir. Bunu hiç yapmadıysanız, bir yedeklemeniz yok, sadece bir umudunuz var demektir.

Hata modları ve karşılaşacağınız dizeler

ML container'ı OOM-killed durumuna düşüyor. sudo docker compose logs immich-machine-learning aniden sonlanır, docker compose ps bunu Restarting şeklinde gösterir ve çıkış kodu 137 olur. sudo dmesg | grep -i oom bunu Out of memory: Killed process ... (python3) ile doğrular. Arama ve yüz tanıma işleri bu noktada durur. Bunun nedeni, modeller için yetersiz RAM miktarıdır. Sırasıyla çözüm yolları: swap alanı ekleyin (Adım 1); VPS'e daha fazla RAM verin veya gerçekten mümkün değilse, Administration → Settings → Machine Learning Settings yolunu izleyerek en üstteki machine learning anahtarını kapatın; bu, tüm ML özelliklerini aynı anda devre dışı bırakır. Yalnızca Smart Search ve Facial Recognition özelliklerini kapatmak yeterli değildir, çünkü OCR ve diğer model türleri varsayılan olarak etkin kalmaya devam eder. Yedeklerinizi ve albümlerinizi korursunuz ancak içeriğe göre arama özelliğini kaybedersiniz. immich-machine-learning servisini compose dosyasından kaldırmak da aynı etkiyi yaratır.

Immich sunucusu yükseltme sonrası başlamayı reddediyor. Postgres container'ı düzgün çalışıyor olabilir; başlangıçta vektör uzantısı sürümünü kontrol eden ve başlamayı reddeden immich_server'tir. Günlük kaydı 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. gibi bir satırla döngüye girer veya eski yığınlarda The pgvecto.rs extension is not available in this Postgres instance. hatası verir. Bunun nedeni, verilerinizin yükseltildiği sürümden daha eski bir uzantı sürümüne sahip bir veritabanı imajıdır; bu durum neredeyse her zaman imaj etiketinin elle düzenlenmesinden veya daha yeni bir yedeğin daha eski bir imaja geri yüklenmesinden kaynaklanır. Çözüm, eşleşen Postgres imajını kullanmak, veritabanınızla uyumlu sürümün compose dosyasını kullanmak, sürüm düşürme yapmamak ve yalnızca uyumlu bir imaja geri yükleme yapmaktır.

Mobil uygulama sunucuya ulaşamıyor. URL'yi girdikten sonra giriş ekranında Could not connect to server gibi bir bağlantı hatası görünür. Yaygın nedenler şunlardır: proxy yalnızca https:// sunarken siz http:// yazdınız; doğrudan backend'e bağlandınız ancak portu belirtmeyi unuttunuz, bu yüzden example.com:2283 yerine example.com (port 443) denendi; reverse proxy /api trafiğini iletmiyor veya Let's Encrypt HTTP-01 sınamalarını yöneten bir proxy, /.well-known/immich trafiğini Immich dışındaki bir yere yönlendiriyor. Çözüm için tam https://photos.example.com URL'sini girin ve önce telefon tarayıcısında yüklendiğini doğrulayın. Tarayıcı çalışıyor ancak uygulama çalışmıyorsa, proxy yolu kırpıyor veya /.well-known/immich trafiğini yanlış yönlendiriyor olabilir ya da sertifika kendinden imzalıdır; uygulama, ayarlardan kendinden imzalı sertifika desteğini etkinleştirmediğiniz sürece bunu bir handshake hatası ile reddeder.

İçe aktarma sırasında disk doluyor. Yüklemeler başarısız olmaya başlar, küçük resimler boş görünür ve günlükler ENOSPC: no space left on device veya Postgres'ten could not extend file ... No space left on device hatasını gösterir. df -h, UPLOAD_LOCATION biriminin %100 dolu olduğunu gösterir. Büyük bir kütüphaneyi içe aktarmadan önce disk boyutunu planlamanızın nedeni budur. Kurtarma için daha büyük bir birim bağlayın, yığını durdurun, UPLOAD_LOCATION içeriğini buraya taşıyın, .env dosyasını güncelleyin ve yeniden başlatın ya da sağlayıcınız izin veriyorsa mevcut diski genişletin. Disk dolduğunda Postgres kilitlenebilir, bu nedenle bozulma olduğunu varsaymadan önce yer açın ve veritabanı container'ını yeniden başlatın.

FAQ

Immich ne kadar RAM ve disk alanına ihtiyaç duyar?

Immich'in resmi gereksinimleri minimum 6 GB RAM ve önerilen 8 GB'tır; küçük bir kütüphane için 4 GB ve swap alanı pratik alt sınırdır. Makine öğrenimi container'ı ani kaynak kullanımı yaptığı için her durumda swap yapılandırılmalıdır. Disk tarafında, tüm kütüphane boyutunuzun üzerine küçük resimler ve önizlemeler için yaklaşık %10-20 ek pay ayırın. Depolama yerel olmalıdır; Postgres veri dizinini asla ağ paylaşımı üzerinde tutmayın. Başka nelerin çalıştırılacağına henüz karar vermediyseniz, 2026 yılında self-host edilecekler rehberi, Immich'in kapladığı alanı diğer servislerle kıyaslamalı olarak sunar.

Immich'i GPU olmadan çalıştırabilir miyim?

Evet. Makine öğrenimi container'ı CPU üzerinde sorunsuz çalışır; GPU yalnızca akıllı arama indekslemeyi ve doğru imaj varyantı kullanıldığında video kod dönüştürme işlemini hızlandırır. CPU üzerinde, büyük bir kütüphanenin ilk indekslenmesi arka planda saatler sürebilir ancak bu durum yedeklemeleri veya gezinmeyi engellemez. Eğer sunucunuz makine öğrenimi için çok yetersizse, yönetici ayarlarındaki ana anahtarı kullanarak makine öğrenimini tamamen kapatabilir ve diğer tüm özellikleri kullanmaya devam edebilirsiniz.

Immich'i nasıl güvenli bir şekilde yükseltebilirim?

IMMICH_VERSION değerini v3.0.2 gibi somut bir etikete sabitleyin, her yükseltmeden önce sürüm notlarını okuyun ve önce veritabanını yedekleyin. Postgres imajı IMMICH_VERSION yerine docker-compose.yml içinde sabitlendiğinden, hem compose dosyasını hem de example.env dosyasını hedef sürümünüzden yeniden indirin, değerlerinizi tekrar uygulayın ve ardından docker compose pull && docker compose up -d komutunu çalıştırın. Sürümü asla kontrolsüz bir şekilde güncel tutmayın; Immich sürüm düşürmeyi desteklemez, bu nedenle hakkında bilgi sahibi olmadığınız bir yükseltme geri alınamaz.

Tam olarak neleri yedeklemeliyim?

Birlikte iki şey: immich veritabanının bir pg_dump yedeği ve tüm UPLOAD_LOCATION orijinaller dizini. Veritabanı albümleri, yüzleri ve varlık-dosya eşleştirmesini tutar; dizin ise fotoğrafların kendisini barındırır. Geri yükleme işlemi için her ikisi ve uyumlu bir vektör eklentisine sahip bir veritabanı imajı gerekir. Önce veritabanı dökümünü alın, ardından dosya kopyalamayı yapın ve geri yüklemeyi en az bir kez boş bir makinede test edin; test edilmemiş bir yedek, yedek sayılmaz.

Mevcut fotoğraf klasörümü nasıl içe aktarırım?

Klasörü salt okunur olarak immich-server container'ına ek bir volume (örneğin - /srv/photos:/mnt/media/photos:ro) şeklinde bağlayın, container'ı yeniden oluşturun ve ardından Administration → External Libraries kısmından bir kütüphane oluşturarak container yolu olan /mnt/media/photos değerini ekleyin. Immich dosyaları yerinde indeksler ve hiçbirini değiştirmez veya silmez. En yaygın hata, container yolu yerine host yolunu girmektir; bu durumda tarama işlemi hiçbir sonuç bulamaz.