sign-ca · 架构

本章只描述源码与配置文件可直接观察到的事实（镜像构成、容器编排、端口、卷）。设计意图与性能特征不在本章覆盖；如有需要，请参考上游 fabric-ca 与 sign-kms 文档。

镜像构成（Dockerfile 三阶段）

来源：Dockerfile 第 7-93 行。

Stage 1 — sign-kms-source（第 7-9 行）

FROM ${SIGN_KMS_IMAGE} AS sign-kms-source

目的：作为 libkms_pkcs11.so 的来源镜像。

Stage 2 — fabric-ca-builder（第 17-54 行）

• 基础镜像：golang:1.26，--platform=$BUILDPLATFORM（第 17 行）。
• ARG：BUILDARCH、TARGETARCH、TARGETOS=linux（第 18-20 行）。
• apt 源替换为阿里云镜像（第 25-32 行）。
• 安装交叉编译工具链（第 29-30 行）：
  • amd64：gcc-x86-64-linux-gnu libc6-dev-amd64-cross
  • arm64：gcc-aarch64-linux-gnu libc6-dev-arm64-cross
• 生成 xbuild-cgo 脚本（第 36-45 行）：按 TARGETARCH 选择 GCC（x86_64-linux-gnu-gcc 或 aarch64-linux-gnu-gcc）。
• 默认 fabric-ca 版本：FABRIC_CA_REF=v1.5.16（第 47 行）。
• 克隆与编译（第 48-54 行）：

  git clone --branch ${FABRIC_CA_REF} --depth=1 \
      https://github.com/hyperledger/fabric-ca.git /build/fabric-ca
  WORKDIR /build/fabric-ca
  xbuild-cgo make fabric-ca-server -j"$(nproc)" GO_TAGS=pkcs11

Stage 3 — runtime（第 60-93 行）

• 基础镜像：ubuntu:24.04（第 60 行）。
• apt 安装（第 65-72 行）：ca-certificates、curl、libgrpc++1.51t64、libprotobuf32t64、libprotobuf-c1。
• 拷入文件：
  • COPY --from=fabric-ca-builder /build/fabric-ca/bin/fabric-ca-server /usr/local/bin/（第 75 行）
  • COPY --from=sign-kms-source /usr/lib/libkms_pkcs11.so /usr/local/lib/libkms_pkcs11.so（第 78 行）
• 创建工作目录 /etc/hyperledger/fabric-ca-server（第 81、83 行）。
• EXPOSE 7054 9443 8125（第 86 行）。
• HEALTHCHECK：curl -f http://localhost:9443/healthz，interval=30s、timeout=3s、start-period=10s、retries=3（第 89-90 行）。
• CMD ["fabric-ca-server", "start", "--idemix.curve", "gurvy.Bn254"]（第 93 行）。

容器编排（docker-compose.yaml）

来源：docker-compose.yaml 第 10-46 行。

服务 kms（第 10-23 行）

字段	值
image	${SIGN_KMS_IMAGE}
container_name	sign-kms
restart	unless-stopped
ports	9200:9200（gRPC）、9201:9201（HTTP / Web UI）
environment	KMS_AUTH_SECRET=1234567890111223（第 19 行硬编码）
volumes	kms-tokens:/var/lib/softhsm/tokens、./kms-conf:/sign-kms/conf、kms-data:/sign-kms/data

服务 ca（第 25-42 行）

字段	值
image	${IMAGE_URL}
container_name	sign-ca
restart	unless-stopped
ports	7054:7054（fabric-ca REST）、9443:9443（operations）
environment	SIGN_KMS_ENDPOINT=kms:9200、FABRIC_CA_SERVER_BCCSP_PKCS11_LABEL=${KMS_LABEL}、FABRIC_CA_SERVER_BCCSP_PKCS11_PIN=${KMS_PIN}
volumes	./conf:/etc/hyperledger/fabric-ca-server
depends_on	kms

命名卷（第 44-46 行）

• kms-tokens
• kms-data

多 CA 部署（deploy/multi-ca）

来源：deploy/multi-ca/docker-compose.yaml 第 1-117 行。

四个 services：

Service	image	container_name	对外端口
kms	${SIGN_KMS_IMAGE}	sign-kms	9200:9200、9201:9201
postgres	postgres:18.3-alpine3.23	sign-ca-pg	5432:5432
pg-init	postgres:18.3-alpine3.23	sign-ca-pg-init	无
ca-bank1	${IMAGE_URL}	sign-ca-bank1	7054:7054、9443:9443

pg-init 用 profiles: ["init"]（第 66 行），不随 up 启动；需手动 docker compose run --rm pg-init。

注释（第 1-26 行）说明 bootstrap 顺序：先 kms + postgres → 去 Web UI 创建 partition + 拿 JWT → 回填 .env → 跑 pg-init → 放好 intermediate cert → 起 ca-bank1。

根 CA 没有 service；deploy/multi-ca/root/ 仅有静态文件（ca-cert.pem + README.md）。详见 deploy/multi-ca/root/README.md [未读]。

暴露的端口汇总

端口	协议	用途	来源
7054	HTTP	fabric-ca REST API	Dockerfile:86、docker-compose.yaml:30
9443	HTTP	operations (/healthz 等)	Dockerfile:86、docker-compose.yaml:30
8125	UDP	StatsD（conf/fabric-ca-server-config.yaml:272 指向 127.0.0.1:8125）	Dockerfile:86
9200	gRPC	sign-kms（被 libkms_pkcs11.so 连接）	docker-compose.yaml:14
9201	HTTP	sign-kms Web UI	docker-compose.yaml:14

go.mod 依赖

module github.com/built-by-sign/sign-ca

go 1.25.1

require github.com/miekg/pkcs11 v1.1.2

无间接依赖。

与 sign-kms 的连接点

• 镜像构建期：Dockerfile:78 从 sign-kms 镜像拷出 /usr/lib/libkms_pkcs11.so。
• 运行期：docker-compose.yaml:33 设置 SIGN_KMS_ENDPOINT=kms:9200，由 libkms_pkcs11.so 读取（具体 env 名见 sign-kms 仓库的 p11client/）。
• 鉴权：KMS_PIN 经 FABRIC_CA_SERVER_BCCSP_PKCS11_PIN env 注入 fabric-ca，再透传到 .so（来源：docker-compose.yaml:38、README.md:107）。