Windows一键部署Calibre-Web：Docker Desktop实战指南

1. 项目概述：为什么在 Windows 上“一键部署” Calibre-Web 是个真需求

Calibre-Web 是一个基于 Web 的电子书管理前端，它不替代 Calibre 桌面软件，而是为 Calibre 的庞大数据库提供一个轻量、跨设备、可远程访问的阅读与管理界面。它本身不处理格式转换或元数据抓取，但能完美展示 Calibre 库中已有的所有书籍、封面、标签、评分和自定义字段，并支持在线阅读、下载、搜索、分类筛选，甚至通过插件集成 Telegram 通知或 OPDS 订阅。对拥有上千本电子书的家庭用户、小团队知识库管理员，或是想把 Kindle 同步内容集中管理的读者来说，它就是那个“看不见却离不开”的数字图书馆后台。

但问题来了：Calibre-Web 官方只提供 Python 源码，原生依赖 Flask、Whoosh、Pillow 等十多个 Python 包，还要求你手动配置 SQLite 数据库路径、静态文件权限、反向代理规则——这在 Linux 上尚可脚本化，在 Windows 上却极易踩坑。我见过太多人卡在pip install报错“Microsoft Visual C++ 14.0 is required”，或是在启动后发现封面图片全显示为红叉，又或者用浏览器访问http://localhost:8083时提示“Connection refused”。这些不是技术门槛高，而是 Windows 环境下路径分隔符（\vs/）、服务注册机制、防火墙默认策略、用户权限模型带来的“隐性摩擦”。

这时候，“一键部署”就不再是营销话术，而是真实生产力诉求。它意味着：你不需要知道什么是 WSL2，不需要手动编辑config.py，不需要查 Docker Desktop 启动失败的日志里那句 “virtualization support not detected”，更不需要为了一个 Web 服务去折腾 IIS 或 Apache。你双击一个.bat文件，等 90 秒，打开浏览器，输入地址，你的电子书库就活了。这个“一键”，背后是环境隔离、依赖固化、端口预检、权限自动提升、日志静默重定向等一系列工程细节的封装。而 Docker Desktop for Windows 正是目前最成熟、最贴近“开箱即用”体验的解决方案——它把 Linux 容器运行时封装成 Windows 用户能理解的图形界面，把docker-compose.yml变成可复用的部署蓝图。所以，当热搜词里反复出现 “docker安装”、“docker desktop安装教程”、“windows安装docker” 时，本质反映的是大量 Windows 用户正从“手动配置党”转向“容器交付党”，而 Calibre-Web，恰好是验证这条路径是否走通的绝佳试金石。

2. 整体设计思路：为什么选择 Docker Desktop + docker-compose 而非其他方案

2.1 排除 Python 原生部署：不是不行，而是不稳

直接在 Windows 上用python calibre-web.py启动，看似最“原教旨”。但实测下来，有三个硬伤无法绕过：

第一是Python 版本碎片化。Calibre-Web 官方明确要求 Python 3.7–3.11，但 Windows 用户电脑上可能同时装着 Python 3.9（用于数据分析）、Python 3.12（刚升级）、甚至 Anaconda 自带的 Python 3.8。pip install时若没激活正确虚拟环境，极易混入不兼容包。比如pywin32在 Python 3.12 下需特定版本，否则启动时报ImportError: DLL load failed；而Pillow编译时若找不到 VS Build Tools，就会退回到纯 Python 模式，导致封面缩略图生成极慢甚至失败。

第二是路径与权限的 Windows 特性陷阱。Calibre-Web 需要读写 Calibre 数据库（metadata.db）和书籍文件夹（含大量子目录）。Windows 默认对C:\Users\XXX\Documents\Calibre Library这类路径有严格的 ACL（访问控制列表），而 Python 进程若未以管理员身份运行，os.listdir()可能因权限不足跳过某些子目录，造成 Web 界面里“部分书籍消失”。更隐蔽的是长路径问题：当 Calibre 库路径超过 260 字符（如嵌套多层作者名+书名），Windows API 默认拒绝访问，必须手动启用LongPathsEnabled策略，而绝大多数用户根本不知道这个注册表键在哪。

第三是进程守护与开机自启的缺失。原生 Python 进程一旦关闭命令行窗口就终止。想实现开机自启，得写 Windows Service（需 pywin32）、或用 Task Scheduler（配置复杂且日志难查）、或依赖第三方工具（如 NSSM）。每种方案都增加维护成本，且任一环节出错，服务就“静默死亡”，用户第二天打开电脑才发现书库打不开。

提示：我曾帮一位高校图书馆老师部署，他坚持用原生 Python，结果两周内三次因 Windows 更新重置了防火墙规则，导致localhost:8083被拦截，每次都要手动进“高级安全 Windows 防火墙”里添加入站规则——这种运维负担，对非 IT 人员就是灾难。

2.2 排除 WSL2 手动部署：太重，偏离“一键”初心

WSL2 确实能跑 Linux 原生环境，理论上比 Docker Desktop 更底层、更高效。但“一键”的核心是降低认知负荷，而 WSL2 要求用户先启用 Windows 功能（dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart），再下载发行版（Ubuntu），再配置sudo apt update && sudo apt install python3-pip，再处理 WSL2 与 Windows 主机的网络互通（/etc/resolv.conf动态覆盖问题）、再解决 Windows 文件系统挂载点的权限映射（/mnt/c/下的文件 UID/GID 映射异常）。光是让localhost:8083在 Windows 浏览器里能访问，就要查至少三篇微软文档。这已经不是“部署 Calibre-Web”，而是在部署一个微型 Linux 运维工程师。

更重要的是，WSL2 的资源占用（默认分配 50% 内存）对普通办公本不友好。我测试过一台 16GB 内存的 ThinkPad，开启 WSL2 后 Chrome 多开几个标签页就频繁触发内存压缩，风扇狂转。而 Docker Desktop 的资源限制是精细可控的：你可以在设置里明确指定容器最多使用 2GB 内存、2 个 CPU 核心，且空闲时自动释放，这对长期运行的服务更友好。

2.3 Docker Desktop + docker-compose：平衡稳定性、隔离性与易用性的最优解

Docker Desktop for Windows 的价值，在于它把复杂的 Linux 容器技术，翻译成了 Windows 用户熟悉的语言：

• 环境隔离：容器内运行的是精简的 Alpine Linux + Python 3.11 环境，与宿主机完全隔离。Calibre-Web 所需的flask==2.3.3、whoosh==2.7.4等包版本被固化在镜像里，不会与你电脑上其他 Python 项目冲突。哪怕你明天卸载了 Anaconda，Calibre-Web 依然纹丝不动。

• 依赖固化：我们使用的linuxserver/calibre-web镜像是社区维护的成熟镜像，已预编译好Pillow的加速模块（libjpeg-turbo、libpng），封面生成速度比 Windows 原生快 3 倍以上。镜像还内置了s6-overlay进程管理器，能优雅处理 SIGTERM 信号，确保数据库写入完成后再退出，避免metadata.db损坏。

• 一键可复现：整个部署逻辑被浓缩为一个docker-compose.yml文件。它声明了服务（calibre-web）、端口映射（8083:8083）、卷挂载（./calibre-data:/books）、环境变量（PUID=1000,PGID=1000）。用户只需修改两处路径，双击start.bat，后续所有操作（拉取镜像、创建网络、启动容器）均由 Docker 引擎自动完成。没有“下一步该敲什么命令”的困惑，只有进度条和最终的绿色Started提示。

• 生态兼容性：Docker Desktop 已深度集成 Windows Terminal、WSL2（可选）、以及 Hyper-V/WSL2 两种后端。当你看到热搜词里反复出现 “docker desktop”、“docker desktop安装教程”、“docker desktop使用教程”，说明它已成为 Windows 容器事实标准。选择它，就是选择最大公约数，降低用户首次接触的挫败感。

3. 核心细节解析：从零开始构建可落地的部署包

3.1 基础环境检查清单：5 分钟确认你的 Windows 是否 ready

在下载任何东西前，请务必花 5 分钟执行以下检查。跳过这步，90% 的部署失败都源于此。

第一步：确认 Windows 版本与架构
按Win+R输入winver，查看系统版本。Calibre-Web 容器要求：

• Windows 10 2004（Build 19041）或更高版本
• Windows 11 全版本支持
• 必须是 64 位系统（32 位 Windows 不支持 WSL2，故 Docker Desktop 也无法运行）

注意：如果你用的是 Windows Server，需额外启用“Containers”功能（Install-WindowsFeature Containers），但本教程默认面向桌面版用户。

第二步：验证硬件虚拟化是否启用
这是 Docker Desktop 启动失败最常见的原因，错误提示常为 “virtualization support not detected” 或 “Docker Desktop failed to start because v...”。请按以下顺序排查：

1. 重启电脑，进入 BIOS/UEFI（通常开机时狂按F2、Del或Esc，具体键位看主板品牌）
2. 找到Advanced→CPU Configuration或Security→System Security类似菜单
3. 将Intel Virtualization Technology (VT-x)或AMD-V设置为Enabled
4. 同时确认Hyper-V或Windows Hypervisor Platform (WHPX)已开启（Docker Desktop 依赖此）

验证是否成功：以管理员身份打开 PowerShell，执行：

systeminfo | find "Hyper-V Requirements"

若输出中包含Virtualization Enabled In Firmware: Yes和Hyper-V Requirements: A hypervisor has been detected. Features required for Hyper-V will not be displayed.，则通过。

第三步：检查 Windows 功能是否就绪
以管理员身份运行 PowerShell，逐条执行：

# 启用 WSL2（Docker Desktop 依赖） dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 重启电脑！这一步不可跳过

重启后，再执行：

# 设置 WSL2 为默认版本 wsl --set-default-version 2 # 检查是否安装了任意 Linux 发行版（Docker Desktop 不需要，但此命令可验证 WSL2 状态） wsl -l -v

若返回Windows Subsystem for Linux has no installed distributions，属正常，Docker Desktop 会自行管理。

第四步：确认磁盘空间与防病毒软件

• 预留至少 5GB 空闲空间（Docker Desktop 安装包约 120MB，linuxserver/calibre-web镜像约 350MB，Calibre 数据库随书籍增长）
• 临时禁用第三方杀毒软件（如 360、腾讯电脑管家）。它们常将 Docker 的com.docker.backend.exe误判为挖矿程序并拦截，导致桌面图标灰色、无法启动。

3.2 Docker Desktop 安装与初始配置：避开那些“默认就错”的坑

Docker Desktop 官网下载地址是https://www.docker.com/products/docker-desktop/，但国内用户常因网络问题卡在下载。这里提供两个可靠备选：

• 阿里云镜像源（推荐）：访问https://mirrors.aliyun.com/docker-ce/windows/stable/，下载最新Docker Desktop Installer.exe
• 清华大学镜像源：访问https://mirrors.tuna.tsinghua.edu.cn/docker-ce/windows/stable/

安装过程看似简单，但有三个关键选项必须手动干预：

安装向导第 3 步：“Choose your backend”
你会看到两个单选框：

• ☑ Use the WSL 2 based engine（默认勾选）
• □ Use the Hyper-V backend

务必保持默认勾选 WSL2。Hyper-V 在 Windows 10 家庭版中不可用，且 WSL2 性能更优、资源占用更低。若你勾选了 Hyper-V 却系统不支持，安装会失败并弹出晦涩错误。

安装向导第 4 步：“Configure advanced settings”
点击右下角Advanced按钮，重点修改两项：

• Disk image size：默认 64GB 过大。普通用户设为32768（即 32GB）足够，既保证镜像存储空间，又不浪费 SSD。
• Use the WSL2 based engine：再次确认此选项已启用。

安装完成后的首次启动配置
首次启动 Docker Desktop 会弹出向导，此时注意：

• ✅ 勾选Start Docker Desktop when you log in（开机自启，确保服务常驻）
• ✅ 勾选Use the new virtualization framework on macOS（此选项 Windows 上灰显，忽略）
• ❌取消勾选Enable cloud experience（云体验）。它会尝试连接 Docker Hub，国内网络常超时，导致桌面图标长时间转圈，误以为启动失败。

实操心得：我曾帮一位同事安装，他没取消云体验，等了 12 分钟无响应，以为软件坏了就强制结束进程，结果 Docker Desktop 的后台服务com.docker.backend.exe残留在内存里，后续再启动始终报错。正确做法是：若等待超 2 分钟无反应，右键任务栏 Docker 图标 →Troubleshoot→Clean / Purge data，再重启。

3.3 构建专属部署包：docker-compose.yml与启动脚本的深度定制

真正的“一键”，不在于 Docker Desktop 是否安装成功，而在于用户拿到手的部署包是否开箱即用。我们构建一个包含 4 个文件的最小可行包：

calibre-web-win/ ├── docker-compose.yml # 核心编排文件 ├── start.bat # 一键启动脚本 ├── stop.bat # 一键停止脚本 └── calibre-data/ # 用户存放 Calibre 库的文件夹（空目录）

docker-compose.yml文件详解（逐行注释）

version: "3.8" # 使用 Compose v3.8 规范，兼容 Docker Desktop 4.0+ services: calibre-web: image: linuxserver/calibre-web:latest # 使用官方维护的稳定镜像 container_name: calibre-web # 容器名称，便于 docker ps 查看 environment: - PUID=1000 # 容器内进程 UID，映射到 Windows 当前用户 - PGID=1000 # 容器内进程 GID，同上 - TZ=Asia/Shanghai # 时区，避免日志时间错乱 volumes: - ./calibre-data:/books:ro # 关键！将本地 calibre-data 目录只读挂载为 /books - ./calibre-config:/config:rw # 新增：独立挂载配置目录，避免配置随镜像更新丢失 ports: - "8083:8083" # 宿主机 8083 → 容器 8083，Calibre-Web 默认端口 restart: unless-stopped # 容器异常退出时自动重启，确保服务永驻 networks: - calibre-net # 自定义网络，避免与其他容器端口冲突 networks: calibre-net: driver: bridge # 使用桥接网络，最稳定

为什么./calibre-data:/books:ro必须是只读（ro）？
这是安全红线。Calibre-Web 作为 Web 前端，只应读取Calibre 数据库和书籍文件，绝不应修改它们。若设为读写（rw），一旦 Web 界面被恶意利用（如 XSS 攻击），攻击者可能通过文件上传功能写入恶意脚本到书籍目录。只读挂载后，容器内任何touch /books/test.txt操作都会返回Permission denied，从根源杜绝风险。

为什么新增./calibre-config:/config:rw卷？
linuxserver/calibre-web镜像将所有配置（app.db、gunicorn.conf.py、log目录）默认存在容器内/config路径。若不挂载，每次docker-compose down后，所有自定义设置（如管理员密码、主题偏好、OPDS 配置）都会丢失。挂载后，配置永久保存在 Windows 本地calibre-config文件夹，升级镜像只需docker-compose pull && docker-compose up -d，配置毫发无损。

start.bat脚本：让 Windows 用户真正“双击即用”

@echo off :: Calibre-Web Windows 一键部署启动脚本 :: 作者：资深电子书运维工程师 :: 功能：自动检测环境、拉取镜像、启动服务、输出访问地址 echo ======================================== echo 正在启动 Calibre-Web 服务... echo ======================================== :: 第一步：检查 Docker Desktop 是否运行 tasklist /fi "imagename eq com.docker.backend.exe" 2>nul | find /i "com.docker.backend.exe" >nul if %errorlevel% neq 0 ( echo [错误] Docker Desktop 未运行！请先启动 Docker Desktop。 echo 按任意键退出... pause >nul exit /b 1 ) :: 第二步：检查当前目录是否存在 docker-compose.yml if not exist "docker-compose.yml" ( echo [错误] 未找到 docker-compose.yml 文件！请确认脚本位于部署包根目录。 echo 按任意键退出... pause >nul exit /b 1 ) :: 第三步：拉取最新镜像（仅当本地不存在或过期时） echo [步骤1/3] 正在拉取 Calibre-Web 镜像... docker-compose pull >nul 2>&1 if %errorlevel% neq 0 ( echo [警告] 镜像拉取失败，尝试使用国内镜像源... :: 临时配置 Docker Daemon 使用阿里云镜像加速器 mkdir "%USERPROFILE%\.docker" 2>nul echo {"registry-mirrors": ["https://u1j4p1zr.mirror.aliyuncs.com"]} > "%USERPROFILE%\.docker\daemon.json" echo 镜像源已切换至阿里云，正在重试... docker-compose pull >nul 2>&1 ) :: 第四步：启动服务 echo [步骤2/3] 正在启动 Calibre-Web 容器... docker-compose up -d >nul 2>&1 if %errorlevel% neq 0 ( echo [错误] 容器启动失败！请检查 docker-compose.yml 格式或端口占用。 echo 常见原因：8083 端口被其他程序（如 Skype）占用。 echo 按任意键查看详细日志... pause >nul docker-compose logs --tail=20 exit /b 1 ) :: 第五步：等待服务就绪并输出访问地址 echo [步骤3/3] 正在等待服务就绪... timeout /t 15 >nul :: 检查容器状态 for /f "tokens=2 delims=," %%a in ('docker-compose ps --format "{{.Status}}" 2^>nul') do set "status=%%a" if "%status%"=="Up" ( echo. echo ✅ 启动成功！ echo ======================================== echo 访问地址：http://localhost:8083 echo 默认管理员账号：admin echo 默认管理员密码：admin123 echo ======================================== echo 提示：首次访问会自动跳转到初始化向导，请按提示设置管理员密码。 echo 按任意键在浏览器中打开... pause >nul start "" "http://localhost:8083" ) else ( echo [错误] 容器状态异常！请运行 'docker-compose logs' 查看详情。 pause >nul )

脚本设计的巧思：

• 智能镜像源切换：当docker-compose pull失败时，脚本自动向%USERPROFILE%\.docker\daemon.json写入阿里云镜像地址。这是 Docker Desktop 的标准配置方式，无需用户手动编辑 JSON，且只影响当前部署，不影响其他 Docker 项目。
• 端口占用预检：虽未在脚本中显式检查 8083 端口，但docker-compose up -d若失败，日志会明确提示Bind for 0.0.0.0:8083 failed: port is already allocated。脚本捕获此错误并引导用户排查（Skype 默认占 8083，是 Windows 用户最高频冲突）。
• 人性化交互：pause >nul隐藏“Press any key...”文字，只保留等待效果；start "" "http://localhost:8083"直接调用默认浏览器，省去用户手动输入 URL 的步骤。

stop.bat脚本：优雅停机，不伤数据

@echo off echo ======================================== echo 正在停止 Calibre-Web 服务... echo ======================================== if not exist "docker-compose.yml" ( echo [错误] 未找到 docker-compose.yml 文件！ pause >nul exit /b 1 ) docker-compose down >nul 2>&1 if %errorlevel% equ 0 ( echo ✅ 已停止服务。容器与网络已清理。 echo 提示：Calibre 数据库与配置文件已安全保存在本地。 ) else ( echo [错误] 停止失败，请检查 Docker Desktop 状态。 ) pause >nul

4. 实操过程与核心环节实现：从下载到访问的完整 walkthrough

4.1 下载与解压：获取部署包的三种可靠途径

途径一：GitHub Release（推荐，版本可控）
访问https://github.com/linuxserver/docker-calibre-web/releases，找到最新Assets中的calibre-web-windows-deploy.zip（此为社区打包的 Windows 专用版）。下载后解压到任意位置，如D:\calibre-web。此包已预置docker-compose.yml、start.bat、stop.bat及空calibre-data目录，开箱即用。

途径二：Gitee 镜像（国内加速）
若 GitHub 访问缓慢，可访问https://gitee.com/mirrors/linuxserver-docker-calibre-web，点击克隆/下载→下载ZIP。Gitee 镜像同步频率高，通常延迟小于 1 小时。

途径三：手动创建（适合学习原理）
若你想完全掌控每个字节，按以下步骤手动生成：

1. 新建文件夹D:\calibre-web
2. 用记事本创建docker-compose.yml，粘贴上文 3.3 节内容
3. 创建start.bat和stop.bat，粘贴对应脚本
4. 创建空文件夹calibre-data和calibre-config

注意：所有文件必须保存为UTF-8 无 BOM 编码。若用 Windows 记事本保存，选择“另存为” → 编码选“UTF-8”，不要选“UTF-8-BOM”，否则docker-compose.yml解析会失败，报错Invalid indentation。

4.2 准备 Calibre 数据库：让 Web 界面有“书”可管

Calibre-Web 本身不管理书籍，它只是 Calibre 桌面软件的“眼睛”。因此，你必须先有一个合法的 Calibre 库。有两种主流方式：

方式一：复用现有 Calibre 库（最常用）

1. 打开 Calibre 桌面软件，确认你的库路径。默认在C:\Users\<用户名>\Documents\Calibre Library
2. 将整个Calibre Library文件夹复制（不是剪切！）到D:\calibre-web\calibre-data\目录下
3. 此时D:\calibre-web\calibre-data\内应有metadata.db文件和cover_cache、author等子目录

提示：复制而非移动，是为了保留原始库的完整性。万一 Web 部署出问题，你仍可双击 Calibre 桌面软件继续使用。

方式二：新建空白库（适合首次尝试）

1. 在D:\calibre-web\calibre-data\内新建文件夹，命名为MyLibrary
2. 启动 Calibre 桌面软件 →文件→切换/新建库→新建库→ 选择D:\calibre-web\calibre-data\MyLibrary
3. Calibre 会自动生成metadata.db和必要结构。你可以稍后通过 Calibre 添加几本书测试。

关键校验步骤：
在D:\calibre-web\calibre-data\目录下，必须存在metadata.db文件，且其大小不为 0。右键 →属性→ 查看“大小”应大于 1KB（新库约 20KB，千本书库约 5–10MB）。若metadata.db为空或损坏，Calibre-Web 启动后会报错No such file or directory: 'metadata.db'，界面显示“Database not found”。

4.3 执行一键启动：见证从零到访问的 90 秒

现在，一切就绪。请严格按此顺序操作：

步骤 1：以管理员身份运行start.bat

• 右键start.bat→以管理员身份运行
• 为什么必须管理员？因为脚本需调用docker-compose命令，而 Docker Desktop 的 CLI 工具在非管理员模式下可能权限不足，尤其涉及网络配置时。

步骤 2：观察控制台输出（典型流程）

======================================== 正在启动 Calibre-Web 服务... ======================================== [步骤1/3] 正在拉取 Calibre-Web 镜像... [步骤2/3] 正在启动 Calibre-Web 容器... [步骤3/3] 正在等待服务就绪... ✅ 启动成功！ ======================================= 访问地址：http://localhost:8083 默认管理员账号：admin 默认管理员密码：admin123 ======================================= 提示：首次访问会自动跳转到初始化向导... 按任意键在浏览器中打开...

整个过程约 60–90 秒。若卡在某一步超过 2 分钟，请按Ctrl+C中断，根据提示排查。

步骤 3：浏览器访问与初始化

• 按任意键，浏览器自动打开http://localhost:8083
• 首次访问会跳转到/login页面，显示“Welcome to Calibre-Web Setup Wizard”
• 输入默认账号admin/ 密码admin123，点击Login
• 进入向导页，关键设置：
  • Calibre library path: 填写/books（容器内路径，不是 Windows 路径！）
  • Database path: 保持默认metadata.db（自动识别）
  • Admin password:必须修改！输入新密码并确认，这是你今后登录的唯一凭证
  • Allow remote access: 勾选（允许局域网内其他设备访问，如手机、平板）
• 点击Save & Continue，页面跳转至主界面，左上角显示Calibre-WebLogo，右上角显示管理员用户名。

步骤 4：验证核心功能

• 在搜索框输入任意书名，应实时返回结果
• 点击一本书，右侧应显示封面、元数据、阅读按钮
• 点击阅读，应在新标签页打开 PDF/EPUB 在线阅读器（基于pdf.js或epub.js）
• 点击左上角Settings→Server Settings，确认Port显示8083，Host显示0.0.0.0（表示监听所有网卡）

实操心得：我第一次部署时，封面全显示红叉。排查发现是calibre-data文件夹的 Windows 权限问题：右键 →属性→安全→编辑→ 为Users组添加读取与执行、列出文件夹内容、读取权限。容器内进程以 UID 1000 运行，对应 Windows 的Users组。此细节官网文档从不提及，却是 Windows 用户最高频的“隐形坑”。

4.4 进阶配置：让 Calibre-Web 更安全、更顺手

配置反向代理（可选，但强烈推荐）

localhost:8083对个人使用足够，但若你想用https://mybooks.local这样的域名访问，或启用 HTTPS 加密，则需反向代理。Windows 下最轻量的方案是Caddy：

1. 下载 Caddy for Windows：https://caddyserver.com/download，选择Windows 64-bit
2. 解压后，创建Caddyfile（无后缀），内容如下：

   mybooks.local { reverse_proxy localhost:8083 tls internal }

3. 以管理员身份运行caddy run
4. 在 Windowshosts文件（C:\Windows\System32\drivers\etc\hosts）末尾添加：

   127.0.0.1 mybooks.local

5. 浏览器访问https://mybooks.local，Caddy 会自动签发 HTTPS 证书。

启用 OPDS 订阅（让 Kindle/Apple Books 直接同步）

Calibre-Web 内置 OPDS 2.0 支持，可让 Kindle 设备通过“导入 RSS”功能订阅你的书库：

1. 在 Calibre-Web 界面 →Settings→OPDS Settings
2. 勾选Enable OPDS feed
3. OPDS URL填写http://<你的电脑IP>:8083/opds（如http://192.168.1.100:8083/opds）
4. 点击Save
5. 在 Kindle 上：设置→Sync & Wireless→Import RSS→ 输入上述 URL

注意：Kindle 必须与你的 Windows 电脑在同一局域网，且 Windows 防火墙需放行 8083 端口（Windows Defender 防火墙→高级设置→入站规则→ 新建规则 → 端口 → TCP 8083 → 允许连接）。

5. 常见问题与排查技巧实录：那些论坛里搜不到的独家经验

5.1 启动失败：docker-compose up报错汇总与速查

5.2 访问异常：浏览器打不开或功能失效的深层排查