10.4. Reverse Proxies

CouchDB recommends the use of HAProxy as a load balancer and reverse proxy.The team’s experience with using it in production has shown it to be superiorfor configuration and montioring capabilities, as well as overall performance.

CouchDB’s sample haproxy configuration is present in the code repository andrelease tarball as rel/haproxy.cfg.

However, there are suitable alternatives. Below are examples forconfiguring nginx and Caddy web-servers appropriately.

10.4.1. Reverse proxying with nginx

10.4.1.1. Basic Configuration

Here’s a basic excerpt from an nginx config file in<nginx config directory>/sites-available/default. This will proxy allrequests from http://domain.com/… to http://localhost:5984/…

  1. location / {
  2.     proxy_pass http://localhost:5984;
  3.     proxy_redirect off;
  4.     proxy_buffering off;
  5.     proxy_set_header Host $host;
  6.     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  7. }

Proxy buffering must be disabled, or continuous replication will notfunction correctly behind nginx.

10.4.1.2. Reverse proxying CouchDB in a subdirectory with nginx

It can be useful to provide CouchDB as a subdirectory of your overall domain,especially to avoid CORS concerns. Here’s an excerpt of a basic nginxconfiguration that proxies the URL http://domain.com/couchdb tohttp://localhost:5984 so that requests appended to the subdirectory, suchas http://domain.com/couchdb/db1/doc1 are proxied tohttp://localhost:5984/db1/doc1.

  1. location /couchdb {
  2.     rewrite /couchdb/(.*) /$1 break;
  3.     proxy_pass http://localhost:5984;
  4.     proxy_redirect off;
  5.     proxy_buffering off;
  6.     proxy_set_header Host $host;
  7.     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  8. }

10.4.1.3. Authentication with nginx as a reverse proxy

Here’s a sample config setting with basic authentication enabled, placingCouchDB in the /couchdb subdirectory:

  1. location /couchdb {
  2.     auth_basic "Restricted";
  3.     auth_basic_user_file htpasswd;
  4.     rewrite /couchdb/(.*) /$1 break;
  5.     proxy_pass http://localhost:5984;
  6.     proxy_redirect off;
  7.     proxy_buffering off;
  8.     proxy_set_header Host $host;
  9.     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  10.     proxy_set_header Authorization "";
  11. }

This setup leans entirely on nginx performing authorization, and forwardingrequests to CouchDB with no authentication (with CouchDB in Admin Party mode).For a better solution, see Proxy Authentication.

10.4.1.4. SSL with nginx

In order to enable SSL, just enable the nginx SSL module, and add anotherproxy header:

  1. ssl on;
  2. ssl_certificate PATH_TO_YOUR_PUBLIC_KEY.pem;
  3. ssl_certificate_key PATH_TO_YOUR_PRIVATE_KEY.key;
  4. ssl_protocols SSLv3;
  5. ssl_session_cache shared:SSL:1m;
  6.  
  7. location / {
  8.     proxy_pass http://localhost:5984;
  9.     proxy_redirect off;
  10.     proxy_set_header Host $host;
  11.     proxy_buffering off;
  12.     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  13.     proxy_set_header X-Forwarded-Ssl on;
  14. }

The X-Forwarded-Ssl header tells CouchDB that it should use the httpsscheme instead of the http scheme. Otherwise, all CouchDB-generatedredirects will fail.

10.4.2. Reverse Proxying with Caddy

10.4.2.1. Basic configuration

Here’s a basic excerpt from a Caddyfile in/<path>/<to>/<site>/Caddyfile. This will proxy allrequests from http(s)://domain.com/… to http://localhost:5984/…

  1. domain.com {
  2.  
  3.     import /path/to/other/config.caddy # logging, error handling etc.
  4.  
  5.     proxy / localhost:5984 {
  6.         transparent
  7.     }
  8.  
  9. }

Note

The transparent preset in the proxy directive is shorthand for:

  1. header_upstream Host {host}
  2. header_upstream X-Real-IP {remote}
  3. header_upstream X-Forwarded-For {remote}
  4. header_upstream X-Forwarded-Proto {scheme}

Note that, because Caddy is https-by-default, you must explicitly include thehttp:// protocol in the site address if you do NOT want Caddyto automatically acquire and install an SSL certificate and begin acceptinghttps connections on port 443.

10.4.2.2. Reverse proxying CouchDB in a subdirectory with Caddy

It can be useful to provide CouchDB as a subdirectory of your overall domain,especially to avoid CORS concerns. Here’s an excerpt of a basic Caddyconfiguration that proxies the URL http(s)://domain.com/couchdb tohttp://localhost:5984 so that requests appended to the subdirectory, suchas http(s)://domain.com/couchdb/db1/doc1 are proxied tohttp://localhost:5984/db1/doc1.

  1. domain.com {
  2.  
  3.     import /path/to/other/config.caddy # logging, error handling etc.
  4.  
  5.     proxy /couchdb localhost:5984 {
  6.         transparent
  7.         without /couchdb
  8.     }
  9.  
  10. }

10.4.2.3. Reverse proxying + load balancing for CouchDB clusters

Here’s a basic excerpt from a Caddyfile in/<path>/<to>/<site>/Caddyfile. This will proxy and evenly distribute allrequests from http(s)://domain.com/… among 3 CouchDB cluster nodesat localhost:15984, localhost:25984 and localhost:35984.

Caddy will check the status, i.e. health, of each node every 5 seconds;if a node goes down, Caddy will avoid proxying requests to that node until itcomes back online.

  1. domain.com {
  2.  
  3.     import /path/to/other/config.caddy # logging, error handling etc.
  4.  
  5.     proxy / http://localhost:15984 http://localhost:25984 http://localhost:35984 {
  6.         policy round_robin
  7.         health_check /_up
  8.         health_check_duration 5s
  9.         try_interval 500ms
  10.         keepalive 0
  11.         transparent
  12.     }
  13.  
  14. }

10.4.2.4. Authentication with Caddy as a reverse proxy

Here’s a sample config setting with basic authentication enabled, placingCouchDB in the /couchdb subdirectory:

  1. domain.com {
  2.  
  3.     import /path/to/other/config.caddy # logging, error handling etc.
  4.  
  5.     basicauth /couchdb couch_username couchdb_password
  6.  
  7.     proxy /couchdb localhost:5984 {
  8.         transparent
  9.         header_upstream -Authorization
  10.         without /couchdb
  11.     }
  12.  
  13. }

For security reasons, using a plaintext password in the Caddyfile is notadvisable. One solution is to define Caddy-process environment variables e.g.COUCH_PW=couchdb_password and using placeholders in the Caddyfileinstead, e.g. {$COUCH_PW}.

This setup leans entirely on Caddy performing authorization, and forwardingrequests to CouchDB with no authentication (with CouchDB in Admin Party mode).For a better solution, see Proxy Authentication.

10.4.2.5. SSL/TLS with Caddy

Caddy is https-by-default, and will automatically acquire, install, activate and,when necessary, renew a trusted SSL certificate for you - all in the background.Certificates are issued by the LetsEncrypt certificate authority.

  1. domain.com {
  2.  
  3.     import /path/to/other/config.caddy # logging, error handling etc.
  4.  
  5.     proxy / localhost:5984 {
  6.         transparent
  7.         header_upstream x-forwarded-ssl on
  8.     }
  9.  
  10. }

The x-forwarded-ssl header tells CouchDB that it should use the httpsscheme instead of the http scheme. Otherwise, all CouchDB-generatedredirects will fail.

原文: http://docs.couchdb.org/en/stable/best-practices/reverse-proxies.html