Immich 伺服器硬體需求：RAM 與磁碟空間建議

Immich 需要多少記憶體？

Immich 官方文件記載的最低記憶體 (RAM) 需求為 6 GB，建議配置則為 8 GB；CPU 核心數最低需求為 2 核心，建議配置為 4 核心以確保運作順暢。此數值涵蓋整個堆疊，因為 Immich 是由四個容器組成的應用程式，而非單一程式。瀏覽已匯入的圖庫資源消耗極低，記憶體主要用於匯入作業，且大部分消耗集中在一個可選擇關閉的容器上。

[
  {
    "label": "Documented minimum",
    "ram_gb": 6,
    "cpu_cores": 2
  },
  {
    "label": "Documented recommended",
    "ram_gb": 8,
    "cpu_cores": 4
  }
]

上述數據為截至 2026 年 8 月 Immich 需求頁面所發布的規格。這僅是規模建議，並非軟體啟動時的檢查機制。Immich 在低於此規格的環境下仍可啟動。在較小型的伺服器上，差異在於背景任務的完成狀況，以及記憶體耗盡時匯入作業的反應。

目前存在一個明確的硬性限制。Immich 3 版及後續版本在 amd64 架構主機上需要 x86-64-v2 CPU，這涵蓋了約 2012 年後販售的大多數處理器。若硬體過舊，容器將無法啟動，而非僅是執行速度緩慢。

若您尚未開始安裝，請先參考 在 VPS 上使用 Docker Compose 完整安裝 Immich，完成後再回到此處評估伺服器規格。

記憶體配置：四個容器

官方的 Compose 檔案啟動了四個服務。每個服務的記憶體需求各異，因此單一總數無法反映實際使用狀況。

immich-server 負責提供網頁介面與 API，同時執行背景工作處理程序（workers）。該容器內運行了兩個 worker。api 負責回應瀏覽器與行動裝置應用程式的請求。microservices 負責處理佇列，包含縮圖生成與影片轉碼。變數 IMMICH_WORKERS_INCLUDE 與 IMMICH_WORKERS_EXCLUDE 可將這兩項任務拆分為獨立容器；透過此方式，您可以為高負載的任務設定記憶體上限，而不影響負責相片服務的容器。

database 是內建 VectorChord 擴充功能的 PostgreSQL 14 映像檔。它儲存了所有元資料以及每個資產的搜尋向量。Immich 文件針對此服務設定了堆疊中唯一的明確下限：若您套用了 Docker 資源限制，資料庫至少需要 2 GB 記憶體。同一份文件亦指出，資料庫必須存放於本機 SSD 儲存空間，絕不可使用任何網路共享磁碟，因為向量與索引查詢屬於小型隨機讀取，網路磁碟會使每次查詢都產生額外的來回延遲。若您的方案選擇取決於此，VPS 上的 NVMe 與 SATA SSD 儲存差異在此堆疊中的影響比其他任何部分都更為關鍵。

redis 執行 Valkey 映像檔並負責維護工作佇列。它是四個服務中記憶體佔用最小的，因為它僅儲存工作紀錄，而非相片資料。

immich-machine-learning 是決定方案規模的服務。它會載入用於智慧搜尋、人臉偵測與文字辨識的模型，且已載入的模型會常駐於記憶體中。MACHINE_LEARNING_MODEL_TTL 的預設值為 300，代表若五分鐘內無請求，模型將會被卸載，並在下次請求時重新從 /cache 磁碟區讀取。在進行大量匯入時，處理間隔通常不會超過五分鐘，因此模型會從第一個資產處理到最後一個，始終保持載入狀態。

匯入期間的變更

閒置狀態的 Immich 非常安靜。匯入作業是小型伺服器最容易崩潰的環節，因為上傳單一資產會觸發一連串工作佇列，且多個佇列會同時執行。

中繼資料提取僅需讀取檔案標頭，負載較輕。縮圖生成則較為吃重。Immich 會為每個資產產生三個縮圖輸出：一個模糊的 thumbhash 預留位置、一個 WebP 預覽圖以及一個 JPEG 縮圖，若偵測到人臉，還會額外產生一個縮圖。每一項工作都會解碼影像，而工作並發數（concurrency）決定了同時解碼的數量。並發數是將單一工作成本放大為全伺服器負載的乘數，這也是為何 Immich FAQ 將其列為資源受限機器首要調降的設定。請在 Administration, Settings, Job Settings 中，將高負載佇列的並發數設為 1。

影片資產會增加轉碼作業。每個轉碼工作都是獨立的 FFmpeg 程序，擁有各自的記憶體佔用，並會耗盡您允許其使用的所有 CPU 執行緒。

智慧搜尋會將每個新資產傳送至機器學習容器，以計算一個嵌入向量（embedding vector）。人臉偵測則會對同一張影像執行第二個模型。在首次匯入現有照片庫時，這兩個佇列會針對您擁有的每個資產執行，耗時數小時。這是整個安裝過程中記憶體壓力最大的時刻，且僅會發生一次。

為什麼人臉與物件辨識最耗用 RAM

處理人臉涉及兩項工作。人臉偵測會在機器學習容器中執行模型並找出邊框。人臉辨識隨後會將這些偵測結果分組為特定人物，此步驟會查詢 Postgres 中的向量索引。因此，龐大的圖庫會依序對這兩項服務造成壓力：偵測執行時由模型容器負擔，分組執行時則由資料庫負擔。

有四項設定會改變機器學習容器的記憶體佔用量。

• 人臉模型。Immich 預設搭載 buffalo_l，而 FAQ 建議小型伺服器使用 buffalo_s。後者為較小的模型，佔用的記憶體較少且執行速度較快，代價是對於小型或側面人臉的辨識準確度較低。
• 工作執行緒數量 (Worker count)。MACHINE_LEARNING_WORKERS 預設值為 1。每個 worker 都是獨立的行程，會載入各自的模型副本，因此將其調高至 2 大約會使常駐模型記憶體需求翻倍。除非記憶體充裕，否則請維持在 1。
• 批次大小 (Batch size)。MACHINE_LEARNING_MAX_BATCH_SIZE__FACIAL_RECOGNITION 限制了同時處理的人臉數量。一個批次會同時保留在記憶體中，因此包含四十張人臉的團體照比單人肖像照更耗用資源。
• 啟用的模型類型。智慧搜尋、人臉偵測與文字辨識各自會載入專屬模型。若在 Administration, Settings, Machine Learning Settings 中關閉不使用的功能，即可徹底釋放其記憶體，而非僅在匯入期間釋放。

此外還有 MACHINE_LEARNING_MODEL_ARENA，其文件說明該設定預先配置 CPU 記憶體以避免碎片化，且預設為開啟。請最後再調整此項。其效果取決於底層的記憶體配置器，因此評估該設定的唯一可靠方式，是觀察調整前後的 docker stats。

三種運作設定檔：2 GB、4 GB 與 8 GB

[
  {
    "label": "2 GB VPS",
    "server_limit_mb": 768,
    "db_limit_mb": 768,
    "ml_limit_mb": 0,
    "redis_limit_mb": 128,
    "notes": "machine learning container removed"
  },
  {
    "label": "4 GB VPS",
    "server_limit_mb": 1024,
    "db_limit_mb": 1280,
    "ml_limit_mb": 1024,
    "redis_limit_mb": 192,
    "notes": "machine learning on, job concurrency 1, buffalo_s"
  },
  {
    "label": "8 GB VPS",
    "server_limit_mb": 2048,
    "db_limit_mb": 2048,
    "ml_limit_mb": 2560,
    "redis_limit_mb": 256,
    "notes": "everything on at default settings"
  }
]

請將這些數值視為輸入至 Compose 的限制值，而非 Immich 實際使用的記憶體量。限制值即為上限。它不會預先保留資源，也不會讓服務變小。它決定了當伺服器記憶體耗盡時，核心（kernel）該終止哪個服務；由您來做此決策，遠比交給核心的評分機制來得可靠。

2 GB 伺服器：移除機器學習容器

2 GB 低於官方建議的 6 GB 最低需求，因此這是一種妥協，必須明確指出。請註解掉 docker-compose.yml 中的整個 immich-machine-learning 服務，或者讓它保持執行，並在「管理」（Administration）、「設定」（Settings）、「機器學習設定」（Machine Learning Settings）中停用所有模型。移除容器是較徹底的做法，因為即使停用模型，Python 程序仍會駐留在記憶體中。

您仍可使用上傳、相簿、分享、行動裝置備份、縮圖，以及依日期、地點與檔名搜尋的功能。您將失去依描述搜尋、自動將臉孔分組為人物，以及圖片內文字辨識的功能。

這四項限制總計約 1.7 GB，留給主機約 300 MB 的空間。請注意，資料庫的 768 MB 限制低於官方建議的 2 GB 下限。這正是 2 GB 規格下必須做的妥協，也是為何 Postgres 在此環境中最容易被核心終止的原因。

最先崩潰的通常是匯入程序，而非瀏覽功能。當照片庫匯入完成後，數萬張照片的瀏覽體驗尚可接受，因為頁面載入僅涉及元數據查詢與檔案讀取。若在同一台機器上進行大量影片匯入，系統將會使用 swap，因為轉碼與縮圖佇列會同時佔用記憶體。請將所有繁重佇列的並行數（concurrency）設為 1，並新增 swap 檔案。

4 GB 伺服器：開啟機器學習，並限制單一任務並行

4 GB 是開啟臉孔與物件辨識功能的最小規格。請將機器學習容器限制在 0 MB，將臉孔辨識切換為 buffalo_s，並將縮圖生成、臉孔偵測與智慧搜尋的任務並行數設為 1。

對現有照片庫進行首次掃描可能需耗時數小時，若照片庫龐大，甚至可能超過一天。這是 CPU 瓶頸而非記憶體瓶頸，因此增加 RAM 並無法縮短時間。

在此規格下，最先崩潰的通常是首次大量掃描期間的機器學習容器。若未設上限，它會隨著轉碼任務同時增長，導致核心終止兩者中佔用較大者。您會在 docker ps -a 中看到 Exited (137) 錯誤與容器重啟，且佇列進度會比您上次查看時更為落後。

8 GB 伺服器：官方建議規格

8 GB 搭配 4 核心符合 Immich 的官方建議，所有功能皆可使用預設值執行：智慧搜尋、臉孔偵測、文字辨識與轉碼，並維持預設並行數。照片庫超過十萬個項目在此規格下運作順暢，壓力會從記憶體轉移至磁碟速度，因為資料庫整天都在處理向量索引與元數據查詢。

無論如何，請務必設定限制值。在資源充足的機器上，限制值可防止單一失控的佇列拖垮資料庫。若您正在評估此規格與較小規格的成本，VPS 記憶體等級的實際成本通常顯示 8 GB 方案是省去調校麻煩的最經濟選擇。

如何透過 Compose 限制個別服務的記憶體用量

請勿編輯 docker-compose.yml。該檔案會在每次升級時被 wget 覆蓋。請將限制設定放入旁邊的 docker-compose.override.yml，docker compose 會自動將其合併。

services:
  immich-server:
    deploy:
      resources:
        limits:
          memory: 1024M
  immich-machine-learning:
    deploy:
      resources:
        limits:
          memory: 1024M
          cpus: '1.5'
  database:
    deploy:
      resources:
        limits:
          memory: 1280M
  redis:
    deploy:
      resources:
        limits:
          memory: 192M

docker compose up -d
docker stats --no-stream

docker stats 現在應顯示您設定的上限，而非主機的總記憶體量，並顯示於 MEM USAGE / LIMIT 欄位中。若限制欄位仍顯示主機總容量，代表覆蓋檔案未被讀取：請檢查檔名，並執行 docker compose config 查看合併後的結果。

若限制過低，會導致服務從緩慢變為崩潰，若容器開始循環重啟，請調高限制。關於運作機制的更多資訊，請參閱 在 Docker Compose 中設定個別服務的記憶體限制，其中包含為何 deploy 在 Swarm 之外也能配合 Compose v2 運作的說明。

如何關閉或遷移機器學習容器

在小型伺服器上，將此容器遷移至他處是提升效能最顯著的調整。Immich 支援將其部署於另一台機器。請在第二台主機（例如僅在晚間開機的桌上型電腦）上建立此檔案：

name: immich_remote_ml
services:
  immich-machine-learning:
    container_name: immich_machine_learning
    image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
    volumes:
      - model-cache:/cache
    restart: always
    ports:
      - 3003:3003
volumes:
  model-cache:

docker compose up -d
curl -s http://localhost:3003/ping

接著進入網頁介面的 Administration、Settings、Machine Learning Settings，點擊 Add URL 並輸入 http://<host>:3003。請確保兩台主機的版本一致，因為 Immich 文件指出版本不匹配會導致錯誤與不穩定。

該連接埠會以未加密方式將照片傳輸至另一台機器，因此請務必將其限制在私人網路內，或透過 兩台主機間的 WireGuard 通道 傳輸。切勿將 3003 埠暴露於網際網路。

若您認為常駐模型容器本身即為問題所在，在決定方案規模前，參考 PhotoPrism 與 Immich 在靜態資源運作上的差異 也是合理的評估方式。

Immich 媒體庫需要多少磁碟空間？

沒有單一的倍數計算方式，因為四種不同的項目會以四種不同的速率增長。以下是針對 50,000 張照片與 500 段短影片媒體庫的計算方式。

[
  {
    "label": "Originals: 50,000 photos at 4 MB",
    "gb": 200
  },
  {
    "label": "Originals: 500 videos at 120 MB",
    "gb": 60
  },
  {
    "label": "Thumbnails and encoded video at 15%",
    "gb": 39
  },
  {
    "label": "Postgres database",
    "gb": 3
  },
  {
    "label": "Machine learning model cache",
    "gb": 2
  }
]

200 GB 的照片與 60 GB 的影片僅為假設值。在購買任何硬體前，請先替換為您自己的平均值，因為影片才是決定此數值的關鍵：一分鐘的手機影片容量大於一百張照片。

find /srv/immich/upload -type f -printf '%s\n' \
  | awk '{n++; s+=$1} END {printf "%d files, %.1f MB average\n", n, s/n/1048576}'

39 GB 這一列是 Immich 唯一公開的比例：生成的縮圖與轉碼後的影片平均會增加媒體庫 10% 到 20% 的空間。這是一個範圍，取決於您有多少資產是需要為了瀏覽器相容性而重新編碼的影片。若媒體庫全為 JPEG 檔案，則會落在該範圍的下限。

資料庫約為 3 GB，這接近於固定成本。Immich 文件指出資料庫檔案通常為 1 到 3 GB，因為它們儲存的是元數據與搜尋向量，而非像素。模型快取為 2 GB，若您啟用多個模型或測試不同模型，此數值會隨之增長。FAQ 特別標註此容量會佔用空間，原因正是如此。

這五列加總後略高於 300 GB，因此 500 GB 的儲存空間留有增長餘裕，而 250 GB 則不足。請使用以下指令監控空間分配：

grep UPLOAD_LOCATION .env
du -sh /srv/immich/*

UPLOAD_LOCATION 下方共有六個資料夾。upload 與 library 存放原始檔案，thumbs 存放預覽圖與人臉縮圖，encoded-video 存放重新編碼後的副本，profile 存放頭像，backups 則存放自動產生的資料庫備份。只有 upload、library 與 profile 是不可取代的，因為其他所有檔案皆可從這些目錄重新生成。

有兩件事常讓使用者感到意外。刪除的資產會先進入垃圾桶，在清空垃圾桶前仍會佔用空間，因此大規模清理當天並不會釋放任何空間。此外，資料庫備份僅包含元數據，若沒有原始檔案，這些備份毫無價值：

docker exec -t immich_postgres pg_dump --clean --if-exists \
  --dbname=immich --username=postgres | gzip > /srv/backups/immich-dump.sql.gz

請將原始檔案的檔案層級副本同步至伺服器外部，這正是 從 VPS 使用 restic 備份至外部儲存空間 的用途。

轉碼使用 CPU，而非 RAM

增加 RAM 不會提升轉碼速度。Immich 使用 FFmpeg 進行轉碼，在一般的 VPS 上，每一幀影像皆由 CPU 進行解碼與編碼。即使在有硬體加速的情況下，Immich 的文件也指出僅有編碼過程會被加速，因此 CPU 仍需負責軟體解碼與色調映射（tone mapping）。

硬體加速需要額外的 hwaccel.transcoding.yml Compose 檔案，並搭配可供直通（pass-through）的裝置，例如使用 NVENC、Quick Sync、RKMPP 或 VAAPI。大多數 VPS 方案並不提供這些硬體，因此請以 CPU 為規劃基礎。

實際的設定重點在於執行緒數量。在 Administration、Settings、Video Transcoding Settings 中，執行緒數值設為 0 代表使用所有核心，這會導致在 2 核心的方案上，單一影片轉碼即可能使網頁介面凍結。請依照 Immich FAQ 的建議將其設為 1 或 2，如此一來，轉碼過程僅會變慢，而不會造成系統中斷。

為何 Swap thrashing 會看起來像系統當機

這是最常被誤判的故障。當 Immich 記憶體耗盡時，會出現兩種結果，但只有其中一種看起來像故障。

若無 Swap，核心會直接終止處理程序。容器會在幾秒內重啟，因此從瀏覽器端看來，工作佇列只是暫停後又恢復。證據在 docker ps -a 中：

docker ps -a --filter name=immich
docker inspect immich_machine_learning | grep -i oomkilled
sudo dmesg -T | grep -i -E 'out of memory|oom-kill'

Exited (137) 代表處理程序被訊號 9 終止。137 是 128 加上 9。OOMKilled 的值為 true，證實它是因記憶體不足而被終止，而非程式崩潰。

若有 Swap，則不會有任何程序被終止或報錯。核心會開始將記憶體頁面移至磁碟，匯入速度會慢上一個數量級，網頁介面也會在正常逾時時間內停止回應。此時所有容器都在執行，健康檢查也可能全部通過。這看起來像當機，使用者通常會在此時重啟伺服器，這不僅會導致佇列進度遺失，也無法解決問題。

free -m
vmstat 1 5

在 vmstat 的 si 與 so 欄位中出現持續非零的數值，代表機器正在持續讀寫 Swap，這就是所謂的 thrashing（抖動）。同時，Swap 使用量的 free -m 列數值會不斷攀升。

在 2 GB 或 4 GB 的機器上，請務必增加 Swap，因為「可診斷的緩慢匯入」遠優於「無法診斷的容器終止」：

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

接著請排除根本原因。將工作並行數（job concurrency）調降為 1，限制機器學習容器的資源，或將其移出此主機。Swap 只是為您爭取處理時間，它本身並非解決方案。

FAQ

我可以在 2 GB RAM 的 VPS 上執行 Immich 嗎？

可以。請將 immich-machine-learning 服務從 docker-compose.yml 中註解掉，並將工作並發數（job concurrency）設為 1。此規格低於官方建議的 6 GB，因此請將其視為一種已知折衷。您仍可使用上傳、相簿、分享、行動裝置備份，以及依日期、地點與檔名搜尋的功能。但您將無法使用依描述搜尋、自動人臉分組，以及圖片內文字辨識功能。請額外建立 2 GB 的 swap 檔案，以確保在大量匯入導致負載飆升時，伺服器僅會變慢，而非導致容器被強制終止。

為什麼我的 Immich 匯入作業會無預警停止？

從瀏覽器端觀察，兩種不同原因的現象相同。一是容器因記憶體不足被強制終止，此時 docker ps -a 會顯示 Exited (137) 且容器已重啟；二是主機正在使用 swap，此時所有容器仍在執行，但整體效能極度緩慢。使用 vmstat 1 5 可區分兩者：若 si 與 so 欄位出現持續性的非零數值，代表系統正在使用 swap。無論何種情況，請調低縮圖生成、人臉偵測與智慧搜尋的工作並發數。

Immich 日誌中的 exit code 137 代表什麼？

137 等於 128 加上訊號 9，代表該處理程序被 SIGKILL 強制終止。實務上，這意味著記憶體已達上限，可能是容器本身的限制，或是主機記憶體耗盡。請使用 docker inspect immich_machine_learning | grep -i oomkilled 檢查。若數值為 true，確認核心因記憶體不足而終止該程序；接著透過 free -m 與 sudo dmesg -T | grep -i oom-kill 即可判斷是容器限制還是主機整體記憶體不足。機器學習容器通常是最容易被終止的對象，因為它通常是佔用記憶體最大的處理程序。

Immich 每張照片需要多少磁碟空間？

請預留原始檔案大小外加 10% 到 20% 的空間。根據 Immich 文件，生成的縮圖與轉碼後的影片平均會增加 10% 到 20% 的儲存空間，而資料庫本身即便在大型圖庫中，通常也僅佔 1 到 3 GB。影片檔案才是決定總容量的關鍵，因此在選擇方案前，請先測量您自身的平均檔案大小，而非僅對照片數量套用倍數計算。

我需要為 Immich 配置 GPU 嗎？

不需要。Immich 的所有組件皆可在 CPU 上執行。顯示卡僅能加速機器學習容器中的模型推論與影片編碼，但這些並非必要。大多數 VPS 方案並不提供 GPU。在僅有 CPU 的硬體上，請將轉碼執行緒設為 1 或 2，使用 buffalo_s 人臉模型，並讓首次大量匯入作業在夜間執行。