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支持，您需要设置 ::1 如果您想让CouchDB正确监听：：

[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

警告

从设置中删除服务器头意味着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 auth；
{{chttpd_auth, default_authentication_handler}} ：用于基本身份验证；
{{couch_httpd_auth, null_authentication_handler}} ：禁用身份验证，断开CouchDB。

buffer_response¶

在 3.1.1 版更改.

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

即使将此设置为 false (缺省设置)，可以在每个请求的基础上为任何延迟的JSON响应调用启用缓冲响应，方法是添加 ?buffer_response=true 添加到请求的参数。

allow_jsonp¶

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

这个 true 此选项的值将启用 JSONP 支持（它是 false 默认情况下）：

[chttpd]
allow_jsonp = false

changes_timeout¶

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

指定默认值 timeout 价值观 Changes Feed 以毫秒为单位（默认为60000）：

[chttpd]
changes_timeout = 60000 ; 60 seconds

config_whitelist¶

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

设置配置修改白名单。只有白名单上的值可以通过 config 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] 部分

控制 Enables or disabled 特点：

[chttpd]
enable_xframe_options = false

max_http_request_size¶

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

限制HTTP请求正文的最大大小。此设置适用于所有请求，并且不区分单文档操作和多文档操作。因此，将其设置为1MB将使挡路成为 PUT of a document larger than 1MB, but it might also block a ``_ BULK_docs``更新1000个1KB文档，或更新一个小文档的多部分/相关内容，然后更新两个512KB的附件。此设置旨在用于防范恶意的大型HTTP请求，而不是限制最大文档大小。：：

[chttpd]
max_http_request_size = 4294967296 ; 4 GB

警告

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

[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中侦听套接字的套接字选项（在ever请求开始时设置）可以指定为元组列表。例如：：

[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

欲了解更多信息，请阅读 certificates HOWTO .

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

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"}

全部完成。

出于你的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 要终止TLS/SSL握手，请使用 handshake_failure 如果客户端未发送证书，则显示警报消息。仅在以下情况下使用 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实例可以接受到受保护数据库和实例的直接连接，而不会因为相同的来源限制而阻止浏览器功能。目前90%以上的浏览器都支持CORS。

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

本节要求 chttpd/enable_cors 选项具有 true 值：：

[chttpd]
enable_cors = true

credentials¶

默认情况下，请求和响应中不包括身份验证头和cookie。这样做需要两个设置 XmlHttpRequest.withCredentials = true 在浏览器中的request对象和启用CouchDB中的凭据支持。:

[cors]
credentials = true

CouchDB将用一个额外的头来响应一个支持凭据的CORS请求， Access-Control-Allow-Credentials=true .

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] 最大年龄=3600

参见

原始吉拉 implementation ticket

标准和参考文献：

与方法相关的IETF RFC： RFC 2618 ， RFC 2817 ， RFC 5789
互联网起源的IETF RFC： RFC 6454
W3C公司 CORS standard

Mozilla开发者网络资源：

客户端CORS支持和使用：

3.5.3.1. 每虚拟主机配置¶

警告

虚拟主机在couchdb3.0中不推荐使用，并将在couchdb4.0中删除。

设置的选项 vhosts ，则需要创建一个以vhost名称为前缀的节 cors: . vhost的示例案例 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年vhost和重写配置 is available ，但不保证与当前语法或行为匹配。

3.5.4. 虚拟主机¶

警告

虚拟主机在couchdb3.0中不推荐使用，并将在couchdb4.0中删除。

[vhosts]¶

CouchDB可以根据 Host 标头，即使它们到达相同的入站IP地址。

这允许同一台机器上的不同虚拟主机映射到不同的数据库或设计文档等 Rewrite Handler ，以提供对应用程序的uri的完全控制。

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

# 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

最后，在 configuration file 在 [vhosts] 章节：

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

如果您的CouchDB正在监听缺省HTTP端口(80)，或者位于代理之后，那么您不需要在 vhost 钥匙。

第一行将重写请求以显示 example 数据库。此规则仅在 Host 页眉是 couchdb.local 不会为 CNAMEs . 另一方面，第二条规则匹配所有 CNAMEs 到 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 。第二个执行相同的操作，但使用了变量名。第三个允许您将任何URL与 ddocname 在具有以下各项的任何数据库中 dbname 。

3.5.5. X Frame选项¶

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

[x_frame_options] ；Settings same origin将返回X-Frame-Options:SAMEORIGIN。；如果设置了“相同原点”，它将忽略“主机”设置；相同的原点=true；设置主机将；返回X-Frame-Options:ALLOW-FROMhttps://example.com/；主机列表，用逗号分隔。*表示接受所有；主人=

如果启用了xframe_options，它将返回 X-Frame-Options: DENY 默认情况下。如果 same_origin 如果启用，它将返回 X-Frame-Options: SAMEORIGIN 。一个 X-FRAME-OPTIONS: ALLOW-FROM url 将在以下情况下返回 same_origin 为false，并且主机标头与 hosts 配置。否则，一个 X-Frame-Options: DENY 将会被退还。