jwilder/nginx-proxy

概述

nginx - proxy 运行一个包含 Nginx 和 [docker - gen][1] 的容器。docker - gen 会为 Nginx 生成反向代理配置，并在容器启动或停止时重新加载 Nginx。

了解[为什么需要使用此工具][2]。

!latest 0.8.0 !nginx 1.19.3 !License MIT   

镜像变体

nginx - proxy 提供两种镜像变体：

jwilder/nginx - proxy:latest

基于 debian:jessie 的 Nginx 镜像。

bash
$ docker pull jwilder/nginx - proxy:latest

jwilder/nginx - proxy:alpine

基于 nginx:alpine 镜像，完全支持 HTTP/2（包括最新 Chrome 版本所需的 ALPN）。使用时需配合有效的证书（详见下文“使用 Let's Encrypt 实现 SSL 支持”）。

bash
$ docker pull jwilder/nginx - proxy:alpine

快速开始

基本运行

启动 nginx - proxy 容器：

bash
$ docker run -d -p 80:80 -v /var/run/docker.sock:/tmp/docker.sock:ro jwilder/nginx - proxy

然后启动需要被代理的容器，并设置环境变量 VIRTUAL_HOST=subdomain.youdomain.com：

bash
$ docker run -e VIRTUAL_HOST=foo.bar.com ...

被代理的容器必须通过 Dockerfile 的 EXPOSE 指令或 docker run/docker create 的 --expose 标志暴露（expose）需要代理的端口，且需处于同一网络。默认情况下，若创建 nginx - proxy 容器时未指定 --net 标志，它仅连接到默认的 bridge 网络，因此无法代理其他网络中的容器。

确保 DNS 配置将 foo.bar.com 转发到运行 nginx - proxy 的主机，请求将被路由到设置了 VIRTUAL_HOST 环境变量的容器。

Docker Compose 示例

yaml
version: '2'

services:
  nginx - proxy:
    image: jwilder/nginx - proxy
    ports:
      - "80:80"
    volumes:
      - /var/run/docker.sock:/tmp/docker.sock:ro

  whoami:
    image: jwilder/whoami
    environment:
      - VIRTUAL_HOST=whoami.local

启动服务：

bash
$ docker - compose up

测试访问：

bash
$ curl -H "Host: whoami.local" localhost
I'm 5b129ab83266

核心配置

虚拟主机（VIRTUAL_HOST）

通过环境变量 VIRTUAL_HOST 指定容器对应的虚拟主机，支持多个主机（用逗号分隔），例如：VIRTUAL_HOST=foo.bar.com,baz.bar.com。

虚拟端口（VIRTUAL_PORT）

若容器暴露多个端口，nginx - proxy 默认使用 80 端口。通过 VIRTUAL_PORT 环境变量可指定其他端口，例如：VIRTUAL_PORT=3000。若容器仅暴露一个端口且设置了 VIRTUAL_HOST，则自动使用该端口。

网络配置

多网络连接

默认情况下，nginx - proxy 仅连接到 bridge 网络。要代理其他网络中的容器，创建容器时需指定 --net=my - network，并可通过 docker network connect 连接到其他网络：

bash
$ docker run -d -p 80:80 -v /var/run/docker.sock:/tmp/docker.sock:ro \
    --name my - nginx - proxy --net my - network jwilder/nginx - proxy
$ docker network connect my - other - network my - nginx - proxy

IPv6 支持

通过设置环境变量 ENABLE_IPV6=true 启用 IPv6 支持：

bash
$ docker run -d -p 80:80 -e ENABLE_IPV6=true -v /var/run/docker.sock:/tmp/docker.sock:ro jwilder/nginx - proxy

默认主机（DEFAULT_HOST）

设置默认主机，当请求未匹配任何 VIRTUAL_HOST 时使用：

bash
$ docker run -d -p 80:80 -e DEFAULT_HOST=foo.bar.com -v /var/run/docker.sock:/tmp/docker.sock:ro jwilder/nginx - proxy

高级功能

通配符主机

支持主机名开头或结尾的通配符，例如 *.bar.com 或 foo.bar.*，也支持正则表达式（需以 ~ 开头），如 ~^foo\.bar\..*\.xip\.io 可匹配 foo.bar.127.0.0.1.xip.io 等。更多信息见 nginx server_names 文档。

后端类型配置

SSL 后端

若需通过 HTTPS 连接后端，在后端容器设置 VIRTUAL_PROTO=https。注意：若后端同时暴露 80 和 443 端口，需配合 VIRTUAL_PORT=443，否则默认使用 80 端口的 HTTPS，这通常不符合预期。

uWSGI 后端

设置 VIRTUAL_PROTO=uwsgi，后端容器需监听端口并暴露该端口（而非 socket）。

FastCGI 后端

设置 VIRTUAL_PROTO=fastcgi，后端容器需监听端口并暴露该端口（而非 socket）。通过 VIRTUAL_ROOT=xxx 指定 FastCGI 的根目录。

内外网访问控制

通过设置后端容器的 NETWORK_ACCESS=internal 环境变量，可限制其仅允许内网访问（默认内网定义为 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16）。自定义内网范围需挂载文件到 nginx - proxy 的 /etc/nginx/network_internal.conf，内容示例：

# 定义为内网的网络
allow 127.0.0.0/8;
allow 10.0.0.0/8;
allow 192.168.0.0/16;
allow 172.16.0.0/12;

# 拒绝其他网络流量
deny all;

启用内网访问限制后，外部客户端将收到 HTTP 403 Forbidden 响应。

若 nginx - proxy 前有负载均衡器/反向代理隐藏客户端 IP（如 AWS ALB），需使用 nginx 的 realip 模块（已预装）提取客户端 IP，配置可添加到 /etc/nginx/conf.d/ 目录下的文件中。详见 nginx realip 模块文档。

SSL 支持

基本配置

启用 SSL 需挂载证书目录：

bash
$ docker run -d -p 80:80 -p 443:443 -v /path/to/certs:/etc/nginx/certs -v /var/run/docker.sock:/tmp/docker.sock:ro jwilder/nginx - proxy

证书和私钥需按虚拟主机名命名，格式为 <virtual_host>.crt 和 <virtual_host>.key，例如 VIRTUAL_HOST=foo.bar.com 对应 foo.bar.com.crt 和 foo.bar.com.key。

Let's Encrypt 集成

https://github.com/JrCs/docker - letsencrypt - nginx - proxy - companion 是 nginx - proxy 的轻量级 companion 容器，可自动创建/续期 Let's Encrypt 证书。设置 DHPARAM_GENERATION=false 可禁用 Diffie - Hellman 参数生成（默认 true）：

bash
$ docker run -e DHPARAM_GENERATION=false ....

Diffie - Hellman 组

默认启用 Diffie - Hellman（DH）参数，预生成的 dhparam.pem 位于 /etc/nginx/dhparam/dhparam.pem。可挂载自定义文件覆盖，或按虚拟主机命名为 <virtual_host>.dhparam.pem。生成新参数可能耗时数分钟，首次启动时在后台低优先级进行。

• 禁用自动生成：DHPARAM_GENERATION=false
• 自定义位数：DHPARAM_BITS=1024（默认 2048，低位数兼容旧客户端如 Java 6/7）

分离容器部署时，需手动生成 DH 参数并挂载到 Nginx 容器的 /etc/nginx/dhparam/dhparam.pem。

通配符证书

通配符证书命名为域名的主域，例如 *.bar.com 证书对应 bar.com.crt 和 bar.com.key。

SNI 支持

多域名证书可通过 CERT_NAME=<name> 指定证书名，例如共享证书 shared.crt/shared.key，后端容器设置 CERT_NAME=shared 即可使用。

OCSP 装订

为域名启用 OCSP 装订，需在证书目录放置包含 CA 证书链的 PEM 文件 <domain>.chain.pem（中间 CA 到根 CA 的拼接），nginx - proxy 将其用于 ssl_trusted_certificate 指令并启用 OCSP 装订。

SSL 策略与重定向

默认 SSL 密码套件基于 Mozilla Intermediate 配置文件（版本 5.0），兼容 Firefox 27+、Android 4.4.2+ 等。设置 SSL_POLICY=Mozilla-Modern 可使用 Modern 配置文件（兼容 Firefox 63+、Android 10.0+ 等，不兼容 IE）。其他可用策略包括 Mozilla-Old 及 AWS ELB 策略（如 AWS-TLS-1-2-2017-01）。

默认行为：若容器有有效证书，80 端口请求重定向到 443；无证书则返回 503。通过 HTTPS_METHOD 自定义：

• redirect（默认）：HTTP 重定向到 HTTPS
• noredirect：同时支持 HTTP 和 HTTPS，不重定向
• nohttp：禁用 HTTP
• nohttps：禁用 HTTPS

可在 nginx - proxy 容器（全局）或后端容器（单个）设置。使用 noredirect 时 HSTS 自动禁用。

HSTS 配置

默认启用 HSTS（HTTP Strict Transport Security），max - age=31536000。通过 HSTS=off 禁用，或自定义如 HSTS=max - age=31536000; includeSubDomains; preload。

自定义 Nginx 配置

替换默认代理设置

添加 /etc/nginx/proxy.conf 文件可替换默认代理配置，默认配置示例：

Nginx
# HTTP 1.1 支持
proxy_http_version 1.1;
proxy_buffering off;
proxy_set_header Host $http_host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $proxy_connection;
proxy_set_header X - Real - IP $remote_addr;
proxy_set_header X - Forwarded - For $proxy_add_x_forwarded_for;
proxy_set_header X - Forwarded - Proto $proxy_x_forwarded_proto;
proxy_set_header X - Forwarded - Ssl $proxy_x_forwarded_ssl;
proxy_set_header X - Forwarded - Port $proxy_x_forwarded_port;

# 缓解 httpoxy 攻击
proxy_set_header Proxy "";

全局配置

在 /etc/nginx/conf.d/ 添加 .conf 文件（如 my_proxy.conf），可添加全局配置，例如：

Dockerfile
FROM jwilder/nginx - proxy
RUN {
      echo 'server_tokens off;';
      echo 'client_max_body_size 100m;';
    } > /etc/nginx/conf.d/my_proxy.conf

或挂载文件：

bash
$ docker run -d -p 80:80 -v /path/to/my_proxy.conf:/etc/nginx/conf.d/my_proxy.conf:ro ... jwilder/nginx - proxy

按虚拟主机配置

主配置

在 /etc/nginx/vhost.d/ 添加与 VIRTUAL_HOST 同名的文件，例如 app.example.com。多主机可使用符号链接共享配置。

默认配置

/etc/nginx/vhost.d/default 文件为未指定单独配置的虚拟主机提供默认设置。

Location 配置

添加 <VIRTUAL_HOST>_location 文件（如 app.example.com_location）可配置 location 块。默认配置文件为 default_location。

基本认证支持

为虚拟主机启用基本认证，需在 /etc/nginx/htpasswd/ 目录创建与 VIRTUAL_HOST 同名的文件。使用 apache2 - utils 生成凭证：

bash
$ docker run -d -p 80:80 -p 443:443 \
    -v /path/to/htpasswd:/etc/nginx/htpasswd \
    -v /path/to/certs:/etc/nginx/certs \
    -v /var/run/docker.sock:/tmp/docker.sock:ro \
    jwilder/nginx - proxy
$ htpasswd -c /path/to/htpasswd/foo.bar.com user

分离容器部署

可将 nginx - proxy 拆分为 Nginx 和 docker - gen 两个容器运行，避免将 docker socket 绑定到暴露的服务。需准备 https://github.com/jwilder/nginx - proxy/blob/master/nginx.tmpl 模板文件。

步骤

1. 启动 Nginx 容器：

bash
$ docker run -d -p 80:80 --name nginx -v /tmp/nginx:/etc/nginx/conf.d -t nginx

2. 启动 docker - gen 容器：

bash
$ docker run --volumes-from nginx \
    -v /var/run/docker.sock:/tmp/docker.sock:ro \
    -v $(pwd):/etc/docker - gen/templates \
    -t jwilder/docker - gen -notify-sighup nginx -watch /etc/docker - gen/templates/nginx.tmpl /etc/nginx/conf.d/default.conf

3. 启动后端容器：

bash
$ docker run -e VIRTUAL_HOST=foo.bar.com ...

贡献指南

提交 PR 或 issue 前，请先检查 GitHub 确保不存在重复。

本地运行测试

构建测试镜像：

bash
docker build -t jwilder/nginx - proxy:test .  # Debian 变体
# 或
docker build -f Dockerfile.alpine -t jwilder/nginx - proxy:test .  # Alpine 变体

运行测试：

bash
test/pytest.sh
# 或
make test

寻求帮助

使用问题请在 Q&A Group 提问。

[1]: https://github.com/jwilder/docker - gen [2]: [***] - nginx - reverse - proxy - for - docker/