架構
Immich 使用傳統的客戶端-伺服器設計,並有專用的資料庫來執行資料持久化。前端客戶端通過 HTTP 使用 REST API 與後端服務進行溝通。以下是架構的高層次圖示。
高層次圖示

圖示顯示了客戶端通過 REST 與伺服器的 API 溝通。伺服器通過儲存庫介面與下游系統(例如 Redis、Postgres 、機器學習、文件系統)進行互動。圖示未顯示的是,伺服器分為兩個獨立的容器 immich-server
和 immich-microservices
。microservices 容器不處理 API 請求或排程 cron 作業,但主要處理來自 Redis 的工作請求。
客戶端
Immich 有三個主要客戶端:
- 移動應用程式 - Android,iOS
- Web 應用程式 - 響應式網站
- CLI - 命令行工具,用於大量上傳
移動應用程式
移動應用程式使用 Flutter 用 Dart 編寫。以下是架構概述:
圖示顯示了目標架構,目前代碼基礎尚未完全遵循該架構。新的代碼和貢獻應遵循此架構。 目前,它使用 Isar Database 作為本地數據庫並使用 Riverpod 作為狀態管理(提供者)。 實體和模型是使用的兩種類型數據類別。雖然實體存儲在設備上的數據庫中,但模型是暫時的,僅存在記憶體中。 倉庫應該是使用其他數據類別(例如 OpenAPI DTO)的唯一地方。但是,它們的介面不得使用外部數據類別!
Web 客戶端
Web 應用程式是一個 TypeScript 專案,使用 SvelteKit 和 Tailwindcss。
CLI
Immich CLI 是一個 npm 套件,允許用戶通過命令行控制他們的 Immich 實例。它使用 API 執行各種任務,特別是上傳資產。請參閱 CLI 文件 了解詳細資訊。
伺服器
Immich 的後端分為多個服務,作為獨立的 docker 容器運行。
immich-server
- 處理和回應 REST API 請求,執行背景作業(縮圖生成、元數據提取、轉碼等)immich-machine-learning
- 執行機器學習模型postgres
- 持久數據存儲redis
- 管理背景作業的隊列
Immich 伺服器
Immich 伺服器是一個使用 Nest.js 框架、Express 伺服器以及查詢構建器 Kysely 寫於 Node.js 的 TypeScript 專案。伺服器代碼基礎也粗略地遵守 Hexagonal Architecture。具體來說,我們的目標是將特定技術實作(src/repositories
)與核心業務邏輯(src/services
)分離。
API 接口
傳入的 HTTP 請求映射到控制器(src/controllers
)。控制器是 HTTP 接口的集合。每個控制器通常以下列 CRUD 操作實施其各自的資源類型:
POST
/<type>
- 創建GET
/<type>
- 讀取 (全部)GET
/<type>/:id
- 讀取 (通過 ID)PUT
/<type>/:id
- 更新 (通過 ID)DELETE
/<type>/:id
- 刪除 (通過 ID)
領域轉移物件(DTO)
伺服器使用 領域轉移物件 作為每個接口的輸入(查詢、參數 和正文)和輸出(響應)的公共介面。DTO 翻譯為 OpenAPI 模式,並控制每個客戶端使用生成的代碼。
背景任務
Immich 使用 worker 執行背景任務。這些任務包括:
- 縮圖生成
- 元數據提取
- 視頻轉碼
- 智能搜索
- 臉部辨識
- 存儲模板遷移
- 側車(參閱 XMP Sidecars)
- 背景操作(文件刪除,用戶刪除)
此列表幾乎與 管理 > 作業 頁面上提供的列表一致,它提供了一些遠端隊列管理功能。
機器學習
機器學習服務是使用 Python 編寫的,並使用 FastAPI 進行 HTTP 通信。
所有與機器學習 相關的操作都被外包到了這個服務 immich-machine-learning
。Python 是 AI 和機器學習的自然選擇。它也有一些相當特殊的硬體需求。將其作為單獨的容器運行使得能在不同的機器上運行容器,或完全輕鬆禁用它。
每個對機器學習服務的請求都包含適用於模型任務、模型名稱等的相關元數據。這些設置與其他系統配置一起存儲在 Postgres數據庫中。對於每個請求,microservices 容器提取這些設置以便將其附加到請求上。
在內部,機器學習服務下載、載入並配置指定的模型,用於處理給定請求的文字或圖像負載。已載入的模型被緩存並在請求之間重複使用。線程池用於在不同線程中處理每個請求,以免阻塞非同步事件循環。
所有的模型格式為 ONNX。這種格式具有廣泛的業界支持,意味著大多數其他模型格式可以導出到它上,許多硬體 API 支援它。它也相當快速。
機器學習模型也非常 大,需要相當多的內存。我們一直在尋找改善和優化這個容器的方式。
Postgres
Immich 在 Postgres 中持久化數據,包括授權與訪問信息、用戶、相冊、資產、分享設定等。
欲了解更多關於如何修訂數據庫以創建索引、修訂表格、添加新列等的資 訊,請參閱 數據庫遷移。
Redis
Immich 使用 Redis 通過 BullMQ 管理作業隊列。有些作業會觸發後續作業。例如,智能搜索和臉部辨識依賴於生成縮圖,在生成後會自動運行。