remogloor/nginx-proxy-letsencrypt

acme-companion 镜像文档

镜像概述

acme-companion 是 https://github.com/nginx-proxy/nginx-proxy 的轻量级配套容器，通过ACME协议处理代理Docker容器的SSL证书自动创建、续期和使用，简化HTTPS配置流程。

核心功能和特性

• 自动化证书管理：使用 https://github.com/acmesh-official/acme.sh 自动创建/续期Let's Encrypt或其他ACME证书颁发机构的证书
• 验证方式：仅支持通过 http-01 挑战进行Let's Encrypt/ACME域名验证
• 配置自动更新：证书创建/续期后自动更新并重新加载nginx配置
• 多域名支持：支持创建多域名（SAN）证书
• 安全增强：启动时自动生成符合RFC7919标准的强Diffie-Hellman组
• 兼容性：兼容所有Docker版本

系统要求

• 主机必须可通过公网访问 80 和 443 端口（Let's Encrypt端口要求）
• 防火墙规则不得阻止80端口（会导致http-01挑战失败）
• 不可使用nginx-proxy的HTTPS_METHOD=nohttp配置
• 目标域名（或子域名）必须正确解析到主机IP
• DNS提供商必须正确响应CAA记录请求（CAA记录说明）
• 若域名设置AAAA记录（IPv6），主机必须通过IPv6公网可达80和443端口

!https://github.com/nginx-proxy/acme-companion/blob/main/schema.png

使用方法

基本使用流程（配合nginx-proxy容器）

nginx-proxy容器需声明三个可写卷，以便与acme-companion共享：

• /etc/nginx/certs：存储证书和私钥（nginx-proxy容器为只读）
• /etc/nginx/vhost.d：修改虚拟主机配置（CA需访问http-01挑战文件）
• /usr/share/nginx/html：写入http-01挑战文件

acme-companion容器需额外声明一个卷：/etc/acme.sh，用于存储acme.sh配置和状态。

步骤1 - 启动nginx-proxy

启动nginx-proxy容器并声明所需卷：

shell
$ docker run --detach \
    --name nginx-proxy \
    --publish 80:80 \
    --publish 443:443 \
    --volume certs:/etc/nginx/certs \
    --volume vhost:/etc/nginx/vhost.d \
    --volume html:/usr/share/nginx/html \
    --volume /var/run/docker.sock:/tmp/docker.sock:ro \
    nginxproxy/nginx-proxy

注：必须将主机的Docker socket（/var/run/docker.sock）挂载到容器内的/tmp/docker.sock，这是nginx-proxy的必要配置。

步骤2 - 启动acme-companion

通过--volumes-from继承nginx-proxy的卷，并启动acme-companion：

shell
$ docker run --detach \
    --name nginx-proxy-acme \
    --volumes-from nginx-proxy \
    --volume /var/run/docker.sock:/var/run/docker.sock:ro \
    --volume acme:/etc/acme.sh \
    --env "DEFAULT_EMAIL=mail@yourdomain.tld" \
    nginxproxy/acme-companion

注：

• 需将主机Docker socket挂载到容器内的/var/run/docker.sock
• 建议通过DEFAULT_EMAIL环境变量提供有效***，Let's Encrypt会通过该***发送证书过期提醒及账户恢复信息

步骤3 - 启动被代理容器

当nginx-proxy和acme-companion容器运行后，启动需代理的容器时，需设置以下环境变量：

• VIRTUAL_HOST：控制nginx-proxy的代理配置
• LETSENCRYPT_HOST：控制acme-companion的证书创建和SSL启用

证书仅会为同时设置了VIRTUAL_HOST和LETSENCRYPT_HOST，且域名正确解析到主机的容器颁发。

基本示例：

shell
$ docker run --detach \
    --name your-proxied-app \
    --env "VIRTUAL_HOST=subdomain.yourdomain.tld" \
    --env "LETSENCRYPT_HOST=subdomain.yourdomain.tld" \
    nginx

非默认端口示例（如Grafana，默认暴露3000端口）：

shell
$ docker run --detach \
    --name grafana \
    --env "VIRTUAL_HOST=othersubdomain.yourdomain.tld" \
    --env "VIRTUAL_PORT=3000"  # 指定容器暴露的端口
    --env "LETSENCRYPT_HOST=othersubdomain.yourdomain.tld" \
    --env "LETSENCRYPT_EMAIL=mail@yourdomain.tld"  # 可覆盖DEFAULT_EMAIL
    grafana/grafana

注：被代理容器必须暴露需代理的端口，可通过Dockerfile的EXPOSE指令或docker run的--expose参数实现。

额外文档

更多详细文档请参考 https://github.com/nginx-proxy/acme-companion/tree/main/docs%E3%80%82