自托管网页EPUB阅读器Codexa

发表于 分类于 Waline： 阅读次数： 本文字数： 3.4k 阅读时长 ≈ 3 分钟
Codexa 是一个自托管的 EPUB 网页阅读器，支持多用户、OPDS 浏览、KOReader 同步和内置词典查词。

简介

什么是 Codexa ？

Codexa 是一个自托管的 EPUB 网页阅读器，支持多用户、OPDS 浏览、KOReader 同步和内置词典查词。它可以帮助用户在浏览器中阅读 EPUB 电子书，同时支持书架管理、阅读进度同步和离线查词功能。

主要特点

  • EPUB 阅读器：基于 epub.js 构建，分页布局，支持自定义字体、主题和状态栏
  • 多用户支持：基于 JWT 的身份验证，每个用户有独立的书架和阅读进度
  • 书架管理：将书籍整理到自定义书架
  • 阅读进度：自动保存阅读进度，跨设备同步
  • KOReader 同步：内置 KOSync 兼容服务器，也可连接到外部 KOSync 服务器
  • OPDS 浏览：浏览并下载任意 OPDS 目录馆藏的书籍
  • OPDS 书架同步：批量下载整个 OPDS 文件夹到书架
  • 词典查词：支持本地 StarDict 词典文件（.ifo/.idx/.dict）
  • PWA 支持：可安装在桌面和移动设备上
  • 多语言界面：支持英语、斯洛文尼亚语、德语、西班牙语、法语、意大利语、葡萄牙语
  • 深色/浅色/墨水屏主题

应用场景

  • 电子书爱好者：需要一个简洁的网页端 EPUB 阅读器
  • 多设备阅读：在电脑、平板、手机上同步阅读进度
  • KOReader 用户：希望将 KOReader 阅读进度与网页阅读器同步
  • OPDS 用户：从公共图书馆或自己的 OPDS 服务器下载书籍

Codexa图书馆界面

Codexa阅读器界面

Codexa 是一个轻量级的自托管 EPUB 阅读解决方案，适合追求简洁和可控的个人用户。

安装

由于镜像托管在 ghcr.io，群晖 Docker 套件无法直接搜索，需要通过命令行拉取镜像并安装

国内拉取可能较慢，可以考虑配置 Docker 代理或使用镜像加速器

docker cli 安装

如果你熟悉命令行，可能用 docker cli 更快捷

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
# 新建文件夹 codexa 和 子目录
mkdir -p /volume1/docker/codexa/data

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

# 运行容器   
docker run -d \
  --name=codexa \
  --restart=unless-stopped \
  -p 3866:3000 \
  -v $(pwd)/data:/data \
  -e JWT_SECRET=replace_with_a_long_random_secret_string_at_least_64_chars
 \
  ghcr.io/thehijacker/codexa:latest

# 示例
docker run -d \
  --name=codexa \
  --restart=unless-stopped \
  -p 3866:3000 \
  -v $(pwd)/data:/data \
  -e JWT_SECRET=78aa0c748aa5acbaa3ee07a0b344f6c7528894e664f1b22b0c315b484f873ef0fc6fed5e9a7544709cee9c9502e6247c70c2cdffe3dbdd7f9ee0a7e355c99e44
 \
  ghcr.io/thehijacker/codexa:latest

环境变量的简单说明

可变 值 说明
JWT_SECRET 至少 64位的随机字符串 可以用 openssl rand -hex 64 生成
PORT 3000 容器内的默认端口
DATA_DIR /data 保存数据、数据库等
CORS_ORIGIN 可选，限制跨域来源

说明：JWT_SECRET 是必需的，必须是一个至少 64 字符的随机字符串。更改它会使所有现有会话失效。生成方法：

1
2
3
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
# 或
openssl rand -hex 64

docker-compose 安装

也可以用 docker-compose 安装，将下面的内容保存为 docker-compose.yml 文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
version: '3.8'

services:
  codexa:
    image: ghcr.io/thehijacker/codexa:latest
    container_name: codexa
    restart: unless-stopped
    ports:
      - "3866:3000"
    volumes:
      - ./data:/data
    environment:
      # REQUIRED — generate with:
      #   openssl rand -hex 64
      JWT_SECRET: "78aa0c748aa5acbaa3ee07a0b344f6c7528894e664f1b22b0c315b484f873ef0fc6fed5e9a7544709cee9c9502e6247c70c2cdffe3dbdd7f9ee0a7e355c99e44"

      # Optional — restrict to your domain when behind a reverse proxy
      # CORS_ORIGIN: "https://books.example.com"

      # Optional — override default port inside the container
      # PORT: "3000"

执行以下命令启动：

1
2
3
4
5
6
7
8
9
10
# 新建文件夹 codexa 和 子目录
mkdir -p /volume1/docker/codexa/data

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

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

# 一键启动
docker-compose up -d

运行

在浏览器中访问 http://<群晖IP>:3866 即可进入登录界面

如果默认显示不是英文，可以切换成英文，不然完全看不懂

需要先注册一个账号

登录成功后的主界面

现在可以上传 EPUB 书籍到书架

打开阅读

支持快捷键操作，可以参考官方文档：https://github.com/thehijacker/codexa#keyboard-shortcuts

OPDS 服务

进入Settings –> OPDS Servers，老苏用的是 calibre-web 的 opds 服务

如果有账号、密码也需要配置；

添加完成后

可以直接点 Open 打开

找到书籍后，可以直接添加到书架

添加完成后，可以在 All books 中找到

直接点开就可以在 Codexa 阅读了

KOReader 用户

如果你使用 KOReader ，有两种同步选项：

  1. 此 Codexa 服务器作为 KOSync 服务器——在 KOReader 中设置此服务器的 URL（例如：http://<群晖IP>:3866），并使用与此处相同的凭据登录。
  2. 外部 KOReader同步服务器 — 请在下方输入您现有的 KOSync 服务器的URL。阅读器在打开书籍时，会将您的阅读进度与该服务器进行同步，并在保存时将进度发送至两个服务器。

之前老苏介绍过 专为KOReader打造的同步服务KOmpanion，不知道是否可以作为外部的 KOReader同步服务器 ？

注意事项

  1. JWT_SECRET 必须修改：使用强随机字符串，不能使用默认值
  2. 数据持久化：确保 DATA_DIR 目录已正确挂载，否则重启后数据会丢失
  3. 首次注册：第一个注册的用户就是管理员，没有默认 admin 账户
  4. 词典文件：如需使用词典查词功能，需要在 dictionaries 目录放置 StarDict 格式的词典文件
  5. 字体文件：用户可以上传自定义字体到 fonts 目录

参考文档

thehijacker/codexa: A self-hosted EPUB web reader with multi-user support, OPDS browsing, KOReader sync, and a built-in dictionary lookup
地址：https://github.com/thehijacker/codexa

ghcr.io/thehijacker/codexa:latest - Docker Image
地址：https://github.com/thehijacker/codexa/pkgs/container/codexa