文档中心

Appearance

cert.yaml —— ACME 证书配置文件 ​

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

每张 ACME 证书对应一份配置文件 ~/.certiman/acme/certs/<CN>/cert.yaml，记录账户、验证方式、密钥算法、部署 hook、输出格式与续期设置。首次运行 certiman acme issue 申请时自动生成，后续 acme renew / acme status / acme convert / acme deploy 命令从该文件读取默认值。

也可以在任意位置手动编写 cert.yaml，并通过 -c/--conf <路径> 指定使用（推荐用于 CI/CD 与配置管理场景）。ACME 与 CertCloud 模式的 cert.yaml 是两套独立的 schema，不能混用。

完整字段清单 ​

yaml
version: 1                          # schema 版本（ACME 模式独立版本线）
wait_timeout: 5m                    # 账户初始化、DNS 传播与 ACME 轮询的累计等待上限；必须为正

# 域名（必填）
domains:                            # 按输入顺序保存，首个为主域名（CN）
  - example.com
  - www.example.com

# 密钥算法（整段省略时按 ec-256）
csr:
  key_type: ecdsa                   # rsa / ecdsa；命令行入口为 -k/--keylength（ec-256 / ec-384 / rsa-2048 / rsa-3072 / rsa-4096）
  key_size: 256                     # ecdsa: 256 / 384；rsa: 2048 / 3072 / 4096

# ACME 账户与质询
acme:
  account: acme-1                   # accounts/ 下的账户目录名；也可通过 directory_url / email / eab_* 声明账户身份
  directory_url: "https://acme.example.com/acme/v2/directory"  # 完整 CA Directory URL
  email: "mail@example.com"        # 账户联系邮箱
  eab_kid: "eab-9f3k2d"             # EAB 密钥 ID（CA 要求 EAB 时）
  eab_hmac_key: ""                  # EAB HMAC 密钥；敏感字段，见下方权限说明
  challenge: dns-01                 # dns-01（默认）/ http-01；通配符域名仅支持 dns-01
  http:                             # 仅 challenge: http-01 时使用
    mode: webroot                   # webroot（默认）/ standalone
    webroot_path: /var/www/html     # webroot 模式的站点根目录（必填）
    port: 80                        # standalone 模式的监听端口；0 按 80

# DCV 验证 hook（与 CertCloud 模式同一契约）
dcv:
  present: ./dns-present.sh         # 布置验证记录，每域名一次；dns-01 必须配置
  cleanup: ./dns-cleanup.sh         # 清理验证记录，每域名一次

# 部署
deploy: "systemctl reload nginx"    # 部署 hook（每证书一次）

# 输出
output:
  formats: [pem, pfx]               # 额外输出格式：der / pfx / jks
  # 下面四项是【额外安装位置】（不是重命名标准文件）——见下方"额外安装位置"小节
  cert_file: /etc/nginx/ssl/example.pem       # 相对路径以证书目录为基准
  key_file: /etc/nginx/ssl/example.key        # 私钥恒 0600
  ca_file: /etc/nginx/ssl/example-chain.pem
  fullchain_file: /etc/nginx/ssl/example-fullchain.pem
  pfx_file: example.com.pfx
  pfx_encoding: modern              # modern（默认）/ legacy
  jks_file: example.com.jks
  jks_alias: server
  password: ""                      # PFX/JKS 口令；与 password_file 互斥
  password_file: ./pfx.pass

# 续期
renew:
  auto_cert: true                   # 纳入自动续期，由定时任务统一扫描
  days_before: 0                    # 提前续期天数；非 0 完全按此判定（不再请求 ARI），0 才走 ARI 动态窗口

字段与 acme issue 命令的 flag 对应，命令行 flag 会覆盖配置文件的值。

EAB HMAC 的文件权限

acme.eab_hmac_key 为敏感字段。配置文件包含该字段时，Linux / macOS 要求文件权限为 0600，Windows 要求 DACL 仅当前用户、SYSTEM 与管理员可访问；权限不符合要求时命令拒绝执行。

参数复用机制 ​

首次运行 acme issue 时使用的参数会固化到 cert.yaml；后续 acme renew / acme convert / acme deploy 直接读取该文件，无需重复指定这些 flag。

关键规则：

  • 账户：acme.account 记录账户目录名；需要更换账户时，运行 acme issue -d <主域名> --account <新账户> -f 显式应用变更
  • 密钥算法：csr 在首次申请时确定；续期沿用相同算法，但每次续期生成新私钥，新证书下载完成后才替换 privkey.pem
  • 域名与密钥变更：domains 或密钥算法与现有证书不一致时，acme renew 拒绝直接续期，需运行 acme issue 申请替代证书
  • 单次覆盖：命令行 flag 仅对本次运行生效，不会写回 cert.yaml（例如 certiman acme deploy -d example.com --deploy-hook "systemctl reload nginx" 仅在本次运行时执行该部署命令，不修改配置）

额外安装位置 ​

output.cert_file / key_file / ca_file / fullchain_file（或对应 flag --cert-file / --key-file / --ca-file / --fullchain-file）是额外安装位置：证书目录 ~/.certiman/acme/certs/<CN>/ 里的标准文件不受影响，CLI 会将内容另外复制一份到指定路径。

规则：

  • 相对路径以证书目录 ~/.certiman/acme/certs/<CN>/ 为基准；绝对路径直接使用
  • 私钥（key_file）无论目标目录权限如何，均以 0600 权限写入
  • 目标目录必须存在且当前用户可写；不满足时报错，且不执行 deploy hook
  • 配置 fullchain_file / key_file 后，deploy hook 收到的 CERTIMAN_CERT_PATH / CERTIMAN_KEY_PATH 环境变量指向安装位置，而非证书目录中的副本；脚本中引用的文件路径需相应调整

典型用法：Nginx / Apache 通常使用固定的证书路径，可通过 output.*_file 直接复制证书，deploy hook 中只需执行 reload，无需手动 cp。

yaml
output:
  formats: [pem]
  fullchain_file: /etc/nginx/ssl/example-fullchain.pem
  key_file:       /etc/nginx/ssl/example.key
deploy: systemctl reload nginx

相关文档 ​