Immich：把手机相册搬回自己家（从零部署，不写一行代码）

读者假设：会用电脑、能敲命令行，但没部署过服务。 需要准备：一台常年开机的电脑（旧笔记本/NAS/小主机都行）+ 40 分钟。 全程四条命令，没有一行需要你改代码。

一、为什么值得折腾这一趟

先算笔账：手机相册 200 GB，iCloud 2TB 方案每月几十块，一年下来够买一块 1TB 的固态硬盘。更麻烦的是：

• 换平台搬不走（安卓 ↔ iPhone 互传像过海关）
• 想批量导出，得一批批点
• 照片里的人和地点，等于交给了别人

Immich 就是干这件事的开源项目：自己电脑上跑一个服务，手机 App 自动把照片传回来，界面体验接近主流云相册——时间线、人脸分组、地图、以图搜图、共享相册都有。

它不是我随便找的小项目：GitHub 上 7 万多星，更新非常勤，社区活跃。下面给的都是官方部署方式，我只是把每一步的坑标出来。

二、它能干什么、不能干什么

能：

不能 / 要注意：

• 它不是网盘，别拿它存文档、电影
• 想把照片从 Immich 搬去别处，官方提供导出，但不是一键迁移到 iCloud
• 人脸识别这类 AI 功能吃内存，小机器建议关掉

三、先看硬件够不够

ARM 设备（比如部分 NAS、树莓派）也能跑，但机器学习容器可能不可用，人脸识别会关掉，其它功能正常。

四、第一步：装 Docker

Immich 官方只提供容器镜像，所以先有 Docker。别被"容器"两个字吓到，它就是个"装好就能跑的软件包"。

Windows

1. 打开 https://www.docker.com/products/docker-desktop/ 下载 Docker Desktop for Windows
2. 双击安装，一路下一步；安装过程会要求启用 WSL2，点同意
3. 装完重启电脑
4. 打开 Docker Desktop，左下角出现绿色 Engine running 就绪

验证：按 Win + R 输入 cmd，敲：

docker --version
docker compose version

应该看到两行版本号：

Docker version 27.x.x, build ...
Docker Compose version v2.x.x

macOS

同样从上面的网址下 Docker Desktop for Mac（Intel 芯片选 Intel，M 系列选 Apple Silicon），装完在"应用程序"里打开，等鲸鱼图标变绿。

docker --version
docker compose version

Linux（Ubuntu / Debian）

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER     # 免 sudo，执行后要重新登录
docker --version

国内网络拉镜像慢的话，Docker Desktop 里配镜像加速器（Settings → Docker Engine），或给 Linux 配 /etc/docker/daemon.json。这一步不通，后面 docker compose up 会卡在 pulling。

五、第二步：建目录、下两个文件

Immich 的部署就是"一个 compose 文件 + 一个配置文件"，官方提供了现成模板。

1. 建一个专用文件夹

# macOS / Linux
mkdir -p ~/immich-app && cd ~/immich-app

:: Windows（在 cmd 里）
mkdir %USERPROFILE%\immich-app
cd %USERPROFILE%\immich-app

2. 下载官方模板

macOS / Linux：

curl -L -o docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
curl -L -o .env https://github.com/immich-app/immich/releases/latest/download/example.env

Windows（PowerShell）：

curl.exe -L -o docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
curl.exe -L -o .env https://github.com/immich-app/immich/releases/latest/download/example.env

万一命令报错（公司网络、GitHub 慢），最省事的办法是：把上面两个网址粘进浏览器，页面会直接下载文件，手动放进 immich-app 文件夹，再把 example.env 重命名成 .env。

你应该看到

ls -la

docker-compose.yml
.env

Windows 注意：文件名是 .env，不是 .env.txt。资源管理器里要点"查看 → 文件扩展名"确认一下，否则改错名会导致后面读不到配置。

六、第三步：改三行配置

用记事本 / VS Code 打开 .env，只需要改这三处（其它保持默认）：

# 照片和视频存放的位置
UPLOAD_LOCATION=./library

# 数据库密码，自己设一个强密码（别用 123456）
DB_PASSWORD=换成你自己的强密码

# 时区，影响照片时间显示
TZ=Asia/Shanghai

Windows 建议把 UPLOAD_LOCATION 改成绝对路径，否则容易因为盘符/权限问题写不进去：

UPLOAD_LOCATION=D:/photos/immich

（用正斜杠 /，别用反斜杠 \。）

三行里 DB_PASSWORD 最关键：第一次启动后再改它，数据库就连不上了。现在就定好，记在密码管理器里。

七、第四步：启动

docker compose up -d

第一次会下载 4 个镜像（服务端、机器学习、PostgreSQL、Redis），几百 MB 到 1 GB 不等，看你网速，5–20 分钟。

你应该看到

[+] Running 5/5
 ✔ Network immich-app_default      Created
 ✔ Container immich_redis          Started
 ✔ Container immich_postgres       Started
 ✔ Container immich_server         Started
 ✔ Container immich_machine_learning Started

检查状态：

docker compose ps

四个容器都应该是 Up 或 running。等 1–2 分钟让它建表，然后浏览器打开：

http://localhost:2283

（局域网里别的设备访问，把 localhost 换成本机内网 IP，比如 http://192.168.1.10:2283。）

首次进入

1. 点 Getting Started
2. 填邮箱、密码、姓名 → Sign up（第一个注册的就是管理员）
3. 进去后是空相册，正常

八、手机怎么连上

1. 应用商店搜 Immich（iOS App Store / Google Play 都有官方 App，图标是紫色渐变相机）
2. 打开 App，Server Endpoint URL 填：http://你的电脑内网IP:2283
   • 查内网 IP：Windows ipconfig 看"IPv4 地址"；macOS ipconfig getifaddr en0
3. 用刚才注册的账号登录
4. 进 设置 → 备份 → 选择相册 → 打开自动备份
5. 建议同时打开 Only charge（只在充电时传）和 Use cellular data 关闭，省流量省电

验证：回到电脑网页端刷新，应该能看到照片陆续冒出来。

九、在外网也能看（两种方案）

方案 A：Tailscale（推荐小白，零配置）

1. 服务器（就是跑 Immich 那台机器）和手机都装 Tailscale：https://tailscale.com/download
2. 两边登录同一个账号
3. 在 Tailscale 后台能看到服务器的 100.x.x.x 地址
4. 手机 App 里把 Server URL 改成 http://100.x.x.x:2283

好处：不用买域名、不用开端口、流量走加密隧道。缺点：每台设备都要装 Tailscale。

方案 B：域名 + Nginx 反代 + HTTPS

适合想给家人用、或者要公开访问的。要点三条：

location / {
    proxy_pass http://127.0.0.1:2283;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    client_max_body_size 50000m;      # 关键：上传大视频会用到
    proxy_request_buffering off;
}

1. client_max_body_size 不设，传大视频会 413
2. 证书用 certbot 或宝塔一键签
3. 不要把 2283 直接暴露在公网 HTTP 上，登录凭据会明文跑

十、升级与备份（这两件事不做，早晚后悔）

升级

cd ~/immich-app
docker compose pull
docker compose up -d

三行，数据保留。升级前先备份，尤其是跨大版本。

备份

Immich 的数据分两块：

照片目录直接拷走就行，它就是一个普通的文件夹结构。数据库建议 dump：

docker compose exec -T database pg_dumpall -c -U postgres > backup-$(date +%F).sql

容器名以 docker compose ps 显示为准，老版本可能叫 immich_postgres、数据库用户是 immich——报"role postgres does not exist"就把 -U postgres 换成 -U immich。

恢复

把照片目录放回原位，把 dump 导回去：

cat backup-2026-10-30.sql | docker compose exec -T database psql -U postgres

十一、九条最常见的坑

十二、下一步

跑起来之后，你大概率会想这两件事：

1. 自动备份到另一块硬盘——用 rsync 或 NAS 的同步任务，把 library 目录镜像出去
2. 给全家开账号——Immich 支持多用户，每个人独立时间线，可以建"家庭共享相册"

想监控这台机器上的服务有没有掉线，可以看后面要写的 Uptime Kuma 那篇。

十三、出处与参考

• 官网：https://immich.app/
• 官方文档（Docker Compose 安装）：https://docs.immich.app/install/docker-compose
• 源码仓库：https://github.com/immich-app/immich
• 官方 compose 模板：https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
• 官方环境变量模板：https://github.com/immich-app/immich/releases/latest/download/example.env
• Docker Desktop 下载：https://www.docker.com/products/docker-desktop/
• Tailscale：https://tailscale.com/download

本项目以 AGPL-3.0 许可开源。版本迭代很快，界面文案和容器名可能随版本变化，以官方文档为准；本文命令在 2026-10 的 release 分支镜像上验证过。