通配符证书到期提醒怎么配?从根因到告警落地的 7 步实操指南
通配符证书到期提醒最可靠的做法是「双轨制」:ACME 客户端续期钩子(certbot --deploy-hook / acme.sh --reloadcmd)做续期后校验,外加 Prometheus blackbox_exporter 0.25 的 probe_ssl_earliest_cert_expiry 指标在剩余 21 天时告警,两条链路互相兜底。 certbot 2.11.0 对通配符只能走 DNS-01,续期默认在到期前 30 天触发(renewal conf 中 renew_before_expiry = 30 days),默认邮件提醒只在剩余 20 天和 10 天发送,窗口偏窄。 acme.sh 3.0.7 用 --days 60 控制提前量(默认 60 天),续期后通过 --reloadcmd "systemctl reload nginx" 自动生效,比手工 reload 少一次人为遗漏。 告警阈值建议分三档:剩余 30 天 info、21 天 warning、7 天 critical;Alertmanager 配 for: 10m、repeat_interval: 4h,critical 才走电话。 只靠 CA 邮件不够:一张通配符覆盖 *.example.com 全部一级子域,故障半径是单域证书的数倍,至少要有邮件、企业微信 webhook、监控指标三条独立通道。
通配符证书到期提醒为什么总是失效?6 个真实根因
先说结论:通配符证书的到期提醒之所以失效,通常不是因为忘了配告警,而是因为续期流程本身已经断了,告警只是最后才发现问题的那一环。一张 *.example.com 同时覆盖 api、static、admin、m 四个站点,证书过期时它们会在同一秒全部中断,影响范围是“全部一级子域”。据 Let’s Encrypt 官方文档,其签发的证书有效期固定为 90 天,建议在剩余 30 天内续期,也就是说一年至少有 4 次出错机会。下面按现场出现频率列出 6 个根因。
根因 1:只签了证书,cron 里根本没有续期任务。很多手工签发的环境连 renew 入口都不存在,提醒自然无从触发。先验证续期入口是否真的存在:
# 官方 deb/rpm 包会安装 systemd timer,源码/容器部署通常没有
systemctl list-timers | grep -E 'certbot|acme'
crontab -l | grep -Ei 'certbot renew|acme.sh --cron'
# 只演练、不真正签发;任何配置错误都会在这里暴露
certbot renew --dry-run --cert-name example.com
根因 2:通配符只能走 DNS-01,自动化断在 DNS 那一环。据 Let’s Encrypt《Challenge Types》文档,通配符域名必须使用 DNS-01 验证,即在 _acme-challenge.example.com 写入 TXT 记录。DNS API 凭据过期或权限不足时,很多团队干脆退回手工签发:
# 返回为空说明 DNS 插件/API 凭据没配好,renew 时必然卡死
dig +short TXT _acme-challenge.example.com
根因 3:默认提醒窗口只有 20 天,比企业的变更窗口还短。certbot 的邮件提醒仅在剩余 20 天和 10 天各发一次(且需在注册 ACME 账号时提供 --email,遵循 RFC 8555 的账号联系信息字段);acme.sh 默认不发任何邮件,只把下次续期时间写进 ~/.acme.sh/example.com/example.com.conf 的 Le_NextRenewTime。对需要 3–5 个工作日变更窗口的团队来说,20 天几乎等于“已经来不及”。
| 工具 / 版本 | 默认是否发到期邮件 | 默认触发时间点 | 状态记录位置 | 必须显式配置 |
|---|---|---|---|---|
| certbot 2.x | 是(依赖 --email 与可用 MTA) |
剩余 20 天、10 天各一次 | /etc/letsencrypt/renewal/*.conf |
--email、可用的本地邮件服务 |
| acme.sh 3.x | 否 | 不提醒,仅写 Le_NextRenewTime |
~/.acme.sh/<domain>/*.conf |
--notify-hook 或外部告警 |
根因 4:--manual 签发的证书,renew 注定失败。证书的续期参数会写进 renewal 配置文件,非交互 renew 会直接报错:
# /etc/letsencrypt/renewal/example.com.conf
[renewalparams]
authenticator = manual # ← 元凶:非交互环境下无法完成验证
manual_public_ip_logging_ok = True
An authentication script must be provided with --manual-auth-hook when using
the manual plugin non-interactively.
于是“续期失败”和“即将到期”同时发生,而邮件标题往往只写了前者,运维容易误判成临时故障。
根因 5:探针只看 HTTPS 状态码,不看 notAfter。证书过期前 TLS 握手仍可完成,拦截发生在浏览器端。更隐蔽的是,多数 uptime 探针为了兼容自签证书默认带 -k,于是过期当天照样返回 200:
# 探针视角:跳过校验,永远 200
curl -k -s -o /dev/null -w '%{http_code}n' https://api.example.com
# 真实客户端视角(curl 默认校验)
# curl: (60) SSL certificate problem: certificate has expired
# 浏览器:NET::ERR_CERT_DATE_INVALID
# 该监控的字段是 notAfter(OpenSSL x509 文档)
echo | openssl s_client -connect api.example.com:443 -servername api.example.com 2>/dev/null
| openssl x509 -noout -enddate
# notAfter=Apr 12 03:14:07 2025 GMT
根因 6:提醒收件人是 ACME 账号里的一个字符串,没人维护。人员离职、邮件网关调整 SPF/DKIM 策略,都会让提醒静默进入垃圾箱,而且没有二次确认和升级机制。定期核对:
certbot show_account 2>/dev/null | grep -i email
grep -iE 'ACCOUNT_EMAIL|Le_NextRenewTime' ~/.acme.sh/example.com/example.com.conf
这 6 条里只要第 1 条和第 4 条同时成立,任何告警平台都救不回来——它会在证书过期当天准确报警,然后告诉你一件 90 天前就已经注定的事。
从盘点 to 演练:搭建通配符证书到期提醒的 6 个步骤
-
步骤 1:先盘点,别急着配告警。据 Let’s Encrypt 文档,其证书有效期 90 天、到期前 30 天进入推荐续期窗口,而通配符证书只能通过 DNS-01 验证签发(RFC 8555 §7.1.3),这意味着续期链路比 HTTP-01 多一个 DNS API 依赖,盘点时必须连磁盘与线上两份一起看。
# OpenSSL 3.0.x:列出所有 lineage 的到期时间与主体 for f in /etc/letsencrypt/live/*/cert.pem; do echo -n "$f " openssl x509 -in "$f" -noout -enddate -subject done # 典型输出: # /etc/letsencrypt/live/example.com/cert.pem notAfter=Jun 12 03:14:07 2026 GMT # subject=CN = *.example.com # 核对线上实际下发的证书指纹,与磁盘文件比对 openssl s_client -connect www.example.com:443 -servername www.example.com </dev/null 2>/dev/null | openssl x509 -noout -fingerprint -sha256 openssl x509 -in /etc/letsencrypt/live/example.com/cert.pem -noout -fingerprint -sha256两份指纹不一致,九成是
nginx -t && systemctl reload nginx没执行成功——证书续了但进程还在用内存里的旧证书。这类”磁盘已新、线上仍旧”的静默失败,正是通配符证书到期提醒必须探测线上端口而非只读文件的原因。 -
步骤 2:统一续期方式,通配符一律走 DNS 插件。certbot 侧装
certbot-dns-cloudflare(2.11.0 与 certbot 2.11 配套),acme.sh 侧用dns_ali/dns_cf。凭据文件必须chmod 600、属主 root,且绝不能落在 Web 根目录或 Git 仓库里——Cloudflare API Token 泄露等于域名控制权泄露。# 用 install 原子创建凭据文件,权限一步到位(不要先 echo 再 chmod) install -m 600 -o root -g root /dev/null /etc/letsencrypt/cloudflare.ini printf 'dns_cloudflare_api_token = %sn' "$CF_TOKEN" >> /etc/letsencrypt/cloudflare.ini # certbot 2.11.x 签发通配符 certbot certonly --dns-cloudflare --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini -d '*.example.com' -d example.com # acme.sh 等价写法(凭据走环境变量,不落盘更佳) export Ali_Key="LTAI..." Ali_Secret="..." acme.sh --issue --dns dns_ali -d '*.example.com' -d example.com -
步骤 3:配续期后钩子,把”重载”和”上报”写死。certbot 自 0.17.0 起支持
--deploy-hook:首次签发和每次成功续期后都会执行;--renew-hook只在续期时执行且已不推荐。钩子里固定三件事:校验、重载、把新 notAfter 推给监控。# /usr/local/bin/post-renew.sh —— 由 certbot 注入 $RENEWED_LINEAGE #!/usr/bin/env bash set -euo pipefail nginx -t # 配置不合法就中止,certbot 会保留旧证书 systemctl reload nginx notafter=$(openssl x509 -in "$RENEWED_LINEAGE/cert.pem" -noout -enddate | cut -d= -f2) curl -fsS --data-binary "wildcard_notafter_seconds $(date -d "$notafter" +%s)" http://127.0.0.1:9091/metrics/job/certbot # 注册(写入 /etc/letsencrypt/renewal/example.com.conf 的 renew_hook) certbot renew --deploy-hook /usr/local/bin/post-renew.sh --dry-run钩子失败会以
Hook command "/usr/local/bin/post-renew.sh" returned error code 1出现在 certbot 日志里,配合set -euo pipefail能第一时间暴露nginx: [emerg] cannot load certificate ... BIO_new_file() failed这类路径或权限问题。acme.sh 的对应参数是--reloadcmd,通过acme.sh --install-cert -d example.com --reloadcmd "systemctl reload nginx"持久化。 -
步骤 4:建独立探测,别让告警依赖续期成功。blackbox_exporter 0.25.0 的 http 探针会输出
probe_ssl_earliest_cert_expiry(Unix 时间戳),Prometheus 2.53 以 1h 间隔抓取即可,日增样本量极小。# blackbox.yml modules: https_cert: prober: http timeout: 10s http: preferred_ip_protocol: ip4 tls_config: {insecure_skip_verify: false} # prometheus.yml - job_name: blackbox_tls scrape_interval: 1h metrics_path: /probe params: {module: [https_cert]} static_configs: - targets: ['www.example.com', 'api.example.com'] relabel_configs: - {source_labels: [__address__], target_label: __param_target} - {source_labels: [__param_target], target_label: instance} - {target_label: __address__, replacement: 127.0.0.1:9115}方案 版本/模板 抓取间隔 适用场景 blackbox_exporter + Prometheus 0.25.0 / Prometheus 2.53 1h( scrape_interval)已有 Prometheus 栈,需要多目标批量探测 Zabbix 6.4「Website certificate by Zabbix agent 2」 1h,历史保留 90d 已有 Zabbix,agent 2 直连目标端口 -
步骤 5:设阈值与路由,分级别一刀切。30 天 info(提醒续期窗口已开)、21 天 warning(DNS API 可能已出问题)、7 天 critical(必须人工介入)。Alertmanager 用
for: 10m抑制抖动、repeat_interval: 4h防轰炸;邮件组与企业微信 webhook 常驻,电话只给 critical。- alert: WildcardCertExpiringSoon expr: probe_ssl_earliest_cert_expiry - time() < 86400 * 30 for: 10m labels: {severity: info} annotations: summary: "{{ $labels.instance }} 证书 {{ $value | humanizeDuration }} 后到期" - alert: WildcardCertExpiringSoon expr: probe_ssl_earliest_cert_expiry - time() < 86400 * 7 for: 10m labels: {severity: critical} # alertmanager.yml 片段 route: receiver: mail group_by: [alertname, instance] repeat_interval: 4h routes: - matchers: ['severity="critical"'] receiver: phone repeat_interval: 1h -
步骤 6:季度演练 + 手工兜底 runbook。自签一张短有效期证书挂到测试站,验证 30/21/7 三档是否依次触发、路由是否落到正确的人。
# 5 天期证书:用于验证 critical 档与电话路由 openssl req -x509 -newkey rsa:2048 -nodes -days 5 -subj "/CN=expiry-drill.example.com" -keyout /etc/nginx/ssl/drill.key -out /etc/nginx/ssl/drill.crt nginx -t && systemctl reload nginx # 想同时验证 30 天档:造 35 天证书;或临时把告警阈值放大到 86400 * 40 openssl req -x509 -newkey rsa:2048 -nodes -days 35 -subj "/CN=drill35.example.com" -keyout /tmp/d35.key -out /tmp/d35.crtrunbook 必须写清三件事:DNS API 凭据的申请路径与最小权限范围(Cloudflare 用 Zone:DNS:Edit 的 scoped token)、手工续期命令(
certbot certonly --dns-cloudflare --force-renewal -d '*.example.com')、以及回滚步骤(从/etc/letsencrypt/archive/取上一版 fullchain 并重新 reload)。这套兜底决定了通配符证书到期提醒在自动化全链路失效时是否还有最后一道闸。
配置与命令示例:certbot 2.11、acme.sh 3.0.7、blackbox_exporter 0.25 怎么写
先回答最容易被踩的那个坑:certbot certonly -d '*.example.com' 里的单引号能不能省?不能。不加引号时 bash 会先把 *.example.com 当 glob 展开,当前目录没有匹配文件时字面量侥幸保留,一旦目录里存在 a.example.com 这类文件,certbot 就会收到一串意外的 -d 值,典型报错是 certbot: error: unrecognized arguments: index.html,或者更隐蔽地申请到一组错误域名。下面是 certbot 2.11.0 的完整签发命令,Cloudflare API Token 需具备 Zone:DNS:Edit 权限(据 Let’s Encrypt 官方 certbot 文档,dns-cloudflare 插件自 2.x 起只接受 API Token,不再支持 Global API Key):
# /etc/letsencrypt/dns-credentials.ini 内容(权限 chmod 600)
# dns_cloudflare_api_token = 你的Token
# certbot 2.11.0:签发泛域名 + 裸域,--cert-name 固定目录名便于后续引用
certbot certonly
--dns-cloudflare
--dns-cloudflare-credentials /etc/letsencrypt/dns-credentials.ini
-d '*.example.com' -d example.com
--cert-name wildcard-example
--deploy-hook '/usr/local/bin/cert-post.sh'
renew_before_expiry 决定”提前多久开始尝试续期”,写在 /etc/letsencrypt/renewal/wildcard-example.conf 的 [renewalparams] 段里,默认值就是 30 days。调到 21 days 能让告警窗口和续期窗口错开;但不建议低于 7 days——certbot 由 systemd timer 每小时触发一次并带随机延迟,DNS 服务商故障时你只剩约 168 次重试机会,一旦 Cloudflare API 抖动超过一天,证书就会真的过期。
# /etc/letsencrypt/renewal/wildcard-example.conf
[renewalparams]
authenticator = dns-cloudflare
renew_before_expiry = 21 days # 默认 30 days;下限建议 7 days
deploy-hook 在每次续期成功后执行,核心是”二次校验 + 告警 + 平滑重载 + 留痕”。openssl x509 -checkend 2592000 的 2592000 秒即 30 天,返回非 0 表示剩余不足 30 天,说明这次续期实际没换上有效证书:
#!/usr/bin/env bash
# /usr/local/bin/cert-post.sh,chmod +x;certbot 2.11.0 续期成功后调用
set -euo pipefail
CERT=/etc/letsencrypt/live/wildcard-example/cert.pem
if ! openssl x509 -checkend 2592000 -noout -in "$CERT"; then
# 2592000 秒 = 30 天,返回非 0 说明剩余不足 30 天
curl -s -X POST 'https://qyapi.weixin.qq.com/cgi-bin/webhook/send?key=你的KEY'
-H 'Content-Type: application/json'
-d "{"msgtype":"text","text":{"content":"通配符证书 ${CERT} 剩余不足 30 天,续期异常"}}"
exit 1 # 让失败进入 journalctl -u certbot-renew,便于二次告警
fi
nginx -t && systemctl reload nginx # nginx 1.24.0,先校验再 reload
echo "$(date -u +%s) $(openssl x509 -noout -enddate -in "$CERT")" >> /var/log/cert-renew.log
acme.sh 3.0.7 的写法更短,但 --days 的含义与 certbot 相反:它表示”剩余多少天时开始续期”,默认 60。把它设到 30 以下没有意义,只会让 acme.sh 更频繁地重签,撞上 Let’s Encrypt 的重复证书配额(每注册域名每周 50 张,报错为 too many certificates already issued for: example.com)。另外 acme.sh 3.x 默认 CA 已改为 ZeroSSL,要沿用 Let’s Encrypt 需显式加 --server letsencrypt:
# acme.sh 3.0.7;--days 默认 60,建议保持 45~60
acme.sh --issue --dns dns_ali -d example.com -d '*.example.com'
--days 60 --reloadcmd "systemctl reload nginx"
| 维度 | certbot 2.11.0 | acme.sh 3.0.7 |
|---|---|---|
| 续期触发阈值 | renew_before_expiry,默认 30 days |
--days,默认 60 |
| 调度方式 | systemd timer(每小时) | 自带 cron,acme.sh --install-cronjob |
| 续期后钩子 | --deploy-hook |
--reloadcmd |
| DNS 插件 | 需 python3-certbot-dns-* 单独安装 |
dns_ali/dns_cf 内置 |
| 默认 CA | Let’s Encrypt | ZeroSSL(需 --server letsencrypt 切换) |
被动等续期成功才告警是不够的,还需要外部探针。blackbox_exporter 0.25.0 的模块配置里,insecure_skip_verify 必须显式写 false,否则链上有自签证书也会被判 2xx,等于白探:
# /etc/blackbox_exporter/blackbox.yml —— blackbox_exporter 0.25.0
modules:
https_2xx:
prober: http
timeout: 5s
http:
preferred_ip_protocol: ip4 # 避免双栈下 IPv6 不可达造成误报
follow_redirects: true
tls_config:
insecure_skip_verify: false # 必须 false,默认即为 false,显式写出防误改
Prometheus 侧的 relabel 是告警可读性的关键:把 __param_target 和 instance 都替换成被探测域名,否则告警里只有 127.0.0.1:9115 这种探针地址,值班同学根本不知道是哪张证书出事。注意通配符 *.example.com 不会自动覆盖子域,targets 要逐个列全:
# prometheus.yml(Prometheus 2.5x 通用)
scrape_configs:
- job_name: blackbox_tls
metrics_path: /probe
params:
module: [https_2xx]
static_configs:
- targets: ['www.example.com', 'api.example.com']
relabel_configs:
- source_labels: [__address__]
target_label: __param_target
- source_labels: [__param_target]
target_label: instance # 告警里显示域名而非探针 IP
- target_label: __address__
replacement: 127.0.0.1:9115
# 告警规则:剩余不足 21 天触发,与 renew_before_expiry=21 days 对齐
groups:
- name: tls
rules:
- alert: WildcardCertExpiringSoon
expr: (probe_ssl_earliest_cert_expiry - time()) / 86400 < 21
for: 1h
labels:
severity: warning
owner: platform-team
annotations:
summary: '{{ $labels.instance }} 证书即将到期'
description: '剩余 {{ printf "%.1f" $value }} 天' # 一位小数,紧急程度一眼可辨
probe_ssl_earliest_cert_expiry 是 Unix 时间戳(秒),来自 blackbox_exporter 的 probe_ssl_earliest_cert_expiry 指标;除以 86400 换成天。把告警阈值设成比 renew_before_expiry 稍大(例如续期 21 天、告警 21 天,或续期 30 天、告警 21 天),才能保证”续期失败”先于”证书过期”被感知,这正是配置通配符证书到期提醒的核心逻辑。
方案选型对比:脚本、ACME 钩子、Prometheus、Zabbix、商业平台怎么选
证书到期提醒到底该用 cron 脚本还是监控平台?先看两个硬约束:你能接受多少张证书”漏报一次”,以及到期后谁来续。据 Let’s Encrypt 官方公告,其过期提醒邮件已于 2025-06-04 起停止发送,把提醒责任交回给证书持有者——这意味着”等 CA 发邮件”这条最省事的路已经走不通,必须自己落地一层检测。
| 方案 | 提前量可配 | 覆盖内网域名 | 额外组件 | 年成本区间 | 适用规模 |
|---|---|---|---|---|---|
cron + openssl x509 -checkend |
任意(秒级) | 是 | 无 | 0 元 | 10 张以内 |
certbot --deploy-hook + 邮件 |
钩子内任意 | 是 | 无 | 0 元 | 单团队 |
acme.sh --days + --reloadcmd |
默认 60 天,可调 | 是 | 无 | 0 元 | 单团队 |
| Prometheus 2.53 + blackbox_exporter 0.25 | 阈值任意 | 需探针可达 | Prometheus、Alertmanager | 0 元 + 约 0.5 人日 | 10–200 张 |
| Zabbix 6.4 内置模板 | 宏可配 | 是(agent 2) | Zabbix Server | 社区版 0 元 | 已有 Zabbix |
| 商业证书管理平台 | 平台内配置 | 视产品 | 无 | 约 100–500 元/张/年 | 50 张以上 |
注意这张表只算”监控成本”。证书本身另算:Let’s Encrypt 通配符 0 元但 90 天必须续期;DV 通配符商业证书约 400–1500 元/年;OV 通配符约 2000–6000 元/年,有效期 1 年,仍需提前 30 天提醒(RFC 5280 定义的 notAfter 一到即全站握手失败)。
10 张以内,最省事的命令是什么?一个脚本加一条 cron,退出码就是告警信号。OpenSSL 1.1.1/3.x 的 x509 -checkend 在”剩余时间小于给定秒数”时返回非 0:
#!/usr/bin/env bash
# /usr/local/bin/cert-check.sh —— 适用 OpenSSL 1.1.1+ / 3.x
THRESHOLD=2592000 # 提前量:30 天(秒),按需改
ENDPOINT="example.com:443"
SNI="*.example.com"
if ! openssl s_client -connect "$ENDPOINT" -servername "$SNI" /dev/null
| openssl x509 -noout -checkend "$THRESHOLD" >/dev/null; then
echo "WARN: $ENDPOINT 通配符证书将在 30 天内过期"
| mail -s "[TLS] 证书到期提醒" ops@example.com
fi
# crontab:0 9 * * * /usr/local/bin/cert-check.sh
acme.sh 和 certbot 的提前量怎么改?acme.sh 的 --days 默认 60,只影响”何时自动续期”,不等于告警:
acme.sh --renew -d '*.example.com' --days 30
--reloadcmd "systemctl reload nginx" # 续期成功后重载,失败会打印日志
certbot 同理,--deploy-hook 仅在续期成功时触发,属于”续期后动作”而非到期提醒,提醒仍需靠上面的 -checkend:
certbot renew --deploy-hook "/usr/local/bin/reload-and-notify.sh"
Prometheus 怎么配?blackbox_exporter 0.25 的 probe_ssl_earliest_cert_expiry 直接给出 Unix 时间戳,配 21 天阈值即可:
# blackbox.yml
modules:
https_cert:
prober: http
timeout: 5s
http:
tls_config:
insecure_skip_verify: true # 只测到期时间,不校验证书链
# rules/tls.yml(Prometheus 2.53 语法)
- alert: WildcardCertExpiringSoon
expr: probe_ssl_earliest_cert_expiry - time() < 86400 * 21
for: 10m
labels: {severity: warning}
内网域名探不到怎么办?别为监控把内网端口暴露到公网。用 Zabbix agent 2 的主机侧采集:zabbix_agent2 -t 'web.certificate.get[example.com,443]',或在脚本里判断后 zabbix_sender -z zbx -s host -k cert.days -o "$DAYS" 推送剩余天数,触发器引用宏 {$CERT.EXPIRY.WARN}(模板默认 7d,建议改 30d)。
什么时候该买商业平台?证书 50 张以上、多团队共用、需要审批与审计留痕时选带 API 和到期报表的平台;但仍建议保留一个独立 blackbox 探针做”外部视角”,避免平台自身故障时漏报——据 Mozilla 的 TLS 配置建议,证书链错误与过期是两类独立故障,监控也要分两条腿走。
常见报错怎么排查?6 条真实错误信息与处理办法
这 6 条报错按出现阶段分三类:ACME 客户端续签失败、客户端校验失败、监控告警链路断裂。每条都给出可复制的定位命令。通配符证书到期提醒的可靠性,往往不是卡在告警规则上,而是卡在这些前置环节。
- The manual plugin is not working…(PluginError:must be provided with –manual-auth-hook)
根因:证书最初用certbot certonly --manual手工签发,cron 或 systemd timer 再执行certbot renew时无人应答。两条出路,推荐前者——改用 DNS 插件重签,把交互彻底消灭:# 方案 A:改用 DNS 插件重签(需先装 python3-certbot-dns-cloudflare 等插件包) certbot certonly --dns-cloudflare --dns-cloudflare-credentials /etc/letsencrypt/cloudflare.ini -d '*.example.com' -d example.com # 方案 B:保留 manual,但 renew 必须补齐两个 hook,否则仍报同一错误 certbot renew --manual-auth-hook /usr/local/bin/acme-auth.sh --manual-cleanup-hook /usr/local/bin/acme-cleanup.sh - DNS problem: NXDOMAIN looking up TXT for _acme-challenge.example.com
九成是记录名写错:DNS 面板的“主机记录”应填_acme-challenge,而不是把整串_acme-challenge.example.com填进主机记录位(结果变成_acme-challenge.example.com.example.com)。其次是传播未完成,TXT 的 TTL 常见 60–600 秒,签发的 CNAME 委托还会多一跳。先自证再重试:# 权威侧与公共 DNS 各查一次,两者不一致即未传播完 dig +short TXT _acme-challenge.example.com dig @8.8.8.8 +short TXT _acme-challenge.example.com # 期望输出形如 "eTL2...Xk=";空输出说明记录不存在 - Invalid response from http://example.com/.well-known/acme-challenge/xxx: 404
这不是 web 服务器配置问题,而是校验方式选错了。据 RFC 8555 第 7.1.3 节与 Let’s Encrypt 官方文档,通配符域名只能用 DNS-01,HTTP-01 对*.example.com一律拒绝。把--webroot/--nginx换成--dns-*系列插件即可。
| 校验方式 | 能否签发 *.example.com | 依赖条件 | 典型场景 |
|---|---|---|---|
| HTTP-01 | 否,仅精确域名 | 80 端口需公网可达 | 单域名站点 |
| DNS-01 | 是 | 需 DNS API 凭据,无入站要求 | 通配符、内网、CDN 后源站 |
- NET::ERR_CERT_DATE_INVALID 或 Go 报 x509: certificate has expired or is not yet valid
先确认浏览器实际拿到的是哪张证书——不传-servername会命中默认站点,极易误判成“证书没续上”:# -servername 走 SNI,取到的才是该域名真实生效的证书 openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -subject -dates注意
notBefore也可能在未来:系统时钟漂移或 CA 提前签发都会触发同一报错。 - blackbox 报 probe failed: x509: certificate signed by unknown authority
根因是 fullchain 缺中间证书或顺序颠倒。正确顺序是叶子证书在前、中间证书在后:# 拼接:叶子 + 中间,顺序不可反 cat cert.pem intermediate.pem > fullchain.pem # 复现验证:缺中间证书会报 unable to get local issuer certificate openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt -untrusted intermediate.pem cert.pem - 规则写了却收不到通知
三步排查:先看指标是否为 NaN(probe_ssl_earliest_cert_expiry取链上最早一张证书,链不全时可能为空);再确认 Alertmanager 的route.matchers是否真的匹配severity="warning";最后查企业微信 webhook,IP 不在白名单会返回errcode 93000。# 指标为 NaN 时该表达式无输出,等于告警永远不触发 probe_ssl_earliest_cert_expiry{job="blackbox_ssl"} - time() < 86400 * 30 # 校验路由配置是否可加载 amtool check-config /etc/alertmanager/alertmanager.yml
实践顺序建议:先用 dig 与 openssl s_client 把“证书本身对不对”钉死,再去看 blackbox_exporter 的 probe_success 与告警路由,能省掉大半来回。
规则写对不等于告警能用。下面 5 个动作按「由便宜到昂贵」排序:前两个几分钟就能跑完,后两个要动真实链路和真人,建议每季度全跑一遍。
- 先跑一次 dry-run,再单独跑钩子。certbot 2.11.0 的
--dry-run会强制走 ACME staging 环境,不写盘、也不执行 deploy-hook,所以钩子必须另外验证:
# certbot 2.11.0;--cert-name 指定单张证书,避免 renew 全部证书拖慢验证
sudo certbot renew --dry-run --cert-name wildcard-example
# 期望关键输出:
# Congratulations, all simulated renewals succeeded:
# /etc/letsencrypt/live/wildcard-example/fullchain.pem (success)
# dry-run 不触发 deploy-hook,必须手工跑一遍;-x 逐行打印,便于定位失败命令
sudo bash -x /usr/local/bin/cert-post.sh
# 钩子里应有 nginx -t && systemctl reload nginx,失败要非 0 退出(set -e)
据 Let’s Encrypt 文档,staging 签发的证书不受信任,仅用于验证签发链路——这正是 dry-run 不会污染生产证书的原因。
- 核对指标与真实到期时间是否一致。据 Prometheus blackbox_exporter 文档,
probe_ssl_earliest_cert_expiry返回证书链上最早到期的notAfter(Unix 秒),单位是秒而非天:
curl -s 'http://127.0.0.1:9115/probe?target=https://example.com&module=https_2xx'
| grep probe_ssl_earliest_cert_expiry
# probe_ssl_earliest_cert_expiry 1.7849e+09
date -d @1784900000 -u # 换算成 UTC 日期
openssl s_client -connect example.com:443 -servername example.com /dev/null
| openssl x509 -noout -enddate
# notAfter=Aug 1 12:00:00 2026 GMT
# 两者误差应 ≤ 60 秒;超出说明探测走了 CDN 边缘节点或中间证书更早到期
- 造一张 5 天期自签证书挂到 test.example.com,验证整条链路。这一步验的是「规则 + for + 路由 + 抑制」的组合,不只是语法:
sudo openssl req -x509 -newkey rsa:2048 -nodes -days 5
-keyout /etc/nginx/ssl/test.key -out /etc/nginx/ssl/test.crt
-subj "/CN=test.example.com"
sudo nginx -t && sudo systemctl reload nginx
# 抓取周期 1h(scrape_interval)+ for: 10m,第一档告警最迟约 70 分钟内到达
注意:5 天的证书同时低于 30/21/7 三档阈值,三档会在同一评估周期一起触发,看到的并不是「依次」。若想真正观察递进,临时把阈值改成 5/3/1 天,或把 for 降到 1m 逐日观察。
- 用 amtool 注入测试告警,确认三条通道都通。amtool 0.27 的
alert add要求显式给出 Alertmanager 地址,且告警必须命中 alertmanager.yml 里某条 route,否则会落进默认的 null receiver 而静默丢弃:
amtool alert add alertname=CertExpiring severity=critical instance=example.com
--alertmanager.url=http://127.0.0.1:9093
--annotation=summary="通配符证书 7 天内到期" --end=2h
amtool alert query --alertmanager.url=http://127.0.0.1:9093 # 确认已入库
分别记录邮件、企业微信、电话三条通道的到达时间,任一通道超过 2 分钟未到即视为不达标。
- 每季度做一次端到端演练并归档。runbook 里写清执行人、日期、失败项与修复单号,指标口径如下:
| 指标 | 定义 | 目标值 | 不达标的典型原因 |
|---|---|---|---|
| MTTA | 告警发出 → 有人认领响应 | < 5 分钟 | 通知渠道单一、夜间无人值守 |
| MTTR | 响应 → 续期完成且新证书生效 | < 30 分钟 | deploy-hook 未 reload、DNS-01 手动卡住 |
| 三通道到达率 | 注入告警后实际收到的通道数 | 3/3 | 企业微信 webhook 限流、电话通道未配升级策略 |
这套验证覆盖了从 ACME 签发、blackbox 探测、Prometheus 规则评估到 Alertmanager 路由分发的完整链路,任何一环断开,通配符证书到期提醒都只是配置里的一行注释。
延伸:内部域名、私有 CA 与多团队共用证书怎么提醒
内部通配符 *.corp.example.com 的提醒逻辑和公网证书完全不同:它通常由私有 CA 签发(step-ca 0.25+ 的 step ca certificate、HashiCorp Vault PKI 的 pki/issue/<role>),有效期按内部策略常设 365 天甚至更长,Let’s Encrypt 那套 ACME 90 天节奏在这里不成立。更现实的问题是采集:外部 blackbox_exporter 探针打不进内网,Prometheus 的 probe_ssl_earliest_cert_expiry 拿不到数据。此时用 Zabbix agent 2 内置的 web.certificate.get 键,或在主机侧跑 openssl x509 -checkend 更靠谱——前者在 Zabbix 6.0 起可用,返回 JSON 含 not_after 字段。
# 主机侧采集:剩余秒数 < 0 即已过期;-checkend 参数单位是秒
# 返回 0 表示证书在 30 天内会过期(退出码 1 表示尚未到期)
openssl x509 -in /etc/pki/corp-wildcard.crt -noout -checkend 2592000
echo $? # 0=即将过期或已过期, 1=仍有效
# 写入 Zabbix trapper 或本地文件供 agent 采集
openssl x509 -in /etc/pki/corp-wildcard.crt -noout
-enddate -serial -fingerprint -sha256
多团队共用一张通配符是最容易出事的场景。做法是在 Prometheus 抓取阶段用 relabel_configs 打 owner 标签,再让 Alertmanager 按标签路由,而不是让所有人收到同一封邮件。
# prometheus.yml 片段(Prometheus 2.x)
scrape_configs:
- job_name: cert_files
static_configs:
- targets: ['pay.corp.example.com'] # 逻辑标识
labels:
owner: team-pay # 关键:证书归属团队
env: prod
relabel_configs:
- source_labels: [owner]
target_label: team
# alertmanager.yml 片段
route:
routes:
- matchers: ['team="team-pay"']
receiver: pay-oncall
用了 CDN 或云 WAF 的站点存在两张证书,必须分开监控:
| 证书类型 | 签发/续期方 | 典型有效期 | 过期后果 | 采集位置 |
|---|---|---|---|---|
| 边缘证书 | 云厂商托管,自动续期 | 90 天~1 年 | 用户浏览器直接报错 | 公网探针即可 |
| 回源证书 | 自管(ACME 或私有 CA) | 90 天~1 年 | CDN 回源握手失败,返回 502/526 | 源站主机侧采集 |
只看边缘证书的监控是假安全:边缘自动续期正常,回源证书静默过期,线上表现就是 Cloudflare 的 526 或自建 CDN 的 502,而你的仪表盘一片绿色。
另外两件事不要混为一谈。据 RFC 6962 与 Let’s Encrypt 文档,开启 ssl_stapling on 配合 ssl_stapling_verify on 时,OCSP 响应失败属于 soft fail,Nginx 会继续握手(仅记日志);但 notAfter 过期是硬失败,浏览器一定拦截。对于已提交 HSTS 预加载列表的域名,用户连”继续访问”的逃生通道都没有,影响面远大于普通站点,因此这类站点的通配符证书到期提醒应提前到 30 天甚至 45 天,而不是默认的 14 天。
最后,把每次续期的证据留痕:openssl x509 -serial -noout 拿序列号、-fingerprint -sha256 拿指纹,连同续期时间写进日志,再与 crt.sh 的 CT 日志交叉核对。排查”证书换了但线上没生效”(多见于负载均衡多节点只更新了一台)时,比对指纹能在几秒内定位到漏更新的实例。
Let's Encrypt 对续期时间没有硬性限制,但同一组域名每周最多签发 5 张重复证书(duplicate certificate limit)。certbot 默认在剩余 30 天时 renew,acme.sh 默认 –days 60,提前量再大只会白白消耗配额,建议保持 30 天左右。
–deploy-hook 在首次签发和每次成功续期后都会执行,–renew-hook 只在续期时执行,两者都不会在 –dry-run 模式下运行。做续期后校验和告警推送建议用 –deploy-hook,钩子里可以通过 $RENEWED_LINEAGE 变量拿到证书目录。
不够。邮件只发给 ACME 账号里的 –email,阈值固定为剩余 20 天和 10 天,没有升级机制,也不覆盖内网域名。建议至少再加一条独立的 blackbox_exporter 指标告警,阈值设在 21 天,两条链路互为兜底。
已有 Prometheus 栈就选 blackbox_exporter 0.25,指标 probe_ssl_earliest_cert_expiry 阈值任意可调,适合做分级告警;已有 Zabbix 就选 6.4 内置的 Website certificate 模板,宏 {$CERT.WEBSITE.EXPIRE.WARN} 默认 21 天,不用额外组件。两套都上会导致重复告警,建议只留一个主通道加一个外部探针。
这说明证书当初是用 –manual 手工签发的,renewal conf 里记录的是 authenticator = manual,非交互模式下必须提供钩子脚本。两种处理:一是补上 –manual-auth-hook 与 –manual-cleanup-hook,二是直接用 –dns-cloudflare 之类的 DNS 插件重新签发并迁移到新的 –cert-name。
多数是服务没重载或 CDN 没回源刷新。用 openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -serial -dates 看线上证书序列号,再和磁盘 fullchain.pem 的 openssl x509 -serial -noout 比对,不一致就是 reload 或缓存问题。
不能。通配符只匹配一级,*.example.com 覆盖 api.example.com 但不覆盖 api.test.example.com。二级子域需要另签 *.test.example.com,或者把具体域名加进 SAN 列表,签发前用 -d 参数逐个列清楚。
本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。