06 · 关键设计取舍

本章记录当前代码能够直接证明的设计约束。历史方案文档只作背景，不作为运行事实。

1. 开发环境由 `cbdc-dev` 控制器统一编排

规范入口是仓库根下的 ./dev/cbdc-dev。控制器负责准备配置与证书、生成 Fabric-X 网络、启动基础设施和业务进程，并把产物写到 dev/run/。

旧 scripts/start-kms-system.sh、顶层 cbdc-network/ 和根 Makefile 启停链不再是当前开发基线。控制器仍识别少量兼容别名，例如 institution-001，但规范运行单元是 walletnode-1。

2. Wallet Node 取代 Institution 应用

Token 侧四个二进制是 auditor、issuer、endorser、walletnode，共享一个 Token Docker 镜像。银行侧内部 RPC 是 WalletNodeOpsService；源码目录是 cbdc-token/app/walletnode。

institution 仍作为业务概念和部分数据库兼容命名存在，但不应继续用于 Go 应用路径、服务名或二进制名。

3. Token driver 由所选配置集决定

配置集	driver	公共参数
`dev/config/token/*`	`zkatdlog`	`zkatdlognoghv1_pp.json`
`cbdc-token/conf/*`	`fabtoken`	`fabtoken1_pp.json`

两者的链驱动都是 fabricx。因此“系统固定使用 fabtoken”或“系统固定使用 zkatdlog”都不准确，部署文档必须写明加载的配置路径。

4. Panurus 是直接依赖，FSC 与 Fabric-X 版本已升级

cbdc-token/go.mod 当前直接依赖：

github.com/LFDT-Panurus/panurus/integration 的 v0.14.3 预发布版本；
github.com/hyperledger-labs/fabric-smart-client v0.14.2；
github.com/hyperledger/fabric-x-common v0.2.7。

Panurus 主模块通过 replace 指向 Built-by-Sign fork。旧的 fabric-token-sdk v0.11 与 FSC v0.11 依赖说明已失效。

5. Facade 是已实现的银行服务面

Facade 对外监听 gRPC 9600 和 HTTP 9601，实现：

WalletService：钱包 ID、创建、证书续期、密钥及 CA/Idemix 相关操作；
TransferService：PrepareTransfer、SubmitTransfer；
TransactionService：ListTransactions。

Facade 校验 Ed25519 请求签名，通过 BizHub 获取银行身份和路由信息，再按 wallet.ShardOf(wallet_id) 把请求发给 Wallet Node。当前单分片实现要求配置的 shard code 等于 walletid.SingleShard；外部调用方不应承担 shard 路由。

6. BizHub 明确区分 runtime 与 management 面

BizHub API 分布在 api/runtime/v1、api/management/v1 与兼容的 api/v1/bizhub。启动 mode 接受：

runtime
management
空值（注册完整服务集）

all 不是有效 mode。服务端先通过 mTLS 解析调用方身份，再以方法级 RequireRoles 限制权限。

7. BizHub 与 Central 分库、分迁移链

BizHub 拥有 cbdc_biz 及其 20 个 Ent schema；Central 拥有 cbdc_central 及用户、权限、审批、通知、系统审计等实体。两者都使用显式版本化迁移命令：

bash

bizhub migrate -conf <path>
central migrate -conf <path>

Central 通过 BizHub management RPC 读写机构和业务配置，而不是直接共享 BizHub 数据库。

8. 节点注册与解析是非对称的

动态 Node Registry 的职责分配如下：

节点	行为
Auditor、Endorser	`NewNodeRegistrarForNode`：注册自身 P2P/View 地址
Issuer、Wallet Node	`NewNodeResolverSyncForNode`：拉取 Auditor/Endorser 快照并更新本地 resolver

因此不能概括成“所有节点都会注册并同步”。静态 resolver 仍用于节点自己的启动信息和初始连接。

9. FSC P2P 使用 WebSocket + 双向 TLS 能力

Token 配置中的 FSC P2P transport 为 WebSocket，并配置 serverRootCAs、clientRootCAs 与较高的 maxSubConns。开发证书脚本给节点证书加入 clientAuth,serverAuth，SAN 覆盖节点域名、短名和 localhost。

开发控制器从宿主机运行 Token 进程时使用 localhost 作为 P2P 地址，原因是 TLS 校验必须匹配实际拨号 host。

10. Prepare/Submit 需要实例亲和

Wallet Node 在 Prepare 阶段把 PendingTransaction 放入进程内 store，Submit 再按 tx_id 原子取出。该状态没有由当前代码共享到 Redis 或 PostgreSQL。

所以多副本部署必须至少满足一种条件：

Prepare 与 Submit 粘到同一实例；
引入共享 pending store；
在路由协议中加入可恢复的实例提示。

仅启用分布式 Token Selector 不能解决 pending transaction 的实例亲和问题。

11. Token Selector 保留 memory / distributed 双模

Wallet Node 的 Token Selector 可使用进程内 memory 模式或 Redis-backed distributed 模式。distributed 模式解决多实例间的选币协调，但不会自动持久化上述 Prepare/Submit pending 状态。

12. Endorser 代理 Auditor 完成审计

Wallet Node 通过 AuditAndEndorseView 连接 Endorser；Endorser 再以 RequestAuditView 请求 Auditor。这样银行侧节点不需要直接向 Auditor 发起每笔交易的审计 View。

13. 基于源码得出的边界

下列内容不能仅凭当前仓库宣称为已实现事实：

具体的 5k / 50k / 100k TPS 保证；
多 Auditor 自动分片与故障切换；
任意数量 Wallet Node 副本的无状态横向扩展；
固定的生产 AZ、共识节点数或云厂商拓扑。

这些都需要部署配置、容量测试或额外协调组件作为证据。

06 · 关键设计取舍 ​

1. 开发环境由 cbdc-dev 控制器统一编排 ​

2. Wallet Node 取代 Institution 应用 ​

3. Token driver 由所选配置集决定 ​

4. Panurus 是直接依赖，FSC 与 Fabric-X 版本已升级 ​

5. Facade 是已实现的银行服务面 ​

6. BizHub 明确区分 runtime 与 management 面 ​

7. BizHub 与 Central 分库、分迁移链 ​

8. 节点注册与解析是非对称的 ​

9. FSC P2P 使用 WebSocket + 双向 TLS 能力 ​

10. Prepare/Submit 需要实例亲和 ​

11. Token Selector 保留 memory / distributed 双模 ​

12. Endorser 代理 Auditor 完成审计 ​

13. 基于源码得出的边界 ​

继续阅读 ​