CouchDB 3.5 配置参数详解

目标：系统讲解 CouchDB 3.5 的核心配置项，覆盖配置文件体系、服务监听、认证、CORS、数据目录、视图索引、性能与安全参数。所有配置值均在 CouchDB 3.5.2 真实环境（官方压缩包 + 官方 apt 源安装）实测。

环境信息

CouchDB 版本：3.5.2（官方压缩包）/ 3.5.2.1（apt 官方源）
配置文件：
- /opt/couchdb/etc/local.ini（主配置）
- /opt/couchdb/etc/local.d/*.ini（自定义配置，优先加载）
- /opt/couchdb/etc/default.d/*.ini（默认配置，勿改）
数据目录：/opt/couchdb/data
默认端口：5984（HTTP）、6984（HTTPS）、5986（内部 httpd）
配置查询 API：GET /_node/_local/_config/<section>

配置文件体系

CouchDB 配置是 INI 格式，支持命令行 -couchdb-config 与 -config 参数指定路径。加载优先级：default.ini < default.d/ < local.ini < local.d/（后者覆盖前者）。

# 查看运行时生效配置（实测）
curl -s -u admin:'AppTest@2026' http://127.0.0.1:5984/_node/_local/_config/chttpd
# 输出 {"bind_address":"any","port":"5984"}

💡 CouchDB 提供 HTTP 配置 API，可在线查看/修改配置（修改后需重启生效的部分见各参数说明）。

一、服务监听（[chttpd] 段）

bind_address

属性	值
默认值（实测）	any（所有网卡）
取值	any / 127.0.0.1 / 0.0.0.0 / 具体 IP

说明： 主 HTTP 服务（5984）监听地址。

[chttpd]
bind_address = 0.0.0.0     # 允许远程访问

⚠️ 注意：CouchDB 3.x 的 bind_address = any 与常规 0.0.0.0 行为一致（监听所有网卡）。安全要求：远程部署时务必已设置 admin 密码，否则 CouchDB 只接受 localhost 连接。

port

属性	值
默认值（实测）	5984
取值	1 ~ 65535

说明： 主服务端口。

[chttpd]
port = 5984

单节点 vs 集群相关

参数	默认值	说明
`[cluster] n`	1	副本数，单节点保持 1
`[cluster] q`	2	分片数，单节点可保持默认

💡 单节点部署无需修改集群参数；q=2 表示每个库分 2 个分片（内部实现，对用户透明）。

二、内部服务（[httpd] 段）

参数	默认值（实测）	说明
bind_address	127.0.0.1	内部管理端口（5986）仅本机监听
port	5986	内部 httpd 端口，勿暴露公网
enable_cors	false	是否允许浏览器跨域访问

[httpd]
enable_cors = true

三、数据与索引目录（[couchdb] 段）

实测运行时配置：

{"database_dir":"./data","view_index_dir":"./data"}

参数	默认值	说明
database_dir	./data	数据库文件目录（相对配置目录）
view_index_dir	./data	视图索引目录
max_dbs_open	500	最多同时打开的数据库句柄数
max_document_size	8000000（8MB）	单文档大小上限（字节），超出拒绝写入
single_node	false	单节点模式开关（配合集群 API 使用）

⚠️ 生产建议将 database_dir 指向独立磁盘：database_dir = /data/couchdb，并确保属主为 couchdb 用户。

四、认证与安全（[admins] 与 [couch_httpd_auth]）

管理员密码存储（实测）

CouchDB 将 admin 密码以 PBKDF2-SHA256 哈希存储于 local.ini 的 [admins] 段：

[admins]
admin = -pbkdf2:sha256-dfdfbd4cca9e65e34e5881c6959175c7e8d543c16260b5320e9ac5750c09dacc,c702ecfae82d241df31d0d37ff7f8574,600000

💡 格式：-pbkdf2:<hash>,<salt>,<iterations>。明文密码仅首次写入时出现，之后存储为哈希。

认证相关参数

参数	默认值	说明
timeout	300	会话超时（秒）
allow_persistent_cookies	false	允许持久化 cookie
secret	随机	会话签名密钥（部署后应重新生成）
proxy_use_secret	false	反向代理共享密钥认证
require_valid_user	false	是否强制所有请求需认证（生产建议开启）

[couch_httpd_auth]
require_valid_user = true

五、CORS（跨域）

[httpd]
enable_cors = true

[cors]
origins = *
credentials = true
methods = GET, PUT, POST, HEAD, DELETE
headers = accept, authorization, content-type, origin, referer

💡 前端 Web 应用（如 Fauxton）跨域访问时需配置；生产环境 origins 应限定具体域名而非 *。

六、SSL/TLS（[ssl] 段）

[ssl]
enable = true
cert_file = /opt/couchdb/etc/cert.pem
key_file = /opt/couchdb/etc/key.pem

启用后 HTTPS 端口为 6984。证书可用自签名或 Let's Encrypt。

七、性能相关参数

参数	默认值	说明
[couchdb] max_dbs_open	500	打开的库句柄上限
[view_compaction]	—	视图压缩阈值
[couchdb] os_process_timeout	5000	外部进程超时（ms）

八、配置修改与生效

配置修改后需重启生效（静态参数）：

sudo systemctl restart couchdb

与 2.x 版本的差异

项目	CouchDB 2.x	CouchDB 3.x（实测）
服务监听段	[httpd]	[chttpd]（HTTP 集群 API）
bind_address 默认	127.0.0.1	any
临时视图	支持	已移除（实测报 `Temporary views are not supported`）
单节点	需初始化	开箱即用
未设 admin 密码	可远程访问	仅本机且拒绝远程（安全默认）

⚠️ 迁移注意：依赖临时视图的旧应用需改写为 Mango 查询或设计文档视图。

参考链接

CouchDB 官方配置文档：https://docs.couchdb.org/en/stable/config/intro.html
CouchDB 配置 API：https://docs.couchdb.org/en/stable/api/server/configuration.html

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