Immich 自托管照片库

Immich：把手机照片备份到自己掌管的图库

一句话看懂

Immich 可把照片和视频放进自己管理的图库，再按相册整理和选择性分享。先用一部旧手机与少量测试照片验证；原始照片必须保留独立备份，图库不应成为唯一副本。

它能帮你做什么

• 手机照片备份：连接测试相册，确认图库出现上传内容。
• 相册整理：按旅行或家庭成员建立相册，集中查看照片。
• 共享相册：只分享已经确认范围的相册，不公开整个图库。

备份一组测试照片

输入：三张内容不同、不含隐私的测试照片。

1. 先按下方部署检查完成一张照片的网页上传测试，再连接手机。
2. 在手机备份设置中仅选测试相册，确认其中只有这三张照片，然后启用备份。
3. 等上传完成，在网页图库逐张打开核对。

输出：图库出现三张测试照片；同内容文件可能被去重，不能靠重复复制同一张图片来测试数量。

成功标志：三张原件可读取、照片数量与内容正确。缩略图出现并不等于已经完成独立备份；先保留手机和测试目录里的原件。后台上传还受网络、系统后台权限和省电策略影响，不保证应用关闭后立刻上传。

建立旅行测试相册

输入：三张已经上传的测试照片。

1. 新建旅行相册。
2. 加入三张照片。
3. 打开相册检查顺序。

输出：一个包含三张照片的相册。

成功标志：相册列表显示三张照片。

只分享一个测试相册

输入：一个不含私人信息的测试相册，以及同一实例的另一个测试账号。

1. 确认照片范围，在相册共享中选择该测试账号并授予只读查看权限。
2. 用另一浏览器登录这个账号，打开被分享的相册。
3. 确认只显示预期照片，没有开放整个图库。

输出：指定测试账号可以浏览选中的相册。

成功标志：其他图库内容没有被显示。不要把“伙伴共享”当作单相册共享，它会共享整个图库。公共链接是另一种方式，持链接者可能访问；若以后使用，再单独设置密码、到期时间与操作权限，不默认发布到公网。

下载后怎么用

本包是固定提交的源码快照，不是离线即用的服务器安装包。源码的 server/package.json 标注 3.2.0-rc.0，而环境示例使用浮动标签 IMMICH_VERSION=v3；直接启动示例不能证明运行的是这个固定提交。仓库还明确提醒：源码里的 Compose 文件不一定兼容正式发行版。

第一次体验建议在独立测试设备上按一个正式发布版本部署。以 2026-09-03 可取得的正式版 v3.1.0 为例：从官方安装说明指向的发布入口选择该完整版本，同时取得该版本的 docker-compose.yml 和 example.env，将后者命名为 .env，放进一个新的部署目录。不要混用源码快照的 Compose、另一个版本的环境文件与浮动镜像；若改选其他版本，就重新核对那一版的配套文件和升级说明。这是独立发行版体验，不是把本包改称为 v3.1.0。官方容器部署说明

在测试设备上准备 Docker Engine 与 Compose 插件，使用 docker compose，不是旧的 docker-compose。编辑新部署目录里的 .env：

• UPLOAD_LOCATION：指向用于测试照片的新目录，留出缩略图和转码文件空间；不要直接指向唯一照片库。
• DB_DATA_LOCATION：使用本机、支持 Unix 权限的存储，推荐本地 SSD；不要放在网络共享上。
• DB_PASSWORD：改为随机的字母数字密码，不沿用示例值，不公开 .env。
• IMMICH_VERSION：设为所选完整标签；本例为 v3.1.0，使服务端与机器学习镜像版本一致。数据库与 Valkey 镜像保留该发布文件给出的配置，不随意改成各自的 latest。
• TZ：按自己的时区设置。

在同一部署目录逐条运行：

docker compose version
docker compose config --quiet
docker compose config --images
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail 50 immich-server database

config --quiet 无报错表示配置解析通过；config --images 应列出服务端、机器学习、Valkey 与数据库镜像，其中两个 Immich 镜像都应指向选定版本。前两项检查不代表服务已启动；pull 会联网下载外部镜像，up -d 会创建容器、网络和持久化数据，并初始化数据库。这些镜像和运行数据不在源码 ZIP 内。Compose 配置检查说明

容器应保持运行，相关健康检查通过，日志无持续的数据库连接、权限或重启错误。然后仅在受信任局域网访问 http://<测试服务器IP>:2283：第一位注册者是管理员，先完成自己的管理员注册，不要在此之前开放公网访问。使用网页上传一张无人物隐私、无敏感定位的测试 JPEG，确认时间线出现该照片、缩略图和原图均能打开，并下载原件核对文件大小与尺寸；需要严格校验时比较原件哈希。完成这一步后，再测试上面的手机三张照片和相册流程。

Windows 用户不能直接把数据库目录放在 NTFS/exFAT 或 WSL 的 /mnt/c 等宿主机挂载目录里。请按官方要求使用合适的 Linux 文件系统或配置命名卷，并核对实际挂载；仅改路径名不能解决权限问题。系统与存储要求

若镜像无法拉取、容器反复重启、网页打不开或原图无法读取，先停止批量导入，检查版本配套、端口、磁盘空间、挂载权限和日志。不要用删除卷、清空数据库或反复切换版本来“试试看”。源码中的 docker-compose.prod.yml 包含本地构建及额外端口，不因文件名有 prod 就成为普通用户可直接采用的生产安装包；严格复现本提交需另按开发文档在隔离环境构建，不能把上述发行版步骤当成已验证的源码复现。

使用前要准备什么

• 可长期运行的 64 位设备和稳定存储。该版本文档要求至少 6GB 内存、2 核 CPU，推荐 8GB、4 核；v3 的 amd64 机器学习容器还要求至少 x86-64-v2 指令集。低配设备需按文档关闭机器学习等功能，不能默认所有旧电脑都能完整运行。
• 独立备份方案：同时备份数据库与照片/视频文件。Immich 自动生成的数据库备份位于 UPLOAD_LOCATION/backups，只含元数据，不含照片和视频；还需备份完整媒体目录及另挂载的外部图库，保留离机副本并演练恢复。备份时应保证数据库和媒体的一致性，不手动挪动应用管理的原件。备份与恢复说明
• 家庭成员账号、共享范围和访问控制约定；首次只用局域网，不额外暴露数据库或机器学习服务端口。
• 默认机器学习由自己的容器处理，缓存缺失时会从公开模型源取得权重；首次运行不是“完全不联网”。下载模型失败或任务未完成时，不能把上传成功当成人脸识别、智能搜索也已成功。核心自托管不要求购买云端 AI API；若配置远端机器学习，照片预览会发往那台机器，版本、网络隔离和算力费用都要另行考虑。远端机器学习说明
• 项目代码可免费自托管；官方购买入口用于支持项目，不是解锁核心功能的必需订阅。硬盘、服务器、电力、网络、域名，以及自选托管、软件服务或异地备份按实际使用计费，本包不附带这些服务。项目支持说明

适不适合你

• 适合你：你重视照片自主保存，并愿意维护设备、存储与备份。
• 适合你：你想把家庭相册集中整理，只分享明确选中的内容。
• 下载前先看：自托管需要你负责更新、权限、备份与安全；不建议直接迁移唯一照片副本。

资源包里有什么

• 固定提交 1c7f9a4f24b17623ac26095bb473927264af0cef 的官方源码快照。
• README、AGPL-3.0 许可证与上游发布说明模板。
• 《资源使用介绍》PDF、中文说明、资源讲解卡和校验清单。
• 源码中的配置与开发材料用于理解项目实现，不包含匹配发布版容器镜像、模型缓存或完整离线运行环境。

资源版本说明

本包锁定官方提交 1c7f9a4f24b17623ac26095bb473927264af0cef，源码标注 3.2.0-rc.0；源码版本标注不能用来确认同名发行镜像是否可用。上文的 v3.1.0 是正式发布版的部署示例，不是本源码提交的运行环境。二次分发、部署或修改前请以包内 LICENSE 与官方文件为准。本包不含任何用户照片、账户、服务器或云端配额。上述步骤需在自己的测试环境中验证，不代表本包已经附带运行中的服务。