danieldent/nginx-ssl-proxy

自动免费证书管理的SSL前端代理

镜像概述和主要用途

本镜像包含nginx及相关代码，可自动获取和续期来自Let's Encrypt的免费域名验证（DV）SSL证书。无需复杂配置，30秒内即可完成SSL设置，默认配置可在SSL Labs获得A级评分，并启用HTTP/2以提升性能。

核心功能和特性

• 零配置部署：仅需设置两个环境变量即可快速启动
• 自动证书管理：自动获取和续期Let's Encrypt证书（90天有效期，60天时自动续期）
• 高安全性：默认使用Mozilla推荐的SSL密码套件，启用安全HTTP头
• HTTP/2支持：提升网站性能和响应速度
• 灵活认证：可选启用IP白名单、Cookie认证或HTTP基本认证
• 可定制化：支持自定义Nginx配置、请求大小限制和安全头

使用场景和适用范围

• 需要为Web应用快速添加SSL/TLS支持的场景
• 希望自动管理SSL证书，避免手动续期的服务
• 对安全性有要求，需要SSL Labs A级评分的网站
• 需要简单访问控制的代理服务

详细使用方法和配置说明

环境变量配置

HSTS严格传输安全头警告

默认配置包含Strict-Transport-Security头，有效期为1年。浏览器会缓存此头并仅通过SSL连接访问。可通过HSTS_HEADER变量自定义：

• 设置为skip：不使用HSTS头
• 其他值：直接作为头内容，例如max-age=31536000; includeSubDomains; preload（用于HSTS预加载准备）

Docker Compose部署示例

创建docker-compose.yml文件：

yaml
nginx-ssl-proxy:
  image: danieldent/nginx-ssl-proxy
  restart: always
  environment:
    UPSTREAM: 127.0.0.1:8080  # 上游服务器地址和端口
    SERVERNAME: test.example.com  # 主域名
    EXTRANAMES: www.test.example.com,test2.example.com  # 额外域名
  ports:
    - "80:80"   # HTTP端口（用于Let's Encrypt验证）
    - "443:443" # HTTPS端口
  volumes:
    - "/etc/letsencrypt"  # 存储证书数据的卷

启动命令：docker-compose up

可选：启用简单认证

当DO_AUTH=required时，代理实现以下认证机制（满足任一条件即可访问）：

• 来自WHITELIST_IPS中的IP或CIDR范围
• 提供名为magic_ssl_proxy_auth且值为COOKIE_VALUE的Cookie
• 使用HTTP基本认证（用户名admin，密码为PROXY_PASSWORD）

注意：

• 未提供COOKIE_VALUE和PROXY_PASSWORD时，系统会随机生成并输出到控制台
• PROXY_PASSWORD可在容器内/tmp/proxy_password文件中查看
• COOKIE_VALUE可在容器内/etc/nginx/auth_part1.conf文件中查看
• Nginx对COOKIE_VALUE长度有限制，过长会导致启动失败，需缩短或调整Nginx配置

可选：使用上游X-Forwarded-For头

配置IP认证时，若存在上游反向代理或Docker网络配置，可能导致客户端IP显示不正确。直接暴露镜像到互联网（如示例中的ports配置）可减少此类问题。

• REAL_IP_RECURSIVE=on：启用解析上游X-Forwarded-For头
• SET_REAL_IP_FROM：指定信任X-Forwarded-For头的IP/CIDR范围
• SET_REAL_IP_FROM_CLOUDFLARE=yes：自动添加Cloudflare反向代理IP到信任列表

可选：调整请求大小限制和缓冲区大小

• NGINX_CLIENT_MAX_BODY_SIZE：设置请求体最大大小（如100m允许100MB）
• NGINX_CLIENT_BODY_BUFFER_SIZE：设置请求体缓冲区大小，超过则使用临时文件

可选：添加自定义Nginx配置

/etc/nginx/main_location.conf文件可添加任意Nginx配置指令到主location块。可通过下游镜像或Docker卷覆盖此文件：

dockerfile
FROM danieldent/nginx-ssl-proxy
COPY custom_main_location.conf /etc/nginx/main_location.conf

证书数据

/etc/letsencrypt卷用于存储证书数据，其中account_key.json是Let's Encrypt账户密钥，可用于证书吊销。

自定义Nginx配置

通过修改https://github.com/DanielDent/docker-nginx-ssl-proxy/blob/master/proxy.conf%E5%B9%B6%E6%9B%BF%E6%8D%A2%60/etc/nginx/conf.d/default.conf%60%E6%9D%A5%E8%87%AA%E5%AE%9A%E4%B9%89%E9%85%8D%E7%BD%AE%EF%BC%9A

dockerfile
FROM danieldent/nginx-ssl-proxy
COPY proxy.conf /etc/nginx/conf.d/default.conf

SSL设置

默认使用Mozilla推荐的SSL密码套件，不支持非常旧的浏览器（如IE6）。

安全头

默认启用安全HTTP头（参考OWASP安全头列表）。设置SECURITY_HEADERS=skip可禁用，避免与上游服务器的头冲突。

依赖

• https://hub.docker.com/_/nginx/%EF%BC%9A%E4%BB%A3%E7%90%86%E6%9C%8D%E5%8A%A1%E5%99%A8
• certbot：证书创建和验证
• https://github.com/kreuzwerker/envplate%EF%BC%9ANginx%E9%85%8D%E7%BD%AE%E4%B8%AD%E7%9A%84%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E6%94%AF%E6%8C%81
• https://github.com/just-containers/s6-overlay%EF%BC%9A%E8%BF%9B%E7%A8%8B%E7%AE%A1%E7%90%86%E5%92%8C%E5%83%B5%E5%B0%B8%E8%BF%9B%E7%A8%8B%E5%9B%9E%E6%94%B6

问题与贡献

遇到问题请查看https://github.com/DanielDent/docker-nginx-ssl-proxy/issues%EF%BC%8C%E6%AC%A2%E8%BF%8E%E6%8F%90%E4%BA%A4PR%E6%88%96%E5%88%9B%E5%BB%BA%E6%96%B0issue%E6%8F%90%E5%87%BA%E6%94%B9%E8%BF%9B%E5%BB%BA%E8%AE%AE%E3%80%82

许可证

Copyright 2015-2018 Daniel Dent。

基于Apache License 2.0许可（详见许可证文本）。镜像中包含的第三方内容单独许可。