>
首页›使用教程›Calibre-Web 搭建教程
🌐 随时随地访问你的书库

Calibre-Web
搭建私人书库教程

基于 Docker 部署 Calibre-Web，实现网页在线阅读、OPDS 推送、多用户管理。让书库触手可及。

❓

什么是 Calibre-Web

不只是网页版 Calibre，而是全新的书库服务体验

Calibre-Web 是一个基于 Web 的 Calibre 书库浏览器和管理界面，托管在 GitHub（janeczku/calibre-web）。它不是 Calibre 官方出品，但已经成为 Calibre 生态中最受欢迎的配套项目之一。

核心功能概览

  1. 网页在线阅读器：在浏览器中直接阅读 EPUB 格式电子书，支持书签、夜间模式、字体调整
  2. OPDS 目录服务：任何支持 OPDS 的阅读 App（如 FBReader、KyBook、Marvin）都可以通过 URL 连接到你的书库，在线浏览和下载
  3. 多用户管理：为家人或朋友创建独立账号，控制每个人能看到的书架范围
  4. Kindle 集成：一键将书籍推送到 Kindle 邮箱，完全替代 Calibre 桌面端的邮件发送功能
  5. Kobo 同步：兼容 Kobo 设备的阅读进度同步
  6. 在线格式转换：利用服务器端 Calibre 引擎，在网页上直接完成格式转换
  7. 自定义书架上架：按标签、丛书、作者自动生成公开或私密的书架展示
💡 Calibre-Web 不等于 Calibre。它需要读取 Calibre 桌面端创建的书库（metadata.db），但提供的是完全独立的 Web 体验。
🛠️

准备工作

部署前的环境与资源清单

在开始部署之前，请确认以下四项准备就绪：

1. 服务器 / VPS / NAS

  1. 任何能运行 Docker 的设备：云服务器（阿里云/腾讯云轻量应用服务器性价比高）、家用 NAS（群晖/威联通）、树莓派（推荐 4B 以上）、甚至一台旧电脑
  2. 最低配置：1 核 CPU、512MB 内存、10GB 存储（实际取决于你的书库大小）

2. Docker 环境

  1. 安装 Docker Engine（docker.com 下载）
  2. 安装 Docker Compose（新版 Docker Desktop 已内置）
  3. 验证安装：终端运行 docker --version 和 docker compose version

3. Calibre 书库路径

  1. 确保你已经在 Calibre 桌面端创建了一个书库（包含 metadata.db 文件）
  2. 记录书库文件夹的完整路径（如 /home/user/Calibre Library 或 D:\Calibre Library）
  3. 建议把书库放在服务器的持久化存储位置

4. 域名 + SSL（可选但强烈推荐）

  1. 购买一个域名，解析到服务器 IP
  2. 准备 SSL 证书（可以用 Let's Encrypt 免费获取）
🐳

Docker 部署步骤

一行命令（或一个 compose 文件）启动 Calibre-Web

docker-compose.yml 示例（推荐方式）

在服务器上创建 docker-compose.yml 文件：

version: "3.8"
services:
  calibre-web:
    image: lscr.io/linuxserver/calibre-web:latest
    container_name: calibre-web
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
      - DOCKER_MODS=linuxserver/calibre-web:calibre
    volumes:
      - ./config:/config
      - /path/to/Calibre Library:/books
    ports:
      - "8083:8083"
    restart: unless-stopped

环境变量说明

  1. PUID / PGID：运行容器的用户和组 ID。运行 id 命令查看。设为 0 即为 root（不推荐）
  2. TZ：时区，中国用户设为 Asia/Shanghai
  3. DOCKER_MODS：添加此行可启用服务器端格式转换功能（在容器中内置 Calibre 引擎）

端口映射

  1. 8083:8083：Calibre-Web 默认监听 8083 端口。左侧为宿主机端口，可自定义（如改为 8888:8083）

持久化存储

  1. ./config：Calibre-Web 的配置数据（用户信息、设置），映射到宿主机避免容器重建后丢失
  2. /path/to/Calibre Library：你的 Calibre 书库路径，必须替换为实际路径。容器内挂载到 /books

启动容器

cd /path/to/docker-compose-file
docker compose up -d

启动后访问 http://你的服务器IP:8083 即可看到 Calibre-Web 页面。

💡 强烈推荐使用 linuxserver 维护的镜像，更新快、跟进积极、文档完整。官方 linuxserver/calibre-web 镜像在 Docker Hub 上有 100M+ 下载量。
⚙️

初始化配置

首次启动后的必要设置

首次启动流程

  1. 打开浏览器访问 http://服务器IP:8083
  2. 首次访问会看到登录页面，但还没有账号
  3. 数据库路径设置：在登录页面下方，输入 Calibre 书库的路径。对应 docker-compose 中的容器内路径 /books，点击"保存"
  4. 用户注册：数据库路径配置成功后，页面会显示注册入口。第一个注册的用户自动成为管理员
  5. 填写用户名、邮箱、密码完成注册

管理员设置

  1. 登录后进入管理面板（右上角齿轮图标 → 管理用户）
  2. 在"基本配置"中设置：网站标题、默认语言（中文）、每页显示书籍数量
  3. 强烈建议开启"允许上传"和"允许未登录用户浏览"（根据你的使用场景决定）
🔐 为了安全，如果服务暴露在公网，建议立即关闭公开注册功能：管理 → 基本配置 → 关闭"允许注册"。
🔧

功能配置

开启上传、转换、推送等核心功能

开启上传

  1. 管理 → 基本配置 → 功能配置 → 勾选"允许上传"
  2. 设置允许的上传格式（EPUB、PDF、MOBI 等）
  3. 用户即可在网页端直接上传新书到书库

格式转换（需 DOCKER_MODS）

  1. 确保 docker-compose 中包含 DOCKER_MODS=linuxserver/calibre-web:calibre
  2. 重启容器：docker compose restart
  3. 进入管理 → 基本配置 → 外部程序 → 设置"电子书转换器路径"为 /usr/bin/ebook-convert
  4. 用户即可在网页端触发格式转换（和桌面版 Calibre 同样效果）

Kobo 同步

  1. 管理 → 基本配置 → 功能配置 → 勾选"启用 Kobo 同步"
  2. 在 Kobo 设备的浏览器中打开 Calibre-Web 地址，即可直接下载 Kepub 格式

邮件推送（Kindle 集成）

  1. 管理 → 邮件设置 → 填写 SMTP 服务器信息（推荐 QQ 邮箱：smtp.qq.com，端口 465，SSL）
  2. 设置发件人邮箱和密码（QQ 邮箱需使用授权码而非登录密码）
  3. 用户可以在书籍详情页点击"发送到 Kindle"，输入 Kindle 邮箱即可推送

OPDS Feed

  1. 默认已启用，OPDS 地址为 http://你的域名:8083/opds
  2. 在阅读 App 中输入该地址即可连接书库
🔒

反向代理与 HTTPS

用 Nginx/Caddy 为书库配置安全访问和自有域名

Nginx 反向代理配置示例

将以下配置添加到 Nginx 配置文件中：

server {
  listen 443 ssl;
  server_name books.yourdomain.com;
  ssl_certificate /path/to/cert.pem;
  ssl_certificate_key /path/to/key.pem;
  client_max_body_size 100M;
  location / {
    proxy_pass http://127.0.0.1:8083;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
  }
}

Caddy 配置示例（更简单）

Caddy 会自动申请和续签 Let's Encrypt SSL 证书：

books.yourdomain.com {
  reverse_proxy localhost:8083
}
🔒 公网部署强烈推荐配置 HTTPS。不加密的 HTTP 连接可能导致密码和 Cookie 被窃取。Let's Encrypt 提供免费 SSL 证书。
🚀

进阶玩法

解锁 Calibre-Web 的更多可能性

自定义 CSS

  1. 管理 → 基本配置 → 自定义 CSS
  2. 可以完全改变 Calibre-Web 的外观（字体、颜色、布局）
  3. 社区有大量现成的主题 CSS 可以直接使用

多书库切换

  1. 如果想管理多个独立的书库，可以运行多个 Calibre-Web 容器实例，分别挂载不同书库
  2. 也可以使用 Calibre-Web 的"书架"功能在不同标签间切换

LDAP / OAuth 登录

  1. 管理 → 基本配置 → LDAP/OAuth 设置
  2. 支持对接企业 LDAP 目录或 Google/GitHub OAuth 登录
  3. 适合团队共享书库场景

Readarr 联动

  1. Readarr 是电子书的自动化下载和管理工具（类似 Sonarr/Radarr 但面向书籍）
  2. Readarr 可以自动下载书籍并放入 Calibre 书库，Calibre-Web 则提供在线阅读界面
  3. 两者配合可实现全自动的"书籍获取 → 管理 → 阅读"管线
🩺

常见部署问题排查

遇到问题先查这里，省时省力

Q1：启动后页面显示"数据库路径无效"？

  1. 检查 docker-compose.yml 中 volumes 路径是否正确
  2. 确认宿主机书库目录中存在 metadata.db 文件
  3. 容器内路径 /books 必须指向包含 metadata.db 的目录（而非 metadata.db 文件本身）

Q2：上传书籍后书库没有更新？

  1. Calibre-Web 依赖 metadata.db 读取书库目录。上传后需要等待数秒刷新
  2. 检查书库目录权限：docker exec calibre-web ls -la /books 确认容器内有写入权限

Q3：转换功能不可用？

  1. 确认 docker-compose.yml 中包含 DOCKER_MODS 环境变量
  2. 重启容器后，在管理面板中验证转换器路径
  3. 注意：转换功能需要更多内存（建议 1GB 以上），低配机器可能超时

Q4：502 Bad Gateway（Nginx 反向代理）？

  1. 检查 Calibre-Web 容器是否正常运行：docker ps | grep calibre-web
  2. 检查端口映射是否正确：docker port calibre-web
  3. 查看 Calibre-Web 日志：docker logs calibre-web

Q5：页面加载慢？

  1. 书库过大（超过 1 万本）时，Calibre-Web 的首次加载可能较慢。考虑使用 SSD 存储
  2. 关闭不必要的功能（如在线阅读器预加载）可以改善响应速度

开始搭建你的私人书库

Docker 一键部署，30 分钟拥有专属在线图书馆

免费下载 Calibre 返回使用教程

📖 相关教程

更多 Calibre 使用技巧，探索以下教程：