Immich 自托管照片与视频管理方案：功能矩阵、部署路径与特性实现对照（基于官方 README）

Immich 自托管照片与视频管理方案功能矩阵、部署路径与特性实现对照基于官方 README【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immichImmich 是一个高性能的自托管self-hosted照片与视频管理解决方案官方仓库的多语言 README本文以 readme_i18n/README_th_TH.md 泰语版为参照主体与 README.md 英文版互为印证完整列出了项目定位、在线演示、全量功能矩阵与翻译计划。读完本文你可以基于 README 的功能清单快速判断 Immich 是否满足你的媒体库管理需求并能结合仓库中的docker-compose.yml、.env示例、一键安装脚本与服务端源码理解每个特性背后的实际实现位置。项目定位与核心提示README 将 Immich 概括为 High performance self-hosted photo and video management solution高性能自托管照片和视频管理方案并给出两条关键提示备份警告重要README 以醒目警告形式提醒——对于重要的照片和视频请始终遵循 3-2-1 备份策略保留 3 份副本、存于 2 种不同介质、其中 1 份异地。这是官方文档中最强烈的安全提醒后文会结合仓库中的备份实现进一步说明。文档入口完整的安装指南与主文档位于官方文档站点immich.app仓库内的docs/目录即该文档站的源码例如 docs/docs/install/docker-compose.mdx、docs/docs/administration/backup-and-restore.md 可直接查阅。仓库采用 AGPL v3 许可证见 README.md 顶部的 License 徽标多语言 README 通过readme_i18n/目录维护包含泰语、简体中文、日语、韩语、德语等 20 余种语言的版本主 README 内嵌语言切换链接。在线演示Demo与登录凭证README 提供了一个公共演示实例供尚未自行部署的用户直观体验演示地址https://demo.immich.app移动端 App 接入时将该地址填入Server Endpoint URL即可连接。邮箱密码demoimmich.appdemo这一设计说明 Immich 的客户端移动端/网页端都是围绕服务器端点 URL 账号这一模型工作的自托管部署后同样以http://你的主机:2283作为端点默认端口 2283见 docker/docker-compose.yml 中immich-server的ports映射。完整功能矩阵README 原表全量继承README 的核心内容是一张特性 × 平台矩阵表明确区分了移动端Mobile与网页端Web的能力差异。下表完整继承 readme_i18n/README_th_TH.md 中的 27 行特性译成中文特性移动端网页端上传并查看视频与照片支持支持打开应用时自动备份支持N/A防止资产重复支持支持选择指定相册进行备份支持N/A将照片和视频下载到本地设备支持支持多用户支持支持支持相册与共享相册支持支持可拖动/可擦洗的滚动条支持支持RAW 格式支持支持支持元数据查看EXIF、地图支持支持基于元数据、物体、人脸与 CLIP 的搜索支持支持管理功能用户管理不支持支持后台备份支持N/A虚拟滚动Virtual scroll支持支持OAuth 支持支持支持API 密钥N/A支持LivePhoto / MotionPhoto 备份与播放支持支持360 度全景图展示不支持支持用户自定义存储结构支持支持公开分享支持支持归档与收藏夹支持支持全球地图支持支持与伴侣Partner共享支持支持人脸识别与聚类支持支持回忆x 年前支持支持离线支持支持不支持只读画廊支持支持照片堆叠Stacked Photos支持支持说明英文版 README.md 的功能表比泰语版多出Tags标签网页端支持与Folder View文件夹视图移动端与网页端均支持两行阅读时以英文版为准可得到最新全量能力。从这张矩阵可以提炼出三个平台差异要点移动端独有打开应用自动备份、指定相册备份、后台备份、离线支持——这些都是依赖操作系统通知/后台任务能力的功能故网页端标注 N/A。网页端独有用户管理Administration、API 密钥、360 度全景展示、Tags——管理与高级展示类功能集中在网页端。双端通用CLIP 语义搜索、人脸识别聚类、LivePhoto 播放、伙伴共享、地图、回忆等核心体验。功能特性在仓库中的实现落点源码佐证README 承诺的每项能力都能在仓库源码中找到对应实现以下按功能分组给出关键路径便于深入阅读服务端NestJS TypeScript服务端代码位于server/src/从 server/package.json 可确认其技术栈nestjs/core、bullmq基于 Redis 的任务队列、sharp图像解码/转码、fluent-ffmpeg视频转码、openid-clientOAuth、jsonwebtoken、bcrypt以及pg/kyselyPostgreSQL 与查询构建。server/src/services/目录下的 100 余个服务文件与功能矩阵几乎一一对应README 功能对应服务端实现示例路径人脸搜索 / 物体搜索 / CLIP 搜索search.service.ts人脸识别与聚类Personsperson.service.ts、cluster-group.service.ts相册与共享相册album.service.ts公开分享 / 分享链接shared-link.service.ts与伴侣共享partner.service.ts回忆x 年前memory.service.ts标签Tagstag.service.ts照片堆叠stack.service.ts防止资产重复duplicate.service.ts转码360 度全景、HLS 播放依赖transcoding.service.ts、hls.service.ts数据库自动备份database-backup.service.ts用户管理与 OAuth/API 密钥user-admin.service.ts、auth-admin.service.ts、api-key.service.ts移动端同步自动备份协议sync.service.ts全局地图map.service.ts此外server/src/下还有queries/36 个 SQL 查询文件、repositories/62 个数据访问层文件与emails/9 个 React Email 模板配合nodemailer发送通知体现了控制器 → 服务 → 仓储 → SQL的分层结构。机器学习服务Python搜索基于元数据、物体、人脸与 CLIP 这一卖点由独立的machine-learning/服务承担模型代码位于machine-learning/immich_ml/models/CLIP 视觉/文本编码machine-learning/immich_ml/models/clip/visual.py 中BaseCLIPVisualEncoder以(ModelType.VISUAL, ModelTask.SEARCH)注册将图片转为向量供语义搜索文本侧对应clip/textual.py。人脸检测与识别machine-learning/immich_ml/models/facial_recognition/ 下的detection.py与recognition.py分别完成检测框定位与人脸特征提取聚类结果由服务端的person.service.ts组织为人物页面。OCRmachine-learning/immich_ml/models/ocr/提供检测/识别/CTC 后处理支撑文字内容可搜索。从 docker/docker-compose.yml 的注释可推断硬件加速方式在 ML 镜像 tag 后追加cuda、rocm、openvino、rknn等后缀如${IMMICH_VERSION:-release}-cuda配合hwaccel.ml.yml扩展文件视频转码加速则由hwaccel.transcoding.yml提供nvenc、quicksync、vaapi等选项对应 docker/hwaccel.ml.yml 与 docker/hwaccel.transcoding.yml。移动端Flutter移动端代码在mobile/采用 Flutter Riverpod Drift本地 SQLite见mobile/drift_schemas/中的 31 个版本 schema 文件。README 中离线支持后台备份只读画廊等移动端能力即由mobile/lib/下的服务与 Provider 实现mobile/pigeon/目录定义了一系列平台通道接口native_sync_api.dart、permission_api.dart等用于与 Android/iOS 原生层交换权限与同步事件。网页端SvelteKit网页端位于web/Svelte SvelteKitweb/src/下约 253 个.svelte组件承担管理后台、CLIP 搜索、地图、360 度全景展示移动端标注不支持的功能在此实现等能力。部署方式与关键配置结合仓库实操文件README 提示安装指南以官方文档为准仓库内则提供了完整的可执行部署材料方案一一键安装脚本仓库根目录的 install.sh 是官方 one-click 安装脚本其执行流程从源码逐行可确认为创建./immich-app目录从 Immich 官方 release 下载最新的docker-compose.yml下载example.env并重命名为.env用sha256sum base64生成随机DB_PASSWORD替换默认值postgres执行docker compose up --remove-orphans -d启动打印访问地址http://主机IP:2283。注意脚本明确要求使用当前 release的 compose 文件而非 main 分支版本docker/docker-compose.yml 头部注释同样强调了这一点main 上的 compose 文件可能与最新 release 不兼容。方案二Docker Compose 手动部署docker/docker-compose.yml 定义了四个服务理解它们即可理解整套架构服务镜像作用immich-serverghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}主 API 与网页应用端口2283:2283依赖 redis 与 databaseimmich-machine-learningghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}CLIP/人脸/OCR 推理使用命名卷model-cache缓存模型redisvalkey/valkey:9BullMQ 任务队列缩略图、转码、分析等异步作业databaseimmich-app/postgres:14-vectorchord...-pgvectors...PostgreSQL 14 定制镜像内置 vectorchord 与 pgvectors 扩展支撑 CLIP/人脸向量的相似度检索开启--data-checksumsshm_size: 128mb配套的环境变量模板 docker/example.env 仅需理解 5 个变量变量示例值说明UPLOAD_LOCATION./library上传文件照片、视频、缩略图等的存放位置compose 中将其挂载到容器/dataDB_DATA_LOCATION./postgres数据库数据目录不支持网络共享盘TZ注释态时区取 IANA 时区标识IMMICH_VERSIONv3镜像版本可固定为具体版本如v2.1.0DB_PASSWORDpostgresPostgres 连接密码必须更换为随机强密码仅允许A-Za-z0-9字符DB_USERNAMEpostgres与DB_DATABASE_NAMEimmich无需修改。此外 compose 文件中还留有两处注释掉的extends块分别用于开启转码硬件加速与 ML 硬件加速需要时取消注释并选择对应服务名即可。备份策略README 警告的落地实现README 顶部的 3-2-1 备份警告不是空话——仓库中提供了完整的机制支撑详见 docs/docs/administration/backup-and-restore.md 与 server/src/services/database-backup.service.ts自动数据库备份Immich 每日定时默认凌晨 2:00创建数据库转储默认保留最近 14 份存储于UPLOAD_LOCATION/backups可在管理 设置 备份调整策略也可在管理 任务队列手动触发Create Database Dump。关键认知数据库只保存文件路径与元数据不包含照片视频本体。因此完整的 3-2-1 备份必须同时覆盖三块数据UPLOAD_LOCATION下的媒体文件backups、encoded-video、library、profile、thumbs、upload等子目录、DB_DATA_LOCATION数据库目录、以及.env中的DB_PASSWORD等配置。恢复路径网页端管理 维护中可直接从备份列表恢复恢复前会自动创建回滚点新实例也可在 Onboarding 阶段导入旧备份目录完成迁移。仓库还提供了可定时执行的备份脚本模板docs/docs/guides/template-backup-script.md 所指的 bash 模板便于把数据库 dump 媒体目录复制固化为 cron 任务。参与翻译与项目支持README 末尾的 Translations 一节说明翻译通过 Weblate 平台进行文档给出 hosted.weblate 上的 immich 项目入口与翻译进度徽标开发者指南位于 docs/docs/developer/translations.md。仓库根目录的i18n/目录存放了 90 种语言的界面翻译 JSON如 i18n/en.json、i18n/zh_Hans.json而readme_i18n/目录维护 README 本身的多语言版本——本文参照的 readme_i18n/README_th_TH.md 即其中之一。贡献与支持的详细说明见 docs/docs/overview/support-the-project.md 与 CONTRIBUTING.md。小结以 readme_i18n/README_th_TH.md 为骨架可以看出Immich 的 README 用一张功能矩阵清晰界定了移动端与网页端的分工移动端强在自动/后台备份与离线网页端强在管理与高级展示并用演示实例降低了首次体验门槛而结合 docker/docker-compose.yml、docker/example.env、install.sh 与server/src/services/下的服务实现可以确认README 承诺的 CLIP 搜索、人脸聚类、LivePhoto 播放、伙伴共享、回忆等功能均有明确的代码落点备份要求则配套了自动转储与恢复流程。若计划自托管建议路径为用install.sh或 release 版 compose 文件完成部署 → 修改.env中DB_PASSWORD与存储位置 → 按 3-2-1 策略配置数据库 UPLOAD_LOCATION 数据库目录的三重备份。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考