基于Hyperledger Fabric的医疗记录存储：链上存证、链下存取

简介：基于区块链的医疗记录存储系统毕业设计项目包，主要面向计算机相关专业正在准备毕设的学生，以及需要项目实战练习的学习者，同样适用于课程设计、期末大作业等场景。包内共包含207个文件，压缩包大小约11.3MB，涵盖Java与Go后端源码、YAML与Properties配置文件、SQL数据库脚本，以及PEM、CRT、KEY等区块链证书与密钥文件，帮助搭建完整的联盟链/节点通信环境。目前已有275人学习下载，可作为区块链方向毕设的完整参考。项目附有答辩PPT、论文报告、中期报告和任务书，覆盖从选题开题、中期检查到最终答辩的全部环节，文档规范程度高；源码经严格调试确保可运行，目录层次清晰，配合大量PNG、JPG架构与界面示意图，可快速理解医疗记录上链存储、患者授权、数据校验等核心模块，同时提供Shell启动脚本和测试数据，便于本地快速验证与二次开发。

1. 基于区块链的医疗记录存储系统：别把病历原文塞进交易，才算真正开始

“基于区块链的医疗记录存储系统”这个毕设标题，几乎每年都能在各种毕业设计源码包里看到。能跑通的很多，但答辩扛问的很少。差别往往不在区块链本身，而在一个容易被忽略的分层：原始病历是敏感明文，体量大，不能直接塞进链上交易；链上放的是元数据、哈希和授权关系，链下放的是加密原文。顺着这个思路，我以 Hyperledger Fabric 为例，把选型、链码字段、最小网络、SDK 联调和五个高频故障完整拆一遍。如果你正在做医疗记录存储相关的毕设，想从“能演示”走到“能解释”，这篇可以作为你对照落地的主线。

2. 从架构选型起步：医疗数据的链上链下怎么分，Fabric 与 Ethereum 该怎么选

2.1 医疗记录“读多写少、写要授权、读要留痕”，和普通日志型数据完全不同

医疗记录和一般业务日志有三个直观差异。第一，一条记录一经产生几乎不可删除和覆盖，写错了只能新增一条纠正记录，原记录仍要保留，这是医疗事故追溯的底线。第二，读流量远大于写流量，同一份病历会被转诊医院、医保核算、临床研究、监管审计反复读取，而写入者只有签发的医生或科室。第三，体量差距极大，结构化检验报告只有几 KB，但 CT、MR 影像一个序列就是几十 MB，全量复制进区块让每个背书节点都背一份，既不现实，也把患者隐私暴露给了本不该接触原始数据的节点。

这个特征决定了正确的落地模型不是“把数据上链”，而是“链上存证、链下存取”。链上世界状态里只放：记录 ID、患者标识、记录类型、原始文件的哈希、版本号、状态、授权关系和关键时间戳。链下文件库存放加密后的原始病历。区块链承担三件事：证明某份记录在特定时间存在、约束谁能读取、为每一次授权与访问留痕。论文里能把“为什么只把哈希和元数据上链”讲清楚，已经甩开大多数只会演示增删改查的同类项目。

2.2 链下用 IPFS 还是 MinIO：不是哪个更链上，而是谁能配合权限审计

链下存储的选型经常被做成“IPFS 看起来更去中心化，所以选了 IPFS”，但这低估了落地成本。IPFS 自带内容寻址，文件哈希天然与链上摘要联动，听起来很美；可公共 IPFS 网关一旦暴露，原始文件等于发到公网。正确做法是搭私有 IPFS 节点，自己控制网关访问，这要求你额外处理节点维护和 ACL。MinIO 或普通对象存储反而在权限模型上更省心，桶策略、预签名 URL、对象版本都可以直接挂到组织角色上，业务侧很快能闭环。

不管选哪个，落地红线只有一条：入库前绝不落明文。我一般会在服务端用 AES-256-GCM 加密原始文件，密钥单独放一个存储区，不和文件放同一台机器。这样即使链下数据库被拖走，攻击者拿到的也是密文，结合链上哈希也无法还原出可读的病历内容。

2.3 选 Hyperledger Fabric 还是 Ethereum：节点准入、隐私与开发量对照

公链方向开发量小、工具链熟，但医疗数据上公链后，账本默认全网公开。想隐藏只能做密文上链、链下分发密钥，绕一圈还是回到访问控制，授权体系一点没省。联盟链方向以 Hyperledger Fabric 为代表，网络只承认被 MSP 注册的组织和节点，多个组织各管各的信任锚点，还能用通道和私有数据集合控制可见性。医院 A 和医院 B 之间可以只共享报告摘要，影像明细留在私有数据集合里。代价也明显：证书、排序服务、链码生命周期、组织策略，第一次把 test-network 跑通往往要折腾大半个晚上。

我的建议很直接：如果导师没有指定 Ethereum，医疗记录方向优选 Fabric。答辩老师大概率会问“其他节点会不会看到患者隐私”，在联盟链上回答“通道隔离 + 私有数据集合”成本低得多。后续所有实现，我也以 Fabric 为准展开。

3. 写进链上状态的数据结构：智能合约字段、访问控制与最小链码实现

3.1 病历台账为什么用复合键：patientId 作前缀，才能按患者范围查询

Fabric 的世界状态是 KV 结构，链码把 JSON 字符串存到某个 key 下。如果只是随机 id，查找某位患者全部病历时就必须遍历所有数据。我习惯把 key 设计成复合键：record:{patientId}:{recordId}，用createCompositeKey生成，既能保证同一患者记录相邻存储，也方便用部分复合键做范围查询。

链上字段不要贪多，够用就好：

注意，version不是 Fabric 世界状态自动带的那个 version，而是业务自定义版本。世界状态自带版本号用于并发冲突检测，业务版本用于表达“这是一份纠正报告”。两者各管各的，论文里最好一句话讲清，避免答辩被混为一谈。

3.2 三种角色的访问控制：不能只在网页藏按钮，链码要亲自验身份

医疗系统的权限不能停留在“前端不显示”或“后端路由拦截”。Fabric 里任何持有合法证书的客户端都能直接构造交易、绕过网站调用链码，权限校验必须下沉到链码内部。链码收到请求后用ctx.clientIdentity能拿到调用方 MSP ID、证书属性和身份标识，读写操作之前先做角色判断。

我一般把角色做成 Fabric CA 注册时写入的属性（role）：

• patient：只能查自己的病历，只能授权医生查看自己的病历。
• doctor：可以创建病历；非本人签发的病历，必须有有效 grant 资产才能读。
• auditor：只能读元数据和操作痕迹，拿不到 recordHash。

毕设如果用 test-network 加 cryptogen 生成身份，角色字段要在 msp 目录或证书 CN 里体现；如果走 Fabric CA，register 时加role属性再签发。这个细节直接决定链码里的getAttributeValue('role')是否有返回值。

3.3 最小可运行的链码：创建记录、授权医生、查询记录

下面是一份简化但能落地的 Node 链码骨架，我在项目里通常从它扩展：

'use strict'; const { Contract } = require('fabric-contract-api'); class MedicalRecordContract extends Contract { // 创建一条病历存证，只有 doctor 角色可以调用 async createRecord(ctx, recordId, patientId, doctorId, recordHash, recordType, createdAt) { const callerRole = ctx.clientIdentity.getAttributeValue('role'); if (callerRole !== 'doctor') { throw new Error('只有 doctor 角色可以创建病历记录'); } const key = ctx.stub.createCompositeKey('record', [patientId, recordId]); const existing = await ctx.stub.getState(key); if (existing.length > 0) { throw new Error('record ' + recordId + ' 已存在'); } const record = { recordId, patientId, doctorId, recordHash, recordType, createdAt, status: 'ACTIVE', version: 1 }; await ctx.stub.putState(key, Buffer.from(JSON.stringify(record))); return JSON.stringify(record); } // 患者授权某个医生读取自己的病历，grant 是独立资产 async grantDoctor(ctx, recordId, patientId, doctorId, expireAt) { const callerRole = ctx.clientIdentity.getAttributeValue('role'); if (callerRole === 'auditor') { throw new Error('auditor 不参与授权'); } // 先确认病历存在，并属于这位患者 const key = ctx.stub.createCompositeKey('record', [patientId, recordId]); const recordBytes = await ctx.stub.getState(key); if (recordBytes.length === 0) { throw new Error('记录不存在'); } const record = JSON.parse(recordBytes.toString()); if (record.patientId !== patientId) { throw new Error('病历记录与患者不匹配'); } // 患者只能授权自己的病历，这里用证书标识包含关系做简化 if (callerRole === 'patient') { const callerId = ctx.clientIdentity.getID(); if (!callerId.includes(patientId)) { throw new Error('患者只能操作自己的病历'); } } // grant 作为独立 KV 保存，不塞进 record 数组 const grantKey = ctx.stub.createCompositeKey('grant', [patientId, recordId, doctorId]); const grant = { recordId, patientId, doctorId, expireAt, grantedAt: new Date().toISOString() }; await ctx.stub.putState(grantKey, Buffer.from(JSON.stringify(grant))); return JSON.stringify(grant); } // 查询单条病历，链码内完成角色与授权校验 async queryRecord(ctx, recordId, patientId) { const callerRole = ctx.clientIdentity.getAttributeValue('role'); const key = ctx.stub.createCompositeKey('record', [patientId, recordId]); const recordBytes = await ctx.stub.getState(key); if (recordBytes.length === 0) { throw new Error('记录不存在'); } const record = JSON.parse(recordBytes.toString()); if (callerRole === 'auditor') { delete record.recordHash; // 审计员不接触内容摘要 return JSON.stringify(record); } if (callerRole === 'patient') { const callerId = ctx.clientIdentity.getID(); if (!callerId.includes(patientId)) { throw new Error('患者只能查询自己的病历'); } return JSON.stringify(record); } if (callerRole === 'doctor') { // 从调用方证书取 doctorId，不能信任参数里的 doctorId const callerDoctorId = ctx.clientIdentity.getAttributeValue('doctorId'); const grantKey = ctx.stub.createCompositeKey('grant', [patientId, recordId, callerDoctorId]); const grantBytes = await ctx.stub.getState(grantKey); if (grantBytes.length === 0) { throw new Error('该医生未获得此病历的授权'); } return JSON.stringify(record); } throw new Error('未知角色无权查询'); } } module.exports.contracts = [MedicalRecordContract];

逻辑要点有三个。第一，grant 是独立资产而不是记录里的一个数组字段，撤销授权时只需要删掉 grant key，不用改动病历本身。第二，医生读取时的 doctorId 取自证书属性，而不是前端传参，否则任何人都能冒充某个医生去查。第三，患者身份判断里的includes是简化写法，适合毕设单向映射；真实项目要解析 X.509 证书的 CN 或属性做精确匹配，不能靠字符串包含。

这段代码还有一个故意留的缺口：queryRecord 没有校验授权过期时间。你可以在链码里读 grant 的 expireAt 再比较，下面第 5.4 节会专门讲这个坑。

3.4 为什么不能把原始病历或明文参数上链：隐私与共识代价

一笔 Fabric 交易经过客户端签名、背书、排序、提交区块，通道内所有 peer 的账本都会保留完整的提案内容。如果调用 createRecord 时把诊断结论作为字符串参数传进去，这段明文就会永久写进区块，所有同步账本的协作者节点都能读到。所谓“不上链”不是只在界面层不显示，而是从参数层就隔离。

敏感字段真正安全的传入方式是 Fabric 的 transient data。它只参与背书执行，不进入排序和区块，适合传加密密钥、临时明文等。毕设里不一定非要实现 transient，但如果论文提了“隐私保护”，最好把这一段补上。链码收到的参数集合与区块里持久化的参数集合不同，这个机制解释清楚，答辩分量会明显不一样。

4. 在本地跑通最小可复现系统：容器编排、链码部署与 SDK 联调

4.1 准备环境与启动 Fabric 测试网：down 干净比 up 更重要

拿到一份能跑的源码包，第一件事不是看前端页面，而是确认它有没有把病历原文写进链码调用参数；第二件事就是把网络拉起来。以 fabric-samples 的 test-network 为底座，先清理环境，再启动：

# 每次实验前先把残留容器、卷和证书清掉 ./network.sh down # 启动网络并创建 mychannel，-ca 表示启用 Fabric CA ./network.sh up createChannel -c mychannel -ca # 确认关键容器都处于 Up 状态 docker ps --format "table {{.Names}}\t{{.Status}}"

-ca参数值得多说一句。默认测试网用 cryptogen 一次性生成证书，不涉及证书颁发过程，演示可以，但论文里很难展开“动态身份管理”。启用 Fabric CA 之后，组织和用户的证书由 CA 签发，你可以在答辩时多讲一条 CA 吊销、证书轮换的链路。代价是踩坑概率略高，常见的就是第 5.1 节里 peer 容器不停重启的问题。

4.2 部署链码时把 pack、approve、commit 三段分开理解

deployCC是 test-network 提供的快捷脚本，内部帮你完成了打包、安装、批准、提交四步。理解了内部流程，才能处理自定义场景：

# 快捷部署，链码语言是 javascript ./network.sh deployCC -ccn medrecord -ccp ../chaincode/medrecord -ccl javascript -c mychannel # 指定背书策略：Org1 或 Org2 任一组织背书即通过 ./network.sh deployCC -ccn medrecord -ccp ../chaincode/medrecord -ccl javascript \ -c mychannel -ccep "OR('Org1MSP.member','Org2MSP.member')"

只跑deployCC的缺点是黑盒，答辩若被问“链码生命周期”容易答空。我建议手动执行一次核心命令，理解 install 装在哪、approve 批准什么、commit 之后才真正生效：

# 1) 打包链码，--label 给一个本地版本标识 peer lifecycle chaincode package medrecord.tar.gz \ --path ../chaincode/medrecord --lang node --label medrecord_1 # 2) 安装到当前 peer peer lifecycle chaincode install medrecord.tar.gz # 3) 查看已安装的包 ID，后面 approve 要用 peer lifecycle chaincode queryinstalled

安装后链码还处于“本地存在但通道不认识”的状态。approveformyorg 是组织表态度，commit 是让通道正式启用这个版本。很多毕设翻车都发生在多组织场景：Org1 批准了，Org2 没批准或包 ID 不一致，commit 时始终报策略不满足。排错时先对比两个组织的queryinstalled输出，再检查 sequence，这个顺序最省时间。

4.3 用 fabric-gateway 完成“患者授权、医生读取”的接口级演示

后端接入不必直接用 gRPC，fabric-gateway 把连接、签名、提交封装得比较友好。下面是患者授权和医生查询两个核心动作：

const { connect } = require('@hyperledger/fabric-gateway'); const fs = require('fs/promises'); async function createGatewayFor(userOrg, userCertPath, userKeyPath) { // 读取该用户证书与私钥，建立一个 Fabric 身份连接 const identity = { mspId: userOrg, // 例如 'Org1MSP' credentials: { certificate: await fs.readFile(userCertPath, 'utf8'), privateKey: await fs.readFile(userKeyPath, 'utf8'), }, }; const client = await connect({ identity }); return client; } async function grantDoctor(patientUser, recordId, patientId, doctorId, expireAt) { // patientUser 是患者自己的 Fabric 身份，授权必须用患者证书签名 const client = await createGatewayFor(patientUser.org, patientUser.cert, patientUser.key); const network = await client.getNetwork('mychannel'); const contract = network.getContract('medrecord'); // submit 会走完背书、排序、提交全流程 const tx = await contract.submit('grantDoctor', { arguments: [recordId, patientId, doctorId, expireAt], }); return tx.getTransactionId(); } async function queryByDoctor(doctorUser, recordId, patientId) { const client = await createGatewayFor(doctorUser.org, doctorUser.cert, doctorUser.key); const network = await client.getNetwork('mychannel'); const contract = network.getContract('medrecord'); // evaluate 只做模拟执行，不产生新区块，适合查询 const buf = await contract.evaluate('queryRecord', { arguments: [recordId, patientId], }); return JSON.parse(buf.toString()); }

关键区别在submit和evaluate。submit发起完整共识流程，授权、创建记录这类状态变更必须用它；evaluate由 peer 模拟执行并直接返回结果，服务器本机的查询走它就够了。把grantDoctor用evaluate调，你会看到返回成功但状态没变，这正是很多“明明调用了却不生效”的来源。

4.4 前端、后端、链上三层对不齐，根因常在后端私钥管理

完整链路从前端看一般是三个接口：

POST /api/records # 上传原始病历，写加密库并上链 POST /api/records/grant # 患者授权医生 GET /api/records/:id # 读取病历明文

后端收到文件后的顺序必须是：序列化为标准结构、计算 SHA-256、加密入库、再提交链码。如果先入库再算哈希，已经被数据库变更过的字段会影响结果。另一个常见病是把 Org1 管理员的 msp 私钥直接塞进前端，浏览器里做 Fabric 签名，结果每个登录用户都相当于拿到了管理员的链上身份。所有与 Fabric 交互的签名私钥必须留在后端或独立签名服务，前端只保持普通登录态。这条也是论文安全章节里最容易自洽的观点。

5. 毕设踩坑记录：节点重启、链码超时、哈希对不上、撤销失效的五个现场

5.1 现象：peer 容器一直重启，日志反复出现 implicit policy evaluation failed

原因：在-ca模式下，网络每次 down 后重新生成 Fabric CA，组织 MSP 的 admincerts 目录里可能还残留上一轮的管理员证书。peer 启动后加载的本地管理员身份不被当前组织 MSP 信任，任何管理操作和背书请求都被策略拒绝。常见于反复up和down之后没有清理干净。

解决：先把./network.sh down执行干净，必要时手动删除 containers 和 volume，再重新up。如果只改了自己写的 docker-compose，重点检查 peer 容器里CORE_PEER_MSPCONFIGPATH指向的管理员 MSP 目录和当前组织 MSP 的 admincerts 是否匹配。用docker logs peer0.org1.example.com看第一条报错比看最后一条有用。

5.2 现象：链码安装成功，approveformyorg 之后 commit 一直超时

原因：同一个链码包在两台 peer 上安装后得到的 package ID 不一致，或者 Node 链码目录缺少依赖、打包时没带 node_modules，容器启动失败。生命周期链码把 package ID 与背书策略绑定，一个节点装了 A 包，另一个节点装了 B 包，commit 策略就永远凑不齐。

解决：先在两台 peer 上分别执行peer lifecycle chaincode queryinstalled，对比 package ID。不一致就重新打同一个 tar 包，确认npm install已经在链码目录执行过。然后看链码容器日志，名字一般是dev-peer0.org1.example.com-medrecord-<packageid>，启动栈里会直接暴露缺哪个模块。

5.3 现象：链下数据库里的原文和链上哈希怎么算都对不上

原因：哈希计算时使用的内容不规范。前端传来的 JSON 字段顺序在传输中被改写，后端重新序列化时缩进不一致，或者文件流读入后末尾多了换行符，都会得到完全不同的哈希结果。哈希对不上的本质不是“区块链坏了”，而是“被哈希的对象变了”。

解决：在服务端定义一个序列化函数，先对 key 排序再生成字符串，写库和上链都用同一个函数：

function canonicalRecord(payload) { const sorted = Object.keys(payload).sort().reduce((acc, k) => { acc[k] = payload[k]; return acc; }, {}); return JSON.stringify(sorted); }

只要能保证“入库前算的哈希”和“上链时用的哈希”来自同一个字符串，两边就不会漂移。更稳的做法是文件入库后，用 MinIO 返回的对象 ETag 作为哈希来源，避免业务序列化层二次引入偏差。

5.4 现象：患者撤销授权后，医生通过历史查询接口仍能读到旧授权

原因：授权关系如果只是被简单地写进记录的历史版本，前端已经点了“撤销”，但链码的查询逻辑读的是旧版本字段，或者后端把授权状态放在本地缓存里，链上撤销没有同步失效。业务侧的授权失效判断做得再漂亮，都挡不住绕过你的 API 直接调链码的客户端，所以授权判断必须以链上当前状态为准。

解决：把 grant 做成独立资产，撤销时删除或置为 REVOKED；查询链码里读 grant 时必须同时检查状态与过期时间：

const grantBytes = await ctx.stub.getState(grantKey); if (grantBytes.length === 0) { throw new Error('该医生未获得此病历的授权'); } const grant = JSON.parse(grantBytes.toString()); if (grant.status !== 'ACTIVE') { throw new Error('授权已被撤销'); } if (new Date(grant.expireAt).getTime() < Date.now()) { throw new Error('授权已过期'); }

另外，不要用getHistoryForKey的结果直接做对外查询接口。历史查询是审计功能，展示的是所有历史版本；读取功能必须只返回最新有效状态，否则撤销授权这种事就成了摆设。

5.5 现象：演示前夜一切正常，早上开虚拟机后网络起不来，链码容器消失

原因：虚拟机休眠恢复后，Docker 守护进程把未标记 restart 策略的容器直接清掉了，链码镜像对应容器不复存在；orderer、peer 都在但链码容器不在时，invoke 会一直报“链码未就绪”。再叠加本地时间跳变，排序服务容易丢连接。

解决：给演示准备一条可重复的初始化脚本，把环境彻底重置并重建数据，而不是靠“上次开机的状态”：

#!/bin/bash set -e ./network.sh down ./network.sh up createChannel -c mychannel -ca ./network.sh deployCC -ccn medrecord -ccp ../chaincode/medrecord -ccl javascript -c mychannel node scripts/init_demo_data.js # 预置患者、病历和授权数据

这套脚本跑通后，答辩现场出任何问题都可以说“重新初始化一遍”，比现场修容器快得多。链码目录的 node_modules 也提前打进去，避免现场npm install拉空。

6. 验收与进阶：让毕设经得起“你能证明数据没被改过吗”

6.1 用世界状态版本号做篡改自检

完成一个系统后，先做一个最直接的完整性验证：查询链上记录，得到 recordHash，再去比对链下原始文件的 SHA-256。然后把世界状态的 version 字段也打出来，记录第一次查询的版本号；提交一次更新后再查，版本号必须递增。版本号不变而内容变了，说明客户端读的是缓存或别的数据源；版本号变了但你没主动改过，说明有第三方用合法身份写了通道。把这两组对照截图，答辩时比任何架构图都有说服力。

6.2 给论文留一张性能观察表

医疗场景更看重访问控制和审计，但论文里通常要有一组基本性能数据。我自己会用一个几百次的并发脚本跑 createRecord：

const txs = []; for (let i = 0; i < 300; i++) { txs.push(contract.submit('createRecord', { arguments: ['R' + i, 'P001', 'D001', 'hash' + i, 'lab', new Date().toISOString()], })); } const results = await Promise.allSettled(txs); console.log('ok:', results.filter(r => r.status === 'fulfilled').length);

结果里除了写 TPS，必须同时记录几个参数：背书节点数、orderer 数量、状态数据库用的是 CouchDB 还是 LevelDB、机器核数与内存。没有这些条件谈 TPS 没有意义。测试网单 orderer 单通道的吞吐上限通常不出在链码，而出在共识和容器资源，论文里这样写反而能显出你真跑过。

6.3 进阶方向：把密钥封装与影像流放进系统，作为加分亮点

如果时间允许，我会加一层对称密钥封装：病历文件用 AES 随机密钥加密，再用接收方公钥封装这个 AES 密钥，链上只记录封装后的指纹。医生被授权时，在密钥服务里解开封装并临时获得解密密钥；撤销授权时密钥服务把对应临时密钥销毁，链上 grant 同时失效。这个模型兼容真实的医疗转诊协作，论文里可以单独开一节“跨机构安全共享”。

最后说一个我保持了很久的检查习惯：每次动手改链码或权限模型之前，先把 down 脚本跑一遍，确认从零能复现，再去做新功能。这能让“刚才还能跑”变成“随时都能跑”。希望这篇笔记能帮你在毕设路上少走几个我已经替你走过的弯路。

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