使用 Dev Containers 進行開發

Dev Containers 使用 Docker 容器提供了一致且可重現的開發環境。只需單擊一下，您即可在 Mac、Linux、Windows 或使用 GitHub Codespaces 的雲端環境中開始 Immich 開發環境。

快速開始！

了解更多關於 Dev Containers 的信息

必備條件

在開始之前，確保您已經具備：

Docker Desktop（最新版本）
- Mac
- Windows（推薦使用 WSL2 後端）
- Linux
Visual Studio Code 和 Dev Containers 擴展
用於複製儲存庫的 Git
至少 8GB RAM（建議 16GB）
20GB 的可用磁碟空間

替代的開發環境

雖然本指南主要介紹使用 VS Code，但您有許多選擇來進行 Dev Container 開發：

本地編輯器：

IntelliJ IDEA - 全面的 JetBrains IDE 支援
neovim - 輕量級基於終端的編輯器
Emacs - 可擴展的文本編輯器
DevContainer CLI - 命令行界面

基於雲的解決方案：

GitHub Codespaces - 與 GitHub 完全集成，擁有優秀的 devcontainer.json 支援
GitPod - SaaS 平台，最近支援 Dev Container（過去主要使用 gitpod.yml）

可自行托管的選項：

Coder - 面向企業，需要 Terraform 知識，自我管理
DevPod - 僅限客戶端的工具，擁有優秀的 devcontainer.json 支持，可與任何供應商（本地，雲端或內部部署）一起使用

Dev Container 服務

Dev Container 環境包含以下服務：

服務	容器名稱	描述	端口
服務器與網頁	`immich-server`	在開發模式下運行 API 服務器和網頁前端	2283 (API) 3000 (網頁) 9230 (工作線程調試) 9231 (API 調試)
數據庫	`database`	PostgreSQL 數據庫	5432
快取	`redis`	快取服務器	6379
機器學習	`immich-machine-learning`	Immich 機器學習模型推理服務	3003

快速入門

第一步：複製儲存庫

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

第二步：配置環境變數

immich dev containers 從您的 shell 環境讀取環境變數，而不是從 .env 文件。這樣它們可以在雲端環境中無需預配置即可運行。

配置

在本地運行時，如果您希望創建（或使用現有的）DB 和/或照片存儲文件夾，您必須在啟動 Dev Container 之前於 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

第三步：啟動 Dev Container

提示

Immich 開發大規模使用了專用的基礎映像用於其基於 docker-compose 的開發。因此，您無法使用 VSCode 的 Clone Repository in a Container Volume 命令。

使用 VS Code 介面：

在 VS Code 中打開複製的儲存庫
按下 F1 或 Ctrl/Cmd+Shift+P 打開命令面板
輸入並選擇「Dev Containers: Rebuild and Reopen in Container」
從列表中選擇「Immich - Backend, Frontend and ML」
等待容器構建並啟動（第一次運行可能需要幾分鐘）

使用 VS Code 快捷操作：

在 VS Code 中打開儲存庫
您應該會看到彈窗詢問是否在容器中重新打開
點擊「Reopen in Container」

使用命令行：

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

環境變數詳情

Dev Containers 如何處理環境變數

與基於 Docker Compose 的 Immich 開發設置使用 .env 文件不同，Immich Dev Containers 從您的 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_PASSWORD`	`postgres`	PostgreSQL 密碼
`DB_USERNAME`	`postgres`	PostgreSQL 用戶名
`DB_DATABASE_NAME`	`immich`	數據庫名稱

設置環境變數

將這些變數添加到您的 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 密鑰和驗證

要在 Dev Container 中使用您的 SSH 密鑰來訪問 GitHub：

在主機機器上啟動 SSH 代理：

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

VS Code 自動將您的 SSH 代理轉發到容器中

欲了解詳細說明，請參考 VS Code 在容器中共享 Git 憑據指南。

提交簽名

要使用您的 SSH 密鑰進行提交簽名，請參考 GitHub 提交簽名指南。

開發工作流

自動化設置

當 Dev Container 啟動時，它會自動完成以下操作：

運行 post-create 腳本（container-server-post-create.sh）：
- 調整 node 使用者的文件權限
- 安裝依賴：在所有包中執行 npm install
- 構建 TypeScript SDK：執行 npm run build 在 open-api/typescript-sdk 中
通過 VS Code 任務啟動開發服務：
- Immich API Server (Nest) - API 服務器，熱重載，埠號 2283
- Immich Web Server (Vite) - 網頁前端，熱重載，埠號 3000
- 上述服務均會監聽文件更改並自動重新編譯
配置埠轉發：
- 網頁界面：http://localhost:3000（自動打開）
- API：http://localhost:2283
- 調試埠：9230（多工器），9231（API）

信息

Dev Container 的設置取代了傳統設置中的 make dev 命令。打開容器時，所有服務會自動啟動。

訪問服務

啟動後，您可以訪問：

服務	URL	描述
網頁界面	http://localhost:3000	主網頁界面
API	http://localhost:2283	REST API 端點 (不直接使用，網頁界面將通過 http://localhost:3000/api 暴露該端點)
數據庫	localhost:5432	PostgreSQL（用戶名：`postgres`）(不直接使用)

連接移動應用

要將移動應用連接到您的 Dev Container：

查找您機器的 IP 地址
在移動應用中，使用：http://YOUR_IP:3000/api
確保防火牆允許埠號 2283 的連接

進行代碼更改

服務器代碼 (/server)：變更將觸發自動重啟
網頁代碼 (/web)：變更將觸發熱模組替換
資料庫遷移：在 server 目錄下執行 npm run sync:sql
API 改變：使用 make open-api 重新生成 TypeScript SDK

測試

執行測試

Dev Container 支援多種方式執行測試：

使用 Make 命令（推薦）

# 執行特定組件的測試
make test-server         # Server 單元測試
make test-web           # Web 單元測試
make test-e2e           # 端到端測試
make test-cli           # CLI 測試

# 執行全部測試
make test-all           # 執行所有組件的測試

# 中型測試（整合測試）
make test-medium-dev    # 端到端測試

使用 NPM

# Server 測試
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     # 監看模式

# E2E 測試
cd /workspaces/immich/e2e
npm run test           # 執行 API 測試
npm run test:web       # 執行 Web 的 UI 測試

代碼質量命令

# 靜態檢查
make lint-server        # 靜態檢查 Server 代碼
make lint-web          # 靜態檢查 Web 代碼
make lint-all          # 靜態檢查所有組件代碼

# 格式化
make format-server      # 格式化 Server 代碼
make format-web        # 格式化 Web 代碼
make format-all        # 格式化所有代碼

# 型別檢查
make check-server       # 型別檢查 Server
make check-web         # 型別檢查 Web
make check-all         # 檢查所有組件

# 完整的清潔檢查
make hygiene-all       # 執行靜態檢查、格式化、型別檢查、SQL 同步及安全檢查

附加的 Make 命令

# 構建命令
make build-server       # 构建 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    # 安裝 Server 依賴項
make install-web      # 安裝 Web 依賴項
make install-all      # 安裝所有依賴項

除錯

Dev Container 已預配置好除錯環境：

API Server 除錯：
- 在 VS Code 中設置斷點
- 按 F5 或使用「運行與除錯」面板
- 選擇「Attach to Server」配置
- 除錯端口：9231
Worker 除錯：
- 使用「Attach to Workers」配置
- 除錯端口：9230
Web 除錯：
- 使用瀏覽器的開發工具
- 支援 VS Code 的 Chrome/Edge 擴展程式除錯功能

疑難解答

常見問題

權限錯誤

問題：出現 EACCES 或權限被拒絕的錯誤 解決方案：

Dev Container 以 node 使用者（UID 1000）運行
如果主機 UID 不同，可能會看到權限問題
嘗試重建容器：「Dev Containers: Rebuild Container」

容器無法啟動

問題：Dev Container 無法啟動或構建 解決方案：

確保 Docker 已運行：docker ps
清理 Docker 資源：docker system prune -a
檢查磁碟空間是否足夠
檢查 Docker Desktop 的資源限制

端口已被佔用

問題：出現「Port 3000/2283 is already in use」 解決方案：

檢查衝突的服務：lsof -i :3000（macOS/Linux）
停止衝突的服務或更改端口映射
重啟 Docker Desktop

上傳位置未設置

問題：出現關於缺少 UPLOAD_LOCATION 的錯誤 解決方案：

設置環境變數：export UPLOAD_LOCATION=./Library
將其添加到 Shell 配置檔以持久化
重啟終端和 VS Code

資料庫連接失敗

問題：無法連接到 PostgreSQL 解決方案：

確保所有容器都在運行：docker ps
檢查日誌：「Dev Containers: Show Container Log」
確認資料庫憑證與環境變數匹配

獲得幫助

如果遇到問題：

檢查容器日誌：查看 → 輸出 → 選擇「Dev Containers」
無緩存重建：「Dev Containers: Rebuild Container Without Cache」
查看 Docker 常見問題解答
在 Discord 的 #help-desk-support 頻道尋求幫助

移動應用程式開發

Dev Container 著重於 Server 和 Web 開發，您可以連接移動應用程式進行測試：

連接 iOS/Android 應用程式

確保 API 是可訪問的：

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

配置移動應用程式：
- Server URL: http://YOUR_IP:2283/api
- 確保防火牆允許端口 2283
完整移動開發指南，請參考移動開發指南，內容包括：
- Flutter 配置
- 在模擬器/設備上運行
- 移動專屬的除錯

高級配置

自定義 VS Code 擴展程式

將擴展程式添加到 .devcontainer/devcontainer.json：

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

附加服務

如需添加服務（例如 Redis Commander），請修改：

/docker/docker-compose.dev.yml - 添加服務定義
/.devcontainer/server/container-compose-overrides.yml - 如果需要，添加覆蓋項

資源限制

調整 Docker Desktop 的資源限額：

macOS/Windows：Docker Desktop → Settings → Resources
Linux：修改 Docker 守護程式配置

推薦最低配置：

CPU：4 核心
記憶體：8GB
磁碟空間：20GB

下一步

閱讀架構概覽
瞭解資料庫遷移
探索 API 文檔
加入 Discord 中的 #immich 頻道

必備條件​

Dev Container 服務​

快速入門​

第一步：複製儲存庫​

第二步：配置環境變數​

第三步：啟動 Dev Container​

使用 VS Code 介面：​

使用 VS Code 快捷操作：​

使用命令行：​

環境變數詳情​

Dev Containers 如何處理環境變數​

上傳位置路徑解析​

數據庫配置​

設置環境變數​

Git 配置​

SSH 密鑰和驗證​

提交簽名​

開發工作流​

自動化設置​

訪問服務​

連接移動應用​

進行代碼更改​

測試​

執行測試​

使用 Make 命令（推薦）​

使用 NPM​

代碼質量命令​

附加的 Make 命令​

除錯​

疑難解答​

常見問題​

權限錯誤​

容器無法啟動​

端口已被佔用​

上傳位置未設置​

資料庫連接失敗​

獲得幫助​

移動應用程式開發​

連接 iOS/Android 應用程式​

高級配置​

自定義 VS Code 擴展程式​

附加服務​

資源限制​

下一步​