简介提供一套面向计算机相关专业软件工程、区块链、物联网等毕业设计的基于区块链的文档交易系统完整源码包适合作为高分开题、毕设或课设的参考实现。压缩包共180个文件容量仅8.43MB核心代码以55个Java文件、18个Vue文件及23个JavaScript文件构成覆盖后端服务、前端交互与智能合约逻辑此外还包含21个Word文档项目报告、部署手册和若干PNG图片便于查阅设计思路与界面效果。目前已有79人学习浏览代码经过测试可运行并附带部署文档降低环境搭建门槛。项目不仅演示了区块链在文档版权交易中的落地流程还具备可修改和扩展的灵活性适合在校学生直接用于毕业设计演示或在此基础上深化区块链应用研究。1. 从一次文档纠纷说起交易系统里区块链到底在存什么二手文档交易最麻烦的不是定价而是你怎么证明这文档是你的。平台数据库被改一行记录卖家就说不清了。这套基于区块链的文档交易系统把文档注册、版权归属、售卖记录放进链上存证层——即使后面 MySQL 表被清空合约事件和交易记录还在。项目核心是 Spring Boot 业务端 Solidity 合约 Web3j 节点对接源码压缩包里附带完整部署文档和项目资料运行时由真实验证工程拆分清楚适合软件工程、区块链方向的毕业设计也适合想搞懂智能合约怎么跟业务系统配合的开发者。这条链路跑通后你会发现区块链在这里不是噱头而是卖家和买家都需要的证据链。2. 智能合约与文档交易系统的核心架构设计2.1 双层结构链上存证链下存文件文档正文直接上链是不现实的一篇几 MB 的 docx 转成 calldata 要把 gas 烧光而且文档本身要能修改、能被下载链上存它是反模式。这套系统的做法和大多数 DApp 一致——文件存本地资源目录或云存储链上只留文档的 SHA-256 哈希、标题、价格、归属地址和状态。业务上分成三层浏览器前端负责上传和购买操作Spring Boot 后端负责计算哈希、落盘文件、组装交易区块链节点层负责接收交易并产生最终不可篡改的记录。后端在落库 MySQL 的同时把关键字段同步提交到合约MySQL 是查询视图合约是真相来源。这里有个值得说透的选型为什么文档注册和交易要拆成两份逻辑而不是塞进一个合约里写完。常见做法是拆分——存证合约管登记、改状态、查归属交易侧持有存证合约地址购买时先查存证合约的 status 再做转账。拆开的好处是存证逻辑独立换交易撮合策略不动版权记录。合约语言选择 Solidity 而不是 Vyper 或 Rust是因为部署文档和 Truffle 脚手架在 EVM 兼容链上的资料最全换链成本也最低。2.2 合约的数据结构字段和存储先看核心数据结构。合约里文档信息用结构体组织字段含义如下表字段类型说明iduint256文档ID从1自增owneraddress上传者地址即版权人titlestring文档标题fileHashbytes32原文件SHA-256哈希防篡改priceuint256售价单位weifileUrlstring文件的链下访问路径statusuint80未上架 1在售 2已售 3下架createdAtuint256注册时的区块时间戳哈希用 bytes32 而不是 string是因为 SHA-256 输出正好 32 字节bytes32 占一个存储槽比 string 省大量 gas。这也是很多初写合约的人容易忽略的细节——毕业设计里如果每个字段都用 string 存部署和调用成本会明显偏高。2.3 核心合约代码注册、状态与购买// SPDX-License-Identifier: MIT pragma solidity ^0.8.0; contract DocStore { struct Doc { uint256 id; address owner; string title; bytes32 fileHash; uint256 price; // 单位wei string fileUrl; uint8 status; // 0未上架 1在售 2已售 3下架 uint256 createdAt; } mapping(uint256 Doc) public docs; uint256 public docCount; event DocRegistered(uint256 indexed id, address indexed owner, bytes32 fileHash); event DocSold(uint256 indexed id, address indexed buyer, uint256 amount); function register(string calldata title_, bytes32 fileHash_, uint256 price_, string calldata fileUrl_) external returns (uint256) { docCount 1; docs[docCount] Doc(docCount, msg.sender, title_, fileHash_, price_, fileUrl_, 1, block.timestamp); emit DocRegistered(docCount, msg.sender, fileHash_); return docCount; } function buy(uint256 docId_) external payable { Doc storage d docs[docId_]; require(d.status 1, not on sale); require(msg.value d.price, insufficient funds); d.status 2; emit DocSold(docId_, msg.sender, msg.value); } }register 里 msg.sender 就是调用地址后端用哪个私钥签名owner 就是哪个地址。fileHash_ 是后端传进来的 bytes32合约不做二次哈希只负责存证。buy 的前两行 require 分别拦住了买已下架文档和付款不足两种常见错误require 条件不满足时交易会整体回滚改不了半截状态。这里的精简版没有做资金分账和退款完整源码里还会有托管账户和一个 withdraw 方法逻辑上就是多一个 mapping 记录购买人seller 可以调用取走余额。你不需要在合约里写 if (msg.value d.price) 的找零逻辑链上交易天然支持差额返回多付的 wei 会留在合约里实际项目中通常由管理员统一结算。3. Spring Boot 集成 Web3j合约调用与文档上链实现3.1 Web3j 接入层的构建后端跟节点通信有三种常见方式直接用 HTTP JSON-RPC 拼请求、用 Web3j SDK、或者用 Spring Boot 的 web3j 场景包。这套项目用的是 Web3j理由很实际——合约用 Solidity 编译后生成的 Java 包装类可以直接 new 出合约对象调用 register、buy 就像调本地方法ABI 编解码、交易签名、nonce 管理都被封装掉了。直接拼 JSON-RPC 也不是不行但代码里到处是十六进制字符串调试成本翻倍。pom 里引核心包dependency groupIdorg.web3j/groupId artifactIdcore/artifactId /dependency版本号按项目源码里的 POM 锁定部署文档里写的是用 Spring Boot 2.x 配套的 Web3j 4.x 系。接入 Bean 配置如下Configuration public class Web3jConfig { Value(${blockchain.rpc-url}) private String rpcUrl; Value(${blockchain.owner-private-key}) private String privateKey; Value(${blockchain.contract-address}) private String contractAddress; Bean public Web3j web3j() { return Web3j.build(new HttpService(rpcUrl)); } Bean public DocStore docStore(Web3j web3j) { Credentials credentials Credentials.create(privateKey); return DocStore.load(contractAddress, web3j, credentials, new DefaultGasProvider()); } }这里三个配置项的分工要讲清楚。rpc-url 决定 Web3j 连哪个节点部署文档里默认是 http://127.0.0.1:8545也就是本机起的私有链或者 Ganache 开发链contract-address 是合约部署完回显的地址很多没跑通的案例都是因为合约重新部署后忘了同步这个配置owner-private-key 是签名凭据所有交易都由后端签名发出这属于后端钱包模式部署文档里强调私钥只放服务端环境变量不要写进前端。3.2 文档上链从文件到交易回执上链不是一个方法搞定的事它是一条完整链路文件落地 → 算哈希 → 调合约 → 等回执 → 解析日志。public DocumentVO publish(MultipartFile file, String title, BigDecimal price) throws IOException { // 1. 文件落盘返回可访问的相对路径 String fileUrl storageService.save(file); // 2. 计算SHA-256转成32字节哈希 String hashHex DigestUtils.sha256Hex(file.getInputStream()); byte[] hashBytes Numeric.hexStringToByteArray(hashHex); // 3. ETH转wei避免double精度问题 BigInteger priceWei price.multiply(BigDecimal.valueOf(1_000_000_000_000_000_000L)) .toBigIntegerExact(); // 4. 调用合约注册返回交易回执 TransactionReceipt receipt; try { receipt docStore.register(title, hashBytes, priceWei, fileUrl).send(); } catch (Exception e) { throw new BizException(上链失败请检查节点连接或Gas设置, e); } // 5. 从事件日志中取回docId ListDocRegisteredEventResponse events docStore.getDocRegisteredEvents(receipt); if (events.isEmpty()) { throw new BizException(注册回执中没有事件日志, null); } return DocumentVO.of(events.get(0).docId, hashHex, fileUrl); }第 2 步用 DigestUtils.sha256Hex 对文件流计算而不是对文件名计算——项目文档里也反复强调任何一个字节变化哈希都会变拿文件名做哈希等于没哈希。第 3 步的 price 用 BigDecimal 乘 10^18 再转 BigInteger是在避免数据库 decimal 或 JSON 数字转 double 带来的精度丢失链上金额一律用 wei 整数。第 5 步必须从回执日志里拿 docId不能自己再 count1链上并发交易时本地计数不一定和实际写进链的顺序一致。3.3 交易接口与授权下载的状态闭环后端接口和合约方法对应关系如下HTTP 接口合约动作业务含义POST /api/docsregister上传文档落盘并上链存证status置1GET /api/docs查 docs() / docCount()分页读MySQL再过滤链上状态POST /api/docs/{id}/buybuy()买家发起购买后端签名代付GET /api/docs/{id}/download查 status 与授权校验链上已售且为当前买家购买和下载之间有一个容易踩的坑buy 里把 status 置为 2 后后端如果还允许卖家自己下载就失去了交易的意义。部署文档里的处理方式是下载接口先查 MySQL 订单表再调链上 docs() 确认 status 和 buyer两层校验都过才签发一次性下载 token。TOKEN 有效期设为 5 分钟放在 Redis 里做防重放。接口层要做幂等同一个订单重复点击购买时后端应先查链上 statusstatus 已经是 2 就直接返回已售而不是再发一笔转账交易否则会多扣一次钱。状态流转在链上只有 1→2 一步下架和退款属于后台管理操作由管理员私钥调单独的方法。这样设计的好处是交易主流程被压到最短出问题的可能性最小。4. 部署文档里的关键配置与节点联调排错4.1 开发链与合约部署这套项目的部署文档我按先链后业务的顺序看。先启动开发链再编译部署合约最后才启动 Spring Boot顺序反了会出现合约地址还没写入配置后端起来却连接空地址的尴尬。# 安装依赖并启动Ganache开发链 npx ganache-cli --port 8545 --chain.chainId 1337 --gasLimit 8000000 # 另开终端编译并部署合约 truffle compile truffle migrate --network development --reset--port 8545 是节点监听端口rpc-url 要对应--chain.chainId 1337 是链ID签名交易里会带上它节点发现链ID不匹配会直接拒绝交易--gasLimit 8000000 给部署和合约调用留足空间gasLimit 设太小稍微复杂一点的 buy 调用就会报 out of gas。--reset 是强制重新部署所有合约开发阶段几乎每次改合约都要带这个参数。truffle migrate 跑完后终端输出里会有 contract address这行输出要记下来填进后端配置。项目资料里的部署文档在每一步都写了回车后的预期输出照着核对就行。如果你的环境里没有 truffle-config.js 里的 development 网络可以改成直接用一个 node 脚本加载编译产物、用 Web3 实例签名部署效果一样只是少了 migrations 的版本管理。项目源码里两种方式的脚本都有优先用部署文档里带的那套。4.2 后端配置与参数调优blockchain: rpc-url: http://127.0.0.1:8545 chain-id: 1337 contract-address: 0x7ce7f4b7b1c63e062f2d9c0c24d1f4b0e3da6d9a # 示例值以migrate输出为准 owner-private-key: 0x4f3edf983ac636a65a842ce7c78d9aa706d3b113bce9c46f30d7d21715b23 gas-limit: 3000000 spring: datasource: url: jdbc:mysql://localhost:3306/doc_trade?useSSLfalsecharacterEncodingutf8各配置项的坑配置项推荐值踩坑说明rpc-urlhttp://127.0.0.1:8545不能用 httpsGanache 默认走 httpchain-id与节点一致不一致报 ChainIdMismatchExceptiongas-limit3000000 以上低于合约方法实际消耗会 out of gasowner-private-key服务端环境变量写进前端等于公开账户权限这里 gas-limit 是后端发交易时给的 gasLimit跟节点 --gasLimit 不是一个东西。节点那个是区块上限后端这个是单笔交易上限。业务高峰期如果大量交易排队建议把 rpc-url 换成负载均衡后的节点地址而不是让所有人连同一个开发节点。4.3 联调期最常见的三个报错第一个是 InvalidAddressException 或 Bad response合约地址写错或节点没同步完。排查时先 curl 节点的 eth_blockNumber确认节点高度在动再确认合约地址前缀 0x 和后端配置完全一致。第二个是 ChainIdMismatchExceptionGanache 的 chainId 和配置里不一致。解决方法是配置以节点启动参数为准把 truffle-config.js 和 application.yml 两处 chainId 改成同一个值。第三个是 out of gasbuy 调用失败率最高。原因是 buy 是 payable 且有 require 分支真实消耗比 register 高gas-limit 给到 8000000 更稳妥。注意不要为了省 gas 把 send() 改成异步后不拿回执Web3j 的异步 API 在开发链上容易丢事件联调阶段用同步 send() 最简单。5. 用测试文档把交易闭环跑通的验证清单5.1 先对哈希文档存证的第一道检验部署跑通后找一个真实 Word 文档做测试不要用空文件。sha256sum 基于区块链的文档交易系统_测试文档.docx得到 64 位十六进制哈希登录系统上传这份文档再到链上查事件。Ganache 终端或 truffle console 都能看truffle console --network development DocStore.deployed().then(c c.getPastEvents(DocRegistered, { fromBlock: 0, toBlock: latest })).then(events console.log(events[0].returnValues))核对事件里的 fileHash 与 sha256sum 输出完全一致。这个验证通过说明上传的文件没被改过这个核心承诺成立。5.2 购买与下载的闭环验证用第二个账户执行购买然后做三件事查链上 Doc 的 status 是否变为 2查 MySQL 订单表是否多了一条记录金额精确到 wei点击下载时拿到的一次性 token 在 5 分钟后是否失效。第三个检查最容易漏——很多文档交易项目链上状态正确但 token 不过期等于把购买校验做成了摆设。三个都通过再重启 MySQL 并删除该文档的订单记录模拟业务库丢失这时下载接口应该仍能通过链上记录放行。这一步是整个项目最有说服力的答辩演示比讲一百句区块链不可篡改都有效。5.3 给真实项目的三个补强点部署文档之外我会建议在这个基础上再做三处小改造。一是文档哈希从 SHA-256 升级到 Keccak-256因为 Solidity 生态对 Keccak 原生支持可以直接用 keccak256(abi.encodePacked(...)) 在合约里校验省掉一次 Java 侧转换。二是把 fileUrl 指向 IPFS 而非本地磁盘本地存储在高并发下载时带宽吃紧IPFS 返回的 CID 天然可校验。三是给 buy 增加退款分支让超付金额退回买家订单取消时卖家退回文档状态这几个方法在完整源码的项目资料里都有模板照抄再改事件名即可。本文还有配套的精品资源点击获取 基于区块链的文档交易系统：Spring Boot集成Web3j与智能合约设计
简介提供一套面向计算机相关专业软件工程、区块链、物联网等毕业设计的基于区块链的文档交易系统完整源码包适合作为高分开题、毕设或课设的参考实现。压缩包共180个文件容量仅8.43MB核心代码以55个Java文件、18个Vue文件及23个JavaScript文件构成覆盖后端服务、前端交互与智能合约逻辑此外还包含21个Word文档项目报告、部署手册和若干PNG图片便于查阅设计思路与界面效果。目前已有79人学习浏览代码经过测试可运行并附带部署文档降低环境搭建门槛。项目不仅演示了区块链在文档版权交易中的落地流程还具备可修改和扩展的灵活性适合在校学生直接用于毕业设计演示或在此基础上深化区块链应用研究。1. 从一次文档纠纷说起交易系统里区块链到底在存什么二手文档交易最麻烦的不是定价而是你怎么证明这文档是你的。平台数据库被改一行记录卖家就说不清了。这套基于区块链的文档交易系统把文档注册、版权归属、售卖记录放进链上存证层——即使后面 MySQL 表被清空合约事件和交易记录还在。项目核心是 Spring Boot 业务端 Solidity 合约 Web3j 节点对接源码压缩包里附带完整部署文档和项目资料运行时由真实验证工程拆分清楚适合软件工程、区块链方向的毕业设计也适合想搞懂智能合约怎么跟业务系统配合的开发者。这条链路跑通后你会发现区块链在这里不是噱头而是卖家和买家都需要的证据链。2. 智能合约与文档交易系统的核心架构设计2.1 双层结构链上存证链下存文件文档正文直接上链是不现实的一篇几 MB 的 docx 转成 calldata 要把 gas 烧光而且文档本身要能修改、能被下载链上存它是反模式。这套系统的做法和大多数 DApp 一致——文件存本地资源目录或云存储链上只留文档的 SHA-256 哈希、标题、价格、归属地址和状态。业务上分成三层浏览器前端负责上传和购买操作Spring Boot 后端负责计算哈希、落盘文件、组装交易区块链节点层负责接收交易并产生最终不可篡改的记录。后端在落库 MySQL 的同时把关键字段同步提交到合约MySQL 是查询视图合约是真相来源。这里有个值得说透的选型为什么文档注册和交易要拆成两份逻辑而不是塞进一个合约里写完。常见做法是拆分——存证合约管登记、改状态、查归属交易侧持有存证合约地址购买时先查存证合约的 status 再做转账。拆开的好处是存证逻辑独立换交易撮合策略不动版权记录。合约语言选择 Solidity 而不是 Vyper 或 Rust是因为部署文档和 Truffle 脚手架在 EVM 兼容链上的资料最全换链成本也最低。2.2 合约的数据结构字段和存储先看核心数据结构。合约里文档信息用结构体组织字段含义如下表字段类型说明iduint256文档ID从1自增owneraddress上传者地址即版权人titlestring文档标题fileHashbytes32原文件SHA-256哈希防篡改priceuint256售价单位weifileUrlstring文件的链下访问路径statusuint80未上架 1在售 2已售 3下架createdAtuint256注册时的区块时间戳哈希用 bytes32 而不是 string是因为 SHA-256 输出正好 32 字节bytes32 占一个存储槽比 string 省大量 gas。这也是很多初写合约的人容易忽略的细节——毕业设计里如果每个字段都用 string 存部署和调用成本会明显偏高。2.3 核心合约代码注册、状态与购买// SPDX-License-Identifier: MIT pragma solidity ^0.8.0; contract DocStore { struct Doc { uint256 id; address owner; string title; bytes32 fileHash; uint256 price; // 单位wei string fileUrl; uint8 status; // 0未上架 1在售 2已售 3下架 uint256 createdAt; } mapping(uint256 Doc) public docs; uint256 public docCount; event DocRegistered(uint256 indexed id, address indexed owner, bytes32 fileHash); event DocSold(uint256 indexed id, address indexed buyer, uint256 amount); function register(string calldata title_, bytes32 fileHash_, uint256 price_, string calldata fileUrl_) external returns (uint256) { docCount 1; docs[docCount] Doc(docCount, msg.sender, title_, fileHash_, price_, fileUrl_, 1, block.timestamp); emit DocRegistered(docCount, msg.sender, fileHash_); return docCount; } function buy(uint256 docId_) external payable { Doc storage d docs[docId_]; require(d.status 1, not on sale); require(msg.value d.price, insufficient funds); d.status 2; emit DocSold(docId_, msg.sender, msg.value); } }register 里 msg.sender 就是调用地址后端用哪个私钥签名owner 就是哪个地址。fileHash_ 是后端传进来的 bytes32合约不做二次哈希只负责存证。buy 的前两行 require 分别拦住了买已下架文档和付款不足两种常见错误require 条件不满足时交易会整体回滚改不了半截状态。这里的精简版没有做资金分账和退款完整源码里还会有托管账户和一个 withdraw 方法逻辑上就是多一个 mapping 记录购买人seller 可以调用取走余额。你不需要在合约里写 if (msg.value d.price) 的找零逻辑链上交易天然支持差额返回多付的 wei 会留在合约里实际项目中通常由管理员统一结算。3. Spring Boot 集成 Web3j合约调用与文档上链实现3.1 Web3j 接入层的构建后端跟节点通信有三种常见方式直接用 HTTP JSON-RPC 拼请求、用 Web3j SDK、或者用 Spring Boot 的 web3j 场景包。这套项目用的是 Web3j理由很实际——合约用 Solidity 编译后生成的 Java 包装类可以直接 new 出合约对象调用 register、buy 就像调本地方法ABI 编解码、交易签名、nonce 管理都被封装掉了。直接拼 JSON-RPC 也不是不行但代码里到处是十六进制字符串调试成本翻倍。pom 里引核心包dependency groupIdorg.web3j/groupId artifactIdcore/artifactId /dependency版本号按项目源码里的 POM 锁定部署文档里写的是用 Spring Boot 2.x 配套的 Web3j 4.x 系。接入 Bean 配置如下Configuration public class Web3jConfig { Value(${blockchain.rpc-url}) private String rpcUrl; Value(${blockchain.owner-private-key}) private String privateKey; Value(${blockchain.contract-address}) private String contractAddress; Bean public Web3j web3j() { return Web3j.build(new HttpService(rpcUrl)); } Bean public DocStore docStore(Web3j web3j) { Credentials credentials Credentials.create(privateKey); return DocStore.load(contractAddress, web3j, credentials, new DefaultGasProvider()); } }这里三个配置项的分工要讲清楚。rpc-url 决定 Web3j 连哪个节点部署文档里默认是 http://127.0.0.1:8545也就是本机起的私有链或者 Ganache 开发链contract-address 是合约部署完回显的地址很多没跑通的案例都是因为合约重新部署后忘了同步这个配置owner-private-key 是签名凭据所有交易都由后端签名发出这属于后端钱包模式部署文档里强调私钥只放服务端环境变量不要写进前端。3.2 文档上链从文件到交易回执上链不是一个方法搞定的事它是一条完整链路文件落地 → 算哈希 → 调合约 → 等回执 → 解析日志。public DocumentVO publish(MultipartFile file, String title, BigDecimal price) throws IOException { // 1. 文件落盘返回可访问的相对路径 String fileUrl storageService.save(file); // 2. 计算SHA-256转成32字节哈希 String hashHex DigestUtils.sha256Hex(file.getInputStream()); byte[] hashBytes Numeric.hexStringToByteArray(hashHex); // 3. ETH转wei避免double精度问题 BigInteger priceWei price.multiply(BigDecimal.valueOf(1_000_000_000_000_000_000L)) .toBigIntegerExact(); // 4. 调用合约注册返回交易回执 TransactionReceipt receipt; try { receipt docStore.register(title, hashBytes, priceWei, fileUrl).send(); } catch (Exception e) { throw new BizException(上链失败请检查节点连接或Gas设置, e); } // 5. 从事件日志中取回docId ListDocRegisteredEventResponse events docStore.getDocRegisteredEvents(receipt); if (events.isEmpty()) { throw new BizException(注册回执中没有事件日志, null); } return DocumentVO.of(events.get(0).docId, hashHex, fileUrl); }第 2 步用 DigestUtils.sha256Hex 对文件流计算而不是对文件名计算——项目文档里也反复强调任何一个字节变化哈希都会变拿文件名做哈希等于没哈希。第 3 步的 price 用 BigDecimal 乘 10^18 再转 BigInteger是在避免数据库 decimal 或 JSON 数字转 double 带来的精度丢失链上金额一律用 wei 整数。第 5 步必须从回执日志里拿 docId不能自己再 count1链上并发交易时本地计数不一定和实际写进链的顺序一致。3.3 交易接口与授权下载的状态闭环后端接口和合约方法对应关系如下HTTP 接口合约动作业务含义POST /api/docsregister上传文档落盘并上链存证status置1GET /api/docs查 docs() / docCount()分页读MySQL再过滤链上状态POST /api/docs/{id}/buybuy()买家发起购买后端签名代付GET /api/docs/{id}/download查 status 与授权校验链上已售且为当前买家购买和下载之间有一个容易踩的坑buy 里把 status 置为 2 后后端如果还允许卖家自己下载就失去了交易的意义。部署文档里的处理方式是下载接口先查 MySQL 订单表再调链上 docs() 确认 status 和 buyer两层校验都过才签发一次性下载 token。TOKEN 有效期设为 5 分钟放在 Redis 里做防重放。接口层要做幂等同一个订单重复点击购买时后端应先查链上 statusstatus 已经是 2 就直接返回已售而不是再发一笔转账交易否则会多扣一次钱。状态流转在链上只有 1→2 一步下架和退款属于后台管理操作由管理员私钥调单独的方法。这样设计的好处是交易主流程被压到最短出问题的可能性最小。4. 部署文档里的关键配置与节点联调排错4.1 开发链与合约部署这套项目的部署文档我按先链后业务的顺序看。先启动开发链再编译部署合约最后才启动 Spring Boot顺序反了会出现合约地址还没写入配置后端起来却连接空地址的尴尬。# 安装依赖并启动Ganache开发链 npx ganache-cli --port 8545 --chain.chainId 1337 --gasLimit 8000000 # 另开终端编译并部署合约 truffle compile truffle migrate --network development --reset--port 8545 是节点监听端口rpc-url 要对应--chain.chainId 1337 是链ID签名交易里会带上它节点发现链ID不匹配会直接拒绝交易--gasLimit 8000000 给部署和合约调用留足空间gasLimit 设太小稍微复杂一点的 buy 调用就会报 out of gas。--reset 是强制重新部署所有合约开发阶段几乎每次改合约都要带这个参数。truffle migrate 跑完后终端输出里会有 contract address这行输出要记下来填进后端配置。项目资料里的部署文档在每一步都写了回车后的预期输出照着核对就行。如果你的环境里没有 truffle-config.js 里的 development 网络可以改成直接用一个 node 脚本加载编译产物、用 Web3 实例签名部署效果一样只是少了 migrations 的版本管理。项目源码里两种方式的脚本都有优先用部署文档里带的那套。4.2 后端配置与参数调优blockchain: rpc-url: http://127.0.0.1:8545 chain-id: 1337 contract-address: 0x7ce7f4b7b1c63e062f2d9c0c24d1f4b0e3da6d9a # 示例值以migrate输出为准 owner-private-key: 0x4f3edf983ac636a65a842ce7c78d9aa706d3b113bce9c46f30d7d21715b23 gas-limit: 3000000 spring: datasource: url: jdbc:mysql://localhost:3306/doc_trade?useSSLfalsecharacterEncodingutf8各配置项的坑配置项推荐值踩坑说明rpc-urlhttp://127.0.0.1:8545不能用 httpsGanache 默认走 httpchain-id与节点一致不一致报 ChainIdMismatchExceptiongas-limit3000000 以上低于合约方法实际消耗会 out of gasowner-private-key服务端环境变量写进前端等于公开账户权限这里 gas-limit 是后端发交易时给的 gasLimit跟节点 --gasLimit 不是一个东西。节点那个是区块上限后端这个是单笔交易上限。业务高峰期如果大量交易排队建议把 rpc-url 换成负载均衡后的节点地址而不是让所有人连同一个开发节点。4.3 联调期最常见的三个报错第一个是 InvalidAddressException 或 Bad response合约地址写错或节点没同步完。排查时先 curl 节点的 eth_blockNumber确认节点高度在动再确认合约地址前缀 0x 和后端配置完全一致。第二个是 ChainIdMismatchExceptionGanache 的 chainId 和配置里不一致。解决方法是配置以节点启动参数为准把 truffle-config.js 和 application.yml 两处 chainId 改成同一个值。第三个是 out of gasbuy 调用失败率最高。原因是 buy 是 payable 且有 require 分支真实消耗比 register 高gas-limit 给到 8000000 更稳妥。注意不要为了省 gas 把 send() 改成异步后不拿回执Web3j 的异步 API 在开发链上容易丢事件联调阶段用同步 send() 最简单。5. 用测试文档把交易闭环跑通的验证清单5.1 先对哈希文档存证的第一道检验部署跑通后找一个真实 Word 文档做测试不要用空文件。sha256sum 基于区块链的文档交易系统_测试文档.docx得到 64 位十六进制哈希登录系统上传这份文档再到链上查事件。Ganache 终端或 truffle console 都能看truffle console --network development DocStore.deployed().then(c c.getPastEvents(DocRegistered, { fromBlock: 0, toBlock: latest })).then(events console.log(events[0].returnValues))核对事件里的 fileHash 与 sha256sum 输出完全一致。这个验证通过说明上传的文件没被改过这个核心承诺成立。5.2 购买与下载的闭环验证用第二个账户执行购买然后做三件事查链上 Doc 的 status 是否变为 2查 MySQL 订单表是否多了一条记录金额精确到 wei点击下载时拿到的一次性 token 在 5 分钟后是否失效。第三个检查最容易漏——很多文档交易项目链上状态正确但 token 不过期等于把购买校验做成了摆设。三个都通过再重启 MySQL 并删除该文档的订单记录模拟业务库丢失这时下载接口应该仍能通过链上记录放行。这一步是整个项目最有说服力的答辩演示比讲一百句区块链不可篡改都有效。5.3 给真实项目的三个补强点部署文档之外我会建议在这个基础上再做三处小改造。一是文档哈希从 SHA-256 升级到 Keccak-256因为 Solidity 生态对 Keccak 原生支持可以直接用 keccak256(abi.encodePacked(...)) 在合约里校验省掉一次 Java 侧转换。二是把 fileUrl 指向 IPFS 而非本地磁盘本地存储在高并发下载时带宽吃紧IPFS 返回的 CID 天然可校验。三是给 buy 增加退款分支让超付金额退回买家订单取消时卖家退回文档状态这几个方法在完整源码的项目资料里都有模板照抄再改事件名即可。本文还有配套的精品资源点击获取