跳到主要内容
Nginx

通配符证书申请与部署全流程:acme.sh + DNS-01 自动化(*.example.com)

一、问题背景:通配符证书为什么只能走 DNS-01

很多团队第一次申请 *.example.com 时会卡在验证环节:HTTP-01 挑战返回 404,或者 CA 直接拒绝为泛域名签发。根因在于 ACME 协议的验证模型——HTTP-01 需要 CA 访问 http://域名/.well-known/acme-challenge/<token>,TLS-ALPN-01 需要在 443 端口完成握手,两者都只能证明你控制了某一个具体主机。而 *.example.com 是一组不存在实体主机名的集合,CA 无法为它构造可访问的验证 URL,因此 RFC 8555 明确规定泛域名只能使用 DNS-01。

DNS-01 的逻辑是:CA 要求你在 _acme-challenge.example.com 下写入一条指定内容的 TXT 记录,能写入就证明你拥有该 DNS 区域的管理权,从而有资格获得该区域下的任意一级子域名。这也解释了通配符证书的两个硬性限制:

  • 不覆盖裸域。*.example.com 的 SAN 里只有 *.example.com,example.com 本身不在其中,必须用 -d example.com -d '*.example.com' 同时申请。
  • 只匹配一级。*.example.com 匹配 a.example.com,不匹配 a.b.example.com;后者要么单独申请 *.b.example.com,要么在 SAN 中显式列出。

还有一层现实压力:根据 CA/Browser Forum 规定,公有 SSL/TLS 证书最长有效期目前为 398 天;2025 年通过的 SC-081 提案将分阶段压缩到 200 天(2026-03-15)、100 天(2027-03-15)和 47 天(2029-03-15),Let’s Encrypt 目前仍为 90 天。这意味着手工签发、手工上传的流程必然失效,通配符证书必须走 API 自动化续期,否则迟早会因过期导致全部子域名同时不可用。

二、环境准备:acme.sh 安装与 DNS API 凭证

acme.sh 是纯 Shell 实现的 ACME 客户端,无外部依赖,支持 100 多家 DNS 服务商的 API 自动写记录。安装命令如下,安装器会自动写入一条 cron 任务:

curl https://get.acme.sh | sh -s email=ops@example.com
source ~/.bashrc
acme.sh --version
# 切换默认 CA(acme.sh v3 默认是 ZeroSSL,需额外注册)
acme.sh --set-default-ca --server letsencrypt

密钥类型:acme.sh v3 起默认使用 ec-256(P-256),证书保存在 ~/.acme.sh/example.com_ecc/ 目录,后续所有命令必须加 --ecc 才能命中;若要 RSA,显式指定 --keylength 2048,目录为 example.com。ECC 证书体积小、握手快,现代浏览器与 Android 7+ 均支持,推荐默认使用。

DNS API 凭证:以 Cloudflare 为例,在 My Profile → API Tokens 创建权限为 Zone:DNS:Edit + Zone:Zone:Read 的 Token,然后导出环境变量:

export CF_Token='你的Token'
export CF_Account_ID='你的AccountID'   # 部分账号场景需要
# 其他服务商:阿里云 dns_ali(Ali_Key/Ali_Secret)、DNSPod dns_dp(DP_Id/DP_Key)、
# AWS dns_aws(AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY)、GoDaddy dns_gd 等

凭证会被 acme.sh 写入 ~/.acme.sh/account.conf 供续期复用,务必 chmod 600。关于 CSR:acme.sh 会自动生成私钥与 CSR,无需手工 openssl req;若企业要求自备密钥(HSM 或固定密钥),可用 --csr /path/example.com.csr 提交,但此时 acme.sh 不再托管私钥,续期与部署需自行串联。

三、签发通配符证书:一条命令完成 DNS-01 验证

凭证就绪后直接签发,acme.sh 会调用 DNS API 自动写入 TXT 记录、轮询等待传播、触发 CA 校验,全程无需人工介入:

acme.sh --issue --dns dns_cf 
  -d example.com -d '*.example.com' 
  --keylength ec-256 
  --server letsencrypt

关键参数说明:

  • -d example.com 与 -d '*.example.com' 必须同时给出,前者覆盖裸域,后者覆盖一级子域,二者共用同一张证书。
  • 需要多级泛域名时追加 SAN:-d '*.api.example.com';需要具体子域时直接加 -d admin.example.com。
  • 首次签发会在 _acme-challenge.example.com 下写入两条同名 TXT(裸域与泛域各一条),这是正常现象,不要手动删除其中一条。
  • DNS 传播慢的服务商可加 --dnssleep 120 强制等待,或 --dnssleep 0 关闭等待(不建议)。
  • 调试阶段务必加 --staging 使用 LE 测试环境,避免触发正式环境限流。

若 DNS 服务商不支持 API,只能用手动 DNS 模式(无法自动续期,仅作应急):

acme.sh --issue --dns 
  --yes-I-know-dns-manual-mode-enough-go-ahead-please 
  -d example.com -d '*.example.com'
# 按提示添加 TXT 后执行续期动作完成签发
acme.sh --renew -d example.com --ecc 
  --yes-I-know-dns-manual-mode-enough-go-ahead-please

签发成功后产物位于 ~/.acme.sh/example.com_ecc/:example.com.key(私钥)、example.com.cer(站点证书)、ca.cer(中间证书)、fullchain.cer(站点 + 中间)。用 acme.sh --list 可查看所有证书及下次续期时间。

四、安装证书与 Nginx 配置示例

不要把 Nginx 直接指向 ~/.acme.sh 目录(该目录权限为 700,且续期时会变动)。正确做法是用 --install-cert 复制到固定路径并注册重载命令:

mkdir -p /etc/nginx/ssl
acme.sh --install-cert -d example.com --ecc 
  --key-file       /etc/nginx/ssl/example.com.key 
  --fullchain-file /etc/nginx/ssl/example.com.pem 
  --reloadcmd      "nginx -t && nginx -s reload"

该命令会在 ~/.acme.sh/example.com_ecc/example.com.conf 中写入 Le_ReloadCmd 等字段,之后每次 acme.sh --cron 续期成功都会自动复制文件并执行 reload,这才是“一次配置、长期有效”的关键。RSA 证书请去掉 --ecc。

Nginx 配置示例(多个子域共用同一对 key/pem,只需在 server_name 中列出):

server {
    listen 443 ssl;
    http2 on;                      # nginx < 1.25.1 请改为 listen 443 ssl http2;
    server_name example.com *.example.com;

    ssl_certificate     /etc/nginx/ssl/example.com.pem;   # 必须是 fullchain
    ssl_certificate_key /etc/nginx/ssl/example.com.key;

    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;
    ssl_session_cache   shared:SSL:10m;
    ssl_session_timeout 1d;
    ssl_session_tickets off;

    add_header Strict-Transport-Security "max-age=31536000" always;
}

两个易踩的坑:其一,server_name 中的 *.example.com 只匹配一级,a.b.example.com 需要另写 *.b.example.com 或显式域名;其二,必须部署 fullchain,只部署 example.com.cer 会让部分客户端(旧版 Android、Java 客户端、部分 curl)报 unable to get local issuer certificate。另外 Let’s Encrypt 已终止 OCSP 服务,为其证书配置 ssl_stapling on 没有实际收益,可省略。

五、单域名、多域名 SAN 与通配符证书对比

选型前先看清三者的能力边界,尤其是“新增子域是否要重签”和“私钥泄露的影响面”:

维度 单域名 DV 多域名 SAN 通配符(Wildcard)
覆盖范围 1 个 FQDN 显式列出的 N 个 FQDN 全部一级子域 + 显式 SAN
验证方式 HTTP-01 / DNS-01 HTTP-01 / DNS-01 仅 DNS-01
是否覆盖裸域 是 需显式列出 否,需单独加 SAN
是否覆盖多级子域 — 是(显式列出) 否,需另签 *.sub 或加 SAN
新增子域 重新签发 重新签发 无需重签,改配置即可
私钥泄露影响面 单站点 全部 SAN 站点 全部一级子域
有效期上限 398 天(LE 90 天) 398 天(LE 90 天) 398 天(LE 90 天)
典型适用场景 单一官网/API SaaS 自定义域名、跨主域业务 内部大量动态子域、CI 预览环境

实践建议:短生命周期、批量生成的子域(如 pr-1234.preview.example.com)用通配符,避免每周反复签发触发限流;对外提供的自定义域名必须用 SAN 显式列出,因为通配符无法覆盖客户自带域名;支付、管理后台等高价值资产建议单独签发独立证书并隔离私钥,避免一张通配符证书泄露导致全部子域同时可被中间人冒充。还需注意通配符证书会进入 CT 日志公开可查,crt.sh 上能直接搜到 *.example.com,但这不会泄露具体子域名单。

六、常见报错与排查

以下报错均来自真实签发/部署过程,按出现频率排序:

  • Verify error: DNS problem: NXDOMAIN looking up TXT for _acme-challenge.example.com - check that a DNS record exists for this domain —— API Token 权限不足或 Zone 选错。用 dig +short TXT _acme-challenge.example.com @1.1.1.1 确认记录是否真的写入;检查 Token 是否包含 Zone:DNS:Edit,以及 _acme-challenge 上是否存在遗留的 CNAME 冲突。
  • Verify error: Incorrect TXT record "jXk9..." found at _acme-challenge.example.com —— 旧的 TXT 未清理,或多值未同时生效。通配符与裸域会产生两条同名 TXT,必须同时存在;等待 TTL 过期后重试,或加 --dnssleep 120。
  • Error: urn:ietf:params:acme:error:caa :: CAA record for example.com prevents issuance —— 域名存在 CAA 记录但未授权该 CA。执行 dig CAA example.com,补充 example.com. CAA 0 issue "letsencrypt.org"。
  • too many certificates already issued for "example.com", retry after 2025-06-01T12:00:00Z —— 触发 LE 限流:同一注册域名每周 50 张、完全相同的证书每周 5 张。调试期一律加 --staging。
  • nginx: [emerg] SSL_CTX_use_PrivateKey_file("/etc/nginx/ssl/example.com.key") failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch) —— 私钥与证书不匹配,最常见原因是 ECC 与 RSA 混用:签发用 ec-256 却在 install-cert 时漏了 --ecc,导致把旧的 RSA 文件复制过去。用 openssl x509 -noout -modulus 与 openssl rsa -noout -modulus 比对指纹。
  • Reload error for : nginx: [emerg] ... —— 续期成功但 reloadcmd 失败,新证书未加载。先手动 nginx -t 定位语法错误,再 acme.sh --install-cert ... --reloadcmd 重新注册。
  • acme.sh: Please refer to https://curl.haxx.se/libcurl/c/libcurl-errors.html for error code: 6 —— 无法解析 ACME 服务端域名,通常是容器内 DNS 或出网代理问题,检查 /etc/resolv.conf 与防火墙 443 出站。

若一切正常但证书迟迟不续期,先查定时任务:crontab -l | grep acme 应能看到 "~/.acme.sh"/acme.sh --cron --home "~/.acme.sh",容器环境需改用 systemd timer 或外部调度器。

七、效果验证与续期监控

部署完成后不要只看浏览器绿锁,用命令行核对 SAN 与有效期才是可靠做法:

# 1. 检查本地证书文件的 SAN 与有效期
openssl x509 -in /etc/nginx/ssl/example.com.pem -noout -subject -dates -ext subjectAltName

# 2. 检查线上实际下发的证书(含中间链)
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null 
  | openssl x509 -noout -dates -ext subjectAltName

# 3. 检查多个子域是否共用同一张证书
curl -sI https://a.example.com | head -1
curl -sI https://b.example.com | head -1

# 4. 查看 acme.sh 管理的证书与下次续期时间
acme.sh --list

期望输出中 SAN 应同时包含裸域与泛域:

X509v3 Subject Alternative Name:
    DNS:example.com, DNS:*.example.com
notBefore=Jun  1 00:00:00 2025 GMT
notAfter=Aug 30 00:00:00 2025 GMT

反向验证“不覆盖多级子域”:访问 a.b.example.com 时 curl 会报 SSL: no alternative certificate subject name matches target host name 'a.b.example.com',说明该域名必须单独签发或加入 SAN。在线侧可用 SSL Labs 检查协议套件与证书链完整性,用 https://crt.sh/?q=example.com 确认证书已进入 CT 日志。

续期与监控:Let’s Encrypt 证书 90 天有效,acme.sh 在剩余约 30 天时自动续期,cron 每日执行一次即可。建议增加剩余天数告警脚本:openssl x509 -checkend 1209600 -noout -in /etc/nginx/ssl/example.com.pem || echo 证书将在14天内过期,把结果接入 Prometheus textfile collector 或 Zabbix。容器化部署时把 /etc/nginx/ssl 挂载为 volume,避免 Pod 重建后证书丢失。

常见问题

不能。*.example.com 只匹配一级子域名,裸域 example.com 不在其 SAN 列表中。申请时必须同时提交 -d example.com -d ‘*.example.com’ 两个参数,签发后证书的 SAN 会包含两条记录。若只部署通配符,直接访问主域名时浏览器会报证书名称不匹配。

公有 CA 签发的 SSL/TLS 证书有效期上限目前为 398 天,Let’s Encrypt 为 90 天。按 CA/Browser Forum 的 SC-081 提案,2026 年 3 月 15 日起降为 200 天,2027 年 3 月 15 日起 100 天,2029 年 3 月 15 日起 47 天,因此必须依赖 acme.sh 定时任务自动续期。

HTTP-01 与 TLS-ALPN-01 都需要 CA 访问一个具体主机名来完成校验,而通配符代表的是一组域名集合,无法构造出可访问的验证目标。RFC 8555 规定泛域名只能使用 DNS-01,即通过在 _acme-challenge 下写入 TXT 记录证明对 DNS 区域的控制权。

可以。私钥与证书文件可复制到任意多台服务器,只需保证 ssl_certificate 指向 fullchain、ssl_certificate_key 指向私钥,并设置 600 权限。但共享私钥会放大泄露风险,任一节点被入侵即可冒充全部一级子域,核心业务建议使用独立证书。

先执行 acme.sh –list 确认续期时间已更新,再检查 install-cert 生成的 renewal conf 中 Le_ReloadCmd 是否正确。若使用 ECC 密钥却漏了 –ecc,acme.sh 会去操作 RSA 目录导致文件未更新。手动运行 acme.sh –cron 观察输出可最快定位。

不支持。*.example.com 仅覆盖一级,a.b.example.com 必须单独申请 *.b.example.com,或在原证书 SAN 中显式加入该域名。注意每新增一条 SAN 都要重新签发整张证书,且多级泛域名同样只能通过 DNS-01 验证。

内容审核

长期从事 SSL/TLS 证书部署与 HTTPS 运维,负责本站证书选型、安装配置与故障排查内容的编写与审核。