nginxproxy/acme-companion

https://github.com/nginx-proxy/acme-companion/actions/workflows/test.yml/badge.svg](https://github.com/nginx-proxy/acme-companion/actions/workflows/test.yml)

acme-companion是https://github.com/nginx-proxy/nginx-proxy%E7%9A%84%E8%BD%BB%E9%87%8F%E7%BA%A7%E9%85%8D%E5%A5%97%E5%AE%B9%E5%99%A8%E3%80%82

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

特性

• 使用https://github.com/acmesh-official/acme.sh%E8%87%AA%E5%8A%A8%E5%88%9B%E5%BB%BA/%E7%BB%AD%E6%9C%9FLet's Encrypt（或其他ACME CA）证书。
• Let's Encrypt / ACME域名验证支持HTTP-01（默认）或https://github.com/nginx-proxy/acme-companion/blob/main/docs/Let's-Encrypt-and-ACME.md#dns-01-acme-challenge%E9%AA%8C%E8%AF%81%E6%96%B9%E5%BC%8F%E3%80%82
• 证书创建/续期时自动更新和重新加载nginx配置。
• 支持创建https://github.com/nginx-proxy/acme-companion/blob/main/docs/Let's-Encrypt-and-ACME.md#multi-domains-certificates%E3%80%82
• 支持创建通配符证书（仅支持DNS-01验证）。
• 启动时创建强加密的RFC7919 Diffie-Hellman组。
• 兼容所有Docker版本。

HTTP-01验证要求

• 您的主机必须能通过端口80和https://github.com/nginx-proxy/acme-companion/discussions/873#discussioncomment-***%E5%85%AC%E5%BC%80%E8%AE%BF%E9%97%AE%E3%80%82
• 检查您的防火墙规则，不要尝试阻止端口80，否则会导致HTTP-01验证失败。
• 出于同样原因，不能使用nginx-proxy的https://github.com/nginx-proxy/nginx-proxy#how-ssl-support-works%E9%85%8D%E7%BD%AE%E3%80%82
• 您要申请证书的（子）域名必须正确解析到主机。
• 如果您的（子）域名设置了AAAA记录，主机必须通过IPv6在端口80和443上公开可达。

如果无法满足这些要求，可使用DNS-01验证方式。详情请参考https://github.com/nginx-proxy/acme-companion/blob/main/docs/Let's-Encrypt-and-ACME.md#dns-01-acme-challenge%E3%80%82

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

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

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

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

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

此外，acme-companion容器需声明第三个卷以存储acme.sh配置和状态：/etc/acme.sh。

另请阅读https://github.com/nginx-proxy/acme-companion/blob/main/./docs/Persistent-data.md%E6%96%87%E6%A1%A3%E3%80%82

使用示例：

步骤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=mail@yourdomain.tld" \
    nginxproxy/acme-companion

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

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

步骤3 - 被代理容器

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

https://github.com/nginx-proxy/nginx-proxy#usage%E6%8E%A7%E5%88%B6**nginx-proxy**%E7%9A%84%E4%BB%A3%E7%90%86%E9%85%8D%E7%BD%AE%EF%BC%8C%60LETSENCRYPT_HOST%60%E6%8E%A7%E5%88%B6**acme-companion**%E7%9A%84%E8%AF%81%E4%B9%A6%E5%88%9B%E5%BB%BA%E5%92%8CSSL%E5%90%AF%E7%94%A8%E3%80%82

只有同时设置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，可通过https://github.com/nginx-proxy/nginx-proxy#multiple-ports%E7%8E%AF%E5%A2%83%E5%8F%98%E9%87%8F%E5%BC%BA%E5%88%B6**nginx-proxy**%E4%BD%BF%E7%94%A8%E8%AF%A5%E7%AB%AF%E5%8F%A3%E3%80%82

例如使用https://hub.docker.com/r/grafana/grafana/%EF%BC%88%E6%9A%B4%E9%9C%B2%E5%B9%B6%E7%9B%91%E5%90%AC3000%E7%AB%AF%E5%8F%A3%EF%BC%89%EF%BC%9A

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" \
    grafana/grafana

对其他需代理的容器，重复https://github.com/nginx-proxy/acme-companion/blob/main/README.md#step-3---proxied-containers%E5%8D%B3%E5%8F%AF%E3%80%82

额外文档

请查看https://github.com/nginx-proxy/acme-companion/tree/main/docs%E3%80%82