自托管网页EPUB阅读器Codexa

简介

什么是 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 是一个轻量级的自托管 EPUB 阅读解决方案，适合追求简洁和可控的个人用户。

安装

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

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

docker cli 安装

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

bash 复制代码

# 新建文件夹 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 字符的随机字符串。更改它会使所有现有会话失效。生成方法：
bash 复制代码
node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"
# 或
openssl rand -hex 64

docker-compose 安装

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

yaml 复制代码

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"

执行以下命令启动：

bash 复制代码

# 新建文件夹 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 ，有两种同步选项：

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

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

注意事项

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