luhn/gunicorn-proxy

gunicorn-proxy

镜像概述和主要用途

gunicorn-proxy是一个Docker一键式反向代理，专为简化gunicorn的反向代理配置而设计。按照最佳实践，通常建议将gunicorn部署在反向代理之后，但在容器化环境中配置这一架构可能需要大量额外工作。该镜像通过仅需设置应用服务器的主机名和端口即可快速启动反向代理，并支持通过环境变量进行灵活配置。尽管名称包含"gunicorn"，但它无特定于gunicorn的功能，可有效用于任何HTTP应用服务器。

核心功能和特性

• 极简配置：仅需指定应用服务器的主机名和端口即可运行，无需复杂配置文件
• 环境变量驱动：所有额外配置通过环境变量设置，便于容器化部署
• SSL支持：可通过SSL证书文件配置HTTPS，或使用AUTO_SSL生成自签名证书
• 响应头自定义：通过HEADER_前缀的环境变量添加自定义响应头（如HSTS、CSP等）
• 灵活日志：支持将请求日志输出到stdout、文件或syslog，可自定义日志格式

使用场景和适用范围

• 容器化环境中为gunicorn或其他HTTP应用服务器快速部署反向代理
• 需要简化反向代理配置流程，避免手动编写nginx配置文件的场景
• 开发/测试环境中需快速启用HTTPS（通过自签名证书）的场景
• 需要自定义安全响应头或其他HTTP头的应用场景

详细使用方法和配置说明

开始使用

该镜像可从以下仓库获取：

• Docker Hub: https://hub.docker.com/r/luhn/gunicorn-proxy
• AWS ECR: public.ecr.aws/luhn/gunicorn-proxy:1

源代码可从GitHub获取：https://github.com/luhn/docker-gunicorn-proxy/

基本运行要求：需提供一个参数——应用服务器的主机名和端口。容器默认在8000端口运行反向代理，并将所有请求转发至指定的应用服务器。

Docker运行示例：

bash
docker run -p 8000:8000 --link gunicorn luhn/gunicorn-proxy gunicorn:8080

配置参数

所有配置通过环境变量实现，以下是可用参数：

自定义响应头

通过设置以HEADER_为前缀的环境变量，可添加自定义响应头。变量名中的下划线会自动替换为连字符。

示例：

bash
docker run -e HEADER_STRICT_TRANSPORT_SECURITY="max-age=3153600" luhn/gunicorn-proxy app:8000

上述配置会在响应中添加头信息：STRICT-TRANSPORT-SECURITY: max-age=3153600

SSL配置

自定义SSL证书

当设置SSL_KEY和SSL_CRT时，代理将通过HTTPS提供服务。SSL配置基于Mozilla SSL配置生成器的中间兼容性配置。

使用示例：

bash
docker run -v /path/to/ssl:/ssl \
  -e SSL_KEY=/ssl/server.key \
  -e SSL_CRT=/ssl/server.crt \
  luhn/gunicorn-proxy app:8000

自签名证书

设置AUTO_SSL环境变量时，将自动生成自签名SSL证书。适用于容器位于负载均衡器（如AWS ALB）之后的场景，因为ALB不验证后端证书，且VPC内传输被认为是安全的。

使用示例：

bash
docker run -e AUTO_SSL=1 luhn/gunicorn-proxy app:8000

日志配置

通过LOG环境变量控制日志输出位置：

• stdout：输出到标准输出
• 文件路径（如/var/log/proxy.log）：输出到指定文件
• syslog:server=address：发送到syslog服务器（详见nginx syslog文档）

日志格式

默认使用nginx的"combined"日志格式：

$remote_addr - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"

可通过LOG_FORMAT自定义日志格式，详见nginx日志格式文档。若需JSON格式日志，可设置LOG_FORMAT_ESCAPE=json以转义日志值。

自定义日志格式示例：

bash
docker run -e LOG=stdout \
  -e LOG_FORMAT='{ "remote_addr": "$remote_addr", "status": "$status" }' \
  -e LOG_FORMAT_ESCAPE=json \
  luhn/gunicorn-proxy app:8000