cbdc-bizhub

BizHub 是 CBDC 业务数据与状态机权威，监听 9000 mTLS。它不运行 FSC 节点；Token 交易由 Wallet Node / Issuer / Auditor / Endorser 执行。

单镜像、双运行模式

同一 bizhub 二进制支持：

mode	专属 API	专属后台任务
`runtime`	Node Registry runtime、Client Auth Data	节点注册初始化、runtime workers
`management`	机构、节点、规则、费用、标记、标签、拒绝日志管理	不启动 runtime-owned workers
空值	两者都启用，供开发使用	两者都启用

命令行使用 -mode runtime|management。all 不是合法值。生产可把同一镜像部署成独立 Management 与 Runtime workload；代码不是只靠鉴权隐藏 handler，而是在 server 注册时就按 mode 裁剪。

包边界

text

api/management/v1       Central-facing
api/runtime/v1          Wallet Node / Facade / Token-facing
api/v1/bizhub           结算、费用、审批、审计、索引
internal/service        通用 transport service
internal/service/management
internal/service/runtime
internal/service/mapper
internal/biz/<module>   业务规则、状态机、事务、Ent
internal/data           DB client 与通用事务设施
internal/worker         后台 worker

Service 层只做请求形状、调用身份、use-case 调用、DTO 映射和错误转换；状态机、幂等和数据库事务放在 Biz 层。

API 注册

Runtime / public business

RuntimeConfigService
FeeService
runtime WalletService
SettlementService
ApprovalService
BizhubAuditorService
IndexerService
runtime mode 下另注册 NodeRegistryService、ClientAuthDataService

Management

NodeRegistryManagementService
InstitutionManagementService
RuleManagementService
FeeManagementService
MarkManagementService
TagManagementService
AuditRejectionQueryService

Management 方法显式要求 mtls.RoleCentral。Runtime 方法按资源要求允许 walletnode、facade、issuer、auditor、endorser 等具体角色。

mTLS 身份

server 开启 clientAuthRequired 时：

TLS 层用 clientRootCAs 验证客户端证书；
cbdc-common/auth/mtls.ServerIdentityMiddleware 从已验证链提取身份；
每个 service 方法使用 mtls.RequireRoles；
钱包归属、实例绑定等数据级授权由 Biz use-case 校验。

请求体不是身份来源。

数据库所有权

BizHub 独占 cbdc_biz 的 schema 与迁移权威。当前 20 个 Ent schema：

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_tag

Central 不直接读写或迁移这些表；它通过 Management RPC 操作。

迁移

cd cbdc-bizhub
make migrate-diff name=<short_name>
make ent
make migrate-verify

运行时由 one-shot bizhub migrate -conf <path> 应用内嵌迁移，版本表为 bizhub_schema_migrations。普通 Runtime / Management 启动不执行 DDL。

Wallet 生命周期与策略

BizHub 是 wallet ID 分配和生命周期权威：

分配可由 shard 解析的钱包 ID；
保存创建 intent / checkpoint，使 X.509 创建可恢复和幂等；
保存钱包元数据、证书状态和策略权威模型；
处理 policy projection 与 reconcile；
管理 auth_client，供 Facade 刷新银行验签公钥。

Wallet Node 持有 Token owner 的本地投影，BizHub 持有跨节点路由与业务权威记录。

Node Registry

node_registry 与 node_registry_meta 保存节点角色、实例、地址与动态 resolver 数据。Runtime API 接收节点注册/心跳和 resolver 查询；Management API 供 Central 管理。Wallet Node 路由按 shard code，Auditor / Endorser resolver 可动态同步。

结算与 RTGS

BizHub 经 MT298 + SMB 连接 RTGS，使用：

Pending / Retry / Timeout settlement workers；
Issuer client；
按 shard 选择的 Wallet Node client；
JKS / PKCS12 keystore；
cbdc-rtgs-mock 本地对手方。

策略 reconcile worker 与 Node Registry schedules 归 Runtime mode；Management-only 进程不会启动它们。

配置

关键字段：

yaml

cbdc: { symbol: SOM }
server:
  grpc:
    address: 0.0.0.0:9000
    tls:
      enabled: true
      clientAuthRequired: true
data:
  database:
    source: ... dbname=cbdc_biz ...
upstreams:
  issuer: { address: ... }
  walletNodes:
    - shardCode: "1"
      address: ...

CA 配置现在是单一 wallet CA，而不是每个 Wallet Node 一套 CA；admin MSP 仍可使用 KMS-backed key。

构建

cd cbdc-bizhub
make test
make build
make api
make config
make wire
make ent

生成文件只能通过对应 Make target 更新。

cbdc-bizhub ​

单镜像、双运行模式 ​

包边界 ​

API 注册 ​

Runtime / public business ​

Management ​

mTLS 身份 ​

数据库所有权 ​

迁移 ​

Wallet 生命周期与策略 ​

Node Registry ​

结算与 RTGS ​

配置 ​

构建 ​