SSD Nodes Learn
คู่มือ Matt Connorโดย Matt Connor · อัปเดตเมื่อ 2026-07-24

วิธีติดตั้ง Immich บน RAM 6 GB และการอัปเกรด

เจาะลึกการใช้ RAM 6 GB และวิธีแก้ปัญหา Immich v3 ที่ไม่สามารถเริ่มระบบบน pgvecto.rs ได้ พร้อมขั้นตอนการกู้คืนข้อมูลและวิธีตั้งค่าพอร์ต 2283 ผ่าน HTTPS

สิ่งที่คุณกำลังสร้าง

Immich คือบริการสำรองข้อมูลรูปภาพและวิดีโอแบบ self-hosted ซึ่งสามารถใช้งานแทน Google Photos ได้อย่างแท้จริง ระบบมีแอปพลิเคชันบนมือถือที่อัปโหลดรูปภาพจาก camera roll ให้โดยอัตโนมัติในพื้นหลัง มีระบบ timeline, อัลบั้ม, การจดจำใบหน้า และการค้นหาด้วย machine-learning ที่สามารถค้นหาคำว่า "beach" หรือค้นหาบุคคลได้โดยไม่ต้องติด tag ใดๆ คุณสามารถรันระบบนี้บน VPS ส่วนตัว ไฟล์ต้นฉบับจะถูกเก็บไว้ใน disk ของคุณ และจะไม่มีใครสแกนข้อมูลเพื่อนำไปใช้ในการโฆษณา

การติดตั้งประกอบด้วย 4 containers จาก Docker Compose file ของโปรเจกต์ ซึ่งใช้เวลาประมาณ 10 นาที ส่วนที่เหลือของคู่มือนี้คือส่วนที่ต้องระมัดระวัง: container สำหรับ machine-learning ใช้หน่วยความจำสูงเมื่อรันบนเครื่องขนาดเล็ก, ไฟล์ต้นฉบับใช้พื้นที่ disk อย่างรวดเร็ว, แอปพลิเคชันมือถือไม่รองรับการเชื่อมต่อผ่าน HTTP ธรรมดา และ Immich มีการอัปเดตที่มีการเปลี่ยนแปลงแบบ breaking changes บ่อยครั้ง ซึ่งหาก docker compose pull ไม่ระมัดระวังอาจทำให้ database ไม่สามารถเริ่มต้นระบบได้ หากคุณจัดการ 4 ประเด็นนี้อย่างจริงจัง Immich จะมีความเสถียรสูง แต่หากละเลย คุณอาจต้องเสียเวลาแก้ไขปัญหาตลอดทั้งวันหยุด

Prerequisites, and the honest gotchas

  • RAM: เอกสารอย่างเป็นทางการระบุว่าต้องการขั้นต่ำ 6 GB และแนะนำที่ 8 GB — ให้ถือว่า 4 GB พร้อม swap คือระดับต่ำสุดที่ใช้งานได้จริง คอนเทนเนอร์ immich-server และ Postgres ใช้ทรัพยากรไม่มาก ส่วนคอนเทนเนอร์ immich-machine-learning ใช้ทรัพยากรสูง เนื่องจากต้องโหลดโมเดล CLIP และ face-recognition ลงใน RAM เพื่อสร้าง search indexes ซึ่งหากใช้เครื่องที่มี RAM เพียง 2 GB kernel จะสั่งปิดโปรเซสทันที ควรเพิ่ม swap แม้ว่าจะมี RAM 4 GB แล้วก็ตาม
  • Disk: ควรเตรียมพื้นที่ให้ครอบคลุมขนาดของคลังภาพทั้งหมดและเผื่อไว้เพิ่มเติม ไฟล์ต้นฉบับจะถูกคัดลอกมาทั้งหมด นอกจากนี้ Immich ยังต้องสร้างรูป thumbnail และรูป preview (ใช้พื้นที่เพิ่มขึ้นประมาณ 10–20%) หากมีรูปภาพ 200 GB ควรเตรียม volume ไว้ 300 GB โดย Postgres ใช้พื้นที่น้อยมากเมื่อเทียบกัน
  • CPU: VPS ที่เป็น KVM รุ่นใหม่สามารถใช้งานได้ แต่การประมวลผล ML บน CPU จะทำงานช้า การทำ smart-search indexing สำหรับข้อมูลจำนวนมากอาจใช้เวลาหลายชั่วโมงใน background ซึ่งเป็นเรื่องปกติและไม่จำเป็นต้องใช้ GPU
  • Domain name ที่ชี้มายัง VPS แอปพลิเคชันบนมือถือทำงานได้ดีที่สุดผ่าน HTTPS endpoint และควรใช้งานร่วมกับ reverse proxy การตั้งค่านี้มีลักษณะเหมือนกับ self-hosted Nextcloud instance with Docker, TLS and backups โดย Immich คือระบบจัดการรูปภาพที่ทำงานในลักษณะเดียวกับ server เก็บไฟล์ดังกล่าว
  • Docker และ Compose plugin ที่ติดตั้งเรียบร้อยแล้ว — ต้องใช้ Docker Engine ร่วมกับ Compose v2 plugin จาก apt repository ของ Docker โดยตรง ตามที่อธิบายไว้ใน our Docker Compose basics guide

Step 1: เพิ่ม swap ก่อนดำเนินการอื่นใด

สาเหตุที่พบบ่อยที่สุดที่ทำให้ Immich ทำงานผิดพลาดบน VPS ขนาดเล็ก คือ container ของ ML ถูกสั่งหยุดทำงานโดย OOM-killer ควรจัดสรรพื้นที่ให้ 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 บนเครื่องที่มี RAM 4 GB

Step 2: รับไฟล์ compose และ env อย่างเป็นทางการ — ให้ใช้ไฟล์จากผู้พัฒนาเท่านั้น

Immich กำหนดเวอร์ชันของ service และที่สำคัญที่สุดคือกำหนด image ของ database ไว้ภายในไฟล์ที่จัดส่งมาด้วย ห้ามคัดลอกไฟล์ compose จากบล็อก (รวมถึงบล็อกนี้) มาใช้เป็นแหล่งข้อมูลหลัก ให้ดาวน์โหลด release assets ดังนี้:

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 ที่มีการติด tag ไว้ เพื่อให้การอ้างอิง image ตรงกัน ไฟล์ compose ประกอบด้วย 4 services ซึ่งควรทำความเข้าใจหน้าที่ของแต่ละ service ก่อนเริ่มดำเนินการ:

  • immich-server (ghcr.io/immich-app/immich-server, container immich_server) — ทำหน้าที่เป็น API และ web UI โดยรับการเชื่อมต่อผ่าน port 2283 และทำการ mount ข้อมูลที่อัปโหลดไว้ที่ /data
  • immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, container immich_machine_learning) — ทำหน้าที่ค้นหาด้วย CLIP และจดจำใบหน้า (face recognition) โดยจะเก็บ cache ของ model ที่ดาวน์โหลดมาไว้ใน volume model-cache service นี้ใช้ทรัพยากร memory สูง
  • database (container immich_postgres) — Postgres ที่ติดตั้ง extension VectorChord สำหรับการค้นหาแบบ similarity search โดย 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) — instance ของ 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

กฎ 2 ข้อเพื่อป้องกันปัญหาที่อาจเกิดขึ้น UPLOAD_LOCATION ควรชี้ไปยัง disk ขนาดใหญ่ หากคุณจะติดตั้ง data volume ในภายหลัง ให้ตั้งค่านี้เป็น mount path ตั้งแต่เริ่มต้น เพราะการย้ายภายหลังจะทำให้ต้องย้าย thumbnails และต้องอัปเดต asset paths ใหม่ และ DB_DATA_LOCATION ต้องอยู่บน local disk เนื่องจาก Postgres บน NFS หรือ SMB share จะทำให้ข้อมูลเสียหายตามที่ระบุไว้ในเอกสาร หากคุณใช้เพียงตัวอักษรและตัวเลขใน DB_PASSWORD คุณจะหลีกเลี่ยงข้อผิดพลาดประเภท connection-string escaping ได้

Step 4: การรันครั้งแรกและการสร้างผู้ใช้ admin

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

ผลลัพธ์ที่ถูกต้องคือต้องมี 4 containers โดยทุกตัวต้องอยู่ในสถานะ running และเปลี่ยนเป็น healthy ในที่สุด:

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

up ตัวแรกจะทำการ pull images ขนาดหลาย gigabytes โปรดรอสักครู่ สามารถติดตามความคืบหน้าได้ด้วย sudo docker compose logs -f immich-server; เมื่อระบบพร้อมแล้ว server จะแสดง log ว่ากำลัง listening บน port 2283 จากนั้นให้เปิด http://YOUR_SERVER_IP:2283 ใน browser การเข้าใช้งานครั้งแรกจะแสดงหน้า wizard Getting Started — บัญชีแรกที่คุณสร้างจะเป็นบัญชี admin โปรดตั้งรหัสผ่านที่คาดเดายาก บัญชีนี้ใช้สำหรับจัดการการตั้งค่า server, การจัดการผู้ใช้ และการตั้งค่า ML ที่ต้องใช้ในภายหลัง

Step 5: แอปพลิเคชันมือถือและการสำรองข้อมูลเบื้องหลัง

ติดตั้ง "Immich" จาก App Store หรือ Play Store เมื่อถึงหน้าจอเข้าสู่ระบบ ระบบจะถามหา Server Endpoint URL ให้กรอก URL ฉบับเต็มรวมถึง scheme ตัวอย่างเช่น https://photos.example.com (แอปจะเพิ่ม /api ให้โดยอัตโนมัติ) เข้าสู่ระบบด้วยบัญชีที่เพิ่งสร้าง จากนั้นเปิดหน้าจอ Backup ของแอป เลือกอัลบั้มที่ต้องการสำรองข้อมูล (โดยปกติคือ Camera และ Screenshots) และเปิดใช้งาน Background backup การสำรองข้อมูลเบื้องหลังบน iOS จะถูกจำกัดความเร็วโดย OS — การอัปโหลดขณะเปิดแอปจะทำงานตลอดเวลา ส่วนการอัปโหลดเบื้องหลังจะเกิดขึ้นเมื่อ OS อนุญาต

ขั้นตอนนี้เป็นจุดที่ผู้ใช้มักประสบปัญหา โปรดอ่าน Step 6 ก่อนเริ่มดำเนินการกับแอป

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

แอปพลิเคชันบนมือถือจำเป็นต้องใช้ HTTPS ให้ติดตั้ง reverse proxy ไว้ด้านหน้า port 2283 เพื่อทำ TLS termination หากคุณรันหลาย container อยู่แล้ว Traefik with automatic TLS for multiple Docker apps เป็นตัวเลือกที่จัดการได้ง่ายที่สุด โดยใช้ label block เพียงชุดเดียวเพื่อ route photos.example.com ไปยัง container immich-server และจัดการดึง certificate ให้โดยอัตโนมัติ หากคุณต้องการใช้ nginx ให้ดูคู่มือ Let's Encrypt with Certbot and nginx เพื่อรับ certificate และสร้าง proxy_pass http://127.0.0.1:2283; block สำหรับการตั้งค่า 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 โดยไม่ระบุ port คือสาเหตุที่ทำให้เกิดข้อผิดพลาด "the app cannot reach the server" ซึ่งมีรายละเอียดระบุไว้ในหัวข้อข้อผิดพลาดด้านล่าง

Step 7: External libraries vs uploads — การนำเข้าโครงสร้างโฟลเดอร์รูปภาพที่มีอยู่เดิม

การนำรูปภาพเข้าสู่ Immich มี 2 วิธี ซึ่งมีลักษณะการทำงานที่แตกต่างกัน

  • Uploads คือไฟล์ที่ Immich เป็นเจ้าของ แอปพลิเคชันหรือเว็บ uploader จะคัดลอกไฟล์ลงใน UPLOAD_LOCATION โดย Immich สามารถเปลี่ยนชื่อ ย้าย หรือลบไฟล์เหล่านี้ได้
  • External libraries คือการนำเข้าไฟล์แบบ read-only จากโฟลเดอร์ที่มีอยู่แล้วบน server เช่น โครงสร้างโฟลเดอร์ Pictures เดิม หรือไฟล์ที่ export จาก NAS โดย Immich จะทำเพียงการทำ index ไฟล์ในตำแหน่งเดิมเพื่อแสดงผลบน timeline แต่จะไม่แก้ไขหรือลบไฟล์ต้นฉบับโดยเด็ดขาด

หากต้องการนำเข้าโครงสร้างโฟลเดอร์ที่มีอยู่เดิม ให้ทำการ mount โฟลเดอร์นั้นแบบ read-only เข้าไปใน server 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 จะไม่สามารถแก้ไขไฟล์ต้นฉบับได้ ให้ทำการ recreate container ด้วย sudo docker compose up -d จากนั้นไปที่ web UI เลือก avatar → Administration → External Libraries → Create Library เลือก user ที่เป็นเจ้าของไฟล์ คลิก Add ภายใต้ Folders แล้วระบุ path ของ container คือ /mnt/media/photos (ไม่ใช่ host path /srv/photos) จากนั้นคลิก Scan ข้อผิดพลาดที่พบบ่อยที่สุดในการใช้ external library คือการระบุ host path แทนที่จะเป็น container path ซึ่งจะทำให้การ scan ไม่พบข้อมูลและรายงานจำนวน asset เป็นศูนย์

Step 8: ข้อควรปฏิบัติในการอัปเกรดสำหรับ Immich

ส่วนนี้คือสิ่งที่แยกการใช้งาน Immich ที่ราบรื่นออกจากระบบที่พัง เนื่องจาก Immich พัฒนาอย่างรวดเร็ว จึงไม่มีการนำการแก้ไขย้อนหลัง (backport) มาใช้ และไม่รองรับการลดเวอร์ชัน (downgrade) การติดตาม tag v3 ที่มีการเปลี่ยนแปลงตลอดเวลาจะทำให้ฐานข้อมูลของคุณพังในที่สุด ข้อควรปฏิบัติมีดังนี้:

  1. ระบุเวอร์ชันที่แน่นอน (Pin a version) กำหนด IMMICH_VERSION ให้เป็น tag ที่เจาะจง เช่น v3.0.2 แทนที่จะใช้ v3 ซึ่งจะดึงเวอร์ชัน v3.x ล่าสุดมาให้เสมอ
  2. อ่าน release notes ทุกครั้ง ก่อนทำการอัปเกรด ข้อมูลการเปลี่ยนแปลงที่ทำให้ระบบเดิมใช้งานไม่ได้ (Breaking changes) โดยเฉพาะการเปลี่ยนแปลงในส่วนของ database หรือ vector-extension จะถูกระบุไว้ในนั้น ตัวอย่างที่ชัดเจนคือเวอร์ชัน v3.0 ซึ่งได้ตัด pgvecto.rs ออกไป ดังนั้นผู้ที่ยังใช้ extension ตัวเดิมอยู่ จะต้องดำเนินการย้ายข้อมูลไปยัง VectorChord (ซึ่งเริ่มใช้ตั้งแต่ v1.133) ให้เสร็จสิ้นก่อนจึงจะอัปเกรดได้
  3. สำรองข้อมูลฐานข้อมูลก่อนเสมอ (Step 9) ต้องทำทุกครั้ง และต้องระมัดระวังเป็นพิเศษหากใน release notes มีการระบุถึงฐานข้อมูล
  4. ดาวน์โหลดไฟล์ compose ใหม่มาด้วย เนื่องจาก IMMICH_VERSION ระบุเวอร์ชันเฉพาะของ server และ ML images เท่านั้น ส่วน Postgres image ถูกระบุด้วย digest ภายใน docker-compose.yml ดังนั้นหากเวอร์ชันใหม่ต้องการ database extension ที่ใหม่กว่า จะมีการส่งไฟล์ compose ชุดใหม่มาด้วย ให้ดาวน์โหลดไฟล์ release ทั้งสองชุดใหม่ นำค่า .env มาใส่อีกครั้ง แล้วจึงทำการอัปเกรด
  5. อัปเดตแอปพลิเคชันบนมือถือในช่วงเวลาเดียวกัน เนื่องจาก server จะรองรับเฉพาะเวอร์ชันหลัก (major version) ที่ตรงกันเท่านั้น และแอปพลิเคชันจะรองรับเวอร์ชันหลักปัจจุบันและเวอร์ชันก่อนหน้า หาก server มีเวอร์ชันที่ใหม่กว่าแอปพลิเคชัน จะแสดงข้อผิดพลาด 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 — การทำ database dump ร่วมกับไฟล์ต้นฉบับ และการทดสอบ

การสำรองข้อมูลของ Immich ประกอบด้วยสองส่วน หากขาดส่วนใดส่วนหนึ่งไป ข้อมูลจะไม่สามารถใช้งานได้ database ทำหน้าที่เก็บโครงสร้างอัลบั้ม, ใบหน้า, ดัชนีการค้นหา และแผนผังที่เชื่อมโยงระหว่าง asset กับไฟล์ ส่วน originals directory ทำหน้าที่เก็บไฟล์รูปภาพจริง หากกู้คืนข้อมูลเพียงอย่างใดอย่างหนึ่ง คุณจะได้เพียงรูปภาพที่ไม่มีการจัดระเบียบ หรือได้โครงสร้างที่ว่างเปล่าซึ่งชี้ไปยังไฟล์ที่ไม่มีอยู่จริง

ทำการ dump database ด้วย pg_dump จากภายใน container ของ Postgres โดยเลือกเฉพาะ database 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 ให้ทำการสำรอง database ก่อนแล้วจึงตามด้วยไฟล์ เพื่อป้องกันไม่ให้ dump อ้างอิงถึงรูปภาพที่ยังไม่ได้ถูกคัดลอกไปยังไฟล์สำรอง สำหรับ external libraries ให้ทำการสำรองข้อมูลแยกต่างหากจากแหล่งที่มาจริง เนื่องจาก Immich ไม่ได้เป็นเจ้าของข้อมูลเหล่านั้น

ขั้นตอนที่ทุกคนมักข้ามไปคือ: การทดสอบการกู้คืนข้อมูล การกู้คืนข้อมูลต้องทำกับ stack ใหม่ที่ยังไม่เคยถูกรันบน server และต้องใช้ postgres image ที่มี 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

สำหรับการใช้งาน VectorChord database จำเป็นต้องมีการ rewrite search_path ด้วย sed หากไม่ทำ การกู้คืนข้อมูลจะหยุดชะงักกลางคัน เมื่อ 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

Immich ต้องใช้ RAM และ disk เท่าใด?

ข้อกำหนดอย่างเป็นทางการของ Immich คือ RAM ขั้นต่ำ 6 GB และแนะนำที่ 8 GB — สำหรับการใช้งานจริงสำหรับคลังภาพขนาดเล็ก สามารถใช้ RAM 4 GB ร่วมกับ swap ได้ และควรตั้งค่า swap ไว้เสมอ เนื่องจาก container ของ machine-learning จะมีการใช้งานทรัพยากรสูงเป็นช่วงๆ สำหรับ disk ให้เตรียมพื้นที่ไว้เท่ากับขนาดของคลังภาพทั้งหมดบวกเพิ่มอีกประมาณ 10–20% สำหรับการสร้าง thumbnail และ preview โดยควรเก็บไว้ใน local storage — ห้ามเก็บ postgres data directory ไว้บน network share โดยเด็ดขาด หากคุณกำลังตัดสินใจเลือกบริการอื่น คู่มือการเลือกบริการ self-host ในปี 2026 จะแสดงการเปรียบเทียบการใช้ทรัพยากรของ Immich กับบริการอื่นๆ

ฉันสามารถรัน Immich โดยไม่ใช้ GPU ได้หรือไม่?

ได้ container ของ machine-learning สามารถทำงานบน CPU ได้ตามปกติ — GPU จะช่วยเพิ่มความเร็วในการทำ smart-search indexing และการทำ video transcoding (หากใช้ image variant ที่เหมาะสม) หากใช้ CPU การทำ index เริ่มต้นสำหรับคลังภาพขนาดใหญ่อาจใช้เวลาหลายชั่วโมงใน background แต่จะไม่ขัดขวางการสำรองข้อมูลหรือการเรียกดูภาพ หากเครื่องของคุณมีทรัพยากรไม่เพียงพอสำหรับ ML คุณสามารถปิดการใช้งาน Smart Search และ Facial Recognition ในการตั้งค่า admin ได้โดยที่ฟังก์ชันอื่นยังใช้งานได้ตามปกติ

ฉันจะอัปเกรด Immich อย่างปลอดภัยได้อย่างไร?

กำหนดเวอร์ชันของ IMMICH_VERSION ให้เป็น tag ที่แน่นอน เช่น v3.0.2 อ่าน release notes ก่อนการอัปเกรดทุกครั้ง และต้องสำรองข้อมูลฐานข้อมูลก่อน เนื่องจาก image ของ postgres ถูกกำหนดเวอร์ชันไว้ภายใน docker-compose.yml แทนที่จะใช้ IMMICH_VERSION ให้ดาวน์โหลดทั้ง compose file และ example.env จากเวอร์ชันที่ต้องการใหม่ แล้วนำค่าคอนฟิกเดิมมาใส่ จากนั้นจึงรัน docker compose pull && docker compose up -d ห้ามปล่อยให้เวอร์ชันเป็นแบบ float (ไม่ได้ระบุเวอร์ชันที่แน่นอน) เนื่องจาก Immich มีการเปลี่ยนแปลงที่อาจทำให้ระบบเดิมใช้งานไม่ได้ (breaking changes) และไม่รองรับการ downgrade

ฉันต้องสำรองข้อมูลอะไรบ้าง?

ต้องสำรองข้อมูลสองส่วนควบคู่กัน ได้แก่ pg_dump ของ immich database และ directory UPLOAD_LOCATION originals ทั้งหมด ฐานข้อมูลจะเก็บข้อมูลอัลบั้ม, ใบหน้า และการจับคู่ระหว่าง asset กับไฟล์ ส่วน directory จะเก็บไฟล์ภาพจริง การกู้คืนข้อมูลจำเป็นต้องใช้ทั้งสองส่วนนี้ พร้อมกับ database image ที่มี vector extension เวอร์ชันที่เข้ากันได้ ให้ทำการ dump database ก่อน แล้วจึงคัดลอกไฟล์ตาม และควรทดสอบการกู้คืนข้อมูลบนเครื่องทดสอบอย่างน้อยหนึ่งครั้ง เพราะการสำรองข้อมูลที่ไม่ได้ทดสอบถือว่ายังไม่ใช่การสำรองข้อมูลที่สมบูรณ์

ฉันจะนำเข้าโฟลเดอร์รูปภาพที่มีอยู่แล้วได้อย่างไร?

ให้ mount โฟลเดอร์ดังกล่าวแบบ read-only เข้าไปใน container immich-server ในฐานะ extra volume (เช่น - /srv/photos:/mnt/media/photos:ro) จากนั้นสร้าง container ใหม่ แล้วไปที่ Administration → External Libraries เพื่อสร้าง library และเพิ่ม path ภายใน container คือ /mnt/media/photos Immich จะทำการ index ไฟล์ในตำแหน่งเดิมโดยไม่มีการแก้ไขหรือลบไฟล์ต้นฉบับ ข้อผิดพลาดที่พบบ่อยที่สุดคือการระบุ host path แทนที่จะเป็น container path ซึ่งจะทำให้การ scan ไม่พบข้อมูลใดๆ

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