EPUB电子书管理平台HomeBranch

发表于 分类于 Waline： 阅读次数： 本文字数： 4k 阅读时长 ≈ 4 分钟
HomeBranch 是一款自托管的电子书管理平台，提供电子书上传、元数据自动抓取、跨设备阅读同步和 OPDS 目录支持。

简介

什么是 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 密钥：

1
2
3
4
5
# 生成 JWT_ACCESS_SECRET
openssl rand -base64 48

# 生成 JWT_REFRESH_SECRET  
openssl rand -base64 48

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

参数说明

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

变量名 说明 默认值 必需
DATABASE_HOST PostgreSQL 数据库主机 db 是
DATABASE_PORT PostgreSQL 数据库端口 5432 是
DATABASE_USERNAME 数据库用户名 homebranch 是
DATABASE_PASSWORD 数据库密码 changeme 是
DATABASE_NAME 数据库名称 homebranch 是
JWT_ACCESS_SECRET JWT 访问密钥（必须与 auth 服务相同） - 是
CORS_ORIGIN CORS 允许来源 http://localhost 是
UPLOADS_DIRECTORY 上传文件目录 /data/uploads 是
AUTH_SERVICE_URL 认证服务地址（OPDS 认证） http://auth:3000 是
GOOGLE_BOOKS_API_KEY Google Books API 密钥 - 否
OPEN_LIBRARY_ENABLED 启用 Open Library 元数据抓取 true 否
TZ 时区设置 UTC 否

docker-compose 部署

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
services:
  db:
    image: postgres:16
    container_name: homebranch-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: homebranch
      POSTGRES_PASSWORD: changeme         # 改为强密码
      POSTGRES_DB: homebranch
    volumes:
      - ./pgdata:/var/lib/postgresql/data
    
  auth-db:
    image: postgres:16
    container_name: homebranch-authdb
    restart: unless-stopped
    environment:
      POSTGRES_USER: auth
      POSTGRES_PASSWORD: changeme
      POSTGRES_DB: authentication
    volumes:
      - ./authdata:/var/lib/postgresql/data
    
  auth:
    image: ghcr.io/oghamark/authentication:latest
    container_name: homebranch-auth
    restart: unless-stopped
    depends_on:
      - auth-db
    environment:
      DATABASE_HOST: auth-db
      DATABASE_PORT: 5432
      DATABASE_USERNAME: auth
      DATABASE_PASSWORD: changeme         # 与 auth-db 密码一致
      JWT_ACCESS_SECRET: your-access-secret-here     # 使用生成的密钥
      JWT_REFRESH_SECRET: your-refresh-secret-here   # 使用生成的密钥
      CORS_ORIGIN: http://localhost
      PORT: 3000
      
  homebranch:
    image: ghcr.io/oghamark/homebranch:latest
    container_name: homebranch-api
    restart: unless-stopped   
    depends_on:
      - db
      - auth
    environment:
      DATABASE_HOST: db
      DATABASE_PORT: 5432
      DATABASE_USERNAME: homebranch
      DATABASE_PASSWORD: changeme         # 与 db 密码一致
      DATABASE_NAME: homebranch
      JWT_ACCESS_SECRET: your-access-secret-here     # 必须与 auth 相同
      CORS_ORIGIN: http://localhost
      UPLOADS_DIRECTORY: /data/uploads
    volumes:
      - ./uploads:/data/uploads
    restart: unless-stopped

  homebranch-web:
    image: ghcr.io/oghamark/homebranch-web:latest
    container_name: homebranch
    restart: unless-stopped   
    ports:
      - "8454:80"
    depends_on:
      - homebranch
      - auth
    environment:
      API_BACKEND: http://homebranch:3000
      AUTH_BACKEND: http://auth:3000

然后执行下面的命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 新建文件夹 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

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

参考文档

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

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

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