简介

什么是 HomeBranch ？

HomeBranch 是一款自托管的电子书管理平台，用于上传、整理、搜索和阅读你的电子书收藏。基于 TypeScript 开发，提供现代化的 Web 界面和丰富的电子书管理功能。方便你在不同设备上组织、搜索和阅读电子书。

主要特点

• 自动元数据抓取：支持 Open Library 和 Google Books 自动抓取电子书的元数据信息，包括作者、出版社、摘要、评分、ISBN、页数、系列信息等
• 跨设备同步：在不同设备上阅读时自动同步阅读进度
• OPDS 目录支持：提供 OPDS 1.2（Atom）和 OPDS 2.0（JSON）目录，与 Kobo、KOReader、Thorium 等电子阅读器无缝集成
• 智能搜索：支持全文搜索和高级筛选功能
• 书架管理：创建自定义的书架来组织电子书，支持多对多的书与书架关系
• 权限管理：完善的用户角色和权限系统，支持多用户访问
• 开源免费：基于 AGPL-3.0 协议开源，可完全私有化部署

应用场景

• 个人数字图书馆：将购买的电子书整理成个人的数字图书馆
• 家庭阅读共享：全家成员共享电子书资源，每个人有自己的阅读历史和偏好
• 学校/图书馆部署：为学校或小型图书馆提供电子书借阅管理系统
• 阅读器同步：配合电子阅读器，随时随地同步阅读进度

适合所有希望通过 Docker 方式建立私有电子书管理平台的用户。

安装

在群晖上以 Docker 方式安装。

本文写作时， latest 版本对应为  1.2.0；

根据官方文档，HomeBranch 由三个核心服务组成：

1. Authentication：用户认证和 JWT 会话管理
2. HomeBranch API：电子书管理、存储和同步
3. Web Frontend：React SPA + nginx 代理

官方推荐使用 Docker Compose 部署完整的三服务架构。

生成密钥

在部署前，需要生成两个 JWT 密钥：

# 生成 JWT_ACCESS_SECRETopenssl rand -base64 48# 生成 JWT_REFRESH_SECRET  openssl rand -base64 48

【重要】：JWT_ACCESS_SECRET 必须在 auth 和 homebranch 服务中使用相同的值

参数说明

Homebranch 支持多个环境变量用于配置，以下是常用配置：

docker-compose 部署

将下面的内容保存为 docker-compose.yml 文件

【重要】：替换所有 changeme 占位符

services:db:image: postgres:16container_name: homebranch-dbrestart: unless-stoppedenvironment:POSTGRES_USER: homebranchPOSTGRES_PASSWORD: changeme# 改为强密码POSTGRES_DB: homebranchvolumes:- ./pgdata:/var/lib/postgresql/data  auth-db:image: postgres:16container_name: homebranch-authdbrestart: unless-stoppedenvironment:POSTGRES_USER: authPOSTGRES_PASSWORD: changemePOSTGRES_DB: authenticationvolumes:- ./authdata:/var/lib/postgresql/data  auth:image: ghcr.io/oghamark/authentication:latestcontainer_name: homebranch-authrestart: unless-stoppeddepends_on:- auth-dbenvironment:DATABASE_HOST: auth-dbDATABASE_PORT: 5432DATABASE_USERNAME: authDATABASE_PASSWORD: changeme# 与 auth-db 密码一致JWT_ACCESS_SECRET: your-access-secret-here# 使用生成的密钥JWT_REFRESH_SECRET: your-refresh-secret-here# 使用生成的密钥CORS_ORIGIN: http://localhostPORT:3000  homebranch:image: ghcr.io/oghamark/homebranch:latestcontainer_name: homebranch-apirestart: unless-stoppeddepends_on:- db- authenvironment:DATABASE_HOST: dbDATABASE_PORT: 5432DATABASE_USERNAME: homebranchDATABASE_PASSWORD: changeme# 与 db 密码一致DATABASE_NAME: homebranchJWT_ACCESS_SECRET: your-access-secret-here# 必须与 auth 相同CORS_ORIGIN: http://localhostUPLOADS_DIRECTORY: /data/uploadsvolumes:- ./uploads:/data/uploads  homebranch-web:image: ghcr.io/oghamark/homebranch-web:latestcontainer_name: homebranchrestart: unless-stoppedports:- "8454:80"depends_on:- homebranch- authenvironment:API_BACKEND: http://homebranch:3000AUTH_BACKEND: http://auth:3000

然后执行下面的命令

# 新建文件夹 homebranch 和 子目录mkdir -p /volume1/docker/homebranch/{authdata,data,pgdata,uploads}# 进入 homebranch 目录cd /volume1/docker/homebranch# 将 docker-compose.yml 放入当前目录# 编辑 docker-compose.yml，替换所有 changeme 占位符#     - 两个数据库密码#     - JWT_ACCESS_SECRET（与 auth 服务相同）#     - JWT_REFRESH_SECRET# 一键启动docker-compose up -d

运行

首次启动时，Auth 服务和 API 会自动运行数据库迁移，等待一会儿完成初始化

在浏览器中输入 http://群晖IP:8454 即可访问 Homebranch

首次访问需要创建管理员账户，按界面提示完成初始化设置

按提示注册第一个用户（自动成为管理员）

登录成功后的主界面

点 Add Book 可以添加目录和文件

只支持 .epub 文件

上传后的效果

选中一本，开始网页阅读

可以根据需要设置字体等

看文档刚添加了 OPDS 协议支持，只要你的阅读器支持，就可以使用以下 URL 访问：

• OPDS 1.2: http://群晖IP:8454/opds/v1/catalog
• OPDS 2.0: http://群晖IP:8454/opds/v2/catalog

但老苏试了下，并没有成功，不知道是设置不正确，还是当前的镜像还没更新到最新的功能

参考文档

1. Oghamark/homebranch: A self-hosted e-book management platform地址：https://github.com/Oghamark/homebranch

2. Self-Hosted E-Book Library | HomeBranch地址：https://homebranch.app/

3. Homebranch | E-Book Management Platform : r/selfhosted地址：https://www.reddit.com/r/selfhosted/comments/1rm6d0c/homebranch_ebook_management_platform/?show=original

@所有人：写文不易，如果你都看到了这里，请点个赞和在看，分享给更多的朋友；为确保你能收到每一篇文章，请主页右上角设置星标。