BookDock：轻量级本地豆瓣书单同步工具

1. BookDock 是什么：一个轻量级个人图书管理服务的诞生逻辑

BookDock 这个名字乍一听像某个科技公司的新品发布会，但其实它背后没有融资故事、没有KPI压力，只有一个很朴素的需求：把豆瓣读书标记过的书单，从网页端“搬”进本地，变成可离线查询、可自由导出、可长期归档的私人知识资产。我第一次意识到这个问题，是在某次出差途中想翻看自己三年前标记的“想读”书单，结果发现豆瓣API早已限流，网页加载缓慢，且无法按出版年份、标签、评分区间做组合筛选——更别提导出为 Excel 或 Markdown 了。这时候我才真正理解：我们标记的不是书，而是时间、兴趣和认知轨迹；而这些数据一旦被锁死在第三方平台，就等于把人生阅读史的原始凭证交了出去。

BookDock 就是为此而生的。它不是一个替代豆瓣的社交读书平台，而是一个极简的、专注“数据主权”的本地化服务层。核心能力只有三件事：

• 自动同步：通过 DOUBAN_COOKIE（即你在豆瓣网站登录后浏览器生成的身份凭证）定时拉取你的“在读”“想读”“读过”书单；
• 本地持久化：所有数据落地为一个标准 SQLite 数据库文件（bookdock.db），不依赖网络、不依赖云服务、不依赖任何外部数据库引擎；
• 开箱即用的交互界面：提供基于 Web 的轻量前端（React + Vite 构建），无需 Node.js 环境本地运行，所有静态资源打包进 Docker 镜像，启动即访问 http://localhost:3000。

你可能会问：为什么不用现成的豆瓣导出工具？为什么非得上 Docker？为什么选 SQLite 而不是 MySQL 或 PostgreSQL？这些问题恰恰是 BookDock 设计决策的锚点。它不是为了炫技，而是为了解决三个真实痛点：
第一，环境隔离性——我不想在本机 Python 环境里装一堆豆瓣爬虫依赖，更不想让 requests、beautifulsoup4 和我正在开发的项目产生版本冲突；
第二，部署确定性——今天在 macOS 上跑通的脚本，下周换到 Ubuntu 服务器上可能因 OpenSSL 版本差异直接报错，而 Docker 镜像把操作系统、Python 解释器、依赖包、甚至时区都固化下来；
第三，数据可验证性——SQLite 是单文件数据库，你可以随时用 DB Browser for SQLite 打开 bookdock.db，执行 SELECT * FROM books WHERE rating > 8.5 AND tags LIKE '%科幻%'，亲眼看到每一行数据从哪来、结构长什么样、有没有脏数据。这不是黑盒 API，这是你握在手里的数据库。

所以 BookDock 的本质，是一个“反云原生”的本地化实践：它拥抱容器化部署的确定性，却拒绝把数据上传到任何远程服务；它利用现代 DevOps 工具链，服务的却是最古典的数据主权理念——你的阅读记录，理应像你的纸质藏书一样，物理地、确定地、可触摸地存在于你自己的设备上。

提示：BookDock 不抓取图书详情页的全文内容，不保存封面图片二进制数据（只存 URL），不采集你的搜索行为或点击流。它的数据边界非常清晰：仅限你主动标记的书单元数据（书名、作者、ISBN、豆瓣 ID、评分、短评、标签、标记时间）。这既是技术约束，也是设计哲学。

2. 安装前必须厘清的四个底层依赖关系

很多人看到 “Docker 安装教程” 就直接复制粘贴 curl -fsSL https://get.docker.com | sh，结果在 Windows 上卡在 “virtualization support not detected”，在 macOS 上遇到 “Docker Desktop requires Intel chip” 报错，在 Ubuntu 上因为内核版本太旧而无法启动 dockerd。这些都不是 BookDock 的问题，而是你跳过了对底层依赖关系的理解。安装 BookDock 前，请务必花 5 分钟确认以下四组依赖是否闭环：

2.1 Docker Engine 与操作系统的绑定逻辑

Docker 不是一个独立软件，而是一套运行时栈，其核心组件 dockerd（Docker Daemon）必须直接与 Linux 内核的 cgroups 和 namespaces 机制交互。这意味着：

• Linux 发行版（Ubuntu/CentOS/Debian）：可直接安装 docker-ce 包，dockerd 作为系统服务运行，权限模型清晰；
• macOS：无法原生运行 Linux 容器，Docker Desktop 实际是启动一个轻量级 Linux 虚拟机（HyperKit），再在其中运行 dockerd，因此对 CPU 虚拟化支持（Intel VT-x / AMD-V）有硬性要求；
• Windows：情况最复杂。Windows 10/11 家庭版默认不支持 WSL2，而 Docker Desktop 2023 年后已强制要求 WSL2 后端。如果你用的是 Windows 10 Home 21H2（19044），即使开启 Hyper-V 也无法启动 Docker Desktop，必须升级到 22H2（19045）或改用 WSL2 手动安装方案。

验证方式很简单：打开终端，执行

如果返回 Command 'docker' not found，说明 Docker Engine 未安装；如果返回 Cannot connect to the Docker daemon，说明 dockerd 服务未运行；如果返回内核版本但显示 Operating System: Docker Desktop，恭喜你，你正在 macOS 或 Windows 的虚拟机环境中运行——这对 BookDock 完全兼容，无需额外处理。

2.2 Docker Compose 的版本演进陷阱

docker-compose.yml 是 BookDock 的部署蓝图，但很多人不知道：Docker Compose 在 2022 年经历了重大架构重构。旧版 docker-compose（Python 编写，命令为 docker-compose up）已被新版 docker compose（Go 编写，命令为 docker compose up，注意中间无横线）取代。两者配置文件语法基本兼容，但新版对 volumes 挂载路径解析更严格，尤其在 Windows 上处理 C:\Users\... 路径时容易出错。

BookDock 的 docker-compose.yml 明确要求使用 Compose V2。如果你的 docker --version 显示 Docker version 24.x，那么 docker compose 命令必然可用；但如果你还在用 docker-compose --version 显示 1.29.x，请立即升级：

• Linux/macOS：sudo curl -L "https://github.com/docker/compose/releases/download/v2.24.5/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose && sudo chmod +x /usr/local/bin/docker-compose
• Windows（WSL2）：在 WSL2 终端中执行同上命令，不要在 PowerShell 中执行，否则挂载路径会错乱。

注意：docker-compose.yml 文件中 volumes 字段的路径写法，必须与宿主机操作系统一致。例如在 WSL2 中，./data:/app/data 表示将当前目录下的 data 文件夹挂载到容器 /app/data；而在 Windows PowerShell 中，若你把项目放在 D:\bookdock，则必须写成 D:/bookdock/data:/app/data（用