CBDC Wiki

主题

cbdc-solution · 快速开始 ​

本地开发环境统一使用仓库根的 ./dev/cbdc-dev。根 Makefile 仍保留镜像构建和兼容编排 target，但 README.md 已明确：日常开发不要用根 Makefile 启停环境。

前置 ​

  • Docker，含 Compose 与 BuildKit
  • Git / Go 1.26（只在本机 debug 或直接构建时需要）
  • Central 前端本机 debug 需要 pnpm
  • Apple Silicon 本机 debug bizhub 或 Token 节点时，需要本机 libkms_pkcs11.so

先做只读检查：

sh
./dev/cbdc-dev doctor
./dev/cbdc-dev plan

启动完整环境 ​

sh
# 清理本地 dev 运行态、构建本地镜像、启动完整栈并 Init Endorser
./dev/cbdc-dev up

# 启动后跑基础 e2e
./dev/cbdc-dev up --verify

# 启动后跑 e2e + RTGS 检查
./dev/cbdc-dev up --verify-all

up 默认启动本地 Postgres、KMS / CA、RTGS mock、Fabric-X Network 以及全部 Apps。它只管理本地 dev 资源，不会停止或删除远程资源。

常用生命周期命令 ​

sh
./dev/cbdc-dev status
./dev/cbdc-dev logs -f issuer

./dev/cbdc-dev restart infra
./dev/cbdc-dev restart network
./dev/cbdc-dev restart apps
./dev/cbdc-dev restart walletnode-1

./dev/cbdc-dev stop apps
./dev/cbdc-dev teardown

可用粗粒度 scope 是 infra、network、apps；可单独控制的应用为：

text
bizhub issuer auditor endorser1 walletnode-1 central facade

兼容别名 institution-001 仍可由控制器识别，但源码与运行单元的规范名称是 walletnode-1。

保留证书或复用镜像 ​

sh
# 保留 KMS/CA 身份与证书，清理数据库和链运行数据后重启
./dev/cbdc-dev up --keep-certs

# 不构建，只使用已经存在的本地镜像
./dev/cbdc-dev up --skip-build

# 只清运行数据，保留证书
./dev/cbdc-dev teardown --keep-certs

WebSocket P2P 使用证书 DNS SAN 校验。若手工生成或替换节点证书，应通过 gen_crypto.sh 的正式流程生成同时带 clientAuth、serverAuth 和节点 DNS SAN 的证书，不要复用缺少 serverAuth 的旧 Wallet Node 证书。

本机源码 debug ​

sh
./dev/cbdc-dev debug bizhub issuer central
./dev/cbdc-dev status apps
./dev/cbdc-dev logs -f issuer

# 修改源码后重启；当前没有自动热更新
./dev/cbdc-dev restart issuer

# 切回 Docker
./dev/cbdc-dev docker bizhub issuer central

被选应用在宿主机运行，其他应用继续在 Docker 中运行。控制器会为 Docker ↔ host 地址做转换；P2P host 地址使用 localhost:<port> 以匹配节点证书 SAN。

远程组件组合 ​

个人或远程配置写入 dev/envs/<name>.local.env：

sh
cp dev/envs/remote.env.example dev/envs/infra-remote.local.env
./dev/cbdc-dev up --env infra-remote

# 后者覆盖前者
./dev/cbdc-dev up --env infra-remote,network-remote --verify

可分别切换远程 Postgres、RTGS 和 Network；KMS 与 CA 必须一起切换。完整字段见源码仓库的 dev/USAGE.md。

验证与初始化 ​

sh
./dev/cbdc-dev verify
./dev/cbdc-dev init endorser

控制器的 up 已自动执行 Endorser Init。只有调试已启动环境或手工恢复时才需要单独运行 init endorser。

生成态目录 ​

text
dev/config/                       已提交的权威模板
dev/run/config/cbdc-infra/       KMS / CA 运行配置
dev/run/config/cbdc-network/     Network 生成配置
dev/run/config/cbdc-apps/        Docker / host 应用配置
dev/run/data/                    本地持久化数据

不要手工修改 dev/run/；它是控制器生成态。