linuxserver/colibre-web

linuxserver/colibre-web 提供了易于浏览、阅读和狭隘现有 Calibre 数据库提供的电子书。我计划在 linuxserver/calibre 部署之后结合使用，以实现一个较为完善的电子书网站。

安装

采用Docker Compose是比较简单方便的方法

初步运行

• 创建数据目录:

创建数据目录

mkdir -p ~/docs/calibre-suite/{calibre-config,web-config,library}
cd ~/docs/calibre-suite

• 编写 docker-compose.yml 配置(该配置没有启用HTTPS，现在较新版本 Selkies(基于WebRTC视频流的桌面) 已经强制采用HTTPS，所以实际访问无法打开桌面，必须改进增加HTTPS ):

配置 docker-compose.yml

services:
  # 后台转换/管理核心（替代本地客户端）
  calibre-backend:
    image: lscr.io/linuxserver/calibre:latest
    container_name: calibre-backend
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
    volumes:
      - ./calibre-config:/config
      - ./library:/library       # 关键：全量图书库和自动生成的 metadata.db 都在这里
    ports:
      - 8080:8080                # 访问 Calibre 虚拟桌面桌面（WebVNC）
    restart: unless-stopped

  # 精美前端与 Kobo 同步引擎
  calibre-web:
    image: lscr.io/linuxserver/calibre-web:latest
    container_name: calibre-web
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
    volumes:
      - ./web-config:/config
      - ./library:/books         # 关键：像素级对齐并读取同一个 library 目录
    ports:
      - 8083:8083                # 访问 Kobo 同步前端
    depends_on:
      - calibre-backend          # 确保后端先启动并初始化数据库
    restart: unless-stopped

改进HTTPS访问

由于 linuxserver/calibre 直接访问 http://<服务器IP>:8080 提示报错必须改进为HTTPS访问，所以上述Docker Compose再增加 Nginx 容器实现 NGINX反向代理https

• 创建数据目录:

创建数据目录，增加nginx配置目录

mkdir -p ~/docs/calibre-suite/{calibre-config,web-config,library}

# 增加创建nginx目录
mkdir -p ~/docs/calibre-suite/nginx/{conf.d,certs}

• 使用OpenSSL创建自签名证书:

使用OpenSSL创建自签名证书

cd ~/docs/calibre-suite/nginx/certs

openssl req -x509 -nodes -days 3650 -newkey rsa:2048 \
  -keyout server.key -out server.crt \
  -subj "/C=CN/ST=Shanghai/L=Shanghai/O=Homelab/OU=Calibre/CN=cloud-atlas.dev"

完成以后 certs 目录就有了 server.crt (公钥) 和 server.key (私钥)

• 编辑一个 支持WebSokcet 的握手升级头（Upgrade Headers） 的NGINX配置，这样就能够支持Selkies/KasmVNC 平台底层深度依赖 WebSocket（WS） 协议进行超低延迟的桌面画面广播: ~/docs/calibre-suite/nginx/conf.d/calibre.conf

~/docs/calibre-suite/nginx/conf.d/calibre.conf

server {
    listen 443 ssl;
    server_name localhost; # 内网通过 IP 访问，这里写 localhost 即可

    # 像素级挂载刚才生成的自签名证书
    ssl_certificate /etc/nginx/certs/server.crt;
    ssl_certificate_key /etc/nginx/certs/server.key;

    # 优化 SSL 安全参数
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # 1. 拦截并代理 Calibre 图形后端（WebVNC / Selkies）
    location / {
        proxy_pass http://calibre-backend:8080; # 利用 Docker 内置 DNS 直连后端容器端口
        
        # 核心：必须向下透传真实的客户端物理 IP
        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;

        # 核心大杀器：完美支持 Selkies 的 WebRTC WebSocket 流量升级握手
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";

        # 调大超时时间，防止看书或操作中断开链接
        proxy_read_timeout 86400;
    }
}

• 重新改写 docker-compose.yml :

增加NGINX反向代理HTTPS的容器的 docker-compose.yml

services:
  # 🔒 新增的 Nginx 高性能反向代理
  nginx-proxy:
    image: nginx:alpine
    container_name: nginx-proxy
    ports:
      - "8080:443"  # 物理映射：让你依然通过服务器的 8080 端口访问，但走的是 HTTPS！
    volumes:
      - ./nginx/conf.d:/etc/nginx/conf.d:ro
      - ./nginx/certs:/etc/nginx/certs:ro
    depends_on:
      - calibre-backend
    restart: unless-stopped

  # 后台转换/管理核心（替代本地客户端）
  calibre-backend:
    image: lscr.io/linuxserver/calibre:latest
    container_name: calibre-backend
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
    volumes:
      - ./calibre-config:/config
      - ./library:/library       # 关键：全量图书库和自动生成的 metadata.db 都在这里
      - ./import:/import         # 💡 书籍自动导入目录
    # 💡 运维重点：这里删除了原先的 ports 暴露，防止绕过 Nginx 直连纯净 HTTP
    restart: unless-stopped

  # 精美前端与 Kobo 同步引擎
  calibre-web:
    image: lscr.io/linuxserver/calibre-web:latest
    container_name: calibre-web
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Shanghai
    volumes:
      - ./web-config:/config
      - ./library:/books         # 关键：像素级对齐并读取同一个 library 目录
    ports:
      - 8083:8083                # 访问 Kobo 同步前端
    depends_on:
      - calibre-backend          # 确保后端先启动并初始化数据库
    restart: unless-stopped

备注

• Compose设置了 depends_on 确保启动顺序

• 后端数据库自动生成: calibre-backend 启动一个完整的Calibre运行环境，在初始化时候将数据目录修改为 /library 目录下初始化 metadata.db 核心数据库文件，就能和 Calibre-Web 共享目录

• 前端无缝读取: 访问 http://<服务器IP>:8083 时WEB和后端共享物理目录，这样 Calibre-Web就能够直接访问后端生成的 metadata.db

• 特别增加一个 import 目录，因为Calibre支持一种自动导入功能，只要将自动导入目录指向这个 import 目录，这样就能将文件从后台复制到该目录下，然后系统就会自动导入Calibre书库，不需要人工干预

备注

Calibre-Web 本质上是 Calibre 桌面端的 Web 前端，因此它的运行必须依赖一个由桌面端生成的初始化索引数据库文件 metadata.db 。如果没有按照上文同时运行 Calibre-Web 和 Calibre，那么可以从官方下载一个空白的 metadata.db 模板存放到 books 目录

下载空白的metadata.db

wget https://raw.githubusercontent.com/janeczku/calibre-web/master/optional-calibre-mount/metadata.db -O ~/homelab/calibre-web/books/metadata.db

• 访问 https://<服务器IP>:8080 就能看到一个Calibre桌面客户端软件；访问 http://<你的服务器IP>:8083 就能看到Calibre Web界面

备注

Calibre桌面 详见 linuxserver/calibre

使用

访问 http://<你的服务器IP>:8083 初次默认管理员账号：admin ，默认初始密码： admin123 务必第一时间进入设置修改默认密码。

参考

• GitHub: linuxserver/docker-calibre-web