Immich 是目前最像 Google Photos 的开源自托管相册：手机自动备份、时间线、人脸识别、语义搜索、共享相册一应俱全。这篇教程用官方 Docker Compose 在一台 2 核 4GB 的服务器上把它跑起来，并接上域名和 HTTPS。
一、准备条件
- 一台 Linux 服务器（Ubuntu 22.04 / Debian 12 均可），建议 2 核 4GB 起，照片存独立数据盘。
- 已安装 Docker 与 Docker Compose 插件：
docker --version、docker compose version能正常输出。 - 一个域名（例如
photos.example.com）并已解析到服务器；手机 App 后台备份需要 HTTPS。 - 放行
2283（测试）与80/443（正式）。
二、镜像与组件
| 组件 | 镜像 | 作用 |
|---|---|---|
| immich-server | ghcr.io/immich-app/immich-server:release | Web 与 API，端口 2283 |
| immich-machine-learning | ghcr.io/immich-app/immich-machine-learning:release | 人脸、物体、CLIP 模型推理 |
| database | ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0 | PostgreSQL + 向量扩展 |
| redis | docker.io/valkey/valkey:9 | 任务队列缓存 |
不要用 main 分支的 Compose 文件，版本必须和 Release 对齐。官方每次发版都会附带对应版本的 docker-compose.yml 与 example.env。
三、下载官方 Compose 并配置
mkdir -p /opt/immich && cd /opt/immich
wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env
编辑 .env，至少改这三项：
# 照片与视频的存放目录，换成你的数据盘
UPLOAD_LOCATION=/data/immich/library
# 数据库文件目录
DB_DATA_LOCATION=/data/immich/postgres
# 数据库密码，自己生成一个强密码
DB_PASSWORD=请替换成随机强密码
# 时区
TZ=Asia/Shanghai
docker-compose.yml 保持官方原样即可，核心服务长这样（节选）：
services:
immich-server:
image: ghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}
volumes:
- ${UPLOAD_LOCATION}:/data
- /etc/localtime:/etc/localtime:ro
env_file: [.env]
ports:
- '2283:2283'
depends_on: [redis, database]
restart: always
immich-machine-learning:
image: ghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}
volumes:
- model-cache:/cache
env_file: [.env]
restart: always
redis:
image: docker.io/valkey/valkey:9
restart: always
database:
image: ghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0
environment:
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_USER: ${DB_USERNAME}
POSTGRES_DB: ${DB_DATABASE_NAME}
volumes:
- ${DB_DATA_LOCATION}:/var/lib/postgresql/data
restart: always
启动：
docker compose up -d
docker compose ps
docker compose logs -f immich-server
看到 Immich Server is listening on ... 2283 就成功了。此时访问 http://服务器IP:2283 就能打开。
四、反向代理与 HTTPS
Immich 必须通过 HTTPS 才能让手机 App 稳定后台上传。Nginx 示例：
server {
listen 80;
server_name photos.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name photos.example.com;
ssl_certificate /etc/letsencrypt/live/photos.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/photos.example.com/privkey.pem;
# 视频上传必须放开，否则大文件会 413
client_max_body_size 50000M;
location / {
proxy_pass http://127.0.0.1:2283;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
# 大文件直传，不落 Nginx 临时盘
proxy_request_buffering off;
proxy_read_timeout 600s;
proxy_send_timeout 600s;
}
}
证书用 certbot 申请：certbot --nginx -d photos.example.com。
五、首次初始化
- 打开
https://photos.example.com，注册第一个账号，这个账号就是管理员。 - 进入「管理 → 设置 → 用户管理」，把「允许注册」关掉，改为管理员手动邀请家人。
- 手机安装 Immich App，服务器地址填
https://photos.example.com，登录后在「备份」里选择要同步的相册。 - 照片量大时，先让手机在 Wi-Fi 与充电状态下跑一晚；服务端会排队生成缩略图和 AI 索引。
六、备份、升级与迁移
- 备份：两样东西最关键 ——
UPLOAD_LOCATION里的原图，以及数据库。数据库用docker compose exec -t database pg_dumpall -U postgres > backup.sql导出，建议每天定时。 - 升级：先看 Release Notes 有没有破坏性变更，然后
docker compose pull && docker compose up -d。跨大版本（例如 1.x → 2.x）必须按官方升级说明逐步来。 - 迁移：在新机器上还原
UPLOAD_LOCATION与数据库，再启动同一版本的 Compose 即可。
七、常见问题
上传大视频报 413？ Nginx 的 client_max_body_size 没放开，改成 50000M 并 reload。
机器学习容器内存占用高？ 属于正常现象，模型常驻约 1GB。内存不足可在 Compose 里给 immich-machine-learning 加 mem_limit: 2g，或关掉部分智能功能。
手机 App 一直显示「服务器不可用」？ 检查是否用了 HTTPS、证书是否可信、X-Forwarded-Proto 是否传给后端。
八、小结
Immich 是「家庭相册」场景里功能最完整的选择，代价是对服务器和运维有一点要求。如果你想跳过折腾，我们也提供已实测的部署服务：环境安装、Compose 编排、HTTPS、手机端连通性一起交付，¥99 起，48 小时内完成。
