跳转到主要内容

使用开发容器进行开发

开发容器使用 Docker 容器提供一致且可复制的开发环境。只需单击一次，即可在 Mac、Linux、Windows 或使用 GitHub Codespaces 的云环境中启动 Immich 开发环境。

快速开始！

在 GitHub Codespaces 打开

了解更多关于开发容器的信息

前提条件​

在开始之前，请确保您已经具备以下条件：

  • Docker Desktop（最新版本）
  • 带有 Dev Containers 插件 的 Visual Studio Code
  • 用于克隆代码库的 Git
  • 至少 8GB RAM（建议 16GB）
  • 20GB 的可用磁盘空间
替代开发环境

虽然本指南重点介绍 VS Code，但您可以选择许多其他开发容器环境：

本地编辑器：

基于云的解决方案：

  • GitHub Codespaces - 与 GitHub 完全集成，具有出色的 devcontainer.json 支持
  • GitPod - SaaS 平台，最近添加了对开发容器的支持（历史上使用 gitpod.yml）

可自行托管的选项：

  • Coder - 面向企业，需具备 Terraform 知识，自行管理
  • DevPod - 仅客户端工具，具有出色的 devcontainer.json 支持，可与任何提供商配合使用（本地、云或内部部署）

开发容器服务​

开发容器环境包含以下服务：

服务容器名称描述端口
服务器和前端immich-server在开发模式下运行 API 服务器和 Web 前端2283 (API)
3000 (Web)
9230 (Workers Debug)
9231 (API Debug)
数据库databasePostgreSQL 数据库5432
缓存redisValkey 缓存服务器6379
机器学习immich-machine-learningImmich ML 模型推理服务器3003

开始使用​

第一步：克隆代码库​

git clone https://github.com/immich-app/immich.git
cd immich

第二步：配置环境变量​

immich 开发容器从您的 shell 环境中读取环境变量，而不是从 .env 文件中读取。这允许它们在云环境中无需预配置即可工作。

配置

在本地运行时，如果您想创建（或使用现有的）数据库或照片存储文件夹，必须在启动开发容器之前在您的 shell 环境中设置 UPLOAD_LOCATION 变量。这将决定上传的文件存储位置以及数据库存储数据的位置。

# 临时为当前会话设置
export UPLOAD_LOCATION=/opt/dev_upload_folder

# 或将其添加到您的 shell 配置文件以实现持久化
# (~/.bashrc, ~/.zshrc, ~/.bash_profile 等)
echo 'export UPLOAD_LOCATION=/opt/dev_upload_folder' >> ~/.bashrc
source ~/.bashrc

第三步：启动开发容器​

提示

Immich 开发广泛使用 基础镜像，因此您无法使用 VS Code 的 在容器卷中克隆代码库 命令。

使用 VS Code UI：​

  1. 在 VS Code 中打开克隆的代码库
  2. 按 F1 或 Ctrl/Cmd+Shift+P 打开命令面板
  3. 输入并选择 "Dev Containers: Rebuild and Reopen in Container"
  4. 从列表中选择 "Immich - Backend, Frontend and ML"
  5. 等待容器构建并启动（首次运行可能需要几分钟）

使用 VS Code 快捷操作：​

  1. 在 VS Code 中打开代码库
  2. 您应该会看到一个弹窗提示是否重新打开到容器中
  3. 点击 "在容器中重新打开"

使用命令行：​

# 使用 DevContainer CLI
devcontainer up --workspace-folder .

环境变量详情​

开发容器如何处理环境变量​

与基于 Docker Compose 的 Immich 开发设置不同（使用 .env 文件），Immich 开发容器从您的 shell 环境中读取环境变量。这在 .devcontainer/devcontainer.json 文件中配置：

"remoteEnv": {
    "UPLOAD_LOCATION": "${localEnv:UPLOAD_LOCATION:./Library}",
    "DB_PASSWORD": "${localEnv:DB_PASSWORD:postgres}",
    "DB_USERNAME": "${localEnv:DB_USERNAME:postgres}",
    "DB_DATABASE_NAME": "${localEnv:DB_DATABASE_NAME:immich}"
}

${localEnv:VARIABLE:default} 语法从您的 shell 环境中读取变量，同时支持可选默认值。

上传位置路径解析​

UPLOAD_LOCATION 环境变量控制文件存储的位置：

默认值： ./Library（相对于 docker 目录） 解析为： <immich-root>/docker/Library

创建的绑定挂载点：

# 来自 .devcontainer/server/container-compose-overrides.yml
- ${UPLOAD_LOCATION-./Library}/photos:/workspaces/immich/server/upload
- ${UPLOAD_LOCATION-./Library}/postgres:/var/lib/postgresql/data

数据库配置​

这些变量具有合理的默认值（用于开发），但可以自定义：

变量默认值描述
DB_PASSWORDpostgresPostgreSQL 密码
DB_USERNAMEpostgresPostgreSQL 用户名
DB_DATABASE_NAMEimmich数据库名称

设置环境变量​

将这些变量添加到您的 shell 配置文件（~/.bashrc, ~/.zshrc, ~/.bash_profile 等）：

# 必需变量
export UPLOAD_LOCATION=./Library  # 或绝对路径

# 可选变量（仅在使用非默认值时）
export DB_PASSWORD=your_password
export DB_USERNAME=your_username
export DB_DATABASE_NAME=your_database

记得重新加载您的 shell 配置：

source ~/.bashrc  # 或 ~/.zshrc 等

Git 配置​

SSH 密钥和认证​

要在开发容器内使用您的 SSH 密钥访问 GitHub：

  1. 在主机上启动 SSH 代理：

    eval "$(ssh-agent -s)"
    ssh-add ~/.ssh/id_rsa  # 或您的密钥路径

  2. VS Code 会自动将您的 SSH 代理转发到容器

查看有关共享 Git 凭据的详细说明，请参阅 VS Code 指南。

提交签名​

要使用您的 SSH 密钥进行提交签名，请参阅 GitHub 指南。

开发工作流程​

自动设置​

开发容器启动时会自动：

  1. 运行创建后脚本（container-server-post-create.sh）：

    • 调整 node 用户的文件权限
    • 安装依赖：在所有包中运行 npm install
    • 构建 TypeScript SDK：在 open-api/typescript-sdk 中运行 npm run build

  2. 通过 VS Code 任务启动开发服务器：

    • Immich API Server (Nest) - 带热重载的 API 服务，端口 2283
    • Immich Web Server (Vite) - 带热重载的 Web 前端，端口 3000
    • 两个服务器都监视文件更改并自动重新编译

  3. 配置端口转发：

    • Web UI: http://localhost:3000（自动打开）
    • API: http://localhost:2283
    • 调试端口：9230（Workers），9231（API）
信息

开发容器设置替代了传统设置中的 make dev 命令。您打开容器时，所有服务会自动启动。

访问服务​

启动后，您可以访问：

服务URL描述
Web UIhttp://localhost:3000主要 Web 界面
APIhttp://localhost:2283REST API 端点（不会直接使用，Web 界面会通过 http://localhost:3000/api 暴露此接口）
数据库localhost:5432PostgreSQL（用户名：postgres）（不会直接使用）

连接移动应用​

要将移动应用程序连接到您的开发容器：

  1. 找到您的机器的 IP 地址
  2. 在移动应用程序中，使用：http://您的IP:3000/api
  3. 确保您的防火墙允许 2283 端口的连接

进行代码更改​

  • 服务器代码（/server）：修改会触发自动重启
  • Web 代码（/web）：修改会触发热模块替换
  • 数据库迁移: 在服务器目录中运行 npm run sync:sql
  • API更改: 使用 make open-api 重新生成 TypeScript SDK

测试​

运行测试​

开发容器支持多种方式运行测试:

使用Make命令（推荐）​

# 针对特定组件运行测试
make test-server         # 服务器单元测试
make test-web           # Web单元测试
make test-e2e           # 端到端测试
make test-cli           # CLI测试

# 运行所有测试
make test-all           # 运行所有组件的测试

# 中型测试（集成测试）
make test-medium-dev    # 端到端测试

直接使用NPM​

# 服务器测试
cd /workspaces/immich/server
npm test                # 运行所有测试
npm run test:watch     # 观察模式
npm run test:cov       # 覆盖率报告

# Web测试
cd /workspaces/immich/web
npm test               # 运行所有测试
npm run test:watch     # 观察模式

# 端到端测试
cd /workspaces/immich/e2e
npm run test           # 运行API测试
npm run test:web       # 运行网络界面测试

代码质量命令​

# 代码检查
make lint-server        # 检查服务器代码
make lint-web          # 检查Web代码
make lint-all          # 检查所有组件

# 格式化
make format-server      # 格式化服务器代码
make format-web        # 格式化Web代码
make format-all        # 格式化所有代码

# 类型检查
make check-server       # 类型检查服务器
make check-web         # 类型检查Web组件
make check-all         # 检查所有组件

# 完整卫生检查
make hygiene-all       # 运行代码检查、格式化、类型检查、SQL同步以及审计

其他Make命令​

# 构建命令
make build-server       # 构建服务器
make build-web         # 构建Web应用
make build-all         # 构建所有内容

# API生成
make open-api          # 生成OpenAPI规范
make open-api-typescript # 生成TypeScript SDK
make open-api-dart     # 生成Dart SDK

# 数据库
make sql               # 同步数据库架构

# 依赖
make install-server    # 安装服务器依赖项
make install-web      # 安装Web依赖项
make install-all      # 安装所有依赖项

调试​

开发容器已预配置用于调试:

  1. API服务器调试:

    • 在VS Code中设置断点
    • 按 F5 或使用“运行和调试”面板
    • 选择“附加到服务器”配置
    • 调试端口: 9231

  2. Worker调试:

    • 使用“附加到Worker”配置
    • 调试端口: 9230

  3. Web调试:

    • 使用浏览器开发者工具
    • 支持VS Code的Chrome/Edge扩展调试器

故障排除​

常见问题​

权限错误​

问题: EACCES或权限被拒绝错误 解决方案:

  • 开发容器以node用户（UID 1000）运行
  • 如果您的主机UID不同，可能会出现权限问题
  • 尝试重新构建容器: “开发容器:重新构建容器”

容器无法启动​

问题: 开发容器无法启动或构建 解决方案:

  1. 检查Docker是否正在运行: docker ps
  2. 清理Docker资源: docker system prune -a
  3. 检查可用磁盘空间
  4. 查看Docker Desktop资源限制

端口已被占用​

问题: "端口3000/2283已被占用" 解决方案:

  1. 检查冲突服务: lsof -i :3000（macOS/Linux）
  2. 停止冲突服务或更改端口映射
  3. 重新启动Docker Desktop

上传位置未设置​

问题: 关于缺少UPLOAD_LOCATION的错误 解决方案:

  1. 设置环境变量: export UPLOAD_LOCATION=./Library
  2. 添加到您的shell配置文件以使其持久化
  3. 重新启动您的终端和VS Code

数据库连接失败​

问题: 无法连接到PostgreSQL 解决方案:

  1. 确保所有容器都在运行: docker ps
  2. 检查日志: “开发容器:显示容器日志”
  3. 验证数据库凭据与环境变量匹配

获取帮助​

如果您遇到问题:

  1. 检查容器日志: 视图 → 输出 → 选择“开发容器”
  2. 无缓存构建: “开发容器:无缓存重新构建容器”
  3. 查看常见Docker问题
  4. 在Discord #help-desk-support频道中寻求帮助

移动开发​

虽然开发容器专注于服务器和Web开发，但您可以连接移动应用程序进行测试:

连接iOS/Android应用程序​

  1. 确保API可访问:

    # 查找您的机器IP
    # macOS
    ipconfig getifaddr en0
    # Linux
    hostname -I
    # Windows（在WSL2中）
    ip addr show eth0

  2. 配置移动应用:

    • 服务器URL: http://YOUR_IP:2283/api
    • 确保防火墙允许端口2283

  3. 完整的移动开发, 请查看 移动开发指南，内容涵盖:

    • Flutter设置
    • 在模拟器/设备上运行
    • 专属于移动设备的调试

高级配置​

自定义VS Code扩展​

在 .devcontainer/devcontainer.json 中添加扩展:

"customizations": {
  "vscode": {
    "extensions": [
      "your.extension-id"
    ]
  }
}

额外服务​

要添加服务（例如Redis Commander），修改以下文件:

  1. /docker/docker-compose.dev.yml - 添加服务定义
  2. /.devcontainer/server/container-compose-overrides.yml - 如果需要添加覆盖

资源限制​

调整Docker Desktop资源限制:

  • macOS/Windows: Docker Desktop → 设置 → 资源
  • Linux: 修改Docker daemon配置

推荐最低配置:

  • CPU: 4核
  • 内存: 8GB
  • 磁盘: 20GB

下一步​