EPUB电子书管理平台HomeBranch

HomeBranch 是一款自托管的电子书管理平台，提供电子书上传、元数据自动抓取、跨设备阅读同步和 OPDS 目录支持。

杨浦老苏

764人浏览 · 2026-03-10 14:22:42

杨浦老苏 · 2026-03-10 14:22:42 发布

在这里插入图片描述

简介

什么是 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 由三个核心服务组成：

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

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

生成密钥

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

# 生成 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 占位符

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

然后执行下面的命令

# 新建文件夹 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