majorfi/immich-stack

Immich Stack

镜像概述和主要用途

Immich Stack 是一个基于 Go 的命令行工具和库，用于在 Immich 照片管理系统中自动将相似照片分组（"堆叠"）。它通过 Immich API 提供可配置、稳健且可扩展的逻辑，实现照片的分组、排序和堆叠管理。该项目深受 https://github.com/tenekev/immich-auto-stack 启发。

核心功能和特性

• 自动堆叠：基于文件名、日期和自定义条件将相似照片分组为堆叠
• 可配置分组：通过环境变量和命令行标志支持自定义分组逻辑
• 父子文件优先级：通过文件名子串或扩展名精细控制堆叠中父文件的优先级
• 命令行工具：支持批量处理和自动化操作的命令行界面
• 安全操作：支持模拟运行（dry-run）模式、堆叠替换和重置功能，并需用户确认
• 全面日志：彩色结构化日志记录所有操作
• 模块化设计：表格驱动测试、模块化辅助函数和清晰的职责分离

使用场景和适用范围

适用于使用 Immich 管理大量照片的用户，特别是需要自动整理相似照片（如同一事件拍摄的多张照片、编辑版本与原始版本、不同格式的同一场景照片等）的场景。支持单次运行和定时任务两种模式，满足即时整理和定期维护需求。

使用方法和配置说明

快速开始

bash
# 创建 .env 文件
cat > .env << EOL
API_KEY=你的_immich_api密钥
API_URL=http://immich-server:2283/api
RUN_MODE=cron
CRON_INTERVAL=60
EOL

# 使用 Docker Hub 运行
docker run -d --name immich-stack --env-file .env -v ./logs:/app/logs majorfi/immich-stack:latest

# 或使用 GitHub 容器注册表
docker run -d --name immich-stack --env-file .env -v ./logs:/app/logs ghcr.io/majorfi/immich-stack:latest

环境变量

Docker Compose 配置

yaml
version: "3.8"

services:
  immich-stack:
    container_name: immich_stack
    # 使用 Docker Hub 镜像（Portainer 推荐）
    image: majorfi/immich-stack:latest
    # 或使用 GitHub 容器注册表
    # image: ghcr.io/majorfi/immich-stack:latest
    environment:
      - API_KEY=${API_KEY}
      - API_URL=${API_URL:-http://immich-server:2283/api}
      - DRY_RUN=${DRY_RUN:-false}
      - RESET_STACKS=${RESET_STACKS:-false}
      - REPLACE_STACKS=${REPLACE_STACKS:-false}
      - PARENT_FILENAME_PROMOTE=${PARENT_FILENAME_PROMOTE:-edit}
      - PARENT_EXT_PROMOTE=${PARENT_EXT_PROMOTE:-.jpg,.dng}
      - WITH_ARCHIVED=${WITH_ARCHIVED:-false}
      - WITH_DELETED=${WITH_DELETED:-false}
      - RUN_MODE=${RUN_MODE:-once}
      - CRON_INTERVAL=${CRON_INTERVAL:-86400}
    volumes:
      - ./logs:/app/logs
    restart: on-failure

与 Immich Docker Compose 集成

要与现有 Immich 安装集成：

1. 将以下服务配置添加到 Immich 的 docker-compose.yml 中：

yaml
immich-stack:
  container_name: immich_stack
  image: ghcr.io/majorfi/immich-stack:latest
  environment:
    - API_KEY=${API_KEY}
    - API_URL=${API_URL:-http://immich-server:2283/api}
    - DRY_RUN=${DRY_RUN:-false}
    - RESET_STACKS=${RESET_STACKS:-false}
    - REPLACE_STACKS=${REPLACE_STACKS:-false}
    - PARENT_FILENAME_PROMOTE=${PARENT_FILENAME_PROMOTE:-edit}
    - PARENT_EXT_PROMOTE=${PARENT_EXT_PROMOTE:-.jpg,.dng}
    - WITH_ARCHIVED=${WITH_ARCHIVED:-false}
    - WITH_DELETED=${WITH_DELETED:-false}
    - RUN_MODE=${RUN_MODE:-once}
    - CRON_INTERVAL=${CRON_INTERVAL:-86400}
  volumes:
    - ./logs:/app/logs
  restart: on-failure
  depends_on:
    immich-server:
      condition: service_healthy

2. 在 Immich 的 .env 文件中添加环境变量：

sh
# Immich Stack 设置
API_KEY=你的_immich_api密钥
API_URL=http://immich-server:2283/api  # 使用内部 Docker 网络
RUN_MODE=once  # 选项：once（单次）, cron（定时）
CRON_INTERVAL=86400  # 秒数，仅在 RUN_MODE=cron 时使用

3. 重启 Immich 服务：

sh
docker compose down
docker compose up -d

堆叠逻辑

分组规则

• 默认条件：按基础文件名（扩展名前部分）和本地拍摄时间分组
• 自定义条件：通过 --criteria 标志或 CRITERIA 环境变量覆盖默认分组规则

排序规则

• 文件名优先级：通过 PARENT_FILENAME_PROMOTE（逗号分隔的子串）提升包含特定子串的文件为父文件
• 扩展名优先级：通过 PARENT_EXT_PROMOTE（逗号分隔的扩展名）进一步优先选择特定扩展名的文件
• 内置扩展名优先级：.jpeg > .jpg > .png > 其他格式
• 字母顺序：作为最终的排序决胜因素

示例

对于文件：L1010229.JPG、L1010229.edit.jpg、L1010229.DNG，当设置 PARENT_FILENAME_PROMOTE=edit 和 PARENT_EXT_PROMOTE=.jpg,.dng 时，排序结果为：

L1010229.edit.jpg
L1010229.JPG
L1010229.DNG

开发构建

bash
# 本地构建
docker build -t immich-stack .

# 本地运行
docker run -d \
  --name immich-stack \
  --env-file .env \
  -v ./logs:/app/logs \
  immich-stack