enarciso/immich-server

S3/MinIO 存储

Immich 可将所有 Immich 管理的媒体（原件、缩略图、生成视频、备份）存储在 S3 兼容对象存储中，而非本地 /data 卷。这在需要持久、可扩展存储和/或与服务器主机解耦存储时非常有用。

启用/禁用

• 通过将存储引擎设置为 s3 并通过环境变量提供 S3 详细信息来启用对象存储。
• 通过将引擎设置回 local 来禁用。不会自动删除任何数据；您可自行控制保留/清理内容。

必填变量（完整列表见 example.env）：

• IMMICH_STORAGE_ENGINE=s3
• S3_BUCKET=<您的存储桶名称>
• 可选变量：
  • S3_REGION=us-east-1
  • S3_PREFIX=<可选/路径/前缀>（存储桶下的文件夹）
  • 对于 MinIO 或路径样式端点：S3_ENDPOINT=http://minio:9000 和 S3_FORCE_PATH_STYLE=true
  • S3_ACCESS_KEY_ID
  • S3_SECRET_ACCESS_KEY（或使用 IAM）
  • S3_USE_ACCELERATE=false（AWS 传输加速，仅在存储桶启用时使用）
  • S3_SSE
  • 用于服务器端加密的 S3_SSE_KMS_KEY_ID

注意事项：

• 使用 S3 时不要设置 IMMICH_MEDIA_LOCATION。Immich 会自动推导 s3://<bucket>/<optional-prefix>。
• 当引擎为 s3 时，服务器容器的 /data 绑定挂载是可选的/未被使用的。

迁移（aws s3 sync）

此方法使用 AWS CLI 将现有本地数据复制到 S3，然后将 Immich 切换到 S3。通过在 Immich 仍运行时执行批量复制，然后快速切换，可减少停机时间。这也是运行数据库转储备份的好机会，以防需要恢复。

1. Immich 运行时批量同步

• 确定主机上的本地上传路径（挂载到服务器容器 /data 的 UPLOAD_LOCATION 文件夹）。
• 执行初始同步到 S3。首次同步避免使用 --delete。

bash
aws s3 sync /path/to/upload s3://<bucket>/<optional-prefix>/

2. 短时间停机、增量同步和切换

• 停止 Immich（或至少服务器）以暂停写入操作。
• 运行第二次同步以复制任何最近的更改。如要严格镜像，可选择添加 --delete。

bash
aws s3 sync /path/to/upload s3://<bucket>/<optional-prefix>/ [--delete]

• 更新环境以启用 S3（见上述变量），然后重启 Immich。
• 启动时，Immich 会检测新的媒体位置，并将存储的路径从之前的基础重写为 s3://<bucket>/<optional-prefix>。

3. 验证

• 浏览媒体库并下载一些项目。
• 检查服务器日志中的媒体位置迁移消息。
• 列出存储桶以确认内容布局：

bash
aws s3 ls s3://<bucket>/<optional-prefix>/backups/

4. 可选清理

• 确认切换成功后，可归档或删除 UPLOAD_LOCATION 下的旧本地数据。

S3 上的数据库备份

启用 S3 后，自动“创建数据库转储”作业会将 .sql.gz 备份写入以下路径：

s3://<bucket>/<optional-prefix>/backups/

Immich 会处理该前缀下的备份列表、保留和清理。

MinIO 及其他 S3 兼容端点

• 将 S3_ENDPOINT 设置为 HTTP(S) URL，并设置 S3_FORCE_PATH_STYLE=true。
• 不要启用 S3_USE_ACCELERATE。

回滚

• 设置 IMMICH_STORAGE_ENGINE=local 并重启。Immich 将继续使用本地 /data 卷。如有需要，可在切换前使用 aws s3 sync s3://<bucket>/<optional-prefix>/ /path/to/upload 将数据从 S3 同步回本地。