简单说，Immich 就是目前你能自己动手搭建的最强「私有版 Google Photos」。手机拍了照片后台无感自动备份、丝滑的瀑布流时间轴、智能人脸与地点聚类、全功能官方手机 App 同步，所有照片和元数据全完整留在你自己的服务器上。你既不用按月给各种云盘交扩容月费，也不必提心吊胆哪天服务商政策收紧甚至直接关停服务；不过丑话也说在前头，它为了保证检索和流媒体体验，架构设计相当完备，绝对不是那种单容器随手一跑就能搞定的小玩具。

口径说明：本文基于 2026-11-03 在真实 Linux 环境下的实操记录，适配官方最新的 Immich v3.3.5 版本。我们采用官方推荐的 Docker Compose「核心三件套」（主服务 Server + 定制版 Postgres 数据库 + 缓存）跑通了全流程：从容器起跑到注册管理员、走完初始化向导，再到顺利将真实照片上传进时间轴。为了兼顾小内存 VPS 或家用轻量 NAS，本次部署按小机器策略先关闭了独立的机器学习（Machine Learning）服务，正文会如实说明这套策略的资源收益与搜索功能影响。

成品长这样

只要服务配置妥当，通过浏览器或手机 App 就能立刻看到搭建完成的私有相册面板。上传照片后，系统会自动读取 EXIF 信息按拍摄日期排列呈现：

Immich 时间线里的第一张照片 — 图 1：照片上传完成，出现在时间线 Today 分组里

准备工作

动手写编排文件前，先把机器配置和关键路径规划好，避免后面踩坑返工：

硬件配置建议：在关闭机器学习服务的前提下，主机建议预留 4GB+ 内存；如果后续打算启用 AI 搜图和人脸归类，建议 8GB 起步，否则小内存机器极易在生成图像向量时遭遇 OOM 闪退。
存储空间规划：Immich 会原汁原味全量保存原始照片和视频，不会做损耗性压缩，务必根据你的家庭照片库总量给磁盘留足冗余空间。
环境依赖：宿主机需预先装好 Docker 运行环境以及 Docker Compose 插件。
划重点：专属数据库镜像：Immich 的语义搜索严重依赖特制向量插件，其数据库必须使用官方定制的 ghcr.io/immich-app/postgres:14-vectorchord... 镜像。千万别图省事拿 Docker 官方原版 postgres:14 顶替，否则由于缺少 VectorChord 扩展，服务启动建表时会当场报错瘫痪！
提前想好两个持久化目录：一个是数据库卷（如 /data/immich-pg），另一个是照片核心存放目录（UPLOAD_LOCATION，如 /data/immich-upload）。照片属于不可再生的个人数字资产，强烈建议这两个目录规划在独立、稳定的数据盘上。

第一步：Docker Compose 三件套

先在宿主机上建好刚才规划的存储目录，并确保具有读写权限：
BASH
```
mkdir -p /data/immich-upload /data/immich-pg
```

在任意部署目录下新建 docker-compose.yml 文件，填入如下精简的三件套编排配置：

services:
  immich-server:
    image: ghcr.io/immich-app/immich-server:v3.3.5
    container_name: immich_server
    restart: always
    depends_on:
      - database
      - redis
    environment:
      DB_HOSTNAME: database
      DB_PORT: 5432
      DB_USERNAME: postgres
      DB_PASSWORD: <MASKED_SECRET_001>
      DB_DATABASE_NAME: immich
      REDIS_HOSTNAME: redis
      UPLOAD_LOCATION: /data
      IMMICH_MACHINE_LEARNING_ENABLED: "false"
    volumes:
      - /data/immich-upload:/data
      - /etc/localtime:/etc/localtime:ro
    ports:
      - 2283:2283

  database:
    image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
    container_name: immich_postgres
    restart: always
    environment:
      POSTGRES_PASSWORD: <MASKED_SECRET_001>
      POSTGRES_USER: postgres
      POSTGRES_DB: immich
      POSTGRES_INITDB_ARGS: --data-checksums
    volumes:
      - /data/immich-pg:/var/lib/postgresql/data
    command: postgres -c config_file=/etc/postgresql/postgresql.conf

  redis:
    image: valkey/valkey:9
    container_name: immich_redis
    restart: always

注：官方目前现行推荐采用开源分叉镜像 valkey/valkey:9 担任高并发任务队列与缓存，如果你习惯使用传统 Redis，换成标准的 redis:7-alpine 亦完全兼容。

在 docker-compose.yml 所在目录执行后台拉取并启动：
BASH
```
docker compose up -d
```
验证服务健康状态。由于主服务容器初次启动时需要等待数据库初始化并自动执行表迁移，等待十几秒后在终端发起健康探测：
BASH
```
curl 127.0.0.1:2283/api/server/ping
```
终端返回 pong（或类似 {"res":"pong"} 的响应），即代表主服务、定制数据库与缓存之间握手完毕，服务端底座已正式就绪！

第二步：注册管理员并走初始化向导

容器跑起来后，直接用浏览器打开 http://你的服务器IP:2283。首次打开会看到欢迎页面，直接点击「Getting Started」进入管理员注册界面（Admin Registration）。在这里输入你的管理员邮箱、名字以及密码（需要确认输两遍），然后点击「Sign up」。这里特别提醒一句：系统里第一个注册成功的账号就是拥有最高权限的管理员，可别手快把账号搞丢了。

注册完成后页面会自动跳回登录页，输入刚才设置的账号密码登录，立刻就会进入一共 7 步的 Onboarding 首次使用向导。流程非常清晰：从主题偏好、界面语言、服务器隐私策略、用户隐私设置，一路走到存储模板（Storage Template）、数据备份和移动端引导。基本上按右下角的指引一步步点过去就行。不过在走到「存储模板」那一页时建议多留个心眼——它决定了你上传的照片在宿主机磁盘上按什么目录规则归档（比如按年/月分目录）。这个规则最好在正式大批量倒数据前想明白，因为一旦定下来，后续如果再去修改，默认只对新上传的文件生效，老文件不会自动搬家。

第三步：上传第一张照片

搞指向导后正式进入 Immich 主界面，呈现在眼前的是按日期排列的 Photos 照片时间线。测试一下最核心的功能：点击右上角的「Upload」按钮，从本地随便选一张 JPG 照片传上去。上传成功后后台会自动生成多尺寸缩略图，几秒钟内这张照片就会安安静静地躺在「Today」分组里。此时瞄一眼左下角，能看到当前部署的 Immich 版本号和绿色的「Server Online」在线状态，说明整套服务已经在稳定工作了。

私有云相册的灵魂在手机端：直接在应用商店下载 Immich 官方 App，服务器地址填入相同的 http://你的服务器IP:2283，用刚才的账号登录进去，顺手打开后台自动备份，手机里的照片就能在连上 Wi-Fi 时无感同步到你自己的机器里了。

踩坑实录

1. 绝不能用官方纯净版的普通 postgres 镜像
很多习惯自己搭服务的朋友喜欢顺手拉一个 postgres:16-alpine，在 Immich 这里必踩大雷。Immich 强依赖 VectorChord 等专用扩展来实现智能相册的高性能向量检索，普通官方镜像没有编译进这些插件，数据库启动执行初始化建扩展脚本时会当场暴毙退出。一定要认准 Immich 维护的专用 PG 镜像，其标签后面都带着特定扩展版本后缀。后续升级时，也要严格对照官方 compose 里的镜像标签一起换。

2. 机器学习服务先关掉省内存，但要想清楚代价
如果你的服务器配置比较紧凑（比如只有 2G 内存的小机器），可以在环境变量里加上 IMMICH_MACHINE_LEARNING_ENABLED=false 把 AI 容器关掉。关了之后相片存储、相册展示、视频转码和基础浏览全都不受影响，能大幅省下内存和 CPU；但代价也很明显——人脸聚合识别、宠物识别以及用自然语言「以文搜图」的 AI 功能全都无法使用。对于资源受限的机器，先关掉让核心服务跑起来是可行的方案；等后续升级了机器，随时把 compose 里的 immich-machine-learning 容器补回来、变量改回 true 就行，完全不需要推倒重装。

3. 照老教程写 redis 也能跑，但官方早已全面切换到 Valkey
在网上扒一些旧版本教程，经常能看到大家在 compose 里挂着 redis:7-alpine。虽然因为协议完全兼容，挂 Redis 目前确实能正常跑，但从上游生态来看官方已经全面转投 Valkey。新安装的实例强烈建议别再惯性使用 Redis，直接遵照官方最新的默认配置使用 valkey/valkey:9，避免后续核心组件依赖新特性时再做多余的迁移。

升级与备份

平时版本的维护非常平滑。升级时直接去 GitHub 翻阅 Immich 对应版本的 release 说明，把 compose.yaml 中主服务、机器学习和专用 PG 这三个镜像的 tag 改成目标新版本，执行 docker compose pull 拉下镜像，再 docker compose up -d 重新拉起即可。Immich 启动时会自动跑数据库 Migration，只要 Postgres 不跨越需要手动做数据倾倒的大版本，挂载的数据卷都可以一路平稳沿用。

想要照片高枕无忧，备份两件套缺一不可：第一是用 pg_dump 导出的 immich 数据库完整 SQL 转储（记录了相册关系、用户数据、资产元数据）；第二是你配置的 UPLOAD_LOCATION 对应的全量相片存储目录。数据库丢了元数据还能靠重新扫描文件挽回一部分，但如果底层的原始相片目录被误删，那就真的神仙难救了，所以照片目录务必搭配异地云备份做二次防灾。至于 Valkey / Redis，里面放的全是会话与临时任务队列等纯缓存数据，重启就重构，完全不需要耗费精力去备份。

Immich 安装教程：Docker Compose 三件套部署自托管相册（v3.3.5 实测）