跳到主要内容
Nginx

通配符 SSL 证书申请与部署:acme.sh + Cloudflare DNS-01 + Nginx 实战

问题背景与根因:通配符证书为什么绕不开 DNS-01

通配符证书的 SAN 通常写成 *.example.com,它只覆盖同一级子域,例如 www.example.com、api.example.com,不覆盖主域名 example.com,也不覆盖 a.b.example.com。CA 在签发通配符时必须确认申请者对整个域名空间的控制权,HTTP-01 只能验证某一个具体域名的 80 端口路径,无法证明任意子域都归你控制,因此 ACME 规范要求通配符走 DNS-01:在 _acme-challenge.example.com 写入随机 TXT 值。照搬单域名教程执行 --webroot 常见报错是 Cannot issue for '*.example.com': The ACME server refuses... 或 Verify error:Invalid response from http://...。同时要注意有效期规则:公共 CA 证书最长 398 天,Let’s Encrypt 为 90 天,acme.sh 默认在到期前约 30 天续期。手工加 TXT 不可持续,所以正确方案是 acme.sh 调用 Cloudflare DNS API 自动增删记录,并用 cron 或 systemd timer 自动续期。若使用 CDN 代理,DNS-01 只关心 DNS 记录,不要求源站 80 端口暴露;但签发完成后仍需确认 443 证书链和 SNI 配置正确。

准备条件与 acme.sh 安装

准备三样东西:可修改 DNS 的域名、Cloudflare API Token、root 或可写 acme.sh 目录的账号。Token 最小权限为 Zone:Read 与 DNS:Edit,Zone Resources 只选 example.com。不要把 Token 写进命令历史,先落盘:install -d -m 700 /root/.secrets,printf '%s' 'TOKEN值' > /root/.secrets/cf_token,chmod 600 /root/.secrets/cf_token。安装 acme.sh:curl https://get.acme.sh | sh -s email=admin@example.com,然后 source ~/.bashrc,acme.sh --version。acme.sh 默认 CA 可能不是 Let’s Encrypt,签发时显式加 --server letsencrypt。如果系统没有 curl,先装 curl 与 openssl;CentOS 用 yum install -y curl openssl,Debian/Ubuntu 用 apt-get update && apt-get install -y curl openssl。检查 DNS API 是否可用:export CF_Token=$(cat /root/.secrets/cf_token),再执行 acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --server https://acme-staging-v02.api.letsencrypt.org/directory 做演练,避免正式环境触发速率限制。

用 Cloudflare DNS API 自动签发通配符证书

正式签发时把主域名和通配符一起写入 SAN,否则浏览器访问 https://example.com 会报证书名称不匹配。命令如下:export CF_Token=$(cat /root/.secrets/cf_token);如 Token 为账户级可再设 export CF_Account_ID='...' 和 export CF_Zone_ID='...';然后执行 acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --keylength ec-256 --server letsencrypt --dnssleep 30。--keylength ec-256 生成 ECC 证书,兼容现代浏览器;老系统可改用 --keylength 2048。--dnssleep 30 用于等待 TXT 记录传播,Cloudflare 通常几秒生效,遇到 NXDOMAIN 可加到 60。成功后会看到 Cert success,证书在 ~/.acme.sh/example.com_ecc/ 或 ~/.acme.sh/example.com/。不要手工复制该目录文件,下一步用 --install-cert 安装,否则续期后 Nginx 仍读旧文件。若只想覆盖通配符,可去掉 -d example.com,但主域名将不在证书内。

安装证书与 Nginx 配置示例

先建目录并安装证书: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'。如果签发时没用 ECC,去掉 --ecc。--fullchain-file 必须用完整链,不能只给叶子证书,否则部分客户端报 unable to get local issuer certificate。Nginx 示例:

server {
    listen 443 ssl;
    http2 on;
    server_name example.com *.example.com;
    ssl_certificate /etc/nginx/ssl/example.com.pem;
    ssl_certificate_key /etc/nginx/ssl/example.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    add_header Strict-Transport-Security 'max-age=31536000' always;
    location / { return 200 'ok'; }
}

私钥权限设为 chmod 600 /etc/nginx/ssl/example.com.key,属主 root。Nginx 1.25.1 之前若 http2 on; 不识别,可改成 listen 443 ssl http2;。Nginx 的 server_name *.example.com 可以匹配多级域名,但证书不会因此覆盖多级域名,证书覆盖范围只看 SAN。

通配符、多子域与 SAN 的覆盖边界

通配符只匹配一个标签,这是最常见的误解。覆盖边界如下:

证书 SAN 覆盖 不覆盖
*.example.com www.example.com、api.example.com example.com、a.b.example.com
example.com + *.example.com 主域名和一级子域 多级子域
*.sub.example.com a.sub.example.com sub.example.com、a.b.sub.example.com
多 SAN 精确域名 列表内域名 未列出的其他域名

需要 a.b.example.com 时,在申请命令中显式加 -d 'a.b.example.com';需要整段二级子域时,单独申请 -d '*.sub.example.com' -d 'sub.example.com'。不要把 *.*.example.com 当作可用写法,公共 CA 不接受。多个子域共用同一对 pem/key 即可,但每个域名必须出现在 SAN 中。部署时建议把 example.com 与 *.example.com 放在同一张证书,减少证书数量;若不同业务需要不同续期策略,再拆分证书。

验证方式与证书方案对比表

先看验证方式。HTTP-01 依赖 80 端口,不支持通配符;DNS-01 依赖 _acme-challenge TXT 记录,支持通配符;TLS-ALPN-01 依赖 443 端口,也不支持通配符。

验证方式 依赖 支持通配符 适用场景
HTTP-01 80/tcp 否 单域名、webroot
DNS-01 53/udp、TXT 是 通配符、无公网 80
TLS-ALPN-01 443/tcp 否 特定反代场景

再看证书方案。公共 CA 证书最长 398 天,Let’s Encrypt 为 90 天,acme.sh 默认约 60 天续期。

方案 SAN 示例 覆盖 续期
DV 单域名 example.com 精确域名 90 天
DV 通配符 *.example.com 一级子域 90 天
主域 + 通配符 example.com、*.example.com 主域和一级子域 90 天
多级通配符 *.sub.example.com sub 的一级子域 90 天

选择原则:只有一个主域名时用单域名;有大量一级子域时用主域 + 通配符;有多级子域时,为每个层级单独申请通配符或在 SAN 中逐个列出。不要为了省事把不相关域名塞进同一张证书,否则一个域名验证失败会影响整张证书续期。

常见错误排查(真实报错与修复)

1. Error add txt for domain:_acme-challenge.example.com,同时出现 code:9109 Invalid access token:Token 错误或缺少 DNS:Edit。重新创建 Token,确认 Zone Resources 包含 example.com,并重新 export CF_Token=$(cat /root/.secrets/cf_token)。

2. DNS problem: NXDOMAIN looking up TXT for _acme-challenge.example.com:记录未传播或加错 Zone。执行 dig TXT _acme-challenge.example.com @1.1.1.1 +short,没有值就加 --dnssleep 60,并检查是否把记录加到了子域 Zone。

3. Verify error:Invalid response from http://example.com/.well-known/acme-challenge/…:用 HTTP-01 申请通配符或 webroot 路径错。通配符必须用 --dns dns_cf,不要用 --webroot。

4. nginx: [emerg] cannot load certificate ‘/etc/nginx/ssl/example.com.pem’: BIO_new_file() failed:路径不存在或权限不足。执行 ls -l /etc/nginx/ssl/,确认 --install-cert 的 --fullchain-file 与 Nginx 配置一致。

5. The domain ‘example.com’ is not found in the list:安装时漏了 --ecc,或 --home 指向了别的 acme.sh 目录。用 acme.sh --list 查看,ECC 证书安装加 --ecc。

6. too many certificates already issued for exact set of domains:触发 Let’s Encrypt 速率限制。改用 staging 调试,正式证书等待窗口结束,不要反复 --force。排查时优先看 ~/.acme.sh/acme.sh.log,比终端摘要更完整。

效果验证与自动续期检查

验证证书链与 SAN:openssl x509 -in /etc/nginx/ssl/example.com.pem -noout -subject -issuer -dates -ext subjectAltName。在线验证 SNI:echo | openssl s_client -connect www.example.com:443 -servername www.example.com 2>/dev/null | openssl x509 -noout -dates -subject -ext subjectAltName。HTTP 验证:curl -I https://www.example.com。检查剩余有效期:openssl x509 -checkend 2592000 -noout -in /etc/nginx/ssl/example.com.pem,输出 Certificate will not expire 表示 30 天内不过期。续期检查:acme.sh --list,crontab -l | grep acme.sh,或 systemctl list-timers | grep acme。手动跑一次续期:acme.sh --cron --home /root/.acme.sh。签发后确认 TXT 已清理:dig TXT _acme-challenge.example.com +short 应为空。若续期成功但 Nginx 仍旧证书,检查 --reloadcmd 是否执行成功,先手动 nginx -t。建议监控证书到期时间,至少在到期前 14 天告警。

常见问题

不能。*.example.com 只匹配一级子域,如 www.example.com、api.example.com;主域名 example.com 必须单独加入 SAN。申请时同时写 -d example.com -d ‘*.example.com’,否则访问主域名会报证书名称不匹配。

HTTP-01 只能证明某一个具体域名的 80 端口路径可访问,无法证明申请者控制任意子域;ACME 规范要求通配符必须用 DNS-01,在 _acme-challenge.example.com 写入 TXT 记录。用 –webroot 申请会报 Invalid response 或策略拒绝。

不能。通配符只匹配一个标签,a.b.example.com 有两个标签。需要时在 SAN 中显式加入 -d ‘a.b.example.com’,或单独申请 *.sub.example.com 并同时加入 sub.example.com。

Let’s Encrypt 证书有效期为 90 天,acme.sh 默认在到期前约 30 天自动续期;公共 CA 证书最长不得超过 398 天。不要按一年有效期规划,务必保留 cron 或 systemd timer 并定期检查续期日志。

最小权限为 Zone:Read 和 DNS:Edit,Zone Resources 只授权 example.com。不要用 Global API Key。Token 落盘到 /root/.secrets/cf_token 并 chmod 600,通过 CF_Token 环境变量传给 acme.sh,避免写进命令历史。

先执行 nginx -t,再检查 acme.sh –install-cert 的 –reloadcmd 是否包含 nginx -s reload;确认 Nginx 配置指向 /etc/nginx/ssl/example.com.pem 而不是旧路径。手动运行 acme.sh –cron –home /root/.acme.sh 观察报错。

内容审核

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