nginxproxy/acme-companion Docker 镜像 - 轩辕镜像 | Docker 镜像高效稳定拉取服务

![Tests]([] ![GitHub release]([]

acme-companion是nginx-proxy的轻量级配套容器。

它通过ACME协议处理代理Docker容器的SSL证书自动创建、续期和使用。

特性

• 使用acme.sh自动创建/续期Let's Encrypt（或其他ACME CA）证书。
• Let's Encrypt / ACME域名验证支持HTTP-01（默认）或DNS-01验证方式。
• 证书创建/续期时自动更新和重新加载nginx配置。
• 支持创建多域名（SAN）证书。
• 支持创建通配符证书（仅支持DNS-01验证）。
• 启动时创建强加密的RFC7919 Diffie-Hellman组。
• 兼容所有Docker版本。

HTTP-01验证要求

• 您的主机必须能通过端口80和443公开访问。
• 检查您的防火墙规则，不要尝试阻止端口80，否则会导致HTTP-01验证失败。
• 出于同样原因，不能使用nginx-proxy的HTTPS_METHOD=nohttp配置。
• 您要申请证书的（子）域名必须正确解析到主机。
• 如果您的（子）域名设置了AAAA记录，主机必须通过IPv6在端口80和443上公开可达。

如果无法满足这些要求，可使用DNS-01验证方式。详情请参考文档。

此外，请确保您的DNS提供商正确响应CAA记录请求。若DNS提供商响应错误，Let's Encrypt将不会为您的域名颁发证书。Let's Encrypt不要求域名设置CAA记录，只需DNS提供商正确响应即可。

!schema

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

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

• /etc/nginx/certs：存储证书和私钥（nginx-proxy容器为只读）。
• /usr/share/nginx/html：写入http-01验证文件。

此外，acme-companion容器需声明第三个卷以存储acme.sh配置和状态：/etc/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 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

启动acme-companion容器，通过--volumes-from获取nginx-proxy的卷：

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=***" \
    nginxproxy/acme-companion

该容器也需挂载主机docker socket，路径为/var/run/docker.sock。

虽然可选，但建议通过DEFAULT_EMAIL环境变量提供有效的默认***，以便Let's Encrypt在证书过期时提醒您并允许账户恢复。

步骤3 - 被代理容器

当nginx-proxy和acme-companion容器均启动后，启动需代理的容器时，需设置VIRTUAL_HOST和LETSENCRYPT_HOST环境变量，值为该容器使用的域名。

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

被代理容器必须暴露需代理的端口，可通过Dockerfile的EXPOSE指令或docker run/docker create的--expose标志实现。

若被代理容器监听并暴露的端口非默认80，可通过VIRTUAL_PORT环境变量强制nginx-proxy使用该端口。

例如使用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=***" \
    grafana/grafana

对其他需代理的容器，重复步骤3即可。

额外文档

请查看文档部分。