BookHaven：一个现代化的浏览器端EPUB阅读器

简介

什么是 BookHaven ？

BookHaven 是一个基于浏览器的 EPUB 阅读器，旨在帮助用户管理和阅读本地的 EPUB 格式电子书。它通过简洁、现代且响应式的界面，让用户能够在任何设备上轻松访问和阅读电子书。

项目特点

• 浏览器内阅读：直接在浏览器中阅读 EPUB 电子书，无需额外软件。
• 本地文件支持：支持从本地文件系统读取和管理 EPUB 文件。
• 元数据编辑：非破坏性地编辑电子书元数据，如标题、作者、封面等。
• 图书馆管理：自动或手动扫描本地电子书库，统一管理所有书籍。
• 搜索与排序：支持强大的搜索功能，并按作者、系列等排序书籍。
• 多设备支持：响应式设计，适配桌面、平板和手机等多种设备。
• 身份验证：支持 CloudFlare Access 和 OIDC 身份验证，确保数据安全。

应用场合

• 希望在线阅读和管理本地 EPUB 电子书的用户。
• 需要非破坏性编辑电子书元数据的用户。
• 希望在多设备上无缝阅读电子书的用户。
• 需要安全认证功能的小型团队或个人用户。

通过 BookHaven，用户可以轻松管理本地 EPUB 电子书，并在任何设备上阅读和下载电子书，具有时尚、现代和响应迅速的界面。

安装

在群晖上以 Docker 方式安装。

在注册表中搜索 pingvin-share ，选择第一个 hrbingr/bookhaven，版本选择 latest。

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

env.txt

env.txt 基于官方的 https://github.com/HrBingR/BookHaven/blob/master/.env.example 文件

###################################################
## APPLICATION CONFIGURATION:                    ##
###################################################

# BASE DIRECTORY (REQUIRED)
# The directory where your ebooks are mounted inside the container.
# Example: /ebooks
BASE_DIRECTORY=/ebooks

# BASE URL (REQUIRED)
# The URL where the application will be accessible. Include protocol, hostname, and optional port.
# Format: https://books.example.com or http://localhost:5000
BASE_URL=

# SECRET KEY (REQUIRED)
# Used for encrypting JWT tokens.
# Generate a new key using openssl rand -hex 32
SECRET_KEY=

# ADMIN EMAIL (REQUIRED ON FIRST STARTUP)
# Used to set the initial admin user's email address on first startup.
# Can be removed/unset after initialization
ADMIN_EMAIL=

# ADMIN PASS (REQUIRED ON FIRST STARTUP)
# Used to set the initial admin user's password on first startup.
# Can be removed/unset after initialization
ADMIN_PASS=

# ADMIN RESET (OPTIONAL)
# Used to set the admin user's password to ADMIN_PASS, and to remove configured MFA
# Should be used as a last resort if admin credentials or MFA method have been lost
ADMIN_RESET=false

# UI BASE COLOR (OPTIONAL)
# Used to set the base color of the UI.
# Valid options: green (default), blue, red, yellow, white, black, pink, purple, orange, cyan
UI_BASE_COLOR=green

# WRITE TO EPUB (OPTIONAL)
# If this is set any metadata changes are written to the ePub file itself as well as the database
# WARNING: Changes are one-way and are irreversible
# NOTE: If your ePub file does not already have a cover image, BookHaven will not be able to add a new one.
# It can only replace an existing cover image in an ePub file at this time.
WRITE_TO_EPUB=false

# CF ACCESS AUTH (OPTIONAL)
# Used to set whether or not you're authenticating through a Cloudflare Access application
# Default: False
CF_ACCESS_AUTH=false

# OIDC ENABLED (OPTIONAL)
# Used to enable OIDC support
# Default: False
OIDC_ENABLED=false

# OIDC CLIENT ID (REQUIRED IF OIDC_ENABLED)
# Your client-id provided to you by your OIDC provider
# OIDC_CLIENT_ID=

# OIDC_CLIENT_SECRET (REQUIRED IF OIDC_ENABLED)
# Your client secret provided to you by your OIDC provider
# OIDC_CLIENT_SECRET=

# OIDC PROVIDER (REQUIRED IF OIDC_ENABLED)
# Your OIDC provider
# e.g. keycloak
# OIDC_PROVIDER=

# OIDC METADATA ENDPOINT (REQUIRED IF OIDC_ENABLED)
# The openid-configuration metadata endpoint for your provider
# e.g. https://accounts.google.com/.well-known/openid-configuration
# OIDC_METADATA_ENDPOINT=

# OIDC AUTO REGISTER USER (OPTIONAL)
# Automatically register new users that log in using OIDC
# Default: false
OIDC_AUTO_REGISTER_USER=false

# OIDC AUTO LINK USER (OPTIONAL)
# Automatically links existing users to OIDC when logging in via OIDC for the first time
# Note: If disabled users can still manually link their accounts to OIDC from their Account Settings
# Default: false
OIDC_AUTO_LINK_USER=false

# LOG LEVEL (OPTIONAL)
# The logging level for the application. Defaults to 'INFO'.
# Options: DEBUG, INFO, WARNING, ERROR, CRITICAL
LOG_LEVEL=INFO

# APP PORT (REQUIRED FOR DOCKER COMPOSE)
# The port the app will listen on within the container. This is mapped via Docker Compose.
# Default: 5000
APP_PORT=5000

# ENABLE HTTPS (OPTIONAL)
# Whether or not your app is HTTPS enabled internally.
# Can be disabled if you reverse proxy does SSL.
# Default: false
ENABLE_HTTPS=false

# SSL CERT FILE (REQUIRED IF ENABLE_HTTPS=true)
# Path relative to /ssl/ where your certificate is mounted
# For example, if your certificate is mounted to /ssl/cert.crt, then SSL_CERT_FILE=cert.crt
# SSL_CERT_FILE=cert.crt

# SSL KEY FILE (REQUIRED IF ENABLE_HTTPS=true)
# Path relative to /ssl/ where your certificate is mounted
# For example, if your certificate is mounted to /ssl/key.key, then SSL_CERT_FILE=key.key
# SSL_KEY_FILE=key.key

# RATE LIMITER ENABLED (OPTIONAL)
# Whether or not to enable the IP-based rate limiter
# Default: True
RATE_LIMITER_ENABLED=true

# SCHEDULER ENABLED (OPTIONAL)
# Whether or not to enable the periodic scanning of your library.
# Manual library scanning is still available whether disabled or enabled.
# Default: True
SCHEDULER_ENABLED=true

# PERIODIC SCAN INTERVAL (OPTIONAL)
# How frequently the scheduler will scan your library, in minutes
# Default: 10
PERIODIC_SCAN_INTERVAL=10

###################################################
## DATABASE CONFIGURATION FOR APPLICATION:       ##
###################################################

# DATABASE TYPE (REQUIRED)
# Specify the type of database to use for the application.
# Supported options: mysql, postgres, sqlite (not recommended for production)
DB_TYPE=mysql

# DATABASE HOST (REQUIRED)
# The hostname or IP address of the database.
# Defaults to 'mysql' when using the provided MySQL container.
DB_HOST=mysql

# DATABASE PORT (REQUIRED FOR DOCKER COMPOSE OR CUSTOM CONNECTIONS)
# The port used to connect to the database. Required for MySQL and PostgreSQL.
# Default: 3306 for MySQL, 5432 for PostgreSQL, or leave unset for SQLite.
DB_PORT=3306

# DATABASE NAME (REQUIRED)
# Name of the database used to store EPUB metadata.
# Default: epub_library
DB_NAME=epub_library

# DATABASE USER (REQUIRED)
# The username for the database connection.
DB_USER=epub_user

# DATABASE PASSWORD (REQUIRED)
# The password for the database connection.
# Use a strong and secure password.
DB_PASSWORD=secure_password_here

###################################################
## REDIS CONFIGURATION FOR APPLICATION:          ##
###################################################

# REDIS HOST (REQUIRED)
# Host running Redis
# Default: localhost
REDIS_HOST=redis

# REDIS PORT (REQUIRED)
# Redis port
# Default: 6379
REDIS_PORT=6379

# REDIS PASSWORD (REQUIRED if Redis auth is enabled on your REDIS instance)
# Default: N/A, DOCKER COMPOSE REDIS does not use auth
# REDIS_PASSWORD=password

# REDIS LIMITER DATABASE
# Redis database for the rate limiter to use to keep track of IPs/Requests
# Default: 0
REDIS_LIMITER_DB=0

# REDIS SCHEDULER DATABASE
# Redis database for the periodic library scanner to use
# Default: 5
REDIS_SCHEDULER_DB=5

###################################################
## MYSQL CONTAINER CONFIGURATION:                ##
###################################################

# MYSQL ROOT PASSWORD (REQUIRED FOR DOCKER COMPOSE MYSQL CONTAINER)
# Set the root password for MySQL if using the MySQL container provided in the Docker Compose file.
# Use a strong and secure password.
MYSQL_ROOT_PASSWORD=secure_mysql_root_password

# MYSQL DATABASE (REQUIRED FOR DOCKER COMPOSE MYSQL CONTAINER)
# Specifies the default database created in the MySQL container.
MYSQL_DATABASE=epub_library

# (REQUIRED FOR DOCKER COMPOSE MYSQL CONTAINER)
MYSQL_USER=epub_user

# (REQUIRED FOR DOCKER COMPOSE MYSQL CONTAINER)
MYSQL_PASSWORD=secure_password_here

源文件中对每个变量都有详细的解释，老苏翻译成中文并放入了表格，方便大家查阅

可变	默认值	说明
BASE_DIRECTORY	/ebooks	电子书在容器内挂载的目录。
BASE_URL		应用程序可访问的 URL。
SECRET_KEY		用于加密 JWT 令牌。
ADMIN_EMAIL		首次启动时设置的管理员用户邮箱地址。
ADMIN_PASS		首次启动时设置的管理员用户密码。
ADMIN_RESET	false	将管理员用户的密码重置为 ADMIN_PASS。
UI_BASE_COLOR	green	UI 的基础颜色。
WRITE_TO_EPUB	false	元数据更改是否写入 EPUB 文件。
CF_ACCESS_AUTH	false	是否通过 Cloudflare Access 进行身份验证。
OIDC_ENABLED	false	是否启用 OIDC 支持。
OIDC_CLIENT_ID		OIDC 提供商提供的客户端 ID。
OIDC_CLIENT_SECRET		OIDC 提供商提供的客户端密钥。
OIDC_PROVIDER		OIDC 提供商。
OIDC_METADATA_ENDPOINT		OIDC 元数据端点。
OIDC_AUTO_REGISTER_USER	false	是否自动注册使用 OIDC 登录的新用户。
OIDC_AUTO_LINK_USER	false	是否自动将现有用户链接到 OIDC。
LOG_LEVEL	INFO	应用程序的日志级别。
APP_PORT	5000	应用程序在容器内监听的端口。
ENABLE_HTTPS	false	应用程序是否在内部启用 HTTPS。
SSL_CERT_FILE		SSL 证书文件路径。
SSL_KEY_FILE		SSL 密钥文件路径。
RATE_LIMITER_ENABLED	true	是否启用基于 IP 的速率限制器。
SCHEDULER_ENABLED	true	是否启用定期扫描库。
PERIODIC_SCAN_INTERVAL	10	调度器扫描库的频率（分钟）。
DB_TYPE	mysql	应用程序使用的数据库类型。
DB_HOST	mysql	数据库的主机名或 IP 地址。
DB_PORT	3306	连接数据库的端口。
DB_NAME	epub_library	存储 EPUB 元数据的数据库名称。
DB_USER	epub_user	数据库连接的用户名。
DB_PASSWORD	secure_password_here	数据库连接的密码。
REDIS_HOST	redis	运行 Redis 的主机。
REDIS_PORT	6379	Redis 端口。
REDIS_LIMITER_DB	0	用于速率限制器的 Redis 数据库。
REDIS_SCHEDULER_DB	5	用于定期库扫描器的 Redis 数据库。
MYSQL_ROOT_PASSWORD	secure_mysql_root_password	MySQL 的根密码。
MYSQL_DATABASE	epub_library	MySQL 容器中创建的默认数据库。
MYSQL_USER	epub_user	MySQL 用户名。
MYSQL_PASSWORD	secure_password_here	MySQL 用户密码。

这里把几个必须修改或者设置的值，简单说明一下

• BASE_URL：老苏设为了 http://192.168.0.197:5533，其中 192.168.0.197 为群晖主机的 IP ，5533 是设置的 BookHaven 的本地端口；
• SECRET_KEY：可以用命令 openssl rand -hex 32 来生成；
• ADMIN_EMAIL：用于登录的账号；
• ADMIN_PASS：用于登录的密码；

【重要】：密码不能少于 8 位，要有至少一个大写字母等，总之要复杂一点，否则会导致容器不断重启

bookhaven-web | time=2025-02-22T07:00:13 level=ERROR msg="Failed to initialize admin user: Password must be at least 8 characters long."

其他保持默认就可以了

docker-compose.yml

docker-compose.yml 在官方 https://github.com/HrBingR/BookHaven/blob/master/compose.yml.example 做了必要的调整

下面是一个完整的示例，如果 5533 端口存在冲突，可以修改，但别忘记了需要同时修改 env.txt 中的 BASE_URL

services:
  # The MySQL and Redis containers are optional if you already have your own DB in place.
  mysql:
    image: mysql:8.0
    container_name: bookhaven-mysql
    env_file:
      - env.txt
    volumes:
      - ./mysql-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin" ,"ping", "-h", "localhost"]
      timeout: 20s
      retries: 10

  redis:
    image: redis:7
    container_name: bookhaven-redis
    volumes:
      - ./redis-data:/data

  bookhaven:
    image: hrbingr/bookhaven:latest
    container_name: bookhaven-web
    env_file:
      - env.txt
    ports:
      - 5533:${APP_PORT}
    volumes:
      - ./epub-data:${BASE_DIRECTORY}
    depends_on:
      mysql:
        condition: service_healthy

然后执行下面的命令

# 新建文件夹 bookhaven 和 子目录
mkdir -p /volume1/docker/bookhaven/{epub-data,mysql-data,redis-data}

# 进入 bookhaven 目录
cd /volume1/docker/bookhaven

# 将 env.txt 和 docker-compose.yml 放入当前目录

# 一键启动
docker-compose --env-file env.txt up -d

运行

在浏览器中输入 http://群晖IP:5533 就能看到登录界面

登录成功后

网上随便下了几本书，上传到 epub-data 目录

点击右上角的 Scan Library

扫描完成后，需要刷新一下页面

现在加入的图书就都出来了

随便点开一本

使用非常简单

手机上看看

阅读的效果感觉不是太好，左右留空太多了

参考文档

HrBingR/BookHaven: A repo for a browser-based epub reader
地址：https://github.com/HrBingR/BookHaven