Apache CouchDB 3.5.3 介绍与选型指南

目标：基于 Apache CouchDB 官网、官方文档站与 GitHub 仓库联网溯源（查询日期 2026-10-18），介绍 Apache CouchDB 3.5.3 的定位、存储与同步架构、官方 HTTP API 交互示例与同类选型对比，帮助读者在文档型数据库选型中判断其适用性。

一、信息基准

本章为全文信息基准：所有版本号、发布时间、能力描述均来自下列官方来源，查询日期统一为 2026-10-18。

1.1 查询日期与版本依据

1.2 官方来源清单

• 官网与下载页：https://couchdb.apache.org/ 、https://couchdb.apache.org/downloads.html
• 官方文档（stable）：https://docs.couchdb.org/en/stable/
• 版本说明（3.5.x）：https://docs.couchdb.org/en/stable/whatsnew/3.5.html
• HTTP API 参考：https://docs.couchdb.org/en/stable/api/
• 复制协议：https://docs.couchdb.org/en/stable/replication/protocol.html
• GitHub 只读副本：https://github.com/apache/couchdb

二、软件概述

Apache CouchDB 3.5.3（2026-10-12 发布，Apache License 2.0）是用 Erlang/OTP 实现的文档型 NoSQL 数据库，官网定位四大卖点：可从大数据集平滑扩展到移动端的多主复制（multi-primary sync）、直观的 HTTP/JSON API、为可靠性而设计（来源：官网首页，2026-10-18）。数据以 JSON 文档存储，通过 RESTful HTTP 接口读写，天然适合 Web 应用与离线优先（offline-first）架构——Couch Replication Protocol 被服务器集群、手机与浏览器端的多类项目实现，数据可在其间无缝同步（来源：官网首页与复制协议文档，2026-10-18）。

查询能力上，CouchDB 提供官方描述为"开发者友好的查询语言"（Mango 查询，类 MongoDB 风格的选择器语法），并可选 MapReduce 视图做高效聚合检索（来源：官网首页 "developer-friendly query language, and optionally MapReduce"，2026-10-18）。管理界面 Fauxton 随服务内置。GitHub apache/couchdb 约 7k stars，最近推送 2026-10-17（来源：GitHub API/shields.io，2026-10-18 实查），是 Apache 旗下成熟度最高的数据库项目之一。

三、核心架构

3.1 存储模型

• 文档（Document）：以 JSON 表示，含唯一 _id 与修订号 _rev；每次修改产生新修订版本（MVCC），杜绝原地覆盖；
• 只追加 B-tree：数据文件采用只追加（append-only）写法与写时复制的 B-tree 结构，崩溃后无需恢复日志即可保证一致性，配合周期性压缩（compaction）回收空间（来源：官方文档 storage 相关章节的长期设计描述，2026-10-18）；
• 分片与集群：集群模式下数据库被切分为分片（shard）分布到多节点，节点间经 Erlang 集群互联，请求由前端协调层聚合（来源：官方文档 cluster 章节）。

3.2 查询与同步组件

（来源：docs.couchdb.org/en/stable/ 与 whatsnew/3.5.html，2026-10-18）

3.3 3.5.x 系列关键演进（官方 whatsnew 摘录）

• 并行读（3.5.0）：存储引擎层实现并行 pread（couch_cfile），读不再被写与 fsync 阻塞——官方给出的初步提升为随机文档读吞吐 +15%、_all_docs +15%、_all_docs（含 include_docs）+25%；
• QuickJS 与 B-tree 缓存优化（3.5.x）：视图/库文件的 BTree term cache、hibernate_after 空闲超时等配置项新增；
• 3.5.3（2026-10-12）：_bulk_docs 热路径二次扫描修复、变更序列解码提速 2-3 倍、若干复制与压缩缺陷修复；Erlang/OTP 27 为最低要求。 （来源：https://docs.couchdb.org/en/stable/whatsnew/3.5.html，查询日期 2026-10-18）

四、功能特性

• 多主复制：任意节点可写，双向增量同步，冲突以"多版本+确定性胜者"方式保留，不丢数据（官方复制文档）；
• HTTP/JSON 原生 API：无需驱动即可用任何 HTTP 客户端操作库、文档、视图、复制；
• 离线优先生态：Couch Replication Protocol 被 PouchDB 等浏览器/移动端实现，实现端云同构同步；
• MVCC 与最终一致：修订号乐观并发控制，适合高并发写冲突少、要求可用性的场景；
• 声明式 + 视图双查询：Mango 查询开箱即用，MapReduce 视图承担聚合与复杂键检索；
• 内建安全：管理员账户、按库的成员/角色访问控制（_security 对象）、Cookie/JWT 认证（3.5.3 改进 JWT 错误信息）；
• 可靠性与运维：只追加存储 + 压缩、增量视图维护、集群分片与内部代理（官方 cluster 文档）。 （来源：docs.couchdb.org/en/stable/ 各章节，2026-10-18）

五、快速上手

以下交互示例转写自官方文档 HTTP API 参考（未做本地运行；来源：https://docs.couchdb.org/en/stable/api/，查询日期 2026-10-18）。

5.1 创建库与写入文档

# 创建数据库（管理员口令按实际环境替换）
curl -X PUT http://admin:password@127.0.0.1:5984/mydb
# 官方示例响应：{"ok":true}

# 新建文档（指定 _id）
curl -X PUT http://admin:password@127.0.0.1:5984/mydb/doc1 \
     -H 'Content-Type: application/json' \
     -d '{"lang":"erlang","tags":["nosql","sync"]}'
# 响应含 {"id":"doc1","ok":true,"rev":"1-xxx"}

# 批量写入
curl -X POST http://admin:password@127.0.0.1:5984/mydb/_bulk_docs \
     -H 'Content-Type: application/json' \
     -d '{"docs":[{"_id":"a"},{"_id":"b"}]}'

5.2 读取与查询

# 读取文档（响应含 _id/_rev）
curl http://admin:password@127.0.0.1:5984/mydb/doc1

# Mango 查询
curl -X POST http://admin:password@127.0.0.1:5984/mydb/_find \
     -H 'Content-Type: application/json' \
     -d '{"selector":{"tags":{"$elemMatch":"nosql"}},"fields":["_id","lang"]}'

# 订阅变更流
curl http://admin:password@127.0.0.1:5984/mydb/_changes?since=now

5.3 复制

# 触发一次性复制（官方 _replicate 端点）
curl -X POST http://admin:password@127.0.0.1:5984/_replicate \
     -H 'Content-Type: application/json' \
     -d '{"source":"mydb","target":"http://other:5984/mydb","continuous":true}'

💡 说明：持久化复制建议使用 _replicator 系统库创建复制文档（带 continuous: true），由内置复制管理器托管——用法见官方文档 replicate 章节。

六、适用场景与限制

适用场景

• 离线优先/弱网应用：移动端或浏览器（PouchDB 等）本地库与服务端 CouchDB 长期双向同步；
• 多活/多地域写入：各节点可写、异步复制的多主拓扑；
• 文档模型 + 中等查询复杂度：内容管理、用户画像存储、设备影子等 JSON 主体数据；
• 以 HTTP 为唯一总线的轻量技术栈（无驱动依赖）。

限制与注意

• 无跨文档事务与 JOIN；关联数据需内嵌或多次查询；
• 即席分析、大规模聚合并非其强项（官方定位为文档同步与检索，不是分析型引擎）；
• 修订与冲突语义需要应用层理解（_rev 必读），照搬关系型思维会踩坑；
• 二进制大对象虽支持附件（standalone attachments），超大文件存储与流式场景需评估；
• 3.5.3 起要求 Erlang/OTP 27+（编译自源码时），发行版包管理器自带运行时则无感。

七、同类选型对比

7.1 对比表

对比对象选取 PouchDB（同协议浏览器/移动端库）、MongoDB（文档库事实标准）与 RethinkDB（同为文档型实时库）；数据查询日期 2026-10-18。

（stars 与推送时间来源：GitHub API / shields.io，2026-10-18；版本来源：官网下载页、npm registry、endoflife.date 与 GitHub Releases，2026-10-18 实查）

7.2 选型建议

一句话选型：需要端到端离线同步、多主复制或纯 HTTP 数据面的文档库选 CouchDB 3.5.3（配 PouchDB 可覆盖移动/浏览器端）；通用文档库首选仍是 MongoDB（生态与聚合能力最强，注意 SSPL 许可对自管服务的影响）；RethinkDB 因长期无新版本不建议新项目采用；若只做浏览器端本地持久化并与 CouchDB 同步，PouchDB 是官方生态内的既定搭档。

八、参考链接

1. 官网首页：https://couchdb.apache.org/
2. 下载页：https://couchdb.apache.org/downloads.html
3. 官方文档：https://docs.couchdb.org/en/stable/
4. 3.5.x 版本说明：https://docs.couchdb.org/en/stable/whatsnew/3.5.html
5. HTTP API 参考：https://docs.couchdb.org/en/stable/api/
6. Couch Replication Protocol：https://docs.couchdb.org/en/stable/replication/protocol.html
7. GitHub 只读副本：https://github.com/apache/couchdb
8. Apache PouchDB：https://pouchdb.apache.org/