SSD Nodes Learn
מדריכים Matt Connorמאת Matt Connor · עודכן 2026-07-24

המדריך לניהול Immich: זיכרון ועדכונים

מדריך להרצת Immich עם 6 GB RAM בלבד. נלמד על פורט 2283, שגיאת ה-exit 137 וסיבות לכך שגרסה v3 לא תעלה על pgvecto.rs, כולל שלבי שחזור מלאים.

מה אתם בונים

Immich הוא שירות גיבוי תמונות ווידאו המאוחסן באופן עצמאי (self-hosted) — תחליף אמיתי ל-Google Photos. יש לו אפליקציה לטלפון המעלה את ספריית התמונות שלכם ברקע, ציר זמן, אלבומים, זיהוי פנים וחיפוש מבוסס למידת מכונה (machine-learning) המאפשר למצוא "חוף" או אדם מסוים ללא צורך בתיוג ידני. אתם מריצים אותו על VPS בבעלותכם, הקבצים המקוריים נשארים בדיסק שלכם, ואף אחד לא סורק אותם כדי למכור לכם מוצרים.

ההתקנה מורכבת מארבעה containers מתוך קובץ ה-Docker Compose של הפרויקט. חלק זה לוקח עשר דקות. שאר המדריך עוסק בחלקים המורכבים: ה-container של למידת המכונה צורך הרבה זיכרון במחשב קטן, הקבצים המקוריים תופסים מקום בדיסק במהירות, האפליקציה לנייד לא מקבלת שרת HTTP רגיל, ו-Immich משחררת עדכונים ששוברים תכונות (breaking changes) בתדירות כזו ש-docker compose pull careless עלול להשאיר את מסד הנתונים שלכם במצב שאינו יכול לעלות. התייחסו לארבעת הדברים הללו ברצינות ו-Immich תהיה יציבה מאוד. התעלמו מהם ותפסידו סוף שבוע שלם.

דרישות קדם, ובעיות נפוצות

  • RAM: התיעוד הרשמי מציין 6 GB לפחות ו-8 GB מומלץ — התייחסו ל-4 GB בתוספת swap כמינימום המוחלט. הקונטיינרים של immich-server ו-Postgres צורכים משאבים מועטים. הקונטיינר של immich-machine-learning הוא הצרכן העיקרי — הוא טוען מודלים של CLIP וזיהוי פנים לתוך ה-RAM כדי לבנות אינדקסים לחיפוש, ובמכונה עם 2 GB ה-kernel יסגור אותו. הוסיפו swap גם אם יש לכם 4 GB.
  • Disk: הקצו נפח עבור הספרייה המלאה שלכם, ועוד קצת. הקבצים המקוריים מועתקים במלואם, בנוסף Immich מייצר תמונות ממוצלות (thumbnails) ותמונות תצוגה מקדימה (בערך 10–20% נוספים). אוסף תמונות של 200 GB דורש נפח של 300 GB. Postgres קטן יחסית.
  • CPU: כל KVM VPS מודרני יתאים, אך ML על ה-CPU איטי. אינדוקס Smart-search של ייבוא גדול יכול להימשך שעות ברקע. זה תקין; אין צורך ב-GPU.
  • שם דומיין המופנה אל ה-VPS. האפליקציה בנייד מעדיפה endpoint מסוג HTTPS, וכדאי להשתמש ב-reverse proxy לפני. זוהי הגדרה דומה ל- self-hosted Nextcloud instance with Docker, TLS and backups — Immich הוא המקביל לתמונות עבור שרת הקבצים הזה.
  • Docker ו-Compose plugin מותקנים — Docker Engine בתוספת ה-Compose v2 plugin מהמאגר הרשמי של Docker (apt repository), בדיוק כפי שמוסבר ב- our Docker Compose basics guide.

Step 1: הוספת swap לפני כל פעולה אחרת

הסיבה הנפוצה ביותר לכשל ב-Immich ב-VPS קטן היא קריסת ה-ML container עקב OOM-kill. יש להקצות ל-kernel שטח עבודה נוסף.

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 אמור להציג שורת Swap: של 4.0Gi. פעולה זו לא תאיץ את ה-ML, אך היא תמנע מה-container לקרוס במהלך תהליך ה-index במכונות עם 4 GB זיקרון.

Step 2: הורד את קובצי ה-compose וה-env הרשמיים — השתמש בהם, לא בעותק

Immich מגדירה גרסאות שירות וגרסת database ספציפיות בתוך הקבצים שהיא מספקת. אל תשתמש בקובץ compose מבלוג (כולל בלוג זה) כמקור המהימן. הורד את קובצי ה-release:

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

קבצים אלו מגיעים מה-release המוגדר (tagged), ולכן הפניות ל-images תואמות. קובץ ה-compose מגדיר ארבעה שירותים, וכדאי להכיר כל אחד מהם לפני שמתחילים:

  • immich-server (ghcr.io/immich-app/immich-server, container immich_server) — ה-API וה-web UI, המאזינים בפורט 2283. הוא מבצע mount לתיקיית ה-uploads שלך ב-/data.
  • immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, container immich_machine_learning) — CLIP search וזיהוי פנים. המודלים שהורדו נשמרים ב-cache בתוך volume מסוג model-cache. שירות זה צורך זיכרון רב.
  • database (container immich_postgres) — Postgres עם תוסף ה-VectorChord לחיפוש וקטורי. ה-image tag מוגדר באמצעות digest בתוך קובץ ה-compose, לדוגמה ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:.... הגדרות ישנות השתמשו ב-pgvecto.rs; התמיכה בה הוסרה ב-Immich v3.0, לכן כל התקנה כיום תשתמש ב-VectorChord. לעולם אל תערוך ידנית את ה-tag הזה.
  • redis (container immich_redis) — מופע Valkey/Redis עבור תורי עבודה (job queues).

Step 3: Configure .env — where your photos and database live

Open .env and set four things. Everything below the marked line stays as-is.

# 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

Two rules to prevent issues. UPLOAD_LOCATION should point to your large disk — if you attach a data volume later, set this to its mount path from the start. moving it later requires moving thumbnails and updating asset paths. DB_DATA_LOCATION must be on a local disk: Postgres on an NFS or SMB share causes corruption, as stated in the documentation. If you use only letters and digits in DB_PASSWORD, you avoid a class of connection-string escaping bugs.

Step 4: הרצה ראשונה ויצירת משתמש ה-admin

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

תוצאה תקינה תכלול ארבעה containers, כולם במצב running ובסופו של דבר במצב healthy:

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

ה-up הראשון מוריד מספר gigabytes של images, לכן יש להמתין. ניתן לעקוב אחר ההתקדמות באמצעות sudo docker compose logs -f immich-server; השרת ידווח ב-logs שהוא מאזין ב-port 2283 ברגע שיהיה מוכן. כעת פתחו את http://YOUR_SERVER_IP:2283 בדפדפן. הביקור הראשון יציג אשריש (wizard) של Getting Started — החשבון הראשון שתצרו יהיה ה-admin. הגדירו סיסמה חזקה; חשבון זה מחזיק את הגדרות השרת, ניהול המשתמשים והגדרות ה-ML שיידרשו בהמשך.

Step 5: האפליקציה לנייד והגיבוי ברקע

התקינו את "Immich" מ-App Store או מ-Play Store. במסך ההתחברות תתבקשו להזין Server Endpoint URL. הזינו את ה-URL המלא כולל ה-scheme, לדוגמה https://photos.example.com (האפליקציה תוסיף את /api באופן אוטומטי). התחברו עם החשבון שיצרתם הרגע, לאחר מכן פתחו את מסך ה-Backup באפליקציה, בחרו את האלבומים שברצונכם לגבות (בדרך כלל Camera ו-Screenshots), והפעילו את Background backup. ב-iOS, הגיבוי ברקע מוגבל על ידי מערכת ההפעלה — העלאות בזמן שהאפליקציה פתוחה (foreground) מתבצעות תמיד, בעוד העלאות ברקע מתבצעות רק כאשר מערכת ההפעלה מאפשרת זאת.

זהו בדיוק השלב שבו משתמשים נתקלים בקשיים, לכן מומלץ לקרוא את Step 6 לפני שתנסו לפתור בעיות באפליקציה.

Step 6: HTTPS via a reverse proxy — and the full-URL rule

האפליקציה בנייד מחייבת שימוש ב-HTTPS. יש להציב reverse proxy לפני פורט 2283 ולבצע שם TLS termination. אם אתם מריצים כבר מספר containers, האפשרות המסודרת ביותר היא Traefik with automatic TLS for multiple Docker apps — בלוק label אחד מפנה את photos.example.com ל-container של immich-server ומשיג עבורכם את התעודה. אם אתם מעדיפים nginx, המדריך Let's Encrypt with Certbot and nginx יספק לכם תעודה ובלוק proxy_pass http://127.0.0.1:2283;. הגדרה אחת ב-proxy קריטית עבור Immich: יש להגדיל את מגבלת גודל ההעלאה (upload size limit), מכיוון שסרטוני וידאו מהטלפון הם גדולים. ב-nginx ההגדרה היא client_max_body_size 50000M; בתוך ה-server block — ברירת המחדל היא 1 MB, מה שגורם לדחיית העלאות וידאו עם שגיאת 413 Request Entity Too Large.

הכלל שהאפליקציה מחויבת לו: ה-endpoint חייב להיות נגיש, ובפועל, חייב להיות HTTPS. שימוש ב-http:// endpoints, או בכתובת IP ישירה ללא הפורט, הם הסיבות לשגיאת "the app cannot reach the server" — נושא זה מפורט תחת כותרת שגיאה ייעודית להלן.

Step 7: External libraries vs uploads — importing an existing photo tree

קיימות שתי דרכים שבהן תמונות מתווספות ל-Immich, והן אינן זהות.

  • Uploads הם קבצים ש-Immich מחזיקה בבעלותה. האפליקציה או ממשק ה-web מעתיקים את הקובץ אל UPLOAD_LOCATION. Immich יכולה לשנות את שמות הקבצים, להזיז אותם ולמחוק אותם.
  • External libraries הם ייבואים במצב Read-only של קבצים שכבר נמצאים בתיקייה על השרת — עץ תמונות Pictures ישן, או ייצוא מ-NAS. Immich מאנדקסת אותם במקומם ומציגה אותם ב-timeline, אך היא לעולם לא תשנה או תמחק את המקור.

כדי לייבא עץ תמונות קיים, יש לעשות לו Mount במצב Read-only לתוך ה-container של השרת. ערוך את docker-compose.yml תחת immich-server: והוסף volume:

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

ה-:ro מבטיח ש-Immich לעולם לא תוכל לגעת בקבצים המקוריים. צור מחדש את ה-container באמצעות sudo docker compose up -d, ולאחר מכן בממשק ה-web עבור אל ה-avatar שלך ← Administration → External Libraries → Create Library, בחר את המשתמש הבעלים, לחץ על Add תחת Folders, והזן את הנתיב של ה-container — /mnt/media/photos, ולא את נתיב ה-host ‏/srv/photos. לחץ על Scan. שימוש בנתיב ה-host במקום בנתיב ה-container הוא הטעות הנפוצה ביותר בשימוש ב-external-library; הסריקה לא תמצא דבר ותדווח על אפס assets.

Step 8: משמעת השדרוג ש-Immich מחייבת

זהו החלק שמבדיל בין התקנת Immich תקינה להתקנה שבורה. Immich משחררת גרסאות במהירות ואינה מעבירה תיקונים לגרסאות ישנות (backport) או תומכת בשחזור גרסה אחורה (downgrade). מעקב עיוור אחר התגית הדינמית v3 יגרום בסופו של דבר לשגיאה במסד הנתונים. משמעת העבודה היא:

  1. קבע גרסה קבועה (Pin a version). השאר את IMMICH_VERSION מוגדר לתגית ספציפית כמו v3.0.2, ולא ל-v3 הדינמית שתמיד מושכת את הגרסה החדשה ביותר של v3.x.
  2. קרא את הערות השחרור (release notes) בכל פעם מחדש לפני השדרוג. שינויים שוברים — במיוחד שינויים במסד הנתונים או ב-vector-extension — מצוינים שם. גרסת v3.0 היא דוגמה מובהקת: היא הסירה לחלוטין את pgvecto.rs, לכן כל מי שהשתמש בתוסף הישן היה חייב להשלים את המעבר ל-VectorChord (שהוכנס בגרסה v1.133) לפני שיוכל לשדרג.
  3. גבה את מסד הנתונים תחילה (Step 9). תמיד, ובמיוחד כאשר הערות השחרור מציינות את מסד הנתונים.
  4. הורד גם את קובץ ה-compose החדש. IMMICH_VERSION מקבע רק את ה-images של ה-server וה-ML. ה-image של Postgres מקובע באמצעות digest בתוך docker-compose.yml, לכן גרסה שדורשת תוסף מסד נתונים חדש יותר משחררת קובץ compose חדש. הורד מחדש את שני קבצי השחרור, החל את ערכי ה-.env שלך, ולאחר מכן שדרג.
  5. עדכן את אפליקציות המובייל בסביבות הזמן שבהן שדרגת את השרת. השרת תומך רק בגרסה הראשית (major version) התואמת לו, והאפליקציה תומכת בגרסה הראשית הנוכחית ובגרסה הראשית הקודמת. שרת שקדם בגרסה לאפליקציה יציג שגיאת Your app major version is not compatible with the server! בטלפון עד שתעדכן את האפליקציה, לכן הבחירה הבטוחה ביותר היא לעדכן את האפליקציה תחילה.

הפקודות בפועל, לאחר שהקבצים החדשים נמצאים במקום:

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

Step 9: גיבויים — dump של מסד הנתונים בתוספת הקבצים המקוריים, ובדיקתם

גיבוי של Immich מורכב משני מרכיבים, ואחד מהם ללא השני אינו מועיל. ה-database מכיל את מבנה האלבומים, זיהוי פנים, אינדקסים לחיפוש והמיפוי בין הנכס (asset) לקובץ. ה-originals directory מכיל את התמונות עצמן. שחזור של אחד ללא השני יניב או תמונות ללא ארגון, או מעטפת ריקה המפנה לקבצים חסרים.

בצע dump למסד הנתונים באמצעות pg_dump מתוך ה-Postgres container — ספציפית את מסד הנתונים immich, ולא את כל ה-cluster:

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

לאחר מכן גבה את UPLOAD_LOCATION — את כל עץ ה-/opt/immich/library, ובמיוחד את תתי-התיקיות library/, upload/ ו-profile/ — באמצעות restic, rsync או borg למכונה אחרת או ל-object storage. בצע את גיבוי מסד הנתונים תחילה ואת הקבצים לאחר מכן, כדי שה-dump לא יפנה לתמונה שגיבוי הקבצים טרם העתיק. ספריות חיצוניות (External libraries) יש לגבות בנפרד במקורן האמיתי; Immich אינה מחזיקה בבעלות עליהן.

כעת החלק שכולם מדלגים עליו: בדוק את השחזור. שחזור חייב להתבצע מול stack חדש ששרתו מעולם לא הופעל, על image של Postgres שבו ה-vector extension תואם ל-dump — זו בדיוק הסיבה שאסור להשתמש ב-DB image tag שאינו מוגדר מראש. על מכונה נקייה עם אותו compose ו-.env, מחק כל מצב ישן, הפעל רק את ה-database, ולאחר מכן טען את ה-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

ה-sed של search_path אינו אופציונלי במסד נתונים VectorChord — אם תחסכו בו, השחזור ייעצר באמצע. לאחר שה-stack יעלה עם ה-originals במקומם, פתחו את ה-web UI: אם התמונות והאלבומים מופיעים שם, הגיבוי שלכם תקין. אם מעולם לא הרצת תהליך זה, אין לכם גיבוי — יש לכם תקווה בלבד.

Failure modes, with the strings you will see

The ML container is OOM-killed. sudo docker compose logs immich-machine-learning ends abruptly, docker compose ps shows it Restarting, and the exit code is 137. sudo dmesg | grep -i oom confirms it: Out of memory: Killed process ... (python3). Search and face jobs then stall. The cause is too little RAM for the models. Fixes, in order: add swap (Step 1); give the VPS more RAM; or, if you genuinely cannot, disable ML in Administration → Settings → Machine Learning Settings by turning off Smart Search and Facial Recognition — you keep backups and albums, you lose search-by-content. Removing the immich-machine-learning service from the compose file has the same effect.

Postgres refuses to start after an upgrade. The server log loops with a line like 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. — or, on older stacks, The pgvecto.rs extension is not available in this Postgres instance.. The cause is a database image whose extension version is older than what your data was upgraded to, almost always from editing the image tag by hand or restoring a newer dump onto an older image. The fix is to use the Postgres image that matches — take the compose file from the release that matches your database, do not downgrade, and restore only onto a compatible image.

The mobile app cannot reach the server. The login screen shows a connection error / Server is not reachable after you enter the URL. Three causes: you typed http:// where the proxy only serves https://; you connected straight to the backend but left the port off, so it tried example.com (port 443) instead of example.com:2283; or the reverse proxy is not forwarding /api. Fix by entering the full https://photos.example.com URL and confirming it loads in a phone browser first. If the browser works and the app does not, the proxy is stripping the path or the certificate is self-signed — the app rejects untrusted certs.

Out of disk mid-import. Uploads start failing, thumbnails go blank, and logs show ENOSPC: no space left on device or, from Postgres, could not extend file ... No space left on device. df -h shows the UPLOAD_LOCATION volume at 100%. This is why you size disk before importing a big library. Recover by attaching a larger volume, stopping the stack, moving UPLOAD_LOCATION to it, updating .env, and starting again — or expand the existing disk if your provider allows it. Postgres can wedge if it fills up, so clear space and restart the database container before assuming corruption.

FAQ

כמה RAM ושטח דיסק Immich דורש?

הדרישות הרשמיות של Immich הן 6 GB RAM לפחות ו-8 GB מומלץ — 4 GB עם swap הם המינימום המעשי עבור ספרייה קטנה. יש להגדיר swap בכל מקרה, מכיוון שקונטיינר ה-machine-learning הוא החלק שצורך משאבים רבים. עבור דיסק, יש לתכנן שטח עבור כל גודל הספרייה בתוספת כ-10–20% עבור תמונות ממוזערות (thumbnails) ותצ previews, על אחסון מקומי — לעולם אין להציב את ספריית הנתונים של Postgres על שיתוף רשת. אם אתם עדיין מחליטים אילו שירותים נוספים להריץ, ה-מדריך למה לארח בעצמכם ב-2026 מציג את צריכת המשאבים של Immich לצד שירותים אחרים.

האם ניתן להריץ Immich ללא GPU?

כן. קונטיינר ה-machine-learning פועל היטב גם על CPU — GPU רק מאיץ את אינדוקס ה-smart-search ואת ה-video transcoding (עם גרסת תמונה מתאימה). על CPU, האינדוקס הראשוני של ספרייה גדולה עשוי להימשך שעות ברקע, אך הוא אינו חוסם גיבויים או גלישה. אם המחשב שלכם חלש מדי עבור ML, ניתן לבטל את ה-Smart Search ואת ה-Facial Recognition בהגדרות המנהל (admin settings) ולהשאיר את שאר השירותים פעילים.

איך משדרגים Immich בצורה בטוחה?

קבעו את IMMICH_VERSION לתג (tag) ספציפי כמו v3.0.2, קראו את ה-release notes לפני כל שדרוג, וגבו את מסד הנתונים תחילה. מכיוון שאימג' ה-Postgres מקובע בתוך docker-compose.yml ולא באמצעות IMMICH_VERSION, יש להוריד מחדש גם את קובץ ה-compose וגם את example.env מהגרסה הרצויה, להחיל מחדש את הערכים שלכם, ואז להריץ את docker compose pull && docker compose up -d. לעולם אל תתנו לגרסה להשתנות ללא פיקוח — Immich כוללת שינויים שוברים (breaking changes) ואינה תומכת בביצוע downgrade.

מה בדיוק צריך לגבות?

שני דברים, יחד: pg_dump של מסד הנתונים immich והתיקייה המלאה UPLOAD_LOCATION. מסד הנתונים מכיל אלבומים, פנים ומיפוי של קבצים; התיקייה מכילה את התמונות עצמן. שחזור דורש את שניהם, בתוספת אימג' של מסד הנתונים עם תוסף vector תואם. בצעו את ה-database dump תחילה ואת העתקת הקבצים לאחר מכן, ובדקו את השחזור על מכונה זמנית לפחות פעם אחת — גיבוי שלא נבדק אינו גיבוי.

איך מייבאים תיקיית תמונות קיימת?

Mount לתיקייה במצב read-only לתוך הקונטיינר immich-server כ-volume נוסף (למשל - /srv/photos:/mnt/media/photos:ro), צרו מחדש את הקונטיינר, ולאחר מכן ב-Administration → External Libraries צרו ספרייה והוסיפו את נתיב ה-container ‏/mnt/media/photos. Immich מאנדקסת את הקבצים במקומם לעולם אינה משנה או מוחקת אותם. הטעות הנפוצה ביותר היא הזנת נתיב ה-host במקום נתיב ה-container, מה שגורם לסריקה לא למצוא דבר.

#immich#photos#docker#self-hosting#backups