step-ca 0.30.2 常用 CLI 命令详解

step CLI 0.30.2 全命令实测：ca health/provisioner/certificate/renew/revoke 与 certificate inspect/create/fingerprint，覆盖 JWK 与 ACME 两条签发路径，排障报错逐行照抄

Smallstep CertificatesSmallstep CertificatesPKI 证书证书管理信息安全2026/10/31

step-ca 0.30.2 常用 CLI 命令详解

目标：系统梳理 step CLI（Smallstep CLI 0.30.2）的日常命令——健康探测、provisioner 查询、JWK 与 ACME 两条签发路径、续期、吊销、证书检查与离线自签——每条命令均附真实实测回显；排障报错逐行照抄，可直接对照排错。

一、环境信息

  • 操作系统：Linux x86_64
  • Smallstep CLI：0.30.2（Smallstep CLI/0.30.2 (linux/amd64)，Release Date: 2026-03-22 23:21 UTC）
  • Smallstep CA：0.30.2（服务端，Smallstep CA/0.30.2 (linux/amd64)，Release Date: 2026-03-23 00:18 UTC）
  • CA 服务地址：https://ca.stepca.internal:9000（客户端已配置该主机名解析）
  • 已配置 provisioner：admin（JWK，密码 q1w2e3r4）、acme-step（ACME）
  • 客户端工作目录：/home/step/work（含 root_ca.crt 根证书与密码文件 .prov.pass）
  • 根证书指纹：2a4d06b866972e6227494089dc788d6706f70f10ed102c7261607b860c45ff5e

二、工具概览

step CLI 的命令树分两大族：

命令族面向本文覆盖
step ca <子命令>与 CA 服务端交互（health/provisioner/certificate/renew/revoke）第四章
step certificate <子命令>本地证书操作（inspect/create/fingerprint），多数不联网第五章

贯穿两条签发路径：

  • JWK 路径：静态密钥认证（provisioner 名 + 密码），适合管理员手工签发与脚本注入；
  • ACME 路径：RFC 8555 挑战认证（http-01 standalone），无需密码，适合自动化客户端。

三、前置条件

  1. 客户端已放置 CA 根证书 root_ca.crt（从 CA 的 https://<ca>/roots.pem 下载或带外复制）；
  2. 客户端能把 ca.stepca.internal 解析到 CA 服务器，且主机名在 CA 配置 dnsNames 列表内（见配置详解篇 5.2）；
  3. 准备密码文件避免交互（权限 600）：
mkdir -p /home/step/work && cd /home/step/work
echo 'q1w2e3r4' > .prov.pass && chmod 600 .prov.pass

四、CA 服务端交互命令（step ca）

4.1 step version：确认版本

step version

实测回显：

Smallstep CLI/0.30.2 (linux/amd64)
Release Date: 2026-03-22 23:21 UTC

4.2 step ca health：健康探测

step ca health --ca-url https://ca.stepca.internal:9000 --root root_ca.crt

实测回显：

ok

服务不可达时的真实报错（故意指向未监听的 9443 端口，逐行照抄）：

client GET https://ca.stepca.internal:9443/health failed: dial tcp 10.89.56.3:9443: connect: connection refused

⚠️ 注意：省略 --ca-url 时默认探测 https://localhost:9000，仅当命令在本机 CA 上执行才成立；跨机探测必须显式给出 --ca-url 与 --root——这是健康检查误报 unhealthy 的头号根因（排障实录见部署篇 Q1）。

4.3 step ca provisioner list：查询签发授权

step ca provisioner list --ca-url https://ca.stepca.internal:9000 --root root_ca.crt

实测回显（完整 JSON，两个 provisioner；encryptedKey 原样保留）：

[
   {
      "type": "JWK",
      "name": "admin",
      "key": {
         "use": "sig",
         "kty": "EC",
         "kid": "0oxx6mWKNZVsQGXbkVua5nuy-EV2zgCUCUIMy-odYpE",
         "crv": "P-256",
         "alg": "ES256",
         "x": "e5b-D49KrFmOJ3zShdidPXOR7hC3qCfkIiVd9jAUuis",
         "y": "U5B246ykzPr2ifagDo43kopO2Dfe_zcqG0zPVAu_Pjo"
      },
      "encryptedKey": "eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ciLCJjdHkiOiJqd2sranNvbiIsImVuYyI6IkEyNTZHQ00iLCJwMmMiOjYwMDAwMCwicDJzIjoiNUdab192UWdwMDh4T1VtVkYzMzF1QSJ9.OZuoyjKIyBbQY4At_aZwBVqv2Os3kF7zhlasGzvGHL6Ae2ZgUo6xBQ.Zz9N2FhoFgjTB8Jy.KTVFZAISdeJIfZQCx4JepWkQe0aiomKRAV9vGRPCFu2OeIqn1LSTYm8tAIdKJXc8zhuH7kLxUdPteR3Ci0gg5eNdwEK-mAFw2VfMujOpLOEgVwYbhUmgx-GLKe92q5-jvoMyC-zYWumqJrG5w8egS0DBJ9cucmZnG83-SPBy9wMTOy2D0Y2cGO9m6vNH88rq-sypkdSHC2aTrPr20hoHBDfKI0yj1QJtDxe4aoS3ofKrA5zpkzafxNfBI6ka2evgXc2uRI7TopxmZAARn6e-uuxeIxM6ynkMvaScmkWBrWaP4HqfW2r_Ix1cojXNbgWC2ck-kp4SxiZRK8jG0es.L7OlncXMVMFvoFnyvBOnCA"
   },
   {
      "type": "ACME",
      "name": "acme-step",
      "claims": {
         "enableSSHCA": true,
         "disableRenewal": false,
         "allowRenewalAfterExpiry": false,
         "disableSmallstepExtensions": false
      },
      "options": {
         "x509": {},
         "ssh": {}
      }
   }
]

4.4 step ca certificate：签发证书（JWK 路径）

step ca certificate acme-test.internal acme-test.crt acme-test.key \
  --ca-url https://ca.stepca.internal:9000 \
  --root root_ca.crt \
  --provisioner admin \
  --password-file .prov.pass \
  --not-after 24h

实测回显（逐行照抄）：

✔ Provisioner: admin (JWK) [kid: 0oxx6mWKNZVsQGXbkVua5nuy-EV2zgCUCUIMy-odYpE]
✔ CA: https://ca.stepca.internal:9000
✔ Certificate: acme-test.crt
✔ Private Key: acme-test.key

常用参数：

参数作用
位置参数 1证书 Subject 与默认 SAN（域名或 IP）
位置参数 2/3输出的证书文件 / 私钥文件
--provisionerprovisioner 名称（provisioner list 里查）
--password-fileprovisioner 密码注入，免交互
--not-after 24h有效期；相对时间（24h/48h）或绝对时间（2026-12-31T00:00:00Z）
--san追加额外 SAN，可重复
--san 10.89.56.2IP 形式 SAN 同样支持

💡 说明：私钥在客户端本地生成，只有 CSR 上送 CA；这是私钥不出机的安全模型。

4.5 step ca certificate：签发证书（ACME 路径）

ACME provisioner（acme-step）无需密码，通过 http-01 挑战证明域名控制权。--standalone 模式由 step CLI 临时在本机 80 端口应答挑战（需 root 或相应端口能力；域名必须解析回本机，CA 会回连验证）：

step ca certificate acme-svc.internal.example.com acme-svc.crt acme-svc.key \
  --provisioner acme-step \
  --ca-url https://ca.stepca.internal:9000 \
  --root root_ca.crt \
  --standalone

实测回显（逐行照抄）：

✔ Provisioner: acme-step (ACME)
Using Standalone Mode HTTP challenge to validate acme-svc.internal.example.com . done!
Waiting for Order to be 'ready' for finalization .. done!
Finalizing Order .. done!
✔ Certificate: acme-svc.crt
✔ Private Key: acme-svc.key

签发后的证书检查（step certificate inspect --short 实测）：

X.509v3 TLS Certificate (ECDSA P-256) [Serial: 2714...3287]
  Subject:     acme-svc.internal.example.com
  Issuer:      Smallstep Internal CA Intermediate CA
  Provisioner: acme-step
  Valid from:  2026-10-31T04:22:07Z
          to:  2026-11-01T04:23:07Z

💡 技术拓展：--standalone（CLI 自起 80 端口应答挑战）之外，ACME 还有 --webroot（把挑战文件放到既有 Web 目录）与 --http-listen（自定义端口）模式；标准 certbot/Caddy/cert-manager 客户端对接同一 ACME 端点时按各自方式完成挑战。

4.6 step ca renew：续期

step ca renew acme-test.crt acme-test.key \
  --ca-url https://ca.stepca.internal:9000 \
  --root root_ca.crt \
  --force

实测回显：

Your certificate has been saved in acme-test.crt.

要点：

  • 续期以原证书+私钥向 /renew 端点认证，不需要 provisioner 密码；
  • 未到期续期需 --force；官方推荐窗口是到期前 2/3 时段内自动续；
  • 常驻自动续期加 --daemon（可配 --renew-period、--interval），配合 systemd 托管实现证书永续；
  • 续期会生成新私钥（默认 --reuse-key 可保留旧钥）。

4.7 step ca revoke：吊销

先签一张专用证书再吊销（实测全程）：

step ca certificate revoke-me.internal rev.crt rev.key \
  --ca-url https://ca.stepca.internal:9000 --root root_ca.crt \
  --provisioner admin --password-file .prov.pass

step ca revoke --cert rev.crt --key rev.key \
  --ca-url https://ca.stepca.internal:9000 --root root_ca.crt

实测回显（签发部分同 4.4，吊销部分逐行照抄）：

✔ CA: https://ca.stepca.internal:9000
Certificate with Serial Number 280286226882480500563967958883881994852 has been revoked.

要点：

  • --cert + --key：以证书自身认证吊销自己（无需密码）；也可用 --serial <序列号> --provisioner admin --password-file .prov.pass 以管理员身份吊销他人证书；
  • 吊销状态记录在 CA 的 db/ 库（badger），CA 重启后仍生效；
  • 吊销是"记入数据库"而非"证书立刻失效"——已部署的 TLS 会话仍会信任到自然过期，关键场景需配合短有效期对冲。

4.8 step ca 的其余常用子命令

子命令用途
step ca init初始化 PKI（交互实录见部署篇）
step ca root [file]下载根证书（https://<ca>/roots.pem 的 CLI 封装）
step ca fingerprint输出 CA 根证书指纹（客户端信任比对用）
step ca ssh certificate签发 SSH 用户/主机证书（SSH CA 能力）
step ca ssh config生成 OpenSSH 配置片段（known_hosts/证书认证）
step ca token生成一次性签发令牌（给无密码自动化管道用）

五、本地证书工具命令（step certificate）

5.1 step certificate inspect：检查证书内容

step certificate inspect acme-test.crt --short

实测回显：

X.509v3 TLS Certificate (ECDSA P-256) [Serial: 3205...0687]
  Subject:     acme-test.internal
  Issuer:      Smallstep Internal CA Intermediate CA
  Provisioner: admin [ID: 0oxx...dYpE]
  Valid from:  2026-10-31T04:15:14Z
          to:  2026-11-01T04:16:14Z
  • 去掉 --short 输出完整 X.509 文本（含 SAN/扩展/签名算法）；
  • --format json 输出 JSON 形态，便于脚本解析；
  • --roots root_ca.crt 可校验链完整性，--server-name 可模拟 SNI 校验。

5.2 step certificate create：离线自签证书

step certificate create selftest.local self.crt self.key \
  --profile self-signed --subtle --no-password --insecure --force

实测回显：

Your certificate has been saved in self.crt.
Your private key has been saved in self.key.

⚠️ 注意：--profile self-signed 必须同时给 --subtle，否则报错（真实回显，逐行照抄）：

'--profile self-signed' requires the '--subtle' flag

常用 profile：leaf（叶子证书，可配 --ca/--ca-key 用自备 CA 签）、self-signed（自签根/自签叶子）、root-ca/intermediate-ca（手工搭 PKI）。--no-password --insecure 表示私钥明文落盘（实验用）；生产离线根私钥必须加密（去掉这两个参数并设置密码）。

5.3 step certificate fingerprint：计算指纹

step certificate fingerprint self.crt
step certificate fingerprint root_ca.crt

实测回显：

f7a3779fc8b5d6ff00beed117d0467e89aab25ac17dd42d4b220a2ce94e6834b
2a4d06b866972e6227494089dc788d6706f70f10ed102c7261607b860c45ff5e

第二条正是 CA 根证书指纹，与 init 输出、https://<ca>/fingerprint 页面一致——客户端首次连接 CA 前用它人工核对信任锚，是防中间人的关键一步。

六、注意事项

  1. 凭据分层：CA 密码（解锁中间 CA 私钥）与 provisioner 密码（JWK 签名）是两把锁，init 时同源生成；ACME 路径完全无密码，但只覆盖它能挑战的域名；
  2. 主机名即信任边界：--ca-url 的主机名必须命中 CA dnsNames，SAN 必须覆盖客户端要保护的名字——名字错=证书白签；
  3. --force 的边界：renew/create 的 --force 会无提示覆盖已有文件，脚本里先备份；
  4. 文件属主：以特权身份执行签发后，产物属主是特权身份，普通用户后续读取会 permission denied（真实踩坑：step certificate inspect 报 open acme-svc.crt failed: permission denied，chown 1000:1000 后恢复）；
  5. token 模式优先：CI/CD 中不建议放 provisioner 密码，用 step ca token 生成短时效令牌传给签发端。

七、常见问题

Q1：connection refused / dial tcp ...？

CA 未监听该地址端口，或解析到的 IP 不对。先用 step ca health --ca-url ... --root ... 探测（回显见 4.2），再核对 DNS/hosts 与 CA 监听配置。

Q2：报 The request was valid, but the server could not process it 或授权被拒？

常见三种：provisioner 名拼错（用 4.3 的 list 核对）、密码文件内容错（含多余换行）、证书有效期超出 provisioner claims 上限（默认 max 24h，见配置详解篇 5.5.3）。

Q3：ACME 挑战一直 pending？

http-01 要求 CA 能回连客户端的 80 端口且域名解析正确：客户端域名解析回客户端 IP、--standalone 进程存活、80 端口未被防火墙拦截。三查：解析、进程、防火墙。

Q4：续期报 certificate is not due for renewal？

还没到续期窗口（默认到期前 2/3 时间内）。加 --force 立即续（本文实测即用 --force）。

Q5：吊销后为什么还在信任？

吊销状态只在 CA 的数据库中，客户端是否查询取决于其吊销检查策略；对高敏感证书用短有效期（如 24h）+ 自动续期，把"吊销滞后"的影响压到一个周期内。

八、参考链接

  1. Smallstep CLI 官方文档 — https://smallstep.com/docs/step-cli/ （查询日期 2026-10-31）
  2. step ca certificate 命令参考 — https://smallstep.com/docs/step-cli/commands/ca/certificate/ （查询日期 2026-10-31）
  3. step ca renew 命令参考 — https://smallstep.com/docs/step-cli/commands/ca/renew/ （查询日期 2026-10-31）
  4. 官方 ACME 端点文档 — https://smallstep.com/docs/step-ca/acme/ （查询日期 2026-10-31）
  5. GitHub 仓库 smallstep/certificates — https://github.com/smallstep/certificates （查询日期 2026-10-31）
  6. 站内《step-ca 0.30.2 Docker Compose 部署指南》 — https://www.quzuo.net/document/cXJikDkUOZp7
  7. 站内《step-ca 0.30.2 配置参数详解》 — https://www.quzuo.net/document/EULFdV7D9m9R
  8. 站内《Smallstep Certificates 介绍与选型指南》 — https://www.quzuo.net/document/KIfB9rTqBgRD
step-ca 0.30.2 常用 CLI 命令详解 - Quzuo