04 · 部署拓扑

本章基于 cbdc-biz/docker/compose-*.yml、cbdc-network/Makefile、cbdc-infra/Makefile、scripts/start-kms-system.sh 的代码实证。

三段启动顺序

来源：cbdc-chain/scripts/start-kms-system.sh（main :1277、setup_network :997、start_biz :1056）。

flag 选项（scripts/start-kms-system.sh）：

flag	用途
--skip-build	跳过镜像构建（scripts/start-kms-system.sh:179）
--skip-rtgs	不启动 rtgs-mock（:183）
--quick	快速重启模式：teardown 并重启 biz 与 network，跳过 setup，保持已起的 KMS / CA（:187、teardown_quick :904-920）
--local-kms	本地 KMS / CA 模式（:191）

cbdc-network 编排

来源：cbdc-network/Makefile（聚合 target 见 :199-263）、cbdc-network/configs/、cbdc-network/.env.example。

target	用途
make setup-kms	clean setup-fabric-kms fetch-fabric-ca-root gen-compose-kms：调用 cbdc-tool 生成 out/ 下 crypto + 配置 + docker-compose.yaml（KMS 模式，Makefile:237）
make setup	clean setup-fabric gen-compose：同上但走 cryptogen 非 KMS 模式（Makefile:201）
make start	start-fabric：cd out && docker compose up -d（Makefile:124-126、251）
make create-ns	fxconfig namespace create cbdc，创建并等待 cbdc namespace（Makefile:139-150）
make list-ns	fxconfig namespace list
make teardown	teardown-fabric：docker compose down -v + 删除 cbdc_net 网络（不删 out/，不删镜像；删 out/ 由 make clean，Makefile:185-193、255）

configs/ 模板：

• test-full-kms.yaml / test-full-kms-postgres.yaml / test-full-kms-yugabyte.yaml — KMS 模式
• test-full.yaml — 纯 cryptogen，4 个 OrdererOrg
• test-simple.yaml — 最简，仅 OrdererOrg1

out/ 是 setup 阶段生成

cbdc-network/out/ 在 make setup / make setup-kms 之前不存在，由 cbdc-tool 的 config-builder setup（crypto + 配置）与 config-builder gen-compose（docker-compose.yaml）生成（Makefile:87-115）。make start 即在 out/ 内 docker compose up -d。

cbdc-biz 编排

来源：cbdc-biz/docker/、cbdc-biz/Makefile。

compose 文件清单：

文件	服务 / 用途
compose-build-base.yml	构建 Go 依赖基础镜像 cbdc-biz-builder-base
compose-build.yml	构建 5 业务 app 镜像：auditor / issuer / endorser / bizhub / institution
compose-local-run.yml	本地启 postgres + 5 应用
compose-local-run-infra.yml	本地启 kms + ca（--local-kms 用）
compose-rtgs-mock.yml	rtgs-smb（SMB 共享）+ rtgs-responder（模拟 RTGS）

compose-local-run.yml 服务：postgres / auditor / issuer / endorser1 / bizhub / institution-001（docker/compose-local-run.yml:40-218）。该文件不含 Redis 服务；BizHub 的 Redis 地址为 host.docker.internal:6379（conf/bizhub/core.yaml:68），指向 compose 外的 Redis。postgres 容器名 cbdc_local_db，启动时建库 cbdc_wholesale / cbdc_retail / cbdc_issuer / cbdc_endorser1 / cbdc_auditor / cbdc_bizhub / cbdc_institution（compose-local-run.yml:50-56）。

cbdc-infra 编排

来源：cbdc-infra/Makefile:13-36、cbdc-infra/cbdc-tool/Dockerfile、cbdc-infra/.env-example。

target	输出镜像
make build-cbdc-tool	${IMAGE_PREFIX}/cbdc-tool:${TAG}（Makefile:18-22）
make build-push	build-all + push cbdc-tool 与 cbdc-ca-server-kms（Makefile:26-29）
make version	git describe --match infra/*（Makefile:33-36）

build-ca-server-kms 未定义

Makefile:15 中 build-all 依赖 build-ca-server-kms、build-push 推送 cbdc-ca-server-kms 镜像，但该 Makefile 内没有定义 build-ca-server-kms target；启动脚本也直接调用它（scripts/start-kms-system.sh:951）。Makefile 内唯一可单独执行的构建 target 是 build-cbdc-tool。

cbdc-tool 镜像以 ghcr.io/built-by-sign/fabric-x-tool 为基础镜像（自带 fxconfig / config-builder 等 fx 工具链），并从 sign-kms 镜像拷入 libkms_pkcs11.so（cbdc-infra/cbdc-tool/Dockerfile:5-20）。

Fabric-X 网络层（Arma + Committer）

来源：fabric-x-orderer · 架构、fabric-x-committer · 架构；cbdc-network/configs/test-full-kms.yaml 的拓扑配置 [未核 — 此处只引用代码与包 wiki]。

Orderer 4 个角色（Arma BFT）：Router / Batcher / Consenter / Assembler，详见 fabric-x-orderer · 02-架构。

Committer 5 个微服务：Sidecar / Coordinator / Verifier / Validator-Committer / Query Service，详见 fabric-x-committer · 02-架构。

端口汇总（实测）

业务平面

服务	端口	出处
Endorser gRPC	9300	cbdc-biz/conf/endorser1/core.yaml:7
Endorser FSC P2P	9301	同 :24
Issuer gRPC	9100	cbdc-biz/conf/issuer/core.yaml:9
Issuer FSC P2P	9101	同 :30
Auditor gRPC	9750	cbdc-biz/conf/auditor/core.yaml:16
Auditor FSC P2P	9751	同 :67
Institution-001 gRPC	9500	cbdc-biz/conf/institution-001/core.yaml:8
Institution-001 FSC P2P	9501	同 :46
Institution-001 HTTP REST	9502	cbdc-biz/app/institution/internal/server/http.go:37-38、cbdc-biz/docker/compose-local-run.yml:202
BizHub gRPC	9000	cbdc-biz/conf/bizhub/core.yaml:50

账本平面 — Orderer（每 Org 4 进程，按 Org 偏移 +100）

来源：cbdc-network/configs/test-full.yaml:26-113、fabric-x-orderer · 02-架构。

Org	Router	Batcher	Consenter	Assembler
OrdererOrg1	7050	7051	7052	7053
OrdererOrg2	7150	7151	7152	7153
OrdererOrg3	7250	7251	7252	7253
OrdererOrg4	7350	7351	7352	7353

test-full.yaml 默认 4 个 OrdererOrg（test-full.yaml:27-126）；test-simple.yaml 仅启 Org1，Org2–4 被注释（test-simple.yaml:49-113）。

账本平面 — Committer

来源：cbdc-network/configs/test-full.yaml:128-157、fabric-x-committer/service/vc/config.go:66、fabric-x-committer · 02-架构。

子组件	端口	出处
committer-validator	5100	cbdc-network/configs/test-full.yaml:140
committer-verifier	5200	同 :144
committer-coordinator	5300	同 :148
committer-sidecar	5400	同 :152
committer-query-service	5500	同 :156
committer-db (Postgres)	5435	同 :133
各 committer 进程 metrics	2116	fabric-x-committer/service/vc/config.go:66（DefaultMonitoringPort）

身份与存储

服务	端口	出处
Fabric CA REST	7054	cbdc-network/.env.example、fabric-ca
KMS gRPC	9200	sign-kms · API
KMS HTTP / Web UI	9201	同
Postgres（biz 层）	5432	cbdc-biz/conf/bizhub/core.yaml:66（容器 cbdc_local_db）
Redis	6379	cbdc-biz/conf/bizhub/core.yaml:68（institution-001 的 Redis 配置默认注释，见 conf/institution-001/core.yaml:30-34）
RTGS / SMB	445	cbdc-biz/conf/bizhub/core.yaml:96

监控栈

文档描述存在，仓库内无对应代码

以下端口来自本仓库外部的部署文档（本仓库不含该文件，无法核验），cbdc-chain 顶层不存在 cbdc-monitoring/ 目录，端口取决于实际部署方使用的镜像。

组件	端口（文档值）
Grafana	3000
OpenTelemetry Collector (OTLP gRPC)	4317
VictoriaMetrics	8428
vmagent	8429
victoria-logs	9428
victoria-traces	10428

业务平面 metrics 端口 [未核]

本仓库外部的部署文档（本仓库不含该文件）列出 bizhub:9010 / issuer:9110 / endorser:9310 / institution:9510 / auditor:9760，但 cbdc-biz/conf/*/core.yaml 与 cbdc-biz/app/*/internal/server/ 中未直接搜到这些端口；实际监听值取决于 signet / OpenTelemetry 注入逻辑（见 05 · 数据流）。

启动依赖图

来源：scripts/start-kms-system.sh + cbdc-network/Makefile + cbdc-biz/Makefile + cbdc-biz/docker/compose-local-run.yml。

关键依赖约束：

1. cbdc-tool 先于 orderer / committer — cbdc-network/Makefile: setup-kms 调用 cbdc-tool 生成 out/，否则 orderer 启动时找不到 crypto material。
2. 账本层先于业务层 — Issuer / Institution 启动会 dial Orderer broadcast 与 Committer query；账本未起则 retry 死循环。
3. bizhub 先于 institution — compose-local-run.yml 中 institution-001 depends_on bizhub（service_healthy，compose-local-run.yml:216-220）。
4. endorser 注册 audit responder — Endorser 启动时注册 AuditResponderView / AuditAndEndorseView（cbdc-biz/app/endorser/cmd/endorser/main.go:107-109）；转账流必须经 endorser 背书（见 composition/05-data-flow）。compose-local-run.yml 中 endorser1 / issuer 仅 depends_on postgres（:153-155、:124-126），跨服务先后由各应用 dial 后的 retry 保证。
5. monitoring 完全独立 — 启停不影响业务平面；监控栈缺失只丢可观测数据，不阻塞链上交易。

--quick 模式 teardown 并重启 biz 与 network（含账本层），仅保持已起的 KMS / CA、跳过 setup（见上方 三段启动顺序）。

镜像版本管理

来源：cbdc-chain/README.md:241-256、各子项目 Makefile。

子项目	git tag 前缀	示例
cbdc-biz	biz/	biz/v0.0.6
cbdc-network	network/	network/v0.1.0
cbdc-infra	infra/	infra/v0.0.3

各子项目 make version 从 git describe --match <prefix>/* 自动生成。

多银行部署

[未核]

cbdc-biz/app/ 下仅 1 个 institution 应用（目录 app/institution，compose 实例名 institution-001）；多银行实例化的具体编排 [未核] — compose 文件与 conf 目录中未发现现成的多银行模板。

biz.institution_code 配置在 cbdc-biz/conf/institution-001/core.yaml:16（值 "001"），缺失时 main.go panic（app/institution/cmd/institution/main.go:127-128）。bizhub/core.yaml 的 institutions 列表已预留追加更多机构（code: '002' 等）的注释模板（conf/bizhub/core.yaml:32-40）。

监控栈

文档描述存在，仓库内无对应代码

cbdc-chain/docs/ARCHITECTURE.md 描述过 cbdc-monitoring/（VictoriaMetrics + Grafana + OTel Collector + Fluent Bit），但 cbdc-chain 顶层不存在该目录。

应用代码侧实现了 OpenTelemetry 注入点（cbdc-biz/pkg/signet/ / pkg/observability/），实际监控栈应部署在公司其他仓库或运维基础设施上。本仓库内不提供监控栈编排。

signet 接 OTLP_ENDPOINT env（来自 cbdc-biz/.env.example），具体由部署方接到合适的 OpenTelemetry 接收端。

[未核]

• cbdc-monitoring/ 的实际部署位置（在哪个仓库）。
• 多银行 institution 实例的完整 compose 模板。
• 各 AZ 之间的网络要求（仓库内无相关配置）。
• 生产环境的 KMS / Postgres / Redis 副本配置（compose 文件为本地开发用）。