Immich - 自托管照片和视频管理解决方案-阿辉的技术笔记

📖 简介

Immich 是一个高性能的自托管照片和视频管理解决方案，旨在帮助用户轻松备份、组织和在自己的服务器上管理照片。Immich 让您可以轻松浏览、搜索和组织照片和视频，同时不牺牲隐私。

⚠️ 重要警告：

本项目正在非常活跃地开发中
可能存在 bug 或者随时有重大变更
不要把本软件作为您存储照片或视频的唯一方式
为了您宝贵的照片与视频，请始终遵守 3-2-1 备份方案

🔗 项目地址

GitHub 仓库: https://github.com/immich-app/immich
官方网站: https://immich.app
官方文档: https://docs.immich.app
在线演示: https://demo.immich.app (登录凭证: demo@immich.app / demo)

🌟 特性

移动端与网页端功能对比

功能特性	移动端	网页端
上传并查看照片和视频	✅	✅
软件运行时自动备份	✅	N/A
忽略重复的项目	✅	✅
选择需要备份的相册	✅	N/A
下载照片和视频到本地	✅	✅
多用户支持	✅	✅
相册与共享相册	✅	✅
支持 RAW 格式	✅	✅
元数据视图（EXIF、地图）	✅	✅
通过元数据、对象、人脸和标签进行搜索	✅	✅
管理功能（用户管理）	❌	✅
后台备份	✅	N/A
OAuth 支持	✅	✅
API Keys	N/A	✅
实况照片备份和查看	✅	✅
支持 360 度全景图显示	❌	✅
用户自定义存储结构	✅	✅
公共分享	✅	✅
归档与收藏功能	✅	✅
足迹地图	✅	✅
好友分享	✅	✅
人脸识别与分组	✅	✅
回忆（那年今日）	✅	✅
离线支持	✅	❌
只读相册	✅	✅
照片堆叠	✅	✅
标签	❌	✅
文件夹浏览	✅	✅

⚙️ 环境要求

最低要求

至少 4GB RAM 和 2 CPU 核心的系统
Docker

📦 安装/集成

Docker 快速安装（推荐）

步骤 1 - 下载所需文件

 # 创建目录
 mkdir ./immich-app
 cd ./immich-app
 
 # 下载 docker-compose.yml 文件
 wget -O docker-compose.yml https://github.com/immich-app/immich/releases/latest/download/docker-compose.yml
 
 # 下载 .env 文件
 wget -O .env https://github.com/immich-app/immich/releases/latest/download/example.env

步骤 2 - 配置环境变量

编辑 .env 文件，至少需要配置以下变量：

 # 上传文件的存储位置
 UPLOAD_LOCATION=./library
 
 # 数据库文件的存储位置（不支持网络共享）
 DB_DATA_LOCATION=./postgres
 
 # 设置时区（可选）
 # TZ=Asia/Shanghai
 
 # Immich 版本（使用 v2 表示最新稳定版）
 IMMICH_VERSION=v2
 
 # PostgreSQL 密码（建议修改为强密码）
 DB_PASSWORD=your_secure_password_here

步骤 3 - 启动容器

 # 启动 Immich 作为后台服务
 docker compose up -d

其他安装方式

Docker Compose（完整版）
Kubernetes
Unraid
TrueNAS
Synology
手动安装

详细安装指南请参考官方文档。

🚀 快速开始

1. 访问 Web 应用

服务器启动后，访问 http://<服务器IP地址>:2283

2. 注册管理员账户

第一个注册的用户将成为管理员，管理员可以添加其他用户。

3. 上传照片

通过网页界面上传测试照片。

4. 安装移动端应用

下载渠道：

Android: Google Play Store
iOS: Apple App Store
F-Droid: F-Droid
GitHub Releases: APK 文件
Obtainium: 从您的 Immich 服务器的工具页面获取配置链接

5. 登录移动端应用

在移动应用中使用服务器地址：http://<服务器IP地址>:2283

📱 使用教程

移动端备份照片

进入备份界面
- 点击右上角的云图标进入备份屏幕
选择备份相册
- 选择要备份到 Immich 服务器的相册
开始备份
- 滚动到底部，点击"开始备份"
- 备份时间取决于照片数量和大小

选择性备份照片

要快速测试，可以先选择性地上传少量照片：

在移动应用中选择特定照片进行备份

查看处理进度

选择"任务"标签页查看 Immich 处理照片的进度

⚙️ 配置与参数

主要环境变量

 # 必需配置
 UPLOAD_LOCATION=./library          # 上传文件存储路径
 DB_DATA_LOCATION=./postgres        # 数据库存储路径
 DB_PASSWORD=your_password          # 数据库密码
 
 # 可选配置
 TZ=Asia/Shanghai                   # 时区设置
 IMMICH_VERSION=v2                  # 版本控制
 DB_USERNAME=postgres               # 数据库用户名
 DB_DATABASE_NAME=immich            # 数据库名称

存储配置

UPLOAD_LOCATION: 照片和视频的存储位置
DB_DATA_LOCATION: PostgreSQL 数据库文件位置（必须是本地存储）

🔧 示例与最佳实践

从 Google Photos 迁移

使用 immich-go 工具从 Google Takeout 导入照片。

从现有档案导入

使用命令行界面上传照片
设置外部库导入现有照片档案

自动备份配置

配置移动设备自动备份到服务器

❓ FAQ/排错

常见问题

Q: 数据库备份包含照片吗？ A: 不，数据库只包含元数据和用户信息。您必须手动备份存储在 UPLOAD_LOCATION 中的图像和视频。

Q: 支持哪些照片格式？ A: 支持 RAW 格式、JPG、PNG、HEIC 等常见格式。

Q: 如何添加更多用户？ A: 管理员可以通过网页界面添加和管理用户。

Q: 如何更新 Immich？ A: 更新 IMMICH_VERSION 环境变量并重新启动容器。

故障排除

容器无法启动
- 检查 Docker 和 Docker Compose 版本
- 查看日志：docker compose logs
无法访问 Web 界面
- 检查防火墙设置
- 确认端口 2283 已开放
上传失败
- 检查存储权限
- 确认磁盘空间充足

📊 版本与更新

版本策略

使用 IMMICH_VERSION=v2 获取最新稳定版
可以固定到特定版本如 v2.1.0

更新方法

 # 停止当前服务
 docker compose down
 
 # 拉取新版本
 docker compose pull
 
 # 启动更新后的服务
 docker compose up -d

📄 许可证

Immich 采用 GNU Affero General Public License v3.0 (AGPL-3.0) 许可证。

许可证要点：

自由使用、修改和分发
修改后的版本必须开源
网络服务必须提供源代码访问

完整许可证文本：LICENSE

🤝 贡献与社区

贡献方式

代码贡献: 提交 Pull Request
翻译贡献: 通过 Weblate 参与翻译
文档贡献: 改进文档
Bug 报告: 提交 Issue

社区支持

Discord: https://discord.immich.app
Reddit: https://www.reddit.com/r/immich/
GitHub Discussions: 项目仓库
YouTube: https://www.youtube.com/@immich-app

支持项目

购买官方商品：https://immich.store
支持开发：https://buy.immich.app

🔗 相关链接

官方资源

路线图: https://immich.app/roadmap
API 文档: https://api.immich.app/
我的 Immich: https://my.immich.app/
工具页面: https://my.immich.app/utilities

第三方工具

immich-go: Google Photos 迁移工具
Obtainium: 移动应用自动更新

公司信息

FUTO: https://futo.org/
购买 Immich: https://buy.immich.app
官方商品: https://immich.store

注意: 此文档基于 Immich v2 版本，具体功能可能随版本更新而变化。建议始终参考官方文档获取最新信息。