企业官网建设流程全解析

简介：面向高校毕业设计与课程设计的慈善救助信用区块链系统，基于Springboot与Hyperledger Fabric框架构建，完整覆盖慈善项目发布、信用评估、救助审批、善款追溯等核心流程，结合区块链不可篡改特性解决传统慈善信息不透明、监管追溯困难等痛点，并利用Springboot提供稳定易用的后端服务接口。压缩包共206个文件，以Java后端源码、Vue前端页面为主，同时配齐Fabric联盟链运行所需的pem/crt证书、key私钥、yaml配置及Go语言链码，整体约3.37MB，目录结构清晰，便于按模块定位学习。目前已有36人学习下载，适合计算机、信息管理等专业学生作为毕业设计、课程设计或项目初期演示使用。源码已经过严格测试可正常运行，随包附带设计文档与报告，可支撑快速理解系统架构；现有代码也方便二次改造，作为区块链技术落地实践的入门参考十分合适。

1. 慈善救助上链：为什么用Springboot对接Hyperledger Fabric而不是自己搭一条公链

如果你接过慈善类的Web项目，大概率做过一套“捐款登记+救助名单”的CRUD：一个MySQL表存捐款人，一个表存受助人，再一个表存审批记录。这套东西最大的问题是救助人和他的救助历史分散在多个机构、多个数据库里，A机构给他发过助学金，B机构不知道；他之前有没有逾期还款、有没有重复申请，全靠人工去查。所以课设题目里出现“信用区块链”，不是噱头，是要解决“救助记录不可篡改、跨机构可查、重复救助可识别”这个真问题。Springboot结合Hyperledger Fabric的慈善救助信用区块链系统，思路就是让Spring Boot继续负责Web接口、文件上传、权限拦截这些老本行，把资产和审批记录挪到底层Fabric链上，用链码把救助申请、审核、放款、还款这几个动作变成状态流转。这套路适合两类人：一类是做区块链课设但不想从零写共识的，另一类是已经有Spring Boot经验、想低成本把区块链模块接进来的。下面我按自己做过的方案，把网络、链码、Java集成和踩坑一条线讲完。

2. 先把Fabric联盟链跑起来：用fabric-samples的test-network搭一个最小可用网络

Fabric 2.x 的开发和部署路径已经很固定：官方维护的 fabric-samples 仓库里带了一个 test-network 脚本，能一键起两组织、两 peer、一个排序节点、两个 CA 的最小联盟链。课设阶段不建议自己手写编排文件，test-network 足够让你理解节点关系，而且删了可以一键重置，省掉我早期用 docker-compose 手工拼配置时的那种玄学排错时间。

2.1 启动命令与容器清单：确认orderer、peer、CA、CouchDB都活着

先确认本机有 Docker 和 Docker Compose，然后把 fabric-samples 克隆下来，进入 test-network 目录执行：

cd fabric-samples/test-network ./network.sh down ./network.sh up createChannel -c reliefchannel -ca -s couchdb

第一行 down 是为了清掉上次残留的容器和卷，避免端口占用。第二行拆开看：up 是拉起整个网络，createChannel 表示启动后立刻创建通道，-c reliefchannel 把通道名从默认的 mychannel 改成业务名，-ca 表示启动独立的 CA 容器（否则脚本会用 cryptogen 直接生成组织证书放目录里，少两个容器但没法演示证书签发流程），-s couchdb 是把 peer 的状态数据库从默认的 LevelDB 切成 CouchDB，这个选项直接决定后面能不能做富查询。

启动成功后在另一个终端执行 docker ps，应该能看见这些容器：

peer0.org1.example.com peer0.org2.example.com orderer.example.com ca_org1 ca_org2 couchdb0 couchdb1

这里的关键点：每个 peer 旁边挂了一个 CouchDB 容器，排序节点只有一个，CA 有两个。这个拓扑对应的是 Fabric 最常见的最小配置——两个组织共同维护一条通道，任何交易要上链必须同时得到两个组织 peer 的背书。检查容器状态时如果发现某个 peer 反复重启，用 docker logs peer0.org1.example.com 看输出，多半是证书目录挂载路径写错。

2.2 用CLI手工调用一次链码：验证背书流程而不是直接写Java

拿到一个刚启动的 Fabric 网络，我先不急着写 Java，而是用 peer CLI 手工部署一个官方示例链码并调用一次。这样做的原因是：如果 CLI 这层都不通，后面 Java 报错时你根本分不清是网络问题还是 SDK 问题。

export PATH=${PWD}/../bin:$PATH export FABRIC_CFG_PATH=${PWD}/../config export CORE_PEER_TLS_ENABLED=true export CORE_PEER_LOCALMSPID=Org1MSP export CORE_PEER_TLS_ROOTCERT_FILE=${PWD}/organizations/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt export CORE_PEER_MSPCONFIGPATH=${PWD}/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp export CORE_PEER_ADDRESS=localhost:7051

这组环境变量的含义：PATH 要指向 fabric-samples/bin 下的 peer 二进制，FABRIC_CFG_PATH 指向 core.yaml 所在目录，CORE_PEER_LOCALMSPID 声明你当前以哪个组织身份操作，MSPCONFIGPATH 指向该组织管理员的私钥和证书目录，CORE_PEER_ADDRESS 是 peer0.org1 的 gRPC 地址。每次换组织操作，只需要把 MSPID、TLS 根证书、MSP 路径、peer 地址四个变量一起换。

接着部署链码，这里先用官方 Java 链码示例验证链路：

./network.sh deployCC -ccn relief -ccp ../asset-transfer-basic/chaincode-java/ -ccl java

部署成功会看到 Chaincode code package identifier 之类的输出。然后查询一次：

peer chaincode query -C reliefchannel -n relief -c '{"Args":["GetAllAssets"]}'

如果返回一个空数组 []，说明查询路径通。再提交一笔：

peer chaincode invoke -C reliefchannel -n relief -c '{"Args":["CreateAsset","1","red","100","org1","alice"]}'

这里 invoke 和 query 的本质区别：invoke 走完整的背书、排序、出块流程，返回的是交易是否提交成功；query 只在一个 peer 上做本地读，不产生区块。你能看到 invoke 的输出里有链码返回的 payload，底层逻辑还是异步上块，不要被控制台的即时返回误导。把这层调通以后，Java 集成里的坑就少了一半。

2.3 频道与排序参数：-ca 和 -s couchdb 到底改变了什么

很多人跑通了脚本，但对两个参数一知半解。先说 -ca。不带它时，网络启动速度更快，但证书是用 cryptogen 一次性生成后静态落盘的，你拿不到证书签发过程的 CA 容器。带了 -ca，每个组织会启动一个 fabric-ca-server，后续你可以用 CA 的 REST 接口为新的用户动态签发证书，而不用重新 down 网络。课设里如果要做“新增用户并授予权限”的演示，务必带这个参数。

再说 -s couchdb。LevelDB 是嵌入在 peer 进程里的，查询只能按 key 来做精确匹配。CouchDB 是一个独立的文档数据库，peer 把世界状态同步给它，你可以用 JSON 选择器做富查询，比如“查所有状态为 APPLIED 的救助单”。代价是多两个容器、多占大概 1GB 内存（每个 CouchDB 容器约 400MB）。如果你的电脑只有 8GB 内存，又是课设演示，宁可用默认 LevelDB 只做 key 查询，也别让 CouchDB 把机器拖卡。

启动完成后验证通道情况，一条命令能看到通道内最新区块高度：

peer channel getinfo -c reliefchannel

输出里的 blockchainHeight 初始是 1，只有创世块。后面每成功提交一笔交易，这个数字就会上涨。这也是验收时向评委展示“链上确实在记账”最直接的证据。

3. 链码设计：把救助申请、审核、放款、还款写成可追溯的状态机

Fabric 里链码是业务逻辑的核心，Spring Boot 只是壳。慈善救助的信用问题拆到链上，本质是一笔救助资金的完整生命周期：申请、核验、审批、放款、还款（或者核销）。如果只把结构化数据塞进 Fabric 当数据库用，那不如用 MySQL。链码的价值在于两件事：一是状态流转必须经过显式调用且留有签名背书，二是历史不可篡改，每一步都有交易ID和时间戳。

3.1 资产结构：为什么用救助编号做复合键而不是只用UUID

救助资产我用 Go 写，结构体长这样：

type ReliefApplication struct { ApplicationId string `json:"applicationId"` ApplicantName string `json:"applicantName"` ApplicantIDCard string `json:"applicantIdCard"` ReliefType string `json:"reliefType"` Amount float64 `json:"amount"` Status string `json:"status"` ApplyOrg string `json:"applyOrg"` ApprovedOrg string `json:"approvedOrg"` CreatedAt string `json:"createdAt"` UpdatedAt string `json:"updatedAt"` }

我先讲清楚为什么主键不用 UUID 字符串。Fabric 世界状态是 KV 存储，key 决定了查询效率。使用 UUID 做主键，查一个受助人过往所有救助记录时，必须做全量扫描然后过滤，效率很低，也绕过了 CouchDB 的索引进而在演示时给自己挖坑。常见做法是用复合键或者带业务含义的键，例如：

applicantKey, err := ctx.GetStub().CreateCompositeKey("relief", []string{ applicantIDCard, applicationId, })

CreateCompositeKey 是 Fabric 链码提供的工具函数，第一个参数是类型前缀，后面是拼接字段。生成出来的 key 形如 “relief\uff000xId\uff00app001”。这样做的直接好处：查一个受助人的全部救助记录时，可以用 GetStateByPartialCompositeKey 按前缀扫描，天然支持范围查询，而且不需要 CouchDB 索引就能跑通。申请人身份证号是敏感字段，存储时可以做哈希后作为第二维度，但课设阶段为了演示可读性，通常直接用脱敏后的编号。

3.2 核心状态流转：从申请到还款的5个状态与权限校验

状态机是信用系统的骨干。我设计了五个状态：

APPLIED → VERIFIED → APPROVED → DISBURSED → REPAID ↘ → OVERDUE

APPLIED 是受助人或社区专员提交救助申请；VERIFIED 是核验人员确认身份和家庭收入信息；APPROVED 是审批人决定救助金额和救助方式；DISBURSED 是资金已经发放；REPAID 是借款人完成还款或公益救助完成核销。如果约定还款期限到期仍未还款，状态置为 OVERDUE，这笔记录进入受助人的负面信用档案。

为什么一定要有 VERIFIED 这个中间状态？传统 CRUD 里核验只是把某个字段改成 true，但在区块链语境下，每一步都代表一个独立的组织或角色在交易上签名。核验人、审批人、放款人可以是不同组织，背书策略才能体现“多方共治”。如果一个人提交完申请就把状态直接改成 APPROVED，那这条链和单机数据库没有区别，评委一问“你凭什么证明审批人是真实机构“就会卡住。

链码里对每个状态变更做权限校验，核心代码：

func (s *SmartContract) ApproveApplication(ctx contractapi.TransactionContextInterface, applicationId string) error { application, err := s.readApplication(ctx, applicationId) if err != nil { return fmt.Errorf("读取救助单失败: %v", err) } if application.Status != "VERIFIED" { return fmt.Errorf("救助单状态不是 VERIFIED，当前状态: %s", application.Status) } clientMSPID, err := ctx.GetClientIdentity().GetMSPID() if err != nil { return fmt.Errorf("获取调用者身份失败: %v", err) } if clientMSPID != "Org1MSP" { return fmt.Errorf("只有审批机构 Org1MSP 可以执行审批操作") } application.Status = "APPROVED" application.ApprovedOrg = clientMSPID application.UpdatedAt = time.Now().Format(time.RFC3339) key, err := ctx.GetStub().CreateCompositeKey("relief", []string{ application.ApplicantIDCard, application.ApplicationId, }) if err != nil { return err } applicationBytes, err := json.Marshal(application) if err != nil { return err } return ctx.GetStub().PutState(key, applicationBytes) }

这段逻辑有三层意思。第一层，状态校验放在入参校验之后、写库之前，防止并发提交时把已审批的单子再次审批。第二层，GetMSPID 判断调用者属于哪个组织，这里写死 Org1MSP 只是示例，实际课设建议把可执行审批的 MSP 列表做成通道参数或链码初始化参数，不要硬编码在方法里，否则评审老师问“换个组织怎么办”你不好答。第三层，写状态时重新生成复合键再 PutState，因为从世界状态读出来的应用对象本身不携带 key 信息，如果你用原始 key 写入，会有冗余。

3.3 CouchDB富查询与历史溯源：给评委演示“这个人的救助记录没法改”

前面说 CouchDB 的意义在于富查询。链码里如果直接调 GetStateByRange，只能按 key 顺序扫，没法按状态过滤。用 CouchDB 的话，可以先在链码包里声明索引。在链码目录下创建 META-INF/statedb/couchdb/indexes/statusIndex.json：

{ "index": { "fields": ["status", "updatedAt"] }, "ddoc": "statusIndexDoc", "name": "statusIndex", "type": "json" }

这个设计文档会在链码部署时自动安装到 CouchDB。注意 ddoc 和 name 是唯一标识，修改索引时如果改了名字，旧的设计文档会残留。索引字段顺序有讲究，status 放前面用于等值过滤，updatedAt 放后面用于排序，反过来会让排序无法利用索引。

部署链码后，链码内用 JSON 选择器做富查询：

func (s *SmartContract) QueryByStatus(ctx contractapi.TransactionContextInterface, status string) ([]*ReliefApplication, error) { queryString := fmt.Sprintf(`{"selector":{"status":"%s"}}`, status) resultsIterator, err := ctx.GetStub().GetQueryResult(queryString) if err != nil { return nil, err } defer resultsIterator.Close() var applications []*ReliefApplication for resultsIterator.HasNext() { queryResponse, err := resultsIterator.Next() if err != nil { return nil, err } var application ReliefApplication err = json.Unmarshal(queryResponse.Value, &application) if err != nil { return nil, err } applications = append(applications, &application) } return applications, nil }

GetQueryResult 是链码 SDK 里专门给 CouchDB 用的接口，LevelDB 模式下调用它会直接报错。这就是为什么我在第 2 章反复强调启动网络要带 -s couchdb。

历史溯源是区块链课设里最有说服力的演示点。核心调用是 GetHistoryForKey，链码侧把它暴露成一个查询接口：

func (s *SmartContract) GetReliefHistory(ctx contractapi.TransactionContextInterface, applicationId string) ([]interface{}, error) { key, err := ctx.GetStub().CreateCompositeKey("relief", []string{ applicantIDFromQuery, applicationId, }) if err != nil { return nil, err } historyIterator, err := ctx.GetStub().GetHistoryForKey(key) if err != nil { return nil, err } defer historyIterator.Close() var history []interface{} for historyIterator.HasNext() { response, err := historyIterator.Next() if err != nil { return nil, err } var value map[string]interface{} if len(response.Value) > 0 { err = json.Unmarshal(response.Value, &value) if err != nil { return nil, err } } history = append(history, map[string]interface{}{ "txId": response.TxId, "timestamp": response.Timestamp, "value": value, "isDelete": response.IsDelete, }) } return history, nil }

返回结果里每一项都带着交易ID和背书时间戳。演示时你可以先做一次 UPDATE，再拉历史，就能看到同一条 key 下出现两个版本的 world state。你可以当场把历史里的旧值修改掉——试试看，链码不会允许直接改以前的版本，因为每个版本都绑定着哈希链上的区块。这就是”不可篡改“的直观证明。

4. Springboot集成Fabric网关：Java侧连接、提交与查询的最小工程

网络和链码通了，接下来就是把 Spring Boot 项目接进 Fabric。这一步的痛点是 Spring Boot 开发者普遍对 Fabric 的连接模型不熟，一看 connection.yaml 和 wallet 目录就懵。其实可以把它类比成数据库连接：connection.yaml 是数据源配置，wallet 是账号密码，Contract 对象是 Mapper，submitTransaction 是写操作，evaluateTransaction 是读操作。

4.1 依赖与选型：fabric-gateway-java的版本和包体积控制

Java 对接 Fabric 有两条路：fabric-sdk-java 和 fabric-gateway-java。sdk-java 是老一代方案，API 复杂，需要手动管理 HFClient、Channel、Peer 对象，课设代码会显得很臃肿。我推荐用官方 Gateway API，依赖就一个：

<dependency> <groupId>org.hyperledger.fabric</groupId> <artifactId>fabric-gateway-java</artifactId> <version>2.2.0</version> </dependency>

这个包会传递依赖 gRPC 和 protobuf。需要说明的是，fabric-gateway-java 2.2 对应 Fabric 2.4 及以上版本的 Gateway 服务，跑通 test-network 没有问题。如果你的 Fabric 网络是 2.2 LTS 老版本，别硬上 2.2 的 gateway-java，去用 1.4 版的 fabric-gateway-java，它走的是旧的 gRPC 通道，兼容性更好。这里版本匹配是个典型翻车点，后面避坑章节细说。

我提一个工程组织的建议：不要在主启动类里直接写连接逻辑，单独建一个 fabric 子包，里面放 config、service 两层。这样后面换网络配置、加链码方法，都不用碰 Controller。

4.2 connection.yaml与钱包目录：证书放哪、MSP怎么配

先看配置文件。在 test-network 目录里其实已经生成了 connection profile，路径是：

fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/connection-org1.yaml

这份文件可以直接复制到 Spring Boot 的 resources 目录里，但默认生成的还包含了 orderer 地址、CA 地址、两个 peer 的 gRPC URL。我通常会把不相关的 peer 条目删掉，只留下 org1 的节点，避免 Java 端在 discovery 时选到跨组织节点导致超时。

精简后的 connection-org1.yaml 关键部分：

name: ReliefNetwork-org1 version: 1.0.0 client: organization: Org1 connection: timeout: peer: endorser: "120" channels: reliefchannel: peers: peer0.org1.example.com: endorsingPeer: true chaincodeQuery: true ledgerQuery: true eventSource: true organizations: Org1: mspid: Org1MSP peers: - peer0.org1.example.com peers: peer0.org1.example.com: url: grpcs://localhost:7051 tlsCACerts: path: ./crypto-config/peerOrganizations/org1.example.com/peers/peer0.org1.example.com/tls/ca.crt

注意这里的 path 是相对路径，网关加载时会以 yaml 文件所在目录为基准。如果你把连接文件放到 resources/fabric/ 下，证书路径就得写 resources/fabric/crypto-config/... 相对路径经常踩坑，我后面会给一个更稳的做法：在 Java 里用 ClassPathResource 读证书，拼绝对路径再填进配置。实际上更常见的做法是标准连接文件路径使用 fabric-samples 里的绝对路径，或者把 organizations 目录拷贝进工程。

然后是钱包目录。Fabric 网关的 wallet 是一个文件夹，里面存用户的身份材料。课设最省事的方式是在 test-network 启动后，把 Admin@org1.example.com 的私钥和证书拷出来：

mkdir -p wallet/adminOrg1/msp/keystore mkdir -p wallet/adminOrg1/msp/signcerts cp organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/*_sk wallet/adminOrg1/msp/keystore/ cp organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/signcerts/cert.pem wallet/adminOrg1/msp/signcerts/

也可以借助 Java 侧工具直接从 org 目录加载身份并写入 wallet：

Path walletPath = Paths.get("wallet"); Wallet wallet = Wallets.newFileSystemWallet(walletPath); Path identityDirectory = Paths.get("crypto-config/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp"); Identity identity = X509Identity.newIdentity("Org1MSP", certificate, privateKey); wallet.put("admin", identity);

这段逻辑说明：Wallets.newFileSystemWallet 会创建或打开一个本地钱包目录；put 方法将身份写入钱包，第一个参数是用户名标识，后续 gateway 构造时只要用这个名字就能找到身份材料。

4.3 把链码调用封装成Service：submitTransaction和evaluateTransaction的分工

Java 侧的核心配置类长这样：

@Configuration public class FabricGatewayConfig { @Bean(destroyMethod = "close") public Gateway gateway() throws Exception { Path walletPath = Paths.get("wallet"); Wallet wallet = Wallets.newFileSystemWallet(walletPath); Path networkConfigPath = Paths.get("src/main/resources/connection-org1.yaml"); Gateway.Builder builder = Gateway.createBuilder() .identity(wallet, "admin") .networkConfig(networkConfigPath) .discovery(true); return builder.connect(); } @Bean public Network network(Gateway gateway) { return gateway.getNetwork("reliefchannel"); } @Bean public Contract contract(Network network) { return network.getContract("relief"); } }

这个配置类集中了两处容易错的地方。第一，Gateway bean 标注了 destroyMethod = close，否则 Spring 容器关闭时连接不会释放，开发环境热重启会积累一堆 gRPC 连接导致端口耗尽。第二，networkConfigPath 这里用的是相对路径，依赖你启动 Spring Boot 时的工作目录是项目根目录。更稳的写法是用 classpath: 前缀读 resources 下的文件，然后转成 Path。至于证书文件路径，在 yaml 里写的相对路径是相对于 yaml 文件所在目录，这个规则容易和 Java 的类路径概念混淆。

Service 层按读写分离封装：

@Service public class ReliefChaincodeService { private final Contract contract; public ReliefChaincodeService(Contract contract) { this.contract = contract; } public String submitApplication(String appId, String name, String idCard, String reliefType, BigDecimal amount) throws Exception { byte[] result = contract.submitTransaction( "SubmitApplication", appId, name, idCard, reliefType, amount.toPlainString() ); return new String(result, StandardCharsets.UTF_8); } public String queryApplication(String appId) throws Exception { byte[] result = contract.evaluateTransaction("QueryApplication", appId); return new String(result, StandardCharsets.UTF_8); } public String queryHistory(String appId) throws Exception { byte[] result = contract.evaluateTransaction("GetReliefHistory", appId); return new String(result, StandardCharsets.UTF_8); } }

两条方法路的底层动作不同。submitTransaction 会把交易提案发给所有需要背书的 peer，收集背书结果，再发给排序节点出块，等待区块提交确认后才返回。所以它在链码返回结果的同时，也保证世界状态已经写入。evaluateTransaction 只发到一个 peer 做本地查询，不会产生交易，响应速度更快但结果可能不是所有 peer 里最新的——在 Fabric 里同一通道的 peer 最终会一致，但查询瞬间可能有短暂滞后。做演示查询用 evaluate，写业务数据必须走 submit。

还有一步值得演示：事件监听。放款动作是资金流动的关键节点，可以在 Spring Boot 启动时注册一个监听器：

contract.addContractListener( "charity-listener", new ContractEventListener() { @Override public void received(ContractEvent event) { String eventName = event.getName(); byte[] payload = event.getPayload(); if ("DisburseEvent".equals(eventName)) { log.info("收到放款事件: {}", new String(payload, StandardCharsets.UTF_8)); } } } );

事件监听让 Java 后端不必频繁轮询链上状态，链码在状态变更时 emit 一个事件，后端收到后可以去更新自己的本地 MySQL 汇总表。这套机制在答辩时提出来，能让评委看到你理解了 Fabric 的异步模型，而不是只会同步调用。

5. 慈善救助信用系统的5个高频坑：证书路径、背书超时、幂等与索引

这一章是血泪经验。我在同一个课设框架下帮人排查过的坑，集中在连接、超时、重启、编码、索引五个点上。每一条都是先给现象，再讲原因，最后说解决。

5.1 连不上peer：报错说MSP not found，其实证书路径错了

现象：启动 Spring Boot 后调用链码，控制台抛出类似 “failed to load MSP: msp not found” 或者 “no valid peers at the requested channel” 的异常。新人第一反应是网络没起或者通道名写错，反复重启 Docker，问题依旧。

原因：Fabric 网关从 wallet 里加载身份时，要求目录结构严格匹配 MSP 标准。最常见的错误是把私钥和证书放反了，或者证书目录叫 cacerts 而不是 signcerts。另外 connection.yaml 里的 tlsCACerts.path 指向的文件必须是 peer 的 TLS CA 证书，如果你误指向了组织管理员自己的签名证书，gRPC 握手时 TLS 校验直接失败。

解决：回到钱包目录用 find 命令确认结构：

find wallet/adminOrg1 -type f

正常输出应该包含 keystore/xxx_sk 和 signcerts/cert.pem 两类文件。如果 multi 证书链很长，用 openssl x509 -in cert.pem -noout -text 查看签发者，确认是 CA 签发的身份证书而不是 tls 证书。顺便把 connection.yaml 的 tlsCACerts 路径改成 test-network 里 peer 节点自己的 ca.crt 绝对路径，一劳永逸。

5.2 提交交易超时：不是网络慢，是背书策略没凑够两个组织

现象：evaluateTransaction 秒回，改成都 submitTransaction 后经常等十几秒然后报 “Transaction timed out” 或者 “ENDORSEMENT_FAILURE”。

原因：Fabric 默认的背书策略是 AND(Org1MSP, Org2MSP)，也就是说一笔交易必须同时拿到两个组织的 peer 背书。如果你的 connection.yaml 里只配了 Org1 的节点，网关自动 discovery 也找不到 Org2 的 peer——因为 Org2 的连接信息不在这个 profile 里。

解决：最省事的做法是在网络层面把链码背书策略改成只需 Org1 一个组织：

./network.sh deployCC -ccn relief -ccp ./chaincode/relief-go -ccl go -ccp ../chaincode/relief-go -ccep "OR('Org1MSP.member')"

重新部署后，背书只需 Org1 的 peer。这个参数就是 chaincode endorsement policy 的简写形式，完整写法则是一串 JSON 策略。课设阶段为了演示顺畅，我会把链码策略改成 OR，并在报告里说明这是为了简化演示，生产环境应当是 AND。

另一个隐藏因素：排序节点出块超时。如果一个区块里交易太少，orderer 会等 BatchTimeout（默认 2 秒）后才出块，所以你会感觉提交后总有一两秒的停顿，这不是 Bug，是设计如此。

5.3 重启Fabric后Java端连不上：orderer地址变了

现象：第一次启动后一切正常，把网络 down 掉再 up，Java 端调用 submitTransaction 就报 “failed to connect to orderer” 或者连接被拒。

原因：test-network 每次 up 后用相同的容器名和映射端口，理论上不应该有问题。但如果之前手工改过 docker-compose 文件、或者旧容器没有完全清理，orderer 的 Raft 节点 ID 和端口映射会发生漂移。更常见的是你通道配置文件里记录的 orderer 端点地址，和当前容器实际监听的地址不一致。

解决：强制彻底清理，不要用 down 再用 up：

docker rm -f $(docker ps -aq) docker volume prune -f ./network.sh up createChannel -c reliefchannel -ca -s couchdb ./network.sh deployCC -ccn relief -ccp ../chaincode/relief-go -ccl go

如果这样还连不上，在容器里直接验证 orderer 端口：

docker exec orderer.example.com sh -c "nc -zv localhost 7050"

再确认 Java 端连接的 host 是不是 localhost:7050。新版 test-network 中 orderer 对外端口是 7050 没错，但如果你用自己的 compose 文件覆盖过，端口可能改成 8050 之类，这时候 connection.yaml 里的 orderer url 要同步改。

5.4 中文数据存进去显示乱码：全链路UTF-8

现象：用 Postman 往 Spring Boot 提交一条含中文姓名的救助申请，链码返回成功，但从 CouchDB 查出来显示 \u5f20\u4e09 或者直接乱码。

原因：Fabric 的 protobuf 序列化和 gRPC 传输都按字节流处理，本身不关心字符集。乱码几乎总是发生在 Java 应用层：要么是 new String(result) 用了平台默认字符集，要么是 Spring Boot 的 CharacterEncodingFilter 被改成了其他编码。

解决：所有链码返回值解码统一显式指定 UTF-8，我在第 4 章的 Service 代码里已经写成了 new String(result, StandardCharsets.UTF_8)，这是唯一正确写法。另外检查 Spring Boot 配置：

server: servlet: encoding: charset: UTF-8 enabled: true force: true

force: true 会将请求和响应都强制按 UTF-8 处理。链码侧 Go 语言默认就是 UTF-8 字符串处理，一般不用额外改。这个坑十次里有八次出在 Java 侧，别去折腾链码。

5.5 富查询报错no usable index：CouchDB设计文档没装进去

现象：链码里用 GetQueryResult 查询状态为 APPLIED 的救助单，返回错误 “no usable index exists for this query”。

原因：这条报错的直接原因是 CouchDB 没有匹配的索引。索引没装进去的原因通常是链码包里的 META-INF 目录结构不对。Fabric 部署链码时，只会把链码打包路径下固定位置的索引文件装入 CouchDB，位置错了它不报错，只是静默忽略。

解决：先检查目录结构，正确格式：

chaincode/relief-go/ ├── go.mod ├── go.sum ├── relief.go └── META-INF/ └── statedb/ └── couchdb/ └── indexes/ └── statusIndex.json

META-INF 必须放在链码源码目录的根下，不能放在子模块里。确认后重新打包部署：

./network.sh deployCC -ccn relief -ccp ./chaincode/relief-go -ccl go

部署成功后，进 CouchDB 容器手动验证：

curl -s http://admin:adminpw@localhost:5984/reliefchannel_relief/_index

返回结果里应该能看到 statusIndexDoc。如果这条命令连不上，检查 CouchDB 的端口映射和用户名密码，test-network 默认是 admin/adminpw。索引生效后再跑富查询就不会报错了。

6. 答辩验收怎么演示：种子数据、区块高度与信用闭环话术

课设做到最后，演示顺序比功能代码更重要。我的建议是一条黄金路线：先证明链在动，再证明数据改不了，最后把”信用“两个字讲成闭环。

6.1 演示顺序：从区块高度到单笔追溯的黄金路线

第一步，控制台执行 peer channel getinfo -c reliefchannel，展示区块链高度。第二步，调用 Spring Boot 提交一笔救助申请，再重复第一步，高度递增。这一步同时证明链和业务系统是真实打通的。第三步，调用历史溯源接口，展示同一笔救助单从 APPLIED 到 DISBURSED 的每一次变更，每一条记录都带 txId 和 timestamp。第四步，用富查询按状态筛选 VERIFIED 的申请，证明跨机构的数据检索能力。第五步，如果时间充裕，展示事件监听日志，后端自动捕获了链码发出的 DisburseEvent。

6.2 把“信用”讲成闭环：评委追问时你递出去的证据链

评委大概率会追问三个方向。第一，“怎么证明数据没被改”——回答是哈希链和背书签名，每个 peer 都存着一份完整账本，改一个区块会导致后续所有区块哈希失配。第二，“信用表现在哪里”——回答是救助记录形成信用档案，同一申请人再次申请时，历史状态里的逾期记录会被自动提取，审批机构据此决策。第三，“为什么不用 MySQL”——回答是 MySQL 的修改不留痕，跨机构数据不互信，Fabric 的多组织背书模型就是为此设计的。演示时提前准备一份带有两三条历史记录的受助人数据，配合查询接口现场展示，比背概念有力得多。

提示：课设源码包里的报告如果写了性能测试数据，答辩时不要主动报 TPS 数字。Fabric 的定位是可信任协作，不是高并发记账，把重点放在一致性、审计和权限模型上。

我自己的习惯是：每次演示前先在空白环境走一遍第 2 章的启动命令，确认容器清单完整、链码部署成功后才开始演示。不然现场虚拟机关机后再开机，经常因为端口占用或容器没正常启动而翻车。这一段流程熟练到闭眼能敲，答辩的底气就有一半了。另外一个建议是把链码里的关键校验逻辑打印到日志里，启动 Spring Boot 时开启 DEBUG 级别的 fabric 日志，出问题直接搜 gRPC 调用栈，比猜快很多。

Fabric 这套东西真正难的不是写代码，是把“多方不信任但需要协作”的业务模型讲清楚。希望这篇文章能让你少走我踩过的那些弯路，把精力留在业务逻辑和演示效果上，希望帮到你。

本文还有配套的精品资源，点击获取