CBDC Wiki

主题

cbdc-chain · 模块详解 ​

本仓库 submodule：cbdc-chain/。路径相对该 submodule 根。

顶层目录 ​

路径用途出处
cbdc-biz/业务服务（独立 go.mod）cbdc-biz/go.mod:1
cbdc-network/Fabric-X 网络配置部署（无 go.mod）cbdc-network/Makefile
cbdc-infra/基础设施镜像（无 go.mod）cbdc-infra/README.md:3-6
cbdc-stress/压测工具（独立 go.mod）cbdc-stress/go.mod
docs/内部设计文档—
open-docs/公开 VitePress 文档open-docs/docs/.vitepress/
scripts/start-kms-system.sh / check-auditor-key.shREADME.md:138-160
tests/独立 go.mod cbdc-chain-teststests/go.mod

cbdc-biz/ ​

5 个业务应用 ​

来源：cbdc-biz/app/、各应用 cmd/*/main.go。

应用入口（func main()）gRPC 端口端口出处
endorsercbdc-biz/app/endorser/cmd/endorser/main.go:569300conf/endorser1/core.yaml:7
issuercbdc-biz/app/issuer/cmd/issuer/main.go:619100conf/issuer/core.yaml:9
auditorcbdc-biz/app/auditor/cmd/auditor/main.go:679750conf/auditor/core.yaml:16
institutioncbdc-biz/app/institution/cmd/institution/main.go:699500conf/institution-001/core.yaml:8
bizhubcbdc-biz/app/bizhub/cmd/bizhub/main.go:589000conf/bizhub/core.yaml:50

README 与实际目录不一致

README.md:32-33, 46 提到 retail/ 与 wholesale/，但 cbdc-biz/app/ 下实际只有 auditor / bizhub / endorser / institution / issuer 5 个目录。Wholesale / Retail 应用当前不存在。

各应用共同结构：

cmd/<app>/
  ├── main.go    Kratos app 启动（flag、配置、OTel、FSC、Wire）
  └── wire.go    Google Wire 依赖注入
internal/
  ├── biz/       业务逻辑
  ├── data/      Repository + Ent ORM
  ├── service/   gRPC service 实现
  └── conf/      配置 proto
Makefile

公共包（cbdc-biz/pkg/） ​

包职责
common/nodesdkFSC 节点启动 SDK
identity/身份与钱包管理
keystore/密钥存储（PKCS#11 + JKS）
observability/OTel tracing 与日志
rtgs/SWIFT MT298 + SMB RTGS 集成
token_selector/UTXO 选币
utxo_management/UTXO 锁定
auditor/审计日志、规则树
scheduler/cron v3 定时任务
signet/OpenTelemetry 集成
views/Token SDK View 实现
workerpool/工作线程池

API（cbdc-biz/api/） ​

16 个 .proto（proto3，均在 cbdc-biz/api/cbdc-biz/v1/）。顶层服务 EndorserService / IssuerService / AuditorService / InstitutionOpsService；kms/ 下 KmsService / KmsManageService；bizhub/ 下 ManageService / WalletService / ApprovalService / SettlementService / IndexerService / CAService 等。EndorserService.Init（endorser.proto:8）即启动初始化 RPC。

cbdc-biz/go.mod ​

来源：cbdc-biz/go.mod。

依赖版本行
hyperledger-labs/fabric-smart-clientv0.11.0go.mod:16
hyperledger-labs/fabric-token-sdkv0.11.0go.mod:17
hyperledger/fabric-cav1.5.16go.mod:18
go-kratos/kratos/v2v2.9.2go.mod:12
entgo.io/entv0.14.6go.mod:6
redis/go-redis/v9v9.18.0go.mod:23
lib/pqv1.10.9go.mod:21

replace（cbdc-biz/go.mod:309-315）仅固定四个 go.opentelemetry.io/otel/log 相关包到 Record-签名版本（v0.6.0 / v0.5.0），等待 FSC 上游补丁；无 fabric-token-sdk / fabric-smart-client 的 replace。

Docker ​

来源：cbdc-biz/docker/。

文件用途
Dockerfile各应用共用同一 Dockerfile，通过构建参数 APP_NAME 在编译期选择 cmd/<app> 并产出各自镜像（cbdc-<app>，见 compose-build.yml 的 args.APP_NAME）；CMD 对所有应用相同
Dockerfile.builder-base构建基础镜像（Go 编译）
Dockerfile.rtgs-mockRTGS 模拟服务
compose-build-base.yml构建基础镜像
compose-build.yml构建应用镜像
compose-local-run.yml本地开发运行
compose-local-run-infra.yml仅基础设施（DB / KMS）
compose-rtgs-mock.ymlRTGS 模拟

institution 应用有独立 cbdc-biz/app/institution/Dockerfile。

cbdc-network/ ​

来源：cbdc-network/README.md、cbdc-network/Makefile。

文件 / 目录用途
README.md启动 / 维护命令清单
Makefilesetup / setup-kms / start / teardown / create-ns / list-ns / version / build-push
configs/test-full-kms.yaml默认 KMS 模式配置
out/docker-compose.yaml由 cbdc-tool 镜像内 config-builder gen-compose 生成（运行时）
.env.example环境变量模板

详细 make target 见 03-quickstart。

cbdc-infra/ ​

来源：cbdc-infra/Makefile、cbdc-infra/cbdc-tool/Dockerfile。

cbdc-infra/ 下仅 cbdc-tool/ 一个目录。

镜像用途
cbdc-tool基于 ghcr.io/built-by-sign/fabric-x-tool，叠加从 sign-kms 镜像复制的 libkms_pkcs11.so（cbdc-tool/Dockerfile:8,20）；提供 config-builder / fxconfig
cbdc-ca-server-kmsbuild-all / build-push 一并构建推送（Makefile:15,29）
target行号用途
make build-allMakefile:15构建 cbdc-tool + cbdc-ca-server-kms
make build-pushMakefile:26构建并推送
make versionMakefile:33查 git tag infra/*

TAG=custom-version make build-push 自定义版本（Makefile:9）。

cbdc-stress/ ​

来源：cbdc-stress/main.go、cbdc-stress/cmd/bootstrap/main.go。

路径用途
main.go压测主程序（flag 在 main.go:26-35）
cmd/bootstrap/main.go钱包批量创建 + 充值（create-mother / create-children / fund-existing）
data/<env>/预设环境的钱包文件目录（由 bootstrap 生成，被 -env 引用）

-env 预设（cbdc-stress/main.go:20-21）：

预设URL钱包路径
devhttp://34.60.193.75:9502data/dev/wallets.json
localhttp://localhost:9502data/local/wallets.json

tests/ ​

来源：tests/、tests/go.mod（module cbdc-chain-tests）。

子目录测试对象主要文件
auditor_rulesets/审计规则集limits_test.go
e2e/端到端endorser_proxy_test.go / ledger_indexer_test.go
fees/费用收集fee_collection_test.go / comprehensive_test.go / category_test.go
internal/bizclient/业务客户端工具库amount.go / walletkit.go / signer.go / conn.go
marked_tokens/资产标记marked_tokens_test.go
transfer/转账batch_transfer_test.go

测试框架：Go testing + stretchr/testify（tests/go.mod:7）。cbdc-biz 单测另用 alicebob/miniredis/v2 与 DATA-DOG/go-sqlmock（cbdc-biz/go.mod:8,46）。

docs/ ​

详见 02-architecture · docs/ 与 plans/。

open-docs/ ​

来源：open-docs/（VitePress 内容在 open-docs/docs/）。

路径用途
docs/.vitepress/VitePress 配置（config.ts / theme / components）
docs/index.md首页
docs/guide/15 个用户指南 .md
docs/architecture/overview.md架构概览
docs/changelog.md变更日志
docs/api-reference.mdAPI 参考（占位，57 字节）
Dockerfile文档站点镜像

scripts/ ​

来源：README.md:138-160、scripts/。

脚本用途
start-kms-system.sh一键 KMS 系统启动（支持 --local-kms / --quick / --skip-build）
check-auditor-key.sh审计节点密钥检查

看代码推荐路径 ​

  1. README.md → 顶层布局、三层架构、启动顺序。
  2. cbdc-biz/app/endorser/cmd/endorser/main.go:56 → 单应用启动模板。
  3. cbdc-biz/pkg/common/nodesdk/ → FSC 节点启动 SDK。
  4. cbdc-biz/pkg/utxo_management/、pkg/token_selector/、pkg/auditor/ → 核心业务原语。
  5. cbdc-network/Makefile + configs/test-full-kms.yaml → 网络部署机制。
  6. tests/e2e/、tests/transfer/ → 端到端用例。
  7. cbdc-biz/conf/<role>/core.yaml → 各应用真实运行配置（含端口、bizhub_addr、p2p、token、fabric）。