Immich 中文指南：高性能自托管照片与视频管理方案的全景解读与部署实战

Immich 中文指南高性能自托管照片与视频管理方案的全景解读与部署实战【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich本篇基于 Immich 仓库的简体中文 README 展开带你完整理解这个自托管照片与视频管理项目的功能矩阵移动端/网页端能力对照、官方演示账号信息并结合仓库内的install.sh一键安装脚本、docker/docker-compose.yml容器编排与环境变量配置讲清楚一套 Immich 实例的四大服务组成、硬件门槛与底层实现要点读完即可独立完成部署并理解其架构原理。项目定位自托管的照片与视频管理方案Immich 是一个高性能的自托管照片与视频管理解决方案High performance self-hosted photo and video management solution采用 AGPL v3 协议开源见 LICENSE。需要特别说明的是简体中文 README 并非由 Immich 官方团队维护而是依靠社区贡献者更新因此内容可能不会及时同步这一点在文档开头有明确声明。README 中有两条关键提示值得所有自托管用户牢记备份警告为了您宝贵的照片与视频请始终遵守 3-2-1 备份方案3 份副本、2 种不同介质、1 份异地存储。Immich 是照片的“管理中枢”不应被当作唯一的备份终点完整文档入口详细的项目文档与安装教程以仓库内docs/目录为准例如 系统要求、架构说明、安装文档目录。此外仓库还收录了 21 份其他语言的 README 翻译见 README 英文主版本 及各语言分册目录 readme_i18n包括正体中文README_zh_TW.md、日文、韩文、德文等方便不同语言区用户查阅。在线演示与体验账号README 提供了官方在线演示站点供用户快速体验全部功能在移动端 App 中可将演示站点的地址填入服务终端链接Server Endpoint URL完成连接。登录认证信息邮箱密码demoimmich.appdemo功能特性矩阵移动端 vs 网页端README 最核心的内容是一张覆盖 30 项能力的功能矩阵逐项标注了移动端Mobile与网页端Web的支持情况。完整矩阵如下功能特性移动端网页端上传并查看照片和视频是是软件运行时自动备份是N/A忽略重复的项目是是选择需要备份的相册是N/A下载照片和视频到本地是是多用户支持是是相册与共享相册是是可拖动的快速滚动条是是支持RAW格式是是元数据视图EXIF、地图是是通过元数据、对象、人脸和标签进行搜索是是管理功能用户管理否是后台备份是N/A虚拟滚动是是OAuth 支持是是API KeysN/A是实况照片备份和查看是是支持360度全景图显示否是用户自定义存储结构是是公共分享是是归档与收藏功能是是足迹地图是是好友分享是是人脸识别与分组是是回忆那年今日是是离线支持是否只读相册是是照片堆叠是是标签否是文件夹浏览否是从矩阵可以读出几点选型参考移动端是备份入口自动备份、后台备份、离线支持均为移动端独有网页端承担管理职责用户管理、API Keys、360 全景显示等仅在网页端提供。矩阵中通过元数据、对象、人脸和标签进行搜索这一智能搜索能力其背后实现可以在服务端源码中找到佐证。部署实战从一键脚本到容器编排一键安装脚本 install.sh仓库根目录的 install.sh 实现了最小化的部署流程其执行链路清晰可查创建目录create_immich_directory()在当前目录创建./immich-app若已存在则复用并覆盖 YAML 文件下载编排文件download_docker_compose_file()与download_dot_env_file()从最新 release 包中拉取docker-compose.yml和example.env后者保存为.env生成随机密码generate_random_password()用$RANDOM 时间戳做 SHA-256 后取 Base64 前 10 位替换.env中默认的DB_PASSWORDpostgres避免使用弱口令启动容器start_docker_compose()检查docker compose命令可用后执行docker compose up --remove-orphans -d。安装完成后脚本会输出访问地址http://本机IP:2283macOS 下通过ipconfig getifaddr en0获取 IP并给出三步修改配置的指引先docker compose down停止容器再编辑.env数据库、Redis、备份/上传位置等最后docker compose up --remove-orphans -d重新拉起。脚本对每一步失败都有独立的退出码10–14便于排障。容器编排 docker/docker-compose.ymldocker/docker-compose.yml 定义了一套由 4 个服务组成的实例服务镜像职责immich-serverghcr.io/immich-app/immich-server:${IMMICH_VERSION:-release}REST API、缩略图/转码等后台任务对外暴露2283:2283immich-machine-learningghcr.io/immich-app/immich-machine-learning:${IMMICH_VERSION:-release}机器学习推理智能搜索、人脸识别等可加-cuda/-rocm/-armnn/-openvino/-rknn后缀启用硬件加速redisdocker.io/valkey/valkey:9锁定 digest后台任务队列healthcheck 为redis-cli pingdatabaseghcr.io/immich-app/postgres:14-vectorchord0.4.3-pgvectors0.2.0锁定 digest数据持久化初始化参数含--data-checksumsshm_size: 128mb几个值得注意的编排细节媒体存储路径由.env的UPLOAD_LOCATION挂载到容器内/datacompose 文件注释明确提醒不要直接改挂载行而要改.env数据库路径同理由DB_DATA_LOCATION控制immich-server通过depends_on声明依赖redis与database三者均设置restart: always与健康检查硬件加速通过extends引用 docker/hwaccel.transcoding.yml转码支持 nvenc/quicksync/rkmpp/vaapi 等与 docker/hwaccel.ml.yml推理支持 armnn/cuda/rocm/openvino/rknn默认注释状态即 CPU 模式另有面向开发者的 docker/docker-compose.dev.yml、docker/docker-compose.prod.yml附带 Prometheus Grafana 监控栈需在.env设置IMMICH_TELEMETRY_INCLUDEall与 docker/docker-compose.rootless.yml。compose 文件头部有重要注释请始终使用当前 release 的 docker-compose.ymlmain 分支上的 compose 文件可能与最新发布版不兼容。关键环境变量 example.envdocker/example.env 是部署后第一优先级需要编辑的文件核心变量如下# 上传文件的存储位置 UPLOAD_LOCATION./library # 数据库文件存储位置不支持网络共享 DB_DATA_LOCATION./postgres # 时区默认为 Etc/UTC可取消注释修改为任意 TZ 标识符 # TZEtc/UTC # 使用的 Immich 版本可锁定到具体版本号如 v2.1.0 IMMICH_VERSIONv3 # Postgres 连接口令务必改成随机强口令 # 仅允许 A-Za-z0-9 字符不含特殊字符或空格 DB_PASSWORDpostgres # 以下默认值无需修改 DB_USERNAMEpostgres DB_DATABASE_NAMEimmich更完整的变量清单可查阅 环境变变量文档。硬件与软件要求部署前建议对照 系统要求文档 自检操作系统推荐 64 位 Linux/*nixWindows 需通过 Docker Desktop 或 WSL2macOS 使用 Docker Desktop内存最低 6GB推荐 8GB仅 4GB 内存时可关闭机器学习功能运行CPU最低 2 核、推荐 4 核支持amd64与arm64自 v3 起amd64 平台的机器学习容器要求 x86-64-v2微架构级别约 2012 年后的 CPU 均满足存储Postgres 数据库文件DB_DATA_LOCATION应放在本地 SSD绝不能放在任何网络共享上缩略图与转码视频平均会使照片库体积增加 10–20%软件Docker 引擎 Compose 插件且必须是docker composev2 插件形式旧版docker-composev1已不再受支持。架构与源码级佐证README 功能矩阵中的能力在仓库中都有对应的实现支撑。根据 架构文档客户端三件套Flutter 编写的移动端 Appmobile/lib、SvelteKit TypeScript 的 Web 应用web/src、以及用于批量上传的 CLIpackages/cli三者都基于 OpenAPI 规格open-api/immich-openapi-specs.json自动生成 REST 客户端服务端TypeScript/Node.js Nest.js Kysely按六边形架构思路将技术实现src/repositories与业务逻辑src/services分离机器学习服务Python FastAPI全部模型使用 ONNX 格式独立容器化后可部署到别的机器上或整体禁用后台任务缩略图生成、元数据提取、视频转码、智能搜索、人脸识别、存储模板迁移等任务经由 RedisBullMQ队列调度执行部分任务存在依赖链例如智能搜索依赖缩略图先完成。以功能矩阵中的智能搜索为例server/src/services/search.service.ts 中的SearchService同时提供人员搜索searchPerson、地点搜索searchPlaces、元数据搜索searchMetadata支持 checksum 查重、分页游标与可见性过滤Locked 可见性需管理员权限等多种检索入口并在类内用一个容量 100 的 LRU 缓存embeddingCache new LRUMapstring, string(100)缓存文本向量减少重复调用机器学习服务获取 embedding 的开销——这正是搜索 by 元数据、对象、人脸矩阵项在代码层的落地。机器学习的模型实现同样有迹可循machine-learning/immich_ml/models 下按clip/智能搜索、facial_recognition/、ocr/三个子模块组织与 compose 中model-cache卷挂载的/cache模型下载缓存相配合。多语言支持Immich 的界面翻译同样采用社区众包模式翻译进度见官方 Weblate 平台多语言开发文档。仓库中 i18n/ 目录收录了 90 种语言的翻译文件en.json、zh_Hans.json、zh_Hant.json、ja.json等这些文件即界面文案的来源。许可与参与许可协议AGPL v3LICENSE与同类方案的对比可参考 对比文档贡献指南见 CONTRIBUTING.md社区维护的 README 分册readme_i18n也欢迎提交翻译改进。适用前提提醒本文所有命令、配置文件路径与环境变量均基于当前仓库实际内容适用于以 Docker Compose 方式部署的 Immich 实例由于简体中文 README 由社区维护若与最新 release 行为有出入请以 release 附带的 compose 文件与官方文档为准。【免费下载链接】immichHigh performance self-hosted photo and video management solution.项目地址: https://gitcode.com/GitHub_Trending/im/immich创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考