step-ca 0.30.2 配置参数详解

目标：逐区块拆解 step-ca 0.30.2 的核心配置文件 ca.json——PKI 证书路径、网络监听、数据库、日志、authority.provisioners（JWK + ACME）、TLS 策略等全部字段，配"改配置 → 重启 → 验证生效"的真实实测回显，并给出生产配置模板。所有 JSON 片段与回显均取自 0.30.2 实例真实文件。

一、环境信息

操作系统：Linux x86_64
Smallstep CA：0.30.2（Smallstep CA/0.30.2 (linux/amd64)，Release Date: 2026-03-23 00:18 UTC）
配置文件：/home/step/config/ca.json（STEPPATH=/home/step 下的主配置），辅助文件 defaults.json
CA 服务地址：https://ca.stepca.internal:9000（对外端口 8128）
根证书指纹：2a4d06b866972e6227494089dc788d6706f70f10ed102c7261607b860c45ff5e
客户端 CLI：Smallstep CLI/0.30.2（Release Date: 2026-03-22 23:21 UTC）
部署形态：见《step-ca 0.30.2 Docker Compose 部署指南》，数据目录整体持久化

二、前置条件

已按部署篇完成 PKI 初始化（step ca init），存在 ca.json 与 defaults.json；
能以管理员身份编辑配置目录并重启 CA 进程；
修改前备份：

cp /home/step/config/ca.json /home/step/config/ca.json.bak.$(date +%F)

⚠️ 注意：step ca init 之后 CA 的日常运行只认 ca.json；defaults.json 仅服务于本机 step CLI 的缺省参数（见 5.9）。

三、参数查看与修改方式

3.1 查看当前配置

cat /home/step/config/ca.json

0.30.2 实例的真实完整内容（encryptedKey 为 JWK 加密私钥，原样保留）：

{
	"root": "/home/step/certs/root_ca.crt",
	"federatedRoots": null,
	"crt": "/home/step/certs/intermediate_ca.crt",
	"key": "/home/step/secrets/intermediate_ca_key",
	"address": ":9000",
	"insecureAddress": "",
	"dnsNames": [
		"localhost",
		"ca.stepca.internal"
	],
	"logger": {
		"format": "text"
	},
	"db": {
		"type": "badgerv2",
		"dataSource": "/home/step/db",
		"badgerFileLoadingMode": ""
	},
	"authority": {
		"provisioners": [
			{
				"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": {}
				}
			}
		],
		"template": {},
		"backdate": "1m0s"
	},
	"tls": {
		"cipherSuites": [
			"TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256",
			"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
		],
		"minVersion": 1.2,
		"maxVersion": 1.3,
		"renegotiation": false
	},
	"commonName": "Step Online CA"
}

3.2 修改与生效规则

修改 ca.json 后必须重启 CA 进程才生效（配置在启动时一次性加载）；
重启实测（本例同时修改 logger.format: text → json 与在 dnsNames 追加 acme-svc.internal.example.com）：

# 修改后重启（以编排部署为例）
docker compose restart stepca
docker logs --tail 8 stepca-0.30.2-ca

实测回显（逐行照抄，两处修改同时得到验证）：

2026/10/31 04:19:30 Community Discord: https://u.step.sm/discord
2026/10/31 04:19:30 Config file: /home/step/config/ca.json
2026/10/31 04:19:30 The primary server URL is https://localhost:9000
2026/10/31 04:19:30 Root certificates are available at https://localhost:9000/roots.pem
2026/10/31 04:19:30 Additional configured hostnames: ca.stepca.internal, acme-svc.internal.example.com
2026/10/31 04:19:30 X.509 Root Fingerprint: 2a4d06b866972e6227494089dc788d6706f70f10ed102c7261607b860c45ff5e
2026/10/31 04:19:30 Serving HTTPS on :9000 ...
{"duration":"38.07µs","duration-ns":38070,"fields.time":"2026-10-31T04:19:37Z","level":"info","method":"GET","msg":"","name":"ca","path":"/health","protocol":"HTTP/2.0","referer":"","remote-address":"10.89.56.2","request-id":"61b0f6eb-f003-4ddb-9638-7635a475349d","size":16,"status":200,"time":"2026-10-31T04:19:37Z","user-agent":"Smallstep CLI/0.30.2 (linux/amd64)","user-id":""}

验证结论：

修改项	生效证据
`dnsNames` 追加域名	启动行 `Additional configured hostnames` 出现新名字
`logger.format: json`	最后一行请求日志由 `time="..." level=info key=val` 文本形态变为纯 JSON 形态

验证后已恢复原配置（logger.format: text、dnsNames 移除临时项）并重启，日志回到 Additional configured hostnames: ca.stepca.internal 与文本日志形态。

⚠️ 注意：dnsNames 决定 CA 自身 TLS 证书覆盖的主机名。客户端 --ca-url 使用的主机名必须在此列表内，否则 x509 校验失败；新增名字重启后 CA 自动重签自身服务证书。

四、参数总览

顶层键	类型	作用	必填
`root`	string	根证书路径（客户端信任锚）	✅
`federatedRoots`	array	联合根证书（多根信任）	❌
`crt`	string	中间（签发）证书路径	✅
`key`	string	中间私钥路径（加密存储）	✅
`address`	string	HTTPS 监听地址与端口	✅
`insecureAddress`	string	额外明文 HTTP 监听（仅内网调试）	❌
`dnsNames`	array	CA 服务证书覆盖的 DNS 名	✅
`logger`	object	日志格式	❌
`db`	object	证书状态库	✅
`authority`	object	签发授权：provisioners/claims/template/backdate	✅
`tls`	object	TLS 版本与套件策略	❌
`commonName`	string	CA 名称（显示用途）	❌

五、核心参数分类详解

5.1 PKI 证书与私钥路径（root / federatedRoots / crt / key）

"root": "/home/step/certs/root_ca.crt",
"federatedRoots": null,
"crt": "/home/step/certs/intermediate_ca.crt",
"key": "/home/step/secrets/intermediate_ca_key"

root：根证书，会通过 https://<ca>/roots.pem 端点对外分发，客户端 --root 引用它建立信任；
crt + key：实际干活的中间 CA 证书与私钥。私钥由 CA 密码加密落盘，进程启动时以 --password-file 解锁；
federatedRoots：联合根列表，签发的证书链会附带这些根，适合"多根并存迁移期"。本文实例未使用（null）。

⚠️ 注意：root 与 crt 指向的证书构成信任链，任一文件损坏或权限不可读（需 uid 1000 可读）都会导致启动失败。

5.2 网络监听（address / insecureAddress / dnsNames）

"address": ":9000",
"insecureAddress": "",
"dnsNames": ["localhost", "ca.stepca.internal"]

address：:<port> 监听全部网卡，127.0.0.1:9000 则仅本机；init 时回答 :9000 即落到这里；
insecureAddress：无 TLS 的 HTTP 监听，生产保持空，仅排障时临时开启；
dnsNames：CA 自身服务证书的 SAN 列表。实测验证其生效行为见 3.2——客户端用什么主机名连 CA，该名字就必须出现在这里（localhost 是健康检查默认目标，勿删）。

5.3 数据库（db）

"db": {
	"type": "badgerv2",
	"dataSource": "/home/step/db",
	"badgerFileLoadingMode": ""
}

type：0.30.2 固定 badgerv2（嵌入式 KV，无外部依赖）；
dataSource：库目录，存放证书序列号/吊销状态/ACME 账号；运行时生成 000000.vlog、*.sst、KEYREGISTRY、LOCK、MANIFEST 五类文件；
badgerFileLoadingMode：空串即默认（loadToRAM 与 loadFileIfCached 由 badger 自决）；内存紧张时可显式设为 loadFileIfCached 之外的文件加载模式减少内存占用。

💡 说明：单实例 + 本地库是 step-ca 的默认形态；多实例高可用需共享该目录或改用支持外置存储的方案，详见官方生产考量文档。

5.4 日志（logger）

"logger": {"format": "text"}

format 取值 text（默认，key=value 形态）或 json（结构化，利于采集器解析）。两种形态的真实对照见 3.2 实测回显：text 形态为 time="..." level=info ... key=val，json 形态为单行 JSON 对象（字段含 duration、method、path、remote-address、status、user-agent 等）。

5.5 authority.provisioners：签发授权体系

provisioners 数组是"谁可以要证书、按什么条件给"的清单，每项一个 type。本文实例含 JWK 与 ACME 两类。

5.5.1 JWK provisioner（初始管理员）

{
	"type": "JWK",
	"name": "admin",
	"key": {"use": "sig", "kty": "EC", "kid": "0oxx6mWKNZVsQGXbkVua5nuy-EV2zgCUCUIMy-odYpE",
	         "crv": "P-256", "alg": "ES256", "x": "e5b-...", "y": "U5B2..."},
	"encryptedKey": "eyJhbGciOiJQQkVTMi1IUzI1NitBMTI4S1ci..."
}

字段	含义
`type: JWK`	用 JSON Web Key 做请求签名认证，init 创建的首个 provisioner 即此类型
`name: admin`	客户端 `--provisioner admin` 引用的名字
`key.kty/crv/alg`	EC P-256 + ES256 签名算法（init 默认）
`key.kid`	密钥 ID，签发回显中 `[kid: 0oxx...]` 即它
`encryptedKey`	JWK 私钥的 PBES2-HS256+A128KW 加密体；解密口令=provisioner 密码（q1w2e3r4）

签发侧配套：step ca certificate ... --provisioner admin --password-file <文件>，密码错误时报 Failed to decrypt provisioner key 类错误。

5.5.2 ACME provisioner（自动化签发）

{
	"type": "ACME",
	"name": "acme-step",
	"claims": {
		"enableSSHCA": true,
		"disableRenewal": false,
		"allowRenewalAfterExpiry": false,
		"disableSmallstepExtensions": false
	},
	"options": {"x509": {}, "ssh": {}}
}

type: ACME：开放 RFC 8555 端点，ACME 客户端经 directory URL https://<ca>/acme/<name>/directory 接入，无需密码（挑战机制自证）；
name: acme-step：出现在 directory URL 路径中；
options.x509 / options.ssh：分别控制该 ACME 端点可申请的证书种类（空对象=默认策略）。

5.5.3 claims 通用字段（provisioner 级策略）

本实例 ACME provisioner 实际携带的 4 个 claims：

claim	本例值	含义
`enableSSHCA`	`true`	允许该 provisioner 签发 SSH 证书（SSH CA 总开关，false 时 SSH 请求被拒）
`disableRenewal`	`false`	允许续期（true 则 `/renew` 拒绝）
`allowRenewalAfterExpiry`	`false`	过期后不允许补续期（true 放宽到 maxDuration 内）
`disableSmallstepExtensions`	`false`	保留 step-ca 自定义 X.509 扩展（写入证书指纹等元信息）

JWK provisioner 还可加（本例未显式配置，取默认值）：

claim	默认值	含义
`minTLSCertDuration`	`5m`	单证书最短有效期
`maxTLSCertDuration`	`24h`	单证书最长有效期
`defaultTLSCertDuration`	`24h`	未指定 `--not-after` 时的有效期
`minHostSSHCertDuration` / `maxHostSSHCertDuration`	`5m` / `1680h`	SSH 主机证书上下限
`minUserSSHCertDuration` / `maxUserSSHCertDuration`	`5m` / `24h`	SSH 用户证书上下限
`defaultHostSSHCertDuration` / `defaultUserSSHCertDuration`	`720h` / `16h`	SSH 证书默认有效期

⚠️ 注意：claims 属于 provisioner 对象内部，改完同样要重启；把 maxTLSCertDuration 放大到 8760h（1 年）前先想清楚——短有效期 + 自动续期才是 step-ca 的设计初衷。

5.5.4 authority 其他字段（template / backdate）

"template": {},
"backdate": "1m0s"

template：CA 级证书模板覆盖（Go template），空对象=使用内置默认模板；
backdate: 1m0s：签发时间回拨 1 分钟（notBefore 提前），容忍客户端轻微时钟漂移，避免"证书未生效"报错。

5.6 TLS 策略（tls）

"tls": {
	"cipherSuites": [
		"TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256",
		"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
	],
	"minVersion": 1.2,
	"maxVersion": 1.3,
	"renegotiation": false
}

字段	本例值	说明
`cipherSuites`	ChaCha20-Poly1305 + AES-128-GCM（均 ECDHE_ECDSA）	init 按中间 CA 密钥类型（EC P-256）自动优选的两套 AEAD 套件
`minVersion`	`1.2`	最低 TLS 1.2，低于此版本的握手被拒
`maxVersion`	`1.3`	上限 TLS 1.3
`renegotiation`	`false`	禁止 TLS 重协商（防重协商攻击面）

💡 说明：若中间 CA 换用 RSA 密钥，cipherSuites 应对应换成 TLS_ECDHE_RSA_* 系列，否则握手失败。

5.7 commonName

"commonName": "Step Online CA"

CA 的显示名称。它不是 TLS 证书的 CN，仅作为 CA 元信息出现，可按组织改名（改名后重启生效）。

5.8 辅助文件 defaults.json

{
	"ca-url": "https://localhost:9000",
	"ca-config": "/home/step/config/ca.json",
	"fingerprint": "2a4d06b866972e6227494089dc788d6706f70f10ed102c7261607b860c45ff5e",
	"root": "/home/step/certs/root_ca.crt"
}

这是本机 step CLI 的缺省值缓存（step path 同目录）。注意 ca-url 是 https://localhost:9000——它只对本机 CLI 有意义；跨机客户端必须显式带 --ca-url https://ca.stepca.internal:9000 --root root_ca.crt，这也是部署篇健康检查排障实录的根因。

六、生产配置模板

适用场景：2C4G 内存、40GB SSD、百级 workload 规模的内网专用 CA（证书签发属低频 IO，瓶颈在安全而非吞吐）。

{
	"root": "/home/step/certs/root_ca.crt",
	"federatedRoots": null,
	"crt": "/home/step/certs/intermediate_ca.crt",
	"key": "/home/step/secrets/intermediate_ca_key",
	"address": ":9000",
	"insecureAddress": "",
	"dnsNames": ["ca.internal.example.com"],
	"logger": { "format": "json" },
	"db": {
		"type": "badgerv2",
		"dataSource": "/home/step/db",
		"badgerFileLoadingMode": ""
	},
	"authority": {
		"provisioners": [
			{
				"type": "JWK",
				"name": "admin",
				"claims": {
					"minTLSCertDuration": "5m",
					"maxTLSCertDuration": "24h",
					"defaultTLSCertDuration": "24h",
					"disableRenewal": false,
					"allowRenewalAfterExpiry": false,
					"enableSSHCA": true
				}
			},
			{
				"type": "ACME",
				"name": "acme",
				"claims": {
					"enableSSHCA": false,
					"disableRenewal": false,
					"allowRenewalAfterExpiry": false
				},
				"options": { "x509": {}, "ssh": {} }
			}
		],
		"template": {},
		"backdate": "1m0s"
	},
	"tls": {
		"cipherSuites": [
			"TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256",
			"TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256"
		],
		"minVersion": 1.2,
		"maxVersion": 1.3,
		"renegotiation": false
	},
	"commonName": "Example Internal CA"
}

模板要点（与 init 默认的差异）：

dnsNames 收敛为唯一对外域名，删除 localhost 之外的多余名字（健康检查用 --ca-url 显式指向，见部署篇）；
JWK provisioner 显式声明 claims：证书最长 24h，短有效期 + 自动续期；
ACME provisioner 关闭 SSH（enableSSHCA: false），SSH 签发收敛到受控的 JWK/OIDC 通道；
日志用 json 形态直供采集器；
启动命令保持 step-ca /home/step/config/ca.json --password-file /home/step/secrets/password；密码文件权限收紧为 600 且属主为运行用户。

七、常见问题

Q1：改了 ca.json 不生效？

配置在启动时加载，改完必须重启进程；docker compose restart 后观察启动日志行（Additional configured hostnames、日志格式）确认新值已被读取（完整实测见 3.2）。

Q2：启动报 open ...: permission denied？

certs/、secrets/、db/ 需对运行用户（uid 1000）可读可写。宿主机目录属主不符时 chown -R 1000:1000。

Q3：报 Failed to decrypt provisioner key？

JWK 签发时 provisioner 密码不对。核对 --password-file 内容与 init 时输入的 q1w2e3r4 是否一致；密码文件末尾多余空行/空格也可能导致解密失败。

Q4：客户端报 x509 校验失败（certificate is not trusted / name mismatch）？

两个检查点：--root 是否为同一份根证书；连接主机名是否在 dnsNames 列表内。往 dnsNames 加名字后重启即可（实测生效行为见 3.2）。

Q5：证书请求报 duration 违规？

--not-after 超出 provisioner 的 maxTLSCertDuration（默认 24h）。按需调大上限或缩短申请值。

八、参考链接

官方配置文档（ca.json 全字段） — https://smallstep.com/docs/step-ca/configuration/ （查询日期 2026-10-31）
官方 provisioner 文档 — https://smallstep.com/docs/step-ca/provisioners/ （查询日期 2026-10-31）
官方生产考量文档 — https://prof.infra.smallstep.com/docs/step-ca/certificate-authority-server-production （查询日期 2026-10-31）
GitHub 仓库 smallstep/certificates — https://github.com/smallstep/certificates （查询日期 2026-10-31）
站内《step-ca 0.30.2 Docker Compose 部署指南》 — https://www.quzuo.net/document/cXJikDkUOZp7
站内《Smallstep Certificates 介绍与选型指南》 — https://www.quzuo.net/document/KIfB9rTqBgRD