Cara hos Immich dengan RAM 6 GB

Apa yang anda bina

Immich ialah perkhidmatan sandaran foto dan video hos-sendiri — pengganti sebenar kepada Google Photos. Ia mempunyai aplikasi telefon yang memuat naik galeri kamera anda di latar belakang, garis masa, album, pengecaman wajah, dan carian pembelajaran mesin yang boleh mencari "beach" atau seseorang tanpa perlu anda melabel apa-apa. Anda menjalankannya pada VPS milik sendiri, fail asal kekal pada cakera anda, dan tiada sesiapa yang mengimbas fail tersebut untuk menjual produk kepada anda.

Pemasangan ini melibatkan empat kontena daripada fail Docker Compose projek tersebut. Bahagian itu mengambil masa sepuluh minit. Bahagian lain dalam panduan ini adalah bahagian yang sukar: kontena pembelajaran mesin memerlukan memori yang tinggi pada peranti kecil, fail asal memakan ruang cakera dengan cepat, aplikasi mudah alih tidak menyokong pelayan HTTP biasa, dan Immich sering mengeluarkan perubahan yang memecahkan sistem sehingga docker compose pull yang cuai boleh menyebabkan pangkalan data anda gagal dimulakan. Tangani empat perkara ini dengan serius dan Immich akan menjadi sangat stabil. Abaikan perkara ini dan anda akan membazirkan masa hujung minggu anda.

Prasyarat, dan perkara penting yang perlu diperhatikan

• RAM: dokumen rasmi menyatakan minimum 6 GB dan disyorkan 8 GB — anggap 4 GB berserta swap sebagai had paling rendah. Kontena immich-server dan Postgres menggunakan sumber yang sedikit. Kontena immich-machine-learning menggunakan banyak sumber — ia memuatkan model CLIP dan pengecaman wajah ke dalam RAM untuk membina indeks carian, dan pada mesin 2 GB, kernel akan menghentikan proses tersebut. Tambah swap walaupun anda mempunyai 4 GB.
• Disk: sediakan saiz untuk keseluruhan perpustakaan anda, dan lebih sedikit. Fail asal disalin sepenuhnya, ditambah dengan Immich menjana imej thumbnail dan pratonton (kira-kira 10–20% tambahan). Koleksi foto 200 GB memerlukan volum 300 GB. Postgres adalah kecil jika dibandingkan.
• CPU: mana-mana KVM VPS moden adalah memadai, tetapi ML pada CPU adalah perlahan. Pengindeksan carian pintar bagi import yang besar boleh berjalan selama berjam-jam di latar belakang. Itu adalah normal; ia tidak memerlukan GPU.
• Nama domain yang dihalakan ke VPS. Aplikasi mudah alih sangat mengutamakan titik akhir HTTPS, dan anda memerlukan reverse proxy di hadapan. Ini adalah jenis tetapan yang sama dengan instans self-hosted Nextcloud dengan Docker, TLS dan sandaran — Immich adalah setara foto bagi pelayan fail tersebut.
• Docker dan plugin Compose telah dipasang — Docker Engine berserta plugin Compose v2 daripada repositori apt Docker sendiri, tepat seperti yang dibincangkan dalam panduan asas Docker Compose kami.

Langkah 1: Tambah swap sebelum perkara lain

Kegagalan Immich yang paling kerap berlaku pada VPS kecil adalah bekas (container) ML mati disebabkan OOM-killed. Berikan kernel ruang tambahan terlebih dahulu.

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 kini sepatutnya menunjukkan baris Swap: sebanyak 4.0Gi. Ini tidak akan mempercepatkan ML, tetapi ia menghalang bekas daripada mati semasa proses pengindeksan pada mesin 4 GB.

Langkah 2: Dapatkan compose dan env rasmi — gunakan fail mereka, bukan salinan

Immich menetapkan versi servis dan imej pangkalan data yang kritikal di dalam fail yang dibekalkan. Jangan gunakan fail compose daripada blog (termasuk blog ini) sebagai sumber rujukan utama. Muat turun aset rilis:

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

Fail ini berasal daripada rilis bertanda, jadi rujukan imej adalah sepadan. Fail compose mentakrifkan empat servis, dan adalah penting untuk mengetahui fungsi setiap satu sebelum anda melakukan sebarang perubahan:

• immich-server (ghcr.io/immich-app/immich-server, kontena immich_server) — API dan UI web, mendengar pada port 2283. Ia memuatkan muat naik anda pada /data.
• immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, kontena immich_machine_learning) — Carian CLIP dan pengecaman wajah. Ia menyimpan cache model yang dimuat turun dalam volum model-cache. Servis ini menggunakan banyak memori.
• database (kontena immich_postgres) — Postgres dengan sambungan vektor VectorChord, yang membolehkan carian persamaan. Tag imej ditetapkan melalui digest dalam fail compose, contohnya ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:.... Tetapan lama menggunakan pgvecto.rs; sokongan untuknya telah dibuang dalam Immich v3.0, jadi apa-apa yang anda pasang hari ini adalah VectorChord. Jangan sesekali mengubah tag ini secara manual.
• redis (kontena immich_redis) — instans Valkey/Redis untuk barisan kerja (job queues).

Langkah 3: Konfigurasi .env — lokasi foto dan pangkalan data anda

Buka .env dan tetapkan empat perkara. Semua perkara di bawah garisan bertanda tidak perlu diubah.

# 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

Dua peraturan untuk mengelakkan masalah. UPLOAD_LOCATION mesti merujuk kepada cakera besar anda — jika anda memasang volum data kemudian, tetapkan ini ke laluan mount tersebut dari awal, kerana memindahkannya kemudian akan memerlukan pemindahan thumbnail dan pengemaskinian laluan aset. Dan DB_DATA_LOCATION mestilah berada pada cakera tempatan: Postgres akan mengalami kerosakan jika berada pada perkongsian NFS atau SMB, seperti yang dinyatakan dalam dokumentasi. Jika anda hanya menggunakan huruf dan angka dalam DB_PASSWORD, anda dapat mengelakkan ralat escaping pada connection-string.

Langkah 4: Jalankan buat kali pertama dan cipta pengguna admin

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

Hasil yang betul ialah empat bekas, semuanya running dan akhirnya healthy:

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

up yang pertama akan memuat turun imej bersaiz beberapa gigabait, jadi tunggu sebentar. Pantau kemajuan dengan sudo docker compose logs -f immich-server; pelayan akan log bahawa ia sedang mendengar pada port 2283 setelah sedia. Sekarang buka http://YOUR_SERVER_IP:2283 dalam pelayar web. Lawatan pertama akan memaparkan wizard Getting Started — akaun pertama yang anda cipta adalah admin. Tetapkan kata laluan yang kuat; akaun ini mengawal tetapan pelayan, pengurusan pengguna dan konfigurasi ML yang anda perlukan kemudian.

Langkah 5: Aplikasi mudah alih dan sandaran latar belakang

Pasang "Immich" daripada App Store atau Play Store. Pada skrin log masuk, anda akan diminta untuk memasukkan Server Endpoint URL. Masukkan URL penuh termasuk skema, contohnya https://photos.example.com (aplikasi akan menambah /api secara automatik). Log masuk dengan akaun yang baru anda buat, kemudian buka skrin Backup pada aplikasi, pilih album yang ingin dilindungi (biasanya Camera dan Screenshots), dan aktifkan Background backup. Sandaran latar belakang pada iOS dihadkan oleh OS — muat naik semasa aplikasi dibuka (foreground) akan sentiasa berjalan, manakala muat naik latar belakang hanya berlaku apabila OS membenarkannya.

Ini adalah bahagian yang sering menyebabkan masalah, jadi baca Langkah 6 sebelum anda cuba membaiki aplikasi ini.

Langkah 6: HTTPS melalui reverse proxy — dan peraturan full-URL

Aplikasi mudah alih memerlukan HTTPS. Letakkan reverse proxy di hadapan port 2283 dan tamatkan TLS di sana. Jika anda sudah menjalankan beberapa container, Traefik dengan TLS automatik untuk pelbagai aplikasi Docker adalah pilihan yang paling kemas — satu blok label akan menghalakan photos.example.com ke container immich-server dan mengambil sijil untuk anda. Jika anda lebih suka nginx, panduan Let's Encrypt dengan Certbot dan nginx akan memberikan anda sijil dan blok proxy_pass http://127.0.0.1:2283;. Satu tetapan proxy adalah penting untuk Immich: naikkan had saiz muat naik, kerana video telefon adalah besar. Dalam nginx, ia adalah client_max_body_size 50000M; di dalam server block — nilai lalai 1 MB akan menolak muat naik video dengan 413 Request Entity Too Large.

Peraturan yang dikuatkuasakan oleh aplikasi: endpoint mesti boleh dicapai dan, secara praktikal, mesti menggunakan HTTPS. Endpoint http://, atau IP terus tanpa port, adalah punca ralat "the app cannot reach the server" — dibincangkan sebagai kegagalan khusus di bawah.

Langkah 7: Library luaran vs muat naik — mengimport struktur foto sedia ada

Terdapat dua cara foto dimasukkan ke dalam Immich, dan kedua-duanya adalah berbeza.

• Uploads adalah aset milik Immich. Aplikasi atau pemuat naik web menyalin fail ke dalam UPLOAD_LOCATION. Immich boleh menamakan semula, memindahkan, dan memadam fail tersebut.
• External libraries adalah import baca sahaja bagi fail yang sudah sedia ada dalam folder di pelayan anda — contohnya struktur Pictures lama atau eksport NAS. Immich mengindeks fail tersebut di lokasi asal dan memaparkannya dalam garis masa, tetapi tidak akan mengubah atau memadam fail asal tersebut.

Untuk mengimport struktur sedia ada, pasang (mount) folder tersebut sebagai baca sahaja ke dalam kontena pelayan. Edit docker-compose.yml di bawah immich-server: dan tambah satu volume:

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

:ro menjamin Immich tidak akan menyentuh fail asal. Bina semula kontena dengan sudo docker compose up -d, kemudian dalam UI web pergi ke avatar anda → Administration → External Libraries → Create Library, pilih pengguna pemilik, klik Add di bawah Folders, dan masukkan laluan kontena — /mnt/media/photos, bukan laluan hos /srv/photos. Klik Scan. Menggunakan laluan hos dan bukannya laluan kontena adalah kesilapan utama bagi library luaran; imbasan tidak akan menemui apa-apa dan melaporkan sifar aset.

Step 8: Disiplin naik taraf yang diperlukan oleh Immich

Ini adalah bahagian yang membezakan antara Immich yang berfungsi dengan baik atau yang rosak. Immich dikemas kini dengan pantas dan tidak menyediakan tampalan (backport) untuk versi lama atau menyokong penurunan versi (downgrade). Mengikuti tag v3 yang sentiasa berubah akan merosakkan pangkalan data anda. Disiplin yang perlu diikuti:

1. Tetapkan versi khusus. Pastikan IMMICH_VERSION ditetapkan pada tag konkrit seperti v3.0.2, bukan tag v3 yang sentiasa menarik versi v3.x yang terbaru.
2. Baca nota keluaran setiap kali sebelum melakukan naik taraf. Perubahan yang merosakkan sistem — terutamanya perubahan pangkalan data atau sambungan vektor — dinyatakan di sana. Versi v3.0 adalah contoh yang jelas: ia membuang pgvecto.rs sepenuhnya, jadi sesiapa yang masih menggunakan sambungan lama mesti menyelesaikan migrasi VectorChord (diperkenalkan dalam v1.133) sebelum boleh naik taraf.
3. Sandarkan (back up) pangkalan data terlebih dahulu (Langkah 9). Sentiasa lakukan ini, terutamanya jika nota menyebut tentang pangkalan data.
4. Muat turun fail compose yang baharu juga. IMMICH_VERSION hanya menetapkan imej server dan ML. Imej Postgres ditetapkan melalui digest di dalam docker-compose.yml, jadi versi yang memerlukan sambungan pangkalan data yang lebih baharu akan menyertakan fail compose yang baharu. Muat turun semula kedua-dua aset keluaran, tetapkan semula nilai .env anda, kemudian lakukan naik taraf.
5. Kemas kini klien mudah alih anda pada masa yang sama. Server hanya menyokong versi utama (major version) yang sepadan, manakala aplikasi menyokong versi utama semasa dan versi sebelumnya. Server yang sudah mendahului aplikasi akan memaparkan Your app major version is not compatible with the server! pada telefon sehingga anda mengemas kini aplikasi tersebut, jadi adalah lebih selamat untuk mengemas kini aplikasi terlebih dahulu.

Perintah sebenar, setelah fail baharu tersedia:

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

Step 9: Sandaran — dump pangkalan data DAN fail asal, serta uji ia

Sandaran Immich terdiri daripada dua perkara, dan salah satu daripadanya tidak berguna tanpa yang lain. Pangkalan data menyimpan struktur album, wajah, indeks carian dan peta daripada aset ke fail. Direktori originals menyimpan foto sebenar. Jika anda memulihkan salah satu tanpa yang lain, anda akan mendapat foto tanpa organisasi atau kerangka kosong yang merujuk kepada fail yang hilang.

Lakukan dump pangkalan data dengan pg_dump dari dalam kontena Postgres — pangkalan data immich secara khusus, bukan seluruh kluster:

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

Kemudian sandarkan UPLOAD_LOCATION — seluruh pokok /opt/immich/library, terutamanya subfolder library/, upload/ dan profile/ — dengan restic, rsync atau borg ke mesin lain atau storan objek. Lakukan sandaran pangkalan data dahulu dan fail kemudian, supaya dump tidak merujuk kepada foto yang belum disalin oleh sandaran fail. Perpustakaan luaran (external libraries) perlu disandarkan secara berasingan pada sumber asalnya; Immich tidak memilikinya.

Sekarang bahagian yang sering diabaikan: uji pemulihan. Pemulihan mesti dijalankan pada stack baharu yang pelayannya belum pernah dimulakan, pada imej Postgres yang sambungan vectornya serasi dengan dump — itulah sebabnya anda tidak boleh menggunakan tag imej DB secara rawak. Pada mesin kosong dengan compose dan .env yang sama, hapuskan sebarang keadaan lama, jalankan pangkalan data sahaja, kemudian muat pangkalan data dump:

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

Penulisan semula sed bagi search_path adalah wajib pada pangkalan data VectorChord — jika diabaikan, proses pemulihan akan terhenti di tengah jalan. Apabila stack kembali berfungsi dengan fail originals anda, buka UI web: jika foto dan album anda ada di sana, sandaran anda berfungsi. Jika anda tidak pernah menjalankan ujian ini, anda tidak mempunyai sandaran — anda hanya mempunyai harapan.

Mod kegagalan, dengan rentetan yang akan anda lihat

Kontena ML dihentikan oleh OOM-killer. sudo docker compose logs immich-machine-learning terhenti secara tiba-tiba, docker compose ps menunjukkan Restarting, dan kod keluar adalah 137. sudo dmesg | grep -i oom mengesahkannya: Out of memory: Killed process ... (python3). Tugasan carian dan wajah kemudian terhenti. Punca masalah adalah RAM tidak mencukupi untuk model. Langkah penyelesaian mengikut urutan: tambah swap (Langkah 1); berikan VPS lebih banyak RAM; atau, jika anda benar-benar tidak boleh, nyahaktifkan ML dalam Administration → Settings → Machine Learning Settings dengan mematikan Smart Search dan Facial Recognition — anda akan mengekalkan sandaran dan album, tetapi kehilangan fungsi carian-berdasarkan-kandungan. Membuang perkhidmatan immich-machine-learning daripada fail compose memberikan kesan yang sama.

Postgres enggan bermula selepas naik taraf. Log pelayan berulang dengan baris seperti 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. — atau, pada susunan lama, The pgvecto.rs extension is not available in this Postgres instance.. Puncanya adalah imej pangkalan data yang versi sambungannya lebih lama daripada versi data yang telah dinaik taraf, hampir selalunya disebabkan oleh penyuntingan tag imej secara manual atau memulihkan dump yang lebih baharu ke atas imej yang lebih lama. Cara penyelesaian adalah dengan menggunakan imej Postgres yang sepadan — ambil fail compose daripada versi yang sepadan dengan pangkalan data anda, jangan turun taraf, dan pulihkan hanya pada imej yang serasi.

Aplikasi mudah alih tidak dapat menghubungi pelayan. Skrin log masuk menunjukkan ralat sambungan / Server is not reachable selepas anda memasukkan URL. Terdapat tiga punca: anda menaip http:// sedangkan proksi hanya melayani https://; anda menyambung terus ke backend tetapi tidak memasukkan port, jadi ia cuba example.com (port 443) dan bukannya example.com:2283; atau reverse proxy tidak memanjangkan /api. Selesaikan dengan memasukkan URL https://photos.example.com yang lengkap dan pastikan ia boleh dimuatkan dalam pelayar telefon terlebih dahulu. Jika pelayar berfungsi tetapi aplikasi tidak, proksi tersebut membuang laluan (path) atau sijil tersebut adalah self-signed — aplikasi akan menolak sijil yang tidak dipercayai.

Disk penuh semasa proses import. Muat naik mula gagal, gambar kecil (thumbnails) menjadi kosong, dan log menunjukkan ENOSPC: no space left on device atau, daripada Postgres, could not extend file ... No space left on device. df -h menunjukkan volum UPLOAD_LOCATION pada 100%. Inilah sebabnya anda perlu menentukan saiz disk sebelum mengimport perpustakaan yang besar. Pulihkan dengan memasang volum yang lebih besar, menghentikan stack, memindahkan UPLOAD_LOCATION ke dalamnya, mengemas kini .env, dan bermula semula — atau luaskan disk sedia ada jika penyedia anda membenarkannya. Postgres boleh tersangkut jika disk penuh, jadi kosongkan ruang dan mulakan semula kontena pangkalan data sebelum menganggap berlaku kerosakan data.

FAQ

Berapakah RAM dan cakera yang diperlukan oleh Immich?

Keperluan rasmi Immich adalah minimum 6 GB RAM dan 8 GB yang disyorkan — 4 GB dengan swap adalah had praktikal untuk perpustakaan kecil. Konfigurasikan swap dalam apa jua keadaan kerana bekas (container) machine-learning akan menyebabkan lonjakan penggunaan. Untuk cakera, sediakan ruang sebanyak saiz penuh perpustakaan anda ditambah kira-kira 10–20% untuk thumbnail dan pratonton yang dijana pada storan tempatan — jangan sesekali letakkan direktori data Postgres pada perkongsian rangkaian. Jika anda masih belum pasti perkhidmatan lain yang ingin dijalankan, panduan tentang apa yang perlu dihoskan sendiri pada 2026 membandingkan penggunaan sumber Immich dengan perkhidmatan lain.

Bolehkah saya menjalankan Immich tanpa GPU?

Boleh. Bekas machine-learning boleh berjalan dengan lancar pada CPU — GPU hanya mempercepatkan pengindeksan smart-search dan transcoding video dengan varian imej yang betul. Pada CPU, pengindeksan awal untuk perpustakaan besar boleh mengambil masa berjam-jam di latar belakang, tetapi ia tidak menghalang proses sandaran atau pelayaran. Jika mesin anda terlalu kecil untuk ML, anda boleh menyahaktifkan Smart Search dan Facial Recognition dalam tetapan admin dan mengekalkan fungsi lain.

Bagaimanakah cara untuk menaik taraf Immich dengan selamat?

Tetapkan IMMICH_VERSION kepada tag khusus seperti v3.0.2, baca nota keluaran sebelum setiap naik taraf, dan buat sandaran pangkalan data terlebih dahulu. Oleh sebab imej Postgres ditetapkan di dalam docker-compose.yml dan bukannya melalui IMMICH_VERSION, muat turun semula fail compose dan example.env daripada versi sasaran anda dan tetapkan semula nilai anda, kemudian jalankan docker compose pull && docker compose up -d. Jangan biarkan versi berubah secara automatik — Immich menyertakan perubahan yang memecahkan sistem (breaking changes) dan tidak menyokong penurunan versi (downgrades).

Apakah yang perlu saya sandarkan (back up)?

Dua perkara secara bersama: pg_dump bagi pangkalan data immich dan keseluruhan direktori originals UPLOAD_LOCATION. Pangkalan data menyimpan album, wajah, dan pemetaan aset-ke-fail; direktori tersebut menyimpan foto sebenar, dan pemulihan memerlukan kedua-duanya serta imej pangkalan data dengan sambungan vektor yang serasi. Lakukan dump pangkalan data dahulu dan salinan fail kemudian, serta uji pemulihan pada mesin percubaan sekurang-kurangnya sekali — sandaran yang tidak diuji bukanlah sandaran yang sah.

Bagaimanakah cara untuk mengimport folder foto sedia ada saya?

Pasang (mount) folder tersebut sebagai volum tambahan yang bersifat baca-sahaja (read-only) ke dalam bekas immich-server (contohnya - /srv/photos:/mnt/media/photos:ro), bina semula bekas tersebut, kemudian dalam Administration → External Libraries, cipta satu perpustakaan dan tambah laluan bekas /mnt/media/photos. Immich mengindeks fail di lokasi asal dan tidak akan mengubah atau memadamnya. Kesilapan yang paling biasa ialah memasukkan laluan hos (host path) dan bukannya laluan bekas (container path), yang menyebabkan imbasan tidak menemui apa-apa.