尧图网页设计 
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 份離線/遠端保存來守護珍貴的照片與影片。自架方案解決的是「資料主權」問題但不替代備份策略——資料庫、上傳媒體與磁碟本身都可能在單點故障中遺失這一點在官方英文 READMEREADME.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登入資訊電子郵件密碼demoimmich.appdemo由於 Demo 與自架實例共用同一套 OpenAPI 介面與資料模型你在 Demo 中看到的時間軸、人物分群、智能搜尋與分享行為就是自架後會得到的完整功能面。建議把 Demo 作為「驗收清單」部署完成後逐項核對下一節的功能矩陣。部署組成四個容器與關鍵環境變數Immich 標準部署由 Docker Compose 拉起四個服務定義見 docker/docker-compose.yml服務容器名鏡像職責immich-serverimmich_serverghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}處理 REST API、執行背景工作縮圖、轉碼、元資料等對外開放2283埠immich-machine-learningimmich_machine_learningghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}執行機器學習模型CLIP 智能搜尋、臉部辨識等可加-armnn / -cuda / -rocm / -openvino / -rknn後綴啟用硬體加速redisimmich_redisdocker.io/valkey/valkey:9背景任務佇列管理databaseimmich_postgresghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0持久化儲存含向量搜尋所需的 pgvector / vectorchord 擴充Compose 檔中的幾個關鍵綁定與註解值得注意媒體儲存位置由${UPLOAD_LOCATION}:/data掛載且檔案明確註明「若要變更媒體儲存位置請修改 .env 中的UPLOAD_LOCATION」而不是直接改 Compose資料庫資料位於${DB_DATA_LOCATION}:/var/lib/postgresql/data並透過POSTGRES_INITDB_ARGS: --data-checksums啟用資料校驗和若資料庫不在 SSD 上可解註DB_STORAGE_TYPE: HDDML 容器透過具名卷model-cache快取已下載的模型避免每次啟動重複下載需要硬體轉碼時可透過extends機制套用 docker/hwaccel.transcoding.ymlnvenc、quicksync、rkmpp、vaapi 等服務ML 硬體加速對應 docker/hwaccel.ml.yml。環境變數模板見 docker/example.env核心欄位如下# 上傳檔案的儲存位置 UPLOAD_LOCATION./library # 資料庫檔案儲存位置不支援網路共享存放資料庫 DB_DATA_LOCATION./postgres # 設定時區取消註解並改成 TZ 資料庫中的標識符 # TZEtc/UTC # 使用的 Immich 版本可固定為特定版本如 v2.1.0 IMMICH_VERSIONv3 # postgres 連線密鑰應改為隨機密碼 # 僅使用 A-Za-z0-9 字元不含特殊字元或空格 DB_PASSWORDpostgres # 以下無需修改 DB_USERNAMEpostgres DB_DATABASE_NAMEimmich倉庫根目錄的 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 能力邊界最權威的清單功能手機版網頁版上傳與檢視照片與影片是是開啟 App 時自動備份是不適用避免重複媒體是是選擇要備份的相簿是不適用下載照片與影片到本機裝置是是多使用者支援是是相簿與共享相簿是是可拖曳的捲軸是是支援 RAW 格式是是中繼資料檢視EXIF、地圖是是依中繼資料、物件、臉孔與 CLIP 搜尋是是管理功能使用者管理否是背景備份是不適用虛擬滾動是是支援 OAuth是是API 金鑰不適用是Live Photo/動態照片備份與播放是是支援 360 度全景照片顯示否是使用者自訂儲存結構是是公開分享是是封存與收藏是是世界地圖是是親朋好友分享是是臉部辨識與分群是是回憶x 年前是是離線支援是否唯讀媒體庫是是照片堆疊是是標籤否是資料夾檢視是是從矩陣可以讀出清晰的分工管理功能使用者管理、API 金鑰與標籤只在網頁端提供背景備份、開啟 App 自動備份與離線支援是手機端獨有360 度全景顯示目前僅網頁端支援。從源碼看功能如何落地矩陣中的每一項能力都能在当前倉庫的三個子專案中找到對應實現1. 伺服器端服務層與矩陣的對應後端為 NestJSTypeScript / Node.js專案位於 server/。其業務邏輯集中在src/services/幾乎每個矩陣功能都有獨立服務檔案例如功能領域服務實作智能搜尋CLIP/物件/文字search.service.ts、smart-info.service.ts、ocr.service.ts臉部辨識與人物分群person.service.ts、cluster-group.service.ts相簿/共享相簿/好友分享/公開分享album.service.ts、shared-link.service.ts、partner.service.ts重複媒體偵測duplicate.service.ts回憶x 年前memory.service.ts照片堆疊stack.service.ts標籤與資料夾檢視tag.service.ts使用者自訂儲存結構storage-template.service.tsAPI 金鑰api-key.service.ts影片轉碼transcoding.service.ts備份同步手機端增量同步sync.service.ts入口 server/src/main.ts 中的Workers類別負責啟動背景工作執行器先檢查維護模式狀態再透過 PostgreSQL 的建議鎖pg_try_advisory_lock確保單例然後依ConfigRepository().getEnv()中的workers配置逐一啟動。工作執行器實體位於 server/src/workers/包含api.tsAPI 容器、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推論會話根據硬體選擇執行引擎ortONNX Runtime CPU/GPU、annApple Neural Engine、rknnRockchip 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.dartAndroid/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 / postgresUPLOAD_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 份離線/遠端保存來守護珍貴的照片與影片。自架方案解決的是「資料主權」問題但不替代備份策略——資料庫、上傳媒體與磁碟本身都可能在單點故障中遺失這一點在官方英文 READMEREADME.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登入資訊電子郵件密碼demoimmich.appdemo由於 Demo 與自架實例共用同一套 OpenAPI 介面與資料模型你在 Demo 中看到的時間軸、人物分群、智能搜尋與分享行為就是自架後會得到的完整功能面。建議把 Demo 作為「驗收清單」部署完成後逐項核對下一節的功能矩陣。部署組成四個容器與關鍵環境變數Immich 標準部署由 Docker Compose 拉起四個服務定義見 docker/docker-compose.yml服務容器名鏡像職責immich-serverimmich_serverghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}處理 REST API、執行背景工作縮圖、轉碼、元資料等對外開放2283埠immich-machine-learningimmich_machine_learningghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}執行機器學習模型CLIP 智能搜尋、臉部辨識等可加-armnn / -cuda / -rocm / -openvino / -rknn後綴啟用硬體加速redisimmich_redisdocker.io/valkey/valkey:9背景任務佇列管理databaseimmich_postgresghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0持久化儲存含向量搜尋所需的 pgvector / vectorchord 擴充Compose 檔中的幾個關鍵綁定與註解值得注意媒體儲存位置由${UPLOAD_LOCATION}:/data掛載且檔案明確註明「若要變更媒體儲存位置請修改 .env 中的UPLOAD_LOCATION」而不是直接改 Compose資料庫資料位於${DB_DATA_LOCATION}:/var/lib/postgresql/data並透過POSTGRES_INITDB_ARGS: --data-checksums啟用資料校驗和若資料庫不在 SSD 上可解註DB_STORAGE_TYPE: HDDML 容器透過具名卷model-cache快取已下載的模型避免每次啟動重複下載需要硬體轉碼時可透過extends機制套用 docker/hwaccel.transcoding.ymlnvenc、quicksync、rkmpp、vaapi 等服務ML 硬體加速對應 docker/hwaccel.ml.yml。環境變數模板見 docker/example.env核心欄位如下# 上傳檔案的儲存位置 UPLOAD_LOCATION./library # 資料庫檔案儲存位置不支援網路共享存放資料庫 DB_DATA_LOCATION./postgres # 設定時區取消註解並改成 TZ 資料庫中的標識符 # TZEtc/UTC # 使用的 Immich 版本可固定為特定版本如 v2.1.0 IMMICH_VERSIONv3 # postgres 連線密鑰應改為隨機密碼 # 僅使用 A-Za-z0-9 字元不含特殊字元或空格 DB_PASSWORDpostgres # 以下無需修改 DB_USERNAMEpostgres DB_DATABASE_NAMEimmich倉庫根目錄的 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 能力邊界最權威的清單功能手機版網頁版上傳與檢視照片與影片是是開啟 App 時自動備份是不適用避免重複媒體是是選擇要備份的相簿是不適用下載照片與影片到本機裝置是是多使用者支援是是相簿與共享相簿是是可拖曳的捲軸是是支援 RAW 格式是是中繼資料檢視EXIF、地圖是是依中繼資料、物件、臉孔與 CLIP 搜尋是是管理功能使用者管理否是背景備份是不適用虛擬滾動是是支援 OAuth是是API 金鑰不適用是Live Photo/動態照片備份與播放是是支援 360 度全景照片顯示否是使用者自訂儲存結構是是公開分享是是封存與收藏是是世界地圖是是親朋好友分享是是臉部辨識與分群是是回憶x 年前是是離線支援是否唯讀媒體庫是是照片堆疊是是標籤否是資料夾檢視是是從矩陣可以讀出清晰的分工管理功能使用者管理、API 金鑰與標籤只在網頁端提供背景備份、開啟 App 自動備份與離線支援是手機端獨有360 度全景顯示目前僅網頁端支援。從源碼看功能如何落地矩陣中的每一項能力都能在当前倉庫的三個子專案中找到對應實現1. 伺服器端服務層與矩陣的對應後端為 NestJSTypeScript / Node.js專案位於 server/。其業務邏輯集中在src/services/幾乎每個矩陣功能都有獨立服務檔案例如功能領域服務實作智能搜尋CLIP/物件/文字search.service.ts、smart-info.service.ts、ocr.service.ts臉部辨識與人物分群person.service.ts、cluster-group.service.ts相簿/共享相簿/好友分享/公開分享album.service.ts、shared-link.service.ts、partner.service.ts重複媒體偵測duplicate.service.ts回憶x 年前memory.service.ts照片堆疊stack.service.ts標籤與資料夾檢視tag.service.ts使用者自訂儲存結構storage-template.service.tsAPI 金鑰api-key.service.ts影片轉碼transcoding.service.ts備份同步手機端增量同步sync.service.ts入口 server/src/main.ts 中的Workers類別負責啟動背景工作執行器先檢查維護模式狀態再透過 PostgreSQL 的建議鎖pg_try_advisory_lock確保單例然後依ConfigRepository().getEnv()中的workers配置逐一啟動。工作執行器實體位於 server/src/workers/包含api.tsAPI 容器、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推論會話根據硬體選擇執行引擎ortONNX Runtime CPU/GPU、annApple Neural Engine、rknnRockchip 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.dartAndroid/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 / postgresUPLOAD_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考