从零部署Immich：打造私有云相册的完整实践指南

之前在做个人照片备份和管理时总是被各种云盘、手机自带相册和第三方工具搞得焦头烂额。要么是隐私担忧要么是功能单一要么是跨平台体验割裂。直到发现了 Immich一个开源的、自托管的 Google Photos 替代品它彻底改变了我的照片管理方式。本文将手把手带你从零开始在本地或服务器上部署 Immich并深入讲解其核心功能、配置优化以及常见问题的解决方案。无论你是想搭建一个私人的家庭照片库还是为团队项目寻找一个高效的媒体资产管理方案这套完整的实操指南都能让你快速上手实现照片管理效率的十倍提升。1. Immich 是什么为什么选择它在深入部署之前我们首先要理解 Immich 解决了什么问题以及它为何能在 GitHub 上获得超过 7 万颗星的关注。1.1 核心概念与定位Immich 是一个自托管的照片和视频备份解决方案。你可以把它理解为你自己完全掌控的“私有云相册”。它的设计目标非常明确提供一个功能上足以媲美 Google Photos 或 iCloud Photos 的体验但所有数据都存储在你自己的服务器或 NAS 上。这意味着数据主权你的所有原始照片、视频及其元数据都保存在你自己的硬件上无需担心第三方公司的隐私政策或服务终止风险。功能完整它并非一个简单的文件浏览器。它提供了时间线视图、人脸识别、地点地图、智能相册、重复检测、RAW 格式支持等高级功能。移动端优先拥有优秀的 iOS 和 Android 应用支持后台自动备份体验与商业应用无异。1.2 与同类方案的对比你可能会想到 Nextcloud、PhotoPrism、Piwigo 等工具。它们各有优劣Nextcloud是一个全能型的协同办公套件其相册功能是插件之一在照片管理的专业性和体验上不如 Immich 专注。PhotoPrism同样优秀但更偏向于“照片库管理”其备份流程和移动端体验在历史上不如 Immich 流畅。Piwigo更侧重于网络相册的展示和分享适合摄影师对外发布作品。Immich 的核心优势在于它在“自动备份”和“智能管理”之间取得了极佳的平衡。它从用户使用场景出发首先确保你能像使用手机原生相册一样无感地将照片备份到自己的服务器然后再通过强大的 AI 模型如 CLIP为你提供高效的搜索和管理能力。1.3 核心功能一览自动备份手机 App 在连接 Wi-Fi 或充电时自动上传新照片/视频。人脸识别与分组自动识别人脸并创建人物相册。对象与场景识别可以搜索“狗”、“海滩”、“生日蛋糕”等。地图视图基于照片的 GPS 信息在地图上显示拍摄地点。重复文件检测避免存储空间被重复内容浪费。RAW 格式支持保留专业摄影师的原始文件。共享相册与链接方便地与家人朋友分享。智能搜索基于自然语言的搜索例如“去年夏天在公园拍的照片”。理解了这些你就会明白为什么 Immich 能成为自托管照片管理领域的明星项目。接下来我们开始准备部署环境。2. 环境准备与部署说明Immich 官方推荐使用 Docker Compose 进行部署这是最简单、最不易出错的方式。它将所有依赖的服务数据库、机器学习引擎、Redis 等封装在一起。2.1 系统要求与前置条件最低配置供体验和小型库使用CPU2 核支持 AVX 指令集用于机器学习推理内存4 GB存储视照片库大小而定建议 SSD 以获得更好体验操作系统任何可以运行 Docker 的 Linux 发行版如 Ubuntu 22.04 LTS、WindowsWSL2或 macOS。推荐配置用于家庭或小型团队CPU4 核或以上更强的单核性能有助于人脸识别和搜索内存8 GB 或以上存储大容量硬盘或 NAS 用于存储媒体文件SSD 用于系统和数据库。必须安装的软件Docker版本 20.10.0 或更高。Docker Compose版本 v2.0.0 或更高。请注意新版的 Docker Desktop 已包含 Compose V2如果是 Linux 服务器可能需要单独安装docker-compose-plugin。在终端中运行以下命令检查版本docker --version docker compose version2.2 项目结构规划在部署前规划好你的目录结构非常重要这关系到数据持久化和后续维护。建议创建一个专用目录例如/opt/immich或~/immich并在其中创建以下子目录immich-app/ ├── docker-compose.yml # Docker Compose 配置文件 ├── .env # 环境变量配置文件 ├── data/ │ ├── postgres # 数据库数据 │ ├── redis # 缓存数据 │ └── model-cache # 机器学习模型缓存 └── upload/ # 照片和视频的上传目录可挂载外部存储重要upload目录是 Immich 存储原始媒体文件的地方请确保它所在的分区有足够大的空间。你可以将其链接到你的 NAS 或大容量硬盘的挂载点。2.3 获取部署配置文件进入你创建的目录下载官方提供的docker-compose.yml和.env文件模板。# 创建并进入项目目录 mkdir -p /opt/immich cd /opt/immich # 下载最新的 docker-compose.yml 文件 curl -L https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml -o docker-compose.yml # 下载环境变量模板文件 curl -L https://github.com/immich-app/immich/releases/latest/download/example.env -o .env现在你的目录下应该有了两个关键文件。接下来我们需要重点配置.env文件。3. 核心配置详解与优化.env文件是 Immich 的配置核心它定义了数据库密码、服务器 URL、文件存储路径等关键信息。直接使用模板可能会出错我们必须根据自身环境进行定制。3.1 编辑 .env 文件用文本编辑器如nano或vim打开.env文件nano .env你会看到很多配置项我们重点关注以下几项# 数据库配置 DB_HOSTNAMEimmich_postgres DB_PORT5432 DB_USERNAMEpostgres # 务必修改为一个强密码 DB_PASSWORDpostgres DB_DATABASE_NAMEimmich # Redis 配置缓存和队列 REDIS_HOSTNAMEimmich_redis REDIS_PORT6379 REDIS_DBINDEX0 # Redis 密码建议设置 REDIS_PASSWORD # Immich 服务器配置 # 这是最重要的配置之一 # 填写你打算访问 Immich 的地址可以是 IP:端口也可以是域名。 # 例如http://192.168.1.100:2283 或 https://photos.yourdomain.com IMMICH_SERVER_URLhttp://localhost:2283 # 公开的外部 URL用于分享链接等。如果和上面一样可以留空。 IMMICH_PUBLIC_LOGIN_PAGE_URL IMMICH_PUBLIC_SERVER_URL # 文件上传相关 # 设置上传文件的目录对应我们之前规划的 upload 目录 IMMICH_UPLOAD_LOCATION/usr/src/app/upload # 机器学习模型配置 # 如果你想使用更强大的 CLIP 模型进行智能搜索可以启用并下载 MACHINE_LEARNING_ENABLEDtrue # CLIP 模型模式可选 ViT-B-32::openai 或 ViT-L-14::openai后者更准但更大 MACHINE_LEARNING_CLIP_MODEL_NAMEViT-B-32::openai关键修改点DB_PASSWORD必须修改不要使用默认的postgres。IMMICH_SERVER_URL必须修改如果你在服务器上部署并希望通过局域网 IP 访问就改成http://你的服务器IP:2283。如果你配置了域名和反向代理如 Nginx就改成https://你的域名。这个配置错误会导致移动端 App 无法连接服务器。IMMICH_UPLOAD_LOCATION在 Docker 容器内部Immich 会将文件存储在这个路径。我们稍后需要在docker-compose.yml中将宿主机的实际目录如/opt/immich/upload映射到这个容器内路径。3.2 配置 Docker Compose 文件现在打开docker-compose.yml文件。我们主要需要关注卷映射volumes部分确保数据持久化。找到services下的immich-server服务查看其volumes配置。通常官方配置已经包含但我们需确认路径正确。services: immich-server: # ... 其他配置 ... volumes: - /path/to/your/upload:/usr/src/app/upload - /path/to/your/model-cache:/cache # ... 其他配置 ...你需要将/path/to/your/upload替换为你宿主机上准备用于存储照片的真实路径例如/opt/immich/upload。同样将/path/to/your/model-cache替换为/opt/immich/data/model-cache。同时检查immich-postgres和immich-redis服务的卷映射确保数据库和缓存数据也持久化到宿主机例如映射到/opt/immich/data/postgres和/opt/immich/data/redis。修改后的片段示例services: immich-server: image: ghcr.io/immich-app/immich-server:release volumes: - /opt/immich/upload:/usr/src/app/upload - /opt/immich/data/model-cache:/cache # ... 环境变量等配置 ... immich-postgres: image: postgres:16-alpine volumes: - /opt/immich/data/postgres:/var/lib/postgresql/data # ... 其他配置 ... immich-redis: image: redis:7-alpine volumes: - /opt/immich/data/redis:/data # ... 其他配置 ...3.3 关于反向代理可选但推荐如果你有域名并希望通过 HTTPShttps://photos.yourdomain.com安全访问或者想使用 80/443 标准端口就需要配置反向代理。Nginx Proxy Manager (NPM)或Caddy是简化此过程的好工具。这里以 Nginx 原生配置为例假设你已经有一个运行在 2283 端口的 Immich 服务# 在 /etc/nginx/sites-available/immich 中创建配置文件 server { listen 80; server_name photos.yourdomain.com; # 你的域名 # 重定向 HTTP 到 HTTPS如果你配置了 SSL return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name photos.yourdomain.com; # SSL 证书路径通过 Certbot 或其他方式获取 ssl_certificate /etc/letsencrypt/live/photos.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/photos.yourdomain.com/privkey.pem; # 提高上传文件大小限制 client_max_body_size 50000M; location / { # 将请求代理到 Immich 服务器 proxy_pass http://localhost: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; } }配置完成后记得将.env文件中的IMMICH_SERVER_URL改为https://photos.yourdomain.com并重启 Nginx 和 Immich 服务。4. 一键部署与初始化配置完成后部署过程非常简单。4.1 启动 Immich 服务在包含docker-compose.yml和.env文件的目录下执行以下命令# 使用 Docker Compose 启动所有服务-d 表示后台运行 docker compose up -dDocker 会自动从网络拉取所需的镜像包括 Immich 服务器、Web 前端、PostgreSQL、Redis、机器学习引擎等这可能需要一些时间取决于你的网络速度。4.2 检查服务状态启动完成后使用以下命令检查所有容器是否正常运行docker compose ps你应该看到所有服务immich-server,immich-web,immich-machine-learning,immich-postgres,immich-redis,immich-proxy的状态都是Up。查看实时日志以监控启动过程或排查问题# 查看所有服务的日志 docker compose logs -f # 仅查看某个服务的日志例如 server docker compose logs -f immich-server4.3 完成 Web 界面初始化打开浏览器访问你在.env中配置的IMMICH_SERVER_URL例如http://192.168.1.100:2283或https://photos.yourdomain.com。首次访问会进入管理员账户注册页面。输入你的邮箱、姓名、密码创建一个管理员账户。这个账户拥有最高权限。注册成功后你将直接登录到 Immich 的 Web 管理界面。至此服务端部署已经完成你现在拥有了一个功能完整的私有照片管理服务器。5. 移动端配置与自动备份Immich 的强大之处在于其无缝的移动端体验。让我们配置手机 App实现自动备份。5.1 安装移动端 AppAndroid在 Google Play Store 搜索 “Immich” 并安装。iOS在 App Store 搜索 “Immich” 并安装。F-Droid同样可用。5.2 连接服务器并配置备份打开 App在服务器地址栏输入你的IMMICH_SERVER_URL与浏览器访问的地址一致。注意如果服务器是 HTTP 且不是 localhostiOS 可能需要在Info.plist中允许非 HTTPS 访问对于自签证书也会有问题。最佳实践是配置 HTTPS 反向代理。使用刚才在 Web 端创建的管理员账户登录。登录成功后App 会引导你进行备份设置。关键配置项备份目录选择手机中需要备份的相册如 DCIM、Screenshots 等。仅在 Wi-Fi 下备份建议开启以节省移动数据。仅在充电时备份建议开启以节省电量。备份原图选择“是”以上传原始质量的照片和视频。如果空间紧张可以选择“优化”进行压缩。排除路径可以排除某些应用缓存目录。保存设置后备份将立即开始。你可以在 App 的“后台任务”中查看上传进度。现在你的手机照片就会自动、安静地备份到你自己的服务器上了。你可以在 Web 端或 App 的“时间线”中看到所有已备份的照片。6. 核心功能实战与使用技巧部署完成只是开始充分使用其功能才能提升效率。6.1 智能搜索与相册管理Immich 的搜索框是你的“效率倍增器”。得益于集成的机器学习模型如 CLIP你可以使用自然语言进行搜索。搜索人物在搜索框输入人物名字需要先通过人脸识别创建人物。搜索物体/场景尝试搜索 “dog”, “beach”, “wedding”, “car”, “mountain”。搜索活动搜索 “birthday”, “Christmas”。组合搜索”dog park summer 2023”。基于元数据搜索”f:heic” (搜索 HEIC 格式), “iso:800” (搜索 ISO 值)。创建智能相册你可以将任何搜索条件保存为“智能相册”。例如搜索“dog”后点击“保存为相册”以后所有包含狗的照片都会自动归入这个相册。6.2 人脸识别与管理首次上传大量包含人像的照片后Immich 的后台任务会开始进行人脸识别。点击左侧导航栏的“人物”。系统会列出所有检测到的人脸集群。你需要手动为每个集群命名如“小明”、“妈妈”。系统会学习后续识别准确率会越来越高。命名后点击该人物即可查看所有包含他/她的照片并可以将其添加到“已收藏的人物”中。6.3 共享相册与协作你可以创建共享相册并邀请其他 Immich 用户需要先注册账户或通过链接分享给任何人。在“相册”页面点击“创建共享相册”。添加照片并为相册命名。点击相册右上角的“分享”图标。添加合作者输入已注册用户的邮箱他们可以上传和管理照片。创建分享链接生成一个公开链接任何人点开都能查看可设置密码和有效期。这对于与没有 Immich 账户的家人朋友分享非常方便。6.4 地图视图与元数据如果照片带有 GPS 信息Immich 会自动在地图视图导航栏“地点”中标注拍摄位置。你可以直观地看到你的旅行足迹。点击地图上的标记可以查看在该地点拍摄的所有照片。7. 常见问题与故障排查在实际使用中你可能会遇到一些问题。以下是高频问题的解决方案。7.1 移动端 App 无法连接服务器这是最常见的问题几乎都是由于.env中的IMMICH_SERVER_URL配置错误导致的。问题现象可能原因解决思路App 提示“无法连接服务器”或一直转圈1.IMMICH_SERVER_URL填写错误。2. 服务器防火墙未开放 2283 端口。3. 在 Docker 主机上客户端用了localhost。1.检查.env文件确保IMMICH_SERVER_URL是手机能访问到的地址。在服务器上用curl http://localhost:2283/api测试服务是否正常。2.检查防火墙sudo ufw allow 2283/tcp(Ubuntu)。3.Docker 网络在宿主机上用宿主机的局域网 IP 而非localhost。在手机上用这个局域网 IP 访问。网页能访问App 不行可能使用了自签名 HTTPS 证书手机不信任。1. 为域名申请免费的 Let‘s Encrypt 证书推荐。2. 或将自签名证书安装到手机的信任证书列表中复杂。3. 或暂时使用 HTTP 进行内网测试不安全。7.2 上传失败或速度慢问题现象可能原因解决思路上传卡住进度条不动1. 单文件过大。2. 反向代理如 Nginx配置了过小的client_max_body_size。3. 存储目录权限问题。1. 检查文件大小Immich 默认支持很大。2.检查 Nginx 配置确保client_max_body_size 50000M;已设置。3. 检查 Docker 卷映射的宿主机目录权限sudo chown -R 1000:1000 /opt/immich/upload(Immich 容器内用户 UID 通常为 1000)。上传速度极慢1. 手机在移动网络下上传大视频。2. 服务器上行带宽不足。3. 客户端与服务器网络延迟高。1. 在 App 设置中开启“仅 Wi-Fi 上传”。2. 检查服务器网络状况。3. 考虑内网穿透或公网 IP 直连的延迟。7.3 人脸识别或智能搜索不工作问题现象可能原因解决思路“人物”页面为空或识别很少1. 机器学习服务未启动或出错。2. 识别任务还在队列中。3. 模型未下载完成。1.docker compose logs immich-machine-learning查看日志。2. 在 Web 端“设置” - “工作区” - “任务管理”查看是否有待处理的人脸检测任务。3. 首次启动需要下载模型网络不好可能失败。检查model-cache目录大小。搜索关键词无结果1. CLIP 模型未启用或未下载。2. 未对库进行智能搜索编码。1. 检查.env中MACHINE_LEARNING_ENABLEDtrue且CLIP_MODEL已设置。2. 在“设置” - “工作区”中手动触发“生成智能搜索索引”任务。7.4 如何更新 Immich 版本Immich 开发活跃定期更新可以获取新功能和修复。更新前务必备份你的docker-compose.yml和.env文件以及数据库。# 进入项目目录 cd /opt/immich # 停止当前服务 docker compose down # 备份数据强烈建议 cp -r data data_backup_$(date %Y%m%d) # 拉取最新的 docker-compose.yml 文件比较差异手动合并自定义修改 curl -L https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml -o docker-compose.yml.new # 使用 diff 工具对比 docker-compose.yml 和 docker-compose.yml.new将你的自定义卷映射等配置合并到新文件。 # 或者如果你改动不多可以直接用新文件覆盖然后重新添加你的卷映射配置。 # 拉取最新镜像 docker compose pull # 重新启动服务 docker compose up -d # 查看日志确认升级无误 docker compose logs -f8. 最佳实践与高级配置为了让你的 Immich 实例更稳定、安全、高效请遵循以下建议。8.1 数据备份策略你的照片是无价的。不能只依赖一份存储。3-2-1 备份原则至少 3 份数据2 种不同介质1 份异地备份。Immich 数据构成媒体文件/opt/immich/upload目录下的所有原始文件。这是最重要的。数据库/opt/immich/data/postgres目录。包含了用户信息、相册结构、元数据、人脸数据等。没有它你的文件只是一堆散乱的图片。配置文件你的docker-compose.yml和.env文件。备份方案方案 A简单定期将整个/opt/immich目录压缩并拷贝到另一块硬盘或云存储。方案 B推荐使用rsync同步upload目录使用pg_dump命令定期导出数据库 SQL 文件。# 导出数据库备份 docker compose exec immich-postgres pg_dump -U postgres immich /path/to/backup/immich_db_$(date %Y%m%d).sql # 使用 rsync 同步媒体文件 rsync -avz /opt/immich/upload/ userbackup-server:/path/to/backup/immich_upload/8.2 性能优化硬件CPU 的单核性能影响人脸识别和搜索速度内存越大能缓存的图片和处理的并发任务越多使用 SSD 存储数据库和model-cache能极大提升响应速度。Docker 配置在docker-compose.yml中可以为immich-machine-learning服务限制 CPU 和内存避免它占用过多资源影响其他服务。immich-machine-learning: # ... 其他配置 ... deploy: resources: limits: cpus: 2.0 memory: 4G模型选择在.env中MACHINE_LEARNING_CLIP_MODEL_NAME默认为ViT-B-32::openai在精度和速度间取得平衡。如果你有强大 GPU 且追求最准搜索可改为ViT-L-14::openai。8.3 安全加固强密码确保.env中的DB_PASSWORD和REDIS_PASSWORD是复杂且唯一的。HTTPS必须为公网访问配置 HTTPS使用 Let‘s Encrypt 免费证书。防火墙仅开放必要的端口如 443, 2283。如果使用了反向代理可以只开 80/443并将 Immich 的 2283 端口绑定到127.0.0.1避免公网直接暴露。定期更新关注 Immich 的 GitHub 发布页定期更新以获取安全补丁。用户权限不要所有人都用管理员账户。为家庭成员创建普通用户账户并管理好共享相册的权限。8.4 与现有照片库的整合如果你已经有大量照片存储在硬盘的某个文件夹里可以通过“外部库”功能导入。在 Web 端进入“设置” - “工作区”。找到“外部库”部分点击“添加外部库”。输入一个名称并填写容器内的路径。例如你将宿主机的/mnt/nas/photos映射到了容器的/external/photos那么这里就填/external/photos。保存后Immich 会扫描该目录并将其内容导入到时间线中。注意这是“链接”而非“移动”原始文件位置不变。通过以上步骤你不仅成功部署了一个功能强大的私有照片管理平台更掌握了使其稳定、安全、高效运行的核心知识。从自动备份到智能搜索从数据安全到性能调优Immich 提供了一个近乎完美的自托管解决方案让你真正成为自己数字记忆的主人。现在就去享受整理和回顾照片的乐趣吧你会发现管理数万张照片也可以如此轻松。如果在实践中遇到本文未覆盖的特定问题查阅 Immich 官方文档和活跃的 GitHub 社区通常是找到答案最快的方式。