Immich 實戰指南：高效能自架照片與影片管理方案的部署組成、功能矩陣與源碼級支撐

Immich 實戰指南：高效能自架照片與影片管理方案的部署組成、功能矩陣與源碼級支撐

【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich

本文以 Immich 官方的正體中文專案說明明細為核心，帶你完整了解這套「高效能自架照片和影片管理解決方案」的能力邊界：從手機與網頁兩端的支援功能矩陣、線上 Demo 體驗方式，到基於 Docker Compose 的四容器部署組成與關鍵環境變數，並結合當前倉庫的伺服器服務層、機器學習模型與背景工作執行器源碼，說明每項功能的底層支撐。讀完後，你能獨立完成一次標準部署、核對功能可用範圍，並具備深入源碼繼續調研的路徑。

專案定位與備份原則

Immich 的自我定位是「高效能的自架照片和影片管理解決方案」（High performance self-hosted photo and video management solution），採用 AGPLv3 授權條款。它的價值主張在於把照片/影片管理的完整能力（備份、搜尋、人脸识别、智能搜尋、共享、管理後台）放到使用者自己的伺服器和資料庫上，由使用者掌控原始資料。

專案文件同時強調了一條不可忽略的紅線：務必遵循 3-2-1 備份原則（3 份資料副本、2 種不同儲存介質、1 份離線/遠端保存）來守護珍貴的照片與影片。自架方案解決的是「資料主權」問題，但不替代備份策略——資料庫、上傳媒體與磁碟本身都可能在單點故障中遺失，這一點在官方英文 README（README.md）與本正體中文版本（readme_i18n/README_zh_TW.md）中被同等強調。

說明：本說明文件本身不包含完整安裝指南，安裝指南位於專案官方文件站；在當前倉庫內，對應的落地材料是 docker/ 目錄下的 Compose 檔與 docs/docs/install/ 下的安裝文件（Docker Compose、Kubernetes、各 NAS 平台等）。

線上 Demo：最快理解功能邊界的方式

在部署自己的實例之前，Immich 提供了線上 Demo 環境供即時體驗：

• Demo 位址：https://demo.immich.app
• 手機 App 接入方式：在 App 的「伺服器端點 URL」（Server Endpoint URL）欄位輸入https://demo.immich.app
• 登入資訊：

由於 Demo 與自架實例共用同一套 OpenAPI 介面與資料模型，你在 Demo 中看到的時間軸、人物分群、智能搜尋與分享行為，就是自架後會得到的完整功能面。建議把 Demo 作為「驗收清單」：部署完成後逐項核對下一節的功能矩陣。

部署組成：四個容器與關鍵環境變數

Immich 標準部署由 Docker Compose 拉起四個服務，定義見 docker/docker-compose.yml：

Compose 檔中的幾個關鍵綁定與註解值得注意：

• 媒體儲存位置由${UPLOAD_LOCATION}:/data掛載，且檔案明確註明「若要變更媒體儲存位置，請修改 .env 中的UPLOAD_LOCATION」，而不是直接改 Compose；
• 資料庫資料位於${DB_DATA_LOCATION}:/var/lib/postgresql/data，並透過POSTGRES_INITDB_ARGS: '--data-checksums'啟用資料校驗和；若資料庫不在 SSD 上，可解註DB_STORAGE_TYPE: 'HDD'；
• ML 容器透過具名卷model-cache快取已下載的模型，避免每次啟動重複下載；
• 需要硬體轉碼時，可透過extends機制套用 docker/hwaccel.transcoding.yml（nvenc、quicksync、rkmpp、vaapi 等服務），ML 硬體加速對應 docker/hwaccel.ml.yml。

環境變數模板見 docker/example.env，核心欄位如下：

# 上傳檔案的儲存位置 UPLOAD_LOCATION=./library # 資料庫檔案儲存位置（不支援網路共享存放資料庫） DB_DATA_LOCATION=./postgres # 設定時區：取消註解並改成 TZ 資料庫中的標識符 # TZ=Etc/UTC # 使用的 Immich 版本，可固定為特定版本如 "v2.1.0" IMMICH_VERSION=v3 # postgres 連線密鑰，應改為隨機密碼 # 僅使用 A-Za-z0-9 字元，不含特殊字元或空格 DB_PASSWORD=postgres # 以下無需修改 DB_USERNAME=postgres DB_DATABASE_NAME=immich

倉庫根目錄的 install.sh 腳本示範了一鍵部署的完整流程：建立./immich-app目錄、下載 Compose 檔與.env、用sha256sum生成隨機資料庫密碼寫入.env，最後執行docker compose up --remove-orphans -d並輸出可訪問的http://<主機IP>:2283位址。你可以直接檢視該腳本作為手動部署步驟的參照實現。

注意：Compose 檔開頭特別警告「請使用當前 release 的 docker-compose.yml」，main 分支上的版本可能與最新 release 不相容，部署時應以發布頁附帶的檔案為準。

功能矩陣：手機端與網頁端能力對照

官方 README 給出的完整功能矩陣如下（「是/否/不適用」與原文一致），這是評估 Immich 能力邊界最權威的清單：

從矩陣可以讀出清晰的分工：管理功能（使用者管理）、API 金鑰與標籤只在網頁端提供；背景備份、開啟 App 自動備份與離線支援是手機端獨有；360 度全景顯示目前僅網頁端支援。

從源碼看功能如何落地

矩陣中的每一項能力，都能在当前倉庫的三個子專案中找到對應實現：

1. 伺服器端：服務層與矩陣的對應

後端為 NestJS（TypeScript / Node.js）專案，位於 server/。其業務邏輯集中在src/services/，幾乎每個矩陣功能都有獨立服務檔案，例如：

入口 server/src/main.ts 中的Workers類別負責啟動背景工作執行器：先檢查維護模式狀態，再透過 PostgreSQL 的建議鎖（pg_try_advisory_lock）確保單例，然後依ConfigRepository().getEnv()中的workers配置逐一啟動。工作執行器實體位於 server/src/workers/，包含api.ts（API 容器）、microservices.ts（消費 Redis 佇列的微服務容器）與maintenance.ts（維護模式）。這解釋了架構文件中的說法：immich-server處理 API 請求並排程 cron 工作，而 microservices 容器專責處理來自 Redis 的入站任務（縮圖生成、元資料抽取、轉碼、智能搜尋、臉部識別等）。

2. 機器學習服務：CLIP 與臉部辨識的模型實現

ML 服務為 Python/FastAPI 專案，位於 machine-learning/。矩陣中「依中繼資料、物件、臉孔與 CLIP 搜尋」與「臉部辨識與分群」兩行能力，對應其模型實現：

• CLIP 多模態模型分文字塔與視覺塔兩部分：machine-learning/immich_ml/models/clip/textual.py 與 machine-learning/immich_ml/models/clip/visual.py；
• 臉部偵測與辨識分離為 detection.py 與 recognition.py；
• 推論會話根據硬體選擇執行引擎：ort（ONNX Runtime CPU/GPU）、ann（Apple Neural Engine）、rknn（Rockchip NPU），見 machine-learning/immich_ml/sessions/。

模型一律以 ONNX 格式快取於model-cache卷中，這與 Compose 檔為 ML 容器掛載的model-cache:/cache卷相呼應；首次啟動下載模型、之後复用快取，正是該卷存在的意義。

3. 手機端：備份與離線的 Flutter 實作

手機 App 為 Flutter/Dart 專案（mobile/），矩陣中手機獨有的「背景備份」「開啟 App 時自動備份」「離線支援」由lib/domain/services/下的一组服務承載：

• sync_stream.service.dart：備份同步串流，負責將本機新增媒體推送至伺服器；
• background_worker.service.dart：Android/iOS 背景工作排程；
• hash.service.dart：媒體雜湊計算，是「避免重複媒體」的去重依據——上傳前以雜湊比對即可跳過已存在檔案；
• local_sync.service.dart 與 device_permission.service.dart：本地同步與權限管理，支撐離線瀏覽。

離線支援的資料基礎是手機端的本地資料庫（Drift schema 遷移檔案可見於 mobile/drift_schemas/main/，已迭代到 v31），確保無網路時仍可瀏覽已同步的媒體。

多語言翻譯體系

正體中文（本文件所在語言）只是 Immich 翻譯生態中的一部分。倉庫根目錄的 i18n/ 目錄收錄了 80 餘個語言的 JSON 翻譯檔，涵蓋 zh_Hant.json、zh_Hans.json、ja.json、de.json、fr.json、ko.json、es.json、pt_BR.json 等，與 README 頂部列出的 20 餘種語言的 README 多語版本（readme_i18n/ 目錄，本文件即為其中的README_zh_TW.md）共同構成兩層本地化：一層是產品介面文字，一層是專案說明文件本身。翻譯流程基於 Weblate 持續本地化平台管理，並使用 ICU 訊息格式處理複數、數字與日期等地區化格式（詳見 docs/docs/developer/translations.md）。

架構總覽與延伸閱讀

整體上，Immich 採用傳統客端-伺服器設計：三個主要客戶端（Android/iOS 手機 App、SvelteKit 網頁應用、npm CLI 工具）皆透過 OpenAPI 自動生成的 REST 客戶端與後端通信；immich-server依六邊形架構原則把技術實作（src/repositories/）與核心業務邏輯（src/services/）分離。更多細節可參照倉庫內文件：

• 架構與背景任務：docs/docs/developer/architecture.mdx
• 安裝文件（Docker Compose / Kubernetes / NAS 平台）：docs/docs/install/docker-compose.mdx、docs/docs/install/kubernetes.md
• 環境變數完整清單：docs/docs/install/environment-variables.md
• 資料庫遷移機制：docs/docs/developer/database-migrations.md
• 多機部署與擴展：docs/docs/guides/scaling-immich.md、docs/docs/guides/remote-machine-learning.md

小結

• 部署面：四個容器（server / machine-learning / redis / postgres）+UPLOAD_LOCATION、DB_DATA_LOCATION、DB_PASSWORD三個必改變數，即可在2283埠得到完整實例；install.sh 提供了可複現的自動部署參照。
• 能力面：以官方功能矩陣為契約——備份、去重、智能搜尋（CLIP/物件/臉孔）、分享與管理後台全功能齊備，管理與標籤類能力集中在網頁端。
• 底層面：矩陣每項功能均可在server/src/services/、machine-learning/immich_ml/models/與mobile/lib/domain/services/中找到對應源碼，便於深入調研或自定義擴展。
• 安全面：自架不等于免備份，3-2-1 備份原則是官方反覆強調的底線。

【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich