文档中心

Appearance

acme issue —— 申请证书 ​

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

通过 ACME 协议申请一张新证书，覆盖质询验证、私钥生成、CSR 提交、证书下载、格式转换与部署的完整流程。运行模式：

  • 无参运行 certiman acme issue → 进入交互向导，按服务器与账户 → 域名 → 验证方式 → 密钥 → 续期与部署的顺序逐项询问；已有证书时显示现有配置并逐项确认修改
  • 带参运行 → 命令模式，CLI 不进行任何交互询问；缺少必要参数时直接报错（例如未提供 -d 或 -c 时，提示「命令模式需要域名：请通过 -d/--domain 或 -c/--conf 指定」）

证书配置在首次申请时保存到 ~/.certiman/acme/certs/<主域名>/cert.yaml，后续命令从该文件读取默认值，完整字段见 cert.yaml 证书配置文件。重复执行同一命令时，同域名、同算法的有效证书已存在则本次无变更，不重复申请。

用法 ​

bash
certiman acme issue [flags]

参数 ​

选择器 / 配置来源：

flag短名类型默认说明
--domain-d[]string域名，可重复；首个为主域名（CN 与证书目录名）；与 -c 互斥
--conf-cstring证书配置文件路径（任意位置的 cert.yaml），域名与设置从文件读取

服务器与账户：

flag短名类型默认说明
--serverstringACME Directory URL，取值为完整地址
--accountstring已注册账户的目录名（取值见 acme account list）；不提供时，本机仅有一个可用账户则自动选中，存在多个可用账户时报错并要求显式指定
--email-mstring账户联系邮箱；注册新账户时使用
--eab-kid / --eab-hmac-keystringEAB 凭证；CA 要求 EAB 且需要注册新账户时，两者必须同时提供
--accept-tosboolfalse接受该 CA 当前的服务条款，仅在注册新账户时生效

账户按以下顺序确定：--account 指定的账户 → 本机唯一可用账户 → --server 与 --email 定位的账户（本机已有同身份账户时复用，否则注册新账户，CA 要求 EAB 或服务条款时按需附加对应参数）。同身份指 CA 目录 URL、联系邮箱与 EAB KID 一致；同一 CA 与邮箱使用不同 EAB KID 时可注册多个账户，此时需用 --account 显式选择。

域名验证：

flag类型默认说明
--acme.challengestringdns-01质询类型：dns-01 / http-01；通配符域名仅支持 dns-01
--dcv-hookstringDNS 验证 hook 脚本路径，脚本同时承担布置与清理，通过环境变量 CERTIMAN_HOOK_TYPE（present / cleanup）区分；dns-01 必须配置本项或证书配置中的 dcv.present
--acme.http.modestringwebroothttp-01 的服务方式：webroot / standalone
--acme.http.webroot-pathstringwebroot 方式的站点根目录，CLI 将质询文件写入该目录
--http-portint80standalone 方式的监听端口，取值 1–65535

密钥：

flag短名类型默认说明
--keylength-kstringec-256证书私钥算法：ec-256 / ec-384 / rsa-2048 / rsa-3072 / rsa-4096

续期与部署：

flag类型默认说明
--renew.auto-certboolfalse将证书纳入自动续期，由定时任务统一扫描续期
--renew.days-beforeint0提前续期天数；大于 0 时按剩余天数判定，不请求 ARI；等于 0（默认）时按 ARI 建议窗口判定，窗口不可用时按剩余有效期比例（不足 1/3）兜底
--deploy-hookstring部署 hook 脚本路径，证书文件写入后执行
--reloadcmdstring--deploy-hook 的同义参数，执行 shell 命令

输出与等待：

flag类型默认说明
--output.formats[]string额外输出格式，以逗号分隔或重复指定：der / pfx / jks
--cert-file / --key-file / --ca-file / --fullchain-filestring额外安装位置：在证书目录的标准文件之外，将内容另外复制一份到指定路径；私钥权限固定为 0600
--output.pfx-file / --output.jks-file / --output.jks-aliasstringPFX / JKS 输出文件名与 JKS 别名
--output.pfx-encodingstringmodernPFX 编码：modern / legacy
--output.password-filestringPFX / JKS 口令文件路径；口令只接受文件输入
--wait-timeoutstring5mACME 账户初始化、DNS 传播与 ACME 轮询的累计等待上限（Duration）

示例 ​

bash
# 交互向导：完整申请流程
certiman acme issue

# DNS hook 自动验证（命令模式）
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 时：注册新账户并申请
certiman acme issue -d example.com \
  --server https://acme.example.com/acme/v2/directory \
  --eab-kid eab-9f3k2d --eab-hmac-key c2VjcmV0LW1hYy1rZXk \
  -m 'mail@example.com' --accept-tos \
  --dcv-hook /home/<用户名>/.certiman/hooks/dns.sh

# 通配符证书 + 自动续期 + 部署
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

# http-01 webroot 验证
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

# 本机存在多个账户时，显式指定账户（目录名见 acme account list）
certiman acme issue -d example.com \
  --account <账户目录名> \
  --dcv-hook /home/<用户名>/.certiman/hooks/dns.sh

# 用配置文件驱动
certiman acme issue -c ./shop-cert.yaml

示例地址

本文示例中的 https://acme.example.com/acme/v2/directory 仅为示例地址，以 CA 实际提供的 Directory URL 为准。

DNS 验证 hook 契约

hook 脚本按阶段注入 CERTIMAN_HOOK_TYPE=present（布置）或 cleanup（清理）。脚本读取 CERTIMAN_DCV_FQDN（完整记录名 _acme-challenge.<域名>）、CERTIMAN_DCV_TYPE（TXT）、CERTIMAN_DCV_VALUE（验证值）、CERTIMAN_DCV_HOST（相对主域的主机记录）等环境变量，完成 TXT 记录的布置与删除。该契约与 CertCloud 模式的 DCV hook 一致，已有验证脚本可直接复用。完整变量清单见 Hook 环境变量。

输出 ​

申请完成后提示 ✔ 证书申请完成:<主域名>；未配置部署脚本时给出配置提示，开启自动续期但未注册定时任务时给出注册提示。-o json 输出结构化结果，包含本轮结论（changed / unchanged / failed / canceled）与证书视图（主域名、域名列表、账户、签发与到期时间、剩余天数、证书目录、本地交付记录等）。私钥在任何格式下都不输出。

0成功（示例）
text
✔ 证书申请完成:example.com
0有效证书已存在（示例）
text
✔ 同域名、同算法的有效证书已存在:example.com · 本次无变更

相关命令 ​