SSD Nodes Learn
راهنماها Matt Connorتوسط Matt Connor · به‌روزرسانی شده 2026-07-24

راهنمای نصب و مدیریت Immich self-hosted

نکات حیاتی برای Immich: مدیریت مصرف 6 GB RAM، تنظیم port 2283 با HTTPS و رفع خطای exit 137. همچنین راهکار ارتقای ایمن و رفع مشکل pgvecto.rs در نسخه v3.

آنچه در حال ساخت آن هستید

Immich یک سرویس پشتیبان‌گیری از عکس و ویدیو با قابلیت Self-hosted است؛ جایگزینی واقعی برای Google Photos. این سرویس دارای یک اپلیکیشن موبایل است که از ردیف تصاویر دوربین شما در پس‌زمینه پشتیبان‌گیری می‌کند. همچنین شامل قابلیت‌هایی مانند Timeline، آلبوم‌ها، تشخیص چهره و جستجوی مبتنی بر Machine-learning است که بدون نیاز به برچسب‌گذاری دستی، مواردی مانند "beach" یا یک شخص خاص را پیدا می‌کند. شما این سرویس را روی یک VPS شخصی اجرا می‌کنید؛ فایل‌های اصلی روی دیسک خودتان باقی می‌مانند و هیچ‌کس برای تبلیغات، آن‌ها را اسکن نمی‌کند.

نصب این سرویس شامل چهار Container بر اساس فایل Docker Compose خود پروژه است. این مرحله 10 دقیقه زمان می‌برد. بخش‌های باقی‌مانده در این راهنما، چالش‌های اصلی هستند: Container مربوط به Machine-learning در سرورهای کوچک مصرف حافظه (RAM) بالایی دارد، فایل‌های اصلی فضای دیسک را سریع پر می‌کنند، اپلیکیشن موبایل از سرورهای ساده با پروتکل HTTP جلوگیری می‌کند، و Immich به اندازه کافی تغییرات ساختاری (Breaking changes) دارد که یک docker compose pull بی‌دقت می‌تواند باعث از کار افتادن دیتابیس شود. اگر این 4 مورد را جدی بگیرید، Immich بسیار پایدار خواهد بود. اگر آن‌ها را نادیده بگیرید، یک آخر هفته را از دست خواهید داد.

پیش‌نیازها و نکات مهم

  • RAM: مستندات رسمی حداقل 6 GB و مقدار پیشنهادی 8 GB را ذکر کرده‌اند — در عمل، 4 GB به همراه swap را به عنوان حداقل مورد نیاز در نظر بگیرید. کانتینرهای immich-server و Postgres منابع کمی مصرف می‌کنند. کانتینر immich-machine-learning مصرف اصلی را دارد؛ زیرا مدل‌های CLIP و تشخیص چهره را برای ساخت ایندکس‌های جستجو در RAM بارگذاری می‌کند و در سیستم‌های با 2 GB، هسته سیستم (kernel) آن را متوقف می‌کند. حتی اگر 4 GB رم دارید، swap اضافه کنید.
  • Disk: فضای مورد نیاز را بر اساس کل کتابخانه خود و کمی بیشتر محاسبه کنید. فایل‌های اصلی شما به طور کامل کپی می‌شوند و علاوه بر آن، Immich تصاویر بندانگشتی (thumbnails) و پیش‌نمایش ایجاد می‌کند (تقریباً 10–20% فضای اضافی). یک مجموعه عکس 200 GB، به یک Volume با ظرفیت 300 GB نیاز دارد. حجم Postgres در مقایسه با این مقدار کم است.
  • CPU: هر VPS مدرکی مبتنی بر KVM مناسب است، اما اجرای ML روی CPU کند است. ایندکس‌گذاری Smart-search برای یک واردسازی (import) بزرگ می‌تواند ساعت‌ها در پس‌زمینه اجرا شود. این وضعیت عادی است و نیازی به GPU ندارد.
  • یک نام دامنه که به VPS اشاره (point) شده باشد. اپلیکیشن موبایل به شدت بر استفاده از HTTPS تاکید دارد و شما باید یک reverse proxy در مقابل آن داشته باشید. این ساختار مشابه یک نمونه self-hosted Nextcloud با Docker، TLS و بک‌آپ است — Immich معادل بخش عکس‌ها برای آن سرور فایل است.
  • نصب بودن Docker و افزونه Compose — Docker Engine به همراه افزونه Compose v2 از مخزن apt خودِ Docker، دقیقاً مطابق آنچه در راهنمای اصول اولیه Docker Compose ما توضیح داده شده است.

Step 1: قبل از هر کاری swap را اضافه کنید

رایج‌ترین دلیل شکست Immich در VPSهای کوچک، از دست رفتن container مربوط به ML به دلیل کمبود حافظه (OOM-killed) است. ابتدا به هسته سیستم (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 نسخه‌های سرویس‌ها و به طور حیاتی، نسخه ایمیج دیتابیس خود را در فایل‌های ارسالی تثبیت می‌کند. فایل 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

این فایل‌ها از نسخه tagged استخراج شده‌اند، بنابراین ارجاعات ایمیج مطابقت دارند. فایل compose شامل چهار سرویس است؛ بهتر است قبل از هر اقدامی، از وظیفه هر کدام مطلع باشید:

  • immich-server (ghcr.io/immich-app/immich-server, container immich_server) — شامل API و رابط کاربری وب که روی پورت 2283 گوش می‌دهد. فایل‌های آپلود شده شما را در /data mount می‌کند.
  • immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, container immich_machine_learning) — شامل جستجوی CLIP و تشخیص چهره. مدل‌های دانلود شده را در یک volume به نام model-cache کش می‌کند. این سرویس مصرف حافظه (RAM) بالایی دارد.
  • database (container immich_postgres) — شامل Postgres با افزونه برداری VectorChord که قابلیت جستجوی شباهت را فراهم می‌کند. تگ ایمیج مستقیماً در فایل compose با استفاده از digest تثبیت شده است، برای مثال ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0@sha256:.... در نصب‌های قدیمی از pgvecto.rs استفاده می‌شد؛ پشتیبانی از آن در Immich v3.0 حذف شد، بنابراین هر چیزی که امروز نصب کنید VectorChord است. هرگز این تگ را به صورت دستی ویرایش نکنید.
  • redis (container immich_redis) — یک نمونه Valkey/Redis برای صف‌های کاری (job queues).

Step 3: Configure .env — محل ذخیره‌سازی عکس‌ها و پایگاه داده شما

.env را باز کنید و 4 مورد را تنظیم کنید. تمام موارد زیر خط مشخص شده بدون تغییر باقی می‌مانند.

# 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

دو قانون برای جلوگیری از بروز مشکلات. مسیر UPLOAD_LOCATION باید به دیسک بزرگ شما اشاره کند؛ اگر قصد دارید بعداً یک volume داده اضافه کنید، از ابتدا این مسیر را برابر با mount path آن قرار دهید، زیرا جابه‌جایی آن در مراحل بعد مستلزم انتقال thumbnailها و به‌روزرسانی مسیرهای asset است. همچنین DB_DATA_LOCATION باید روی دیسک محلی باشد: استفاده از Postgres روی یک share از نوع NFS یا SMB باعث خرابی داده‌ها می‌شود و مستندات نیز صراحتاً به این موضوع اشاره کرده‌اند. اگر در DB_PASSWORD فقط از حروف و اعداد استفاده کنید، از بروز دسته‌ای از باگ‌های مربوط به escaping در connection-string جلوگیری می‌کنید.

Step 4: اولین اجرا و ساخت کاربر admin

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

نتیجه صحیح شامل چهار container است که همگی در وضعیت running و در نهایت در وضعیت healthy هستند:

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

اولین up چندین گیگابایت image را دانلود می‌کند، بنابراین منتظر بمانید. روند پیشرفت را با sudo docker compose logs -f immich-server مشاهده کنید؛ پس از آماده شدن، سرور در log اعلام می‌کند که در port 2283 در حال listening است. اکنون http://YOUR_SERVER_IP:2283 را در یک browser باز کنید. اولین بازدید، یک wizard با عنوان Getting Started را نمایش می‌دهد — اولین حسابی که می‌سازید، حساب admin خواهد بود. یک password قوی انتخاب کنید؛ این حساب مالک تنظیمات سرور، مدیریت کاربران و ML configuration است که بعداً به آن نیاز خواهید داشت.

Step 5: اپلیکیشن موبایل و بک‌آپ در پس‌زمینه

اپلیکیشن "Immich" را از App Store یا Play Store نصب کنید. در صفحه ورود، از شما Server Endpoint URL خواسته می‌شود. آدرس کامل را همراه با scheme وارد کنید، برای مثال https://photos.example.com (خودِ اپلیکیشن /api را اضافه می‌کند). با حسابی که تازه ساخته‌اید وارد شوید، سپس صفحه Backup در اپلیکیشن را باز کنید، آلبوم‌های مورد نظر برای محافظت را انتخاب کنید (معمولاً Camera و Screenshots) و گزینه Background backup را فعال کنید. در iOS، عملیات بک‌آپ در پس‌زمینه توسط سیستم‌عامل محدود (throttle) می‌شود؛ آپلودها در حالت foreground همیشه اجرا می‌شوند، اما آپلودهای پس‌زمینه زمانی انجام می‌شوند که سیستم‌عامل اجازه دهد.

دقیقاً همین‌جا است که کاربران دچار مشکل می‌شوند، بنابراین قبل از تلاش مجدد با اپلیکیشن، Step 6 را بخوانید.

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

اپلیکیشن موبایل حتماً به HTTPS نیاز دارد. یک reverse proxy در مقابل پورت 2283 قرار دهید و TLS را در آنجا terminate کنید. اگر در حال حاضر چندین container را اجرا می‌کنید، Traefik with automatic TLS for multiple Docker apps تمیزترین گزینه است؛ یک بلوک label، مسیر photos.example.com را به container مربوط به immich-server هدایت می‌کند و گواهینامه (certificate) را برای شما دریافت می‌کند. اگر 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 باشد. استفاده از endpointهای http://، یا استفاده از IP مستقیم بدون پورت، علت خطای "the app cannot reach the server" است که در ادامه به عنوان یک خطای مشخص بررسی می‌شود.

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

دو روش برای ورود عکس‌ها به Immich وجود دارد که با هم متفاوت هستند.

  • Uploads دارایی‌های تحت مالکیت Immich هستند. اپلیکیشن یا uploader وب، فایل را در UPLOAD_LOCATION کپی می‌کند. Immich می‌تواند نام آن‌ها را تغییر دهد، آن‌ها را جابه‌جا کند یا حذف کند.
  • External libraries وارد کردن فایل‌هایی هستند که از حالت read-only خارج نمی‌شوند و از قبل در پوشه‌ای روی سرور شما قرار دارند؛ مانند یک ساختار قدیمی Pictures یا یک export از NAS. Immich آن‌ها را در همان محل ایندکس کرده و در timeline نمایش می‌دهد، اما هرگز فایل‌های اصلی را تغییر نمی‌دهد یا حذف نمی‌کند.

برای وارد کردن یک ساختار موجود، آن را به صورت read-only در container سرور mount کنید. فایل 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 هرگز نمی‌تواند به فایل‌های اصلی دسترسی تغییر داشته باشد. با استفاده از sudo docker compose up -d container را بازسازی کنید، سپس در رابط کاربری وب به قسمت avatar خود بروید ← Administration → External Libraries → Create Library، کاربر مالک را انتخاب کنید، در بخش Folders روی Add کلیک کنید و مسیر container را وارد کنید — یعنی /mnt/media/photos، نه مسیر host یعنی /srv/photos. روی Scan کلیک کنید. استفاده از مسیر host به جای مسیر container، رایج‌ترین اشتباه در بخش external-library است؛ در این حالت scan هیچ فایلی پیدا نمی‌کند و تعداد assets را 0 گزارش می‌دهد.

Step 8: نظم به‌روزرسانی مورد نیاز Immich

این بخش تفاوت میان یک نصب سالم و یک نصب خراب از Immich را تعیین می‌کند. Immich با سرعت بالا توسعه می‌یابد و اصلاحیه‌ها را به نسخه‌های قدیمی منتقل نمی‌کند (backport) و از بازگشت به نسخه‌های قبلی (downgrade) پشتیبانی نمی‌کند. دنبال کردن کورکورانه تگ شناور v3 در نهایت باعث از کار افتادن پایگاه داده شما می‌شود. نظم مورد نیاز:

  1. یک نسخه مشخص را ثابت کنید (Pin). مقدار IMMICH_VERSION را روی یک تگ مشخص مانند v3.0.2 تنظیم کنید، نه روی تگ شناور v3 که همیشه جدیدترین نسخه v3.x را دریافت می‌کند.
  2. هر بار قبل از به‌روزرسانی، یادداشت‌های انتشار (release notes) را بخوانید. تغییرات مخرب (Breaking changes) — به‌ویژه تغییرات مربوط به پایگاه داده یا افزونه‌های برداری (vector-extension) — در آنجا ذکر می‌شوند. نسخه v3.0 یک مثال واضح است: این نسخه افزونه pgvecto.rs را کاملاً حذف کرد؛ بنابراین هر کسی که هنوز از افزونه قدیمی استفاده می‌کرد، باید پیش از ارتقا، مهاجرت به VectorChord (که در نسخه v1.133 معرفی شده بود) را تکمیل می‌کرد.
  3. ابتدا از پایگاه داده نسخه پشتیبان تهیه کنید (Step 9). همیشه این کار را انجام دهید، اما وقتی یادداشت‌ها به پایگاه داده اشاره دارند، این کار اهمیت دوچندان دارد.
  4. فایل compose جدید را نیز دریافت کنید. فایل IMMICH_VERSION فقط تصاویر (images) مربوط به server و ML را ثابت می‌کند. تصویر 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: Backups — a database dump PLUS the originals, and test it

یک بک‌آپ از Immich شامل دو بخش است و نبود هر کدام، دیگری را بی‌فایده می‌کند. database شامل ساختار آلبوم‌ها، چهره‌ها، ایندکس‌های جستجو و نقشه اتصال asset به فایل است. originals directory شامل عکس‌های اصلی است. اگر یکی را بدون دیگری بازیابی کنید، یا با عکس‌های بدون سازماندهی مواجه می‌شوید و یا با یک پوسته خالی که به فایل‌های مفقود اشاره می‌کند.

دیتابیس را با استفاده از pg_dump از داخل کانتینر Postgres استخراج کنید — مشخصاً دیتابیس 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. ابتدا دیتابیس و سپس فایل‌ها را بک‌آپ بگیرید، تا فایل استخراج شده هرگز به عکسی اشاره نکند که فایل آن هنوز کپی نشده است. کتابخانه‌های خارجی (External libraries) را باید جداگانه از منبع اصلی خود بک‌آپ بگیرید؛ Immich مالک آن‌ها نیست.

حالا مرحله‌ای که همه از آن چشم‌پوشی می‌کنند: بازیابی را تست کنید. یک بازیابی باید روی یک stack جدید که سرور آن هرگز اجرا نشده است، و روی یک image از Postgres که افزونه vector آن با dump سازگار باشد، انجام شود — دقیقاً به همین دلیل است که هرگز نباید در انتخاب DB image tag مرتجع باشید. در یک سیستم تست با همان compose و .env، هرگونه وضعیت قدیمی را پاک کنید، فقط دیتابیس را بالا بیاورید، سپس 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 شما بالا آمد، رابط کاربری وب را باز کنید: اگر عکس‌ها و آلبوم‌های شما آنجا هستند، بک‌آپ شما کار می‌کند. اگر هرگز این کار را انجام نداده‌اید، شما بک‌آپ ندارید — شما فقط امیدوار هستید.

حالت‌های خطا و رشته‌هایی که مشاهده خواهید کرد

کانتینر ML با خطای OOM-killed مواجه می‌شود. فرآیند sudo docker compose logs immich-machine-learning ناگهان متوقف می‌شود، docker compose ps این موضوع را نشان می‌دهد (Restarting) و کد خروج 137 است. sudo dmesg | grep -i oom این مورد را تایید می‌کند: Out of memory: Killed process ... (python3). پس از آن، وظایف (jobs) مربوط به Search و Face متوقف می‌شوند. علت این است که مقدار RAM برای مدل‌ها کافی نیست. راه حل‌ها به ترتیب: افزودن swap (مرحله 1)؛ افزایش RAM مربوط به VPS؛ یا اگر واقعاً امکان‌پذیر نیست، غیرفعال کردن ML در مسیر Administration → Settings → Machine Learning Settings با خاموش کردن Smart Search و Facial Recognition — در این حالت بک‌آپ‌ها و آلبوم‌ها حفظ می‌شوند، اما قابلیت جستجو بر اساس محتوا از دست می‌رود. حذف سرویس immich-machine-learning از فایل compose نیز نتیجه مشابهی دارد.

Postgres پس از ارتقا از اجرا باز می‌ماند. لاگ سرور با خطایی مانند 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. یا در نسخه‌های قدیمی‌تر The pgvecto.rs extension is not available in this Postgres instance. در یک حلقه تکرار می‌شود. علت این است که نسخه افزونه (extension) در ایمیج دیتابیس قدیمی‌تر از نسخه‌ای است که داده‌های شما به آن ارتقا یافته‌اند؛ این اتفاق معمولاً به دلیل تغییر دستی تگ ایمیج یا بازیابی یک dump جدیدتر روی یک ایمیج قدیمی‌تر رخ می‌دهد. راه حل استفاده از ایمیج Postgres متناظر است — فایل compose مربوط به نسخه‌ای که با دیتابیس شما مطابقت دارد را استفاده کنید، نسخه را پایین نیاورید (do not downgrade) و فقط روی یک ایمیج سازگار بازیابی (restore) کنید.

اپلیکیشن موبایل نمی‌تواند به سرور متصل شود. پس از وارد کردن URL، صفحه ورود خطای اتصال یا Server is not reachable را نشان می‌دهد. سه علت وجود دارد: شما http:// را وارد کرده‌اید در حالی که پروکسی فقط https:// را سرو می‌کند؛ مستقیماً به backend متصل شده‌اید اما پورت را وارد نکرده‌اید، بنابراین برنامه سعی می‌کند به جای example.com:2283 به example.com (پورت 443) متصل شود؛ یا reverse proxy در انتقال /api مشکل دارد. با وارد کردن URL کامل https://photos.example.com و اطمینان از اینکه ابتدا در مرورگر گوشی باز می‌شود، مشکل را حل کنید. اگر مرورگر کار می‌کند اما اپلیکیشن خیر، پروکسی در حال حذف کردن path است یا گواهی (certificate) self-signed است — اپلیکیشن گواهی‌های غیرقابل اعتماد را رد می‌کند.

کمبود فضای دیسک در حین Import. عملیات آپلود با خطا مواجه می‌شود، تصاویر بندانگشتی (thumbnails) خالی می‌مانند و لاگ‌ها ENOSPC: no space left on device یا از سمت Postgres، could not extend file ... No space left on device را نشان می‌دهند. دستور df -h میزان پر بودن حجم UPLOAD_LOCATION را در 100% نشان می‌دهد. به همین دلیل است که باید قبل از وارد کردن یک کتابخانه بزرگ، حجم دیسک را محاسبه کنید. برای بازیابی، یک volume بزرگ‌تر متصل کنید، stack را متوقف کنید، UPLOAD_LOCATION را به آن منتقل کنید، .env را به‌روزرسانی کنید و دوباره شروع کنید — یا اگر ارائه‌دهنده شما اجازه می‌دهد، دیسک موجود را گسترش دهید. اگر دیسک پر شود، Postgres ممکن است دچار قفل شدن (wedge) شود، بنابراین قبل از فرض کردن خرابی داده‌ها، فضا را خالی کرده و کانتینر دیتابیس را ری‌استارت کنید.

FAQ

Immich به چه میزان RAM و دیسک نیاز دارد؟

حداقل مقدار مورد نیاز رسمی برای Immich برابر با 6 GB از RAM است و مقدار 8 GB توصیه می‌شود. برای یک کتابخانه کوچک، مقدار 4 GB به همراه swap کفِ عملیاتی است؛ در هر صورت swap را پیکربندی کنید، زیرا container مربوط به machine-learning باعث افزایش ناگهانی مصرف منابع می‌شود. برای دیسک، حجم کامل کتابخانه خود را به علاوه حدود 10–20% برای تصاویر بندانگشتی (thumbnails) و پیش‌نماهای تولید شده در نظر بگیرید و از حافظه محلی استفاده کنید؛ هرگز دایرکتوری داده‌های Postgres را روی یک network share قرار ندهید. اگر هنوز در حال تصمیم‌گیری برای سایر سرویس‌ها هستید، راهنمای خودمیزبانی در سال 2026 میزان مصرف منابع Immich را در کنار سایر سرویس‌ها مقایسه کرده است.

آیا می‌توانم Immich را بدون GPU اجرا کنم؟

بله. container مربوط به machine-learning بدون مشکل روی CPU اجرا می‌شود؛ یک GPU فقط سرعت ایندکس‌گذاری smart-search و در صورت استفاده از نسخه مناسب، سرعت transcoding ویدیو را افزایش می‌دهد. در حالت CPU، ایندکس اولیه یک کتابخانه بزرگ ممکن است ساعت‌ها در پس‌زمینه زمان ببرد، اما مانع از انجام backup یا مرور تصاویر نمی‌شود. اگر سخت‌افزار شما اصلاً برای ML مناسب نیست، می‌توانید Smart Search و Facial Recognition را در تنظیمات ادمین غیرفعال کنید و سایر قابلیت‌ها را حفظ کنید.

چگونه Immich را با امنیت بالا ارتقا (upgrade) دهم؟

نسخه IMMICH_VERSION را روی یک تگ مشخص مانند v3.0.2 ثابت (pin) کنید، قبل از هر ارتقا release notes را بخوانید و ابتدا از دیتابیس backup بگیرید. از آنجایی که تصویر Postgres در داخل docker-compose.yml به جای IMMICH_VERSION ثابت شده است، فایل compose و example.env مربوط به نسخه هدف را مجدداً دانلود کرده، مقادیر خود را دوباره اعمال کنید و سپس docker compose pull && docker compose up -d را اجرا کنید. هرگز اجازه ندهید نسخه به صورت شناور (float) باقی بماند؛ Immich شامل تغییرات ساختاری (breaking changes) است و از بازگشت به نسخه‌های قبلی (downgrades) پشتیبانی نمی‌کند.

دقیقاً چه چیزی را باید backup کنم؟

دو مورد را با هم: یک pg_dump از دیتابیس immich و کل دایرکتوری اصلی UPLOAD_LOCATION. دیتابیس شامل آلبوم‌ها، چهره‌ها و نگاشت فایل‌ها (asset-to-file mapping) است؛ دایرکتوری شامل عکس‌های واقعی است و برای بازیابی (restore)، به هر دو مورد به همراه یک image دیتابیس با یک vector extension سازگار نیاز دارید. ابتدا dump دیتابیس را انجام دهید و سپس کپی فایل‌ها را انجام دهید؛ همچنین حداقل یک بار فرآیند بازیابی را روی یک سیستم آزمایشی تست کنید؛ یک backup که تست نشده باشد، backup محسوب نمی‌شود.

چگونه پوشه عکس‌های موجود خود را وارد (import) کنم؟

پوشه مورد نظر را به صورت read-only به عنوان یک volume اضافی (مثلاً - /srv/photos:/mnt/media/photos:ro) به container immich-server mount کنید، container را مجدداً ایجاد کنید، سپس در مسیر Administration → External Libraries یک کتابخانه بسازید و مسیر container یعنی /mnt/media/photos را اضافه کنید. Immich فایل‌ها را در محل اصلی خود ایندکس می‌کند و هرگز آن‌ها را تغییر نمی‌دهد یا حذف نمی‌کند. رایج‌ترین اشتباه، وارد کردن مسیر host به جای مسیر container است که باعث می‌شود اسکن هیچ فایلی پیدا نکند.

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