CBDC Wiki

主题

10 · 问题排查指南 ​

先确认当前入口和配置：开发基线是 ./dev/cbdc-dev，Token 运行单元是 walletnode-1，不是旧的 institution-001 应用；dev/config/token/* 与 cbdc-token/conf/* 的 driver 不同。

启动前快照 ​

bash
./dev/cbdc-dev status
./dev/cbdc-dev logs walletnode-1
./dev/cbdc-dev logs bizhub

同时记录：当前 commit、加载的 core.yaml、pp 文件、证书目录以及 dev/run/ 中实际生成的配置。

Facade 返回认证失败 ​

检查：

  • 是否同时发送 x-key-id、x-timestamp、x-signature；
  • 签名是否基于 Facade 的规范化请求，而不是只签 body；
  • key 是否已由 BizHub ClientAuthDataService 同步到 Facade 缓存；
  • 客户端状态和机构状态是否有效；
  • HTTP JSON 字段是否符合 protojson 形态。

未知 key 与错误签名故意返回相同的 AUTH_FAILED，避免暴露 key 是否存在。

找不到 Wallet Node 或 shard ​

检查 Facade 的 Wallet Node 配置。当前 wallet.ShardOf 是单分片实现，配置 shard code 必须与 walletid.SingleShard 一致。不要用旧的机构代码/钱包尾号算法推导节点。

pending transaction not found ​

常见原因：

  • Submit 到了不同 Wallet Node 副本；
  • pending transaction 已过期；
  • 同一 tx_id 已被 Pop 或取消；
  • 节点在 Prepare 与 Submit 之间重启。

当前 pending store 在进程内。修复部署路由亲和或实现共享 store；只切换 distributed selector 不能解决该问题。

同一钱包已有 in-flight transaction ​

Wallet Node 明确阻止同一钱包同时存在未完成 pending transaction。等待当前交易完成/过期，或先调用取消接口释放对应选择器锁。不要通过重试风暴绕过保护。

Submit 成功但余额未变化 ​

SubmitTransfer 成功只表示 broadcast 已接受，finality 仍在后台。通过交易查询接口检查 Token SDK 权威状态，并查看：

  • Wallet Node FinalityWorker；
  • Orderer/Committer 日志；
  • FSC/sidecar 连接；
  • 是否出现 broadcast outcome uncertain。

不要把 HTTP/gRPC 200 直接解释为账本已提交。

Audit / Endorse 失败 ​

链路是 Wallet Node → Endorser → Auditor。逐段检查：

  1. Wallet Node resolver 是否已同步 Endorser；
  2. Endorser 是否在 BizHub Node Registry 注册了可达地址；
  3. Endorser 是否能解析并连接 Auditor；
  4. TLS root CA、SAN 与实际拨号 host 是否匹配；
  5. pp 中的 Auditor/Issuer 身份是否与运行节点一致；
  6. Auditor worker pool 是否饱和；
  7. 实际 driver 是否与 pp 文件一致。

TLS / WebSocket P2P 失败 ​

当前 FSC P2P 使用 WebSocket + TLS。检查：

  • 节点证书同时具有 clientAuth、serverAuth；
  • serverRootCAs 与 clientRootCAs 指向正确 CA；
  • SAN 覆盖实际拨号的 DNS 名或 localhost；
  • registry 中注册地址对调用方可达；
  • 从宿主机启动时是否错误使用了仅容器内可解析的服务名。

driver / pp 不匹配 ​

加载配置预期 driver预期 pp
dev/config/token/*zkatdlogzkatdlognoghv1_pp.json
cbdc-token/conf/*fabtokenfabtoken1_pp.json

四个 Token 节点必须使用同一套 TMS/pp。混用时先停止业务节点，重新生成或选择一致的公共参数，再启动并初始化 Endorser。

BizHub / Central 表缺失 ​

当前两者都使用显式 migration：

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

确认 BizHub 指向 cbdc_biz，Central 指向 cbdc_central，并检查各自 migration version。不要依赖应用启动 auto-migrate，也不要把 Central 指向 BizHub 数据库。

BizHub mode 无法启动 ​

有效 mode 为 runtime、management 或空值。all 无效。若 RPC 存在但返回权限错误，继续检查 mTLS 身份与该方法的 RequireRoles。

Auditor 链上索引没有更新 ​

确认 Auditor indexer 配置是否 enabled。启用后依次检查 block source、GetCursor、批量 lookup、AppendBatch 和 BizHub 的 ledger_transactions / index_cursors。cursor 在 BizHub 中，不在 Auditor 本地。

代码入口 ​

  • dev/internal/controller/
  • cbdc-facade/internal/auth/
  • cbdc-facade/internal/client/clients.go
  • cbdc-token/app/walletnode/internal/
  • cbdc-token/pkg/nodesdk/
  • cbdc-token/pkg/token/views/
  • cbdc-bizhub/cmd/bizhub/migrate.go
  • cbdc-central/cmd/central/migrate.go