跳到主要内容
安装配置教程

acme.sh 申请证书教程:用 DNS API 自动签发通配符证书并配置自动续期

acme.sh 申请证书教程 — acme.sh 申请证书教程:用 DNS API 自动签发通配符证书并配置自动续期
核心结论

acme.sh 申请证书的核心只有三步:安装脚本并绑定邮箱、导出 DNS API 密钥后执行 acme.sh --issue --dns dns_ali -d example.com -d '*.example.com' --keylength ec-256 --server letsencrypt、最后用 --install-cert 把证书装到 Nginx 并写入 reloadcmd,全程约 3 分钟。 acme.sh 自 3.0.0 起默认 CA 已改为 ZeroSSL,要签发 Let's Encrypt 证书必须显式加 --server letsencrypt 或执行 acme.sh --set-default-ca --server letsencrypt,否则容易触发 ZeroSSL 免费额度限制。 自动续期由 cron 驱动:安装脚本会写入一行 0 0 * * * 的 ~/.acme.sh/acme.sh --cron 任务,默认在到期前 60 天(--days 60)续期,证书文件位于 ~/.acme.sh/example.com_ecc/。 通配符域名只能走 DNS-01 验证,Let's Encrypt 官方文档明确 http-01 不支持 *.example.com,因此必须准备 DNS 服务商 API 密钥或使用 --dnssleep 等待 TXT 记录传播。 验证是否生效用三条命令即可:openssl x509 -in fullchain.pem -noout -subject -issuer -dates、openssl s_client -connect example.com:443 -servername example.com、acme.sh --list 查看 Le_NextRenewTime。

为什么手动换证书总会出问题?acme.sh 申请证书教程要解决的根本原因

如果你的证书管理流程还是”一年一换、到期手动续一张”,那它在 2026 年会直接失效——这不是危言耸听,而是 CA/Browser Forum 已经投票通过的时间表。据 CA/Browser Forum 的 SC-081 提案(*Introduce Schedule of Reducing Validity and Data Reuse Periods*),公开信任 TLS 证书的最长有效期分三步压缩:2026 年 3 月 15 日起降到 200 天,2027 年 3 月 15 日起降到 100 天,2029 年 3 月 15 日起降到 47 天。Let’s Encrypt 目前签发的仍是 90 天证书,但同样受 BR 约束,签发端会跟着收紧。到 2029 年,一张证书的寿命不到七周,人工在这个时间尺度上不可能保持可靠——这正是 acme.sh 申请证书教程要解决的第一层问题:把”换证书”从人的日历上彻底移走。

把人工操作拆开看,高频失败点其实只有三个,但每一个都足以造成线上事故:

  • 忘记续期:证书在凌晨过期,告警把你叫醒时手上没有可用新证书,回滚也回不去。
  • CSR 与私钥不匹配:手工生成 CSR 后私钥被覆盖,Nginx reload 直接失败并报 SSL_CTX_use_PrivateKey_file() failed (SSL: error:0B080074:x509 certificate routines:X509_check_private_key:key values mismatch),服务起不来。
  • fullchain 漏拼中间证书:桌面浏览器能过,但部分 Android 版本和 JDK 8 客户端报 CERTIFICATE_VERIFY_FAILED——因为它们的 truststore 里没有 ISRG Root X1 的交叉链。

acme.sh 把这三件事收敛成一条 –issue 加一条 –install-cert:前者负责向 CA 下单并完成挑战,后者负责把 key、fullchain 落到指定路径,并在每次续期成功后执行 reloadcmd。

第二个坑更隐蔽:HTTP-01 的适用边界很窄。它要求 80 端口对公网可达,CDN 回源规则、安全组、WAF 任意一层拦截都会让验证返回 404。而通配符域名 *.example.com 只能用 DNS-01——据 Let’s Encrypt 文档说明,通配符订单不接受 http-01 挑战。这是很多人在 acme.sh 申请证书教程里踩的第一个坑。DNS-01 需要 DNS 服务商的 API 凭据,acme.sh 内置了 100 多家适配脚本(dns_ali、dns_dp、dns_cf、dns_gd……),全部位于安装目录的 dnsapi/ 下,一家服务商一个纯 sh 文件,不需要装任何 SDK。

acme.sh 的定位是纯 POSIX sh 实现,不依赖 Python 或 Go 运行时,安装后主目录约 1.5 MB。它不是常驻进程:没有守护进程,续期完全依赖 cron 或 systemd timer 触发,账户信息写在 ~/.acme.sh/account.conf,每个域名的元数据写在 ~/.acme.sh/<domain>_ecc/<domain>.conf(acme.sh 3.x 默认签发 ECC 证书,目录带 _ecc 后缀;用 –keylength 2048 签 RSA 时目录无后缀)。默认续期阈值是剩余 60 天(源码常量 DEFAULT_RENEW=60,可用 –days 修改)。理解这一点,后面排查”为什么没自动续期”才有方向。

# 1) 确认版本(本文以 acme.sh 3.0.x 为准,POSIX sh + curl/wget,无其他运行时依赖)
acme.sh --version
# https://github.com/acmesh-official/acme.sh
# v3.0.9

# 2) 查看证书真实到期时间(OpenSSL 1.1.1 / 3.x 通用)
openssl x509 -in /etc/nginx/ssl/example.com/fullchain.pem -noout -dates
# notBefore=Nov  1 00:00:00 2025 GMT
# notAfter=Jan 30 00:00:00 2026 GMT      <-- 90 天后

# 3) 确认续期任务是否存在(安装时自动写入,分钟/小时由脚本随机化,避免整点集中请求 CA)
crontab -l | grep acme.sh
# 47 3 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null

# 4) 证书默认只留在 ~/.acme.sh 内,必须显式 --install-cert 才会落地到系统路径
acme.sh --install-cert -d example.com --ecc 
  --key-file       /etc/nginx/ssl/example.com/key.pem 
  --fullchain-file /etc/nginx/ssl/example.com/fullchain.pem 
  --reloadcmd      "systemctl reload nginx"
# 注:3.x 默认即 ECC,--ecc 为兼容旧脚本保留,可省略
维度 acme.sh 3.0.x certbot
运行时依赖 POSIX sh + curl/wget Python 3 + 系统包管理器
安装体积 主目录约 1.5 MB 数百 MB(含 Python 依赖)
通配符签发 原生支持,配合 –dns 参数 需额外安装 certbot-dns-* 插件
默认续期触发 cron 执行 –cron,剩余 60 天触发 systemd timer,剩余 30 天触发
证书落盘位置 默认仅 ~/.acme.sh/,需 –install-cert 默认 /etc/letsencrypt/live/

最后澄清一个常见误解:免费证书和付费证书的差别不在加密强度(DV 与 OV 同样可以用 RSA 2048 或 ECDSA P-256),而在身份校验深度与保障条款。据 Let’s Encrypt 官方说明,其签发的全部是 DV 证书。

类型 验证内容 典型签发时长 年费区间 通配符
DV 仅域名控制权(HTTP-01 / DNS-01) 秒级到数分钟 0 元(Let’s Encrypt)至数百元 支持
OV 组织主体资料人工审核 1~3 个工作日 千元级 支持
EV 组织 + 法律实体严格核验 3~7 个工作日 数千元 一般不签发

对绝大多数站点,用 acme.sh 申请证书配合 DV 已经够用;OV 留给需要展示组织身份、或合同明确要求组织校验的合规场景。真正该投入精力的是把续期做成无人值守的确定性流程,而不是在证书类型上反复权衡。

acme.sh 申请证书教程:从安装到签发的 7 个实操步骤

很多人搜 acme.sh 申请证书教程时,找到的是一堆“复制粘贴就跑”的片段,结果 60 天后续期静默失败。下面这 7 步是一条经过验证的完整链路,每一步都附上可直接执行的命令和判断成功与否的依据。

步骤 1:安装并把邮箱绑定到 ACME 账户

# 在线安装:脚本会克隆仓库到 ~/.acme.sh,并向 ~/.bashrc 追加 alias acme.sh
curl https://get.acme.sh | sh -s email=ops@example.com

# 让 alias 生效(或重新登录 shell)
source ~/.bashrc

# 验证版本,输出应类似:
# https://github.com/acmesh-official/acme.sh
# v3.0.7
acme.sh --version

# 无外网环境:先 git clone,再用本地安装模式
git clone https://github.com/acmesh-official/acme.sh.git
cd acme.sh && ./acme.sh --install -m ops@example.com

邮箱不是可选项:ACME 协议(RFC 8555 §7.3)要求账户关联联系邮箱,用于到期与吊销通知;acme.sh 会据此生成 4096 位账户私钥存放在 ~/.acme.sh/ca/<CA>/account.key。

步骤 2:显式指定 CA(最容易被跳过的一步)

# 将 DEFAULT_ACME_SERVER 写入 ~/.acme.sh/account.conf
acme.sh --set-default-ca --server letsencrypt

# 确认当前默认 CA
acme.sh --info | grep -i ca

据 acme.sh 官方文档,v3.0.0 起默认 CA 已改为 ZeroSSL。跳过这一步,你会看到类似 Please update your account with an email address first. 的提示,且 ZeroSSL 免费证书有签发数量限制。想用 Let’s Encrypt 就必须显式切换;也可换成 --server zerossl 或 --server google。

步骤 3:准备 DNS API 凭据

# 阿里云(RAM 子账号,最小权限 AliyunDNSFullAccess)
export Ali_Key="LTAI5t****"
export Ali_Secret="****"

# 签发前先持久化,避免 cron 执行时读不到环境变量
cat >> ~/.acme.sh/account.conf <<'EOF'
SAVED_Ali_Key='LTAI5t****'
SAVED_Ali_Secret='****'
EOF
chmod 600 ~/.acme.sh/account.conf
DNS 服务商 dns 参数 凭据变量 建议权限
阿里云 dns_ali Ali_Key / Ali_Secret RAM 子账号,仅 DNS 权限
DNSPod dns_dp DP_Id / DP_Key 专用 Token
Cloudflare dns_cf CF_Token(推荐)/ CF_Key+CF_Email API Token 限定 Zone.DNS Edit

Cloudflare 场景优先用 CF_Token 而非全局 API Key,因为 Token 可限定到单个 Zone 且可随时吊销,泄露面小得多。

步骤 4:签发通配符证书

acme.sh --issue --dns dns_ali 
  -d example.com -d '*.example.com' 
  --keylength ec-256 
  --server letsencrypt
# DNS 生效慢的线路可加:--dnssleep 120(单位秒)

不加 --dnssleep 时,acme.sh 会轮询权威 DNS 检查 TXT 是否生效,最长约 20 分钟;超时会报 Verify error:DNS problem: NXDOMAIN looking up TXT for _acme-challenge.example.com。--keylength 默认 2048(RSA),ec-256 体积更小、握手更快,现代客户端均支持。

步骤 5:部署到 Web 服务器

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'

务必用 --install-cert 而不是手工 cp:acme.sh 会把这条部署命令记录进 ~/.acme.sh/example.com/example.com.conf,每次续期后自动重新复制并执行 reloadcmd。手工 cp 的结果是续期成功、线上仍是旧证书。

步骤 6:确认定时任务存在

crontab -l | grep acme.sh
# 0 0 * * * "/root/.acme.sh"/acme.sh --cron --home "/root/.acme.sh" > /dev/null

部分版本的安装脚本会随机化分钟位以避免整点集中请求,只要行内包含 --cron 即可。Let’s Encrypt 建议在到期前 30 天续期,acme.sh 默认阈值为 60 天,无需改动。

步骤 7:强制续期演练

acme.sh --renew -d example.com --ecc --force

在日志里确认出现 Run reload cmd: systemctl reload nginx 且 Reload success。如果 reloadcmd 写错,这里会立刻暴露,而不是等到两个月后的凌晨静默失败——这正是这条 acme.sh 申请证书教程最值得多做的一步。

acme.sh 申请证书教程的核心命令与配置示例(含具体参数与版本)

想把主域名、www 和泛域名一次签全,命令怎么写?以 Cloudflare 为例(其他服务商只需换 --dns 的脚本名,如阿里云 dns_ali、DNSPod dns_dp、Route53 dns_aws):

# acme.sh 3.0.0+ ;-d '*.example.com' 的引号必须加,否则会被 shell 通配符展开
export CF_Token="你的Cloudflare-API-Token"   # 权限只需 Zone:DNS:Edit,别用 Global API Key

acme.sh --issue --dns dns_cf 
  -d example.com -d '*.example.com' -d www.example.com 
  --keylength ec-256 --server letsencrypt 
  --dnssleep 60 --log
参数 含义与取值 默认值
--dns DNS 服务商适配脚本名,决定用哪套 API 写 _acme-challenge TXT 记录 无(不加则走 webroot/standalone)
--keylength 2048/4096/ec-256/ec-384 3.0.0 起为 ec-256
--server letsencrypt、letsencrypt_test、zerossl、buypass zerossl(旧版为 letsencrypt)
--dnssleep 强制等待 TXT 生效的秒数;DNS API 模式通常靠自动轮询即可,遇到权威 NS 缓存慢才需要显式指定 自动轮询
--log 把调试输出追加到 ~/.acme.sh/acme.sh.log,排障必开 关闭

证书拿到后,Nginx 侧最容易踩的坑是引用错了文件。必须指向 fullchain,而不是 cert——据 Let’s Encrypt 文档,cert.pem 只含叶子证书,缺中间证书会让 Android 旧版本、部分 Java 客户端报 unable to get local issuer certificate。

# /etc/nginx/conf.d/example.com.conf
ssl_certificate     /etc/nginx/ssl/example.com.fullchain.pem;  # 叶子+中间证书
ssl_certificate_key /etc/nginx/ssl/example.com.key;
ssl_protocols       TLSv1.2 TLSv1.3;                            # 对齐 Mozilla intermediate 配置
ssl_ciphers         ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256;
ssl_stapling        on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/example.com.fullchain.pem;  # OCSP 校验链,同样用 fullchain
nginx -t && systemctl reload nginx   # 先语法检查,通过后再 reload,避免配置错导致站点全挂

为什么续期会“证书更新了但没生效”?因为 --reloadcmd 是以 acme.sh 的运行身份执行的。用 root 的 cron 时,/etc/nginx/ssl 建议 chmod 750、私钥 chmod 600、属主 chown root:root;若用普通用户跑 acme.sh,除目录写权限外,还得在 sudoers 里为该用户免密放行 systemctl reload 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      "systemctl reload nginx"

失败通知建议在部署时就配好,别等监控发现 443 端口证书过期:

export MAIL_FROM="acme@example.com"
export MAIL_TO="ops@example.com"
export SMTP_HOST="smtp.example.com"
export SMTP_PORT="465"          # 465 走 SSL,587 走 STARTTLS
export SMTP_USERNAME="acme@example.com"
export SMTP_PASSWORD="******"
acme.sh --set-notify --notify-level 2 --notify-hook mail
# 推送到钉钉/飞书:--notify-hook webhook,并 export WEBHOOK_URL=...

日常运维靠哪几条命令?acme.sh --list 列出全部证书与下次续期时间;acme.sh --info -d example.com 输出 Le_NextRenewTime、Le_Keylength、Le_Webroot;acme.sh --revoke -d example.com --ecc 吊销;acme.sh --remove -d example.com --ecc 仅从管理列表移除;acme.sh --upgrade 手动升级——安装时默认开启 --auto-upgrade,介意自动变更的团队可在 ~/.acme.sh/account.conf 写 AUTO_UPGRADE='0'。

调试阶段为什么要用 –staging?据 Let’s Encrypt 速率限制文档,正式环境同一注册域名每周 50 张证书、完全相同的域名集合每周 5 张。调 --reloadcmd 或验证 DNS Token 权限时反复签发,很容易撞上 too many certificates already issued。加上 --staging(等价 --server letsencrypt_test)走测试环境,签出来的证书不受信任但不占配额,验证通过后去掉该参数重签一次即可。这背后是 RFC 8555 定义的 ACME 协议在起作用,acme.sh 只是把 dns-01 挑战的 TXT 记录写入自动化了。

acme.sh 申请证书方案选型对比:验证方式、CA、密钥类型怎么选

先问最关键的问题:你要签的是 *.example.com 这种通配符吗?如果是,选型的第一步就已经被锁死了。据 Let’s Encrypt 文档(《Challenge Types》)和 RFC 8555 的约束,通配符订单只接受 DNS-01 验证,HTTP-01 与 TLS-ALPN-01 无法签发通配符。这也是 acme.sh 申请证书教程里最容易踩坑的分水岭——很多人用 --webroot 反复重试 -d '*.example.com',拿到的永远是 Cannot issue for "*.example.com": Domain name contains an invalid character 这类报错。

验证方式 acme.sh 参数 支持 *.example.com 端口要求 典型场景
HTTP-01 --webroot / -w,或 --standalone 否 80 端口需公网可达 单域名、无 DNS API 权限
DNS-01 --dns dns_xxx 是 无 通配符、内网服务器、CDN 全站加速
TLS-ALPN-01 --alpn 否 443 端口可达 无 80 端口但有 443 的环境
# 适用 acme.sh 3.x。3.0.0 起默认 CA 已从 Let's Encrypt 改为 ZeroSSL,建议显式指定
acme.sh --register-account -m you@example.com --server letsencrypt
acme.sh --set-default-ca --server letsencrypt

# DNS-01 签发通配符(以 Cloudflare 为例);--keylength 默认值即 ec-256,此处显式写出便于审阅
export CF_Token="你的Cloudflare_API_Token"   # 只读 Zone:DNS:Edit 权限即可
acme.sh --issue --dns dns_cf 
  -d example.com -d '*.example.com' 
  --keylength ec-256 
  --server letsencrypt

第二步才轮到选 CA,它决定你的签发额度和证书有效期。Let’s Encrypt 的速率限制是硬约束:每个注册域名每周 50 张,同一组完全相同的域名集合每周 5 张。测试环境务必加 --server letsencrypt_test(或 --staging),否则几轮调试就会把配额烧光。

CA 参数 单张有效期 关键限制
Let’s Encrypt --server letsencrypt 90 天 每注册域名 50 张/周,重复集合 5 张/周
ZeroSSL --server zerossl(3.0.0 起默认) 90 天 免费账户有数量配额,超限报 rate limit
Google Trust Services --server google 90 天 需 EAB 凭据(--eab-kid / --eab-hmac-key),接入步骤更多
云厂商托管证书 不适用 90 天至 1 年 与厂商绑定,跨云迁移成本高
# 触达 Let's Encrypt 限额时的真实报错(HTTP 429)
# Error creating new order :: too many certificates already issued for exact set of domains:
# example.com,*.example.com: see https://letsencrypt.org/docs/rate-limits/
# 处理方式:改用 --server letsencrypt_test 调试,或等待窗口滚动(7 天)

第三步看密钥类型,它影响握手开销与老旧客户端兼容性。acme.sh 3.x 的 --keylength 默认值是 ec-256,即 ECDSA P-256;想覆盖 Android 5/6、老 JDK 这类只认 RSA 的客户端时,才需要显式降级到 2048。

--keylength 握手开销 兼容性 建议
2048 基准 最广,含老旧设备 需兼容 Android 5/6、老 JDK 时选
ec-256(默认) 约为 RSA-2048 的 1/3 TLS 1.2+ 主流浏览器均支持 新站点首选
ec-384 略高于 ec-256 少数老旧客户端不支持 合规要求高安全等级时选

ECC 与 RSA 可以并存:同一组域名分别用两种 --keylength 各签一张(acme.sh 会把 ECC 证书放在带 _ecc 后缀的目录),再让 Nginx 在同一个 server 块里配两张证书,由客户端按自身能力协商(Nginx 1.11.0 起支持)。

acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --keylength ec-256
acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' --keylength 2048

# Nginx:双证书,ECDSA 优先,RSA 兜底
ssl_certificate     /etc/nginx/ssl/example.com_ecc/fullchain.cer;  # ECDSA P-256
ssl_certificate_key /etc/nginx/ssl/example.com_ecc/example.com.key;
ssl_certificate     /etc/nginx/ssl/example.com/fullchain.cer;      # RSA 2048
ssl_certificate_key /etc/nginx/ssl/example.com/example.com.key;

最后是工具选型,它决定长期运维成本。

工具 运行时依赖 通配符 自动续期机制 适合谁
acme.sh 仅 sh + curl/cron 支持(100+ DNS API) cron 调用 acme.sh --cron 已有 Nginx/Apache,想要轻量脚本
certbot python3 + 系统包 支持(插件较少) systemd timer 偏好官方客户端、Debian/Ubuntu 系
Caddy Go 单二进制 支持 内置自动续期 新建站点、可接受更换 Web 服务器

结论落在可操作的判断上:已有 Nginx 且要签通配符,acme.sh 的接入成本最低——它不需要 Python 运行时,DNS API 覆盖最广,续期只是 cron 里的一行 acme.sh --cron --home ~/.acme.sh。选型确定后,下一步才是配置具体的 DNS API 凭据与续期钩子。

acme.sh 申请证书时最常见的 6 个报错与排查方法

acme.sh 的报错几乎都发生在三个环节:依赖缺失、DNS API 鉴权、HTTP 校验可达性。下面按报错原文逐条给出排查路径,其中命令可直接复制。注意一个高频前提:acme.sh v3.0.0 起默认 CA 已从 Let’s Encrypt 改为 ZeroSSL,要签发 Let’s Encrypt 证书必须显式加 --server letsencrypt,很多”限速”和”验证失败”的困惑由此而来。

1. Please install socat tools first.

出现在 --standalone 模式:acme.sh 调用 socat 临时监听 80 端口完成 HTTP-01 校验,缺依赖时直接失败(RFC 8555 定义的 http-01 挑战要求 80 端口可达)。

# Debian/Ubuntu
apt install -y socat
# RHEL/CentOS 7+/Rocky/Alma
yum install -y socat   # 或 dnf install -y socat

# 80 端口被 Nginx/宝塔占用时,改用 webroot(需与站点 root 完全一致)
acme.sh --issue -d example.com -w /var/www/html
# 或干脆走 DNS API,完全不依赖 80/443
acme.sh --server letsencrypt --issue --dns dns_ali -d example.com -d '*.example.com'

2. Error add txt for domain:_acme-challenge.example.com

DNS API 鉴权失败。排查顺序:① Ali_Key/Ali_Secret 是否被复制时带了换行或空格(export 时加引号);② RAM 子账户是否具备 AliyunDNSFullAccess,若用自定义最小权限策略,必须包含 AddDomainRecord、DeleteDomainRecord、DescribeDomainRecords 三个 Action;③ 打开调试看 API 原始返回体——--debug 2 会打印请求与响应,默认 --debug 0 只输出错误。

export Ali_Key="LTAI5txxxxxxxx"
export Ali_Secret="xxxxxxxxxxxxxxxx"   # 勿带换行/空格
acme.sh --server letsencrypt --issue --dns dns_ali 
  -d example.com -d '*.example.com' --debug 2

3. Invalid response from http://example.com/.well-known/acme-challenge/xxxx: 404

验证文件访问不到。四大常见原因:--webroot 填成了站点根目录以外的路径;Nginx 的 location ~ /. 规则拦截了 .well-known;CDN 缓存了旧的 404;80 端口被 301 强制跳转到 443 导致校验请求被改写。先用 curl 定位:

curl -I http://example.com/.well-known/acme-challenge/test
# 期望 200 或 404;若返回 301/403 就是跳转规则或隐藏文件规则在拦
# Nginx 中放行(放在 80 端口的 server 块内,且不要被跳转规则覆盖)
location ^~ /.well-known/acme-challenge/ {
    root /var/www/html;
    default_type text/plain;
}

4. too many certificates (5) already issued for this exact set of domains

撞上 Let’s Encrypt 重复证书限速:据 Let’s Encrypt 官方 Rate Limits 文档,同一域名集合每周最多 5 张,窗口滚动释放;另有 Failed Validation 每小时 5 次的失败限速。处理方式是先用 --staging 把流程跑通,正式签发前用 acme.sh --list 确认没有重复订单在跑。

acme.sh --list
acme.sh --server letsencrypt --staging --issue --dns dns_ali -d example.com -d '*.example.com'
# 调试通过后去掉 --staging 重新签发

5. Verify error: DNS problem: NXDOMAIN looking up TXT for _acme-challenge.example.com

TXT 记录尚未生效就发起了校验。默认 acme.sh 在 DNS 模式下会轮询公共 DNS,但受 TTL 与递归缓存影响常需 60–120 秒,可显式加 --dnssleep 120 固定等待。另一个隐蔽原因是 _acme-challenge 已被 CNAME 到别处,此时 acme.sh 写入的记录不会生效。

dig +short CNAME _acme-challenge.example.com   # 有输出说明存在 CNAME,需先删除
dig +short TXT _acme-challenge.example.com @8.8.8.8
acme.sh --server letsencrypt --issue --dns dns_ali -d example.com -d '*.example.com' --dnssleep 120

6. –install-cert: Can not find domain key 或 nginx: [emerg] cannot load certificate

前者通常是漏了 --ecc:acme.sh 默认签发 RSA 2048(--keylength 2048),只有显式指定 --keylength ec-256 时才生成 ECC 证书,且证书目录变为 example.com_ecc,安装时必须带 --ecc 才能找到私钥。后者多为路径写错,或 SELinux 上下文不允许 Nginx 读取 /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"

ls -lZ /etc/nginx/ssl              # 查看 SELinux 上下文
restorecon -Rv /etc/nginx/ssl      # 修复为 httpd_config_t 等正确类型

三种验证方式的取舍,决定了上面大部分报错会不会出现:

验证方式 依赖端口 能否签通配符 典型失败原因
--standalone 80 否 缺 socat、80 被 Web 服务占用
--webroot 80 否 路径不符、隐藏文件规则、CDN 缓存
--dns(DNS API) 无 是(*.example.com) API 权限不足、TXT 未生效、CNAME 冲突

因此本教程主线选择 --dns:一次配置即可覆盖泛域名与多级子域,且不受 80/443 可达性影响;后续自动续期依赖的也正是这条无端口依赖的链路。签发成功后务必用 acme.sh --info -d example.com --ecc 核对 Le_NextRenewTime,确认 cron 续期任务已写入(安装时默认自动创建,可用 crontab -l | grep acme 验证)。

怎么确认 acme.sh 申请的证书已经生效?5 种可复现的验证方法

acme.sh 返回 Cert success 只代表证书文件已经写进磁盘,不代表浏览器拿到的就是这张证书。真正的”生效”要穿过三层:文件正确、进程已加载、链路与协议合规。下面 5 个方法按这个顺序排查,每条命令都可直接复现。

验证层次 核心命令 通过标准
本地文件 openssl x509 -in ... -noout -dates -ext subjectAltName CN、issuer、90 天有效期、SAN 含泛域名
线上实际下发 openssl s_client -connect ... -servername ... 与本地文件序列号一致
证书链 openssl verify -CAfile ... 输出 : OK
续期任务 acme.sh --list / crontab -l Renew 列有时间、存在 cron 或 timer
协议与装订 s_client -status、-tls1_1 OCSP successful、TLS 1.1 握手失败

1)本地证书文件对不对?先看文件本身。据 Let’s Encrypt 文档,其证书有效期固定为 90 天,因此 notAfter 应在签发后约 90 天;acme.sh 默认在到期前 60 天续期(--days 60,可用 --days 调整,取值范围建议 1–89)。

# OpenSSL 1.1.1+ 支持 -ext;1.0.2 需改用 -text 后 grep
openssl x509 -in /etc/nginx/ssl/example.com.fullchain.pem -noout 
  -subject -issuer -dates -ext subjectAltName
# 期望:
# subject=CN = example.com
# issuer=C = US, O = Let's Encrypt, CN = R11   (ECDSA 证书为 E5/E6)
# notBefore=...  notAfter=...(约 90 天后)
# X509v3 Subject Alternative Name:
#     DNS:example.com, DNS:*.example.com

2)Nginx 真正加载的是哪张证书?这是最容易被忽略的一步:--install-cert 复制了文件,但没有 --reloadcmd 时 Nginx 仍持有旧证书。用 SNI 直接问线上进程:

openssl s_client -connect example.com:443 -servername example.com /dev/null 
  | openssl x509 -noout -dates -issuer -serial
# 与本地文件对比序列号,不一致就说明没 reload
openssl x509 -in /etc/nginx/ssl/example.com.fullchain.pem -noout -serial

# 快速版(curl 7.x)
curl -vI https://example.com 2>&1 | grep -E 'expire date|issuer'

确认后执行 nginx -t && nginx -s reload,并把 reload 固化进 acme.sh:acme.sh --install-cert -d example.com --key-file ... --fullchain-file /etc/nginx/ssl/example.com.fullchain.pem --reloadcmd "nginx -s reload"。

3)证书链完整吗?只部署 cert.pem 是常见错误,Android 与部分 Java 客户端会直接报错。用系统 CA 包校验 fullchain:

openssl verify -CAfile /etc/ssl/certs/ca-certificates.crt 
  /etc/nginx/ssl/example.com.fullchain.pem
# 期望:example.com.fullchain.pem: OK
# 失败典型输出:
# error 20 at 0 depth lookup: unable to get local issuer certificate

出现该报错说明中间证书缺失,检查 Nginx 的 ssl_certificate 是否指向 fullchain.pem 而非 cert.pem。可用 openssl s_client -showcerts -connect example.com:443 </dev/null 数一数返回了几张证书(应为 2 张:叶证书 + 中间证书)。

4)续期任务真的存在吗?据 acme.sh 文档,安装时默认写入 0 0 * * * 的 cron;使用 systemd 的系统也可能是 timer。两者至少存在一个:

acme.sh --list                 # Renew 列应显示具体日期,而非空或 Initial
acme.sh --info -d example.com  # 查看 Le_NextRenewTimeStr、Le_ReloadCmd、Le_RealFullChainPath
crontab -l | grep acme.sh
systemctl list-timers | grep acme

若 Le_ReloadCmd 为空,即使续期成功也不会热加载,务必补一次 --install-cert。

5)OCSP Stapling 与协议版本。OCSP 装订可省去客户端回源查询(RFC 6066 定义 status_request 扩展):

openssl s_client -status -connect example.com:443 -servername example.com /dev/null 
  | grep -A2 'OCSP Response Status'
# 期望:OCSP Response Status: successful (0x0)

openssl s_client -connect example.com:443 -tls1_1 </dev/null
# 期望握手失败(no protocols available / handshake failure),确认 TLS 1.0/1.1 已关闭

Nginx 需配置 ssl_stapling on; ssl_stapling_verify on; ssl_trusted_certificate /etc/nginx/ssl/example.com.fullchain.pem;。最后用 SSL Labs 做整体评分,参考 Mozilla SSL Configuration Generator 的 intermediate 配置,A 级及以上视为达标;若只有 B,通常是未开 HSTS 或仍支持 TLS 1.1。

默认 cron 是 0 0 * * *,为什么一定要错峰?

acme.sh 安装定时任务时写入的是 0 0 * * *(见 acme.sh --install-cronjob 生成的条目),全网大量主机在同一分钟醒来,CA 接口与本机 systemctl reload nginx 都会撞在一起。好在 acme.sh 只有证书剩余有效期低于 Le_RenewalDays(默认 60 天)时才真正续期,据 Let’s Encrypt 文档,90 天证书建议在剩余 30 天前完成续期,所以把执行时间挪到凌晨、并带上非整点的随机分钟几乎零成本:

# 1) 先看现有条目,确认 acme.sh 装的是哪个表达式
crontab -l | grep -F '.acme.sh/acme.sh --cron'

# 2) 用绝对路径改写成非整点时间,输出重定向避免 cron 发邮件
17 3 * * * /root/.acme.sh/acme.sh --cron --home /root/.acme.sh > /dev/null

# 3) 改完复核(重装/迁移后条目容易回退成默认值)
crontab -l | grep -F '.acme.sh/acme.sh --cron'

多机部署能不能直接 scp -r ~/.acme.sh?为什么不行?

不能。~/.acme.sh 里除了证书,还有 ca/acme-v02.api.letsencrypt.org/directory/account.key(CA 账户私钥)和 account.conf 中的 SAVED_CF_Token 等 DNS API 凭据,复制目录等于把凭据扩散到每一台机器。正确做法二选一:DNS-01 校验只要求出站 443,不需要 80 端口,内网机可以各自独立签发;或者中心机签发、rsync 分发证书文件后在目标机显式 reload。

# 方案 A:每台机器独立签发(DNS-01,内网机亦可)
export CF_Token="仅含 Zone.DNS 编辑权限的最小权限 Token"
/root/.acme.sh/acme.sh --issue --dns dns_cf -d example.com -d '*.example.com'

# 方案 B:中心机签发后分发(--install-cert 会把 reloadcmd 记入配置)
/root/.acme.sh/acme.sh --install-cert -d example.com --ecc 
  --key-file       /etc/nginx/certs/example.com.key 
  --fullchain-file /etc/nginx/certs/fullchain.cer 
  --reloadcmd      "systemctl reload nginx"

rsync -a --delete /etc/nginx/certs/ root@10.0.0.12:/etc/nginx/certs/
ssh root@10.0.0.12 'systemctl reload nginx'   # rsync 不会触发 reload,必须显式执行
部署方式 凭据扩散风险 内网机能否签发 reload 是否自动 适用场景
复制整个 ~/.acme.sh 高:账户私钥 + DNS Token 一起扩散 否(无独立账户) 依赖目标机 reloadcmd 不推荐
各机独立签发(DNS-01) 低:每机一份最小权限 Token 能,仅需出站 443 是 主机少、内网多
中心机签发 + rsync 分发 最低:凭据只留一台 能收证书、不能签发 需在目标机显式 reload 主机多、边缘节点

容器里没有 crontab,能用 systemd timer 代替吗?

可以,据 systemd.timer 手册,Persistent=true 会补跑关机期间错过的任务,RandomizedDelaySec 还能再做一次抖动。注意 --cron 必须带 --home,否则会读错目录:

# /etc/systemd/system/acme-sh.service
[Unit]
Description=acme.sh renewal
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-sh.timer
[Unit]
Description=Daily acme.sh renewal
[Timer]
OnCalendar=*-*-* 03:17:00
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target

# 启用并验证下次触发时间
systemctl daemon-reload && systemctl enable --now acme-sh.timer
systemctl list-timers acme-sh.timer

怎么监控“续期其实早就挂了”?

这条能兜住 reloadcmd 写错、DNS Token 过期、cron 被清理等所有自动化失效场景。数据源有两个:acme.sh --info -d example.com 输出的 Le_NextRenewTimeStr/Le_ReloadCmd,或直接抓线上证书的 notAfter:

# 看 acme.sh 自己记录的续期时间与 reload 命令
/root/.acme.sh/acme.sh --info -d example.com | grep -E 'Le_NextRenewTimeStr|Le_ReloadCmd'

# 抓线上实际证书的到期时间(OpenSSL 1.0.2+ 支持 -servername)
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null 
  | openssl x509 -noout -enddate

# 告警规则:-checkend 1814400 秒 = 21 天,返回 1 即触发
openssl x509 -checkend 1814400 -noout -in /etc/nginx/certs/fullchain.cer 
  || echo "ALERT: example.com 证书将在 21 天内过期"

把最后一条塞进任意巡检脚本或 Prometheus textfile collector,规则固定为“剩余天数 < 21 即告警”,比盯 acme.sh 的日志可靠得多——它只看结果,不看过程。

acme.sh 申请证书的安全边界:私钥、API 密钥与日志怎么管

为什么说”能签发成功”不等于”配置安全”?acme.sh 把 DNS API 凭据以明文写进 ~/.acme.sh/account.conf,把私钥写进域名目录,把调试细节写进日志。据 Let’s Encrypt 文档,ACME 账户密钥等同于账户身份,一旦泄露,攻击者可为你名下任意域名签发证书。所以这一步的核心是三件事:凭据最小化、文件权限收紧、日志不留痕。

DNS API 密钥应该给多大权限?永远不要用阿里云主账号 AK。应创建 RAM 子账号,绑定只含解析记录增删查的自定义策略(Resource 精确到单个域名):

{
  "Version": "1",
  "Statement": [{
    "Effect": "Allow",
    "Action": ["alidns:AddDomainRecord",
               "alidns:DeleteDomainRecord",
               "alidns:DescribeDomainRecords"],
    "Resource": "acs:alidns:*:*:domain/example.com"
  }]
}
# 密钥只通过环境变量注入,签发后会被 acme.sh 存入 account.conf(600)
export Ali_Key="LTAI5t****"      # RAM 子账号 AccessKeyId
export Ali_Secret="****"
~/.acme.sh/acme.sh --issue --dns dns_ali 
  -d example.com -d '*.example.com' --keylength ec-256   # 默认 RSA 2048,ec-256 更小更快

Cloudflare 同理,优先用 CF_Token 而非全局 CF_Key:Token 权限选 Zone.DNS:Edit,Zone Resources 限定到单个 Zone;全局 Key 可操作账号下所有域名,泄露后果完全不同。

凭据类型 作用范围 泄露后影响 建议
阿里云主账号 AK 全部云资源 可创建/删除任意资源 禁止使用
RAM 子账号 AK + 自定义策略 单个域名的解析记录 仅能篡改该域名 DNS 推荐
Cloudflare 全局 CF_Key 账号下全部 Zone 可接管所有域名 不推荐
Cloudflare CF_Token 指定 Zone 的 DNS 仅影响该 Zone 解析 推荐

目录和文件权限怎么设?acme.sh 保存 account.conf 时会自行设为 600,但迁移、手工编辑或换 umask 后可能被放宽,建议复核一次:

chmod 700 ~/.acme.sh                 # 目录仅属主可进入,阻断同组用户遍历
chmod 600 ~/.acme.sh/account.conf    # 内含 DNS API 密钥与 ACME 账户信息
find ~/.acme.sh -name '*.key' -exec chmod 600 {} ;   # 私钥默认 600,此处兜底
ls -l ~/.acme.sh/example.com_ecc/
# -rw------- 1 root root  227 example.com.key        ← 私钥
# -rw-r--r-- 1 root root 3.5K fullchain.cer          ← 证书链,可公开

在共享主机上要额外确认上级目录(如 /root 应为 700)不对外开放,否则 700 的子目录也可能被绕过读取。

–debug 2 到底打印了什么?它会输出完整的 HTTP 请求体与响应头,Authorization: Bearer <CF_Token>、阿里云签名参数会明文出现在终端;同时开启 --log 或 --debug 时,这些内容还会落盘到 ~/.acme.sh/acme.sh.log。排障结束立刻清理:

grep -nE "Authorization|CF_Token|Ali_Secret|AccessKey" ~/.acme.sh/acme.sh.log
: > ~/.acme.sh/acme.sh.log && chmod 600 ~/.acme.sh/acme.sh.log   # 清空并收紧

把 --debug 2 的原始输出贴到公开工单或 Issue 前,务必先替换密钥片段——这是最常见的泄露途径。

私钥真的泄露了怎么办?按”吊销 → 轮换 → 重签 → 重载”顺序执行,不要只做其中一步:

~/.acme.sh/acme.sh --revoke -d example.com --ecc        # 走 ACME revokeCert 接口吊销
~/.acme.sh/acme.sh --remove -d example.com --ecc        # 清理本地记录
# 在云控制台轮换 DNS API 密钥后重新签发
~/.acme.sh/acme.sh --issue --dns dns_cf -d example.com -d '*.example.com' 
  --keylength ec-256 --force
~/.acme.sh/acme.sh --install-cert -d example.com --ecc 
  --key-file /etc/nginx/ssl/example.com.key 
  --fullchain-file /etc/nginx/ssl/fullchain.cer 
  --reloadcmd "systemctl reload nginx"

如果泄露的是 ACME 账户密钥(~/.acme.sh/ca/*/account.key),仅吊销证书不够——需按 RFC 8555 第 7.3.6 节的账户停用接口停用该账户(acme.sh --help | grep -i deactivate 确认当前版本是否支持 --deactivate-account),再 --register-account 重新注册。

协议侧还能怎么加固?证书选 ec-256 后,Nginx 需加载 ECDSA 套件;TLS 1.3 要求 OpenSSL 1.1.1+ 与 Nginx 1.13+。HSTS 建议从 300 秒灰度,确认无混合内容后再升到 31536000(Mozilla SSL Configuration Generator 的 intermediate 档位即采用该值,且不建议急于加 includeSubDomains):

ssl_protocols TLSv1.2 TLSv1.3;                     # TLS 1.3 需 OpenSSL 1.1.1+
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384;
ssl_prefer_server_ciphers off;                     # TLS 1.3 下由客户端优选
ssl_stapling on;                                   # OCSP Stapling,减少客户端额外请求
ssl_stapling_verify on;
ssl_trusted_certificate /etc/nginx/ssl/fullchain.cer;
add_header Strict-Transport-Security "max-age=300" always;   # 稳定后改 31536000

这些服务端配置与 acme.sh 申请证书教程里的签发、续期流程互不冲突:证书只是文件,TLS 参数决定它被如何使用。

看你的技术栈。acme.sh 是纯 Shell 脚本,无 Python 依赖,内置 100 多家 DNS 服务商适配,签通配符时配置量明显更小;certbot 依赖 python3 与系统包,Debian/Ubuntu 生态集成更好,官方维护。已有 Nginx 且需要 *.example.com 的场景,优先 acme.sh;如果团队已经用 certbot 的 systemd timer 体系且运行稳定,没必要迁移。

因为 acme.sh 从 3.0.0 起把默认 CA 改成了 ZeroSSL。解决方法是签发前执行 acme.sh –set-default-ca –server letsencrypt,或在每条 –issue 命令后显式加 –server letsencrypt。注意切换 CA 后已签发的证书不会自动迁移,需要重新签发一次。

这是 DNS API 写入 TXT 记录失败。先确认 Ali_Key/Ali_Secret(或 CF_Token)没有多余空格与换行,再确认 RAM 子账户具备 DNS 记录增删查权限。仍无法定位时用 acme.sh –issue –dns dns_ali -d example.com –debug 2 重跑,命令输出里会带上服务商返回的原始错误码,例如 InvalidAccessKeyId.NotFound 或 Forbidden.RAM。

默认 –days 60 表示剩余 60 天时续期,对 90 天证书来说相当于到期前 30 天左右开始动作,留有充足重试窗口。不建议把 –days 调得很小,因为 Let's Encrypt 有失败验证限速(每账户每主机名每小时 5 次),留出重试空间更稳妥。如果 cron 意外失效,提前 30 天的窗口也给了监控足够的告警时间。

*.example.com 只匹配一级子域,能覆盖 mail.example.com、api.example.com,但不覆盖 a.b.example.com,也不覆盖裸域 example.com。所以签发时通常写成 -d example.com -d '*.example.com',两个名字放同一张证书的 SAN 里。若存在多级子域,需要再加 -d '*.sub.example.com'。

九成是 reloadcmd 没执行成功。检查 ~/.acme.sh/example.com_ecc/example.com.conf 里的 Le_ReloadCmd 是否为你期望的命令,再手动跑一次 systemctl reload nginx 看返回码;如果是容器或负载均衡架构,还要确认证书是否被分发到所有节点。可用 openssl s_client -connect example.com:443 -servername example.com 查看线上实际下发证书的 notAfter 来确认。

加密强度没有区别,都是同等位数的 ECC/RSA 密钥与同样的 TLS 协议。差别在有效期管理方式、保障条款与身份校验:Let's Encrypt 90 天且无赔付,付费 DV 常见 1 年有效期并带有限额的签发错误赔付,OV/EV 还要审核组织资料。需要向客户展示组织身份或采购合同要求有 SLA 时选 OV,纯技术站点用 acme.sh 申请证书即可。


本文由 sslgood.com 安全团队基于生产环境实战经验撰写,关键结论均经过技术复核。

内容审核

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