radaisystems/nginx-dynamic-acm

NGINX Private ACM Proxy

镜像概述和主要用途

NGINX Private ACM Proxy是一个轻量级NGINX代理镜像，核心功能是从AWS ACM（AWS Certificate Manager）Private CA自动拉取证书，完成SSL配置并代理请求到指定目标URL。它通过环境变量简化配置，无需手动管理证书文件，适用于需要快速部署带有SSL终止功能的代理服务场景。

核心功能和特性

• 自动证书管理：从AWS ACM Private CA下载证书，自动配置私钥、证书链和密码文件
• 环境变量配置：通过简单的环境变量设置域名和代理目标，无需复杂配置文件
• 灵活的CA支持：可通过环境变量安装私有CA，适用于代理HTTPS后端服务的场景
• 调试模式：支持开启详细日志和环境变量打印，便于问题排查
• 动态配置注入：启动时自动替换配置文件中的令牌，确保配置与环境变量同步

使用场景和适用范围

• 需要将HTTP请求代理到后端服务，并通过AWS ACM Private CA提供SSL终止的场景
• 内部服务间的HTTPS代理，且证书由AWS ACM集中管理的环境
• 快速部署临时或测试环境的SSL代理，避免手动配置证书的繁琐流程
• 需要动态调整代理目标或域名的场景

环境变量配置

必选环境变量

可选环境变量

使用方法

基本运行示例

使用以下命令启动容器，替换示例中的环境变量值：

bash
docker run -d \
  -p 443:443 \
  -e FQDN=api.example.com \
  -e HTTP_PROXY_URL=http://backend-service:8080 \
  --name acm-proxy \
  nginx-private-acm-proxy

带私有CA的运行示例

如果需要代理到HTTPS后端服务并信任私有CA：

bash
docker run -d \
  -p 443:443 \
  -e FQDN=api.example.com \
  -e HTTP_PROXY_URL=https://secure-backend:443 \
  -e PRIVATE_CA_NAME=MyCorpCA \
  -e PRIVATE_CA_URL=https://internal-ca.example.com/ca.crt \
  --name acm-proxy-with-ca \
  nginx-private-acm-proxy

调试模式运行

开启调试模式以排查配置问题：

bash
docker run -it \
  -p 443:443 \
  -e FQDN=api.example.com \
  -e HTTP_PROXY_URL=http://backend-service:8080 \
  -e DEBUG=true \
  --name acm-proxy-debug \
  nginx-private-acm-proxy

自定义NGINX配置

默认配置文件（default.conf）包含SSL和代理所需的基础设置，并使用嵌入式令牌（如{{FQDN}}、{{HTTP_PROXY_URL}}）在启动时动态替换。如需自定义配置：

1. 从项目中获取默认配置文件（路径：conf/default.conf）
2. 根据需求修改配置内容（保留必要的令牌以便动态注入）
3. 将自定义配置文件挂载到容器的/default.conf路径

示例（使用本地自定义配置文件）：

bash
docker run -d \
  -p 443:443 \
  -e FQDN=api.example.com \
  -e HTTP_PROXY_URL=http://backend-service:8080 \
  -v /path/to/custom/default.conf:/default.conf \
  --name acm-proxy-custom-config \
  nginx-private-acm-proxy

注意：不要直接修改/etc/nginx/conf.d/default.conf，该文件会在启动时被自动覆盖。自定义配置必须挂载到/default.conf，由启动脚本处理后再移动到正确位置。