点击展开更新日志

2025

08-11

Created

nexttime

会有些什么呢(❁´◡`❁)

源起

因为想折腾不想用威联通自带的相册管理软件，因此经过浅浅的搜索，决定部署 immich。

本文所用的 docker-compose.yml 是实际跑过的，因此基本不会存在什么大问题（如果遇到了其它问题，那就遇到了吧。。），请善用搜索引擎及大模型，特别是 GitHub issue，会很有帮助。

部署环境

  • 硬件环境

    • CPU：n7505 2C4T，核显
    • 内存：32G
    • 硬盘：100G

  • 软件环境

    • 底层系统：PVE9.0.3
    • OS：Debian13 trixie
    • 虚拟化容器：LXC 非特权模式
    • Docker：28.3.3

部署

创建数据目录

根据你的喜好决定数据目录位置！

1
2
mkdir -p /data/docker/immich
cd /data/docker/immich

下载部署文件

docker-compose.yml

官方 docker-compose.yml：

1
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml

建议调整项：

  • immich-machine-learning 开启硬件加速
    • 更新镜像
    • 取消 hwaccl 注释
  • 添加自定义网络，如 immich
  • 如果是 HDD，取消 database 相关注释

🍀：关于模型如果有条件是建议在 immich 后台修改直接下载的，如果不行就只能找一下网上第三方的下载地址，然后拷贝到挂载目录。

.env

1
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env
  • 修改时区：TZ=Asia/Shanghai
  • 修改数据库密码：注意建议仅使用大小写字母和数字

hwaccel.ml.yml

如果需要使用 GPU 加速机器学习，还需要进行额外配置。

以 Intel 核显为例：

  1. 下载配置：

    1
    wget https://github.com/immich-app/immich/releases/latest/download/hwaccel.ml.yml

  2. 在 immich-machine-learning 下的 docker-compose.yml 中，取消注释 extends 部分并将 cpu 更改为适当的后端，这里是 openvino

  3. immich-machine-learning 中，在镜像末尾添加 -openvino 以使用硬件加速镜像

如果配置了智能搜索检查日志存在错误：

No GPU device found in OpenVINO. Falling back to CPU.

可能需要修改 hwaccel.ml.yml，在 openvino 下新增环境变量和 group_add ：

1
2
3
4
5
6
7
8
9
10
11
12
13
openvino:
    environment:
      - NEOReadDebugKeys=1
      - OverrideGpuAddressSpace=48
    device_cgroup_rules:
      - 'c 189:* rmw'
    group_add:
      - "44"
      - "104"
    devices:
      - /dev/dri:/dev/dri
    volumes:
      - /dev/bus/usb:/dev/bus/usb

部署

1
2
3
4
5
# 建议先用这个命令检查启动是否正常
docker compose up 

# 后台运行
docker compose up -d

immich cli

官方文档在这里：Immich CLI

简单使用：

安装

1
2
3
# 卸载旧版本
npm uninstall -g immich
npm i -g @immich/cli

登录认证：

1
2
3
4
# 1. 从账户设置获取 API Key

# 2. 登录
immich login http://localhost:2283/api <API_KEY>

命令行参数

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
$ immich
Usage: immich [options] [command]

Command line interface for Immich

Options:
  -V, --version                       output the version number
  -d, --config-directory <directory>  Configuration directory where auth.yml will be stored (default: "~/.config/immich/", env:
                                      IMMICH_CONFIG_DIR)
  -u, --url [url]                     Immich server URL (env: IMMICH_INSTANCE_URL)
  -k, --key [key]                     Immich API key (env: IMMICH_API_KEY)
  -h, --help                          display help for command

Commands:
  login|login-key <url> <key>         Login using an API key
  logout                              Remove stored credentials
  server-info                         Display server information
  upload [options] [paths...]         Upload assets
  help [command]                      display help for command

上传命令选项

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Usage: immich upload [paths...] [options]

Upload assets

Arguments:
  paths                       One or more paths to assets to be uploaded

Options:
  -r, --recursive             Recursive (default: false, env: IMMICH_RECURSIVE)
  -i, --ignore <pattern>      Pattern to ignore (env: IMMICH_IGNORE_PATHS)
  -h, --skip-hash             Don't hash files before upload (default: false, env: IMMICH_SKIP_HASH)
  -H, --include-hidden        Include hidden folders (default: false, env: IMMICH_INCLUDE_HIDDEN)
  -a, --album                 Automatically create albums based on folder name (default: false, env: IMMICH_AUTO_CREATE_ALBUM)
  -A, --album-name <name>     Add all assets to specified album (env: IMMICH_ALBUM_NAME)
  -n, --dry-run               Don't perform any actions, just show what will be done (default: false, env: IMMICH_DRY_RUN)
  -c, --concurrency <number>  Number of assets to upload at the same time (default: 4, env: IMMICH_UPLOAD_CONCURRENCY)
  -j, --json-output           Output detailed information in json format (default: false, env: IMMICH_JSON_OUTPUT)
  --delete                    Delete local assets after upload (env: IMMICH_DELETE_ASSETS)
  --no-progress               Hide progress bars (env: IMMICH_PROGRESS_BAR)
  --watch                     Watch for changes and upload automatically (default: false, env: IMMICH_WATCH_CHANGES)
  --help                      display help for command```

迁移备份

20250817: 已实际测试可以使用以下操作完成数据完整迁移。

数据库备份

进入 docker 容器

1
pg_dumpall -U postgres -h localhost -p 5432 2> "/tmp/error.log" | gzip > immich_postgres_dump_$(date +%Y%m%d).sql.gz

文件备份

打包 library 目录即可：

1
tar -zcvf library.tar.gz library/

传输数据

  1. 将以上备份的数据库和文件拷贝到新的服务器 immich 数据目录下
  2. 将 docker-compose.yml、.env、hwaccel.ml.yml 拷贝到新的服务器 immich 数据目录下

恢复数据备份

执行以下命令恢复备份（注意操作及顺序）：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 此时应该还没有创建容器，有的话就删除，包括数据
docker compose down -v

# 拉取镜像
docker compose pull

# 创建容器，先不启动
docker compose create

# 启动 postgres
docker start immich_postgres

# 导入数据
gunzip --stdout "dump.sql.gz" | sed "s/SELECT pg_catalog.set_config('search_path', '', false);/SELECT pg_catalog.set_config('search_path', 'public, pg_catalog', true);/g" | docker exec -i immich_postgres psql --dbname=postgres --username=postgre

# 恢复文件
tar -zxvf library.tar.gz

# 启动容器
docker compose up -d

问题处理

openvino 不工作

解决方案是修改 hwaccel.ml.yml ，增加相关环境变量配置。

参考 issue

报错信息：

1
pthread_setaffinity_np failed for thread: 19, index: 0, mask: {2, 3, }, error code: 22 error msg: Invalid argument. Specify the number of threads explicitly so the affinity is not set

解决方案是 .env 添加一个环境变量：

1
MACHINE_LEARNING_MODEL_INTRA_OP_THREADS=2

参考 issue

升级2.2版本照片不显示

现象：相册及首页照片不显示

原因：F12看到是因为 CSP 策略阻止了WebAssembly模块的编译：

1
CompileError: WebAssembly.Module(): Compiling or instantiating WebAssembly module violates the following Content Security policy directive because 'unsafe-eval' is not an allowed source of script in the following Content Security Policy directive:

解决方案：修改 CSP 策略，可以直接注释掉 Content-Security-Policy 相关配置，不放心可以在 server 块下添加如下配置：

1
add_header Content-Security-Policy "script-src 'self' 'wasm-unsafe-eval'; object-src 'self';" always;

重新刷新页面即可。这里有个笨b一直在改其它网站的 Content-Security-Policy，还说怎么不生效，我不说是谁。