主题
01 · 系统整体架构
顶层目录树（实测）
来源：ls cbdc-chain/。
cbdc-chain/
├── cbdc-biz/ 业务应用（5 个 app + rtgs-mock 工具）
├── cbdc-network/ Fabric-X 网络编排（Makefile 驱动）
├── cbdc-infra/ 基础设施镜像（Makefile 仅 build-cbdc-tool 有实际构建 recipe）
├── cbdc-stress/ 压测工具（纯 Go）
├── open-docs/ 公开 VitePress 文档
├── tests/ 独立 go.mod（cbdc-chain-tests）
├── scripts/ start-kms-system.sh / check-auditor-key.sh
├── docs/ 历史设计文档（与代码脱节，本 wiki 不依赖）
└── README.mdcbdc-chain/README.md:32-33 描述的 retail/ / wholesale/ 实际不存在（已修正）；此外 ARCHITECTURE.md 描述的 cbdc-monitoring/ 目录在仓库中也不存在。
cbdc-infra 的 Makefile 中只有 build-cbdc-tool 写了真正的构建命令（cbdc-infra/Makefile:18-22，产出 cbdc-tool 镜像）。build-all（cbdc-infra/Makefile:15）虽把 build-ca-server-kms 列为前置目标，但 Makefile 未定义该目标的 recipe，make build-all 不会构建出 cbdc-ca-server-kms。该镜像由 compose 以 ${CA_SERVER_KMS_IMAGE} 形式引用并直接拉取（cbdc-biz/docker/compose-local-run-infra.yml:25，容器内跑 fabric-ca-server，编译带 pkcs11 tag 经 PKCS#11 委托 KMS）。
5 个业务应用 + 1 个工具
来源：ls cbdc-biz/app/、ls cbdc-biz/cmd/、各 cmd/<name>/main.go、cbdc-biz/conf/<role>/core.yaml。
| 应用 | 入口 | gRPC | FSC P2P | 配置 |
|---|---|---|---|---|
| Endorser | cbdc-biz/app/endorser/cmd/endorser/main.go | 9300 | 9301 | cbdc-biz/conf/endorser1/core.yaml:7, 24 |
| Issuer | cbdc-biz/app/issuer/cmd/issuer/main.go | 9100 | 9101 | cbdc-biz/conf/issuer/core.yaml:9, 30 |
| Auditor | cbdc-biz/app/auditor/cmd/auditor/main.go | 9750 | 9751 | cbdc-biz/conf/auditor/core.yaml:16, 67 |
| Institution-001 | cbdc-biz/app/institution/cmd/institution/main.go | 9500 | 9501 | cbdc-biz/conf/institution-001/core.yaml:8, 46 |
| BizHub | cbdc-biz/app/bizhub/cmd/bizhub/main.go | 9000 | — | cbdc-biz/conf/bizhub/core.yaml:50 |
rtgs-mock（工具） | cbdc-biz/cmd/rtgs-mock/main.go | — | — | compose-rtgs-mock.yml 启动；用于本地模拟 RTGS |
详见各 app 深度页：auditor / bizhub / endorser / institution / issuer。
5 个 app 的运营方与职责
来源：综合各应用 cmd/<app>/main.go、cbdc-biz/conf/<role>/core.yaml、pkg/views/*。
| 应用 | 运营方 | 技术栈 | 主要职责 | 关键代码 |
|---|---|---|---|---|
| institution-001 | 商业银行（per-bank 一个实例） | Kratos + FSC + Token SDK | 托管用户钱包；发起转账 / 赎回；对外 REST（/api/v1/wallets/* / /api/v1/transfers/*）；UTXO 选币；钱包审批轮询 | cbdc-biz/app/institution/cmd/institution/main.go；pkg/views/{transfer,accept_transfer}.go；pkg/token_selector/ |
| bizhub | 中央银行 | Kratos + gRPC | 跨机构清算编排；发行 / 赎回 RPC 路由；RTGS 网关；三 Worker（Pending / Retry / Timeout） | cbdc-biz/app/bizhub/cmd/bizhub/main.go:42-54；internal/biz/settlement_biz.go；pkg/rtgs/ |
| issuer | 中央银行 | Kratos + FSC | 持 Issuer 钱包；IssueCashView 真签；调审计 + 背书；Broadcast | cbdc-biz/app/issuer/cmd/issuer/main.go；pkg/views/issue.go |
| endorser | 中央银行 | Kratos + FSC | 部署 TMS（DeployTMSs()）；注册 AuditResponderView + AuditAndEndorseView 两个响应视图（main.go:107） | cbdc-biz/app/endorser/internal/biz/endorser.go；pkg/views/{endorsement,audit}.go |
| auditor | 监管 / 央行审计部 | Kratos + FSC | 持 Auditor 私钥签 σ；只读聚合（ttxdb.QueryTransactionsParams）；持仓 NewHoldingsFilter；FinalityCaptureWorker 索引 | cbdc-biz/app/auditor/internal/biz/auditor.go；internal/worker/finality_capture_worker.go |
辅助工具：cbdc-biz/cmd/rtgs-mock/main.go（本地 RTGS 模拟，由 compose-rtgs-mock.yml 启动）。
用户密钥托管
用户不持有链上私钥，由 institution 作为托管钱包持有（cbdc-biz/pkg/keystore/：PKCS12 / JKS 两种文件后端）。owner 身份用 Idemix（零知识身份），issuer 用 ECDSA P-256。源头身份由 cbdc-ca-server-kms 镜像（sign-ca 打包的 fabric-ca-server，编译带 pkcs11 tag）通过 PKCS#11 委托给 sign-kms 签发（KMS_TOKEN_LABEL / KMS_USER_PIN 鉴权）。
9 个外部包 + cbdc-chain 的归属
| 角色 | 包 / 仓库 | 出处 |
|---|---|---|
| 身份 CA | fabric-ca | 上游 |
| 身份 CA（容器化） | sign-ca | Sign |
| 密钥管理 | sign-kms | Sign |
| Fabric-X 工具集 | fabric-x | 上游 |
| 排序服务 | fabric-x-orderer | 上游 |
| 提交服务 | fabric-x-committer | 上游 |
| 客户端 SDK | fabric-x-sdk | 上游 |
| 应用框架 | fabric-smart-client | 上游 |
| Token UTXO | fabric-token-sdk | 上游（cbdc-biz 取 v0.11.0，cbdc-biz/go.mod:17） |
| 业务实现 | cbdc-chain | Sign |
三层运行视图
依据：
bizhub的上游 gRPC 客户端：upstream.issuer.addr: ${UPSTREAM_ISSUER_ADDR}（cbdc-biz/conf/bizhub/core.yaml:75）与institutions[].endpoint.addr: ${INSTITUTION_001_ADDR}（cbdc-biz/conf/bizhub/core.yaml:26）；env 默认UPSTREAM_ISSUER_ADDR=issuer:9100/INSTITUTION_001_ADDR=institution-001:9500（cbdc-biz/.env.example:87-88）。- 各应用反向连 bizhub：
biz.bizhub_addr: ${BIZHUB_ADDR}（cbdc-biz/conf/{endorser1,issuer,auditor,institution-001}/core.yaml）。 - FSC P2P 端口分配规律：业务端口 + 1。
与外部 monitoring 系统的关系
当前仓库内未发现可观测性栈
ARCHITECTURE.md 描述过 cbdc-monitoring/（VictoriaMetrics 全家桶），但 cbdc-chain/ 顶层无该目录。应用代码侧实现：
cbdc-biz/pkg/signet/— Sign 的 OpenTelemetry 封装（trace + middleware）cbdc-biz/pkg/observability/— 日志 / 指标辅助- 各
core.yaml中的observability.tracing.endpoint字段（默认从 envOTLP_ENDPOINT注入）
具体监控栈的部署形态需查公司其他仓库或运维配置，本仓库内不包含。
关键代码入口
| 用途 | 文件 |
|---|---|
| 启动业务应用 | cbdc-biz/app/<app>/cmd/<app>/main.go |
| FSC 节点启动 | cbdc-biz/pkg/common/nodesdk/ |
| 跨包 View | cbdc-biz/pkg/views/（含 transfer.go / accept_transfer.go / issue.go / redeem.go / audit.go / endorsement.go / finality_registry.go / token_optimization.go / audit_metrics.go / warmup.go） |
| 一键启动脚本 | cbdc-chain/scripts/start-kms-system.sh |
go.mod 关键依赖
来源：cbdc-biz/go.mod（cbdc-chain · 概述）。
| 依赖 | 版本 | 用途 |
|---|---|---|
github.com/hyperledger-labs/fabric-smart-client | v0.11.0（go.mod:16） | FSC 框架 |
github.com/hyperledger-labs/fabric-token-sdk | v0.11.0（go.mod:17） | Token UTXO |
github.com/hyperledger/fabric-ca | v1.5.16 | CA 客户端 |
github.com/go-kratos/kratos/v2 | v2.9.2 | gRPC + Wire DI |
entgo.io/ent | v0.14.6 | BizHub ORM |
github.com/redis/go-redis/v9 | v9.18.0 | Token Selector 分布式后端 |
github.com/lib/pq | v1.10.9 | PostgreSQL |
go.mod 仅有四条 replace（cbdc-biz/go.mod:309-315），均把 go.opentelemetry.io/otel/log 等 OTel 包钉到旧的 Record-signature 版本（v0.6.0 / v0.5.0），等待上游 FSC 补丁；fabric-token-sdk 与 fabric-smart-client 已直接取 v0.11.0，无 Built-by-Sign 分支 replace。