华为云搭建Calibre-Web云端书库全记录

需求背景：解决平板空间不足到随看随下的服务器解决方案

故事的开始，源于妹妹的平板电脑储存空间告急，再也装不下她日益增多的电子书收藏了。不过我发现我推给她的"静读天下"App支持"云端书库"功能，便打算用我尚有空闲的服务器为她搭建一个专属的、无限容量的云端图书馆

不过我的第一次尝试是"坚果云"，它设置简单，（能用成熟的解决方案就用，嘿嘿|ू･ω･` )）但很快，每月1GB的上传和3GB的下载流量限制，对于一个书库来说，这太局限了，只能作为一个备选方案。

在进一步的调研中，我遇到了它------Calibre-Web，一个强大开源的个人书库项目。而部署它，最简单的方式是使用Docker。久仰Docker大名，这次终于落到实处了ヾ(ｏ･ω･)ﾉ

一、给服务器安装Docker

我的装备很简单：一台2核2G的云服务器。不过没用宝塔面板一键安装Docker，这次跟着教程走流程

在Calibre-Web服务器安装教程、附赠多系统安装Docker教程）和AI的指导，开始在服务器上安装Docker和Docker Compose。过程唯一的阻挠便是，在添加Docker官方GPG密钥时，有443连接错误，多试几次就好了。

ps：不需要教程一的数据库文件操作，不过其可以贯穿整个大体流程d(´ω｀*)

二、Docker镜像选择

(1)部署实例选择：我了解到有Calibre和Calibre-Web：前者更像一个本地的、重量级的管理软件；而后者，天生就是为云端访问和分享而生的。目标明确，我选择了Calibre-Web。

(2)选择Docker镜像：社区里有多个Calibre-Web的Docker Image ，我最终选择了johngong/calibre-web这个版本。原因很简单：经过调研，我发现另一个曾经流行的版本[technosoft2000/calibre-web]已经停止维护，并且存在一些已知的Bug

然而，真正的挑战来了------网络。直接从官方的Docker Hub拉取镜像，速度慢得令人绝望。即使尝试了网上教程里的镜像加速器，效果也并不理想。

就在我一筹莫展之际，我发现了一个神奇的网站 (https://docker.aityp.com) ，它能为Docker镜像提供加速下载命令。我的下载进度条瞬间起飞！✧*｡٩(ˊᗜˋ*)و✧*｡

ps：我选的是"docker.io/johngong/calibre-web:0.6.24-7.9.0"版本，教程

三、编写 `docker-compose.yml`

一开始，我对Docker的部署原理一无所知。镜像下载下来了，它只是一个静态的"模板"，如何让它跑起来？通过与AI的反复问答，我逐渐理解了：docker-compose.yml文件，就是一份精确的"装配指令图"。

使用Docker Compose，可以将所有复杂的配置参数------端口、文件夹、环境变量------都写进这一个文件里。这就告别了网上那些又长又难记的docker run命令，实现了优雅的"一键发射"。

不过"最新"(latest)的，未必是最好的。我第一次尝试使用了:latest (最新)标签来启动容器，结果再次遭遇了网络访问失败。AI导师告诉我，:latest标签会触发Docker在每次启动时都联网检查更新，这在国内的网络环境下是致命的。在生产环境中，必须使用精确的版本号标签，比如我的0.6.24-7.9.0，来保证部署的确定性和可复现性。 当时我还想着个人项目选latest每次运行就都能保持最新版本挺好的呢,结果服务器没T子变成了每次都碰壁**╮(╯﹏╰）╭** ，还是指定特定版本号稳定

这是我最终的、经过千锤百炼的 docker-compose.yml 先呈上来(*´・ｖ・)：

javascript 复制代码

# 使用较新的Compose文件版本，功能更全
# version: "3.7" #不需要了本身就够新了，会自动忽略

services:
  # 定义我们的calibre-web服务
  calibre-web:
    # 1. 镜像 (Image): 指定使用你下载的这个镜像
    image: johngong/calibre-web:0.6.24-7.9.0
    
    # 2. 容器名 (Container Name): 给它起个名字，方便管理
    container_name: calibre-web
    
    # 3. 端口映射 (Ports): 把容器的8083端口暴露到服务器的8083端口
    ports:
      - "8083:8083"
      
    # 4. 卷映射 (Volumes): 这是最关键的"手动连接"
    volumes:
      # 将我们控制室的appdata文件夹，连接到容器内部的/config接口
      # 注意：这里的 ./appdata 是一个相对路径，代表当前目录下的appdata文件夹
      - ./config:/config
      
      # 将你服务器上真正的书库文件夹，连接到容器内部的/library接口
      # 【请修改这里!】把 /root/my_ebooks 替换成你自己的真实路径
      - ./books:/library
      - ./autoaddbooks:/autoaddbooks
    environment:
      # 设置用户和组ID，通常保持1000即可，用于文件权限管理
      - PUID=1000
      - PGID=1000
      
      # 设置时区，保证日志和任务时间正确
      - TZ=Asia/Shanghai
      # Ai桑说的【重要】根据文档，需要开启这个补丁，让calibre-web和内置的calibre-server能和谐共存
      - ENABLE_CALIBREDB_URLLIBRARYPATH=true

      //解决第四步"获取元数据"卡死的参数    复制后记得删掉本行
      # Ai说是自带的豆瓣参数，虽然官方文档没见，试试
      - ENABLE_DOUBAN_RATE_LIMIT_PATCH=true
      # 手动设置禁止禁用搜索,现在把国外的禁用了，只开豆瓣
      - DISABLE_GOOGLE_SEARCH=true  #谷歌
      - DISABLE_SCHOLAR_SEARCH=true  #谷歌学术搜索?
      - DISABLE_AMAZON_SEARCH=true #亚马逊
      - DISABLE_COMICVINE_SEARCH=true  #美国漫画
      - DISABLE_DOUBAN_SEARCH=false
      - DISABLE_LUBIMYCZYTAC_SEARCH=true #波兰图书馆
      
    # 6. 重启策略 (Restart Policy): 保证容器在退出或服务器重启后能自动启动
    restart: unless-stopped

四、害获取元数据卡死的豆瓣api？

服务成功启动，我通过http://我的服务器IP:8083访问到了Calibre-Web的界面。但新的问题出现了：当我上传一本书，点击"获取元数据"时，页面就陷入了无尽的加载中，最终只能通过重启容器来解决。

搜寻半天，文章都是说豆瓣api关闭了，用不了啦，换个api吧( Ĭ ^ Ĭ )

正当我准备研究如何安装一堆复杂的第三方API插件时，一个"意外"的发现为我指明了方向。我不小心开启了魔法，并再次尝试获取元数据，页面立刻从"一直加载"变成了明确的"加载失败"提示。

我瞬间顿悟！ 问题根源有可能在于Calibre-Web在后台尝试连接那些国外的API网站，而这些连接在国内网络环境下极其不稳定，导致了请求超时，最终拖垮了整个应用 |*´Å`)ﾉ

我果断使原本计划的复杂的插件路线中道崩殂，选择了最直接、最根本的解决方案：回到我的docker-compose.yml蓝图中，通过镜像文档中的环境变量，将所有国外网站的搜索功能一一禁用，只保留国内可以稳定访问的豆瓣源。

javascript 复制代码

      - DISABLE_GOOGLE_SEARCH=true  #谷歌
      - DISABLE_AMAZON_SEARCH=true #亚马逊
      # ...等等

我执行了 docker compose up -d 让配置生效。再次尝试，终于能获取豆瓣的书籍数据了！(*/ω＼*)

五、连接静读天下与其下载问题小提示

我把服务器的IP地址和端口在"静读天下"App的"云端书库"功能中添加一个新的OPDS目录。

这里还有一个小插曲：首次从"静读天下"下载书籍时，手机的通知栏可能没有任何下载进度提示，让人以为没有成功。 但经过我的测试，这只是UI显示的问题，后台其实正在默默地全速下载。只要你在Web端能正常下载书，那这边App端就一定可以。

六、总结

嗯，还是花了一下午的，但一回看其实就安装个Docker、配置个yml、调调参、必必应，一路教程和A老师护送，还是缓慢地理解了Docker这使环境和数据分离的工具，还有看着超方便的docker-compose配yml文件组合。方便是真方便，只是遇到这种灵异的时候调参也需要点灵感而已￣ω￣=

服务器补充知识：swap

我2核2g的小服务器还是经不住蹂躏，三台设备同时io就负载拉爆了，于是我就想着是不是可以加点虚拟内存，然后还真发现没有并给我整上了，且效果也很显著。如下：

操作步骤：为服务器创建一个2GB的Swap文件
检查当前是否有Swap 执行命令，如果没有任何输出，说明没有启用Swap。

bash
复制代码
sudo swapon --show
创建Swap文件 我们用fallocate命令在根目录创建一个2GB大小的文件，作为"书架"。

bash
复制代码
sudo fallocate -l 2G /swapfile
设置正确的权限 这个文件里将存放内存数据，非常敏感，必须设置只有root用户能读写。

bash
复制代码
sudo chmod 600 /swapfile
将该文件格式化为Swap空间 告诉系统，这个文件以后要当做Swap来用。

bash
复制代码
sudo mkswap /swapfile
立即启用Swap空间

bash
复制代码
sudo swapon /swapfile
再次检查，验证是否成功 现在再执行这个命令，应该能看到Swap空间的信息了。

bash
复制代码
sudo swapon --show
# 或者用 free -h 命令，能看到Swap一行有了2G的容量
free -h
【关键一步】让Swap永久生效 以上操作在服务器重启后会失效。我们需要把Swap信息写入到系统启动的配置文件/etc/fstab中。
首先，备份一下这个重要文件，这是一个好习惯： bash
复制代码
sudo cp /etc/fstab /etc/fstab.bak
然后，将Swap配置追加到文件末尾： bash
复制代码
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
现在，服务器已经拥有了强大的"虚拟内存"，在处理上传下载任务时，稳定性会大大提高。

执行效果

bash 复制代码

root@hcss-ecs-0abe:~/calibre-web-docker# sudo swapon --show
root@hcss-ecs-0abe:~/calibre-web-docker# sudo fallocate -l 2G /swapfile
root@hcss-ecs-0abe:~/calibre-web-docker# sudo chmod 600 /swapfile
root@hcss-ecs-0abe:~/calibre-web-docker# sudo mkswap /swapfile
配置 swap 空间版本 1，大小 = 2 GiB (2147479552 字节)
无标签，UUID=0ba0a648-49b2-4665-803a-e94bcea2b6bb
root@hcss-ecs-0abe:~/calibre-web-docker# sudo swapon /swapfile
root@hcss-ecs-0abe:~/calibre-web-docker# sudo swapon --show
NAME      TYPE SIZE USED PRIO
/swapfile 文件   2G   0B   -2
root@hcss-ecs-0abe:~/calibre-web-docker# ls
autoaddbooks  books  config  docker-compose.yml
root@hcss-ecs-0abe:~/calibre-web-docker# ls -ah
.  ..  autoaddbooks  books  config  docker-compose.yml
root@hcss-ecs-0abe:~/calibre-web-docker# sudo cp /etc/fstab /etc/fstab.bak
root@hcss-ecs-0abe:~/calibre-web-docker# cd ../
root@hcss-ecs-0abe:~# ls
calibre-web-docker  csv_chat  EasyRSA-3.1.2.tgz  HSSInstall  install.sh  my_file.txt  myfile.txt  openvpn  simple_share  snap
root@hcss-ecs-0abe:~# cd ../
root@hcss-ecs-0abe:/# ls
bin   CloudrResetPwdAgent  data  etc   lib    lib64   lost+found  mnt  patch  root  sbin  srv       sys  usr  www
boot  credentials          dev   home  lib32  libx32  media       opt  proc   run   snap  swapfile  tmp  var
root@hcss-ecs-0abe:/# echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
/swapfile none swap sw 0 0
root@hcss-ecs-0abe:/# sudo swapon --show
NAME      TYPE SIZE USED PRIO
/swapfile file   2G   0B   -2