HomeGallery

Home-Gallery.org 是一款自托管的开源网页相册，用于浏览个人照片和视频，支持标签功能、移动设备友好以及基于 AI 的图片和人脸识别。您可以试用 演示相册，或者欣赏一下 美食图片！

注意： 本软件为个人业余项目，不提供任何担保。如有疑问，请前往 gitter.im 或 Discord 咨询。

您喜欢 HomeGallery 吗？它是否解决了您的媒体管理问题？如果您愿意帮忙，请阅读 CONTRIBUTING 指南，并通过定期资助我的 patreon.com/xemle 或一次性捐赠至我的 paypal.me/xemle 账户来支持该项目。提前感谢您的支持。

MIT 许可证

链接

• 首页
• 演示相册
• 最新二进制文件适用于 Linux、Mac 和 Windows，以及 Docker 镜像
• 文档
• 更新日志

动机

• 我所有的私人图片和视频都存储在家中的 NAS 设备上，相册应该尽可能靠近数据源。
• 云服务无法满足我对隐私的需求。
• 现有的相册软件在移动设备上的用户体验普遍较差。
• 相册应帮助用户从庞大的媒体库中浏览并发现那些被遗忘的记忆。

目标用户

• 熟悉计算机操作、能够独立解决问题并愿意付出额外努力的用户。
• 在不使用云服务的情况下，直接服务于本地数据。
• 仅限单个用户使用，所有文件均在此环境中提供。
• 可以通过手机查看自己的照片和视频。
• 支持从多个媒体源目录（如硬盘、相机文件、手机文件等）提供图片。

快速入门

要使用 HomeGallery，您需要执行以下步骤：

• 下载 相册软件的预编译二进制文件或 Docker 镜像。
• 使用 ~/Pictures 等媒体源初始化配置。
• 在 localhost:3000 上启动服务器。

curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-linux-x64 -o gallery
chmod 755 gallery
./gallery init --source ~/Pictures
./gallery run server

然后在浏览器中打开 localhost:3000。运行 ./gallery -h 可获取更多 CLI 帮助信息。

更多二进制文件请访问 dl.home-gallery.org/dist。例如，最新版本的 Linux、Mac 和 Windows 版本。

配置文件 gallery.config.yml 可在当前目录下找到，以便进行精细调整。更多信息请参阅文档中的 安装部分。

使用 Docker 的快速入门

mkdir -p data
alias gallery="docker run -ti --rm \
  -v $(pwd)/data:/data \
  -v $HOME/Pictures:/data/Pictures \
  -u $(id -u):$(id -g) \
  -p 3000:3000 xemle/home-gallery"
gallery init --source /data/Pictures
gallery run server

然后在浏览器中打开 localhost:3000。运行 gallery -h 可获取更多 CLI 帮助信息。

相册配置文件位于 ./data/config/gallery.config.yml 中，可供进一步调整。

想使用 Docker Compose 吗？请参阅文档中的 安装部分 获取更多信息。

文档

有关通用文档，请访问 home-gallery.org/docs。

• 安装指南
• CLI 帮助
• 配置说明
• 常见问题解答
• 架构说明

特性

• 通过虚拟滚动实现无限照片流。
• 视频转码功能。
• 图片反向搜索（相似图片搜索）。如果您有一张日落照片，可以轻松在您的档案中找到其他日落照片，而无需手动打标签。
• 人脸识别与相似人脸搜索。
• 强大的查询语言，支持“与”、“或”、“非”等逻辑运算符。
• 地理位置反向查询。
• 通过 PWA 支持简单的移动应用体验。
• 标签功能，支持单选和多选。
• 支持只读和离线媒体源。一旦生成了预览文件并提取了元数据，原始数据源便不再被触碰，因此离线磁盘只需提取一次，后续运行时仍可保持离线状态。
• 媒体内容识别功能。完全相同的文件（字节级一致）只会被处理一次。文件重命名后无需重新计算预览等信息。
• 快速检测文件变化，包括新增、删除、重命名或移动。
• 可导出静态网页相册，例如 演示相册。
• 元数据可导出为 XMP 辅助文件。
• 可将照片和视频流式传输到支持 Chromecast 的电视设备。
• 支持在树莓派等 SoC 设备上运行。

限制

整个“数据库”会加载到浏览器中。我目前有 10 万条媒体记录，未压缩的 JSON 文件约为 100 MB，压缩后约为 12 MB。在现代移动设备上性能表现良好。有用户反馈称成功部署了超过 40 万条媒体记录的数据集。欢迎提供更多反馈。

二进制下载

HomeGallery 提供适用于 Linux、MacOS 和 Windows 的预编译二进制文件。更多下载选项请访问 这里。

使用方法请参阅 安装部分。

外部服务与隐私

HomeGallery 的目标是尽可能减少对外部公共服务的依赖，以保护敏感的私人图像数据。它尽量使用可以在本地部署的服务。然而，这种设置需要一定的技术知识和维护能力。以下是所调用的服务：

对于地理反向查询（将地理坐标转换为地址），HomeGallery 会向 OpenStreetMap 提供的 Nominatim 服务 发送请求。仅传输地理坐标信息。

对于反向图像搜索、物体检测和人脸识别，HomeGallery 使用其在 api.home-gallery.org 上的公共 API。该公共 API 支持低功耗设备，例如 Raspberry Pi 等单板计算机，并且默认会将所有预览图像发送到此公共 API。系统不会保存任何图像或隐私数据。

该 API 也可以配置并在本地运行，或者作为 Docker 容器部署。有关使用方法，请参阅安装部分。

自定义环境

HomeGallery 运行在 JavaScript 运行时 Node.js 上，该运行时支持多种平台，包括 Linux（也适用于 Raspberry Pi）、Mac 和 Windows。

在大多数情况下，以下自定义环境即可满足需求：

• Node.js 版本 20 LTS（或 18 LTS）
• Perl（Linux）

设置步骤

# 克隆或从 GitHub 下载仓库
git clone https://github.com/xemle/home-gallery.git
cd home-gallery
# 安装所需依赖包
npm install
# 构建所需模块
npm run build

在某些特殊情况下，您可能还需要一些必要的构建工具来编译库绑定。

• make
• g++
• python

开发指南

构建

HomeGallery 使用 npm 工作区管理多个包。常用的 npm 脚本包括 clean、build 和 test。

如果只想运行部分包，可以使用 pnpm 的过滤功能，例如仅构建 export-static 和 database 模块：

npx pnpm -r --filter './*/{export-static,database}' build

单元测试

通过 pnpm 运行特定包的单元测试：

npx pnpm -r --filter './*/{query,events}' test

端到端测试

运行特定的端到端测试（使用 Gauge）：

git clone https://github.com/xemle/home-gallery-e2e-data.git data
npm run test:e2e -- --tags dev

home-gallery-e2e-data 包含使用 Git LFS 的测试文件。

端到端测试的输出数据存储在 /tmp/gallery-e2e 目录中。最近一次测试会被创建为符号链接，指向 HomeGallery 工作目录下的 latest-e2e-test 目录。请检查每个测试目录中的 cli.log 和 e2e.log 文件（采用 ndjson 格式）。

打包

从某个特性分支创建本地二进制包：

node scripts/bundle.js --version=1.3 --snapshot=-feature-test --filter=linux-x64 --no-before --no-run

创建本地原生包，排除 sharp、ffmpeg 和 ffprobe 等 npm 包中的二进制文件。该包仅包含可在任何地方运行的 JavaScript 代码。不过，为了正常工作，仍需确保 PATH 环境变量中包含 vipsthumbnail、ffmpeg 和 ffprobe 等外部二进制文件。

node scripts/bundle.js --version=1.3 --snapshot=-feature-test --filter=linux-native --no-before --no-run

开发环境重置

若遇到非常奇怪的错误行为，可尝试重置当前开发状态并重新开始：

rm -rf package-lock.json node_modules e2e/node_modules packages/*/node_modules
npm install && npm run clean && npm run build

HomeGallery 快速上手指南

HomeGallery 是一款自托管的开源网络相册，支持标签管理、移动端适配以及 AI 驱动的图像和人脸发现功能。它专为隐私敏感用户设计，可直接浏览本地 NAS 或硬盘中的照片和视频。

环境准备

系统要求

• 操作系统：Linux (含 Raspberry Pi)、macOS 或 Windows
• 硬件建议：适用于低功耗设备（如树莓派），也可运行在普通服务器上
• 存储：需预留空间存放生成的预览图和元数据数据库

前置依赖

若选择源码编译或自定义环境，需安装以下依赖：

• Node.js: 版本 20 LTS (或 18 LTS)
• Perl: Linux 系统通常需要
• 构建工具 (仅源码编译需要): make, g++, python

提示：大多数用户推荐直接使用预编译二进制文件或 Docker 镜像，无需手动配置 Node.js 环境。

安装步骤

您可以选择以下两种方式之一进行安装：

方式一：使用预编译二进制文件 (推荐 Linux/Mac/Windows)

1. 下载程序

   curl -sL https://dl.home-gallery.org/dist/latest/home-gallery-latest-linux-x64 -o gallery
   

   (注：Mac 用户请将链接后缀改为 darwin-x64，Windows 用户下载 .exe 文件)

2. 赋予执行权限

   chmod 755 gallery
   

3. 初始化配置 指定您的图片源目录（例如 ~/Pictures）：

   ./gallery init --source ~/Pictures
   

4. 启动服务

   ./gallery run server
   

方式二：使用 Docker (推荐容器化部署)

1. 创建数据目录并设置别名

   mkdir -p data
   alias gallery="docker run -ti --rm \
     -v $(pwd)/data:/data \
     -v $HOME/Pictures:/data/Pictures \
     -u $(id -u):$(id -g) \
     -p 3000:3000 xemle/home-gallery"
   

   请确保 $HOME/Pictures 替换为您实际的媒体文件路径。

2. 初始化配置

   gallery init --source /data/Pictures
   

3. 启动服务

   gallery run server
   

基本使用

1. 访问相册 启动成功后，在浏览器中打开： http://localhost:3000

2. 核心功能体验

   • 浏览：支持无限滚动加载照片流。
   • 搜索：在搜索框输入自然语言查询（支持 and, or, not），例如 sunset and beach。
   • 以图搜图：点击任意图片，可查看相似图片（基于 AI 内容识别）。
   • 人脸发现：自动检测人脸并支持按人脸聚类搜索。
   • 移动端：在手机浏览器访问同一地址，即可获得类似原生 App 的体验 (PWA)。

3. 高级配置 如需调整端口、添加多个媒体源或配置 AI 服务，可编辑当前目录下的配置文件：

   • 二进制安装：gallery.config.yml
   • Docker 安装：./data/config/gallery.config.yml

   查看命令行帮助：

   ./gallery -h
   # 或 Docker 模式下
   gallery -h