在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

immich-app/immich

菜单

开发指南

相关源文件

本文档是为希望为Immich项目做出贡献的开发者提供的全面指南。它涵盖了开发环境的设置、构建系统的理解、CI/CD管道的导航、测试框架的使用以及发布流程的参与。

开发环境设置

先决条件

要开发Immich，您需要

  • Docker和Docker Compose（推荐用于所有开发）
  • Node.js（版本在特定组件的.nvmrc文件中指定）
  • Flutter SDK（用于移动开发）
  • Python（用于机器学习组件）

基于 Docker 的开发

推荐的开发方式是使用Docker Compose

此配置设置了

  • immich-server-dev：支持热重载的NestJS后端
  • immich-web-dev：支持热重载的SvelteKit前端
  • immich-machine-learning-dev：Python FastAPI服务
  • redis：用于缓存和作业队列
  • database：PostgreSQL，带有pgvecto.rs扩展

Docker开发环境使用卷挂载，以便在不重新构建容器的情况下实现实时代码更改。

来源：server/Dockerfile1-17 web/Dockerfile1-12

组件特定开发

服务器 (NestJS)

Web UI (SvelteKit)

移动端 (Flutter)

CLI (TypeScript)

机器学习服务 (Python)

仓库架构

开发架构图

来源：server/Dockerfile web/Dockerfile cli/Dockerfile

组件关系

构建系统

服务端构建过程

服务器组件使用TypeScript和NestJS

构建过程

  1. 将TypeScript编译为JavaScript
  2. 生成OpenAPI规范
  3. 准备生产就绪的代码

对于Docker构建，使用了多阶段方法来创建优化的镜像。

来源：server/Dockerfile19-27 server/Dockerfile45-78

Web构建流程

Web UI使用SvelteKit

对于生产环境，Web构建将被集成到服务器Docker镜像中。

来源：server/Dockerfile28-42

移动端构建流程

移动端应用使用Flutter并结合代码生成

来源：mobile/makefile1-22 .github/workflows/build-mobile.yml85-94

Docker构建系统

对于生产环境，Immich使用多阶段Docker构建，并支持多种架构

来源：server/Dockerfile cli/Dockerfile .github/workflows/docker.yml95-203 .github/workflows/docker.yml317-493

CI/CD 流水线

Immich使用GitHub Actions进行持续集成和部署。

测试管道

测试工作流针对所有拉取请求和推送到main分支运行

来源：.github/workflows/test.yml1-63 .github/workflows/test.yml252-318

Docker构建流水线

Docker工作流构建和发布容器镜像

来源：.github/workflows/docker.yml1-44 .github/workflows/docker.yml95-203

测试框架

Immich采用了全面的测试策略，覆盖所有组件。

测试策略

  1. 单元测试：测试单个函数和组件
  2. 中级测试：在真实数据库上进行的服务器测试
  3. 端到端测试：通过API和UI测试完整的用户流程

组件特定测试

服务器测试

来源：.github/workflows/test.yml56-92 .github/workflows/test.yml252-275

Web测试

来源：.github/workflows/test.yml168-211

移动端测试

来源：.github/workflows/test.yml360-374

机器学习测试

来源：.github/workflows/test.yml376-407

端到端测试

来源: .github/workflows/test.yml277-318 .github/workflows/test.yml319-358

测试架构

来源: .github/workflows/test.yml

发布流程

Immich 遵循其发布的语义化版本.

版本管理

版本升级通过一个自动化脚本进行管理，该脚本更新所有组件中的版本

  • 服务器: package.json
  • Web: package.json
  • 移动端: pubspec.yaml
  • CLI: package.json
  • ML: pyproject.toml

来源: misc/release/pump-version.sh1-91

发布工作流

发布流程

  1. 维护者触发发布准备工作流程
  2. 指定版本升级的类型（次要/补丁）
  3. 可选地递增移动端的构建号
  4. 工作流程更新所有组件中的版本号
  5. 提交更改并创建 git 标签
  6. 构建移动应用
  7. 创建带有资源的 GitHub 发布草稿
  8. 发布时，触发带有新版本标签的 Docker 镜像构建

来源: .github/workflows/prepare-release.yml1-102 misc/release/pump-version.sh1-91

贡献工作流程

为 Immich 做贡献的典型流程

关键贡献指南

  1. 为 PR 标题遵循约定俗成的提交格式
  2. 提交前确保本地测试通过
  3. 为新功能或 bug 修复添加测试
  4. 必要时更新文档
  5. 遵循项目的编码风格

来源: .github/workflows/fix-format.yml1-52 .github/workflows/pr-require-conventional-commit.yml1-16 .github/workflows/pr-label-validation.yml1-23

总结

此开发指南涵盖了为 Immich 项目做贡献的基本方面，从设置环境到参与发布过程。有关特定组件的详细信息，请参阅文档的其他部分，包括 服务器组件、Web 界面、移动应用程序 和 机器学习组件。

CI/CD 管道通过全面的测试确保代码质量，自动化的发布流程维护所有组件之间的一致版本。通过遵循概述的工作流程和约定，您可以有效地为 Immich 的发展和改进做出贡献。

来源: .github/workflows/test.yml .github/workflows/docker.yml .github/workflows/prepare-release.yml