tozd/nginx-proxy

<[***]>

可用镜像地址：

• tozd/nginx-proxy
• registry.gitlab.com/tozd/docker/nginx-proxy

镜像继承关系

tozd/base ← tozd/dinit ← tozd/nginx ← tozd/nginx-mailer ← tozd/nginx-cron ← tozd/nginx-proxy

标签

• ubuntu-xenial
• ubuntu-bionic
• ubuntu-focal
• ubuntu-jammy
• ubuntu-noble

卷

• /var/log/dnsmasq：当Docker未提供内部轻量级DNS解析器且LOG_TO_STDOUT未设为1时，存储该DNS解析器的日志文件。
• /var/log/dockergen：当LOG_TO_STDOUT未设为1时，存储docker-gen的日志文件。
• /var/log/letsencrypt：Let's Encrypt服务的（调试）日志文件。
• /ssl：存储主机SSL密钥及可选额外配置的卷。所有Let's Encrypt生成的密钥及认证密钥也存储于此。需持久化此卷以避免状态丢失。

环境变量

• DOCKER_HOST：连接Docker守护进程以监控新容器的地址。默认值为容器内的/var/run/docker.sock。
• LETSENCRYPT_EMAIL：若设置，启用通过Let's Encrypt服务自动生成SSL密钥。设置此变量即表示同意Let's Encrypt订阅协议。
• LETSENCRYPT_ARGS：传递给Let's Encrypt certbot的额外参数。
• LOG_TO_STDOUT：若设为1，日志输出到标准输出（可通过docker logs查看），而非日志卷。
• NGINX_HTTPS_PORT：设置HTTPS监听端口，默认值为443。
• NGINX_HTTPS_PROTOCOLS：设置HTTPS虚拟主机的SSL协议。默认值为TLSv1.2 TLSv1.3。
• NGINX_HTTPS_CIPHERS：设置HTTPS虚拟主机的SSL密码套件。默认值为HIGH:!aNULL:!MD5。

镜像概述

提供基于Nginx HTTP服务器的反向代理功能，支持HTTPS虚拟主机。可直接使用或扩展该镜像，添加自定义虚拟主机配置文件。当LOG_TO_STDOUT设为1时，日志输出到标准输出和标准错误流，所有标准输出内容为JSON格式。

自动配置

该镜像使用docker-gen动态生成Nginx配置文件，用于暴露HTTP虚拟主机的容器。即使容器重启，配置也能自动生效。通过在需反向代理的容器上配置以下环境变量来设置虚拟主机：

• VIRTUAL_HOST：容器提供的虚拟主机列表，以逗号分隔。
• VIRTUAL_URL：容器提供的URL路径列表，以逗号分隔；这些路径会映射到容器的HTTP根路径（/）。
• VIRTUAL_ALIAS：容器提供的URL路径列表，以逗号分隔；这些路径会映射到容器的相同HTTP路径。
• VIRTUAL_PORT：若容器暴露多个端口或不使用默认端口80，可指定反向代理连接的自定义端口。
• VIRTUAL_NETWORK：若容器连接多个网络，可通过此变量选择使用的网络（默认使用第一个网络，但顺序不保证）。
• VIRTUAL_LETSENCRYPT：若设置，且已启用Let's Encrypt功能，则自动为该虚拟主机生成并启用SSL密钥。

运行HTTP内容容器时，可指定上述环境变量。例如，以下命令会使反向代理将[***]解析到example容器：

docker run --name example ... --env VIRTUAL_HOST=example.com --env VIRTUAL_URL=/ ...

以下命令会使反向代理将[***]解析到example1容器，将[***]解析到example2容器：

docker run --name example1 ... --env VIRTUAL_HOST=example.com --env VIRTUAL_URL=/foo ...
docker run --name example2 ... --env VIRTUAL_HOST=example.com --env VIRTUAL_URL=/bar ...

多个容器可提供同一主机和URL路径的内容，Nginx会在所有容器间进行负载均衡。

VIRTUAL_URL与VIRTUAL_ALIAS的区别：VIRTUAL_URL将所有外部路径映射到容器的HTTP根路径（/），适用于容器在根路径提供静态内容且需暴露到其他外部路径的场景，但可能导致容器内资源引用（如<img src="/foobar.png" />）无法正确解析。VIRTUAL_ALIAS则将外部路径与容器路径1:1映射，通常更推荐，但需容器也配置相应路径。

HTTPS配置

若需为虚拟主机配置HTTPS，需挂载/ssl卷并提供SSL密钥。对于主机example.com，需提供/ssl/example.com.key（私钥）和/ssl/example.com.crt（证书，包含完整验证链）。若这两个文件存在，镜像会自动配置虚拟主机使用HTTPS，并将非HTTPS流量重定向到HTTPS。

如需非HTTPS流量的额外配置，可提供/ssl/example.com_nonssl.conf文件；如需HTTPS的额外配置，可提供/ssl/example.com_ssl.conf文件。文件名需与虚拟主机名匹配。

Let's Encrypt集成

若需启用Let's Encrypt证书自动生成与续期功能，并同意Let's Encrypt订阅协议，可在运行镜像时设置LETSENCRYPT_EMAIL环境变量（值为你的邮箱地址）以启用该功能。此后，所有设置VIRTUAL_LETSENCRYPT环境变量的容器会自动生成、启用SSL证书，并定期续期。

所有生成的密钥及Let's Encrypt认证密钥均存储在/ssl卷下。

建议配置MAILTO环境变量（你的邮箱地址）以接收每日 cron 任务报告，并定期检查/var/log/letsencrypt和/var/log/dockergen卷中的日志，排查证书生成与续期问题。为使邮件发送功能生效，还需至少配置REMOTES环境变量。

可在/ssl/letsencrypt.manual.list文件中列出需额外获取SSL密钥的域名。

容器动态解析

扩展镜像时，可将站点配置文件放在/etc/nginx/sites-enabled/目录添加自定义站点；或挂载卷到/etc/nginx/sites-volume/目录并在此提供站点配置。

为支持动态IP的容器静态配置文件，该镜像会配置内部轻量级DNS解析器（当Docker未提供时），使Nginx能动态将容器主机名解析为IP。以下是使用DNS解析的站点配置示例：

server {
    listen 80;
    server_name example.com;

    # 动态解析容器IP，使用变量使Nginx持续解析（非仅启动时），以适应容器IP变化
    location / {
        set $example example;
        proxy_pass [***]
    }
}

上述配置假设存在主机名为example的容器：

docker run --name example --hostname example ...

默认情况下，容器IP变化后，Nginx最多需5秒重新解析虚拟主机到新IP（因缓存机制）。

GitHub镜像

项目提供只读GitHub镜像，方便在GitHub上 Fork 项目。