架構

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

高層次圖示

圖示顯示了客戶端通過 REST 與伺服器的 API 溝通。伺服器通過儲存庫介面與下游系統（例如 Redis、Postgres、機器學習、文件系統）進行互動。圖示未顯示的是，伺服器分為兩個獨立的容器 immich-server 和 immich-microservices。microservices 容器不處理 API 請求或排程 cron 作業，但主要處理來自 Redis 的工作請求。

客戶端

Immich 有三個主要客戶端：

1. 移動應用程式 - Android，iOS
2. Web 應用程式 - 響應式網站
3. CLI - 命令行工具，用於大量上傳

信息

所有三個客戶端使用 OpenAPI 自動生成 REST 客戶端以供輕鬆整合。欲了解更多關於此過程的資訊，請參閱 OpenAPI。

移動應用程式

移動應用程式使用 Flutter 用 Dart 編寫。以下是架構概述：

圖示顯示了目標架構，目前代碼基礎尚未完全遵循該架構。新的代碼和貢獻應遵循此架構。 目前，它使用 Isar Database 作為本地數據庫並使用 Riverpod 作為狀態管理（提供者）。 實體和模型是使用的兩種類型數據類別。雖然實體存儲在設備上的數據庫中，但模型是暫時的，僅存在記憶體中。 倉庫應該是使用其他數據類別（例如 OpenAPI DTO）的唯一地方。但是，它們的介面不得使用外部數據類別！

Web 客戶端

Web 應用程式是一個 TypeScript 專案，使用 SvelteKit 和 Tailwindcss。

CLI

Immich CLI 是一個 npm 套件，允許用戶通過命令行控制他們的 Immich 實例。它使用 API 執行各種任務，特別是上傳資產。請參閱 CLI 文件 了解詳細資訊。

伺服器

Immich 的後端分為多個服務，作為獨立的 docker 容器運行。

1. immich-server - 處理和回應 REST API 請求，執行背景作業（縮圖生成、元數據提取、轉碼等）
2. immich-machine-learning - 執行機器學習模型
3. postgres - 持久數據存儲
4. 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 管理作業隊列。有些作業會觸發後續作業。例如，智能搜索和臉部辨識依賴於生成縮圖，在生成後會自動運行。