CALIBRE-WEB Docker 容器化部署指南

713次阅读

没有评论

共计 4890 个字符，预计需要花费 13 分钟才能阅读完成。

概述

CALIBRE-WEB 是一个基于 Web 的电子书管理应用，它提供了一个简洁的界面用于浏览、阅读和下载电子书，支持使用现有的 Calibre 数据库。该应用由 LinuxServer.io 团队提供容器化支持，具备以下特点：

定期及时的应用更新
简单的用户权限映射（PGID、PUID）
自定义基础镜像与 s6 overlay
每周基础操作系统更新，在整个 LinuxServer.io 生态系统中共享通用层，以最小化空间使用、停机时间和带宽消耗
定期安全更新

CALIBRE-WEB 还支持集成 Google Drive，并允许通过应用本身编辑元数据和管理 Calibre 库。该软件是 library 的一个分支，采用 GPL v3 许可证授权。

环境准备

在开始部署 CALIBRE-WEB 之前，需要先确保 Docker 环境已正确安装。对于大多数 Linux 发行版，可以使用以下一键安装脚本：

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

该脚本将自动安装 Docker 和 Docker Compose，并配置必要的系统参数。安装完成后，建议启用并启动 Docker 服务：

sudo systemctl enable docker
sudo systemctl start docker

镜像准备

拉取 CALIBRE-WEB 镜像

使用以下命令通过轩辕镜像加速地址拉取最新版本的 CALIBRE-WEB 镜像：

docker pull xxx.xuanyuan.run/linuxserver/calibre-web:latest

如需指定特定版本，可参考 CALIBRE-WEB 镜像标签列表选择合适的标签替换上述命令中的latest。

容器部署

CALIBRE-WEB 容器部署支持两种方式：Docker Compose（推荐）和 Docker CLI。两种方式都能实现相同的功能，可根据个人习惯选择。

使用 Docker Compose 部署

创建一个名为 docker-compose.yml 的文件，内容如下：

---
services:
  calibre-web:
    image: xxx.xuanyuan.run/linuxserver/calibre-web:latest
    container_name: calibre-web
    environment:
      - PUID=1000               # 用户 ID，用于权限映射
      - PGID=1000               # 组 ID，用于权限映射
      - TZ=Etc/UTC              # 时区设置，例如 Asia/Shanghai
      - DOCKER_MODS=linuxserver/mods:universal-calibre # 可选，启用电子书转换功能（仅 64 位系统）- OAUTHLIB_RELAX_TOKEN_SCOPE=1 # 可选，允许 Google OAUTH 支持
    volumes:
      - /path/to/calibre-web/data:/config  # 配置文件存储路径
      - /path/to/calibre/library:/books    # Calibre 库存储路径
    ports:
      - 8083:8083               # Web 界面端口映射
    restart: unless-stopped     # 自动重启策略

参数说明：

PUID和 PGID：用于解决容器内用户与宿主机用户的权限问题，可通过id your_username 命令查看当前用户的 UID 和 GID
TZ：时区设置，国内用户可设置为Asia/Shanghai
DOCKER_MODS：可选参数，用于启用电子书转换功能，仅支持 64 位系统
volumes：需要将宿主机的实际路径替换 /path/to/calibre-web/data 和/path/to/calibre/library
ports：默认 Web 界面端口为 8083，可根据需要修改宿主机端口

创建完成后，在该文件所在目录执行以下命令启动容器：

docker-compose up -d

使用 Docker CLI 部署

如果不使用 Docker Compose，可直接通过 docker run 命令部署：

docker run -d \
  --name=calibre-web \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -e DOCKER_MODS=linuxserver/mods:universal-calibre `# 可选 ` \
  -e OAUTHLIB_RELAX_TOKEN_SCOPE=1 `# 可选 ` \
  -p 8083:8083 \
  -v /path/to/calibre-web/data:/config \
  -v /path/to/calibre/library:/books \
  --restart unless-stopped \
  xxx.xuanyuan.run/linuxserver/calibre-web:latest

请将上述命令中的 /path/to/calibre-web/data 和/path/to/calibre/library替换为宿主机上的实际路径。其他参数与 Docker Compose 方式相同。

功能测试

容器启动后，可通过以下步骤验证 CALIBRE-WEB 是否正常工作：

访问 Web 界面

打开浏览器，访问http:// 服务器 IP:8083，应该能看到 CALIBRE-WEB 的登录界面。

初始登录

使用默认管理员凭据登录：

用户名：admin
密码：admin123

首次登录后，系统会要求您修改默认密码以提高安全性。

配置 Calibre 库位置

在初始设置界面，需要指定 Calibre 库的位置。根据容器部署时的卷映射配置，应输入 /books 作为 Calibre 库位置。

验证基本功能

检查是否可以浏览电子书（如果库中已有书籍）
尝试上传一本电子书到库中
测试阅读功能是否正常
检查设置页面是否可访问

查看容器日志

通过以下命令查看容器运行日志，确认是否有错误信息：

docker logs -f calibre-web

如无错误信息且 Web 界面正常访问，则说明 CALIBRE-WEB 部署成功。按 Ctrl+C 可退出日志查看。

生产环境建议

为确保 CALIBRE-WEB 在生产环境中稳定可靠运行，建议考虑以下配置：

数据备份策略

定期备份配置数据 ：对/path/to/calibre-web/data 目录进行定期备份，确保配置信息不会丢失
Calibre 库备份：如果 Calibre 库包含重要数据，建议实施定期备份策略
自动化备份：可使用 cron 任务或其他自动化工具实现定期备份，示例：

# 每日凌晨 2 点备份 Calibre 配置和库数据
0 2 * * * tar -czf /backup/calibre-$(date +\%Y\%m\%d).tar.gz /path/to/calibre-web/data /path/to/calibre/library

资源配置优化

内存分配：根据库中电子书数量和并发访问量，适当调整容器内存限制。对于小型图书馆，512MB 内存通常足够；对于大型图书馆或高并发场景，建议分配 1GB 或更多内存
CPU 资源：CALIBRE-WEB 对 CPU 资源要求不高，一般场景下 1 核 CPU 即可满足需求
存储性能：建议使用 SSD 存储以提高电子书加载速度，特别是对于包含大量图片的 PDF 文件

安全加固

使用非 root 用户运行：容器默认以非 root 用户运行，确保宿主机目录权限正确配置
设置强密码：确保管理员密码复杂度足够高，避免使用默认密码
HTTPS 访问：通过反向代理（如 Nginx、Traefik）配置 HTTPS，加密传输数据
网络隔离：限制 CALIBRE-WEB 仅在必要的网络范围内可访问，避免暴露在公网

监控与维护

容器状态监控：使用工具如 Prometheus+Grafana 或简单的监控脚本，定期检查容器运行状态
日志管理：配置日志轮转，避免日志文件过大占用磁盘空间
定期更新：定期更新 CALIBRE-WEB 镜像以获取最新功能和安全补丁：

# 使用 Docker Compose 更新
docker-compose pull
docker-compose up -d

# 使用 Docker CLI 更新
docker pull xxx.xuanyuan.run/linuxserver/calibre-web:latest
docker stop calibre-web
docker rm calibre-web
# 重新运行之前的 docker run 命令

故障排查

常见问题及解决方法

1. 权限问题

症状：无法读取或写入文件，Web 界面提示权限错误。

解决方法：

确保宿主机上的 /path/to/calibre-web/data 和/path/to/calibre/library目录权限正确，建议设置为 755
检查 PUID 和 PGID 是否与宿主机目录所有者匹配，可通过 chown 命令调整目录所有者：

chown -R 1000:1000 /path/to/calibre-web/data
chown -R 1000:1000 /path/to/calibre/library

2. 端口冲突

症状：容器启动失败，日志中出现 ”bind: address already in use” 错误。

解决方法：

检查 8083 端口是否已被其他服务占用：netstat -tulpn | grep 8083
如端口冲突，修改端口映射为未被占用的端口，例如使用 8084 端口：-p 8084:8083

3. 忘记管理员密码

症状：无法登录管理界面，忘记管理员密码。

解决方法：

通过以下命令重置管理员密码（将 <user> 替换为用户名，<pass>替换为新密码）：

docker exec -it calibre-web python3 /app/calibre-web/cps.py -p /config/app.db -s <user>:<pass>

例如重置 admin 用户密码为 newpassword123：

docker exec -it calibre-web python3 /app/calibre-web/cps.py -p /config/app.db -s admin:newpassword123

4. 电子书转换功能无法使用

症状：尝试转换电子书格式时失败。

解决方法：

确保已添加 DOCKER_MODS=linuxserver/mods:universal-calibre 环境变量
确认系统架构为 64 位（该功能仅支持 64 位系统）
在 Calibre-Web 管理页面（基本配置：外部二进制文件）设置 Calibre 电子书转换器路径：
- 对于 0.6.21 及更低版本：/usr/bin/ebook-convert
- 对于 0.6.22 及更高版本：/usr/bin/