环境：群晖DSM 7.x，Container Manager，镜像lscr.io/linuxserver/calibre-web:latest，端口8084 配套：Dozzle（查看容器日志）

一、用途介绍

Calibre-Web，Calibre电子书库网页前端，支持：

  • 电子书书库管理（元数据、封面、标签分类）
  • 网页上传EPUB/PDF/MOBI等电子书
  • 在线网页阅读EPUB、电子书下载
  • 多用户管理，适合NAS自建电子书库

⚠️重点提醒：内置网页阅读器仅对标准EPUB兼容性尚可；国内打包、排版复杂的中文EPUB容易网页阅读打不开，但下载文件不受影响。PDF不推荐网页在线阅读，建议下载本地打开。

二、前置准备（File Station手动创建目录）

路径：/volume2/docker/calibre-web/（你可改为volume1，注意全文统一） 新建2个子文件夹：

  1. config：存放Calibre-Web程序配置、账号数据库
  2. books：电子书库目录，存放metadata.db和所有电子书文件

重要：books目录内直接放书库，不要嵌套多一层文件夹； 权限：books文件夹权限设置Everyone【读取&写入】，勾选：应用到这个文件夹、子文件夹及文件，保存。

三、项目 Compose 配置

新建项目，粘贴下面yaml：

services:
  calibre-web:
    image: lscr.io/linuxserver/calibre-web:latest
    container_name: calibre-web
    environment:
      - PUID=1026
      - PGID=100
      - TZ=Asia/Shanghai
    volumes:
      - /volume2/docker/calibre-web/config:/config
      - /volume2/docker/calibre-web/books:/books
    ports:
      - "8080:8083"
    restart: unless-stopped

PUID/PGID：在群晖控制面板-用户与群组查看你的UID/GID； 端口：宿主机8084映射容器内部8083，确认8084端口未被其他容器占用。

四、首次初始化步骤

  1. 启动项目，等待镜像拉取完成、容器正常运行；
  2. 浏览器访问 http://群晖IP:8080；
  3. 首次进入向导：书库路径填写 /books；
  4. 创建管理员账号（admin）；
  5. 登录后台【行政】面板。

五、开启电子书上传功能（关键步骤）

  1. 行政页面 → 点击【编辑基本配置】
  2. 在【功能配置】板块：
    • ✅ 勾选：启用上传（请确保用户也拥有上传权限）
    • ❌ 取消勾选：在下载/转换/电子邮件时将元数据嵌入电子书文件（需要Calibre/Kepubify二进制文件）

      不取消会报红色警告：Kepubify二进制文件找不到，该功能用于Kobo阅读器格式转换，自用电子书库不需要。

  3. 点击【保存】
  4. 返回行政页面 → 用户列表 →【编辑用户（admin）】
  5. 用户权限里，勾选【上传】权限，保存；
  6. 刷新首页，顶部出现上传书籍按钮。

六、书籍阅读使用说明

进入书籍详情页，两个按钮：

  1. EPUB(xxMB)：直接下载电子书到电脑/手机，推荐使用（稳定性最高）
  2. Read in Browser - epub：网页在线阅读EPUB

    故障现象：电子书可以正常下载，但点击网页阅读无反应/空白 原因：网页阅读器是前端JS实现，对中文复杂排版EPUB兼容性差； 排查顺序：

    1. 无痕模式打开网页，排除浏览器广告拦截脚本插件干扰
    2. Dozzle打开calibre-web实时日志，点击阅读按钮查看后端是否报错
    3. 权限确认：books目录递归应用读写权限 ✅ 解决方案：优先下载EPUB，本地阅读器打开（Calibre、静读天下、Apple图书）

七、常见坑记录

  1. Kepubify二进制文件找不到红色提示 原因：镜像默认不带Calibre二进制转换工具； 处理：取消元数据嵌入勾选即可，不影响上传、下载、书库管理。如需Kepub转换，需要增加环境变量DOCKER_MODS=linuxserver/mods:universal-calibre，容器体积变大，启动变慢。

  2. metadata.db能加载显示书籍封面，但无法读取电子书实体文件 原因：权限只给了外层文件夹，没有递归应用到子文件夹；File Station权限设置务必勾选【应用到这个文件夹、子文件夹及文件】。

  3. 网页阅读打不开，但电子书下载正常 不属于部署错误，是内置网页阅读器兼容性限制，中文电子书很常见。

  4. 不要手动往books文件夹丢电子书文件 Calibre-Web不会自动扫描新增文件；新增电子书两种正确方式：

    • 网页端上传按钮上传
    • 本地Calibre软件管理书库后，把完整书库同步挂载到NAS的books目录

八、访问信息汇总

  • 地址：[http://192.168.0.xxx:8080](http://192.168.0.xxx:8080)
  • 账号：admin
  • 端口：8080
  • 挂载目录：
    • 配置：/volume2/docker/calibre-web/config
    • 书库：/volume2/docker/calibre-web/books