网站导航
> 技术文档 > 华为云搭建Calibre-Web云端书库全记录

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

网友: 技术文档 2025-07-30 10:30:17

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

故事的开始，源于妹妹的平板电脑储存空间告急，再也装不下她日益增多的电子书收藏了。不过我发现我推给她的“静读天下”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 先呈上来(*´・ｖ・)：

# 使用较新的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蓝图中，通过镜像文档中的环境变量，将所有国外网站的搜索功能一一禁用，只保留国内可以稳定访问的豆瓣源。

     - 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文件

  1. 检查当前是否有Swap 执行命令，如果没有任何输出，说明没有启用Swap。

    bash

    sudo swapon --show

  2. 创建Swap文件 我们用fallocate命令在根目录创建一个2GB大小的文件，作为“书架”。

    bash

    sudo fallocate -l 2G /swapfile

  3. 设置正确的权限 这个文件里将存放内存数据，非常敏感，必须设置只有root用户能读写。

    bash

    sudo chmod 600 /swapfile

  4. 将该文件格式化为Swap空间 告诉系统，这个文件以后要当做Swap来用。

    bash

    sudo mkswap /swapfile

  5. 立即启用Swap空间

    bash

    sudo swapon /swapfile

  6. 再次检查，验证是否成功 现在再执行这个命令，应该能看到Swap空间的信息了。

    bash

    sudo swapon --show# 或者用 free -h 命令，能看到Swap一行有了2G的容量free -h

  7. 【关键一步】让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

现在，服务器已经拥有了强大的“虚拟内存”，在处理上传下载任务时，稳定性会大大提高。

执行效果
root@hcss-ecs-0abe:~/calibre-web-docker# sudo swapon --showroot@hcss-ecs-0abe:~/calibre-web-docker# sudo fallocate -l 2G /swapfileroot@hcss-ecs-0abe:~/calibre-web-docker# sudo chmod 600 /swapfileroot@hcss-ecs-0abe:~/calibre-web-docker# sudo mkswap /swapfile配置 swap 空间版本 1，大小 = 2 GiB (2147479552 字节)无标签，UUID=0ba0a648-49b2-4665-803a-e94bcea2b6bbroot@hcss-ecs-0abe:~/calibre-web-docker# sudo swapon /swapfileroot@hcss-ecs-0abe:~/calibre-web-docker# sudo swapon --showNAME TYPE SIZE USED PRIO/swapfile 文件 2G 0B -2root@hcss-ecs-0abe:~/calibre-web-docker# lsautoaddbooks books config docker-compose.ymlroot@hcss-ecs-0abe:~/calibre-web-docker# ls -ah. .. autoaddbooks books config docker-compose.ymlroot@hcss-ecs-0abe:~/calibre-web-docker# sudo cp /etc/fstab /etc/fstab.bakroot@hcss-ecs-0abe:~/calibre-web-docker# cd ../root@hcss-ecs-0abe:~# lscalibre-web-docker csv_chat EasyRSA-3.1.2.tgz HSSInstall install.sh my_file.txt myfile.txt openvpn simple_share snaproot@hcss-ecs-0abe:~# cd ../root@hcss-ecs-0abe:/# lsbin CloudrResetPwdAgent data etc lib lib64 lost+found mnt patch root sbin srv sys usr wwwboot credentials dev home lib32 libx32 media opt proc run snap swapfile tmp varroot@hcss-ecs-0abe:/# echo \'/swapfile none swap sw 0 0\' | sudo tee -a /etc/fstab/swapfile none swap sw 0 0root@hcss-ecs-0abe:/# sudo swapon --showNAME TYPE SIZE USED PRIO/swapfile file 2G 0B -2
网络标签：

相关问题