Immich 自架需要多少 RAM？安全升級與修復

你要建置的內容

Immich 是一套自架的相片與影片備份服務，可真正取代 Google Photos。它提供手機應用程式，能在背景上傳相機膠卷，並具備時間軸、相簿、人臉辨識及機器學習搜尋功能。即使你從未加上標籤，也能搜尋「海灘」或特定人物。你可以在自有的 VPS 上執行它，原始檔案會保留在你的磁碟中，也不會有人掃描這些檔案來向你推銷商品。如果你仍在 Immich 與另一個明顯的候選方案之間評估，我們的 PhotoPrism 與 Immich 比較會並列比較兩者的最低 RAM 需求、手機應用程式及備份指令。

安裝內容是專案自有 Docker Compose 檔案中的 4 個容器。這個部分只需 10 分鐘。其餘問題才是本指南的難點：在資源較小的主機上，機器學習容器非常耗用記憶體；原始檔案會快速占滿磁碟；行動應用程式拒絕連線至純 HTTP 伺服器；而 Immich 經常發布會造成相容性問題的變更，粗心的 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 RAM，也請加入 swap。
• 磁碟：請依整個媒體庫的容量估算，並預留額外空間。 系統會完整複製原始檔案，Immich 也會產生縮圖與預覽圖片，通常還會增加約 10–20%。200 GB 的相片集合需要 300 GB 的 volume。Postgres 的容量需求相較之下很小。
• CPU：任何現代 KVM VPS 都足以使用，但在 CPU 上執行 ML 的速度較慢。 大量匯入資料的智慧搜尋索引可能會在背景執行數小時。這是正常情況，不需要 GPU。
• 指向 VPS 的網域名稱。 行動應用程式強烈偏好 HTTPS endpoint，因此前方需要設定 reverse proxy。這與 使用 Docker、TLS 與備份自架 Nextcloud 的架構相同；Immich 是該檔案伺服器的相片對應方案。
• 已安裝 Docker 與 Compose plugin。 請依照 Docker Compose 基礎指南 的說明，從 Docker 自有的 apt repository 安裝 Docker Engine 與 Compose v2 plugin。

步驟 1：先新增 swap

小型 VPS 上最常見的 Immich 失敗原因，是 ML 容器因記憶體不足而被 OOM-kill。先為 kernel 提供可用的 swap 空間。

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 機器上建立索引的過程中終止。

步驟 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

這些檔案來自標記的 release，因此映像檔參照會相互對應。compose 檔案定義了 4 個服務。在進行任何操作前，先了解各服務的用途：

• immich-server（ghcr.io/immich-app/immich-server，容器 immich_server）提供 API 與 Web UI，監聽連接埠 2283。它會將您的上傳內容掛載至 /data。
• immich-machine-learning（ghcr.io/immich-app/immich-machine-learning，容器 immich_machine_learning）提供 CLIP 搜尋與臉部辨識功能。它會將下載的模型快取在 model-cache volume 中。這是最耗用記憶體的服務。
• database（容器 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（容器 immich_redis）執行 Valkey/Redis 執行個體，供工作佇列使用。

步驟 3：設定 .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 應指向容量較大的磁碟；如果之後會掛載資料磁碟區，請一開始就將它設定為該磁碟區的掛載路徑，因為事後搬移代表必須搬移縮圖並更新資產路徑。DB_DATA_LOCATION 必須位於本機磁碟：Postgres 在 NFS 或 SMB 共用上執行會造成資料損毀，文件也已明確說明這一點。DB_PASSWORD 只使用字母和數字，可避免一類連線字串跳脫錯誤。

步驟 4：首次執行並建立管理員使用者

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

正確結果應為 4 個容器，全部處於 running 狀態，最後顯示為 healthy：

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

首次執行 up 會下載數 GB 的映像檔，因此請耐心等候。使用 sudo docker compose logs -f immich-server 監看進度；伺服器就緒後，日誌會記錄其正在監聽連接埠 2283。接著在瀏覽器中開啟 http://YOUR_SERVER_IP:2283。首次造訪時會顯示 開始使用 精靈；建立的第一個帳戶就是管理員帳戶。請設定強式密碼；此帳戶可管理伺服器設定、使用者管理，以及稍後需要的 ML 設定。

步驟 5：行動應用程式與背景備份

從 App Store 或 Play Store 安裝「Immich」。在登入畫面中，系統會要求輸入 Server Endpoint URL。輸入包含 scheme 的完整 URL，例如 https://photos.example.com（應用程式會自行附加 /api）。使用剛建立的帳戶登入，然後開啟應用程式的 Backup 畫面，選取要保護的相簿（通常是 Camera 和 Screenshots），並啟用 Background backup。iOS 會限制背景備份的頻率；前景上傳一律會執行，背景上傳則會在作業系統允許時執行。

這正是許多人卡住的地方，因此請先閱讀步驟 6，再處理應用程式的問題。

步驟 6：透過反向代理使用 HTTPS，以及完整 URL 規則

行動版應用程式確實需要 HTTPS。請在連接埠 2283 前方設定反向代理，並在該處終止 TLS。若您已執行多個容器，使用自動 TLS 為多個 Docker 應用程式提供服務的 Traefik 是最整潔的選項；只要一個標籤區塊，就能將 photos.example.com 轉送至 immich-server 容器，並代為取得憑證。若您偏好 nginx，使用 Certbot 和 nginx 設定 Let's Encrypt 的指南會協助您取得憑證與 proxy_pass http://127.0.0.1:2283; 區塊。

建立代理後，新增下一個服務通常只需設定新的子網域。因此，像 適用於 Jellyfin 的 90 年代影像出租店外觀 Halcyon 這類媒體前端，就能與 Immich 共存於同一台主機。讓 Codex 和 Claude Code 共用單一 API 的自架 HarnessRouter 也是如此。它刻意繫結至 loopback，只有在前方代理終止 TLS 後才可連線。因此，將子網域指向它之前，請先變更預設登入資訊。

不過，並非每個容器都需要公開主機名稱。像 自架的 open-kritt 安全性掃描器 這類僅供管理員使用的工具，最好完全不要放在代理後方。只有在偶爾開啟其 UI 時，才透過 SSH tunnel 存取。其他服務則因為根本不使用 HTTP 而不適合代理。自架的 RustDesk relay server 是最明顯的例子。它會監聽數個原始 TCP 與 UDP 連接埠，需要設定防火牆規則，而不是建立子網域。

Immich 有一項代理設定需要特別注意：請提高上傳大小限制，因為手機影片通常很大。在 nginx 中，請在 server block 內設定 client_max_body_size 50000M;。預設的 1 MB 會以 413 Request Entity Too Large 拒絕影片上傳。

應用程式強制執行的規則是：端點必須可連線，實務上也必須使用 HTTPS。http:// 端點，或省略連接埠的直接 IP 位址，會導致「應用程式無法連線至伺服器」；下方會以具名故障情境說明此問題。

步驟 7：外部程式庫與上傳內容：匯入現有相片目錄

相片進入 Immich 有兩種方式，兩者並不相同。

• 上傳內容是由 Immich 管理的資產。應用程式或網頁上傳工具會將檔案複製到 UPLOAD_LOCATION。Immich 可以重新命名、移動及刪除這些檔案。
• 外部程式庫是唯讀匯入。檔案原本已存在於伺服器上的資料夾、舊有的 Pictures 目錄或 NAS 匯出內容中。Immich 會在原位置建立索引，並將檔案顯示在時間軸中，但不會修改或刪除原始檔案。

若要匯入現有目錄，請以唯讀方式將其掛載至伺服器容器。編輯 docker-compose.yml（位於 immich-server:）並新增磁碟區：

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

:ro 可確保 Immich 絕對無法修改原始檔案。使用 sudo docker compose up -d 重新建立容器，然後在網頁介面中前往你的頭像 → Administration → External Libraries → Create Library，選取擁有者使用者，按一下 Folders 下方的 Add，並輸入容器路徑 /mnt/media/photos，而不是主機路徑 /srv/photos。按一下 Scan。使用主機路徑而非容器路徑，是外部程式庫最常見的錯誤；掃描會找不到任何內容，並顯示資產數量為 0。

步驟 8：Immich 要求的升級紀律

這是正常運作的 Immich 與損壞的 Immich 之間的關鍵差異。Immich 發布速度快，且不會回移修正，也不支援降級。盲目追蹤浮動的 v3 標籤，最終會導致資料庫損壞。相同的「固定版本後閱讀版本說明」習慣，也適用於伺服器上所有長期運作的容器。因此，自架的 KiroCrew agent 會固定在一個已知可正常運作的標籤，而不是讓它在下一次重新啟動時自行變更版本。具體紀律如下：

1. 固定版本。 將 IMMICH_VERSION 設為具體標籤，例如 v3.0.2，不要使用會永遠拉取最新 v3.x 的浮動 v3。
2. 每次升級前都要閱讀版本說明。 其中會列出重大變更，尤其是資料庫或向量擴充功能的變更。v3.0 版本就是明顯的例子：該版本直接移除 pgvecto.rs，因此仍使用舊擴充功能的使用者，必須先完成 VectorChord 遷移（早在 v1.133 引入），才能升級。
3. 先備份資料庫（步驟 9）。任何時候都應如此；版本說明提到資料庫時，更必須如此。
4. 一併取得新的 compose 檔案。 IMMICH_VERSION 只會固定 server 與 ML 映像檔。Postgres 映像檔的 digest 是在 docker-compose.yml 內部固定的，因此需要較新資料庫擴充功能的版本會隨附新的 compose 檔案。重新下載兩個版本資產，重新套用你的 .env 值，然後再升級。
5. 在相近時間更新行動用戶端。 server 只支援相符的 major version，而 app 支援目前與前一個 major version。若 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

步驟 9：備份資料庫傾印與原始檔案，並測試還原

Immich 的備份包含兩個部分，缺一不可。資料庫儲存相簿結構、人臉資料、搜尋索引，以及資產對應檔案的關係。原始檔案目錄則儲存實際的相片。只還原其中一項，結果不是相片失去整理結構，就是只剩指向遺失檔案的空殼。

在 Postgres 容器內使用 pg_dump 傾印資料庫，指定 immich 資料庫，而不是整個叢集：

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 將其備份到另一台機器或物件儲存。先備份資料庫，再備份檔案，這樣傾印內容就不會參照檔案備份尚未複製的相片。外部媒體庫應在其實際來源處另外備份；這些媒體庫不由 Immich 管理。

接下來是所有人都會跳過的部分：測試還原。 還原必須在全新的 stack 上執行，且該 stack 的 server 從未啟動過；同時，Postgres image 的 vector extension 必須與傾印內容相容。因此，絕對不要自行臨時決定 DB image tag。在使用相同 compose 和 .env 的測試主機上，清除所有舊狀態，只啟動資料庫，然後載入傾印：

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 資料庫中，search_path 的 sed 改寫不是選用項目。省略後，還原會在中途中止。將原始檔案放回原位並重新啟動 stack 後，開啟 Web UI：如果相片和相簿都存在，表示備份可正常運作。如果從未執行過這項測試，就不能算有備份，只能算是抱持希望。

失敗模式與您會看到的字串

ML container 被 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)。接著，搜尋與人臉辨識工作會停滯。原因是模型需要的 RAM 不足。請依序採取以下修正措施：新增 swap（Step 1）；為 VPS 增加 RAM；如果確實無法增加，則在 Administration → Settings → Machine Learning Settings 中關閉 Smart Search 與 Facial Recognition，停用 ML。這樣會保留備份與相簿，但無法再依內容搜尋。從 compose file 移除 immich-machine-learning service 也會產生相同效果。

升級後 Postgres 拒絕啟動。 server 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.。原因是 database image 的 extension version 比資料升級後使用的版本舊。這幾乎都是手動編輯 image tag，或將較新的 dump 還原到較舊的 image 所造成。修正方式是使用相符的 Postgres image，從與資料庫相符的 release 取得 compose file。不要降級，且只還原到相容的 image。

行動應用程式無法連線到 server。 輸入 URL 後，登入畫面會顯示連線錯誤／Server is not reachable。常見原因有 3 個：您輸入了 http://，但 proxy 只提供 https://；您直接連線到 backend，卻省略了 port，因此它嘗試使用 example.com（port 443），而不是 example.com:2283；或 reverse proxy 沒有轉送 /api。請輸入完整的 https://photos.example.com URL，並先在手機瀏覽器中確認可以載入。如果瀏覽器可以運作，但應用程式無法連線，可能是 proxy 移除了 path，或憑證是 self-signed；應用程式會拒絕不受信任的憑證。

匯入中途磁碟空間用盡。 上傳開始失敗，縮圖變成空白，log 會顯示 ENOSPC: no space left on device，或 Postgres 顯示 could not extend file ... No space left on device。df -h 會顯示 UPLOAD_LOCATION volume 已達 100%。因此，在匯入大型資料庫前，應先估算所需磁碟空間。復原方式是連接容量更大的 volume，停止 stack，將 UPLOAD_LOCATION 移至該 volume，更新 .env，再重新啟動；如果 provider 支援，也可以擴充現有磁碟。Postgres 在磁碟空間用盡時可能會卡住，因此請先清出空間並重新啟動 database container，再判斷是否損毀。

FAQ

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

Immich 官方要求至少 6 GB RAM，建議使用 8 GB；對小型相片庫而言，搭配 swap 的 4 GB 是實際可行的下限。無論採用哪種配置，都應設定 swap，因為 machine-learning container 會產生突發的資源用量。磁碟空間方面，請以完整相片庫大小為基準，另外預留約 10–20% 用於產生縮圖與預覽，並使用本機儲存空間；絕對不要將 Postgres data directory 放在 network share 上。如果你還在評估要執行哪些服務，2026 年適合自行託管的服務指南會將 Immich 的資源需求與其他服務並列比較。

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

可以。machine-learning container 在 CPU 上即可正常執行。GPU 只會加快 smart-search 索引建立，以及在使用正確 image variant 時加速 video transcoding。在 CPU 上，大型相片庫的初始索引可能需要在背景執行數小時，但不會阻礙備份或瀏覽。如果你的主機太小，無法執行 ML，可以在管理設定中停用 Smart Search 和 Facial Recognition，其他功能仍可保留。

如何安全地升級 Immich？

將 IMMICH_VERSION 固定為明確的 tag，例如 v3.0.2；每次升級前閱讀 release notes，並先備份資料庫。由於 Postgres image 是在 docker-compose.yml 中固定，而不是透過 IMMICH_VERSION 固定，因此請從目標 release 重新下載 compose file 和 example.env，重新套用你的設定值，然後執行 docker compose pull && docker compose up -d。絕不要讓版本在無人管理的情況下浮動。Immich 會發布不相容變更，且不支援降級。

確切需要備份哪些內容？

需要一併備份兩項內容：immich 資料庫的 pg_dump，以及完整的 UPLOAD_LOCATION originals directory。資料庫包含相簿、人臉和資產至檔案的對應關係；該目錄則包含實際相片。還原時需要這兩者，以及具備相容 vector extension 的 database image。先執行資料庫 dump，再複製檔案，並至少在測試主機上完整測試一次還原。未經測試的備份不算備份。

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

將資料夾以唯讀方式作為額外 volume 掛載至 immich-server container，例如 - /srv/photos:/mnt/media/photos:ro，重新建立 container，然後在 Administration → External Libraries 中建立 library，並加入 container path /mnt/media/photos。Immich 會直接在原位置建立檔案索引，絕不修改或刪除檔案。最常見的錯誤是輸入 host path，而不是 container path，導致掃描找不到任何內容。