通配符证书免费版怎么落地:acme.sh v3.0.8、DNS-01 与 Nginx 自动续期 8 步
通配符证书免费版可以做到 0 元,但主流免费 DV 通配符证书有效期通常为 90 天,必须用 ACME DNS-01 验证并通过 acme.sh、certbot 等客户端自动续期。 用 acme.sh v3.0.8 签发时执行 `acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --keylength ec-256`,Cloudflare Token 只需 Zone.DNS:Edit 且限定到单个 Zone。 据 Let's Encrypt 文档,同一注册域默认限制为每周 50 张证书、每账户每主机名每小时 5 次失败验证,调试 DNS 时先用 `--staging` 避免打满限额。 Nginx 1.24 需同时配置 `ssl_certificate` 全链与 `ssl_certificate_key`,`*.example.com` 不覆盖 `example.com`,证书 SAN 必须同时包含根域和通配符。 验证命令 `openssl s_client -connect foo.example.com:443 -servername foo.example.com </dev/null | openssl x509 -noout -dates -ext subjectAltName`,剩余有效期低于 30 天应告警。
通配符证书免费版为什么不是“永久免费”?先看 ACME 与 DNS-01 的硬约束
“免费”指的是不收证书费,不等于证书不过期。据 Let’s Encrypt 官方文档(《Why ninety-day lifetimes?》),其证书有效期固定为 90 天,且不提供付费延长;ACME v2(RFC 8555)的设计前提就是“短周期 + 全自动续期”。acme.sh v3.0.8 默认在到期前 30 天(`–days 60` 即证书剩余 60 天时触发,实际默认阈值为 60 天剩余寿命)由 cron 任务续期。若 cron 未运行、DNS Token 失效或 `reloadcmd` 缺失,Nginx 仍加载旧证书,浏览器会直接报 `NET::ERR_CERT_DATE_INVALID`,此时用户看到的是整站红色警告,而不是“证书过期”这种温和提示。
为什么通配符证书必须走 DNS-01?Let’s Encrypt 明确不支持用 HTTP-01 签发通配符证书——因为 HTTP-01 只能证明你对某一个具体主机名的控制权,而 `*.example.com` 声称覆盖任意子域,CA 必须验证你对整个 DNS 区域的权威。于是只能采用 DNS-01:在 `_acme-challenge.example.com` 写入 TXT 记录,由 CA 从多个网络位置、多个递归解析器查询,任一视角失败即整体失败。典型报错:`DNS problem: NXDOMAIN looking up TXT for _acme-challenge.example.com` 或 `SERVFAIL`。acme.sh 的 DNS 模式默认等待传播(`–dnssleep`,默认 120 秒),也可设 `–dnssleep 0` 交由支持回调确认的 DNS API 插件立即继续。
调试务必用 staging,否则会撞速率限制。据 Let’s Encrypt 文档,生产环境限制为“每个注册域名每周 50 张证书”,且失败的验证也计入“每账户每主机名每小时 5 次失败”的限额。acme.sh v3.0.8 默认 CA 是 `https://acme-v02.api.letsencrypt.org/directory`,加 `–staging` 或显式指定 staging 目录即可切换,签发结果是浏览器不信任的测试证书,但流程完全一致:
# acme.sh v3.0.8 —— 同时覆盖根域与一级通配符;DNS-01 必需
export CF_Token="***" # Cloudflare API Token,仅授予 Zone:DNS:Edit,勿用 Global API Key
export CF_Account_ID="***"
acme.sh --issue --dns dns_cf
-d example.com -d '*.example.com' # 两个 -d 缺一不可,见下方匹配规则
--keylength ec-256 # 默认 2048 位 RSA;ec-256 体积更小、握手更快
--server https://acme-staging-v02.api.letsencrypt.org/directory # 调试期用 staging,避免计入生产限额
# 生产签发后安装并挂上重载命令(缺 reloadcmd 则 Nginx 永远用旧证书)
acme.sh --install-cert -d example.com --ecc
--key-file /etc/nginx/ssl/example.com.key
--fullchain-file /etc/nginx/ssl/example.com.fullchain.pem
--reloadcmd "nginx -t && systemctl reload nginx"
# 核对续期时间与到期日
acme.sh --list # Next Renew 列即为触发时间
openssl x509 -in /etc/nginx/ssl/example.com.fullchain.pem -noout -enddate
为什么必须同时签 `example.com` 和 `*.example.com`?据 RFC 6125 §6.4.3,通配符只能替代最左侧一个 DNS 标签,且不匹配裸域。所以 `*.example.com` 命中 `a.example.com`,但不命中 `a.b.example.com`(两个标签)也不命中 `example.com`(零个标签)。把两者放进同一张证书的 SAN 是通行做法,也是 acme.sh 单次签发即可搞定的。
| 维度 | HTTP-01 | DNS-01 |
|---|---|---|
| 能否签通配符 | 不能 | 能(Let’s Encrypt 唯一途径) |
| 前置条件 | 80 端口公网可达、无跳转拦截 | DNS API 凭据、TXT 记录可写 |
| 典型失败 | Connection refused / 301 跳转 |
NXDOMAIN / SERVFAIL / TXT 值不匹配 |
| 自动化风险点 | 防火墙、CDN 回源 | Token 权限过大(可改全 Zone)或过小(无法写 TXT) |
免费版还差在哪?免费 DV 只验证域名控制权,不做组织审核,证书 Subject 里只有 CN/SAN 域名、无 O/OU 字段,浏览器地址栏也不展示企业名。它适合博客、API 网关、SaaS 多租户测试环境;招投标、支付收单页面若要求 OV/EV 身份展示,免费通配符证书免费版无法替代商业证书。另一条常被忽略的约束是证书透明度:所有公开 CA 签发的证书都会写入 CT 日志(RFC 6962),内网域名一旦签成公共通配符证书,主机名即对外可查——这类场景应改用私有 CA(如 `step-ca`、OpenSSL 自建)而非公共免费证书。
通配符证书免费版选哪个 ACME 客户端?acme.sh、certbot、lego、Caddy 对比
如果你只是想给一台已有 Nginx 签发通配符证书免费版,最省事的答案是 acme.sh;如果是容器化或 CI 流水线,lego 更合适;Caddy 只在你能接受”由它接管 80/443″时才值得选。判断标准不是”谁免费”,而是三件事:你的 DNS 服务商是否被客户端原生支持、客户端能不能把证书安装进现有 Web 服务器、续期结果能否被 systemd 或 Prometheus 观测到。
| 客户端 | 当前版本 | 形态 | 内置 DNS API | 默认 CA | 装进现有 Nginx | 典型场景 |
|---|---|---|---|---|---|---|
| acme.sh | v3.0.8 | POSIX Shell,约 1 MB | 150+ | ZeroSSL(v3 起) | --install-cert + reloadcmd |
存量 Nginx 站群、纯 SSH 环境 |
| certbot | 2.11.0+(EFF 维护) | Python,DNS 按插件拆包 | 按插件安装 | Let’s Encrypt | 需 deploy-hook 或改 Nginx 配置 | Debian/Ubuntu 官方源、审计要求明确 |
| lego | v4.19+ | Go 单文件二进制 | 100+ | Let’s Encrypt | 需自行复制并 reload | 容器、CI、K8s Job |
| Caddy | 2.8+ | 自带 Web 服务器 | 需 xcaddy 编译模块 | Let’s Encrypt(失败回退 ZeroSSL) | 不接管 Nginx,只能做前置反代 | 新项目、统一入口 |
acme.sh 最容易踩的坑是默认 CA。v3 系列默认 CA 是 ZeroSSL,很多人签完发现链上不是 Let’s Encrypt。一条命令切回去,配置写入 ~/.acme.sh/account.conf,只需执行一次:
# 1) 安装(纯 Shell,无 Python/Go 依赖,解压后约 1 MB)
curl https://get.acme.sh | sh -s email=ops@example.com
# 2) v3 默认 CA 为 ZeroSSL,切到 Let's Encrypt(据 Let's Encrypt 文档,通配符必须走 DNS-01)
~/.acme.sh/acme.sh --set-default-ca --server letsencrypt
# 3) DNS-01 签发裸域 + 通配符,凭据用环境变量而非落盘
export CF_Token="你的Cloudflare-API-Token"
~/.acme.sh/acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --keylength ec-256
# 4) 安装到 Nginx 路径并注册续期后钩子(续期后自动 reload)
~/.acme.sh/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 "systemctl reload nginx"
安装脚本会自动写入 cron 任务(0 0 * * *,每天零点检查一次),续期阈值为 60 天(--days 60,可调),而 Let’s Encrypt 证书有效期是 90 天。certbot 2.11.0+ 由 EFF 维护,通配符必须装对应 DNS 插件,凭据文件权限必须是 600,否则 certbot 直接报错拒绝运行:
apt install -y certbot python3-certbot-dns-cloudflare # 包名带 python3- 前缀
install -m 600 /dev/null /root/.secrets/cf.ini
printf 'dns_cloudflare_api_token = %sn' "$CF_TOKEN" > /root/.secrets/cf.ini
certbot certonly --dns-cloudflare
--dns-cloudflare-credentials /root/.secrets/cf.ini
-d example.com -d '*.example.com'
--key-type ecdsa --deploy-hook "systemctl reload nginx"
# 证书落在 /etc/letsencrypt/live/example.com/,续期由 certbot.timer 驱动
lego v4.19+ 是 Go 单文件二进制,证书默认输出到当前目录的 .lego/certificates/,没有守护进程,续期要自己挂 cron(lego renew --days 30);较新版本需显式 --accept-tos 接受 CA 条款。Caddy 2.8+ 开箱自动 HTTPS,但 DNS-01 要先用 xcaddy 编译 caddy-dns/cloudflare 模块,等于把证书生命周期交给一个 Web 服务器——老 Nginx 站群用 acme.sh 改造,成本明显更低。
# lego:适合容器与 CI,一条命令签完即走
CLOUDFLARE_DNS_API_TOKEN="$CF_TOKEN" lego --accept-tos
--email ops@example.com --dns cloudflare
--domains example.com --domains '*.example.com' run
# Caddy:需自编译 DNS 模块,再用 Caddyfile 声明
xcaddy build v2.8.4 --with github.com/caddy-dns/cloudflare
# example.com, *.example.com {
# tls { dns cloudflare {env.CF_API_TOKEN} }
# reverse_proxy 127.0.0.1:8080
# }
最后提醒一个常见误解:免费的通配符证书只解决”身份信任”,不解决协议版本。据 Mozilla SSL Configuration Generator,现代服务端至少应启用 TLS 1.2 与 TLS 1.3,密码套件需在 Nginx 或负载均衡层单独写 ssl_protocols TLSv1.2 TLSv1.3;——证书换好了但 ssl_protocols 还留着 TLSv1.0,扫描依旧会告警。DNS 服务商被原生支持、证书能落到现有 Nginx、日志可被监控采集,这三点都满足再谈选型,才是通配符证书免费版真正能长期跑下去的前提。
通配符证书免费版完整实操:acme.sh v3.0.8 + Cloudflare DNS 的 6 个步骤
本节的 6 个步骤全部可复制执行,环境为 Debian/Ubuntu + Nginx 1.24+ + acme.sh v3.0.8,签发方式为 DNS-01(Cloudflare)。选 DNS-01 而不选 HTTP-01 的原因很直接:通配符证书只能通过 DNS-01 验证,这是 RFC 8555 与 Let’s Encrypt 文档明确规定的限制,`http-01` 无法证明你对 `*.example.com` 全体的控制权。
-
第 1 步:创建最小权限的 Cloudflare API Token。在 Cloudflare 控制台 My Profile → API Tokens → Create Token,用 “Edit zone DNS” 模板:权限 `Zone → DNS → Edit`,Zone Resources 选 `Include → example.com`。据 Cloudflare 官方文档,Token 只在创建时明文显示一次,刷新即不可再查看。
认证方式 环境变量 权限范围 建议 Global API Key CF_Key+CF_Email账号下所有 Zone 的全部权限 不要用:泄露等于整账号沦陷 Scoped API Token CF_Token仅 example.com 的 DNS 编辑 推荐:可随时单独吊销 # 保存 Token 到仅 root 可读的位置 mkdir -p /root/.secrets && chmod 700 /root/.secrets printf '%s' 'YOUR_CLOUDFLARE_API_TOKEN' > /root/.secrets/cf.token chmod 600 /root/.secrets/cf.token # 自检:返回 "success":true 说明权限配置正确 curl -s -H "Authorization: Bearer $(cat /root/.secrets/cf.token)" "https://api.cloudflare.com/client/v4/zones?name=example.com" | grep -o '"success":[a-z]*' -
第 2 步:安装 acme.sh 并固定 CA。acme.sh 从 3.x 起默认 CA 已改为 ZeroSSL,不显式固定会导致证书签发来源漂移、排障困难,因此必须执行
--set-default-ca,该值写入~/.acme.sh/account.conf的DEFAULT_ACME_SERVER。curl https://get.acme.sh | sh -s email=ops@example.com # 注册 ACME 账号邮箱 source ~/.bashrc # 加载 acme.sh 别名 acme.sh --set-default-ca --server letsencrypt # 固定 Let's Encrypt acme.sh --version # 期望:v3.0.8 -
第 3 步:先用 staging 试跑。Let’s Encrypt 正式环境对同一组域名有每周 5 张重复证书的速率限制,调试 DNS 权限时务必先打测试环境。
--dnssleep默认值为0,此处显式给 30 秒是为了给 Cloudflare 的 NS 传播留余量。export CF_Token=$(cat /root/.secrets/cf.token) acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --keylength ec-256 --staging --dnssleep 30 # --keylength 默认 2048(RSA),ec-256 即 ECDSA P-256,握手更快 -
第 4 步:去掉
--staging正式签发。注意-d example.com与-d '*.example.com'必须同时给:按 RFC 6125,通配符只匹配一级标签,*.example.com不覆盖裸域。acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --keylength ec-256 --server letsencrypt # 成功输出关键行: # [Mon Jan 6 10:12:31 UTC 2025] Cert success. # Your cert is in: /root/.acme.sh/example.com_ecc/example.com.cer -
第 5 步:安装证书并绑定 reload。
--install-cert会把路径和 reload 命令持久化到example.com_ecc/example.com.conf,此后每次自动续期都会自动复制并重载 Nginx。带--ecc是因为证书落在*_ecc目录,漏掉会报找不到证书。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.fullchain.pem --reloadcmd 'systemctl reload nginx' chmod 700 /etc/nginx/ssl && chmod 600 /etc/nginx/ssl/example.com.key # Nginx 侧:ssl_certificate 必须指向 fullchain,否则缺中间证书导致部分客户端链校验失败 # ssl_certificate /etc/nginx/ssl/example.com.fullchain.pem; # ssl_certificate_key /etc/nginx/ssl/example.com.key; -
第 6 步:确认自动续期任务真的存在。安装脚本会写入一条每日 cron;acme.sh 的
--days默认 60,即 90 天证书在第 60 天(到期前约 30 天)触发续期,这与 Let’s Encrypt 官方建议的续期窗口一致。crontab -l | grep acme.sh # 0 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null acme.sh --list # 查看 NextRenewTime 字段确认时间点 acme.sh --cron --force # 手动演练一次,验证 reloadcmd 与权限链路至此这套通配符证书免费版方案完全无人值守:Token 权限收敛到单域名 DNS、CA 固定为 Let’s Encrypt、续期只依赖 cron +
systemctl reload nginx,无需停机也无需人工介入。
配置示例:Nginx 1.24 + systemd timer 如何接住通配符证书免费版
Nginx 1.24 的 server 块怎么写,才能直接使用 acme.sh 签出的通配符证书?
把证书安装路径固定到 /etc/nginx/ssl/,由 acme.sh 的 --install-cert 负责写入证书文件,并同时写入 --reloadcmd;Nginx 配置里只引用这些固定的文件路径,不引用 ~/.acme.sh/ 下的临时目录。据 acme.sh 官方文档,--install-cert 会在每次续期成功后自动执行 reloadcmd,这是实现自动续期的关键。
# 签发后安装到 Nginx 目录,并绑定 reload 钩子(acme.sh v3.0.8)
/root/.acme.sh/acme.sh --install-cert -d example.com -d '*.example.com'
--key-file /etc/nginx/ssl/example.com.key
--fullchain-file /etc/nginx/ssl/example.com.fullchain.pem
--reloadcmd "systemctl reload nginx" # 必须 reload,不能 restart
# /etc/nginx/conf.d/example.conf
server {
listen 443 ssl http2; # Nginx 1.24 用此写法;1.25.1+ 才有独立 http2 指令
server_name example.com *.example.com;
ssl_certificate /etc/nginx/ssl/example.com.fullchain.pem; # 全链,不是 leaf
ssl_certificate_key /etc/nginx/ssl/example.com.key;
ssl_protocols TLSv1.2 TLSv1.3; # Mozilla 生成器 v5.7 的 Intermediate 配置同此
ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
}
为什么 ssl_certificate 必须指向 fullchain,而不是只指向域名证书本身?
只配置域名证书(leaf)时,Nginx 不会补发中间证书,客户端需要自行补齐证书链。Android 7.1 及更早版本的系统信任库不包含 Let’s Encrypt 的 ISRG Root X1,也不支持通过 AIA 扩展自动获取中间证书,因此会直接报 unable to get local issuer certificate。fullchain.pem 等于 leaf 加上中间证书,可以避免这个问题;RFC 5280 第 6 节要求的证书路径构建,正是依赖这条链。
| 文件 | 内容 | 适用场景 |
|---|---|---|
cert.pem(leaf) |
仅域名证书 | 仅供内部签发校验,不可直接上线 |
fullchain.pem |
leaf + 中间证书 | Nginx ssl_certificate 的唯一正确选择 |
chain.pem |
仅中间证书 | 填 ssl_trusted_certificate,配合 OCSP stapling |
ECDSA P-256 证书对 OpenSSL 有什么版本要求?
TLS 1.3 和 ECDSA P-256 需要 OpenSSL 1.1.1 及以上版本。请执行以下命令确认版本:
openssl version -a # 期望 OpenSSL 1.1.1w 或 3.0.x
nginx -V 2>&1 | tr ' ' 'n' | grep -i openssl # 看 "built with OpenSSL x.y.z"
ldd $(command -v nginx) | grep libssl # 看运行库实际版本
如果 built with 的版本与 libssl.so 实际版本不一致,常见报错是 SSL_CTX_use_PrivateKey_file(...) failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch),或者 Nginx 启动时提示 cannot load certificate key。这种情况通常是因为用新版 OpenSSL 签发了 ECDSA 密钥,而运行时链接的仍是旧版 libssl。据 OpenSSL 官方文档,1.1.1 系列是首个支持 TLS 1.3 的长期支持版本。
systemd timer 怎么配,才能代替 crontab 来运行 acme.sh?
acme.sh 自带的 --cron 会检查证书是否进入 60 天续期窗口(默认 --days 60),因此每天运行一次即可,不需要频繁触发。
# /etc/systemd/system/acme-renew.service
[Unit]
Description=acme.sh renewal check
After=network-online.target
Wants=network-online.target
[Service]
Type=oneshot
ExecStart=/root/.acme.sh/acme.sh --cron --home /root/.acme.sh
# /etc/systemd/system/acme-renew.timer
[Unit]
Description=Daily acme.sh renewal
[Timer]
OnCalendar=*-*-* 03:15:00
RandomizedDelaySec=30m # 打散并发,避免撞 Let's Encrypt 速率限制
Persistent=true # 关机错过则开机补跑
[Install]
WantedBy=timers.target
# 生效与验证
systemctl daemon-reload
systemctl enable --now acme-renew.timer
systemctl list-timers acme-renew.timer --no-pager
journalctl -u acme-renew.service -n 50 --no-pager
续期后为什么只能用 reload,不能用 restart?
| 动作 | 连接影响 | 配置出错时 |
|---|---|---|
systemctl reload nginx / nginx -s reload |
平滑重载,旧 worker 处理完存量连接后退出 | 新配置校验失败则保留旧进程与旧证书,服务不中断 |
systemctl restart nginx |
断开全部连接,长连接/上传被中断 | 启动失败导致全站 502/无法访问 |
reload 失败时,acme.sh 会保留旧证书文件,不会把线上环境变成“没有证书”的状态。排查入口是 /root/.acme.sh/acme.sh.log;也可以用 tail -f 实时查看 reload 阶段的输出。
OCSP stapling 和 HSTS 要不要一起打开?
OCSP stapling 属于可选项,开启后客户端无需再单独访问 CA:
ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/example.com.fullchain.pem;
resolver 223.5.5.5 1.1.1.1 valid=300s; # 无 resolver 时 stapling 直接失效
resolver_timeout 5s;
如果上游网络屏蔽了 OCSP 响应端,日志会反复出现 ssl_stapling 相关告警,此时先关闭该选项,待网络恢复后再打开。HSTS(RFC 6797)必须后置启用:先用 return 301 https://$host$request_uri; 把 HTTP 流量导向 HTTPS,确认所有子域都被通配符证书覆盖后,再加 Strict-Transport-Security: max-age=31536000; includeSubDomains。否则未覆盖的子域会被浏览器强制跳转到 HTTPS 并直接报证书错误,而且 HSTS 的 max-age 在客户端侧无法回滚。
参数对比与方案选型表:通配符证书免费版的续期、权限与成本
三种方案到底差在哪?先看这张选型表
| 方案 | 有效期 | 验证方式 | 续期方式 | 年成本 | 适用场景 |
|---|---|---|---|---|---|
| Let’s Encrypt ACME 免费版 | 90 天 | DNS-01(通配符强制) | acme.sh Cron / Systemd Timer 自动 | 0 元证书费 + 约 1200 元隐性人力 | 有 DNS API、能跑自动化、接受 90 天周期 |
| 商业 DV 通配符 | 1 年 | DNS / 文件 / 邮箱 | 手动或厂商 API,一年一换 | 约 300–1500 元/年 | 需要发票、SLA、法务要求长有效期 |
| 自签通配符 | 自定义 | 无 | 手动重签 + 分发根证书 | 0 元 | 内网测试,客户端需导入根 CA |
关键判断点不是”免费 vs 付费”,而是你能否把 DNS-01 自动化跑通。通配符证书免费版只支持 DNS-01(据 Let’s Encrypt 文档,通配符必须走 DNS-01,因为 HTTP-01 无法证明对 *.example.com 的控制权),一旦 DNS API 打通,一张证书同时覆盖 example.com 与 *.example.com:
# acme.sh v3.0.8,一次签发主域 + 通配符,避免为每个子域单独申请
acme.sh --issue --dns dns_cf
-d example.com -d '*.example.com'
--keylength ec-256
--renew-hook "systemctl reload nginx" # 续期成功后自动热加载,避免手工重启
续期窗口怎么设?默认值是多少?
acme.sh v3.0.8 的续期阈值存在 account.conf 的 DEFAULT_RENEW='60'(单位:天),即剩余 60 天就开始续;certbot 的默认值是 renew_before_expiry = 30 days。对 90 天证书来说,剩余 30–35 天完成续期最稳妥——既躲开 Let’s Encrypt 的失败重试窗口,也给排障留出时间。把监控告警阈值统一设成 30 天:
# 查看 acme.sh 当前记录的续期天数与下次续期时间
acme.sh --info -d example.com | grep -Ei "renew|Le_RenewalDays"
# 线上实际到期时间(以服务端返回为准,比本地文件更可信)
openssl s_client -connect example.com:443 -servername example.com /dev/null
| openssl x509 -noout -enddate
# 输出示例:notAfter=Apr 12 08:31:07 2025 GMT
速率限制:为什么不能给每个子域签一张证书?
据 Let’s Encrypt 官方 Rate Limits 文档:同一注册域每周 50 张证书、每周 5 张重复(duplicate)证书、每账户每 3 小时 300 个新订单。若你有 200 个子域并逐个签发,第一次批量就会撞上 50 张/周的上限并报 too many certificates (50) already issued for this exact set of domains。正确做法是用 -d 一次带上主域和通配符,让 200 个子域共用 1 张证书、1 次续期。
DNS API 权限如何最小化?
Cloudflare 用 API Token 而非 Global Key,权限只勾 Zone → DNS → Edit,Zone Resources 选 Include → Specific zone → example.com;阿里云 RAM 的 AliyunDNSFullAccess 覆盖全账号所有域名,建议改成自定义策略,只放开解析记录的读写:
{
"Version": "1",
"Statement": [{
"Effect": "Allow",
"Action": ["dns:Describe*", "dns:AddDomainRecord", "dns:DeleteDomainRecord"],
"Resource": ["acs:alidns:*:*:domain/example.com"]
}]
}
成本怎么算才不亏?
免费版证书费为 0,但要投入 DNS API 配置、Cron/Timer、监控与故障处理。按每月 1 小时运维、人力 100 元/小时估算,年隐性成本约 1200 元,仍低于多数商业 DV 通配符的中位价。真正的分水岭是:若你的团队无人值守、且合规要求发票与 SLA,直接买商业证书更省心;若能接受自动化,通配符证书免费版在 TCO 上更优。
兼容性参数怎么选?
RSA 2048 位兼容性最广;ECDSA P-256 握手更快、证书体积更小,但 Android 7 以下的老终端可能握手失败。对外 API 网关建议先验证再切换,或短期双证书并存:
# 探测客户端/服务端能否协商纯 ECDSA 套件;返回空或 handshake failure 说明需保留 RSA
openssl s_client -connect api.example.com:443 -servername api.example.com
-cipher ECDHE-ECDSA-AES128-GCM-SHA256 &1
| grep -E "Cipher|Verify return code"
# 期望输出:Cipher : ECDHE-ECDSA-AES128-GCM-SHA256 / Verify return code: 0 (ok)
选型结论落到一句话:能自动化 DNS 且接受 90 天周期 → 走 ACME 免费版并配 30 天告警;有发票/SLA/长有效期硬约束 → 商业 DV 通配符;纯内网 → 自签并分发根证书。
常见错误与排查:通配符证书免费版报错信息对照
acme.sh v3.0.8 签发通配符证书免费版时,失败几乎都落在两处:DNS-01 的 TXT 记录没被 Let’s Encrypt 的验证节点看到,或 Nginx 加载了错误的证书/私钥文件。据 Let’s Encrypt 文档,通配符域名只能通过 DNS-01 校验(HTTP-01 不支持通配符),所以先按下表定位,再针对性处理。
| 报错关键字 | 根因 | 一条命令定位 |
|---|---|---|
DNS problem: NXDOMAIN looking up TXT for _acme-challenge.example.com |
TXT 未写入,或写到了错误的 Zone / 被 CNAME 带到别的 Zone | dig TXT _acme-challenge.example.com +short |
DNS problem: SERVFAIL looking up TXT for _acme-challenge.example.com |
权威 DNS 超时、DNSSEC 配置错误,或传播慢于 acme.sh 的等待时间 | dig @1.1.1.1 TXT _acme-challenge.example.com 与 @8.8.8.8 对比 |
Error add txt for domain:_acme-challenge.example.com + Invalid request headers / code=9103 |
Cloudflare Token 权限不足,或只读 Token;用 Global API Key 却没设 CF_Key/CF_Email |
curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" -H "Authorization: Bearer $CF_Token" |
nginx: [emerg] SSL_CTX_use_PrivateKey_file(...) failed ... key values mismatch |
证书与私钥不是一对(常见于手工拼错 fullchain 与 key) | openssl x509 -noout -modulus -in fullchain.pem | openssl md5 |
浏览器 NET::ERR_CERT_COMMON_NAME_INVALID |
*.example.com 只覆盖一级,不含 a.b.example.com |
openssl x509 -noout -ext subjectAltName -in fullchain.pem |
curl: (60) SSL: no alternative certificate subject name matches target host name |
SAN 未包含该主机名,或 Nginx 仍指向旧文件 | nginx -T | grep ssl_certificate |
为什么 NXDOMAIN 时 Cloudflare 的橙色云朵不影响结果?因为代理状态只作用于 A/AAAA/CNAME 的解析结果,TXT 查询直连权威 DNS,与是否代理无关。真正会出错的是你给 _acme-challenge.example.com 建了 CNAME 指向另一个 Zone(例如多级子域委派),此时 TXT 必须写到 CNAME 指向的那个 Zone 里。手工核对:
# 看 TXT 是否真的落地(+short 只输出值,空行即未写入)
dig TXT _acme-challenge.example.com +short
# 看是否被 CNAME 带到了别的 Zone,Answer 段出现 CNAME 就要去目标 Zone 写 TXT
dig _acme-challenge.example.com TXT +noall +answer
# 换公共解析器交叉验证,排除本地缓存与递归 DNS 干扰
dig @1.1.1.1 TXT _acme-challenge.example.com +short
dig @8.8.8.8 TXT _acme-challenge.example.com +short
SERVFAIL 又该怎么处理?两个解析器结果不一致,通常是权威 NS 响应超时或 DNSSEC 签名问题——用 dig +dnssec 看是否出现 status: SERVFAIL 且 ad 标志缺失。若只是传播慢,让 acme.sh 多等一会儿;不指定 --dnssleep 时 acme.sh 会自行轮询(默认约 20 秒一次),显式加长更稳:
# 手动签发时加 --dnssleep 120,单位秒;默认轮询间隔约 20s
acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --dnssleep 120
# 修改已有配置的等待时间(acme.sh v3.x 配置文件为 account.conf / *.conf)
acme.sh --issue ... --dnssleep 120 --force
Cloudflare 报 9103 到底缺什么权限?据 Cloudflare API 文档,code=9103 属于鉴权头无效。用 CF_Token 时只读 Token 不够,必须是 Zone.DNS:Edit,且 Zone Resources 要包含 example.com;若沿用 Global API Key,则必须在环境里同时设置 CF_Key 与 CF_Email,只设其中一个同样报这个错。
key values mismatch 怎么快速比对?RSA 用 modulus 的 MD5,ECDSA(Let’s Encrypt 默认已签发 ECDSA 链)没有 modulus,要用公钥派生值对比,据 OpenSSL 文档 pkey -pubout 输出标准 PEM 公钥:
# RSA:两行输出的 md5 必须完全一致
openssl x509 -noout -modulus -in /etc/nginx/ssl/fullchain.pem | openssl md5
openssl rsa -noout -modulus -in /etc/nginx/ssl/example.com.key | openssl md5
# ECDSA:对比公钥的 md5
openssl x509 -noout -pubkey -in /etc/nginx/ssl/fullchain.pem | openssl md5
openssl pkey -in /etc/nginx/ssl/example.com.key -pubout | openssl md5
为什么 curl 报 no alternative certificate subject name?先确认 SAN 里到底有什么:*.example.com 匹配 api.example.com,但不匹配 api.b.example.com,也不匹配裸域 example.com(必须单独加 -d example.com)。若 SAN 正确却仍报错,多半是 Nginx 还在用旧文件:acme.sh 的 --install-cert 只负责拷贝,重载要靠 --reloadcmd "systemctl reload nginx";排查时用 nginx -T | grep -n ssl_certificate 看实际加载路径,再用 openssl s_client -connect 127.0.0.1:443 -servername api.example.com /dev/null | openssl x509 -noout -ext subjectAltName 验证线上真正下发的那张证书。多级子域场景下,正确做法是同一张通配符证书免费版里放多个 SAN:-d example.com -d '*.example.com' -d '*.b.example.com',一次签发覆盖两级。
效果验证:如何确认通配符证书免费版已生效并会自动续期
证书签发成功不等于线上已经用上,更不等于 90 天后会自动更换。验证要分三层:外部握手看到的是哪张证书、本地文件里的 SAN 覆盖了哪些名字、续期任务下一次触发在什么时候。任何一层跳过,都可能出现”监控显示证书有效、但 api 子域已经过期三天”的情况。
第一层:从外部看真实握手结果。关键是必须带 -servername 触发 SNI,否则 Nginx 会返回 default_server 的证书,你验证的其实是另一个站点:
# 适用 OpenSSL 1.1.0+(含 3.x);-servername 触发 SNI,不能省
echo | openssl s_client -connect foo.example.com:443 -servername foo.example.com 2>/dev/null
| openssl x509 -noout -subject -issuer -dates -ext subjectAltName
# 期望输出(Let's Encrypt 目前单张证书有效期 90 天)
# subject=CN = *.example.com
# issuer=C = US, O = Let's Encrypt, CN = R11
# notAfter=Sep 12 03:14:07 2025 GMT
# X509v3 Subject Alternative Name:
# DNS:*.example.com, DNS:example.com
SAN 里必须同时出现 DNS:*.example.com 和 DNS:example.com——通配符不覆盖裸域,这是很多人第一次申请通配符证书免费版时踩的坑。据 Let’s Encrypt 文档,*.example.com 与 example.com 需在同一次 DNS-01 订单中作为两个标识提交。另外据 RFC 6125 与 CA/B Forum 基线要求,现代客户端只匹配 SAN,subject=CN 已不参与校验。
第二层:本地证书文件自检。-checkhost 自 OpenSSL 1.1.0 起提供,只读 SAN:
openssl x509 -noout -checkhost foo.example.com -in /etc/nginx/ssl/example.com.fullchain.pem
# 命中:foo.example.com does match certificate
# 未命中:foo.example.com does NOT match certificate
openssl x509 -noout -checkhost a.b.example.com -in /etc/nginx/ssl/example.com.fullchain.pem
# 输出 does NOT match —— 通配符按 RFC 6125 只匹配最左一级标签
第三层:多域名实测 + 续期调度。不要只测根域,至少覆盖 www、api、一个随机子域。--resolve 可绕过 DNS 直接打指定 IP(注意要带端口):
for h in example.com www.example.com api.example.com random.example.com; do
curl -svI "https://$h" --resolve "$h:443:203.0.113.10" 2>&1
| grep -E "SSL certificate verify|subjectAltName|expire date"
done
# 期望每行都出现:SSL certificate verify ok.
acme.sh --list # Renew 列 = 下次续期时间
acme.sh --info -d example.com # 看 Le_NextRenewTimeStr / Le_RenewalDays
systemctl list-timers acme-renew.timer # 使用 systemd 安装方式时
# NEXT LEFT LAST PASSED UNIT
# Tue 2025-06-17 00:00:00 CST 6h left Mon 2025-06-16 00:00:12 CST 17h ago acme-renew.timer
acme.sh v3.0.8 安装时默认写入每日 0 0 * * * 的 cron 或 acme-renew.timer,默认在到期前 60 天(Le_RenewalDays=60,可用 --days 调整,取值 1–90)开始尝试,因此 Renew 列通常落在 notAfter 前 30 天左右,属正常。
| 验证手段 | 检测点 | 能发现什么 | 盲区 |
|---|---|---|---|
openssl s_client |
线上握手 | Nginx 是否加载了新证书、SAN 是否完整 | 只测一个域名时漏掉其他子域 |
openssl x509 -checkhost |
本地文件 | 文件本身是否覆盖该主机名 | 不反映 Nginx 是否 reload |
curl --resolve |
指定后端 IP | 绕过 CDN/DNS,定位单机问题 | 需知道真实回源 IP |
acme.sh --list |
调度状态 | 续期任务是否还在 | 任务存在但 hook 失败 |
| blackbox_exporter | 持续监控 | 过期趋势与握手失败 | 需额外部署 |
线上化之后,用 blackbox_exporter 的 probe_ssl_earliest_cert_expiry(单位:Unix 秒)做长期告警,并同时盯 probe_success,否则证书有效但握手失败的场景不会触发:
# prometheus rules:剩余不足 30 天告警;握手失败单独告警
- alert: WildcardCertExpiringSoon
expr: probe_ssl_earliest_cert_expiry - time() < 30 * 24 * 3600
for: 1h
- alert: TLSHandshakeFailing
expr: probe_success{job="blackbox_tls"} == 0
for: 5m
最后用 CT 日志反查签发范围,确认没有把不该公开的子域写进 SAN:
curl -s 'https://crt.sh/?q=%25.example.com&output=json'
| jq -r '.[].name_value' | sort -u
# 需要 jq 1.6+;%25 是 % 的 URL 编码,即 *.example.com
若这里出现你并不认识的域名,说明某次申请用了过宽的通配符或多余的 -d 参数——证书透明日志不可撤回,只能尽快收窄后续签发范围。
上线检查清单:把通配符证书免费版纳入日常运维
上线之后,每天到底该盯哪几样东西?
把通配符证书免费版纳入运维的第一件事是台账化:acme.sh --list 的输出只存在个人电脑里,等于没有资产记录。建议每次续期后把输出落到 CMDB 或 Git 仓库,并逐项补齐下表字段。据 Let’s Encrypt 文档,公共证书有效期上限为 90 天且不可续期延长,所以台账的核心是”下次动作时间”而非”到期时间”。
| 台账字段 | 取值来源(acme.sh v3.0.8) | 为什么必须记 |
|---|---|---|
| Common Name | acme.sh --list 第 1 列 Main_Domain |
与 Nginx server_name 对齐,防止漏配站点 |
| SAN | 第 3 列 SAN_Domains | 通配符与裸域常混签,漏一个就出现告警或 404 |
| 签发 CA | 第 4 列 CA | acme.sh v3 默认 ZeroSSL,可用 --server letsencrypt 切回,CA 变更影响 CT 与速率限制 |
| 下次续期 | 第 6 列 Renew | 比证书真实 notAfter 早约 30 天,告警必须按此列算 |
| 验证方式 | acme.sh --info -d 域名 中的 Le_Webroot |
写的是 dns_cf 之类,换 DNS 服务商时必须同步改 |
| reload 命令 | Le_ReloadCmd | 漏配会”续期成功、线上仍是旧证书” |
# acme.sh v3.0.8:导出台账并入库
acme.sh --list > /srv/cmdb/acme-$(date +%F).txt
acme.sh --info -d '*.example.com' | grep -E 'Le_Domain|Le_Alt|Le_Webroot|Le_API|Le_Real|Le_ReloadCmd'
首次切换通配符证书免费版,怎么保证不断服?
选业务低峰窗口,旧证书目录整份留 7 天不删。--reloadcmd 里串上 nginx -t,让配置错误在 reload 前就失败,而不是把 443 打成 502。
cp -a /etc/nginx/ssl /etc/nginx/ssl.bak-$(date +%F) # 旧证书保留 7 天
acme.sh --install-cert -d example.com -d '*.example.com'
--key-file /etc/nginx/ssl/example.com.key
--fullchain-file /etc/nginx/ssl/example.com.fullchain.pem
--reloadcmd "nginx -t && systemctl reload nginx"
nginx -t && systemctl reload nginx # 手动演练一次
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null
| openssl x509 -noout -subject -issuer -dates -ext subjectAltName
到期告警设几级?续期失败谁来叫醒人?
按 30 / 14 / 7 天三级推送到 IM 与邮件;acme.sh --cron 失败返回非 0,连续 2 次才通知值班,避免单次 DNS 抖动造成误报,成功一次必须把计数清零。日志用 logrotate 的 maxsize(logrotate ≥ 3.8.1)而不是 size,因为 size 与 weekly 互斥。
acme.sh --cron --home /root/.acme.sh >>/var/log/acme-cron.log 2>&1
|| { n=$(($(cat /run/acme.fail 2>/dev/null || echo 0)+1)); echo $n >/run/acme.fail;
[ "$n" -ge 2 ] && /usr/local/bin/alert.sh "acme.sh 续期连续 $n 次失败"; }
# /etc/logrotate.d/acme-sh
/root/.acme.sh/acme.sh.log {
weekly
maxsize 100M # 超过 100MB 立即轮转,不等周末
rotate 8
missingok
notifempty
compress
copytruncate # acme.sh 持续写同一 fd,必须 copytruncate
}
DNS API Token 怎么管?
Token 每 90 天轮换,人员离职立即在 DNS 服务商侧撤销。Token 绝不写进 Nginx 配置或公开仓库——acme.sh 会把它落在 /root/.acme.sh/account.conf 的 SAVED_* 字段里,该文件与密钥目录都应是 600/700。轮换后执行一次 --renew --force 验证新 Token 可用,再删旧 Token。
install -d -m 700 /root/.secrets
printf 'SAVED_CF_Token="%s"n' "$CF_TOKEN" > /root/.secrets/cf.env
chmod 600 /root/.secrets/cf.env /root/.acme.sh/account.conf
acme.sh --renew -d example.com -d '*.example.com' --force
回滚时最容易踩什么坑?
只恢复证书、不恢复私钥,Nginx 会直接起不来:
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)
tar czf /backup/acme-$(date +%F).tgz /root/.acme.sh /etc/nginx/ssl # 证书与私钥同备份
# 配对校验:ECDSA(acme.sh v3 默认 ec-256)用公钥比对,RSA 可用 -modulus
openssl x509 -pubkey -noout -in example.com.fullchain.pem | openssl md5
openssl pkey -pubout -in example.com.key | openssl md5
合规上还要检查什么?
据 RFC 6962,公共 CA 签发的证书会进入 CT 日志并公开域名,内网域名、测试域名不要签公共证书,用内部 CA 或 mkcert。对外服务确认 TLS 1.2/1.3、HSTS、OCSP stapling 与链完整:nginx 1.23.0 起 ssl_protocols 默认已是 TLSv1.2 TLSv1.3,但 ssl_stapling 默认仍为 off,需显式开启并配 resolver。
ssl_protocols TLSv1.2 TLSv1.3;
ssl_stapling on; # 默认 off
ssl_stapling_verify on; # 默认 off,需完整链 + resolver
resolver 223.5.5.5 valid=300s;
# 验收
openssl s_client -connect example.com:443 -servername example.com -status -tls1_2 </dev/null 2>/dev/null | grep -E 'OCSP response|Verify return code'
curl -sI https://example.com | grep -i '^strict-transport-security'
可以,Let's Encrypt 等免费 DV 通配符证书被主流浏览器信任,适合公开网站。但它没有 OV 组织信息和商业 SLA,有效期通常 90 天,必须配置自动续期与到期监控。
主要区别在有效期、赔付/SLA、发票与支持。免费版通常 90 天、0 元、社区支持;付费 DV 通配符常见 1 年、约 300–1500 元/年,提供商业支持和发票。两者在 TLS 加密强度上没有本质区别。
据 RFC 6125,通配符只匹配最左一个标签,`*.example.com` 匹配 `a.example.com`,不匹配 `a.b.example.com`。需要 `*.b.example.com` 或把具体主机名加入 SAN。
先执行 `dig TXT _acme-challenge.example.com +short` 确认记录是否存在,检查 API Token 是否写错 Zone、CNAME 是否指向别处。Cloudflare 的 TXT 记录 TTL 设 Auto 或 120 秒,传播慢时加 `–dnssleep 120`。
通常不会,ACME 客户端续期成功后才覆盖文件。但 `–install-cert` 的 reloadcmd 失败会导致 Nginx 仍加载旧证书,需查 `/root/.acme.sh/acme.sh.log` 并执行 `nginx -t`。
是证书与私钥不配对或路径指错。用 `openssl x509 -noout -modulus` 与 `openssl rsa -noout -modulus` 对比,ECDSA 用 `openssl pkey -pubout` 对比,确认 `ssl_certificate_key` 指向当前证书私钥。
可以,把 acme.sh 生成的 fullchain 和 key 导入 Secret,或使用 cert-manager 的 DNS-01 ClusterIssuer。注意 `*.example.com` 仍只覆盖一级子域,Ingress host 不要写两级通配符。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。