CBDC Wiki

主题

sign-pki · 快速开始 ​

前置条件 ​

  • Docker 24+，包含 buildx 与 Compose。
  • 可以拉取 SIGN_KMS_IMAGE；构建时从该镜像复制 libkms_pkcs11.so。
  • 多架构推送前已登录目标 registry。
  • 真实 PKCS#11 集成或 e2e 前，目标 KMS Key、SKI、Access Token 与 CA 环境已由运维侧准备。

以下命令均在 sign-pki/ 目录执行。

构建发布物 ​

bash
make build                  # CA Server，默认镜像 sign-ca:latest
make build-pki-cli          # pki-cli，默认镜像 pki-cli:latest

覆盖镜像或 Fabric CA 版本：

bash
make build \
  IMAGE_URL=registry.example/sign-pki-ca:v1 \
  SIGN_KMS_IMAGE=registry.example/sign-kms:v1 \
  FABRIC_CA_REF=v1.5.22

多架构目标默认推送 linux/amd64,linux/arm64：

bash
make build-multi IMAGE_URL=registry.example/sign-pki-ca:v1
make build-pki-cli-multi PKI_CLI_IMAGE_URL=registry.example/pki-cli:v1

使用 pki-cli ​

bash
cd pki-cli
make build
./pki-cli --help

推荐用 Catalog 一次生成并校验 CA 公开资产：

bash
cp bundle-catalog.example.yaml bundle-catalog.yaml
# 填写组织、KMS Endpoint、SKI 和有效期；真实 Access Token 只放环境变量
export KMS_PIN_IDENTITY_ROOT='<access-token>'
# 还需导出 Catalog 中所有 enabled target 对应的 pinEnv

make gen BUNDLE_CONFIG=bundle-catalog.yaml
./pki-cli bundle verify --config bundle-catalog.yaml

单目标运行时使用 NAME 或 --name：

bash
make gen BUNDLE_CONFIG=bundle-catalog.yaml NAME=bank001-identity-ca
./pki-cli bundle verify \
  --config bundle-catalog.yaml \
  --name bank001-identity-ca

若单独生成 Intermediate，必须先用同一 Catalog 生成对应 Root 目标。全部目标一次执行时必须使用同一 KMS Endpoint；不同 Endpoint 应按 --name 分进程执行。

启动本地 KMS 与 CA ​

bash
make kms-up

KMS 默认地址：gRPC 127.0.0.1:9200，Web UI http://127.0.0.1:9201。准备好 KMS Key 与本地 CA Bundle 后：

bash
cp local-run/ca-server/.env-example local-run/ca-server/.env
# 只在 .env 中填写 KMS_PIN，不提交该文件
make ca-up

本地 Compose 启动三个 HTTP CA：

CA地址
Central Bank TLS CAhttp://localhost:7052
Central Bank Identity CAhttp://localhost:7054
Wallet CAhttp://localhost:7056

Operations 端点只监听容器回环地址，不映射到宿主机。本地配置仅用于开发/e2e，不能作为生产模板。

测试 ​

pki-cli 的普通测试不需要真实 HSM：

bash
cd pki-cli
go vet ./...
go test ./...

真实 PKCS#11 集成测试只消费已存在的 KMS Key：

bash
cd pki-cli
make test-integration

CA e2e 会注册、续签、吊销身份并改变目标 CA 数据库，只在专用环境执行：

bash
make test-e2e

可用 E2E_CA_URL、E2E_OPS_URL、E2E_CA_NAME 等环境变量指定目标；详细场景见 sign-pki/ca-server/e2e/README.md。

停止本地环境 ​

bash
make ca-down
make kms-down

两个 down 目标都带 -v，会删除对应的本地具名 volume。它们只适用于可重建的开发/e2e 环境，勿对承载真实材料的环境执行。