跳到主要内容
基础知识

Let’s Encrypt 通配符证书怎么申请?DNS-01 验证、certbot 命令与自动续期全流程(2025 版)

letsencrypt 通配符证书 — 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 端口。

  1. 安装 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 /snap

    snap 包内置独立 Python 运行时和 OpenSSL,不与发行版 Python 混用;RHEL 系系统 Python 受 dnf 保护,pip install certbot 极易在下次系统升级时把 certbot 依赖的 cryptography 顶掉。

  2. 安装 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-cloudflare dns_cloudflare_api_token 10 秒(--dns-cloudflare-propagation-seconds)
    阿里云 社区 certbot_dns_aliyun dns_aliyun_access_key_id 10 秒
    DNSPod 社区 certbot-dns-dnspod dns_dnspod_api_id 10 秒
    任意(acme.sh) 内置 dns_cf / dns_ali / dns_dp 环境变量导出 --dnssleep,默认不等待
  3. 准备 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。

  4. 先 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 张证书的配额,撞上了要等一周。

  5. 正式签发。去掉 --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)的链验证失败。

  6. 确认自动续期。--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 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

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