服务器组件

相关源文件

• cli/package-lock.json
• cli/package.json
• e2e/package-lock.json
• e2e/package.json
• machine-learning/pyproject.toml
• mobile/android/fastlane/Fastfile
• mobile/ios/fastlane/Fastfile
• mobile/openapi/README.md
• mobile/pubspec.yaml
• open-api/immich-openapi-specs.json
• open-api/typescript-sdk/package-lock.json
• open-api/typescript-sdk/package.json
• open-api/typescript-sdk/src/fetch-client.ts
• server/package-lock.json
• server/package.json
• server/src/cores/storage.core.ts
• server/src/database.ts
• server/src/entities/asset.entity.ts
• server/src/queries/asset.job.repository.sql
• server/src/queries/asset.repository.sql
• server/src/repositories/asset-job.repository.ts
• server/src/repositories/asset.repository.ts
• server/src/repositories/media.repository.ts
• server/src/services/asset.service.spec.ts
• server/src/services/asset.service.ts
• server/src/services/media.service.spec.ts
• server/src/services/media.service.ts
• server/src/services/metadata.service.spec.ts
• server/src/services/metadata.service.ts
• server/src/utils/media.ts
• server/test/fixtures/asset.stub.ts
• server/test/fixtures/media.stub.ts
• server/test/fixtures/shared-link.stub.ts
• server/test/repositories/asset.repository.mock.ts
• web/package-lock.json
• web/package.json

目的与范围

本文档描述了 Immich 服务器组件，它是 Immich 应用程序的核心后端系统。服务器组件负责处理 API 请求、资产处理、作业管理和数据库操作。它是用户界面（Web、移动设备、CLI）与其他后端服务（如机器学习组件和数据库）之间的中心连接点。

有关机器学习组件的详细信息，请参阅 机器学习组件。

架构概述

服务器组件是使用 NestJS 构建的，NestJS 是一个渐进式的 Node.js 框架，为服务器端应用程序提供了强大的基础。它遵循控制器、服务和存储库的模块化架构模式。

来源：server/package.json server/src/services/media.service.ts server/src/services/metadata.service.ts

核心组件

API 控制器

API控制器处理传入的 HTTP 请求、验证输入并将处理委托给适当的服务。它们定义了客户端可以交互的路由和端点。

来源：open-api/immich-openapi-specs.json

服务层

服务层包含应用程序的业务逻辑。它负责处理请求、协调操作以及与存储库和其他服务进行交互。

主要服务

服务	主要职责
AssetService	资产的创建、检索、更新和删除
MediaService	媒体处理、缩略图生成、视频转码
MetadataService	元数据提取、EXIF 处理
SearchService	资产搜索操作
PersonService	人脸检测和人物管理
AuthService	身份验证和授权
LibraryService	外部库管理
StorageService	文件系统操作

来源：server/src/services/asset.service.ts server/src/services/media.service.ts server/src/services/metadata.service.ts

存储库层

存储库层提供数据访问抽象。它结合使用 Kysely 和 TypeORM 进行数据库交互。

来源：server/src/repositories/asset.repository.ts server/src/repositories/asset-job.repository.ts

作业处理系统

服务器使用 BullMQ（由 Redis 支持）进行异步作业处理。这允许在后台执行资源密集型操作，而不会阻塞主应用程序流程。

作业处理系统使用 NestJS 装饰器进行装饰

• @OnJob() - 将方法标记为作业处理程序
• @OnEvent() - 将方法标记为事件处理程序

MetadataService 中的作业处理示例

来源：server/src/services/metadata.service.ts server/src/services/media.service.ts

资产处理管道

服务器组件的核心功能之一是处理资产（图像和视频）。

来源：server/src/services/asset.service.ts server/src/services/metadata.service.ts server/src/utils/media.ts

元数据提取

MetadataService 负责从资产中提取元数据。它使用 exiftool-vendored 从图像和视频中提取 EXIF 数据。

MetadataService 按此优先级顺序查找特定的 EXIF 日期标签

来源：server/src/services/metadata.service.ts36-47

媒体处理

MediaService 负责媒体处理任务，例如缩略图生成和视频转码。

缩略图生成

该服务为不同的用例生成多种缩略图尺寸

• 用于网格视图的小型缩略图
• 用于预览的中型缩略图
• 用于详细视图的大型缩略图

视频转码

对于视频，该服务可以转码为不同的格式，并支持各种硬件加速选项

来源：server/src/services/media.service.ts server/src/utils/media.ts

数据库 Schema

服务器使用 PostgreSQL 数据库，并带有 pgvecto.rs 扩展用于向量存储。数据库中的主要实体包括

实体	描述
资源	照片、视频和其他媒体
Exif	从资产中提取的元数据
AssetFiles	与资产相关的文件（原始文件、缩略图、编码视频）
AssetFaces	资产中的人脸检测
人员	从人脸识别出的人物实体
相册	资产集合
用户	用户账户
库	外部媒体库
标签	用户分配或自动生成的标签

来源：server/src/database.ts server/src/entities/asset.entity.ts

关键枚举

服务器定义了几个贯穿代码库的关键枚举

枚举（Enum）	目的
AssetType	资产类型（图像、视频）
JobName	后台作业名称（元数据提取、缩略图生成等）
JobStatus	作业状态（待定、处理中、完成、失败）
AssetFileType	资产文件类型（原始文件、缩略图、编码视频等）
WithoutProperty	资产响应中要排除的属性

AssetRepository 中的示例

来源：server/src/repositories/asset.repository.ts44-52

与其他组件的集成

机器学习服务

服务器组件与机器学习服务交互，用于

• 人脸检测和识别
• 目标检测
• CLIP 处理以实现智能搜索
• 反向地理编码

移动和 Web 客户端

服务器公开供移动和 Web 客户端使用的 API。它还维护 WebSocket 连接以实现实时更新。

命令行界面

服务器包含一个使用 nest-commander 构建的 CLI 组件，允许进行命令行操作和管理。

结论

服务器组件是 Immich 应用程序的中心枢纽，连接用户界面与数据存储和处理服务。它处理广泛的职责，从 API 请求处理到复杂的媒体处理任务。理解其架构和组件对于处理 Immich 项目的开发人员至关重要。

来源： server/package.json server/src/services/asset.service.ts server/src/services/media.service.ts server/src/services/metadata.service.ts