crocodilestick/calibre-web-automated

Calibre-Web Automated - Docker镜像文档

镜像概述和主要用途

Calibre-Web Automated（简称CWA）是一个基于Docker的一体化自托管数字图书馆解决方案，它将Calibre-Web的现代轻量级Web界面与Calibre的强大功能集相结合，并添加了大量自动化特性。该镜像旨在解决原版Calibre在容器化时的资源占用问题，同时弥补Calibre-Web在功能上的不足，为用户提供一个既美观又实用的电子书管理平台。

核心功能和特性

基础功能（继承自Calibre-Web）

CWA特有功能

自动导入服务 ✨

• 支持27种不同的流行电子书格式的自动导入
• 用户可在管理面板中配置服务行为，包括忽略某些格式和自动转换特定格式

自动转换服务 🔃

• 默认启用，可在CWA设置页面中关闭
• 默认目标格式为EPUB，支持的目标格式包括：EPUB、MOBI、AZW3、KEPUB和PDF
• 检测到导入目录中的新文件时自动转换配置的格式

封面和元数据自动应用 👀📔

• 在Calibre-Web界面中对封面和元数据所做的更改会自动应用到实际电子书文件
• 解决原版Calibre-Web中元数据仅在界面显示而不修改实际文件的问题

批量编辑和删除 🗂️🗄️

• 支持批量编辑和删除书籍
• 通过书籍列表页面选择多本书籍进行操作

自动备份服务 🔒

• 默认将所有处理过的文件的原始版本存储在/config/processed_books
• 可在CWA设置面板中切换此功能

自动EPUB修复服务 🔨

• 修复EPUB文件中的常见问题，确保与Amazon的Send-to-Kindle服务兼容
• 解决UTF-8编码问题、超链接问题、无效/缺失语言标签和杂散标签等问题
• 默认启用，可在设置中关闭

多格式转换服务 🌌

• 提供简单易用的多格式转换工具
• 支持保留原始文件副本或替换文件（不推荐替换）

额外的元数据提供商 🗃️

• 支持isbndb.com的大型数据库（通过ibdb.dev提供）
• 正在集成Hardcover作为元数据提供商

KOReader同步（KOSync） 📖⚡

• 内置KOReader同步功能，提供传统KOReader同步服务器的现代替代方案
• 通用KOReader同步器：适用于所有兼容KOReader的设备
• 现代认证：使用RFC 7617兼容的基于头的认证
• CWA集成：利用现有CWA用户账户和权限
• 简易安装：插件和设置说明可从CWA实例的/kosync路径获取

增强的OAuth 2.0/OIDC认证 🔐

• 自动发现：通过OIDC元数据URL自动配置端点
• 手动覆盖：当自动发现不可用时，可完全手动控制OAuth端点
• 字段映射：可配置的JWT字段提取，用于用户名和电子邮件
• 基于组的角色：根据OAuth提供商组自动分配管理员角色
• 测试工具：内置连接测试和验证功能
• 企业就绪：支持自定义范围、多种认证方法和全面的故障排除

服务器统计跟踪页面 📍📊

• 提供CWA使用统计信息
• 记录所有执行的操作，便于问题排查

图书馆自动检测 📚🕵️

• 简化新用户和现有用户的设置过程
• 自动检测缺少的库并创建新库
• 自动查找并挂载现有Calibre库

明暗模式切换 ☀️🌙

• 通过Web UI导航栏上的🕶️图标一键切换主题

内部更新通知系统 🛎️

• 从Web UI内自动通知用户有新版本可用
• 仅管理员可见，每天显示一次直到更新

手动图书馆刷新 ♻️

• 通过Web UI导航栏上的"刷新图书馆"按钮手动触发导入目录处理
• 处理意外断电等情况后滞留在导入文件夹中的书籍

备份文件自动压缩 🤐

• 每天午夜前自动压缩当天处理的所有文件
• 最小化磁盘空间使用并保持备份文件的组织性
• 默认启用，可在CWA设置页面中禁用

使用场景和适用范围

Calibre-Web Automated适合以下场景：

1. 个人电子书库管理：为个人用户提供完整的电子书管理解决方案，包括自动导入、转换和元数据管理。

2. 家庭图书馆共享：支持多用户和权限控制，适合家庭内共享电子书资源。

3. 小型组织或社区图书馆：提供用户注册、内容隐藏和权限管理功能，适合小型组织共享数字资源。

4. 电子阅读器用户：支持多种格式转换和设备同步，特别适合拥有Kindle、Kobo等电子阅读器的用户。

5. 自托管爱好者：为喜欢自托管服务的用户提供功能丰富、自动化的电子书管理平台。

安装与部署

快速安装 🚀

1. 使用以下命令下载Docker Compose模板文件：

bash
curl -OL https://raw.githubusercontent.com/crocodilestick/calibre-web-automated/main/docker-compose.yml

2. 将compose文件移动到一个空文件夹（例如：~/docker/calibre-web-automated/docker-compose.yml），该文件夹将用于存储服务器数据和图书馆。

3. 编辑compose文件，根据注释填写时区（可选）和所需的挂载路径。

4. 使用cd命令导航到下载Compose文件的位置，然后运行：

bash
docker compose up -d

使用Docker Compose（推荐）🐋⭐

以下是推荐的Docker Compose配置示例：

yaml
version: '3.8'

services:
  calibre-web-automated:
    image: docker.xuanyuan.run/crocodilestick/calibre-web-automated:latest
    container_name: calibre-web-automated
    restart: unless-stopped
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai  # 替换为您的时区
      #- NETWORK_SHARE_MODE=false  # 仅在使用网络共享时设置为true
      #- CWA_WATCH_MODE=poll  # 仅在inotify不可用时设置
    volumes:
      - ./config:/config  # 配置文件存储路径
      - ./library:/library  # 图书馆存储路径
      - ./ingest:/ingest  # 导入文件夹路径
    ports:
      - "8083:8083"  # Web界面端口

保存为docker-compose.yml文件，然后运行：

bash
docker compose up -d

从原版Calibre-Web迁移 🔄

1. 停止原版Calibre-Web容器
2. 复制原版Calibre-Web的配置文件夹和图书馆文件夹
3. 使用上述Docker Compose配置启动CWA，确保挂载正确的配置和图书馆路径
4. 启动容器后，CWA将自动适应现有配置和图书馆

安装后任务 🏁

默认管理员登录凭据 🔑

• 默认管理员用户名: admin
• 默认管理员密码: admin123

首次登录后，请立即更改管理员密码以确保安全。

使用方法和配置说明

添加书籍到图书馆

1. 将电子书文件放入配置的导入目录（默认为./ingest）
2. CWA将自动检测并处理新文件：
   • 导入支持的格式
   • 根据配置转换文件格式
   • 应用元数据和封面
   • 将处理后的文件添加到图书馆

手动刷新图书馆

如果书籍在意外断电等情况后停留在导入文件夹中，可以使用Web UI导航栏上的"刷新图书馆"按钮手动触发导入。

KOReader同步（KOSync）📖⚡

1. 在KOReader设备上安装同步插件
2. 从CWA实例的/kosync路径获取详细的插件和设置说明
3. 使用现有CWA用户凭据进行配置
4. 开始在所有KOReader设备之间同步阅读进度

OAuth认证设置 🔐

1. 登录CWA管理界面
2. 导航到"设置" > "认证" > "OAuth设置"
3. 选择OAuth提供商或使用自定义设置
4. 配置以下选项：
   • OIDC元数据URL（用于自动发现）或手动输入端点
   • 客户端ID和客户端密钥
   • 用户名和电子邮件字段映射
   • 管理员组映射（可选）
5. 使用内置测试工具验证配置
6. 保存设置并启用OAuth认证

环境变量配置

网络共享注意事项 🚨

Calibre、Calibre-Web和CWA都是基于SQLite3的应用，因此不建议在网络共享（尤其是NFS）上运行：

• SQLite设计为轻量级、基于文件的数据库系统，假设底层文件系统支持文件锁定、原子写入和一致性保证
• 网络文件系统（如NFS、SMB/CIFS等）通常不满足这些假设，可能导致问题

如果必须在网络共享上部署CWA，请设置：

yaml
environment:
  - NETWORK_SHARE_MODE=true

这将禁用SQLite WAL模式并调整文件处理以提高网络共享兼容性，但仍可能遇到问题。

注意事项和限制

1. SQLite和网络共享：如前所述，CWA在网络共享（尤其是NFS）上可能不稳定，官方不提供对此类部署的支持。

2. 性能考虑：自动转换和处理大量书籍可能会消耗大量系统资源，建议在具有足够CPU和内存的系统上运行。

3. 存储空间：电子书库，特别是包含多种格式的库，可能需要大量存储空间。确保有足够的磁盘空间可用。

4. 备份：虽然CWA提供自动备份功能，但建议定期备份整个图书馆和配置目录，以防数据丢失。

5. 更新：使用Docker Compose时，可以通过以下命令更新CWA：

   bash
   docker compose pull
   docker compose up -d
   

社区支持

• 服务器：[]
• GitHub项目：https://github.com/crocodilestick/Calibre-Web-Automated
• Wiki文档：https://github.com/crocodilestick/Calibre-Web-Automated/wiki

功能开发路线图

高优先级 🚨

• 与Hardcover集成，作为元数据提供商和阅读进度同步
• 集成其他内容来源
• 支持Calibre插件（如deDRM）
• 拆分图书馆（将Calibre图书馆和书籍存储在不同位置）

低优先级 🌱

• 通知系统集成（***、Gotify、ntfy等）
• ***集成

总结

Calibre-Web Automated提供了一个功能丰富、高度自动化的自托管电子书管理解决方案，结合了Calibre-Web的现代Web界面和Calibre的强大功能。通过Docker部署，可以轻松设置和管理个人或家庭电子书库，并享受自动导入、转换、元数据管理等高级功能。

无论是电子阅读器用户、电子书收藏者还是需要共享数字资源的小型组织，Calibre-Web Automated都能提供直观且强大的解决方案，简化电子书管理流程。# Calibre-Web Automated - Docker镜像文档

镜像概述和主要用途

Calibre-Web Automated (简称CWA) 是一个功能增强的Docker镜像，旨在将Calibre-Web的现代轻量级Web界面与Calibre的强大功能集相结合，并添加了大量自动化特性。该项目解决了原版Calibre在容器化时的资源占用问题，同时弥补了Calibre-Web在功能上的不足，提供了一个一体化的自托管数字图书馆解决方案。

CWA的主要目标是成为一个全方位的解决方案，让用户能够轻松管理、转换、同步和访问他们的电子书收藏，同时提供直观且美观的Web界面。

核心功能和特性

基础功能（继承自Calibre-Web）

CWA特有功能

自动导入服务 ✨

• 支持27种不同的流行电子书格式的自动导入
• 用户可配置服务行为，包括忽略某些格式和自动转换特定格式
• 智能检测最佳导入格式，避免重复导入

自动转换服务 🔃

• 默认启用，可在设置页面关闭，默认目标格式为EPUB
• 支持的目标格式：EPUB、MOBI、AZW3、KEPUB和PDF
• 检测到导入目录中的新文件时自动转换配置的格式

封面和元数据自动应用 👀📔

• 在Calibre-Web界面中对封面和元数据所做的更改会自动应用到实际电子书文件
• 解决原版Calibre-Web中元数据仅在界面显示而不修改实际文件的问题

批量编辑和删除 🗂️🗄️

• 支持批量选择书籍进行编辑和删除操作
• 通过书籍列表页面选择多本书籍，使用表格上方或标题内的按钮执行操作

自动备份服务 🔒

• 默认将所有处理过的文件的原始版本存储在/config/processed_books
• 可在CWA设置面板中切换此功能

自动EPUB修复服务 🔨

• 修复EPUB文件中的常见问题，确保与Amazon的Send-to-Kindle服务兼容
• 解决UTF-8编码问题、超链接问题、无效/缺失语言标签和杂散标签等问题

多格式转换服务 🌌

• 提供Web界面工具，支持将图书馆中的书籍批量转换为不同格式
• 可选择保留原始文件或替换（建议保留）

(https://github.com/crocodilestick/Calibre-Web-Automated/raw/main//README_images