Let’s Encrypt 通配符证书怎么申请?DNS-01 验证、certbot 命令与自动续期全流程(2025 版)
Let's Encrypt 通配符证书(*.example.com)只能用 DNS-01 验证签发,HTTP-01 会被 ACME 服务器直接拒绝;一张证书有效期固定 90 天,建议每 60 天续期一次。 certbot 申请命令核心是 certbot certonly --dns-cloudflare --dns-cloudflare-credentials /root/.secrets/cloudflare.ini -d example.com -d '*.example.com',通配符必须带单引号,且要同时写裸域名否则 example.com 本身不被覆盖。 速率限制:每个注册域名每周 50 张证书、每账户每 3 小时 300 个新订单、每主机名每小时 5 次验证失败,调试务必加 --dry-run 或指向 acme-staging-v02 环境。 自动续期靠 certbot.timer(每天两次带随机延迟)加 --deploy-hook "systemctl reload nginx",用 certbot renew --dry-run 演练可在不消耗正式配额的情况下验证整条链路。 验证生效看三处:certbot certificates 的 Domains 是否含 *.example.com、openssl x509 -ext subjectAltName 的 SAN 列表、以及 openssl s_client 握手返回的 notAfter 日期。
为什么 Let's Encrypt 通配符证书只能走 DNS-01?根因与硬性限制
为什么 *.example.com 用 HTTP-01 会被 CA 直接拒绝?
这是协议层硬约束,不是 certbot 的 bug。RFC 8555 §7.1.3 把通配符定义为受限标识符(wildcard domain name),Boulder(Let’s Encrypt 的 CA 实现)在创建订单阶段就校验挑战类型;据 Let’s Encrypt 官方《Challenge Types》文档,通配符证书“只能”用 dns-01。强行指定 HTTP-01 会拿到:
urn:ietf:params:acme:error:malformed :: Error creating new order ::
Cannot issue for "*.example.com": The ACME server refuses to issue a
certificate for this domain name, because it is a wildcard and the
challenge type is not dns-01.
根因很直接:HTTP-01 的验证点是 http://<host>/.well-known/acme-challenge/<token>,而 *.example.com 根本不是可解析的主机名,CA 无法向一个通配符发 HTTP 请求。dns-01 则只需查询 _acme-challenge.example.com 的 TXT 记录(值为 base64url(SHA-256(keyAuthorization))),这条记录天然覆盖该域下所有一级子域,一次查询即可证明你对整域的 DNS 控制权。
一张 *.example.com 到底覆盖哪些主机名?
| 主机名 | 是否被 *.example.com 覆盖 | 说明 |
|---|---|---|
| example.com | 否 | 裸域必须单独 -d |
| a.example.com | 是 | 仅匹配一级子域 |
| a.b.example.com | 否 | 需另签 *.b.example.com 或补精确 SAN |
所以申请 Let’s Encrypt 通配符证书时标准写法是同时下两个 -d,最终 SAN 为 DNS:example.com, DNS:*.example.com。'*.example.com' 的单引号不能省,否则会被 shell 当作 glob 展开:
# certbot 3.x / Python 3.9+;--manual 走 DNS-01,交互提示添加 TXT 记录
sudo certbot certonly --manual --preferred-challenges dns
-d example.com -d '*.example.com'
# 调试期先加 --dry-run:自动使用 staging 环境,不消耗生产速率限制
# sudo certbot certonly --manual --preferred-challenges dns
# -d example.com -d '*.example.com' --dry-run
90 天有效期对通配符有例外吗?续期何时触发?
没有例外,Let’s Encrypt 所有证书统一 90 天。certbot 的 renewal 配置默认 renew_before_expiry = 30 days,即剩余 30 天起才会真正续签;配合每天跑一次的定时任务(官方包自带 certbot.timer,可用 systemctl list-timers | grep certbot 确认),实际约每 60 天完成一次真实续期,留出 30 天容错窗口。
# /etc/letsencrypt/renewal/example.com.conf(certbot 自动生成,可手工微调)
[renewalparams]
authenticator = dns-cloudflare ; 换成你的 DNS 插件
renew_before_expiry = 30 days ; 默认值,可改 30/15 days
# 手动模拟续期,验证 DNS 凭据是否仍然有效
# sudo certbot renew --dry-run
调试通配符最容易撞上哪条速率限制?
据 Let’s Encrypt《Rate Limits》文档(2024 年后的现行值):
| 限制项 | 默认值 | 备注 |
|---|---|---|
| 每注册域名证书数 | 50 / 7 天 | 相同 SAN 集合的续期不计入 |
| 每账户新订单数 | 300 / 3 小时 | 一个订单不等于一张证书 |
| 每账户每主机名验证失败 | 5 / 小时 | 通配符调试最常撞的一条 |
| 完全相同 SAN 集合的重复证书 | 5 / 7 天 | 反复重签同一组名字会命中 |
所以每次改 DNS 凭据、换插件后,务必先 --dry-run;连续 5 次 TXT 写错就会进入 1 小时冷却。
我的 certbot 版本够用吗?
| 工具 | 支持通配符的最低版本 | 2025 主流稳定版 | 运行时前提 |
|---|---|---|---|
| certbot | 0.22.0(2018-03) | 3.x | Python 3.9+ |
| acme.sh | 2.x(DNS API 模式) | 3.0.x | POSIX shell |
| lego | 1.x | 4.x | Go 静态单文件 |
低于 0.22.0 的 certbot(例如部分老发行版仓库里的版本)根本无法完成 DNS-01 通配符签发,需先用 snap 或 pip 升级。
既然这么麻烦,为什么还值得用?
因为 DNS-01 要求 CA 能查到 _acme-challenge.example.com 的 TXT,你必须有 DNS 服务商 API 凭据,或搭 acme-dns 做 CNAME 委派——这就是 Let’s Encrypt 通配符证书比单域名证书“重”的根本来源。但一旦凭据打通,几十个子域只需一张证书、一条续期任务,运维成本反而从线性变成常数。
申请 Let's Encrypt 通配符证书的完整步骤(以 certbot + Cloudflare 为例)
据 Let’s Encrypt 官方文档《Challenge Types》,通配符域名(*.example.com)只能用 DNS-01 验证,HTTP-01 与 TLS-ALPN-01 一律被 ACME 服务端拒绝,这是 RFC 8555 之外 Let’s Encrypt 自己加的约束。下面以 certbot + Cloudflare DNS 为例走完全流程,每一步都可以直接复制执行。前提:域名已托管在 Cloudflare,服务器能出网访问 443 端口。
- 安装 certbot(用 snap,不要用 pip)。
# Ubuntu 22.04 / 24.04 sudo snap install --classic certbot sudo ln -s /snap/bin/certbot /usr/bin/certbot certbot --version # 期望输出:certbot 3.x.x # CentOS Stream 9 / Rocky 9 先装 snapd sudo dnf install -y epel-release sudo dnf install -y snapd sudo systemctl enable --now snapd.socket sudo ln -s /var/lib/snapd/snap /snapsnap 包内置独立 Python 运行时和 OpenSSL,不与发行版 Python 混用;RHEL 系系统 Python 受
dnf保护,pip install certbot极易在下次系统升级时把 certbot 依赖的cryptography顶掉。 - 安装 DNS 插件。
# Cloudflare(官方插件,随 snap 生态分发) sudo snap install certbot-dns-cloudflare # 阿里云(社区包 certbot_dns_aliyun,2024 年后仍在维护) pip install certbot-dns-aliyun # DNSPod(社区包) pip install certbot-dns-dnspod选择哪种方式,可参考下表:
DNS 服务商 插件来源 凭据字段 传播等待默认值 Cloudflare snap / pip certbot-dns-cloudflaredns_cloudflare_api_token10 秒( --dns-cloudflare-propagation-seconds)阿里云 社区 certbot_dns_aliyundns_aliyun_access_key_id10 秒 DNSPod 社区 certbot-dns-dnspoddns_dnspod_api_id10 秒 任意(acme.sh) 内置 dns_cf/dns_ali/dns_dp环境变量导出 --dnssleep,默认不等待 - 准备 API 凭据。据 Cloudflare 官方文档,应使用 API Token 而非 Global API Key:权限勾选
Zone:Zone:Read与Zone:DNS:Edit,Zone Resources 限定到具体域名,泄漏后影响面最小。sudo mkdir -p /root/.secrets sudo tee /root/.secrets/cloudflare.ini > /dev/null <<'EOF' # 只写一行,等号两侧各留一个空格 dns_cloudflare_api_token = 你的TOKEN EOF sudo chmod 600 /root/.secrets/cloudflare.ini sudo chown root:root /root/.secrets/cloudflare.ini阿里云则创建 RAM 子账号,只授予
AliyunDNSFullAccess,不要用主账号 AccessKey。 - 先 dry-run,不消耗配额。
sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials /root/.secrets/cloudflare.ini -d example.com -d '*.example.com' --agree-tos -m ops@example.com --non-interactive --server https://acme-staging-v02.api.letsencrypt.org/directory --dry-run看到
The dry run was successful.再往下走。Staging 环境不占用正式速率限制,能提前暴露 Token 权限不足、DNS 传播慢、域名拼写错误等问题——正式环境每周同一注册域名下有 50 张证书的配额,撞上了要等一周。 - 正式签发。去掉
--dry-run与--server,补上部署钩子:sudo certbot certonly --dns-cloudflare --dns-cloudflare-credentials /root/.secrets/cloudflare.ini -d example.com -d '*.example.com' --agree-tos -m ops@example.com --non-interactive --keep-until-expiring --deploy-hook "systemctl reload nginx"证书落在
/etc/letsencrypt/live/example.com/。Nginx 里只引用ssl_certificate .../fullchain.pem和ssl_certificate_key .../privkey.pem;fullchain.pem已包含cert.pem与chain.pem,单独引用cert.pem会缺中间证书,触发部分客户端(尤其 Android 与老版 Java)的链验证失败。 - 确认自动续期。
--deploy-hook会被写进/etc/letsencrypt/renewal/example.com.conf的[renewalparams]段,续期成功后自动重载 Nginx。systemctl list-timers | grep -i certbot # snap 安装:snap.certbot.renew.timer # 发行版包安装:certbot.timer sudo certbot renew --dry-run # 单独验证续期链路该 timer 每天触发两次(约 00:00 与 12:00 UTC 前后),并带最长 12 小时的
RandomizedDelaySec随机延迟,避免全球用户同时打 Let’s Encrypt 的接口;Persistent=true保证宕机期间错过的任务开机后补跑。certbot 只在剩余有效期不足 30 天时才真正续签,其余时间直接退出,因此一天两次的检查不会浪费配额。
Let's Encrypt 通配符证书的命令与配置示例(certbot / acme.sh / nginx)
先把结论说清楚:Let’s Encrypt 通配符证书只能走 DNS-01 验证,这是 CA/Browser Forum 基线要求与 Let’s Encrypt 官方文档共同规定的——通配符域名无法用 HTTP-01 校验,因为 ACME 服务器无从对 *.example.com 发起 HTTP 请求。所以下面的所有命令,核心都是“让客户端自动写一条 _acme-challenge.example.com TXT 记录”。ACME 协议本身见 RFC 8555 第 7.4.4 节(DNS-01 challenge)。
问:certbot 一条命令能不能搞定申请 + 部署?可以,但要把 --cert-name 显式写死,否则第二次申请同名证书时目录会变成 example.com-0001,nginx 里的路径就全错位了。
# 前提:pip/apt 安装 certbot 与插件,Cloudflare API Token 需 Zone:DNS:Edit + Zone:Zone:Read
sudo apt install certbot python3-certbot-dns-cloudflare # certbot 2.x / 3.x 均可
sudo mkdir -p /root/.secrets && sudo chmod 700 /root/.secrets
printf 'dns_cloudflare_api_token = %sn' "$CF_TOKEN" | sudo tee /root/.secrets/cloudflare.ini
sudo chmod 600 /root/.secrets/cloudflare.ini # 必须 600,644 会被 certbot 直接拒绝
sudo certbot certonly
--dns-cloudflare
--dns-cloudflare-credentials /root/.secrets/cloudflare.ini
--cert-name example.com # 固定证书目录名,避免 -0001 后缀
-d example.com -d '*.example.com' # 通配符必须加单引号,防 shell 展开
--agree-tos -m ops@example.com --non-interactive
--deploy-hook "systemctl reload nginx" # 首次签发与每次续期成功都会触发
成功时终端会打印(节选自 certbot 2.11 的真实输出):
Successfully received certificate.
Certificate is saved at: /etc/letsencrypt/live/example.com/fullchain.pem
Key is saved at: /etc/letsencrypt/live/example.com/privkey.pem
This certificate expires on 2025-xx-xx.
These files will be updated when the certificate renews.
问:续期配置长什么样,能手改吗?certbot 把状态写进 /etc/letsencrypt/renewal/example.com.conf,续期时以这个文件为准,所以你改 nginx 路径不改这里,续期照样走 DNS 插件。关键段落如下:
[renewalparams]
account = 1a2b3c... # ACME 账户 ID,勿改
authenticator = dns-cloudflare # 决定续期用哪种验证方式
dns_cloudflare_credentials = /root/.secrets/cloudflare.ini
server = https://acme-v02.api.letsencrypt.org/directory
key_type = ecdsa # certbot 2.0 起默认 ECDSA P-256
renew_before_expiry = 30 days # 90 天证书的默认提前量
renew_hook = systemctl reload nginx # 等价于 --deploy-hook
别手改
domains行。要增减域名,用sudo certbot certonly --cert-name example.com -d example.com -d '*.example.com' -d api.example.com重签,certbot 会自动重写该行;手改会导致续期时域名与归档证书不一致而报错。
nginx 侧只要三行证书指令加一行协议配置。注意 http2 on; 是 nginx 1.25.1 才引入的独立指令(见 nginx CHANGELOG),旧版仍写 listen 443 ssl http2;,两者混用会报 "http2" directive is duplicate。
server {
listen 443 ssl;
http2 on; # nginx >= 1.25.1;旧版删掉此行改用 listen 443 ssl http2;
server_name example.com *.example.com; # 通配符只匹配一级子域,多级需另签
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; # 必须 fullchain
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3; # 参考 Mozilla SSL Configuration Generator 的 intermediate 档
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
}
问:不用 certbot,acme.sh 怎么写?acme.sh 默认 --days 60 续期(比 certbot 的 30 天更早),靠安装时写入的 cron 每天检查一次,对经常抽风的 DNS API 更宽容:
export CF_Token="你的Cloudflare_Token" # acme.sh 读环境变量,不落盘更安全
acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --keylength ec-256
acme.sh --install-cert -d example.com
--key-file /etc/nginx/ssl/example.com.key
--fullchain-file /etc/nginx/ssl/example.com.crt
--reloadcmd "systemctl reload nginx" # 续期后自动 reload
至于更轻量的 lego 与 Caddy,写法如下。Caddy 2.8+ 内置自动续期,不需要 cron,但 Cloudflare DNS 模块需用 xcaddy build --with github.com/caddy-dns/cloudflare 编译,官方标准二进制不含该模块——这是新手最常踩的坑。
# lego:需先 export CLOUDFLARE_DNS_API_TOKEN=...
lego --email ops@example.com --dns cloudflare
--domains example.com --domains '*.example.com' run
# Caddyfile(Caddy 2.8+,自定义构建含 caddy-dns/cloudflare)
example.com, *.example.com {
tls {
dns cloudflare {env.CF_API_TOKEN}
}
respond "ok"
}
四者怎么选?按是否需要自动化、是否愿意装插件来定:
| 工具 | 通配符 DNS 插件 | 默认续期时机 | 适用场景 |
|---|---|---|---|
| certbot | 官方 python3-certbot-dns-*,覆盖主流海外 DNS |
到期前 30 天 | 已有 nginx/apache,想与 systemd timer 集成 |
| acme.sh | dnsapi/ 内置 150+ 家,含阿里云/DNSPod/华为云 |
到期前 60 天(--days) |
国内 DNS、纯 shell 环境、无 Python |
| lego | Go 库,编译进单二进制 | 到期前 30 天 | 容器/CI 中跑一次即走 |
| Caddy | 需 xcaddy 编译 dns.providers | 到期前约 30 天,全自动 | 新项目,不想维护证书脚本 |
国内 DNS 服务商的参数差异是另一处高频卡点,acme.sh 的写法对照如下(凭据同样 chmod 600):
| 服务商 | acme.sh 参数 | 凭据环境变量 |
|---|---|---|
| Cloudflare | --dns dns_cf |
CF_Token |
| 阿里云 DNS | --dns dns_ali |
Ali_Key / Ali_Secret |
| DNSPod(腾讯云) | --dns dns_dp |
DP_Id / DP_Key |
| 华为云 DNS | --dns dns_huaweicloud |
账号名 / 密码 / 项目相关变量,见 dnsapi/README.md |
最后提醒一个真实报错:若把 cloudflare.ini 留在 644,certbot 会直接中止并打印 Unsafe permissions on credentials configuration file: /root/.secrets/cloudflare.ini(部分插件版本包装成 Unauthorized 后退出),因为 ACME 凭据泄露等同于域名控制权泄露。chmod 600 是硬性前提,不是建议。
Let's Encrypt 通配符证书方案怎么选?工具、DNS 插件与验证方式对比
先把结论说清楚:据 Let’s Encrypt 官方文档《Challenge Types》,通配符域名(*.example.com)只能用 DNS-01 验证签发,HTTP-01 与 TLS-ALPN-01 都被明确排除。因此“选型”实际是两层:选签发工具,选 DNS 凭据通道。ACME 协议本身见 RFC 8555,通配符标识符的授权在 RFC 8555 §7.1.3 的 identifier 处理基础上由 CA 策略限定。
签发工具怎么选?下表按 2025 年主流版本对比,四者签出的证书完全等价(90 天有效期,续期窗口由客户端自定)。
| 工具 | 版本 | 依赖 | 自动续期 | 适用场景 |
|---|---|---|---|---|
| certbot | 3.x(需 Python 3.9+ 或 snap 包) | snap 版自带运行时,无需系统 Python | systemd timer(certbot.timer,每日两次)或 cron |
单机 nginx/Apache,生态与文档最全 |
| acme.sh | 3.0.x | 纯 Shell,无 Python 依赖 | 自带 cron,默认 60 天续期(--days 可改) |
容器、精简系统,国内 DNS 插件最全 |
| lego | 4.x | Go 单二进制 | 需自建定时任务 | 多机分发、与 Traefik 集成 |
| Caddy | 2.8 | 内置 ACME 客户端 | 进程内自动续期 | 新项目、反代入口统一 |
DNS 服务商没有 API 怎么办?三条路:换支持 API 的服务商、用 certbot-dns-acmedns / acme.sh 的 dns_acmedns 做 CNAME 委派、或退回 --manual(无法自动化,不推荐)。
| 服务商 | certbot 插件 | acme.sh 参数 | 凭据形式 |
|---|---|---|---|
| Cloudflare | certbot-dns-cloudflare | dns_cf |
API Token(推荐,权限 Zone:Read + DNS:Edit)或 Global Key |
| 阿里云 | certbot-dns-aliyun(社区) | dns_ali |
RAM 子账号 AccessKey(Ali_Key/Ali_Secret) |
| DNSPod | certbot-dns-dnspod(社区) | dns_dp |
ID + Token(DP_Id/DP_Key) |
| AWS Route53 | certbot-dns-route53 | dns_aws |
IAM 角色或 AK/SK |
| 无 API 权限 | certbot-dns-acmedns | dns_acmedns |
CNAME 委派到自建 acme-dns |
三种挑战到底差在哪?关键差别不在“能不能过”,而在“失败时你能不能远程排查”。
| 挑战类型 | 需开入站端口 | 能否签通配符 | 典型失败原因 |
|---|---|---|---|
| HTTP-01 | 需 80 端口公网可达 | 不能 | 安全组拦截 80、CDN 回源 404、.well-known 被重写规则吃掉 |
| DNS-01 | 不需要任何入站端口 | 能 | TXT 未生效、TTL 过长、记录名拼错(应为 _acme-challenge.example.com) |
| TLS-ALPN-01 | 需 443 且不能被反代占用 | 不能 | nginx 已监听 443,握手返回的是网站证书而非临时证书 |
certbot 3.x 一条命令签通配符(snap 安装,官方推荐路径):
# 1) 安装 certbot 与 Cloudflare 插件(snap 版允许插件以 root 运行)
sudo snap install --classic certbot
sudo snap set certbot trust-plugin-with-root=ok
sudo snap install certbot-dns-cloudflare
# 2) 写入凭据,权限必须 600,否则 certbot 直接拒绝读取
sudo install -d -m 700 /root/.secrets
sudo install -m 600 /dev/null /root/.secrets/cloudflare.ini
echo 'dns_cloudflare_api_token = 你的Token' | sudo tee /root/.secrets/cloudflare.ini
# 3) 签发;--dns-cloudflare-propagation-seconds 默认 10 秒,TTL 慢的域名调到 30~60
sudo certbot certonly
--dns-cloudflare
--dns-cloudflare-credentials /root/.secrets/cloudflare.ini
--dns-cloudflare-propagation-seconds 30
-d example.com -d '*.example.com'
--cert-name wildcard-example
# 4) 续期走同一份 lineage,renew 会复用上面的参数
sudo certbot renew --dry-run
acme.sh 3.0.x 有个坑必须先说:自 3.0.0 起 acme.sh 默认 CA 已改为 ZeroSSL,签 Let’s Encrypt 证书必须显式指定 --server letsencrypt,否则你拿到的不是 Let’s Encrypt 通配符证书。
curl https://get.acme.sh | sh -s email=admin@example.com
export CF_Token="你的Token"
export CF_Account_ID="你的AccountID"
# 显式指定 Let's Encrypt,并签发 ECC 通配符证书
~/.acme.sh/acme.sh --issue --server letsencrypt
--dns dns_cf -d example.com -d '*.example.com' --keylength ec-256
# 安装到 nginx 并设置 reload;acme.sh 会自动写入 cron(默认 60 天续期)
~/.acme.sh/acme.sh --install-cert -d example.com --ecc
--key-file /etc/nginx/ssl/example.key
--fullchain-file /etc/nginx/ssl/example.crt
--reloadcmd "systemctl reload nginx"
失败时最常看到的原始报错是 DNS problem: NXDOMAIN looking up TXT for _acme-challenge.example.com——九成是记录名多写了一级,或 CNAME 与 TXT 在同名节点冲突(RFC 1034 不允许)。
一张通配符还是五张单域名?据 Let’s Encrypt 速率限制文档,同一注册域名每周 50 张证书、同一组域名每周 5 张重复证书;子域超过 5 个且都由同一套 nginx 入口承载时,一张通配符在配额与运维条目上都更省。但风险是集中:私钥泄露影响全部一级子域,务必 600 权限、最小化分发节点、保留 30 天吊销重签预案。成本上 Let’s Encrypt 通配符证书为 0 元,真实成本在 DNS API 权限治理;商业 DV 通配符约 300–1500 元/年,OV 通配符普遍 2000 元以上且需企业材料。
申请 Let's Encrypt 通配符证书常见报错与排查(含真实错误信息)
申请 letsencrypt 通配符证书时,失败原因高度集中在三类:挑战类型选错、TXT 记录写错、账号触发限流。先按报错原文对号入座,再动手改命令,比反复重试省时间。
| 报错关键字(原文片段) | 根因 | 修复动作 |
|---|---|---|
| wildcard … challenge type is not dns-01 | 用了 HTTP-01 类插件(standalone/webroot/nginx) | 改用 DNS 插件或显式指定 dns 挑战 |
| DNS problem: NXDOMAIN looking up TXT | 记录名带星号、写错主机名、未传播 | 用 dig 直连权威/公共 DNS 验证 |
| Incorrect TXT record “…” found at | 同名 TXT 残留多条旧值 | 清理旧记录,TTL 降到 60–120 秒 |
| too many certificates already issued | 注册域名 7 天滚动窗口内超 50 张 | 等窗口释放或切 staging 调试 |
| too many failed authorizations recently | 同一账户+主机名 1 小时内失败 5 次 | 停手排查,等待 1 小时 |
| Invalid request headers / 403 Forbidden | API Token 权限或 Zone 范围不足 | 补权限后先列 zone 自检 |
Q:为什么 HTTP-01 插件签不了通配符?因为 ACME 协议规定通配符标识只能通过 dns-01 校验(见 RFC 8555 第 7.1.3 节对通配符的限制)。certbot 的 --preferred-challenges 默认值是 http-01,所以必须显式改。可用命令如下(certbot 2.x / 3.x 通用):
# 关键:--preferred-challenges dns 强制走 DNS-01;-d 后的星号必须加单引号
certbot certonly
--dns-cloudflare
--dns-cloudflare-credentials ~/.secrets/cf.ini
--preferred-challenges dns
-d 'example.com' -d '*.example.com'
--cert-name example.com
# 注意同时写裸域,否则 https://example.com 会证书不匹配
Q:NXDOMAIN 报错怎么三步定位?第一,通配符的 TXT 记录名不带星号,应是 _acme-challenge.example.com,写成 _acme-challenge.*.example.com 必然查不到;第二,若做了子域委派,记录应落在 _acme-challenge.sub.example.com;第三,DNS 传播未完成。绕开本地缓存直接问权威解析:
# 指定公共 DNS,跳过本机缓存;应返回 certbot 生成的 TXT 值
dig +short TXT _acme-challenge.example.com @1.1.1.1
# 对比权威 NS 的应答,确认是传播问题还是记录本身写错
dig +short NS example.com
Q:为什么提示 Incorrect TXT record?Let’s Encrypt 会读取该名字下全部 TXT 记录并逐一比对,只要残留一条旧值就失败。据 Let’s Encrypt 文档,校验节点不做缓存偏好,所以把 _acme-challenge 的 TTL 设为 60–120 秒(Cloudflare 默认 Auto 为 300 秒)能显著缩短清理窗口;续期时让插件自动增删,不要手工留旧值。
Q:限流报错只能等吗?是的。too many certificates already issued for: example.com 对应”每注册域名 7 天内 50 张”的滚动窗口,最多等 7 天;调试阶段一律加 --dry-run 或指向 staging(--server https://acme-staging-v02.api.letsencrypt.org/directory),staging 证书不受信任但不计入正式配额。
Q:Cloudflare / 阿里云权限怎么自检?Token 必须含 Zone:Read + DNS:Edit,且 Zone Resources 勾选目标域名;阿里云子账号常缺 AliyunDNSFullAccess。先用只读调用验证:
# 能列出 zone 才说明 Token 有效;返回 403 就是权限/范围问题
curl -s -X GET "https://api.cloudflare.com/client/v4/zones"
-H "Authorization: Bearer $CF_TOKEN" | head -c 300
Q:Shell 层还有哪些坑?zsh 下裸写 -d *.example.com 会报 no matches found: *.example.com,bash 则会把当前目录文件名展开进命令,导致证书里混入意外域名。始终写成 -d '*.example.com'。另一个高频问题是只签了通配符没签裸域——通配符证书不覆盖 example.com 本身,签发成功但首页仍报证书不匹配,务必在同一条命令里同时列出两个 -d。
如何验证 Let's Encrypt 通配符证书已生效?6 个可执行的检查点
签发成功不等于线上生效。下面 6 个检查点从本地文件一路验证到外部 CT 日志,逐层排查;全部通过后,才能说明这张 Let’s Encrypt 通配符证书真的可用了。命令均以 example.com 为例,需要 root 权限或 sudo 权限。
检查 1:本地证书清单是否包含裸域。据 Let’s Encrypt 文档,一张证书的有效期固定为 90 天,且证书覆盖的域名在申请时一次性确定。用 certbot certificates 查看证书管理库中的记录:
certbot certificates --cert-name example.com
# 期望输出片段:
# Certificate Name: example.com
# Domains: example.com *.example.com
# Expiry Date: 2025-12-08 07:12:33+00:00 (VALID: 89 days)
# Certificate Path: /etc/letsencrypt/live/example.com/fullchain.pem
如果 Domains 只列出 *.example.com,说明申请时漏掉了裸域;通配符不覆盖 example.com 本身,需重新签发:
certbot certonly --dns-cloudflare # 通配符只能走 DNS-01,必须用 DNS 插件或 --manual
--cert-name example.com
-d example.com -d '*.example.com' # 引号必须加,否则 shell 会展开 glob
检查 2:SAN 扩展与有效期。证书文件本身是最终依据:
openssl x509 -in /etc/letsencrypt/live/example.com/cert.pem -noout -text
| grep -A1 "Subject Alternative Name"
# X509v3 Subject Alternative Name:
# DNS:example.com, DNS:*.example.com
openssl x509 -in /etc/letsencrypt/live/example.com/cert.pem -noout -dates
# notBefore=Sep 9 07:12:33 2025 GMT
# notAfter =Dec 8 07:12:33 2025 GMT ← 距今应在 90 天内
检查 3:线上握手返回的是不是同一张证书。据 OpenSSL 文档,-servername 触发 SNI,避免拿到同 IP 下默认站点的证书:
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null
| openssl x509 -noout -subject -dates -ext subjectAltName
# 再把 -servername 换成 a.example.com 复测,应返回完全相同的 subject 与 notAfter
注意通配符只匹配一级标签(RFC 6125 §6.4.3),a.b.example.com 不会命中 *.example.com,需单独签发或改用 -d 追加。
检查 4:HTTP 层是否真正可用。
curl -sSI https://a.example.com | head -1
# HTTP/2 200
curl -vI https://a.example.com 2>&1 | grep -E "subject|expire date|SSL certificate verify"
# subject: CN=example.com
# expire date: Dec 8 07:12:33 2025 GMT
# SSL certificate verify ok.
# 若失败会看到:curl: (60) SSL: no alternative certificate subject name matches target host name
检查 5:外部视角。用 Qualys SSL Labs 跑一次评级,展开 Certificate #1,确认 Alternative Names 含 *.example.com;再到 crt.sh 搜 example.com。Let’s Encrypt 会把所有证书提交到 CT 日志(RFC 6962),通常几分钟内可查。这两步能排除“本地文件已更换、但 Nginx 仍在用旧证书”的常见情况。
检查 6:续期链路演练。据 Let’s Encrypt 文档,--dry-run 请求的是 staging 环境,不会消耗生产环境的速率限制,也不动线上证书:
certbot renew --dry-run --cert-name example.com
# Congratulations, all simulated renewals succeeded:
tail -n 50 /var/log/letsencrypt/letsencrypt.log | grep -i hook
# Running deploy-hook command: systemctl reload nginx ← 确认 hook 真的被触发
| 检查点 | 关键命令 | 通过判据 | 失败最常见原因 |
|---|---|---|---|
| 1 证书清单 | certbot certificates |
Domains 含裸域 + 通配符 | 申请时只写了 -d '*.example.com' |
| 2 SAN / 日期 | openssl x509 -text |
两个 DNS 条目,notAfter ≤ 90 天 | 读的是 chain.pem 或旧文件 |
| 3 SNI 握手 | openssl s_client -servername |
主域与子域返回同一 subject | 未启用 SNI / 默认站点抢答 |
| 4 HTTP 可用性 | curl -vI |
verify return code: 0 | 中间证书缺失,只配了 cert.pem |
| 5 外部审计 | SSL Labs / crt.sh | CT 日志可见新证书 | 服务未 reload,仍加载旧证书 |
| 6 续期演练 | certbot renew --dry-run |
all simulated renewals succeeded | DNS 插件凭据过期、hook 未执行 |
不能。*.example.com 只匹配一级子域,a.example.com 可以,a.b.example.com 不在覆盖范围内,且裸域 example.com 也不包含。需要的话就申请 -d example.com -d '*.example.com' -d '*.sub.example.com' 多个标识符,或为二级子域单独签一张 *.sub.example.com。
可以但无法全自动。方案一是 acme.sh 手动 DNS 模式,按提示添加 TXT 记录后回车继续,缺点是每次续期都要人工介入;方案二是用 acme-dns 把 _acme-challenge.example.com CNAME 到自建或托管服务,再由 certbot-dns-acmedns 插件写入,这样能恢复自动化,推荐生产环境使用后者。
看环境。单机 nginx/Apache、希望用官方工具和 systemd timer 的,选 certbot 3.x;容器、精简系统、国内 DNS 服务商多、不想装 Python 依赖的,选 acme.sh 3.0.x,它内置 dns_cf/dns_ali/dns_dp 且默认 60 天续期。两者签出的 Let's Encrypt 通配符证书完全等价,只是自动化路径不同。
先在签发机上执行 dig +short TXT _acme-challenge.example.com @1.1.1.1 确认记录是否存在且值匹配。常见原因是记录名写错(通配符的 TXT 名不带星号)、子域委派时写错层级、或 DNS 还没传播。把 TTL 调到 60–120 秒,等 1–2 分钟重试;若用 Cloudflare,注意不要开启会改写 TXT 的代理或防火墙规则。
功能上都是 DV 级别、都支持无限一级子域,差别在有效期与保障:Let's Encrypt 固定 90 天、无人工客服、无赔付;商业 DV 通配符通常 1 年期、价格约 300–1500 元/年,提供签发失败支持与保修。合规审计要求外部支持或需要 1 年免续期运维的团队会选商业证书,其余场景 Let's Encrypt 通配符证书足够。
多数是 reload 没执行或前面还有一层。检查 /etc/letsencrypt/renewal/example.com.conf 里的 renew_hook 是否存在,手动执行 systemctl reload nginx 后再用 openssl s_client 看 notAfter 是否变化;如果前面有 CDN 或负载均衡,需要在证书更新后同步上传到 CDN,并确认回源用的是最新 fullchain.pem。
单张证书的 SAN 上限是 100 个名称(Let's Encrypt 限制),通配符也计入其中,例如 -d example.com -d '*.example.com' 占 2 个。实际使用中建议一张证书控制在 10 个名称以内,便于排障与轮换;子域非常多时按业务线拆成多张通配符证书,避免单点私钥泄露影响过大。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。