文档中心

Appearance

ACME 模式 ​

示例邮箱统一使用 mail@example.com，运行命令或使用配置前请替换为实际业务邮箱。

本页演示使用 CertiMan 内置 ACME 客户端的完整流程：申请证书 → 部署到服务器 → 开启自动续期。完成后，证书到期前的续期、下载、安装与服务重载均自动完成，无需人工操作。

前置准备 ​

在开始之前，请确认：

  • 已按 安装 certiman 完成安装，运行 certiman version 可输出版本号
  • 拥有 CA 提供的 ACME Directory URL；CA 要求 EAB 时，同时持有 eab-kid 与 eab-hmac-key
  • 拥有示例所申请域名的 DNS 管理权限（用于 dns-01 质询），或对应 Web 服务器的站点目录写权限（用于 http-01 质询）

首次申请证书时，CLI 按 --server 与 --email 自动完成 ACME 账户注册，无需单独执行账户命令；本机存在多个账户时，运行 certiman acme account list 查看账户，并通过 --account <账户目录名> 显式指定。

示例域名与地址

本页所有示例统一使用 example.com（IANA 保留域名）与示例 Directory URL https://acme.example.com/acme/v2/directory。实际操作时请替换为自有域名与 CA 实际提供的地址。

申请证书 ​

DNS 验证（推荐） ​

准备一个 DNS 验证 hook 脚本，用于在 DNS 服务商处布置与删除 TXT 记录 _acme-challenge.<域名>。脚本通过环境变量接收操作类型与验证值，编写方式见 Hook 环境变量。

bash
certiman acme issue -d example.com \
  --server https://acme.example.com/acme/v2/directory \
  --email 'mail@example.com' \
  --accept-tos \
  --dcv-hook /home/<用户名>/.certiman/hooks/dns.sh

CA 要求 EAB 时，在上述命令中附加 --eab-kid 与 --eab-hmac-key；CA 未声明服务条款时，省略 --accept-tos。

申请成功后，证书文件保存在 ~/.certiman/acme/certs/example.com/，包含 cert.pem、privkey.pem、chain.pem 与 fullchain.pem。重复执行同一命令时，同域名、同算法的有效证书已存在则本次无变更，不重复申请。

无参运行 certiman acme issue 可进入交互向导，按提示逐项完成相同配置。

HTTP 验证 ​

站点可通过公网 HTTP 访问时，可使用 http-01 质询，CLI 将质询文件写入指定站点目录：

bash
certiman acme issue -d example.com \
  --server https://acme.example.com/acme/v2/directory \
  --email 'mail@example.com' \
  --accept-tos \
  --acme.challenge http-01 --acme.http.webroot-path /var/www/html

http-01 不支持通配符域名；通配符证书必须使用 dns-01。

部署到服务器 ​

申请时提供 --deploy-hook，证书写入后自动执行部署脚本；申请时已配置部署脚本的证书，续期后同样自动部署：

bash
certiman acme issue -d example.com \
  --server https://acme.example.com/acme/v2/directory \
  --email 'mail@example.com' \
  --accept-tos \
  --dcv-hook /home/<用户名>/.certiman/hooks/dns.sh \
  --deploy-hook /home/<用户名>/.certiman/hooks/nginx.sh

部署脚本接收证书路径等环境变量，完成证书安装与服务重载。常见服务的脚本模板见 部署示例，可使用 certiman hook test 在本地试运行，详见 Hook 命令。

已签发的证书可单独执行部署，例如重试失败的部署或后期补充脚本：

bash
# 执行证书配置中的部署脚本
certiman acme deploy -d example.com

# 单次覆盖部署脚本（不修改证书配置）
certiman acme deploy -d example.com --deploy-hook /home/<用户名>/.certiman/hooks/nginx.sh

证书已有成功部署记录时，再次部署需追加 -f（单次覆盖同样适用）：certiman acme deploy -d example.com -f。详见 acme deploy。

开启自动续期 ​

申请时提供 --renew.auto-cert，将证书纳入自动续期：

bash
certiman acme issue -d example.com \
  --server https://acme.example.com/acme/v2/directory \
  --email 'mail@example.com' \
  --accept-tos \
  --dcv-hook /home/<用户名>/.certiman/hooks/dns.sh \
  --renew.auto-cert \
  --deploy-hook /home/<用户名>/.certiman/hooks/nginx.sh

注册定时任务后，CertiMan 每 12 小时扫描一次，自动续期进入窗口的证书并执行部署脚本：

bash
certiman cron install

运行 certiman cron status 查看下次触发时间与最近一轮执行结果。详见 定时任务命令。

续期窗口：优先使用 ARI

ARI（Automated Renewal Information，自动续期信息，RFC 9773） 是 CA 通过 ACME 协议发布建议续期窗口的机制，客户端按 CA 建议的时间续期，可平滑 CA 侧的签发负载并及时响应 CA 的调度调整。

保持 renew.days_before 为默认值 0 即使用 ARI，推荐优先使用该方式；需要固定提前天数时，再将 --renew.days-before 设置为大于 0 的值，此时不再请求 ARI。

常用运维命令 ​

bash
# 查看本机 ACME 证书
certiman acme list

# 查看单张证书的状态与交付记录
certiman acme status -d example.com

# 手动触发一次续期（未到窗口时幂等跳过）
certiman acme renew -d example.com

# 排查签发与续期日志
certiman logs --cert example.com

相关文档 ​

  • ACME 命令 —— 命令与参数完整参考
  • acme account —— 账户注册与查看（多账户场景）
  • 部署示例 —— Nginx / Apache / Tomcat 等部署 hook 脚本
  • 配置 —— 数据目录、全局 flag 与退出码