主题
cbdc-solution · 模块详解
工作区模块
| 路径 | Go module | 说明 |
|---|---|---|
cbdc-token/ | github.com/built-by-sign/cbdc-token | 四个 FSC / Token 节点及共享 Token 业务包 |
cbdc-bizhub/ | github.com/built-by-sign/cbdc-bizhub | 业务权威与 RTGS 编排 |
cbdc-central/ | github.com/built-by-sign/cbdc-central | 管理服务与 Web Console |
cbdc-facade/ | github.com/built-by-sign/cbdc-facade | 银行侧 API 网关 |
cbdc-common/ | github.com/built-by-sign/cbdc-common | 跨模块公共库和公开客户端 |
cbdc-rtgs-mock/ | github.com/built-by-sign/cbdc-rtgs-mock | RTGS mock |
cbdc-stress/ | cbdc-stress | 压测工具 |
dev/controller/ | github.com/built-by-sign/cbdc-chain/dev/controller | 开发环境控制器 |
tests/ | cbdc-solution-tests | 集成测试 |
cbdc-token
应用
| 应用 | 入口 | 业务端口 | Proto 服务 |
|---|---|---|---|
| Issuer | app/issuer/cmd/issuer | 9100 | IssuerService |
| Endorser | app/endorser/cmd/endorser | 9300 | EndorserService |
| Wallet Node | app/walletnode/cmd/walletnode | 9500 / HTTP 9502 | WalletNodeOpsService |
| Auditor | app/auditor/cmd/auditor | 9750 | AuditorService |
四个应用共享 cbdc-token/docker/Dockerfile。构建循环和镜像内二进制名称都是 auditor issuer endorser walletnode。
公共包
| 包 | 职责 |
|---|---|
pkg/nodesdk | FSC 启动、动态 node resolver 同步 |
pkg/token/views | issue / transfer / redeem / audit / endorsement 等 FSC View |
pkg/token/wallet | 钱包身份、策略钱包、pending transaction、签名器 |
pkg/token/idemixholder | 银行自持 Idemix 密钥与 enrollment 辅助 |
pkg/token/selector | memory / Redis 分布式 UTXO 选择器 |
pkg/token/utxomgr | UTXO 合并、拆分与规划 |
pkg/token/fee / marked | 费用与资产标记 |
pkg/audit/* | 规则集、撤销、拒绝和审计信封签名 |
pkg/client/bizhub | Token 节点访问 BizHub 的 mTLS client |
关键依赖
cbdc-token/go.mod 当前直接依赖 Panurus、FSC v0.14.2、Fabric-X common v0.2.7、Kratos v3 和 Redis。Panurus module 通过 replace 指向 Built-by-Sign fork；旧的 fabric-token-sdk v0.11.0 描述已过时。
cbdc-bizhub
BizHub 内部按边界拆分：
text
api/management/v1 Central-facing 管理 API
api/runtime/v1 Token / Facade 运行时 API
api/v1/bizhub 结算、费用、审批、审计和索引兼容 API
internal/service/* DTO、认证、use-case 调用
internal/biz/<module> 状态机、事务和 Ent 访问
internal/data 数据库与通用事务基础设施
internal/worker 结算、策略 reconcile、节点注册调度当前 Ent schema 共 20 个：
text
account_type asset_mark asset_mark_limit
audit_rejection_log auditor_ruleset auth_client
fee_config fee_transaction index_cursor
institution ledger_transaction node_registry
node_registry_meta settlement_request sys_message
tx_selector_group wallet_lifecycle wallet_meta
wallet_status_log wallet_tagbizhub migrate 使用独立的 bizhub_schema_migrations 版本链。BizHub 是 cbdc_biz 的 schema 与迁移权威。
cbdc-central
Central 包含：
internal/auth：密码、session、OTP、WebAuthn；internal/approval：审批定义、实例、任务与执行命令；internal/audit：管理操作审计与字段脱敏；internal/client：BizHub management 与 Auditor 客户端；internal/data：Central 自有数据库；web：React / Vite 管理前端。
Central 的 9 个 entity schema 文件为 approval、notification、sys_audit_log、sys_role、sys_role_permission、sys_session、sys_user、sys_user_role、sys_webauthn_credential，另有共享 mixin。approval.go 定义 6 个审批 entity，因此合计生成 14 个 entity。业务机构、费用、标记、标签与规则不在 Central DB 保留权威副本。
cbdc-facade
Facade 当前不是脚手架，结构为：
text
api/v1/{wallet,transfer,transaction}.proto
internal/auth 请求签名规范化、校验、公钥快照
internal/client BizHub + 分片 Wallet Node clients
internal/service 三个银行侧服务的编排与响应映射
internal/server gRPC / HTTP 注册、统一错误 envelopeFacade 无本地数据库。它从 BizHub 刷新 auth_client 公钥，依据签名上下文确定调用机构；钱包绑定请求按钱包 ID 分片路由。
cbdc-common
当前公共能力包括：
| 包 | 职责 |
|---|---|
auth/mtls | 从已验证客户端证书提取角色，RequireRoles 显式授权 |
client/* | Auditor / BizHub / Issuer / Wallet Node 客户端与生成快照 |
noderegistry | 节点注册模型和同步协议 |
wallet / walletlifecycle / policy | 钱包 ID、生命周期和策略共享类型 |
transport/grpc | TLS client 配置与拨号 |
observability/signet | OpenTelemetry / Signet 初始化 |
scheduler / syncutil / workerpool | 后台调度、周期同步和并发边界 |
cbdc-infra 与 dev
cbdc-infra 负责：
cbdc-tool镜像；cbdc-orderer-kms；cbdc-committer-kms。
dev/controller 负责解析环境组合、构建/拉取镜像、生成证书和配置、启动分层 Compose、切换 host debug、初始化 Endorser 以及执行验证。开发 topology 位于 dev/config/network/。
tests
集成测试当前覆盖：审计规则、费用、标记 token、批量转账、Endorser proxy、账本索引以及 Idemix policy key。测试连接地址和 BizHub mTLS 材料由 controller 在 verify 阶段注入。