sign-ca · 模块详解

本仓库 submodule：sign-ca/。每条均带 file:line 引用，路径均相对于该 submodule 根。

顶层

路径	行数 / 说明	出处
README.md	136 行；9 个章节	README.md
Dockerfile	93 行；3 个 stage（sign-kms-source / fabric-ca-builder / runtime）	Dockerfile
Makefile	85 行；8 个 target	Makefile
docker-compose.yaml	2 service：kms、ca	docker-compose.yaml
.env-example	env 模板	—
go.mod	module=github.com/built-by-sign/sign-ca、go=1.25.1、唯一依赖 github.com/miekg/pkcs11 v1.1.2	go.mod:1-5
todo.md	36 行；e2e 实现进度	todo.md

conf/ — fabric-ca 配置

文件	行数	说明
conf/fabric-ca-server-config.yaml	279	fabric-ca-server 主配置。顶层段：version、port、debug、crlsizelimit、tls、ca、bccsp、csr、registry、db、affiliations、signing、crl、intermediate、ldap、operations、metrics

kms-conf/ — sign-kms 服务端配置

文件	行数	顶层 key
kms-conf/sign-ca.yaml	33	server、data、observability、hsm

cmd/sign-ca-cli/ — 离线工具

文件	行数 / 说明	出处
main.go	61 行；os.Args[1] switch 分发入口（非 cobra）	cmd/sign-ca-cli/main.go:27-47
commands/doc.go	20 行；包注释 + defaultLib 常量	commands/doc.go
commands/self_sign.go	RunSelfSign	main.go:33
commands/gen_csr.go	RunGenCSR	main.go:35
commands/sign_csr.go	RunSignCSR	main.go:37
pki/cert.go	X.509 / CSR 模板（未细读）	—
pki/p11.go	PKCS#11 helper（未细读）	—
pki/ski.go	SKI 推导（未细读）	—

main.go:49-61 中的 usage 输出：

sign-ca-cli self-sign  [flags]   # self-signed root CA cert
sign-ca-cli gen-csr    [flags]   # CSR signed by a KMS-resident key
sign-ca-cli sign-csr   [flags]   # issue cert by signing a CSR with a KMS-resident key

必需 env：SIGN_KMS_ENDPOINT（main.go:59-60）。

默认 PKCS#11 库路径：/usr/local/lib/libkms_pkcs11.so（commands/doc.go:20）。所有子命令支持 --pkcs11-lib 覆盖（commands/doc.go:19）。

[未核]

三个子命令的完整 flag 列表（除 --pkcs11-lib）。需直接读 commands/*.go。

e2e/ — 集成测试

总计 846 行（3 个文件）。

文件	行数	关键符号
e2e_test.go	93	build tag e2e（第 1 行）；TestMain（第 56-69 行）；全局 state（第 33-54 行）
helpers_test.go	188	signECDSALowS（37-48）、genFabricCAToken（50-69）、doWithToken（71-103）、doWithAdminToken（105-109）、enrollWithBasicAuth（111-188）
scenarios_test.go	565	TestCAFlow（28-39）+ 10 个 t.Run 子测

10 个子测（scenarios_test.go）：

#	名称	行号
01	testHealthz	45-67
02	testCAInfo	73-145
03	testEnrollAdmin	154-170
04	testRegisterUser	172-214
05	testEnrollUser	217-232
06	testVerifyCertChain	235-278
07	testReenroll	282-373
08	testListIdentities	376-422
09	testRevoke	425-474
10	testGenCRL	477-563

全局 state 字段（e2e_test.go:33-54）：caCerts / caRoots / adminKey / adminCert / adminCertPEM / userName / userSecret / userKey / userCert / userCertPEM / revokedDone。

deploy/multi-ca/ — 多 CA 部署模板

路径	说明
docker-compose.yaml	117 行；4 个 service：kms / postgres / pg-init / ca-bank1
.env.example	29 行；变量见 配置
postgres/init.sql	DB 初始化 SQL [未读]
root/README.md	根 CA 离线仪式说明 [未读]
root/ca-cert.pem	由 sign-ca-cli 生成的根 cert
bank1/bank1.csr	中间 CA CSR
bank1/ca-cert.pem	中间 CA cert（由 root 离线签）
bank1/sign-ca.yaml	bank1 fabric-ca-server 配置 [未读]

docs/

来源：README.md:119-122 提到的两份文档。

文件	用途
docs/fabric-ca-server-guide.md	[未读]，README 提及
docs/e2e-scenarios.md	[未读]，README 第 117 行提及

Makefile target 一览

target	行号	主要命令
help	17-31	打印用法
check-env	33-38	test -n "$(SIGN_KMS_IMAGE)"
build	40-47	docker buildx build --load（单架构）
build-multi	49-57	docker buildx build --platform --push（多架构）
test-setup	59-70	条件启动：KMS_PIN 空 → 仅 kms；否则 kms + ca
test-teardown	72-74	docker compose down
test-e2e	78-80	go test -tags=e2e -v -count=1 ./e2e/...
clean	82-85	docker compose down -v + docker rmi

来源：Makefile。

看代码推荐路径

1. README.md → 仓库目标与两阶段启动。
2. Dockerfile → 三阶段构建产物（fabric-ca-server 与 libkms_pkcs11.so 的来源）。
3. docker-compose.yaml → 运行时编排。
4. conf/fabric-ca-server-config.yaml → 关键配置段（特别是 bccsp 段，第 55-89 行）。
5. Makefile:59-70 → test-setup 两阶段判断逻辑。
6. e2e/scenarios_test.go → 10 个 t.Run 子测覆盖业务面。
7. cmd/sign-ca-cli/main.go → 离线工具入口；细节看三个 commands/*.go。