adamus1red/nginx-proxy

nginx-proxy 镜像文档

镜像概述和主要用途

nginx-proxy 是一个运行 nginx 和 https://github.com/jwilder/docker-gen 的容器。docker-gen 会为 nginx 生成反向代理配置，并在容器启动或停止时自动重载 nginx。本镜像为 fork 版本，使用 nginx 的 mainline 和 stable 标签而非固定版本，实现滚动发布。

有关使用此镜像的原因，可参考 Automated Nginx Reverse Proxy for Docker。

核心功能和特性

• 自动配置生成：通过 docker-gen 自动生成 nginx 反向代理配置
• 动态重载：容器启动或停止时自动重载 nginx 配置
• 滚动发布：基于 nginx mainline 和 stable 标签，支持版本自动更新
• 多网络支持：可连接多个 Docker 网络，实现跨网络容器代理
• IPv6 支持：通过环境变量启用 IPv6
• 多虚拟主机：支持单个容器绑定多个虚拟主机
• 通配符主机：支持通配符和正则表达式匹配主机名
• SSL 支持：支持单主机、通配符和 SNI 证书，集成 Let's Encrypt
• 灵活的后端支持：支持 HTTP、HTTPS、uWSGI、FastCGI 后端
• 访问控制：可限制容器仅内网访问
• 自定义配置：支持全局、按虚拟主机或位置块的自定义 Nginx 配置

使用场景和适用范围

• Docker 环境下多容器应用的反向代理管理
• 需要自动配置更新的动态服务集群
• 多域名/子域名的流量路由
• 需同时处理 HTTP 和 HTTPS 流量的场景
• 需要隔离内外网访问的服务部署

详细的使用方法和配置说明

基本使用

运行 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 ...

注意：被代理的容器必须通过 EXPOSE 指令或 --expose 标志暴露端口，且与 nginx-proxy 在同一网络。默认情况下，若未指定 --net，nginx-proxy 仅连接默认 bridge 网络，无法代理其他网络的容器。

镜像变体

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），需配合有效证书使用：

bash
$ docker pull jwilder/nginx-proxy:alpine

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
$ curl -H "Host: whoami.local" localhost
I'm 5b129ab83266

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

多端口处理

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

多主机支持

单个容器可绑定多个虚拟主机，使用逗号分隔：

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

通配符主机

支持主机名前后通配符（如 *.bar.com 或 foo.bar.*）及正则表达式（如 ~^foo\.bar\..*\.xip\.io）。更多信息见 nginx server_names 文档。

多网络配置

Docker 1.9+ 支持覆盖网络，nginx-proxy 可连接多个网络。默认仅连接默认 bridge 网络，可通过 --net 指定创建时的网络，或使用 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

内外网访问控制

通过设置容器环境变量 NETWORK_ACCESS=internal 限制容器仅内网访问。默认内网定义为 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16。

自定义内网范围：挂载文件至 /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，需配置 nginx realip 模块提取真实 IP，配置文件可挂载至 /etc/nginx/conf.d/。

后端类型配置

SSL 后端

通过 VIRTUAL_PROTO=https 使反向代理使用 HTTPS 连接后端：

bash
$ docker run -e VIRTUAL_HOST=foo.bar.com -e VIRTUAL_PROTO=https -e VIRTUAL_PORT=443 ...

注意：若后端同时暴露 80 和 443 端口，需指定 VIRTUAL_PORT=443，否则默认使用 80 端口的 HTTPS。

uWSGI 后端

通过 VIRTUAL_PROTO=uwsgi 连接 uWSGI 后端，后端需监听端口并暴露。

FastCGI 后端

通过 VIRTUAL_PROTO=fastcgi 连接 FastCGI 后端，后端需监听端口并暴露。可通过 VIRTUAL_ROOT=xxx 设置根目录。

默认主机

通过环境变量 DEFAULT_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

分离容器部署

可将 nginx 和 docker-gen 运行在 separate 容器，提高安全性：

1. 启动 nginx 容器：

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

2. 启动 docker-gen 容器（需本地有 https://github.com/jwilder/nginx-proxy/blob/master/nginx.tmpl%EF%BC%89%EF%BC%9A

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. 启动带 VIRTUAL_HOST 的后端容器：

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

SSL 支持

Let's Encrypt 集成

使用 https://github.com/JrCs/docker-letsencrypt-nginx-proxy-companion 自动管理 Let's Encrypt 证书。通过 DHPARAM_GENERATION=false 禁用 Diffie-Hellman 参数生成（默认 true）：

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

基本 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 为 foo.bar.com 时，证书文件为 foo.bar.com.crt 和 foo.bar.com.key。

Diffie-Hellman 组

默认启用 DH 组，使用 /etc/nginx/dhparam/dhparam.pem。可挂载自定义文件覆盖，或按虚拟主机命名（如 foo.bar.com.dhparam.pem）。首次启动时会自动生成 2048 位 DH 参数（后台低优先级执行），可通过 DHPARAM_BITS=1024 生成兼容旧客户端的 1024 位参数。

通配符证书

通配符证书命名为域名（如 bar.com.crt 和 bar.com.key），适用于 VIRTUAL_HOST=foo.bar.com。

SNI 支持

通过 CERT_NAME=<name> 指定证书名称，适用于多域名证书：

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

OCSP Stapling

为域名启用 OCSP Stapling，需在证书目录放置 CA 证书链文件 <domain>.chain.pem。

SSL 策略

默认使用 Mozilla Intermediate 策略（兼容主流客户端），可通过 SSL_POLICY 环境变量指定其他策略（如 Mozilla-Modern、Mozilla-Old 或 AWS ELB 策略）。

HTTPS 行为控制

通过 HTTPS_METHOD 环境变量控制 HTTP/HTTPS 行为：

• redirect（默认）：HTTP 重定向至 HTTPS
• noredirect：同时提供 HTTP 和 HTTPS，不重定向
• nohttp：禁用 HTTP
• nohttps：禁用 HTTPS

HSTS 配置

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

基本认证支持

通过 htpasswd 文件保护虚拟主机，文件路径为 /etc/nginx/htpasswd/$VIRTUAL_HOST：

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

使用 apache2-utils 创建 htpasswd 文件，详见 htpasswd 文档。

自定义 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 后缀文件添加全局配置：

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

按虚拟主机配置

在 /etc/nginx/vhost.d/ 挂载与 VIRTUAL_HOST 同名的文件，如 app.example.com：

bash
$ docker run -d -p 80:80 -v /path/to/vhost.d:/etc/nginx/vhost.d:ro ...
$ echo 'server_tokens off;' > /path/to/vhost.d/app.example.com

多主机可使用符号链接共享配置。

按虚拟主机默认配置

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

按虚拟主机位置块配置

在 /etc/nginx/vhost.d/ 挂载 <VIRTUAL_HOST>_location 文件，如 app.example.com_location：

bash
$ echo 'proxy_cache my-cache;' > /path/to/vhost.d/app.example.com_location

按虚拟主机位置块默认配置

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