自托管EPUB阅读器Codexa部署教程：Docker搭建多用户同步与OPDS管理

简介

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

安装

镜像托管在 ghcr.io，群晖 Docker 套件无法直接搜索，需要通过命令行拉取并运行容器。

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

docker cli 安装

如果熟悉命令行，使用 docker cli 更加快捷。

# 新建文件夹 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 字符。使用强随机字符串，更改后所有现有会话将失效。生成方式：

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

在终端执行 openssl rand -hex 64 即可获得一组随机字符串。

docker-compose 安装

也可以使用 docker-compose，将以下内容保存为 docker-compose.yml 文件：

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"

执行以下命令启动：

# 新建文件夹 codexa 和子目录
mkdir -p /volume1/docker/codexa/data

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

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

# 一键启动
docker-compose up -d

运行

在浏览器中访问 http://<群晖IP>:3866 进入登录界面。若默认不是英文，建议先切换至英文以便操作。需要先注册一个账号，第一个注册的用户即为管理员。

登录成功后进入主界面，此时书架为空。可通过界面上传 EPUB 书籍，上传后的书籍会显示在 All books 列表中，点击即可打开阅读。

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

OPDS 服务

进入 Settings → OPDS Servers，添加自己的 OPDS 服务（如 calibre-web 提供的 opds 地址）。如果需要账号密码，请一并填写。

添加完成后，点击 Open 浏览服务器上的书籍，找到想要的书籍后可直接添加到书架。成功添加的书籍会出现在 All books 中，点开即可在 Codexa 内阅读。

KOReader 用户

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

1. 将本 Codexa 服务器作为 KOSync 服务器：在 KOReader 中填入本服务器 URL（例如 http://<群晖IP>:3866），并使用与 Codexa 相同的凭据登录。
2. 使用外部 KOReader 同步服务器：输入已有 KOSync 服务器的地址。阅读器打开书籍时会与外部服务器对比进度，保存时会同时将进度发送至两个服务器。

之前介绍过的 KOmpanion 可能可以作为外部同步服务器，不妨一试。

注意事项

1. JWT_SECRET 必须修改：使用强随机字符串，切勿使用默认值。
2. 数据持久化：确保 DATA_DIR 目录已正确挂载，否则重启后数据丢失。
3. 首次注册：第一个注册的用户即为管理员，没有预设的 admin 账户。
4. 词典文件：如需使用词典查词功能，请将 StarDict 格式的词典文件放入 dictionaries 目录。
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