acme-companion 独立证书（Standalone Certificates）配置指南：通过 `/app/letsencrypt_user_data` 为无容器依赖场景签发 ACME 证书

云原生运维【免费下载链接】acme-companionAutomated ACME SSL certificate generation for nginx-proxy项目地址https://gitcode.com/gh_mirrors/ac/acme-companion点击查看免费下载导读本文介绍 acme-companion 的Standalone certificates独立证书功能当你的域名并不对应某个被 nginx-proxy 代理的 Docker 容器时例如证书要用于宿主机直连的静态站点、非容器化服务、或 nginx-proxy 之外的其他 nginx 实例你无需为每个证书创建一个占位容器并设置ACME_HOST环境变量只需在容器内挂载一个用户配置文件/app/letsencrypt_user_data即可为任意域名签发和续期证书。读完本文你将掌握独立证书的运行前提卷共享要求、用户配置文件的语法与全部必选/可选参数、DNS-01 与 HTTP-01 挑战的配置方法、配置变更的拾取机制以及这些配置在 letsencrypt_service.sh 中对应的底层实现。为什么需要独立证书脱离容器环境变量的证书签发在 acme-companion 的基本用法中证书的签发完全由被代理容器上的ACME_HOST环境变量驱动docker-gen 扫描所有带ACME_HOST旧称LETSENCRYPT_HOST的容器生成/app/letsencrypt_service_data配置文件acme-companion 再依据该文件为对应域名签发证书详见 Basic-usage.md。但有些场景并不存在被代理的容器证书服务于宿主机上非容器化的 HTTPS 服务域名直接解析到宿主机但流量并不经过 nginx-proxy你需要为一个与任何 Docker 容器都无关的域名提前准备证书。此时仍然可以借助 acme-companion 完成证书的签发与续期办法就是挂载一个用户配置文件到/app/letsencrypt_user_data。该文件是 bash 变量与数组的集合语法与 docker-gen 生成的/app/letsencrypt_service_data完全一致——从源码看update_certs()会先source服务数据文件再source用户数据文件两者的变量随后被同一条证书签发链路消费letsencrypt_service.sh。运行前提必须共享的目录与卷使用独立证书功能除了挂载用户配置文件外还要求nginx-proxy 与 acme-companion 容器共享/etc/nginx/vhost.d和/etc/nginx/conf.d两个目录。如果采用三容器部署nginx、docker-gen、acme-companion 分离docker-gen 容器也必须共享这些目录详见 Advanced-usage.md。之所以需要共享这两个目录从 entrypoint.sh 可以看出只要检测到/app/letsencrypt_user_data存在启动流程就会强制检查/etc/nginx/vhost.d与/etc/nginx/conf.d是否可写。它们的用途分别对应 functions.sh 中的两个函数add_standalone_configuration()当域名的server_name未出现在 nginx 现有配置中时会在/etc/nginx/conf.d/下生成名为standalone-cert-domain.conf的独立 server 块专门应答/.well-known/acme-challenge/路径下的 HTTP-01 验证请求functions.sh若域名已存在于现有 nginx 配置则改走add_location_configuration()向/etc/nginx/vhost.d/对应文件追加 challenge location 配置functions.sh。典型的两容器部署如下。nginx-proxy 容器需显式声明vhost与conf两个卷docker run --detach \ --name nginx-proxy \ --publish 80:80 \ --publish 443:443 \ --volume certs:/etc/nginx/certs \ --volume vhost:/etc/nginx/vhost.d \ --volume conf:/etc/nginx/conf.d \ --volume html:/usr/share/nginx/html \ --volume /var/run/docker.sock:/tmp/docker.sock:ro \ nginxproxy/nginx-proxyacme-companion 容器通过--volumes-from继承卷并将本地配置文件只读挂载到/app/letsencrypt_user_datadocker 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 \ --volume /path/to/your/config_file:/app/letsencrypt_user_data:ro \ nginxproxy/acme-companion注意/etc/nginx/certs与/usr/share/nginx/html两个卷在基本用法中已经需要共享Basic-usage.md。如果独立证书全部走 DNS-01 挑战则无需共享/usr/share/nginx/html。用户配置文件语法与必选参数/app/letsencrypt_user_data是一个bash 脚本由一组普通变量与 bash 数组组成。acme-companion 在每次服务循环中直接source它因此文件中的语法错误会导致该次循环跳过用户数据源码中会出现Warning: could not source /app/letsencrypt_user_data的提示见 letsencrypt_service.sh。ACME_STANDALONE_CERTS证书标识符数组ACME_STANDALONE_CERTS是一个 bash 数组存放你所有独立证书的标识符identifier。每个元素必须唯一。这些标识符仅存在于容器进程内部永远不会出现在证书上也不会被外界看到——它们的作用与 docker-gen 生成的/app/letsencrypt_service_data中ACME_CONTAINERS数组的元素完全对等在 letsencrypt_service.sh 中ACME_STANDALONE_CERTS的元素会被逐个当作cid传入update_cert()与代理容器的容器 ID 走完全相同的证书处理路径。ACME_identifier_HOST域名数组对ACME_STANDALONE_CERTS中的每个标识符都必须有一个对应的ACME_identifier_HOST数组列出该证书要覆盖的域名。identifier必须与数组中的标识符逐字一致。数组的第一个域名是基准域名base domain决定证书文件的存放目录名。这与代理容器的行为一致源码update_cert()中hosts_array[0]被用作base_domain与证书目录名letsencrypt_service.sh。向后兼容LETSENCRYPT_STANDALONE_CERTS为兼容旧版本LETSENCRYPT_STANDALONE_CERTS仍可作为ACME_STANDALONE_CERTS的替代。源码中的回退逻辑为若ACME_STANDALONE_CERTS数组长度为 0则使用LETSENCRYPT_STANDALONE_CERTS的内容letsencrypt_service.sh。其他拥有LETSENCRYPT_旧名的变量可参考 Environment-variables-reference.md 中的对照表。单证书单域名最小示例ACME_STANDALONE_CERTS(uniqueidentifier) ACME_uniqueidentifier_HOST(yourdomain.tld)多证书多域名示例每个标识符对应一个 SAN 证书ACME_STANDALONE_CERTS(web app othersite) ACME_web_HOST(yourdomain.tld www.yourdomain.tld) ACME_app_HOST(myapp.yourdomain.tld myapp.yourotherdomain.tld service.yourotherdomain.tld) ACME_othersite_HOST(yetanotherdomain.tld)使用 DNS-01 验证的示例下面的配置中web与app使用全局/默认配置签发证书而othersite通过独立的 DNS-01 API 配置完成验证ACME_STANDALONE_CERTS(web app othersite) ACME_web_HOST(yourdomain.tld www.yourdomain.tld) ACME_app_HOST(myapp.yourdomain.tld myapp.yourotherdomain.tld service.yourotherdomain.tld) ACME_othersite_HOST(yetanotherdomain.tld) ACME_othersite_CHALLENGEDNS-01 declare -A ACMESH_othersite_DNS_API_CONFIG( [DNS_API]dns_cf [CF_Token]CLOUDFLARE_TOKEN [CF_Account_ID]CLOUDFLARE_ACCOUNT_ID [CF_Zone_ID]CLOUDFLARE_ZONE_ID )注DNS_API的值是 acme.sh 的 DNS API 名称如dns_cf对应 Cloudflare其余键值对依 DNS 服务商而异可参考 acme.sh 官方文档。acme-companion 固定使用某个版本的 acme.sh因此文档可能包含当前镜像中尚未提供的服务商。可选配置参数单值变量变量含义与取值ACME_identifier_EMAIL必须是合法邮箱用于 Lets Encrypt 在自动续期失败时向你发送证书即将过期的警告ACME_identifier_KEYSIZE决定所请求私钥的尺寸。合法值与ACME_KEYSIZE一致RSA2048/3072/4096/8192或椭圆曲线ec-256/ec-384/ec-521默认 4096详见 Lets-Encrypt-and-ACME.mdLETSENCRYPT_identifier_TEST设为true时为测试证书不受每周每域名 5 张证书的速率限制约束但由不受信任的中间 CA 签名浏览器不信任关于LETSENCRYPT_identifier_TEST的实现源码中该变量一旦为真ACME_CA_URI会被强制覆盖为 Lets Encrypt v2 staging 端点账户邮箱被清空、配置目录切换为staging证书目录还会加上_test_前缀letsencrypt_service.sh。DNS-01 相关变量ACME_identifier_CHALLENGE默认HTTP-01要切换到 DNS-01 ACME 挑战将其设为DNS-01。在 letsencrypt_service.sh 中该变量会先回退到全局ACME_CHALLENGE默认HTTP-01随后决定--issue使用--webroot还是--dns参数。注意HTTP-01 挑战不支持通配符证书*.example.com源码会在检测到通配符 base domain 时直接报错返回letsencrypt_service.sh。ACMESH_identifier_DNS_API_CONFIG默认回退到全局ACMESH_DNS_API_CONFIG该全局变量由 docker-gen 从 JSON/YAML 字符串解析为关联数组DEFAULT_ACMESH_DNS_API_CONFIG见 letsencrypt_service_data.tmpl。如果你希望为某个独立证书指定特定的 DNS-01 验证方法必须将其定义为bash 关联数组。DNS_API键始终必需可选DNS_SLEEP键可指定 acme.sh 等待 TXT 记录传播的秒数会被转换为--dnssleep参数letsencrypt_service.sh。示例declare -A ACMESH_alt_DNS_API_CONFIG( [DNS_API]dns_cf [CF_Token]CLOUDFLARE_TOKEN [CF_Account_ID]CLOUDFLARE_ACCOUNT_ID [CF_Zone_ID]CLOUDFLARE_ZONE_ID )从源码实现看ACMESH_cid_DNS_API_CONFIG的解析遵循默认配置 → 单证书配置的优先级若单证书关联数组存在且含DNS_API键则使用之否则回退到全局默认letsencrypt_service.sh。该机制与代理容器的ACMESH_DNS_API_CONFIG处理完全一致。拾取/app/letsencrypt_user_data的变更acme-companion 并不会主动监听watch该文件的变化。变更的生效时机有两种每小时服务循环acme-companion 的服务循环默认每 3600 秒执行一次CERTS_UPDATE_INTERVAL见 letsencrypt_service.sh每次循环都会重新source用户数据文件手动触发执行docker exec your-le-container-name-or-id signal_le_servicesignal_le_service实际上是向容器内的letsencrypt_service进程发送USR1信号signal_le_service.sh服务循环随即重新执行并拾取最新配置。代理到非 Docker 容器的场景如果你的用例是把流量代理到非 Docker 容器的其他服务例如宿主机上直接运行的进程请参考nginx-proxy官方文档中关于 proxy-wide 配置的说明。需要注意的是acme-companion 仓库不为这类代理问题提供支持代理相关的问题请到 nginx-proxy 项目寻求帮助。附录独立证书的完整处理链路从仓库源码可以完整还原一条独立证书的签发链路便于排查问题启动校验入口脚本检测到/app/letsencrypt_user_data存在后强制校验/etc/nginx/vhost.d与/etc/nginx/conf.d可写entrypoint.sh加载配置update_certs()依次source/app/letsencrypt_service_data与/app/letsencrypt_user_dataletsencrypt_service.sh生成挑战应答配置对每个走 HTTP-01 挑战的独立证书域名调用add_standalone_configuration()生成standalone-cert-domain.conf或走add_location_configuration()追加 location 配置然后reload_nginxletsencrypt_service.sh签发证书每个标识符作为cid传入update_cert()与代理容器的处理完全一致——包括账户注册、--issue参数组装密钥尺寸、挑战类型、OCSP、证书 profile、hooks 等与符号链接创建letsencrypt_service.sh清理签发完成后删除对应standalone-cert-*.conf文件并重载 nginxletsencrypt_service.shcleanup_links()则负责清除不再启用的域名符号链接letsencrypt_service.sh。相关测试可在 test/tests 目录中找到例如 certs_standalone/run.sh 即为独立证书场景的集成测试。结语独立证书功能把 acme-companion 的证书管理能力从容器环境变量驱动扩展到了任意域名驱动通过一个挂载的 bash 配置文件你就能复用整套 ACME 签发、续期与符号链接管理机制同时按标识符粒度单独定制邮箱、密钥尺寸、测试模式与 DNS-01 提供商配置。结合 Environment-variables-reference.md 与 Lets-Encrypt-and-ACME.md 阅读可以进一步掌握这些参数与代理容器参数之间的对应关系。赞分享云原生运维【免费下载链接】acme-companionAutomated ACME SSL certificate generation for nginx-proxy项目地址https://gitcode.com/gh_mirrors/ac/acme-companion点击查看免费下载相关推荐acme-companion 实战指南为 nginx-proxy 自动化签发与续期 ACME SSL 证书acme companion 实战指南为 nginx proxy 自动化签发与续期 ACME SSL 证书 本文围绕 nginx proxy 生态中的轻量级伴云原生运维认证与授权完全指南从 Session、JWT 到 OAuth 2.0 的后端身份安全实战认证与授权完全指南从 Session、JWT 到 OAuth 2.0 的后端身份安全实战 导读 认证Authentication与授权Authoriz云原生运维使用 lego 通过 Constellix DNS 提供商签发 ACME 证书DNS-01 挑战完整配置指南使用 lego 通过 Constellix DNS 提供商签发 ACME 证书DNS 01 挑战完整配置指南 本文以 legoLets Encrypt/A网络安全密码学上一篇neovim-flake调试技巧解决Nix配置中的常见问题下一篇TSF协程编程完全解析从同步代码到异步性能的魔法创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考