3.5. CouchDB HTTP 服务器

3.5.1. HTTP 服务器选项

[chttpd]

注意

在 CouchDB 2.x 和 3.x 中，chttpd 部分指的是标准的集群端口。除本文档中描述的少数特定维护任务外，所有 CouchDB 的使用都应通过此端口进行。

bind_address

定义集群端口可用的 IP 地址

[chttpd]
bind_address = 127.0.0.1

要让 CouchDB 监听任何可用的 IP 地址，请使用 0.0.0.0

[chttpd]
bind_address = 0.0.0.0

对于 IPv6 支持，如果您想让 CouchDB 正确监听，则需要设置 ::1

[chttpd]
bind_address = ::1

或 :: 用于任何可用的

[chttpd]
bind_address = ::
port

定义要监听的端口号

[chttpd]
port = 5984

要让 CouchDB 使用任何空闲端口，请将此选项设置为 0

[chttpd]
port = 0
prefer_minimal

如果请求具有标头 "Prefer": "return=minimal"，CouchDB 将只发送 prefer_minimal 配置中列出的标头。

[chttpd]
prefer_minimal = Cache-Control, Content-Length, Content-Range, Content-Type, ETag, Server, Transfer-Encoding, Vary

警告

从设置中删除 Server 标头将意味着 CouchDB 服务器标头将被 MochiWeb 服务器标头替换。

authentication_handlers

CouchDB 使用的身份验证处理程序列表。您可以通过第三方插件扩展它们，或者如果您不允许用户使用提供的其中一种方法，则可以删除其中一些。

[chttpd]
authentication_handlers = {chttpd_auth, cookie_authentication_handler}, {chttpd_auth, default_authentication_handler}

  • {chttpd_auth, cookie_authentication_handler}: 用于 Cookie 身份验证；

  • {chttpd_auth, proxy_authentication_handler}: 用于代理身份验证；

  • {chttpd_auth, jwt_authentication_handler}: 用于 JWT 身份验证；

  • {chttpd_auth, default_authentication_handler}: 用于基本身份验证；

  • {couch_httpd_auth, null_authentication_handler}: 禁用身份验证，破坏 CouchDB。

buffer_response

在版本 3.1.1 中更改。

将其设置为 true 以延迟响应的开始，直到计算出结束。这会增加内存使用量，但会简化客户端错误处理，因为它消除了响应可能由于超时而被故意终止一半的可能性。此配置值可以在运行时更改，而不会影响任何正在进行的响应。

即使将其设置为 false（默认值），也可以通过在请求参数中添加 ?buffer_response=true 为任何延迟的 JSON 响应调用按请求启用缓冲响应。

allow_jsonp

在版本 3.2 中更改: 从 [httpd] 部分移至 [chttpd] 部分

此选项的 true 值启用 JSONP 支持（默认情况下为 false）

[chttpd]
allow_jsonp = false
changes_timeout

在版本 3.2 中更改: 从 [httpd] 部分移至 [chttpd] 部分

以毫秒为单位指定 更改馈送 的默认 timeout 值（默认值为 60000）

[chttpd]
changes_timeout = 60000 ; 60 seconds
config_whitelist

在版本 3.2 中更改: 从 [httpd] 部分移至 [chttpd] 部分

设置配置修改白名单。只有白名单中的值可以通过 配置 API 更改。要允许管理员通过 HTTP 更改此值，请记住包含 {chttpd,config_whitelist} 本身。从列表中排除它将需要编辑此文件以更新白名单

[chttpd]
config_whitelist = [{chttpd,config_whitelist}, {log,level}, {etc,etc}]
enable_cors

在版本 1.3 中新增。

在版本 3.2 中更改: 从 [httpd] 部分移至 [chttpd] 部分

控制 CORS 功能

[chttpd]
enable_cors = false
secure_rewrites

在版本 3.2 中更改: 从 [httpd] 部分移至 [chttpd] 部分

此选项允许通过子域隔离数据库

[chttpd]
secure_rewrites = true
x_forwarded_host

在版本 3.2 中更改: 从 [httpd] 部分移至 [chttpd] 部分

x_forwarded_host 标头（默认情况下为 X-Forwarded-Host）用于转发 Host 标头字段的原始值，例如，如果反向代理在将请求转发到 CouchDB 之前将“Host”标头字段重写为某个内部主机名。

[chttpd]
x_forwarded_host = X-Forwarded-Host

此标头优先于 Host 标头，前提是它存在于请求中。

x_forwarded_proto

在版本 3.2 中更改: 从 [httpd] 部分移至 [chttpd] 部分

x_forwarded_proto 标头（默认情况下为 X-Forwarder-Proto）用于识别 HTTP 请求的源协议，因为反向代理可以使用 HTTP 与 CouchDB 实例通信，即使对反向代理的请求是 HTTPS。

[chttpd]
x_forwarded_proto = X-Forwarded-Proto
x_forwarded_ssl

在版本 3.2 中更改: 从 [httpd] 部分移至 [chttpd] 部分

x_forwarded_ssl 标头（默认情况下为 X-Forwarded-Ssl）告诉 CouchDB 它应该使用 https 方案而不是 http。实际上，它是 X-Forwarded-Proto: https 标头的同义词，但被一些反向代理使用。

[chttpd]
x_forwarded_ssl = X-Forwarded-Ssl
enable_xframe_options

在版本 3.2 中更改: 从 [httpd] 部分移至 [chttpd] 部分

控制 启用或禁用 功能

[chttpd]
enable_xframe_options = false
max_http_request_size

在版本 3.2 中更改: 从 [httpd] 部分移至 [chttpd] 部分

限制 HTTP 请求正文的最大大小。此设置适用于所有请求，它不区分单文档操作与多文档操作。因此，将其设置为 1MB 将阻止大小超过 1MB 的文档的 PUT，但它也可能阻止 1000 个 1KB 文档的 _bulk_docs 更新，或一个小文档的 multipart/related 更新，后跟两个 512KB 附件。此设置旨在用作针对恶意大型 HTTP 请求的保护，而不是用于限制最大文档大小。

[chttpd]
max_http_request_size = 4294967296 ; 4 GB

警告

在版本 2.1.0 之前，couchdb/max_document_size 实际上是作为 max_http_request_size 实现的。也就是说，它检查 HTTP 请求正文而不是文档大小。升级后，建议审查这些配置设置的使用情况。

bulk_get_use_batches

在版本 3.3 中新增。

设置为 false 以恢复到以前使用内部单文档获取的 _bulk_get 实现。使用批次应该更快，但是新实现中可能存在错误，因此公开此选项以允许恢复到旧行为。

[chttpd]
bulk_get_use_batches = true
admin_only_all_dbs

在版本 2.2 中新增: 为 _all_dbs 实现，默认值为 false

版本 3.0 中的变更: 默认值切换为 true，适用于 _all_dbs

版本 3.3 中的变更: 适用于 _all_dbs 和 _dbs_info

当设置为 true 时，需要管理员权限才能访问 _all_dbs 和 _dbs_info。

[chttpd]
admin_only_all_dbs = true
disconnect_check_msec

版本 3.3.3 中新增。

在处理流式请求（如 _all_docs、_find、_changes 和视图）时，检查客户端断开连接的频率（以毫秒为单位）。

[chttpd]
disconnect_check_msec = 30000
disconnect_check_jitter_msec

版本 3.3.3 中新增。

对 disconnect_check_msec 周期应用的随机抖动量。这是为了避免在大量并发客户端的情况下出现踩踏现象。

[chttpd]
disconnect_check_jitter_msec = 15000
[httpd]

版本 3.2 中的变更: 这些选项已移至 [chttpd] 部分：allow_jsonp、changes_timeout、config_whitelist、enable_cors、secure_rewrites、x_forwarded_host、x_forwarded_proto、x_forwarded_ssl、enable_xframe_options、max_http_request_size。

server_options

CouchDB 的 MochiWeb 组件的服务器选项可以添加到配置文件中

[httpd]
server_options = [{backlog, 128}, {acceptor_pool_size, 16}]

支持的选项是 TCP/IP 堆栈支持的完整选项的子集。支持的选项列表在 Erlang inet 文档中提供。

socket_options

CouchDB 中监听套接字的套接字选项（在每次请求开始时设置）可以指定为元组列表。例如

[httpd]
socket_options = [{sndbuf, 262144}]

支持的选项是 TCP/IP 堆栈支持的完整选项的子集。支持的选项列表在 Erlang inet 文档中提供。

3.5.2. HTTPS (SSL/TLS) 选项

[ssl]

CouchDB 本地支持 TLS/SSL，无需使用代理服务器。

HTTPS 设置可能很棘手，但 CouchDB 中的配置旨在尽可能简单。您只需要两个文件：证书和私钥。如果您有来自证书颁发机构的官方证书，则这两个文件应该都在您的手中。

如果您只想试用一下，不想费心获取官方证书，可以创建自签名证书。所有操作都将按预期进行，但客户端会收到有关不安全证书的警告。

您需要安装 OpenSSL 命令行工具。它可能已经安装了。

shell> mkdir /etc/couchdb/cert
shell> cd /etc/couchdb/cert
shell> openssl genrsa > privkey.pem
shell> openssl req -new -x509 -key privkey.pem -out couchdb.pem -days 1095
shell> chmod 600 privkey.pem couchdb.pem
shell> chown couchdb privkey.pem couchdb.pem

现在，您需要编辑 CouchDB 的配置，方法是编辑您的 local.ini 文件。以下是您需要执行的操作。

在 [ssl] 部分下，启用 HTTPS 并设置新生成的证书

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

有关更多信息，请阅读 证书 HOWTO。

现在启动（或重新启动）CouchDB。您应该能够使用 HTTPS 在端口 6984 上连接到它

shell> curl https://127.0.0.1:6984/
curl: (60) SSL certificate problem, verify that the CA cert is OK. Details:
error:14090086:SSL routines:SSL3_GET_SERVER_CERTIFICATE:certificate verify failed
More details here: http://curl.haxx.se/docs/sslcerts.html

curl performs SSL certificate verification by default, using a "bundle"
of Certificate Authority (CA) public keys (CA certs). If the default
bundle file isn't adequate, you can specify an alternate file
using the --cacert option.
If this HTTPS server uses a certificate signed by a CA represented in
the bundle, the certificate verification probably failed due to a
problem with the certificate (it might be expired, or the name might
not match the domain name in the URL).
If you'd like to turn off curl's verification of the certificate, use
the -k (or --insecure) option.

糟糕！发生了什么？！请记住，客户端会通知其用户您的证书是自签名的。在这种情况下，curl 是客户端，它会通知您。幸运的是，您信任自己（不是吗？），您可以指定 -k 选项，如消息中所述

shell> curl -k https://127.0.0.1:6984/
{"couchdb":"Welcome","version":"1.5.0"}

全部完成。

出于性能原因，以及为了简化设置，您可能仍然希望在负载均衡器/反向代理处终止 HTTPS 连接，然后在它与 CouchDB 集群之间使用未加密的 HTTP。这是推荐的方法。

您可以在 CouchDB wiki 中找到更多详细信息。

cacert_file

包含 PEM 编码 CA 证书的文件的路径。CA 证书用于构建服务器证书链，以及用于客户端身份验证。此外，CA 用于在请求证书时传递给客户端的可接受客户端 CA 列表中。如果不需要验证客户端，并且服务器证书没有中间 CA，则可以省略。

[ssl]
cacert_file = /etc/ssl/certs/ca-certificates.crt
cert_file

包含用户证书的文件的路径

[ssl]
cert_file = /etc/couchdb/cert/couchdb.pem
key_file

包含用户私有 PEM 编码密钥的文件的路径

[ssl]
key_file = /etc/couchdb/cert/privkey.pem
password

包含用户密码的字符串。仅在私钥文件受密码保护时使用

[ssl]
password = somepassword
ssl_certificate_max_depth

最大对等证书深度（即使证书验证已关闭，也必须设置）

[ssl]
ssl_certificate_max_depth = 1
verify_fun

验证函数（可选）如果未指定，将使用默认验证函数

[ssl]
verify_fun = {Module, VerifyFun}
verify_ssl_certificates

设置为 true 以验证对等证书

[ssl]
verify_ssl_certificates = false
fail_if_no_peer_cert

设置为 true 以使用 handshake_failure 警告消息终止 TLS/SSL 握手，如果客户端未发送证书。仅在 verify_ssl_certificates 为 true 时使用。如果设置为 false，则仅在客户端发送无效证书时才会失败（空证书被视为有效）

[ssl]
fail_if_no_peer_cert = false
secure_renegotiate

设置为 true 以拒绝不符合 RFC 5746 的重新协商尝试

[ssl]
secure_renegotiate = true
ciphers

设置为应支持的密码套件，可以使用 Erlang 格式“{ecdhe_ecdsa,aes_128_cbc,sha256}”或 OpenSSL 格式“ECDHE-ECDSA-AES128-SHA256”指定。

[ssl]
ciphers = ["ECDHE-ECDSA-AES128-SHA256", "ECDHE-ECDSA-AES128-SHA"]
tls_versions

设置为允许的 SSL/TLS 协议版本列表

[ssl]
tls_versions = [tlsv1 | 'tlsv1.1' | 'tlsv1.2']

3.5.3. 跨域资源共享

[cors]

版本 1.3 中新增: 添加了 CORS 支持，请参阅 JIRA COUCHDB-431

在版本 3.2 中更改: 从 [httpd] 部分移至 [chttpd] 部分

CORS 或“跨域资源共享”允许资源（例如在浏览器中运行 JavaScript 的网页）向不同域发出 AJAX 请求（XMLHttpRequests），而不会影响任何一方的安全性。

一个典型的用例是让托管在 CDN 上的静态网站向另一个资源（例如托管的 CouchDB 实例）发出请求。这避免了使用中间代理、使用 JSONP 或类似方法来检索和托管内容。

虽然 CouchDB 的集成 HTTP 服务器支持文档附件，这使得纯 CouchDB 项目的约束减少了，但仍有许多情况下，将静态内容与数据库访问分离是可取的，而 CORS 使得这变得非常简单。

通过支持 CORS 功能，CouchDB 实例可以接受对受保护数据库和实例的直接连接，而不会因同源策略限制而阻止浏览器功能。CORS 如今在 90% 以上的最新浏览器中得到支持。

CORS 支持在 1.3 中作为实验性功能提供，因此需要在 CouchDB 的配置中专门启用它。虽然默认情况下所有来源都被禁止发出请求，但支持简单请求、预检请求和每个虚拟主机的配置。

此部分要求 chttpd/enable_cors 选项具有 true 值

[chttpd]
enable_cors = true
credentials

默认情况下，身份验证标头和 cookie 都不包含在请求和响应中。要执行此操作，需要在浏览器中的请求对象上同时设置 XmlHttpRequest.withCredentials = true 并在 CouchDB 中启用凭据支持。

[cors]
credentials = true

CouchDB 将使用一个额外的标头 Access-Control-Allow-Credentials=true 响应启用凭据的 CORS 请求。

origins

以逗号分隔的来源列表，* 表示接受所有来源。您不能同时设置 origins = * 和 credentials = true 选项

[cors]
origins = *

可以通过协议、主机和可选的端口来限制访问。来源必须遵循以下方案：http://example.com:80

[cors]
origins = http://localhost, https://localhost, http://couch.mydev.name:8080

请注意，默认情况下，不接受任何来源。您必须明确定义它们。

headers

以逗号分隔的接受标头列表

[cors]
headers = X-Couch-Id, X-Couch-Rev
methods

接受的方法列表

[cors]
methods = GET,POST
max_age

以秒为单位设置 Access-Control-Max-Age 标头。使用它来避免重复的 OPTIONS 请求。

[cors] max_age = 3600

另请参阅

原始 JIRA 实现票证

标准和参考

Mozilla 开发者网络资源

客户端 CORS 支持和使用

3.5.3.1. 每个虚拟主机配置

警告

虚拟主机在 CouchDB 3.0 中已弃用，将在 CouchDB 4.0 中删除。

要设置 vhosts 的选项，您需要创建一个以 cors: 为前缀的虚拟主机名称部分。虚拟主机 example.com 的示例情况

[cors:example.com]
credentials = false
; List of origins separated by a comma
origins = *
; List of accepted headers separated by a comma
headers = X-CouchDB-Header
; List of accepted methods
methods = HEAD, GET

2010 年关于虚拟主机和重写配置的视频 已发布，但不能保证与当前语法或行为匹配。

3.5.4. 虚拟主机

警告

虚拟主机在 CouchDB 3.0 中已弃用，将在 CouchDB 4.0 中删除。

[vhosts]

CouchDB 可以根据 Host 标头将请求映射到不同的位置，即使它们到达相同的入站 IP 地址。

这允许同一台机器上的不同虚拟主机映射到不同的数据库或设计文档等。最常见的用例是将虚拟主机映射到 重写处理程序，以提供对应用程序 URI 的完全控制。

要添加虚拟主机，请在您的域名 DNS 中添加一个 CNAME 指针。对于开发和测试，在 hosts 文件中添加一个条目就足够了，通常在类 Unix 操作系统上是 /etc/hosts`

# CouchDB vhost definitions, refer to local.ini for further details
127.0.0.1       couchdb.local

测试它是否有效

$ ping -n 2 couchdb.local
PING couchdb.local (127.0.0.1) 56(84) bytes of data.
64 bytes from localhost (127.0.0.1): icmp_req=1 ttl=64 time=0.025 ms
64 bytes from localhost (127.0.0.1): icmp_req=2 ttl=64 time=0.051 ms

最后，在 配置文件 的 [vhosts] 部分添加一个条目

[vhosts]
couchdb.local:5984 = /example
*.couchdb.local:5984 = /example

如果您的 CouchDB 正在侦听默认 HTTP 端口 (80)，或者位于代理后面，那么您不需要在 vhost 键中指定端口号。

第一行将重写请求以显示 example 数据库的内容。此规则仅在 Host 标头为 couchdb.local 时有效，对 CNAME 不起作用。另一方面，第二条规则将所有 CNAME 匹配到 example 数据库，因此 www.couchdb.local 和 db.couchdb.local 都将起作用。

3.5.4.1. 将主机重写到路径

就像在 _rewrite 处理程序中一样，您可以匹配一些变量并使用它们来创建目标路径。一些例子

[vhosts]
*.couchdb.local = /*
:dbname. = /:dbname
:ddocname.:dbname.example.com = /:dbname/_design/:ddocname/_rewrite

第一条规则将通配符作为 dbname 传递。第二个规则也是这样做的，但使用了一个变量名。第三个规则允许您使用任何带有 ddocname 的 URL，在任何带有 dbname 的数据库中。

3.5.5. X-Frame-Options

X-Frame-Options 是一个响应标头，它控制 HTTP 响应是否可以嵌入到 <frame>、<iframe> 或 <object> 中。这是一个安全功能，有助于防止点击劫持。

[x_frame_options] ; 设置 same-origin 将返回 X-Frame-Options: SAMEORIGIN。 ; 如果设置了 same origin，它将忽略 hosts 设置 ; same_origin = true ; 设置 hosts 将 ; 返回 X-Frame-Options: ALLOW-FROM https://example.com/ ; 用逗号分隔的主机列表。* 表示接受所有 ; hosts =

如果启用了 xframe_options，它将默认返回 X-Frame-Options: DENY。如果启用了 same_origin，它将返回 X-Frame-Options: SAMEORIGIN。当 same_origin 为 false 且 HOST 标头与 hosts 配置中的某个 URL 匹配时，将返回 X-FRAME-OPTIONS: ALLOW-FROM url。否则，将返回 X-Frame-Options: DENY。