简介：本资源是一套面向本科毕业设计的分布式身份认证系统用户端实现，基于Hyperledger Fabric区块链平台与SpringBoot框架构建，聚焦可信身份注册、DID文档管理、凭证申领与验证等核心交互流程，适用于区块链安全、数字身份方向的课程设计与毕设开发。压缩包共119个文件，含39个Java源码文件（如DidDoc、Issuer、AppServiceImpl等业务类）、39个编译后class文件、26个运行日志用于调试分析、9个XML配置文件支撑Spring生态集成，以及yaml、properties等基础配置文件，整体仅183KB，轻量易部署。已有83人学习下载，资源结构清晰，模块职责分明——涵盖控制器层、服务实现、异常统一处理、AOP切面及预置材料管理，附带README说明与Git规范，可直接作为毕设原型参考或二次开发基础。
1. 这不是又一个 SpringBoot 登录页：它用 Hyperledger Fabric 把「我是我」这件事，真正在链上跑通了
你写过多少个用户注册登录模块？邮箱验证、短信验证码、密码加密、JWT Token、OAuth2 接入……但有没有哪一次，你提交完「张三，身份证号 110…，手机号 138…」之后，心里没点嘀咕：这堆信息真能证明「张三」就是链上那个「张三」？本科毕设里常见的「模拟区块链」往往只在数据库加个block_hash字段，而这个项目——它把 DID（去中心化标识符）生成、DID Document 签署、凭证签发与验证、链上身份状态查询，全跑在真实的 Hyperledger Fabric v2.5 测试网络上。SpringBoot 不是摆设，而是作为用户端网关，把 Web 表单操作翻译成 Fabric SDK 调用，再把链上返回的 JSON-LD 格式 DidDoc 解析成前端可渲染的可信凭证卡片。它不解决「高并发秒杀」，但直击数字身份最硬的核：谁签发、谁持有、谁验证、链上可审计。适合想把毕业设计从「CRUD 上链」升级到「身份主权落地」的后端同学，也适合想摸清 Fabric 用户侧集成逻辑的初级区块链工程师——别被DidDocServiceImpl.class这种名字吓住，它背后是完整的 DID Lifecycle 实现。
2. 从 SpringBoot 启动到 Fabric 链码调用：四层穿透式拆解
2.1 为什么选 Fabric 而不是 Ethereum 或 Solana 做 DID？——毕业设计里的务实选型逻辑
很多同学一提「区块链毕业设计」就默认选以太坊，但 DID 场景下 Fabric 的优势是刚性的：第一，隐私保护粒度可控。Ethereum 上所有交易公开，而 Fabric 的 Channel + Private Data Collection 允许「仅 Issuer 和 Holder 可见凭证内容」，比如学历证书的 GPA 分数只对学校和学生可见，HR 只能看到「已通过认证」状态；第二，性能与成本真实可用。Fabric 单通道 TPS 稳定在 1000+，远超本科毕设部署的云服务器承载力，且无需 Gas 费——你不用教导师怎么充 ETH；第三，身份模型原生契合。Fabric 的 MSP（Membership Service Provider）本身就是一套 PKI 体系，天然支持 X.509 证书签发，而 DID 的核心正是「密钥对即身份」，Issuer.class里generateKeyPair()调用的就是 Fabric CA SDK，不是自己手撸 ECDSA。所以这个项目没用任何魔改链，而是直接复用 Fabric 官方 test-network，省掉 70% 的环境踩坑时间——这也是它能成为优质毕设的关键：技术栈真实、部署路径清晰、答辩时能现场peer chaincode invoke。
2.2 用户端 SpringBoot 的三层架构：Controller → Service → Fabric SDK 封装
整个用户端代码结构非常干净，没有过度设计：
- Controller 层：
ControllerAop.class是关键，它用@Around拦截所有/api/did/**请求，统一做 DID 绑定校验（检查请求头是否带did:web:xxx），失败直接抛GlobalExceptionHandler.class返回BaseResponse.error("DID not bound")； - Service 层：
DidDocServiceImpl.class是核心，它不直接调 Fabric SDK，而是依赖RegisterCenterServiceImpl.class——后者才是真正封装HFCSDK的类，负责连接 peer、背书、提交交易； - Fabric SDK 封装层：
PredefinedMaterials.class存放预置材料，比如测试用的 CA 证书路径、连接配置文件connection-org1.yaml、以及最关键的issuerMSPID（"Org1MSP"）。这里有个血泪经验：connection-org1.yaml里的peer0.org1.example.com地址必须和你docker-compose.yaml中容器名完全一致，少个0或多空格都会报Connection refused。
# connection-org1.yaml 片段（注意缩进与冒号空格！） peers: peer0.org1.example.com: url: grpcs://localhost:7051 tlsCACerts: pem: |- -----BEGIN CERTIFICATE----- MIICvzCCAaigAwIBAgIUQZ... -----END CERTIFICATE-----提示：
pem值必须顶格写，前面不能有空格，否则 HFCSDK 解析失败，报错java.lang.NullPointerException在CryptoSuiteFactory初始化阶段——这是毕设调试中最隐蔽的坑之一。
2.3 用户交互流程的四个原子动作：注册、绑定、申领、验证
整个用户端流程不是线性瀑布，而是围绕 DID 生命周期展开：
| 动作 | 触发端 | Fabric 链码调用 | 链上写入内容 | 前端反馈 |
|---|---|---|---|---|
| 注册 | Web 表单提交邮箱/手机号 | registerUser(string did, string publicKey) | 创建did:web:xxx索引，存公钥哈希 | 返回did:web:student-2023-001 |
| 绑定 | 扫描 Issuer 二维码 | bindIssuer(string did, string issuerDid) | 写入双向信任关系（Holder→Issuer） | 弹窗「已绑定教务处签发机构」 |
| 申领 | 点击「申请学历凭证」 | issueCredential(string holderDid, string credentialType) | 生成 VC（Verifiable Credential）JSON-LD，存 CID 到链上 | 下载.vc.json文件 |
| 验证 | HR 输入 DID 查询 | verifyCredential(string holderDid, string vcCid) | 读取 VC 并调用IssuerServiceImpl.class的verifySignature() | 返回绿色「✅ 已验证｜签发时间：2024-03-15」 |
注意：AppServiceImpl.class是流程协调者，它把上述四步串成状态机，比如「申领」前强制校验bindIssuer是否成功，失败则跳转绑定页——这比单纯写四个 API 更贴近真实业务。
3. DidDoc 与 DID Document：为什么你的 DID 在链上「活」不起来？
3.1 DidDoc 不是字符串，而是一份可验证的 JSON-LD 文档
很多同学以为did:web:xxx就是身份，其实这只是标识符（Identifier），真正的身份凭证是DidDoc（DID Document）。这个项目里DidDoc.class是 POJO，但它映射的是 W3C DID Core 规范定义的完整结构：
public class DidDoc { private String id; // did:web:xxx private List<VerificationMethod> verificationMethod; // 公钥、签名算法、用途 private List<Authentication> authentication; // 认证方式列表 private List<Service> service; // 服务端点，如 credential endpoint private List<AssertionMethod> assertionMethod; // 断言方法，用于 VC 签名 }关键点在于verificationMethod：它不是简单存一个公钥字符串，而是包含id（#key-1）、type（Ed25519VerificationKey2018）、controller（did:web:xxx）、publicKeyJwk（标准 JWK 格式）。DidDocServiceImpl.class的generateDidDoc()方法会调用io.jsonwebtoken:jjwt-api生成符合规范的 JWK，而不是用BigInteger.toString(16)拼接——后者会导致 VC 验证失败，因为验证方（如IssuerServiceImpl.class）用的是jose4j库解析 JWK。
3.2 Fabric 链码如何存储 DidDoc？——用 StateDB 而非私有数据集合
DidDoc存储在 Fabric 的 world state（LevelDB）中，键为DID_DOC_${did}，值为序列化后的 JSON 字符串。为什么不用 Private Data Collection？因为 DidDoc 本身是公开的（就像你的 GitHub 主页），只有 VC 内容才需隐私保护。链码did-contract.go的PutDidDoc函数如下：
func (s *SmartContract) PutDidDoc(ctx contractapi.TransactionContextInterface, did string, docJSON string) error { // 验证 JSON-LD 结构合法性（调用 external validator） if !isValidDidDoc(docJSON) { return fmt.Errorf("invalid did document format") } return ctx.GetStub().PutState("DID_DOC_"+did, []byte(docJSON)) }注意：
isValidDidDoc()是调用外部github.com/creachadair/jjsonld库做的 schema 校验，不是正则匹配。如果传入{ "id": "did:web:x" }这种残缺结构，链码会直接return error，SpringBoot 层捕获后返回BaseResponse.error("DID doc validation failed")。
3.3 用户端如何解析链上 DidDoc？——DidDocServiceImpl.class的三步解析法
当用户点击「查看我的 DID」时，DidDocServiceImpl.class执行：
- 查链：调用
RegisterCenterServiceImpl.queryState("DID_DOC_did:web:student-2023-001")获取原始 JSON 字符串； - 转 POJO：用
com.fasterxml.jackson.databind.ObjectMapper反序列化为DidDoc对象； - 验签名：提取
verificationMethod[0].publicKeyJwk，用io.jsonwebtoken.security.Keys.hmacShaKeyFor()生成验证密钥，调用JwtParserBuilder.parseClaimsJws()验证 DidDoc 自身签名（DID 文档需自签名以防止篡改）。
这三步缺一不可。曾有同学跳过第 3 步，导致前端显示「公钥：xxx」却无法用于后续 VC 签名——因为链上存的可能是被中间人篡改过的 DidDoc。
4. 避坑指南：Fabric 用户端集成的五个致命错误
4.1 现象：java.lang.NoClassDefFoundError: org/hyperledger/fabric/sdk/BlockchainInfo
原因：fabric-sdk-java版本与 Fabric 网络版本不匹配。项目用 Fabric v2.5，但pom.xml里写的是<version>2.2.12</version>。2.2.x SDK 无法解析 v2.5 新增的ChaincodeEvent结构。
解决：将fabric-sdk-java升级至2.5.3，同时确认fabric-ca-client版本也为2.5.3，二者必须严格一致。
4.2 现象：org.hyperledger.fabric.sdk.exception.InvalidArgumentException: Invalid channel name: mychannel
原因：connection-org1.yaml中channels.mychannel.peers.peer0.org1.example.com的mychannel名称，与test-network启动时创建的通道名不一致。默认通道名是mychannel，但若你执行过./network.sh createChannel -c yourchannel，则此处必须同步修改。
解决：运行peer channel list -C mychannel查看实际通道名，再更新 YAML 文件，重启 SpringBoot。
4.3 现象：io.grpc.StatusRuntimeException: UNAVAILABLE: io exception
原因：SpringBoot 容器与 Fabric 容器不在同一 Docker network。常见于用java -jar直接运行 jar 包，而非docker-compose up整体启动。此时localhost:7051指向宿主机，但 Fabric peer 运行在test-network网络内，IP 不可达。
解决：将 SpringBoot 打包为 Docker 镜像，并在docker-compose.yaml中加入networks: [test]，用peer0.org1.example.com:7051替代localhost:7051。
4.4 现象：BaseResponse.error("VC signature verification failed")
原因：IssuerServiceImpl.class验证 VC 时，用的是Issuer的私钥签名，但AppServiceImpl.class调用issueCredential()时传入的issuerDid是did:web:issuer.edu.cn，而链码中GetState("DID_DOC_did:web:issuer.edu.cn")返回的 DidDoc 里verificationMethod[0].publicKeyJwk为空（因 Issuer 注册时未正确生成 JWK）。
解决：检查IssuerServiceImpl.registerIssuer()方法，确保调用KeyPairGenerator.getInstance("Ed25519")生成密钥对，并用JWKSGenerator.generateJWK()输出标准 JWK，而非keyPair.getPublic().getEncoded()。
4.5 现象：前端显示「DID 已存在」但链上查不到DID_DOC_键
原因：RegisterCenterServiceImpl.class的registerUser()方法中，ctx.GetStub().GetState("DID_DOC_"+did)返回nil，但代码误判为!= null，导致重复注册逻辑未触发。Go 链码中GetState()返回nil表示键不存在，Java SDK 接收后为null byte[]，需用Objects.isNull(result)判断，而非result.length > 0。
解决：在RegisterCenterServiceImpl.java的registerUser()中，将if (result != null && result.length > 0)改为if (!Objects.isNull(result))。
5. 验证链上身份的终极技巧：用 curl 模拟 HR 验证流程
5.1 构建最小可验证命令链：绕过前端，直击 Fabric 底层
毕业答辩时，导师常问：「你说链上可验证，那我现在用 Postman 能不能查？」——这时候千万别打开 Swagger UI，要直接甩出终端命令。以下四步，10 秒内完成一次完整验证：
# Step 1：获取用户 DID（假设为 did:web:student-2023-001） curl -X GET http://localhost:8080/api/did/get-did?email=zhangsan@univ.edu.cn # Step 2：查链上 DidDoc（需先进入 cli 容器） docker exec -it cli bash peer chaincode query -C mychannel -n did-contract -c '{"function":"GetDidDoc","Args":["did:web:student-2023-001"]}' # Step 3：查该用户最新 VC CID（链码中 GetLatestVcCid 函数） peer chaincode query -C mychannel -n did-contract -c '{"function":"GetLatestVcCid","Args":["did:web:student-2023-001"]}' # Step 4：验证 VC（调用 verifyCredential） peer chaincode query -C mychannel -n did-contract -c '{"function":"VerifyCredential","Args":["did:web:student-2023-001","Qmabc123..."]}'注意：Step 4 的
Qmabc123...是 CID，来自 Step 3 返回值。VerifyCredential链码函数会：① 用 CID 查 VC 内容；② 用DidDoc中assertionMethod指向的公钥验签；③ 检查expirationDate是否过期。返回{"valid":true,"issuer":"did:web:issuer.edu.cn","issuedAt":"2024-03-15"}即为成功。
5.2 用 Python 快速生成测试 VC：避免手动构造 JSON-LD 的玄学错误
手动写 VC JSON-LD 极易出错（比如@context顺序错、credentialSubject.id缺失）。我一般用pyld库生成：
from pyld import jsonld import json vc_template = { "@context": ["https://www.w3.org/2018/credentials/v1"], "type": ["VerifiableCredential", "UniversityDegreeCredential"], "issuer": "did:web:issuer.edu.cn", "issuanceDate": "2024-03-15T00:00:00Z", "credentialSubject": { "id": "did:web:student-2023-001", "degree": {"name": "Bachelor of Science"} } } # Compact 为标准格式 compacted = jsonld.compact(vc_template, "https://www.w3.org/2018/credentials/v1") print(json.dumps(compacted, indent=2))输出结果可直接粘贴到peer chaincode invoke的-c参数中，比手敲安全 10 倍。
5.3 毕设答辩必问三连击及应答脚本
| 导师问题 | 本质考察点 | 我的标准应答（30 秒内） |
|---|---|---|
| 「Fabric 和 Ethereum 做 DID 有什么区别？」 | 是否理解技术选型逻辑 | 「Ethereum 所有数据公开，不适合存 GPA；Fabric 的 Private Data Collection 可让学校、学生、HR 各看各的数据。我们用的是 Fabric 原生 MSP，不是自己造 PKI，更贴近企业级身份系统。」 |
| 「你们的 DID 怎么防女巫攻击？」 | 是否考虑安全边界 | 「每个 DID 绑定唯一邮箱+手机双重验证，且 Issuer 签发 VC 时强制校验credentialSubject.id与链上 DidDoc 的id一致。女巫攻击需要伪造 CA 证书，而 Fabric CA 的 root cert 由运维离线保管。」 |
| 「如果 Fabric 网络宕机，用户还能登录吗？」 | 是否理解系统分层 | 「用户端 SpringBoot 有本地缓存策略：DidDoc 和 VC 验证结果缓存 24 小时。网络恢复后自动同步状态。这不是单点故障，而是『链上存证+本地验证』的混合模式。」 |
从那以后我每次部署 Fabric 毕设，都强制走一遍docker-compose down && ./network.sh down && ./network.sh up -c mychannel -s ca清空环境，再重跑mvn clean package。因为 Fabric 的状态残留比想象中顽固——哪怕只是改了一行connection.yaml，旧 peer 的 TLS 证书也会拒绝新连接，浪费两小时查日志。希望帮到你。
本文还有配套的精品资源，点击获取
