官方安装教程: https://immich.app/docs/install/docker-compose

基础信息

系统: 群晖 DSM 6.x
Host: 192.168.1.31|nas.yan.cn

安装

拉取最新配置文件

wget "https://gh-proxy.com/https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml"

wget -O .env https://gh-proxy.com/https://github.com/immich-app/immich/releases/latest/download/example.env

删除机器学习配置(可选)

编辑docker-compose.yml中immich-machine-learning相关配置

启动

sudo docker compose up -d
# or
sudo docker-compose up -d

镜像下载可能需要很久

使用

直接登录immich, 根据提示注册账号即可

上传图片可以界面操作, 也可以建一个批量上传, 有一个开源工具immich-go可以使用

  1. 准备api_key
    点击右上角用户名->账号设置->API密钥->创建API密钥, 根据所需权限进行勾选, 完成后会生成一段密钥:
    UME61o9RXWZr75wp5QnuhttjAR6bTGGlGQk8TBe0Rig
  2. 在release界面下载最新版本的程序包, 解压后得到immich-go

下面给出 2025-08 实测有效的「immich-go 批量上传」完整流程，涵盖

  1. 获取 API-Key
  2. 下载与鉴权
  3. 4 种常用上传场景（本地文件夹、嵌套子目录、Google-Takeout 压缩包、按日期过滤）
  4. 常见问题与加速技巧。
    全部命令复制即用，Windows / macOS / Linux 通用。

一、准备工作（只需做一次）

  1. 在 Immich Web 界面 → 头像 → 「API Keys」→ 「New Key」→ 复制字符串，假设为
    HFEJ38DNSDUEG……

  2. 下载对应系统二进制
    GitHub Release: https://github.com/simul/immich-go/releases
    以 Windows 为例，解压后得到 immich-go.exe；macOS/Linux 同理，下文统一用 immich-go 指代。

  3. 建议把二进制放到 PATH 或建立 alias，方便随时调用。

三、4 种典型批量上传场景

1. 本地单层目录（快速体验）
immich-go upload ./2024-photos/sudo immich-go upload from-folder --recursive --admin-api-key UME61o9RXWZr75wp5QnuhttjAR6bTGGlGQk8TBe0Rig --server http://nas.yan.cn:2283 /volume1/data/immich/ --concurrent-uploads 4

默认：

  • 自动计算 SHA256 去重
  • 遇到同名文件若服务器已存在则跳过
  • 不上传隐藏文件（Thumbs.db、.@__thumb 等）

2. 含子目录 / 希望按文件夹名自动建相册

immich-go upload --recursive --album "./全家桶/"

说明：

  • --recursive 递归所有子文件夹
  • --album 让 immich-go 把「每个文件夹」在 Immich 里创建成同名相册，并自动把照片归进去，省去 Web 端手动整理。

3. 直接读取 Google Takeout 多卷压缩包（无需手动解压）

把 Google 导出的 takeout-001.zip takeout-002.zip … 放在同一目录，执行：

immich-go upload from-google-photos "takeout-*.zip"

特性：

  • 自动读取 JSON 元数据，还原拍摄时间、GPS、相册名称
  • 识别 Live Photo（.mov+/jpg）、RAW+JPEG 堆栈
  • 去重、补传、断点续传：中断后重跑同一命令即可。

4. 只传最近 30 天，且跳过 RAW

immich-go upload \
  --recursive \
  --date-after 2025-08-01 \
  --ignore "**/*.CR3" \
  ./DCIM/

常用过滤 flag

  • --date-before YYYY-MM-DD
  • --date-after YYYY-MM-DD
  • --ignore "glob" 可多次出现

四、Dry-run 先验算（强烈推荐）

正式上传前先跑一把「演习」，确认文件数、相册名、重复项：

immich-go upload --dry-run --recursive --album "./全家桶/"

观察输出：
Images: 4820 Videos: 1030 Discarded: 12 Duplicates: 127
确认无误后去掉 --dry-run 正式跑。

五、上传中断 / 续传 / 性能调优

  1. 续传：重新执行相同命令即可，immich-go 会先向服务器查询哈希，已存在则秒跳。
  2. 多实例：如果服务器在局域网，可开 2-3 个终端同时跑不同目录（immich-go 进程级并行）。
  3. 关闭哈希计算（高带宽场景）：
    immich-go upload --skip-hash …
    可节省本地 CPU，但 Immich 服务端仍会再算一次哈希做去重。
  4. 大文件 / 慢网络：
    在 Immich 反向代理（Nginx/Apache）加
    client_max_body_size 0; proxy_read_timeout 300;
    避免 413/502 错误。

六、常见报错速查

报错 原因 解决
401 Unauthorized API-Key 错或失效 重新 login
413 Request Entity Too Large 反向代理限制 按本文「五-4」调大
tls: certificate verify 自签证书 immich-go login --insecure …
进度条长时间 0% 正在比对/拼图 大库耐心等，或先小目录试跑

七、一键备份脚本示例（Linux / macOS）

#!/usr/bin/env bash
set -eu
SRC_DIR="/mnt/nas/photo"
LOG_DIR="$HOME/immich-log"
mkdir -p "$LOG_DIR"

immich-go upload \
  --recursive \
  --album \
  --date-after "$(date -d '7 days ago' +%F)" \
  "$SRC_DIR" \
  > "$LOG_DIR/upload_$(date +%F_%T).log" 2>&1

echo "Done, log saved to $LOG_DIR"

配合 cron 即可实现「增量备份最近一周」。

至此，无论是一次性迁移多年老照片，还是日常增量备份，immich-go 都能稳定、快速、断点续传地完成。祝上传顺利！

immich-go帮助手册:

An alternative to the immich-CLI command that doesn't depend on nodejs installation. It tries its best for importing google photos takeout archives.

Usage:
  immich-go [command]

Available Commands:
  archive     Archive various sources of photos to a file system
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  stack       Update Immich for stacking related photos
  upload      Upload photos to an Immich server from various sources
  version     Give immich-go version

Flags:
  -h, --help               help for immich-go
  -l, --log-file string    Write log messages into the file
      --log-level string   Log level (DEBUG|INFO|WARN|ERROR), default INFO (default "INFO")
      --log-type string    Log formatted  as text of JSON file (default "text")
  -v, --version            version for immich-go

Use "immich-go [command] --help" for more information about a command.

升级

备份

参考 https://docs.immich.app/guides/template-backup-script

常用

  1. 一键下载所有文件
    sudo immich-go archive from-immich --from-api-key qUgKtSam7TiaZMYSPAEWzrHvGWIHvfISkB7VQowUmkI --from-server http://192.168.1.31:2283 -w /volume1/data/immich

最佳实践

背景

由于我使用了synology photos作为主力相册, 因此immich需要使用文件夹模式, 这样可以方便的进行双向同步.
假设我的synology photos共享目录在:/volume2/photo
那么应该修改docker-compose.yml文件:

# https://docs.immich.app/features/libraries
  immich-server:
    volumes:
      - ${UPLOAD_LOCATION}:/data
+     - /volume2/photo:/mnt/media/photo:ro
+     - /home/user/old-pics:/mnt/media/old-pics:ro
+     - /mnt/media/videos:/mnt/media/videos:ro
+     - /mnt/media/videos2:/mnt/media/videos2 # WARNING: Immich will be able to delete the files in this folder, as it does not end with :ro
+     - "C:/Users/user_name/Desktop/my media:/mnt/media/my-media:ro" # import path in Windows system.

也就是说将所有目标系统文件夹挂载到/mnt/media/photo下, 并且官方建议保持只读, 之后启动容器, 登录后打开系统设置>外部图库,点击添加目录, 填入/mnt/media/photo, 再点击上方扫描: