Immich 自架指南：6 GB RAM 需求與版本更新注意事項

專案目標

Immich 是一個自架式相片與影片備份服務，可完全取代 Google Photos。它提供手機 App，能在背景上傳相簿內容；具備時間軸、相簿功能、人臉辨識，以及無需手動標記即可搜尋「beach」或特定人物的機器學習搜尋功能。您可以在自己的 VPS 上執行，原始檔案儲存在您的磁碟中，且不會有任何廠商掃描您的檔案來進行廣告推銷。

安裝過程是透過專案提供的 Docker Compose 檔案啟動四個容器，約需 10 分鐘。本指南的重點在於後續的挑戰：機器學習容器會消耗大量記憶體，原始檔案會迅速佔用磁碟空間，行動 App 不支援純 HTTP 伺服器，且 Immich 的版本更新頻繁，若不小心處理 docker compose pull 可能導致資料庫無法啟動。只要妥善處理這四個問題，Immich 的運行會非常穩定；若忽略這些細節，您將浪費整個週末的時間。

前置作業與注意事項

• RAM：官方文件建議至少 6 GB，推薦 8 GB — 若只有 4 GB 且搭配 swap，才算勉強達標。 immich-server 與 Postgres 容器對資源需求不高。immich-machine-learning 容器最耗資源 — 它需將 CLIP 與臉部辨識模型載入 RAM 以建立搜尋索引，若在 2 GB 的機器上執行，核心 (kernel) 會將其強制關閉。即便擁有 4 GB 記憶體，仍建議增加 swap。
• 磁碟：容量應預留給整個媒體庫，並額外增加空間。 原始檔案會被完整複製，且 Immich 會產生縮圖與預覽圖（約增加 10–20% 的空間）。若有 200 GB 的照片收藏，建議配置 300 GB 的磁碟卷 (volume)。相比之下，Postgres 佔用空間很小。
• CPU：任何現代的 KVM VPS 即可，但使用 CPU 進行機器學習 (ML) 速度較慢。 大量匯入後的智慧搜尋 (Smart-search) 索引作業可能會在背景執行數小時。這是正常現象，不需要 GPU。
• 網域名稱：需指向該 VPS。行動裝置 App 偏好使用 HTTPS 端點，且建議前端配置反向代理 (reverse proxy)。其設定架構與 使用 Docker、TLS 與備份自架的 Nextcloud 實例 相同 — Immich 即是該檔案伺服器的照片對應方案。
• 已安裝 Docker 與 Compose plugin — 請從 Docker 官方 apt 儲存庫安裝 Docker Engine 與 Compose v2 plugin，詳情請參閱 我們的 Docker Compose 基礎指南。

Step 1: 在進行其他操作前先新增 swap

在小型 VPS 上，Immich 最常見的錯誤是 ML container 因 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 的速度，但能防止在 4 GB 的機器上進行 index 時 container 崩潰。

Step 2: 取得官方的 compose 與 env — 請使用官方版本，而非副本

Immich 在其提供的檔案中，已針對服務版本與關鍵的資料庫映像檔進行了版本鎖定。請勿將來自部落格（包含本篇）的 compose 檔案作為唯一依據。請下載發行版本資產：

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

這些檔案來自已標記的發行版本，因此映像檔引用會完全匹配。此 compose 檔案定義了四個服務，在進行任何操作前，了解各項服務的功能會很有幫助：

• immich-server (ghcr.io/immich-app/immich-server, container immich_server) — 提供 API 與 Web UI，監聽 port 2283。它會將您的上傳內容掛載至 /data。
• immich-machine-learning (ghcr.io/immich-app/immich-machine-learning, container immich_machine_learning) — 負責 CLIP 搜尋與臉部辨識。它會在 model-cache volume 中快取已下載的模型。此服務非常消耗記憶體。
• database (container immich_postgres) — 使用 VectorChord 向量擴充功能的 Postgres，用於驅動相似度搜尋。映像檔標籤已在 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) — 用於工作隊列 (job queues) 的 Valkey/Redis 實例。

Step 3: 設定 .env — 存放照片與資料庫的位置

開啟 .env 並設定四項參數。標記線以下的內容請保持原樣。

# 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 應指向您的儲存空間。若之後會掛載資料磁碟，請一開始就將此項設為該磁碟的掛載路徑，否則後續移動會導致縮圖與資產路徑失效。DB_DATA_LOCATION 必須位於本地磁碟：官方文件明確指出，將 Postgres 放在 NFS 或 SMB 共享目錄會導致資料損毀。若在 DB_PASSWORD 中僅使用英數字，可避免連線字串轉義（escaping）引發的錯誤。

Step 4: 首次執行與建立管理員使用者

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

正確結果應顯示四個容器，皆為 running 且最終狀態為 healthy：

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

首次 up 會下載數 GB 的 images，請耐心等待。使用 sudo docker compose logs -f immich-server 監控進度；準備就緒後，伺服器會記錄正在監聽 port 2283。接著請在瀏覽器開啟 http://YOUR_SERVER_IP:2283。首次訪問會顯示 Getting Started 精靈 — 您建立的第一個帳號即為管理員。請設定強密碼；此帳號擁有伺服器設定、使用者管理以及後續所需的 ML configuration 權限。

Step 5: 行動裝置 App 與背景備份

從 App Store 或 Play Store 安裝 "Immich"。在登入畫面中，系統會要求輸入 Server Endpoint URL。請輸入包含協定（scheme）的完整 URL，例如 https://photos.example.com（App 會自動附加 /api）。使用您剛建立的帳戶登入，接著開啟 App 的 Backup 畫面，選擇要備份的相簿（通常選擇 Camera 與 Screenshots），並啟用 Background backup。iOS 的背景備份會受到作業系統限制，前景上傳會持續執行，而背景上傳則會在作業系統允許時進行。

這是使用者最常遇到問題的地方，在嘗試解決 App 問題前，請先閱讀 Step 6。

Step 6: 使用反向代理進行 HTTPS 傳輸 — 以及完整 URL 規則

行動裝置 App 強烈要求使用 HTTPS。請在 2283 埠口前架設反向代理，並在此處進行 TLS 終止。若您已運行多個容器，使用 Traefik 為多個 Docker 應用程式提供自動 TLS 是最整潔的方案 — 僅需一個 label 區塊即可將 photos.example.com 路由至 immich-server 容器，並自動取得憑證。若您偏好使用 nginx，請參考 使用 Certbot 與 nginx 搭配 Let's Encrypt 指南來取得憑證與 proxy_pass http://127.0.0.1:2283; 區塊。針對 Immich，有一項代理設定至關重要：請調高上傳大小限制，因為手機影片檔案很大。在 nginx 中，這是在 server 區塊內的 client_max_body_size 50000M; — 預設值 1 MB 會導致影片上傳時出現 413 Request Entity Too Large 錯誤。

App 執行的規則：端點必須可連線，且在實際應用中必須使用 HTTPS。若使用 http:// 端點，或直接使用未包含埠口的 IP，會導致「App 無法連線至伺服器」的錯誤 — 下文將針對此特定錯誤進行說明。

Step 7: External libraries vs uploads — 匯入現有的照片目錄

照片進入 Immich 有兩種方式，兩者性質不同。

• Uploads 是由 Immich 管理的資產。應用程式或網頁上傳器會將檔案複製到 UPLOAD_LOCATION。Immich 可以對這些檔案進行重新命名、移動或刪除。
• External libraries 是對已存在於伺服器資料夾中檔案的唯讀匯入，例如舊有的 Pictures 目錄或 NAS 匯出檔。Immich 會在原位進行索引並顯示於時間軸，但絕不會修改或刪除原始檔案。

若要匯入現有的目錄，請將該目錄以唯讀模式掛載至伺服器容器中。編輯 immich-server: 下的 docker-compose.yml 並新增一個 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 重新建立容器，接著在 Web UI 中前往個人頭像 → Administration → External Libraries → Create Library，選擇擁有者使用者，在 Folders 下點擊 Add，並輸入容器內的路徑 — 請輸入 /mnt/media/photos，而非主機路徑 /srv/photos。點擊 Scan。使用主機路徑而非容器路徑是使用 External Library 時最常見的錯誤；這會導致掃描結果為空，並回報零個資產。

Step 8: Immich 要求的升級規範

這是決定 Immich 運行穩定或毀損的關鍵。Immich 的更新速度極快，且不提供舊版本修復（backport）或支援降版本（downgrade）。若盲目追蹤浮動的 v3 標籤，最終會導致資料庫毀損。請遵守以下規範：

1. 固定版本。 將 IMMICH_VERSION 設定為具體的標籤（例如 v3.0.2），不要使用會自動抓取最新 v3.x 的浮動標籤 v3。
2. 每次升級前務必閱讀 Release Notes。 所有的重大變更（Breaking changes）——特別是資料庫或 vector-extension 的變更——都會在其中說明。v3.0 是一個典型的例子：它直接移除了 pgvecto.rs，因此使用舊版擴充套件的使用者，必須先完成 VectorChord 遷移（自 v1.133 起引入）才能升級。
3. 先備份資料庫（見 Step 9）。這是必要步驟，若 Release Notes 特別提到資料庫變更時，更需格外小心。
4. 同時下載新的 compose file。 IMMICH_VERSION 僅固定了 server 與 ML 的 image。Postgres 的 image 是透過 docker-compose.yml 內部的 digest 來固定的，因此若新版本需要更新的資料庫擴充套件，也會隨附新的 compose file。請重新下載這兩項 release 資產，重新套用您的 .env 設定值，然後再進行升級。
5. 同步更新行動裝置用戶端。 Server 僅支援對應的主版本（major version），而 App 僅支援當前與前一個主版本。若 Server 版本領先於 App，手機會顯示 Your app major version is not compatible with the server!，直到您更新 App 為止。因此，最穩妥的做法是先更新 App。

當您準備好新檔案後，實際指令如下：

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

Step 9: Backups — 包含資料庫 dump 與原始檔案，並進行測試

Immich 的備份包含兩個部分，缺一不可。database 儲存相簿結構、人臉、搜尋索引以及資產與檔案間的對應關係。originals directory 則儲存實際的相片檔案。若只還原其中之一，結果會是只有相片卻無組織結構，或是只有空殼卻找不到檔案。

請在 Postgres container 內部使用 pg_dump 進行資料庫 dump —— 僅針對 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

接著使用 restic、rsync 或 borg 備份 UPLOAD_LOCATION —— 包含整個 /opt/immich/library 樹狀目錄，特別是其 library/、upload/ 與 profile/ 子目錄，並將其傳送到另一台機器或 object storage。請先備份資料庫，再備份檔案，以確保 dump 內容不會引用尚未完成檔案備份的相片。外部 library 需在原始來源處另行備份；Immich 並不擁有這些檔案。

接下來是大家最常忽略的步驟：測試還原。 還原作業必須在一個全新的 stack 上執行，該伺服器從未啟動過，且使用的 Postgres image 必須具備與 dump 相容的 vector extension —— 這正是為何絕對不能隨意變更 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

若使用 VectorChord 資料庫，則必須執行 sed 對 search_path 的改寫 —— 若略過此步驟，還原程序會在執行中途中止。當 stack 重新啟動且 originals 已就緒時，請開啟 web UI：若相片與相簿皆正確顯示，代表備份成功。若從未執行過此測試，你擁有的不是備份，而是希望。

Failure modes, with the strings you will see

ML container 被 OOM-killed。 sudo docker compose logs immich-machine-learning 突然結束，docker compose ps 顯示 Restarting，且 exit code 為 137。sudo dmesg | grep -i oom 確認了此問題：Out of memory: Killed process ... (python3)。隨後 search 與 face 作業會停滯。原因為模型所需的 RAM 不足。依序進行修復：新增 swap (Step 1)；增加 VPS 的 RAM；若真的無法增加，請至 Administration → Settings → Machine Learning Settings 關閉 Smart Search 與 Facial Recognition 以停用 ML —— 您可以保留 backups 與 albums，但會失去 search-by-content 功能。從 compose file 中移除 immich-machine-learning service 亦有相同效果。

升級後 Postgres 無法啟動。 伺服器 log 會出現如 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. 的循環行 —— 或在舊版 stack 中顯示 The pgvecto.rs extension is not available in this Postgres instance.。原因為資料庫 image 的 extension version 低於資料已升級的版本，這通常是因為手動修改 image tag，或將較新版本的 dump 還原至較舊的 image。修復方法是使用匹配的 Postgres image —— 請從與資料庫版本一致的 release 中取得 compose file，請勿降級，且僅能還原至相容的 image。

行動裝置 App 無法連線至伺服器。 輸入 URL 後，登入畫面顯示 connection error / Server is not reachable。有三種可能原因：您輸入了 http://，但 proxy 僅提供 https://；您直接連線至 backend 但未加上 port，導致系統嘗試連線至 example.com (port 443) 而非 example.com:2283；或者 reverse proxy 未轉發 /api。修復方法是輸入完整的 https://photos.example.com URL，並先確認其能在手機瀏覽器中正常載入。若瀏覽器正常但 App 無法連線，代表 proxy 正在剝離 path，或是憑證為 self-signed —— App 會拒絕不被信任的憑證。

匯入過程中磁碟空間不足。 上傳開始失敗、縮圖變為空白，且 log 顯示 ENOSPC: no space left on device 或 Postgres 顯示 could not extend file ... No space left on device。df -h 顯示 UPLOAD_LOCATION volume 使用率達 100%。這就是為何在匯入大型 library 前必須規劃好磁碟容量。修復方法是掛載較大的 volume，停止 stack，將 UPLOAD_LOCATION 移至該 volume，更新 .env 並重新啟動 —— 或者若您的供應商支援，直接擴展現有的磁碟。若磁碟滿載，Postgres 可能會卡死，因此在判定為資料損毀前，請先清理空間並重啟資料庫 container。

FAQ

Immich 需要多少 RAM 與磁碟空間？

Immich 的官方需求為至少 6 GB RAM，建議配置為 8 GB。若包含 swap，小規模資料庫的實際最低門檻為 4 GB；無論如何都請配置 swap，因為 machine-learning container 會造成資源突發需求。磁碟空間方面，請預留完整資料庫大小加上約 10–20% 的空間，用於存放產生的縮圖與預覽檔，並請儲存於本地端磁碟——切勿將 Postgres data directory 放在網路共享裝置上。若您正在評估其他服務，可參考 2026 年自架服務指南 來比較 Immich 的資源佔用。

我可以在沒有 GPU 的情況下執行 Immich 嗎？

可以。machine-learning container 可於 CPU 上正常執行；GPU 僅能加速 smart-search indexing 以及（在選用正確映像檔的情況下）video transcoding。若使用 CPU，大型資料庫的初始索引可能需在背景執行數小時，但這不會影響備份或瀏覽功能。若您的設備完全無法負擔 ML 運算，可以在 admin settings 中停用 Smart Search 與 Facial Recognition，並保留其他功能。

如何安全地升級 Immich？

請將 IMMICH_VERSION 固定在特定標籤（如 v3.0.2），每次升級前請閱讀 release notes，並先備份資料庫。由於 Postgres image 是在 docker-compose.yml 中被固定，而非透過 IMMICH_VERSION，因此請從目標版本重新下載 compose file 與 example.env 並重新套用您的設定值，接著執行 docker compose pull && docker compose up -d。切勿讓版本處於浮動狀態——Immich 包含破壞性變更（breaking changes）且不支援降級（downgrades）。

我具體需要備份什麼？

需同時備份兩項內容：immich 資料庫的 pg_dump 以及整個 UPLOAD_LOCATION originals 目錄。資料庫儲存相簿、人臉以及資產與檔案的映射關係；目錄則儲存實際照片。還原時需要這兩者，外加一個具備相容 vector extension 的資料庫映像檔。請先進行資料庫 dump，再進行檔案複製，並至少在測試機上進行一次還原測試——未經測試的備份不具備備份效力。

如何匯入現有的照片資料夾？

將該資料夾以唯讀方式掛載至 immich-server container 作為額外 volume（例如 - /srv/photos:/mnt/media/photos:ro），重新建立 container，接著在 Administration → External Libraries 建立一個 library 並新增 container 路徑 /mnt/media/photos。Immich 會直接對現有檔案進行索引，絕不會修改或刪除檔案。最常見的錯誤是輸入了 host path 而非 container path，這會導致掃描結果為空。