04 · 部署拓扑

当前开发拓扑的权威入口是 ./dev/cbdc-dev；旧 scripts/start-kms-system.sh、顶层 cbdc-network/ 与根 Makefile 启停链不再是日常开发基线。

分层运行

控制器应用启动顺序为 BizHub → Issuer → Auditor → Endorser → Wallet Node → Central → Facade，并在启动后调用 Endorser Init。

生命周期命令

./dev/cbdc-dev up
./dev/cbdc-dev up --verify
./dev/cbdc-dev up --verify-all
./dev/cbdc-dev start infra network apps
./dev/cbdc-dev restart apps
./dev/cbdc-dev stop apps
./dev/cbdc-dev teardown

--keep-certs 保留 KMS/CA 身份与证书；--skip-build 只使用已有镜像。粗粒度 scope 为 infra、network、apps，也可指定具体 app。

本地与远程组合

单元	支持模式
Postgres	docker / remote
KMS + CA	docker / remote，两者必须一致
RTGS	docker / remote / disabled
Network	docker / remote
单个 App	Docker / host debug

命名环境放在 dev/envs/<name>.local.env，多个环境从左到右覆盖。远程资源不会被 controller 停止或删除。

目录

dev/config/                         已提交的应用模板与 Network topology
dev/envs/                           个人/远程环境覆盖
dev/run/config/cbdc-infra/         KMS / CA 运行配置
dev/run/config/cbdc-network/       Network 生成配置
dev/run/config/cbdc-apps/          Docker / host 应用配置
dev/run/data/                       本地持久化数据

dev/run/ 是生成态，不应手工修改。

镜像归属

镜像	构建位置
cbdc-token	cbdc-token/docker/Dockerfile，含四个 Token 二进制
cbdc-bizhub	cbdc-bizhub/docker/Dockerfile
cbdc-central	cbdc-central/docker/Dockerfile
cbdc-facade	cbdc-facade/docker/Dockerfile
cbdc-tool	cbdc-infra/cbdc-tool/Dockerfile
cbdc-orderer-kms / cbdc-committer-kms	cbdc-infra/cbdc-network/

Network topology 在 dev/config/network/，镜像构建在 cbdc-infra/cbdc-network/，两者职责不同。

端口

业务面

服务	业务端口	P2P / 辅助
Central	HTTP 8000 / gRPC 8001	—
BizHub	gRPC mTLS 9000	—
Issuer	gRPC 9100	P2P 9101 / FSC Web 9102
Endorser	gRPC 9300	P2P 9301 / FSC Web 9302
Wallet Node	gRPC 9500 / HTTP 9502	P2P 9501 / FSC Web 9503
Facade	gRPC 9600 / HTTP 9601	—
Auditor	gRPC 9750	P2P 9751 / FSC Web 9752

P2P 端口承载 WebSocket TLS；listenAddress 的 multiaddr 语法不表示 libp2p。

基础设施

服务	默认端口
Fabric CA	7054
sign-kms gRPC / HTTP	9200 / 9201
Postgres	5432
RTGS SMB	445
Committer notification / query	5400 / 5500

Orderer 与 Committer 具体内部端口由 dev/config/network topology 生成，不应从已删除的旧 cbdc-network/configs 示例推断当前部署。

数据库拓扑

本地可共用一个 Postgres 实例，但逻辑数据库分开：

• cbdc_biz：BizHub；
• cbdc_central：Central；
• cbdc_issuer、cbdc_endorser1、cbdc_auditor；
• Wallet Node 的数据库名以实际模板为准，dev 当前仍为 cbdc_institution。

生产可把这些逻辑库部署到不同实例。BizHub 和 Central 分别用各自 one-shot migrate job，不共享 schema 权威。

Host debug

./dev/cbdc-dev debug bizhub issuer central
./dev/cbdc-dev restart issuer
./dev/cbdc-dev docker bizhub issuer central

控制器会转换 Docker ↔ host 地址。WebSocket P2P 在 host 模式使用 localhost，以匹配节点证书 DNS SAN；不要改成未包含在证书中的 IP literal。

证书拓扑

Fabric CA Root → 共享 TLS Intermediate CA → 服务叶证书。Token 节点叶证书包含 client/server EKU 和节点 DNS SAN；Wallet Node 的统一证书同时用于 FSC P2P 与 BizHub mTLS。

扩展

• Wallet Node 以 shard_code 注册和路由，不以机构码选择进程；
• 当前代码仍有限制为单一 walletid.SingleShard；
• Auditor / Endorser 注册动态地址，Wallet Node / Issuer 同步 resolver；
• 多副本前还需处理 selector、pending transaction 与 finality watcher 的共享/亲和问题，见扩容指南。