手机中的照片和视频不断增长后常见问题不只是磁盘容量还包括自动备份、跨设备浏览、相册共享、重复文件控制和元数据检索。Immich 把这些能力组合成一个可自托管的照片管理系统提供 Web 管理界面和移动端应用适合家庭相册、个人影像归档、小团队素材共享等场景。Immich 支持照片和视频上传、移动端后台备份、多用户、共享相册、EXIF 与地图信息、RAW 格式、LivePhoto/MotionPhoto、人脸聚类、对象和 CLIP 搜索、公开分享、OAuth 与 API Key。管理员功能主要位于 Web 端移动端则更偏向照片浏览和自动备份。移动端可以按网络、电量和后台任务条件调整自动备份行为。需要提前明确一点Immich 是照片管理和同步系统不应被当作照片的唯一副本。项目 README 明确建议对重要照片执行 3-2-1 备份即至少保留三份数据、使用两种介质并有一份位于其他位置。部署结构与数据边界官方 Docker Compose 部署通常包含以下组件组件用途是否需要持久化immich-serverWeb、API、上传、媒体处理等核心服务媒体目录需要持久化immich-machine-learning人脸识别、对象识别和 CLIP 等机器学习任务模型缓存建议持久化PostgreSQL保存用户、相册、资源索引和任务状态等结构化数据必须持久化Valkey/Redis 兼容服务队列和缓存由 Compose 管理Web 访问入口由immich-server提供默认映射到2283端口照片原文件与 PostgreSQL 数据承担不同职责。只备份上传目录能够保住媒体文件却不能完整恢复用户、相册关系、分享配置和索引只备份数据库则没有照片原件。备份方案必须同时覆盖两者。Immich 更新频率较高部署时应以官方发布版本附带的docker-compose.yml和example.env为准不要从不同版本分别复制这两个文件。混用模板可能导致环境变量、镜像或数据库扩展不匹配。一、准备 Linux 与 Docker Compose部署主机需要运行 Linux并已安装 Docker Engine 和 Docker Compose 插件。CPU、内存和磁盘需求会受照片数量、视频转码及机器学习任务影响实际部署前应核对官方的最新要求Immich 安装要求Docker Engine 安装文档Docker Compose 插件文档检查 Docker 服务和 Compose 插件是否可用docker--versiondockercompose versiondockerinfo这里使用的是docker compose中间没有连字符。如果系统只能执行旧版docker-compose不应直接假定它与当前官方模板兼容建议按 Docker 官方文档安装 Compose 插件。再检查可用磁盘空间df-hdockersystemdfImmich 的容量规划不能只按现有照片大小计算。缩略图、转码文件、机器学习模型、数据库和后续上传都需要额外空间。上传目录最好位于容量明确、可监控且能纳入备份的文件系统中。二、下载官方 Compose 和环境变量模板创建独立部署目录mkdir-p./immich-appcd./immich-appwget-Odocker-compose.yml\https://github.com/immich-app/immich/releases/latest/download/docker-compose.ymlwget-O.env\https://github.com/immich-app/immich/releases/latest/download/example.env这两个文件来自同一个最新版本发布附件能够减少模板跨版本混用的问题。若生产环境要求固定版本应从目标版本的 Release 页面下载对应附件并在变更记录确认无破坏性升级后再更新。检查文件是否存在ls-lahdocker-compose.yml .envdockercompose config--servicesdocker compose config --services会解析 Compose 文件并列出服务。如果这里已经报错应先处理 YAML、环境变量或 Compose 版本问题不要继续启动容器。Immich 的正常部署入口是 Docker Compose不需要在部署目录执行npm install或npm run build。仓库根目录的开发构建方式与发布版容器部署不是同一条路径在一个只有下载文件的目录中执行npm run build出现Missing script: build并不能说明 Immich 服务本身构建失败。三、设置媒体目录和数据库参数使用文本编辑器打开.envnano.env官方模板中的关键项目通常包括UPLOAD_LOCATION./library DB_DATA_LOCATION./postgres TZEtc/UTC IMMICH_VERSIONrelease DB_PASSWORDreplace_with_a_long_random_password DB_USERNAMEpostgres DB_DATABASE_NAMEimmich实际文件应以下载到的example.env内容为准不要因为示例中出现了某个变量就在旧版本模板中强行添加。UPLOAD_LOCATION该目录保存上传的照片和视频及 Immich 管理的媒体数据。相对路径会以 Compose 项目目录为基准例如UPLOAD_LOCATION./library也可以改成容量更充足的绝对路径UPLOAD_LOCATION/srv/immich/library如果使用绝对路径先创建目录并确保 Docker 能访问对应文件系统sudomkdir-p/srv/immich/library不要把这个目录放在容易被系统清理的临时路径中也不要在容器运行期间手工移动或重命名内部文件。Immich 的数据库记录与磁盘文件存在对应关系绕开应用直接整理目录可能产生不一致。DB_DATA_LOCATION该目录保存 PostgreSQL 数据文件例如DB_DATA_LOCATION./postgres数据库数据目录应位于本地 Linux 文件系统。是否适合放到网络文件系统需要遵守官方数据库存储说明不能仅因为网络目录可挂载就默认它具备 PostgreSQL 所需的锁、同步和一致性语义。DB_PASSWORD将模板密码换成随机强密码。密码应使用模板允许的字符范围并妥善保管openssl rand-base6432把生成值填写到DB_PASSWORD需要替换的随机密码编辑.env后限制文件读取权限chmod600.envTZ与版本策略TZ用于时区设置可替换为部署环境对应的 IANA 时区名称。无法确定时可保留模板值并通过官方时区数据库核对。IMMICH_VERSIONrelease会跟随官方发布标签。它便于获取当前稳定发布但也意味着重新拉取镜像时可能进入新版本。对可回滚要求较高的环境更稳妥的方式是记录当前镜像版本、阅读 Release Notes并在备份完成后执行升级。四、检查 Compose 展开结果启动前先让 Compose 完整解析配置dockercompose config/tmp/immich-compose-rendered.ymldockercompose config--services这一步可以发现以下问题.env中变量未定义YAML 缩进或语法错误当前 Compose 版本无法解析配置挂载路径被展开到非预期位置手工修改后出现重复端口或服务名。不要公开/tmp/immich-compose-rendered.yml其中可能包含已经展开的数据库密码。检查完成后可以删除rm-f/tmp/immich-compose-rendered.yml如果需要确认端口映射可在本机查看解析后的 Compose 内容但不要把包含凭据的完整输出粘贴到公开问题中。官方模板默认通过主机的2283端口提供访问入口。五、拉取镜像并启动服务在immich-app目录执行dockercompose pulldockercompose up-dpull与up -d分开执行便于区分镜像下载错误和容器启动错误。启动后查看容器状态dockercomposeps继续观察服务日志dockercompose logs--tail200需要持续跟踪核心服务时可执行dockercompose logs-fimmich-server按CtrlC只会结束日志跟踪不会停止后台容器。若主机启用了防火墙应按实际访问方式放行端口。直接访问 Immich 时需要允许 TCP2283若前面部署了反向代理则通常只对外开放代理使用的 HTTP/HTTPS 端口并限制2283的来源范围。不要为了排错一次性开放无关端口也不要对公网暴露 PostgreSQL 和缓存服务。六、创建管理员并完成基础验收浏览器访问http://需要替换的服务器地址:2283首次进入时按照页面流程创建管理员账户。管理员创建后可在 Web 管理界面继续添加普通用户。项目功能表表明用户管理属于 Web 端管理功能不在移动端执行。基础验收不应只看“页面能打开”至少检查以下路径docker compose ps中服务没有反复重启。Web 页面能够完成管理员登录。上传一张非敏感测试图片。刷新页面后测试图片仍可显示。打开图片详情检查时间和 EXIF 等元数据。执行一次搜索确认搜索界面与索引任务可用。重启 Compose 后再次确认测试资源仍然存在。重启测试命令如下dockercompose restartdockercomposepsdockercompose logs--since5m高级搜索可以组合元数据、对象、人脸及其他过滤条件具体可用项取决于资源类型和索引状态。如果刚上传的照片暂时无法通过对象或人脸检索不应立即判定上传失败。上传、生成缩略图、提取元数据和机器学习分析属于不同任务应结合后台任务状态和immich-machine-learning日志排查。七、连接移动端并设置自动备份移动端应用需要填写 Immich 服务地址例如http://需要替换的服务器地址:2283通过反向代理提供 HTTPS 时应填写实际 HTTPS 地址。外部访问不应继续依赖局域网地址也不能只更换端口而忽略证书、代理请求体大小和超时配置。登录后进入备份页面按设备相册选择需要同步的目录。备份范围可以按设备相册选择避免把截图、缓存图片等目录全部上传。相册同步设置用于关联设备相册与服务端相册调整后应以少量测试照片验证归类结果。自动备份启用后至少测试以下情况新拍摄照片是否进入等待备份队列Wi-Fi 或移动网络条件是否符合设置应用退到后台后系统是否允许其执行后台任务同一资源重复扫描时是否被重复上传LivePhoto/MotionPhoto 是否能按预期备份和播放。移动系统可能根据省电策略暂停后台任务。Immich 提供后台备份能力但最终执行仍受系统权限、网络状态和电池优化策略影响。通知与账户设置Immich 支持多用户和管理功能管理员应为每位使用者创建独立账户不要让所有设备共用管理员凭据。独立账户能隔离个人图库也便于撤销单个用户的访问权限。用户可以在设置页面调整通知相关选项实际可用通知类型以部署版本为准。需要统一身份认证时Immich 支持 OAuth。OAuth 涉及回调地址、客户端标识、客户端密钥、发行者地址和外部访问域名不能只在认证服务中创建客户端而不配置 Immich。相关参数应按官方 OAuth 文档填写并通过普通用户账户测试登录与退出流程。外部认证服务需要为 Immich 配置正确的客户端访问范围和重定向地址。如果只是家庭局域网使用先完成内置账户、上传、备份和恢复验证再引入 OAuth故障边界会更清晰。备份媒体文件与数据库必须成套处理Immich 仓库明确提示采用 3-2-1 备份策略。对 Docker Compose 部署至少需要保护.env和docker-compose.ymlUPLOAD_LOCATION指向的媒体目录PostgreSQL 逻辑备份当前 Immich 版本和升级记录反向代理配置及证书管理配置如有。在immich-app目录中可以先确认 PostgreSQL 服务名dockercompose config--services官方 Compose 常见数据库服务名为database。确认服务名后创建逻辑备份目录并导出数据库mkdir-p./backupsdockercomposeexec-Tdatabase\pg_dumpall--clean--if-exists\--username${DB_USERNAME:-postgres}\./backups/immich-database.sql这里的服务名、数据库用户名和具体恢复命令必须与当前版本官方备份文档核对。如果 shell 没有加载.env中的变量可显式替换用户名dockercomposeexec-Tdatabase\pg_dumpall--clean--if-exists--usernamepostgres\./backups/immich-database.sql检查备份文件是否非空ls-lh./backups/immich-database.sqltest-s./backups/immich-database.sql媒体目录可以使用支持增量和校验的备份工具同步到另一块存储介质。下面的目标路径必须替换rsync-aH--delete\/srv/immich/library/\/需要替换的备份挂载点/immich-library/--delete会删除目标端中源端已不存在的文件只适合维护镜像型副本。若希望保留误删历史应改用带版本管理或快照能力的备份方案。配置文件可单独归档tar-czf./backups/immich-config.tar.gz\.env docker-compose.yml数据库导出、媒体副本和配置归档完成后还要做恢复演练。未经恢复验证的备份只能证明生成过文件不能证明能够恢复服务。应用内的恢复入口用于对应的客户端数据恢复流程不能代替服务端媒体目录和 PostgreSQL 备份。升级前后的操作顺序升级前阅读 Immich Releases 和官方升级说明。跨多个版本时应检查是否存在要求按中间版本迁移的说明。记录当前状态cd./immich-appdockercomposepsdockercompose imagescpdocker-compose.ymldocker-compose.yml.$(date%F).bakcp.env.env.$(date%F).bak完成数据库和媒体备份后下载同一目标版本配套的 Compose 文件与环境变量模板。不要直接用新example.env覆盖现有.env应比较新增和废弃变量wget-Oexample.env.new\https://github.com/immich-app/immich/releases/latest/download/example.envdiff-u.env example.env.new.env包含实际密码而模板包含默认值差异不能机械覆盖。应把新版本要求的变量合并到现有配置中。确认配置后执行dockercompose pulldockercompose up-ddockercomposepsdockercompose logs--since10m升级完成后重新检查登录、上传、缩略图、视频播放、搜索、后台任务和移动端连接。数据库迁移完成后简单切换旧镜像不一定能回滚数据库结构因此真正的回滚基础仍然是升级前的数据库与媒体备份。常见故障定位docker compose命令不存在表现通常是docker: compose is not a docker command这说明 Compose 插件未安装或 Docker 安装不完整。按 Docker 官方文档安装 Compose 插件并重新执行dockercompose version端口2283无法访问先确认容器和端口监听状态dockercomposepsss-lntp|grep2283curl-Ihttp://127.0.0.1:2283本机能够访问而外部不能访问排查主机防火墙、上游防火墙和来源地址限制。本机也不能访问则查看immich-server日志。不要把数据库端口开放到公网作为处理方式。容器不断重启查看最近日志dockercomposepsdockercompose logs--tail300常见边界包括PostgreSQL 数据目录权限或文件系统不适用.env中数据库参数不一致磁盘空间或 inode 耗尽内存不足导致进程被系统终止Compose 文件和.env来自不同版本升级跨度过大或迁移未完成。检查系统层面的终止记录df-hdf-ifree-hdmesg--ctime|tail-n100上传失败或大视频中断直接访问2283时先检查服务日志。经反向代理访问时还应检查代理的请求体大小、读取超时和上游超时。若内网直连成功、域名访问失败问题更可能位于代理层而不是 Immich 上传逻辑。搜索、人脸识别没有结果检查机器学习容器和后台任务dockercompose logs--tail200immich-machine-learningdockercomposeps模型首次下载、资源分析和索引需要时间并会消耗 CPU、内存和磁盘。是否完成应以任务状态和日志为依据不能仅通过页面暂时没有搜索结果来判断。PostgreSQL 启动失败重点检查DB_DATA_LOCATIONdockercompose logs--tail200databasels-ld./postgresdf-h./postgres如果.env使用绝对路径则将./postgres替换为实际目录。不要在没有数据库备份的情况下删除该目录或重新初始化数据库。移动端后台备份停止依次核对应用是否获得照片访问权限系统是否允许后台运行电池优化是否限制应用网络条件是否符合备份设置服务地址在当前网络中是否可达用户存储配额是否已满服务端是否存在上传错误。重新安装应用不应作为首要排障动作因为它可能改变本地任务和设置状态。先查看备份队列、网络和服务端日志。执行npm run build报错发布版 Docker Compose 部署不需要在部署目录执行 Node.js 构建。出现Missing script: build时先确认自己是否误把容器部署步骤与源码开发步骤混在一起。正确的部署检查入口是dockercompose configdockercompose pulldockercompose up-d只有参与源码开发时才应按照仓库开发文档准备完整源码、包管理器和对应脚本。部署后的维护边界Immich 同时管理原文件、派生媒体、数据库关系和机器学习任务日常维护应围绕这几类数据展开定期检查上传目录、数据库目录和 Docker 存储占用定期导出 PostgreSQL并验证 SQL 文件不是空文件将媒体副本保存到独立存储介质升级前阅读 Release Notes保留目标版本的 Compose 文件不在应用运行期间手工改动媒体目录内部结构不把2283、数据库或缓存服务无条件暴露到公网通过 HTTPS 提供外部访问并保护.env、OAuth 密钥和管理员账户使用少量测试资源定期验证上传、搜索、下载和恢复链路。Immich 可以承担照片归档、浏览和自动备份入口但数据安全仍取决于部署者是否建立了独立、可恢复、经过验证的备份体系。参考资料Immich 项目仓库https://github.com/immich-app/immichImmich 官方文档https://docs.immich.app/项目介绍https://docs.immich.app/overview/introduction安装要求https://docs.immich.app/install/requirements/Docker Compose 安装https://docs.docker.com/compose/install/linux/Immich Releaseshttps://github.com/immich-app/immich/releases3-2-1 备份策略https://www.backblaze.com/blog/the-3-2-1-backup-strategy/项目 README 标示的许可证https://opensource.org/license/agpl-v3
