CouchDB 3.5 常用命令与 HTTP API 详解

目标：系统演示 CouchDB 3.5 的使用方式。CouchDB 没有传统意义的数据库 CLI，一切操作都是 HTTP API（RESTful JSON），配套 Fauxton Web 界面。本文覆盖数据库/文档 CRUD、批量操作、Mango 查询、MapReduce 视图、变更流与复制，全部在 CouchDB 3.5.2 真实环境实测。部署见《CouchDB 3.5 Docker Compose 部署指南》。

一、环境信息

CouchDB：3.5.2（监听端口 15984）
管理员：admin / AppTest@2026
测试库：app_db（10 个文档，含中文）
客户端：curl（HTTP API 是 CouchDB 的唯一原生接口）

二、服务与认证

2.1 服务状态

# 欢迎页（无需认证）
curl -s http://127.0.0.1:15984/
# {"couchdb":"Welcome","version":"3.5.2",...}

# 健康检查（需认证）
curl -s -u admin:'AppTest@2026' http://127.0.0.1:15984/_up
# {"status":"ok","seeds":{}}

# 节点信息
curl -s -u admin:'AppTest@2026' http://127.0.0.1:15984/_membership

⚠️ 认证：CouchDB 使用 Basic Auth（-u user:pass）。密码含 @ 时必须单引号包裹（实测不包裹报 401）。URL 内嵌密码时 @ 编码为 %40。

2.2 创建管理员（首次/忘记密码场景）

curl -s -X PUT http://127.0.0.1:15984/_node/_local/_config/admins/admin \
  -d '"AppTest@2026"'
# 输出 "password" 表示已写入（存储为 PBKDF2 哈希）

三、数据库操作

3.1 创建 / 列表 / 删除

curl -s -u admin:'AppTest@2026' -X PUT http://127.0.0.1:15984/app_db   # 创建 → {"ok":true}
curl -s -u admin:'AppTest@2026' http://127.0.0.1:15984/_all_dbs         # 列表 → ["app_db"]
curl -s -u admin:'AppTest@2026' -X DELETE http://127.0.0.1:15984/app_db  # 删除

3.2 查看数据库信息（实测）

curl -s -u admin:'AppTest@2026' http://127.0.0.1:15984/app_db

实测输出关键字段：

{"db_name":"app_db","doc_count":10,"doc_del_count":0,"update_seq":"12-g1...","sizes":{...}}

字段	说明
doc_count	文档数
doc_del_count	已删除文档数（tombstone）
update_seq	变更序列号（用于增量同步）

四、文档 CRUD（核心）

4.1 创建文档

# 显式 _id
curl -s -u admin:'AppTest@2026' -X PUT http://127.0.0.1:15984/app_db/emp_1 \
  -H 'Content-Type: application/json' \
  -d '{"name":"员工1","dept":"技术部","salary":12000}'
# {"ok":true,"id":"emp_1","rev":"1-ede15b940342e460d1874ed3ff25e6e5"}

# 自动生成 _id
curl -s -u admin:'AppTest@2026' -X POST http://127.0.0.1:15984/app_db \
  -H 'Content-Type: application/json' -d '{"name":"员工9"}'

4.2 读取文档

curl -s -u admin:'AppTest@2026' http://127.0.0.1:15984/app_db/emp_1
# {"_id":"emp_1","_rev":"1-ede15b940342e460d1874ed3ff25e6e5","name":"员工1","dept":"技术部","salary":12000}

4.3 更新文档（MVCC，必须带 _rev）

# 错误示范（不带 _rev）→ 实测报 409：
# {"error":"conflict","reason":"Document update conflict."}

# 正确方式
REV=$(curl -s -u admin:'AppTest@2026' http://127.0.0.1:15984/app_db/emp_1 | jq -r ._rev)
curl -s -u admin:'AppTest@2026' -X PUT "http://127.0.0.1:15984/app_db/emp_1?rev=$REV" \
  -H 'Content-Type: application/json' \
  -d '{"name":"员工1改","dept":"技术部","salary":18000}'
# {"ok":true,"id":"emp_1","rev":"2-398fdca06bde8f1d15cdf1abc51a4617"}

4.4 删除文档（实测）

REV=$(curl -s -u admin:'AppTest@2026' http://127.0.0.1:15984/app_db/emp_5 | jq -r ._rev)
curl -s -u admin:'AppTest@2026' -X DELETE "http://127.0.0.1:15984/app_db/emp_5?rev=$REV"
# {"ok":true,"id":"emp_5","rev":"2-bbb71b46a62053298064d74f47b51c6c"}

💡 删除是逻辑删除：写入 tombstone 标记（doc_del_count +1），历史版本仍可访问，磁盘由后台压缩回收。

4.5 批量操作（_bulk_docs，实测）

curl -s -u admin:'AppTest@2026' -X POST http://127.0.0.1:15984/app_db/_bulk_docs \
  -H 'Content-Type: application/json' \
  -d '{"docs":[{"_id":"emp_7","name":"员工7","dept":"财务部","salary":25000},
               {"_id":"emp_8","name":"员工8","dept":"市场部","salary":28000}]}'

实测输出：

[{"ok":true,"id":"emp_7","rev":"1-23b914f6562fcbbbc72101ccf3c01b06"},
 {"ok":true,"id":"emp_8","rev":"1-db71f3df830a479c16b555fe618b2872"}]

五、查询（Mango / MapReduce 视图）

5.1 Mango 查询（_find，实测）

curl -s -u admin:'AppTest@2026' -X POST http://127.0.0.1:15984/app_db/_find \
  -H 'Content-Type: application/json' \
  -d '{"selector":{"dept":"技术部"},"fields":["name","salary"],"limit":3}'

实测输出：

{"docs":[
  {"name":"员工1改","salary":18000},
  {"name":"员工2","salary":14000},
  {"name":"员工3","salary":16000}],
 "bookmark":"g1AAAAA6...","warning":"No matching index found..."}

⚠️ 实测提示 No matching index found：查询会执行但性能差，应创建 Mango 索引。

5.2 创建 Mango 索引（实测）

curl -s -u admin:'AppTest@2026' -X POST http://127.0.0.1:15984/app_db/_index \
  -H 'Content-Type: application/json' \
  -d '{"index":{"fields":["dept","salary"]},"name":"dept_salary_idx","type":"json"}'
# {"result":"created","id":"_design/b3c9122f...","name":"dept_salary_idx"}

验证索引被使用（_explain 实测输出）：

{"index":{"ddoc":"_design/b3c9122f...","name":"dept_salary_idx","type":"json","def":{"fields":[{"dept":"asc"},{"salary":"asc"}]}}}

5.3 MapReduce 视图

创建设计文档（实测）：

curl -s -u admin:'AppTest@2026' -X PUT http://127.0.0.1:15984/app_db/_design/emp_views \
  -H 'Content-Type: application/json' \
  -d '{"views":{"by_dept":{"map":"function(doc){ if(doc.dept) emit(doc.dept, doc.salary); }"}}}'

查询视图：

curl -s -u admin:'AppTest@2026' 'http://127.0.0.1:15984/app_db/_design/emp_views/_view/by_dept'

实测输出（按 dept 键排序）：

{"total_rows":8,"offset":0,"rows":[
  {"id":"emp_6","key":"市场部","value":22000},
  {"id":"emp_8","key":"市场部","value":28000},
  {"id":"emp_1","key":"技术部","value":12000}, ...]}

⚠️ 实测踩坑：_temp_view（临时视图）在 CouchDB 3.x 已移除，报 {"error":"gone","reason":"Temporary views are not supported in CouchDB"}。MapReduce 必须写成设计文档。

六、变更流（_changes，实测）

curl -s -u admin:'AppTest@2026' 'http://127.0.0.1:15984/app_db/_changes?limit=3'

实测输出：

{"results":[
  {"seq":"2-g1AAAABteJz...","id":"emp_4","changes":[{"rev":"1-aa08a2bed60f2e00f613d61ac1df6917"}]},
  {"seq":"3-g1AAAACLeJz...","id":"emp_2","changes":[{"rev":"1-1d06a9942b25fb3e74c3e3c3f1a75c33"}]}],...}

💡 变更流是 CouchDB 数据同步/增量处理的核心机制：seq 为全局递增序号，include_docs=true 可携带文档内容，feed=continuous（HTTP 长连接）或 feed=eventsource 可实时推送。

七、复制（_replicate）

curl -s -u admin:'AppTest@2026' -X POST http://127.0.0.1:15984/_replicate \
  -H 'Content-Type: application/json' \
  -d '{"source":"app_db","target":"http://localhost:15984/backup_db","create_target":true}'

⚠️ 实测踩坑：在单节点上执行复制时，CouchDB 内部将目标主机名解析为 any:5984，报：
{"error":"replication_auth_error","reason":"{session_request_failed,\"http://any:5984/_session\",\"admin\",{conn_failed,{error,nxdomain}}}"}
生产环境推荐双实例（源/目标各一个服务）复制，或用 _all_docs 导出+_bulk_docs 导入方式备份。

八、密码与特殊字符处理

# curl -u 中密码含 @ 必须单引号
curl -s -u admin:'AppTest@2026' http://127.0.0.1:15984/_up

# URL 内嵌密码：@ → %40
curl -s 'http://admin:AppTest%402026@127.0.0.1:15984/_up'

# 环境变量方式
export COUCHDB_PASS='AppTest@2026'
curl -s -u "admin:$COUCHDB_PASS" http://127.0.0.1:15984/_up

九、Fauxton 管理界面

# 浏览器访问
# http://127.0.0.1:15984/_utils/

Fauxton 提供：数据库浏览、文档编辑、Mango 查询调试、配置查看、复制任务管理。

十、常见问题 FAQ

10.1 批量导入 _bulk_docs 报 409

原因：文档已存在且未带 _rev。批量更新需在 docs 中携带各自 _rev；批量新建则确保 _id 唯一。

10.2 查询慢

原因：未建索引。用 _explain 确认使用哪个索引（实测未建索引时 _find 输出 warning）。

10.3 中文乱码

CouchDB 文档一律 UTF-8 JSON，写入时确保 Content-Type: application/json 且 body 为 UTF-8；curl 与 shell 终端编码保持一致。

十一、参考链接

CouchDB HTTP API 文档：https://docs.couchdb.org/en/stable/api/index.html
CouchDB Mango 查询：https://docs.couchdb.org/en/stable/api/database/find.html
CouchDB 复制文档：https://docs.couchdb.org/en/stable/replication/intro.html

本文档由 www.quzuo.net 平台开发