文档中心

Appearance

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

每张证书对应一份配置文件 ~/.certiman/cc/certs/<CN>/cert.yaml，记录申请参数、验证方式、部署 hook、输出格式等配置。首次运行 certiman issue 申请时自动生成，后续 renew / reissue / status / download / deploy 命令从该文件读取默认值。

也可以在任意位置手动编写 cert.yaml，并通过 -c/--conf <路径> 指定使用（推荐用于 CI/CD 与配置管理场景）。

完整字段清单 ​

yaml
version: 2                          # schema 版本

# 域名（必填）
domains:                            # 按输入顺序保存，首个为主域名（CN）；每项前后空白会被修剪，中间空格与不可见字符会拒收
  - example.com
  - www.example.com

# 订单参数
product_id: trustasia_ssl_dv_v2     # 产品 ID（字符串）
validity_months: 12                 # 必须整年（12 的倍数）；上限由产品的 max_order_validity_years 决定
skip_given_domain: false            # 关闭 www / 裸域赠送
wait_timeout: 15m                   # 单轮轮询上限；必须为正，0 / 负值一律拒绝
order:
  id: ""                            # 复用平台订单 ID
remark: ""                          # 本机备注

# CSR
# 新建 cert.yaml 时不写入 key_type / key_size：缺字段表示"尚未指定"，由订单或产品决定；
# 一旦写入即视为用户的显式选择，复用订单时以本地值为准。可生成的组合为
# RSA-2048/3072/4096、ECDSA-256/384、SM2-256，订单要求其他组合时直接报错。
csr:
  key_type: ecdsa                   # rsa / ecdsa / sm2；命令行入口为 -k/--keylength（ec-256 / ec-384 / 2048 / 3072 / 4096 / sm2）
  key_size: 256
  sign_hash: SHA384                 # SHA256 / SHA384 / SM3

# 组织（OV / EV 证书需要）
# OV / EV 提交 CSR 前，CertiMan 用订单上绑定的那份组织信息覆盖 CSR 主体的组织字段并回写本文件——
# CA 审核比对的正是这份记录。取不到订单信息时仅告警、按本文件的值照常生成；
# 订单绑了组织而订单与本文件都没有组织名称时以退出码 5 停止，需先在 org 段补齐。
org:
  id: "wgCSwVxP"                    # 复用已通过审核的组织；给了此项则下面字段不再要求
  name: "Example Inc."              # 组织名（随单新建时必填）
  chinese_name: "示例科技有限公司"   # 组织中文名（随单新建时必填，长度 ≤ 200）
  uscc: "91XXXXXXXXXXXXXXXX"        # 统一社会信用代码（随单新建时必填，长度 ≤ 64）
  country: "US"
  state: "CA"
  city: "San Francisco"
  address: "123 Example St"
  postal_code: "94103"
  phone: "+1-555-000-0000"
  biz_email: "biz@example.com"
  contact:
    first_name: "John"    # 名
    last_name: "Doe"      # 姓
    title: "IT Manager"
    email: "john@example.com"
    phone: "+1-555-000-0001"

# 邮箱验证
approver_email: "admin@example.com"

# DCV 域名验证
dcv:
  method: dns                       # dns-persist / dns-proxy / dns / cname / file / file-proxy / email
  present: ./dns-present.sh         # 每域名一次
  cleanup: ./dns-cleanup.sh

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

# 输出
output:
  formats: [pem, pfx]               # pem / 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（默认，AES-256）/ legacy（3DES+SHA1，兼容老环境）
  jks_file: example.com.jks
  jks_alias: example
  password: ""                      # PFX/JKS 口令；与 password_file 互斥
  password_file: ./pfx.pass

# 续期
renew:
  auto_cert: true                   # 服务期内证书自动续期（免费）
  auto_order: false                 # 订单自动续费（会扣费）
  days_before: 0                    # 提前续期天数；非 0 完全按此判定（不再请求 ARI），0 才走 ARI 动态窗口

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

参数复用机制 ​

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

cert.yaml 里被固化的字段：csr / dcv / org / output / deploy / renew。

关键规则：

  • CSR 参数（csr.key_type / key_size / sign_hash）：首次运行 issue 时确定并写入 cert.yaml；renew / reissue 沿用相同的 CSR 参数，但每次都生成新私钥（不复用旧私钥，新证书下载完成后才替换 privkey.pem）
  • DCV / 组织 / 部署 hook：同样在首次配置后复用；需要调整时，直接编辑 cert.yaml 中的对应字段
  • 增删 SAN：reissue 没有增删 SAN 的 flag，编辑 cert.yaml.domains 后运行 reissue；首个域名是 CN，不能更换
  • 单次覆盖：命令行 flag 仅对本次运行生效，不会写回 cert.yaml（例如 certiman download -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/cc/certs/<CN>/ 里的标准文件不受影响，CLI 会将内容另外复制一份到指定路径。

规则：

  • 相对路径以证书目录 ~/.certiman/cc/certs/<CN>/ 为基准；绝对路径直接使用
  • 私钥（key_file）无论目标目录权限如何，均以 0600 权限写入
  • 目标目录必须存在且当前用户可写；不满足时报错，且不执行 deploy hook
  • issue / renew / download / 手工 deploy 都会在执行 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

相关文档 ​