在实际个人数据管理中照片和视频的备份、整理与检索一直是个痛点。依赖单一云服务商不仅存在隐私风险还可能面临服务关闭、费用上涨或功能限制。自建方案如Nextcloud虽然功能全面但在媒体文件的智能管理、快速浏览和高效检索上往往力不从心。Immich的出现正是为了解决这一系列问题。它是一个专注于个人照片和视频备份与管理的开源、自托管解决方案其核心目标是成为Google Photos的替代品让你完全掌控自己的数据。Immich的设计理念非常明确快速、安全、智能。它提供了接近原生应用的上传和浏览体验支持从手机自动备份并利用机器学习模型为你的媒体库添加人物识别、物体识别、场景分类等智能标签从而实现强大的语义搜索功能。对于拥有大量照片、注重隐私且希望获得现代化管理体验的开发者或技术爱好者来说Immich是一个极具吸引力的选择。本文将带你从零开始理解Immich的核心架构完成一键式部署并深入配置其关键功能最终构建一个完全属于你自己的高效照片管理中枢。1. 理解 Immich 的核心架构与组件在动手部署之前必须先理解Immich的架构。它不是一个单一的应用而是一个由多个微服务组成的系统。这种设计带来了灵活性和可扩展性但也意味着部署时需要协调好各个组件。盲目安装很容易导致服务无法启动或功能异常。1.1 核心服务组件及其职责Immich 主要包含以下四个核心服务它们通过Docker容器进行隔离和协作Immich Server (immich-server): 这是应用的大脑一个基于NestJS构建的Node.js后端API服务器。它处理所有业务逻辑包括用户认证、资产管理上传、删除、整理、元数据提取、以及向机器学习服务发起分析请求。Immich Web (immich-web): 这是用户交互的前端界面一个基于React构建的单页应用。你通过浏览器访问、浏览照片、进行搜索等操作都是在与这个服务交互。它通过API与Server通信。PostgreSQL (postgres): 作为主数据库存储所有的结构化数据。这包括用户信息、相册、资产照片/视频的元数据如拍摄时间、地点、文件路径、人脸识别数据、标签等。所有重要的业务数据都存在这里。Redis (redis): 用作缓存和消息队列。机器学习任务队列、会话Session存储、临时数据缓存等都依赖于Redis。它能显著提升系统响应速度和处理并发任务的能力。1.2 机器学习微服务智能化的引擎Immich的“智能”特性如人物识别、物体识别和CLIP搜索依赖于独立的机器学习微服务。在官方部署中通常包含以下两个机器学习 (immich-machine-learning): 这是一个封装了多种AI模型的Python服务。它接收来自Server的任务对图片进行分析识别人脸、物体和场景并将结果返回。这是消耗计算资源尤其是CPU/GPU的主要服务。TensorFlow Serving (tensorflow): 某些特定的模型如MobileNet可能通过TensorFlow Serving来提供推理服务immich-machine-learning会调用它。注意机器学习服务对硬件有一定要求。CPU模式下分析速度较慢尤其是初始处理大量历史照片时。如果有NVIDIA GPU并配置了CUDA可以极大加速分析过程。1.3 存储架构原图、缩略图与元数据理解文件存储方式对后续管理和备份至关重要上传文件 (Upload Location): 用户上传的原始照片和视频文件存储在这里。目录结构通常会按年份/月份组织。库文件 (Library Location): 与上传目录类似是资产的实际存储位置。在典型设置中“上传”目录会被移动到“库”目录进行永久存储。缩略图 (Thumbnail Location): 系统会自动生成多种尺寸的缩略图用于列表预览、详情页展示等这些文件存储在此处以避免每次请求都动态处理原图。编码视频 (Encoded Video Location): 针对视频文件系统会生成适用于网页播放的编码版本如MP4存储在这里。在Docker部署中这些路径通常通过卷Volumes或绑定挂载Bind Mounts映射到宿主机的磁盘目录上。2. 部署环境准备与规划Immich官方推荐使用Docker和Docker Compose进行部署这能简化多服务依赖的管理。下面我们将规划一个典型的单机部署环境。2.1 系统与软件要求组件最低要求推荐配置说明操作系统Linux (Ubuntu 20.04, Debian 11), macOS, Windows (WSL2)Linux服务器发行版生产环境建议使用Linux服务器。Docker20.10.0最新稳定版必须安装Docker Engine。Docker Compose2.0.0随Docker Desktop安装或独立安装v2用于编排多容器。CPU2核4核或更多机器学习服务吃CPU核心越多批量分析越快。内存4 GB8 GB 或更多6-8GB是流畅运行的基础照片库巨大则需要更多。存储50 GB (取决于照片库大小)SSD容量为照片库的2倍以上SSD能极大提升缩略图生成和浏览体验。预留空间用于缩略图和编码视频。网络可访问互联网以下载镜像稳定的局域网/宽带上传和浏览速度体验关键。2.2 目录结构规划在宿主机上创建一个清晰的工作目录用于存放配置和数据。假设我们以/opt/immich作为根目录。sudo mkdir -p /opt/immich cd /opt/immich # 创建子目录用于持久化数据 sudo mkdir -p pgdata redisdata machine-learning model-cache uploads library thumbnails encoded-videos # 修改目录权限确保Docker容器可写根据你的Docker运行用户调整 sudo chown -R 1000:1000 /opt/immich/* # 假设容器内用户UID为1000最简便方式是先启动看日志报错再调整目录说明:pgdata: PostgreSQL数据库数据。redisdata: Redis数据。machine-learning: 机器学习模型缓存可加速后续启动。model-cache: 另一个模型缓存目录。uploads/library/thumbnails/encoded-videos: 对应上文提到的四种媒体文件存储位置。2.3 获取官方部署文件官方提供了维护良好的Docker Compose配置文件。我们直接使用它。# 进入工作目录 cd /opt/immich # 下载最新的 docker-compose.yml 和 .env 文件 wget https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml wget https://github.com/immich-app/immich/releases/latest/download/example.env -O .env下载后你会得到两个关键文件docker-compose.yml: 定义了所有服务server, web, postgres, redis, machine-learning的容器配置、网络和卷映射。.env: 环境变量配置文件用于设置数据库密码、密钥、文件路径等关键参数。这是你需要主要修改的文件。3. 配置与启动 Immich3.1 关键环境变量配置使用文本编辑器如nano或vim打开.env文件进行配置。nano .env你需要关注并修改以下关键变量。以#开头的行是注释可以阅读但不一定需要修改。# 数据库配置 DB_HOSTNAMEimmich_postgres # 通常与docker-compose中服务名一致无需修改 DB_PORT5432 DB_USERNAMEpostgres DB_PASSWORDyour_strong_postgres_password_here # 必须修改设置一个强密码。 DB_DATABASE_NAMEimmich # Immich 服务器配置 IMMICH_LOG_LEVELlog IMMICH_MACHINE_LEARNING_URLhttp://immich-machine-learning:3003 IMMICH_MACHINE_LEARNING_PORT3003 # 密钥 - 安全关键 # 用于加密JWT令牌和敏感数据。务必使用 openssl rand -base64 64 生成并替换。 JWT_SECRETyour_generated_jwt_secret_here # 用于文件完整性检查等。 DB_ENCRYPTION_KEYyour_generated_db_encryption_key_here # 文件上传大小限制根据你的需求调整 IMMICH_MAX_FILE_SIZE50M # 单文件最大50MB # 最重要的路径配置 # 将这些路径映射到你在宿主机上创建的目录 UPLOAD_LOCATION/opt/immich/uploads LIBRARY_LOCATION/opt/immich/library THUMBNAIL_LOCATION/opt/immich/thumbnails ENCODED_VIDEO_LOCATION/opt/immich/encoded-videos # PostgreSQL 数据目录映射宿主机目录 PGDATA/opt/immich/pgdata # Redis 数据目录映射宿主机目录 REDIS_DATA/opt/immich/redisdata # 机器学习模型缓存目录映射宿主机目录避免重复下载 MACHINE_LEARNING_CACHE_FOLDER/opt/immich/machine-learning MODEL_CACHE_FOLDER/opt/immich/model-cache # 时区 TZAsia/Shanghai # 设置为你的本地时区保证照片时间戳正确配置要点:密码与密钥DB_PASSWORD、JWT_SECRET、DB_ENCRYPTION_KEY必须替换为你自己生成的强随机字符串。可以使用命令openssl rand -base64 32生成。文件路径UPLOAD_LOCATION等路径必须与你在宿主机上创建的目录绝对路径一致且确保Docker容器有读写权限。这是数据持久化的关键。时区正确设置TZ否则照片的拍摄时间可能显示错误。3.2 启动 Immich 服务配置好.env文件后使用 Docker Compose 启动所有服务。# 在 /opt/immich 目录下执行 docker compose up -d-d参数表示在后台运行。执行后Docker会从Docker Hub拉取所需的镜像首次运行耗时较长然后创建并启动所有容器。你可以使用以下命令查看服务状态和日志# 查看所有容器状态 docker compose ps # 查看所有容器的实时日志CtrlC退出 docker compose logs -f # 仅查看某个服务的日志例如server docker compose logs -f immich-server当看到immich-server日志中出现类似“Immich Server is running on port 3001”的信息并且其他服务没有持续报错时说明启动成功。3.3 初始访问与用户创建打开浏览器访问http://你的服务器IP地址:2283。这是Immich Web前端的默认端口。首次访问会进入管理员注册页面。输入你的邮箱、姓名、密码创建一个管理员账户。这个账户拥有最高权限。登录后你将进入Immich的主界面。4. 核心功能配置与使用详解成功登录后你需要进行一些初始配置才能开始高效使用Immich。4.1 移动端自动备份设置Immich的精髓之一就是手机App自动备份。你需要在应用商店Google Play或Apple App Store搜索“Immich”并安装。获取服务器地址和API密钥在Web端点击左下角用户头像 -设置-API密钥。点击创建新密钥为其命名如“My iPhone”然后复制生成的密钥字符串。此密钥只显示一次请妥善保存。服务器地址通常是http://你的服务器IP:2283/api。如果你配置了域名和反向代理则可能是https://你的域名/api。配置手机App打开手机Immich App。在服务器地址处填入上一步的地址。在API密钥处粘贴复制的密钥。保存后App会连接服务器。你可以在设置中开启“自动备份”选择要备份的相册、是否仅Wi-Fi下备份等。4.2 管理存储设置与库在Web端设置-存储中你可以看到之前配置的存储路径的使用情况。确保你的存储目录有足够空间。“库” (Library) 的概念在Immich中一个“库”是一个顶级容器用于存放所有资产。你上传或备份的照片视频都会进入你用户的库中。管理员可以为其他用户创建独立的库。4.3 启用并理解智能搜索Immich的智能搜索依赖于机器学习服务对照片的分析。分析不会自动开始需要手动触发或等待计划任务。启动智能识别进入设置-机器学习。你可以看到人脸识别、物体识别、CLIP语义搜索等选项。点击启动任务或重新扫描库系统会将库中所有未分析的图片加入处理队列。查看处理进度在Web端右上角有一个活动图标通常是个铃铛或进度条点击可以查看后台任务队列。处理大量照片需要很长时间请耐心等待。你可以在docker compose logs -f immich-machine-learning中查看分析日志。使用智能搜索分析完成后在主页的搜索框中你可以输入诸如“狗”、“沙滩”、“生日蛋糕”、“两个人”等自然语言进行搜索。系统会返回相关的照片。你还可以在“探索”页面中按人物、物体类型等浏览已识别的结果。4.4 相册、共享与用户管理相册你可以手动创建相册或将搜索、人脸识别结果保存为相册方便整理和分享。共享可以将相册共享给其他Immich用户需要先创建用户生成分享链接可设置密码和有效期。用户管理管理员可以在设置-用户管理中创建新用户并分配存储配额和权限。5. 常见问题排查与优化5.1 部署与启动问题问题现象可能原因检查与解决方式访问http://IP:2283无法连接1. 防火墙未开放端口。2. 容器启动失败。1. 检查服务器防火墙如ufw是否允许2283端口。2. 运行docker compose logs查看具体错误日志。容器不断重启1. 环境变量配置错误如路径不存在。2. 数据库连接失败。3. 端口冲突。1. 检查.env文件中的路径是否正确宿主机目录是否存在且有权限。2. 查看immich-server日志常见数据库连接错误是密码不对或Postgres容器未就绪。3. 运行docker compose ps查看端口映射检查2283、3001等端口是否被占用。上传照片失败提示“无法到达服务器”1. 手机App服务器地址配置错误。2. 服务器地址无法从外网访问。1. 确认App中服务器地址为http://服务器IP:2283/api。2. 如果你在家庭网络需在路由器设置端口转发2283, 3001。注意内网穿透的安全风险。机器学习服务启动慢或失败1. 首次需要下载数百MB的模型文件网络慢。2. 宿主机内存不足。1. 查看immich-machine-learning容器日志等待下载完成。可尝试配置科学的上网环境加速。2. 确保宿主机有足够可用内存4GB。5.2 功能与性能问题问题现象可能原因检查与解决方式智能搜索无结果1. 机器学习分析未完成。2. 机器学习服务未运行或分析出错。1. 在“活动”页面查看分析任务队列状态。2. 检查immich-machine-learning容器是否运行日志是否有错误。尝试在设置中重新启动分析任务。浏览照片缩略图加载慢1. 首次访问需要生成缩略图CPU资源紧张。2. 存储介质是机械硬盘。1. 等待初始缩略图生成完成。2. 考虑使用SSD作为存储盘。这是提升体验最有效的方式。视频无法播放或转码失败1. 视频格式不支持。2. 编码服务所需编解码器缺失。1. Immich依赖FFmpeg进行视频转码。确保Docker镜像包含FFmpeg官方镜像已包含。2. 查看immich-server日志中关于视频处理的错误信息。复杂的视频可能需要更多CPU资源。手机备份耗电快或上传慢1. App设置为始终后台活动。2. 上传大量原图网络慢。1. 在手机系统设置中为Immich App合理设置电池优化选项不要过度限制。2. 在App设置中可以开启“仅Wi-Fi上传”并选择“备份原图”或“备份压缩后的版本”以节省流量和电量。5.3 数据备份与迁移重要Immich不负责备份你的媒体文件Docker Compose 配置将数据卷映射到了宿主机目录/opt/immich/*你需要自行备份这些目录。备份策略数据库定期备份/opt/immich/pgdata目录或者使用pg_dump命令导出SQL。媒体文件备份/opt/immich/library和/opt/immich/uploads如果不同。这是你最珍贵的资产。配置文件备份/opt/immich/docker-compose.yml和/opt/immich/.env注意.env包含密码需安全存储。迁移在新服务器上创建相同目录结构复制所有数据文件pgdata, library等复制docker-compose.yml和.env文件然后运行docker compose up -d即可。6. 生产环境最佳实践与扩展将Immich用于长期、重要的照片管理时需要考虑更多生产级别的因素。6.1 安全加固使用反向代理和HTTPS绝不要将http://IP:2283直接暴露在公网。使用Nginx或Caddy作为反向代理并配置SSL证书如Let‘s Encrypt启用HTTPS。# Nginx 配置示例片段 (在 server 块内) location / { 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_set_header Upgrade $http_upgrade; # proxy_set_header Connection upgrade; }强化密码与密钥确保.env文件中的DB_PASSWORD、JWT_SECRET等是足够长且随机的字符串。并限制.env文件的访问权限chmod 600 .env。定期更新关注Immich的GitHub Releases定期执行docker compose pull和docker compose up -d来更新到新版本修复安全漏洞。6.2 性能与稳定性优化存储分离对于大型库考虑将媒体文件存储在与系统盘分离的、更大容量的SSD或高速NAS上并通过网络挂载如NFS或直接映射到数据盘。资源限制在docker-compose.yml中为immich-machine-learning服务添加资源限制防止其耗尽系统资源。# 在 immich-machine-learning 服务下添加 deploy: resources: limits: cpus: 2.0 # 限制使用2个CPU核心 memory: 4G # 限制使用4GB内存外部数据库对于超大规模部署可以考虑使用宿主机上独立管理的PostgreSQL实例而非Docker容器内的以便进行更专业的备份和调优。6.3 监控与维护日志收集配置Docker的日志驱动或将容器日志定向到外部日志系统如ELK Stack便于问题排查。健康检查Immich服务提供了健康检查端点。可以结合Prometheus和Grafana监控服务状态。制定备份计划自动化你的备份流程。可以使用脚本定期打包library目录并用pg_dump备份数据库然后将备份文件同步到异地存储如另一台服务器或对象存储。通过以上步骤你不仅成功部署了一个功能强大的私人照片管理平台还为其长期稳定运行打下了基础。Immich的活跃社区和持续开发意味着它会不断进化你可以通过关注其GitHub仓库来获取最新功能和改进。接下来你可以尝试探索其API进行二次开发或者结合其他工具如PhotoPrism构建更复杂的媒体工作流。
从零部署Immich：构建私有智能相册，替代Google Photos
在实际个人数据管理中照片和视频的备份、整理与检索一直是个痛点。依赖单一云服务商不仅存在隐私风险还可能面临服务关闭、费用上涨或功能限制。自建方案如Nextcloud虽然功能全面但在媒体文件的智能管理、快速浏览和高效检索上往往力不从心。Immich的出现正是为了解决这一系列问题。它是一个专注于个人照片和视频备份与管理的开源、自托管解决方案其核心目标是成为Google Photos的替代品让你完全掌控自己的数据。Immich的设计理念非常明确快速、安全、智能。它提供了接近原生应用的上传和浏览体验支持从手机自动备份并利用机器学习模型为你的媒体库添加人物识别、物体识别、场景分类等智能标签从而实现强大的语义搜索功能。对于拥有大量照片、注重隐私且希望获得现代化管理体验的开发者或技术爱好者来说Immich是一个极具吸引力的选择。本文将带你从零开始理解Immich的核心架构完成一键式部署并深入配置其关键功能最终构建一个完全属于你自己的高效照片管理中枢。1. 理解 Immich 的核心架构与组件在动手部署之前必须先理解Immich的架构。它不是一个单一的应用而是一个由多个微服务组成的系统。这种设计带来了灵活性和可扩展性但也意味着部署时需要协调好各个组件。盲目安装很容易导致服务无法启动或功能异常。1.1 核心服务组件及其职责Immich 主要包含以下四个核心服务它们通过Docker容器进行隔离和协作Immich Server (immich-server): 这是应用的大脑一个基于NestJS构建的Node.js后端API服务器。它处理所有业务逻辑包括用户认证、资产管理上传、删除、整理、元数据提取、以及向机器学习服务发起分析请求。Immich Web (immich-web): 这是用户交互的前端界面一个基于React构建的单页应用。你通过浏览器访问、浏览照片、进行搜索等操作都是在与这个服务交互。它通过API与Server通信。PostgreSQL (postgres): 作为主数据库存储所有的结构化数据。这包括用户信息、相册、资产照片/视频的元数据如拍摄时间、地点、文件路径、人脸识别数据、标签等。所有重要的业务数据都存在这里。Redis (redis): 用作缓存和消息队列。机器学习任务队列、会话Session存储、临时数据缓存等都依赖于Redis。它能显著提升系统响应速度和处理并发任务的能力。1.2 机器学习微服务智能化的引擎Immich的“智能”特性如人物识别、物体识别和CLIP搜索依赖于独立的机器学习微服务。在官方部署中通常包含以下两个机器学习 (immich-machine-learning): 这是一个封装了多种AI模型的Python服务。它接收来自Server的任务对图片进行分析识别人脸、物体和场景并将结果返回。这是消耗计算资源尤其是CPU/GPU的主要服务。TensorFlow Serving (tensorflow): 某些特定的模型如MobileNet可能通过TensorFlow Serving来提供推理服务immich-machine-learning会调用它。注意机器学习服务对硬件有一定要求。CPU模式下分析速度较慢尤其是初始处理大量历史照片时。如果有NVIDIA GPU并配置了CUDA可以极大加速分析过程。1.3 存储架构原图、缩略图与元数据理解文件存储方式对后续管理和备份至关重要上传文件 (Upload Location): 用户上传的原始照片和视频文件存储在这里。目录结构通常会按年份/月份组织。库文件 (Library Location): 与上传目录类似是资产的实际存储位置。在典型设置中“上传”目录会被移动到“库”目录进行永久存储。缩略图 (Thumbnail Location): 系统会自动生成多种尺寸的缩略图用于列表预览、详情页展示等这些文件存储在此处以避免每次请求都动态处理原图。编码视频 (Encoded Video Location): 针对视频文件系统会生成适用于网页播放的编码版本如MP4存储在这里。在Docker部署中这些路径通常通过卷Volumes或绑定挂载Bind Mounts映射到宿主机的磁盘目录上。2. 部署环境准备与规划Immich官方推荐使用Docker和Docker Compose进行部署这能简化多服务依赖的管理。下面我们将规划一个典型的单机部署环境。2.1 系统与软件要求组件最低要求推荐配置说明操作系统Linux (Ubuntu 20.04, Debian 11), macOS, Windows (WSL2)Linux服务器发行版生产环境建议使用Linux服务器。Docker20.10.0最新稳定版必须安装Docker Engine。Docker Compose2.0.0随Docker Desktop安装或独立安装v2用于编排多容器。CPU2核4核或更多机器学习服务吃CPU核心越多批量分析越快。内存4 GB8 GB 或更多6-8GB是流畅运行的基础照片库巨大则需要更多。存储50 GB (取决于照片库大小)SSD容量为照片库的2倍以上SSD能极大提升缩略图生成和浏览体验。预留空间用于缩略图和编码视频。网络可访问互联网以下载镜像稳定的局域网/宽带上传和浏览速度体验关键。2.2 目录结构规划在宿主机上创建一个清晰的工作目录用于存放配置和数据。假设我们以/opt/immich作为根目录。sudo mkdir -p /opt/immich cd /opt/immich # 创建子目录用于持久化数据 sudo mkdir -p pgdata redisdata machine-learning model-cache uploads library thumbnails encoded-videos # 修改目录权限确保Docker容器可写根据你的Docker运行用户调整 sudo chown -R 1000:1000 /opt/immich/* # 假设容器内用户UID为1000最简便方式是先启动看日志报错再调整目录说明:pgdata: PostgreSQL数据库数据。redisdata: Redis数据。machine-learning: 机器学习模型缓存可加速后续启动。model-cache: 另一个模型缓存目录。uploads/library/thumbnails/encoded-videos: 对应上文提到的四种媒体文件存储位置。2.3 获取官方部署文件官方提供了维护良好的Docker Compose配置文件。我们直接使用它。# 进入工作目录 cd /opt/immich # 下载最新的 docker-compose.yml 和 .env 文件 wget https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml wget https://github.com/immich-app/immich/releases/latest/download/example.env -O .env下载后你会得到两个关键文件docker-compose.yml: 定义了所有服务server, web, postgres, redis, machine-learning的容器配置、网络和卷映射。.env: 环境变量配置文件用于设置数据库密码、密钥、文件路径等关键参数。这是你需要主要修改的文件。3. 配置与启动 Immich3.1 关键环境变量配置使用文本编辑器如nano或vim打开.env文件进行配置。nano .env你需要关注并修改以下关键变量。以#开头的行是注释可以阅读但不一定需要修改。# 数据库配置 DB_HOSTNAMEimmich_postgres # 通常与docker-compose中服务名一致无需修改 DB_PORT5432 DB_USERNAMEpostgres DB_PASSWORDyour_strong_postgres_password_here # 必须修改设置一个强密码。 DB_DATABASE_NAMEimmich # Immich 服务器配置 IMMICH_LOG_LEVELlog IMMICH_MACHINE_LEARNING_URLhttp://immich-machine-learning:3003 IMMICH_MACHINE_LEARNING_PORT3003 # 密钥 - 安全关键 # 用于加密JWT令牌和敏感数据。务必使用 openssl rand -base64 64 生成并替换。 JWT_SECRETyour_generated_jwt_secret_here # 用于文件完整性检查等。 DB_ENCRYPTION_KEYyour_generated_db_encryption_key_here # 文件上传大小限制根据你的需求调整 IMMICH_MAX_FILE_SIZE50M # 单文件最大50MB # 最重要的路径配置 # 将这些路径映射到你在宿主机上创建的目录 UPLOAD_LOCATION/opt/immich/uploads LIBRARY_LOCATION/opt/immich/library THUMBNAIL_LOCATION/opt/immich/thumbnails ENCODED_VIDEO_LOCATION/opt/immich/encoded-videos # PostgreSQL 数据目录映射宿主机目录 PGDATA/opt/immich/pgdata # Redis 数据目录映射宿主机目录 REDIS_DATA/opt/immich/redisdata # 机器学习模型缓存目录映射宿主机目录避免重复下载 MACHINE_LEARNING_CACHE_FOLDER/opt/immich/machine-learning MODEL_CACHE_FOLDER/opt/immich/model-cache # 时区 TZAsia/Shanghai # 设置为你的本地时区保证照片时间戳正确配置要点:密码与密钥DB_PASSWORD、JWT_SECRET、DB_ENCRYPTION_KEY必须替换为你自己生成的强随机字符串。可以使用命令openssl rand -base64 32生成。文件路径UPLOAD_LOCATION等路径必须与你在宿主机上创建的目录绝对路径一致且确保Docker容器有读写权限。这是数据持久化的关键。时区正确设置TZ否则照片的拍摄时间可能显示错误。3.2 启动 Immich 服务配置好.env文件后使用 Docker Compose 启动所有服务。# 在 /opt/immich 目录下执行 docker compose up -d-d参数表示在后台运行。执行后Docker会从Docker Hub拉取所需的镜像首次运行耗时较长然后创建并启动所有容器。你可以使用以下命令查看服务状态和日志# 查看所有容器状态 docker compose ps # 查看所有容器的实时日志CtrlC退出 docker compose logs -f # 仅查看某个服务的日志例如server docker compose logs -f immich-server当看到immich-server日志中出现类似“Immich Server is running on port 3001”的信息并且其他服务没有持续报错时说明启动成功。3.3 初始访问与用户创建打开浏览器访问http://你的服务器IP地址:2283。这是Immich Web前端的默认端口。首次访问会进入管理员注册页面。输入你的邮箱、姓名、密码创建一个管理员账户。这个账户拥有最高权限。登录后你将进入Immich的主界面。4. 核心功能配置与使用详解成功登录后你需要进行一些初始配置才能开始高效使用Immich。4.1 移动端自动备份设置Immich的精髓之一就是手机App自动备份。你需要在应用商店Google Play或Apple App Store搜索“Immich”并安装。获取服务器地址和API密钥在Web端点击左下角用户头像 -设置-API密钥。点击创建新密钥为其命名如“My iPhone”然后复制生成的密钥字符串。此密钥只显示一次请妥善保存。服务器地址通常是http://你的服务器IP:2283/api。如果你配置了域名和反向代理则可能是https://你的域名/api。配置手机App打开手机Immich App。在服务器地址处填入上一步的地址。在API密钥处粘贴复制的密钥。保存后App会连接服务器。你可以在设置中开启“自动备份”选择要备份的相册、是否仅Wi-Fi下备份等。4.2 管理存储设置与库在Web端设置-存储中你可以看到之前配置的存储路径的使用情况。确保你的存储目录有足够空间。“库” (Library) 的概念在Immich中一个“库”是一个顶级容器用于存放所有资产。你上传或备份的照片视频都会进入你用户的库中。管理员可以为其他用户创建独立的库。4.3 启用并理解智能搜索Immich的智能搜索依赖于机器学习服务对照片的分析。分析不会自动开始需要手动触发或等待计划任务。启动智能识别进入设置-机器学习。你可以看到人脸识别、物体识别、CLIP语义搜索等选项。点击启动任务或重新扫描库系统会将库中所有未分析的图片加入处理队列。查看处理进度在Web端右上角有一个活动图标通常是个铃铛或进度条点击可以查看后台任务队列。处理大量照片需要很长时间请耐心等待。你可以在docker compose logs -f immich-machine-learning中查看分析日志。使用智能搜索分析完成后在主页的搜索框中你可以输入诸如“狗”、“沙滩”、“生日蛋糕”、“两个人”等自然语言进行搜索。系统会返回相关的照片。你还可以在“探索”页面中按人物、物体类型等浏览已识别的结果。4.4 相册、共享与用户管理相册你可以手动创建相册或将搜索、人脸识别结果保存为相册方便整理和分享。共享可以将相册共享给其他Immich用户需要先创建用户生成分享链接可设置密码和有效期。用户管理管理员可以在设置-用户管理中创建新用户并分配存储配额和权限。5. 常见问题排查与优化5.1 部署与启动问题问题现象可能原因检查与解决方式访问http://IP:2283无法连接1. 防火墙未开放端口。2. 容器启动失败。1. 检查服务器防火墙如ufw是否允许2283端口。2. 运行docker compose logs查看具体错误日志。容器不断重启1. 环境变量配置错误如路径不存在。2. 数据库连接失败。3. 端口冲突。1. 检查.env文件中的路径是否正确宿主机目录是否存在且有权限。2. 查看immich-server日志常见数据库连接错误是密码不对或Postgres容器未就绪。3. 运行docker compose ps查看端口映射检查2283、3001等端口是否被占用。上传照片失败提示“无法到达服务器”1. 手机App服务器地址配置错误。2. 服务器地址无法从外网访问。1. 确认App中服务器地址为http://服务器IP:2283/api。2. 如果你在家庭网络需在路由器设置端口转发2283, 3001。注意内网穿透的安全风险。机器学习服务启动慢或失败1. 首次需要下载数百MB的模型文件网络慢。2. 宿主机内存不足。1. 查看immich-machine-learning容器日志等待下载完成。可尝试配置科学的上网环境加速。2. 确保宿主机有足够可用内存4GB。5.2 功能与性能问题问题现象可能原因检查与解决方式智能搜索无结果1. 机器学习分析未完成。2. 机器学习服务未运行或分析出错。1. 在“活动”页面查看分析任务队列状态。2. 检查immich-machine-learning容器是否运行日志是否有错误。尝试在设置中重新启动分析任务。浏览照片缩略图加载慢1. 首次访问需要生成缩略图CPU资源紧张。2. 存储介质是机械硬盘。1. 等待初始缩略图生成完成。2. 考虑使用SSD作为存储盘。这是提升体验最有效的方式。视频无法播放或转码失败1. 视频格式不支持。2. 编码服务所需编解码器缺失。1. Immich依赖FFmpeg进行视频转码。确保Docker镜像包含FFmpeg官方镜像已包含。2. 查看immich-server日志中关于视频处理的错误信息。复杂的视频可能需要更多CPU资源。手机备份耗电快或上传慢1. App设置为始终后台活动。2. 上传大量原图网络慢。1. 在手机系统设置中为Immich App合理设置电池优化选项不要过度限制。2. 在App设置中可以开启“仅Wi-Fi上传”并选择“备份原图”或“备份压缩后的版本”以节省流量和电量。5.3 数据备份与迁移重要Immich不负责备份你的媒体文件Docker Compose 配置将数据卷映射到了宿主机目录/opt/immich/*你需要自行备份这些目录。备份策略数据库定期备份/opt/immich/pgdata目录或者使用pg_dump命令导出SQL。媒体文件备份/opt/immich/library和/opt/immich/uploads如果不同。这是你最珍贵的资产。配置文件备份/opt/immich/docker-compose.yml和/opt/immich/.env注意.env包含密码需安全存储。迁移在新服务器上创建相同目录结构复制所有数据文件pgdata, library等复制docker-compose.yml和.env文件然后运行docker compose up -d即可。6. 生产环境最佳实践与扩展将Immich用于长期、重要的照片管理时需要考虑更多生产级别的因素。6.1 安全加固使用反向代理和HTTPS绝不要将http://IP:2283直接暴露在公网。使用Nginx或Caddy作为反向代理并配置SSL证书如Let‘s Encrypt启用HTTPS。# Nginx 配置示例片段 (在 server 块内) location / { 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_set_header Upgrade $http_upgrade; # proxy_set_header Connection upgrade; }强化密码与密钥确保.env文件中的DB_PASSWORD、JWT_SECRET等是足够长且随机的字符串。并限制.env文件的访问权限chmod 600 .env。定期更新关注Immich的GitHub Releases定期执行docker compose pull和docker compose up -d来更新到新版本修复安全漏洞。6.2 性能与稳定性优化存储分离对于大型库考虑将媒体文件存储在与系统盘分离的、更大容量的SSD或高速NAS上并通过网络挂载如NFS或直接映射到数据盘。资源限制在docker-compose.yml中为immich-machine-learning服务添加资源限制防止其耗尽系统资源。# 在 immich-machine-learning 服务下添加 deploy: resources: limits: cpus: 2.0 # 限制使用2个CPU核心 memory: 4G # 限制使用4GB内存外部数据库对于超大规模部署可以考虑使用宿主机上独立管理的PostgreSQL实例而非Docker容器内的以便进行更专业的备份和调优。6.3 监控与维护日志收集配置Docker的日志驱动或将容器日志定向到外部日志系统如ELK Stack便于问题排查。健康检查Immich服务提供了健康检查端点。可以结合Prometheus和Grafana监控服务状态。制定备份计划自动化你的备份流程。可以使用脚本定期打包library目录并用pg_dump备份数据库然后将备份文件同步到异地存储如另一台服务器或对象存储。通过以上步骤你不仅成功部署了一个功能强大的私人照片管理平台还为其长期稳定运行打下了基础。Immich的活跃社区和持续开发意味着它会不断进化你可以通过关注其GitHub仓库来获取最新功能和改进。接下来你可以尝试探索其API进行二次开发或者结合其他工具如PhotoPrism构建更复杂的媒体工作流。
