简介一套基于SpringBoot的区块链农产品溯源系统采用多系统微服务架构包含后端Java服务、Vue管理端、微信小程序端以及区块链网络配置与数据库脚本。面向需要毕业设计、课程项目或快速搭建溯源平台的开发者适合已有SpringBoot基础并希望了解区块链结合微服务的读者。压缩包共1370个文件整体约15.73MB其中255个Java与86个Vue承担服务端和后台管理251个JavaScript配合110个WXML、109个WXSS组成小程序页面另有124个JSON、98个PEM、34个CRT、17个KEY等文件覆盖区块链证书、节点身份密钥与各项配置配套SQL脚本可完成数据库初始化。资源内含多个区块链身份密钥和Fabric相关工具配置能帮助还原多节点交易链打通产地、加工、仓储、销售的全流程追溯。已有459人学习下载对需要完整可运行参考项目的研究者与开发者具有较高实用价值。1. 基于SpringBoot的区块链农产品溯源系统这套工程包到底值不值得拆网上打着区块链溯源的工程包一抓一把十个里有八个是把一串哈希存进MySQL数据库就算上了链扫码页面后端一刷新运营随手就把记录改了。真正对得上“区块链的农产品溯源系统”这个标题的工程通常长这样不是单个SpringBoot应用而是按照溯源核心、生产、质检、物流、区块链存证拆成多个SpringBoot微服务协作另外再配一份初始化数据库脚本。多系统微服务源代码加数据库的工程包价值就在于能把“上链动作”和“业务查询”真正拆开。这篇笔记不打算复述某个包里每一个文件的目录结构而是把这类方案普遍要迈的坎写清楚微服务边界怎么切、上链代码放在哪一层、多服务之间如何共享同一个批次号、数据库脚本按什么顺序导入以及部署后最容易翻车的几个点。适合两种人刚接手区块链溯源项目想快速跑通的已经在维护溯源系统、想把链上链下数据关系理顺的。全文按后端工程师落地视角来写能抄作业的地方尽量给了参数。2. 农产品溯源系统的微服务拆分哪些数据值得上链哪些留在数据库2.1 先把业务链条画出来批次号是一整条链路的主键做农产品溯源第一件事是认清业务追踪的是“批次”而不是单件。一棵白菜上印一个码不现实通常是一块地、同一采收时段、同一品种的菜用一个批次号对外流通。后续所有环节都围绕这个批次号展开。一个典型的信息闭环是生产环节记录播种、施肥、打药、采收养殖类还要记饲料、疫苗、防疫日期加工环节做初加工、包装批次、贴溯源码质检环节记录样品编号、检测报告编号、质检员物流环节记录运输车辆、温湿度、出入库时间销售环节把订单和批次绑定。这里每段数据天然由不同角色产生。产地现场可能是农户或合作社在用一套录入系统加工厂是另一套系统物流公司又是第三方平台。这些系统原本就各自独立做溯源并不是要求所有人换到同一套软件里而是用微服务把各自的接口收进来统一挂到批次号下面。所以微服务不是拿SpringCloud硬拆出来的模块而是业务现场本来就有多套系统微服务只是让它们在同一套数据模型下协作这就是标题里“多系统微服务”的来由。2.2 微服务怎么切溯源核心、业务域服务、链服务三层职责常见的一种切法是五个业务服务加一个网关。网关负责路由、鉴权和限流trace-core是溯源核心负责批次号生成、溯源码管理、扫码聚合查询producer-service管生产农事quality-service管质检报告logistics-service管物流单据chain-service是区块链存证服务统一封装对联盟链节点的读写。关键边界在chain-service这一层。它是唯一连接区块链节点的服务其它业务服务不允许直连链。为什么一定要单独抽一层原因有三私钥要收敛到一处管理节点地址和链参数只要改一个地方合约升级时只动chain-service而不牵连生产服务。如果每个业务服务都直连节点私钥散落在多个工程里签名账户五花八门等审计时连“哪个服务写了哪条记录”都分不清这个链就等于白搭了。还有一点常被忽略业务域服务之间不直接互相调用一律经过trace-core聚合。比如质检服务不会直接去调生产服务查种植记录它只保存“批次号检测结果”查询页面要拼装完整链路时由trace-core统一去各服务取数。这样依赖方向是向心的不会出现两个业务服务互相Feign的死循环。2.3 数据库与区块链各存什么双写双存储的边界我刚接触区块链溯源时有一个误区以为要把所有业务明细都往链上写。后来被现实教育了链上存储成本远高于数据库写入速度也慢把几百条农事记录全上链既不划算也没必要。实际方案是“数据库存全量链上存凭证摘要”。存储方向存什么数据特征MySQL业务库生产、质检、物流全量明细后台可维护查询快、支持复杂统计、数据可修正区块链存证批次关键字段的哈希摘要、上链账户、时间戳不可篡改、防抵赖、可按账户追溯具体做法是每个批次在trace_db里生成一条主记录包含批次号、产品类型、产地、生产者等核心字段业务明细继续落在各业务库里。上链时把核心字段按固定规则拼接成一个字符串做SHA-256得到摘要再连同批次号一起写入链上存证合约。这样设计之后“不可篡改”体现在哪里——MySQL里的业务数据可以被后台修改但修改后重新计算的摘要就和链上旧摘要对不上了。扫码查询时后端取到库里的明细重新计算一次摘要去链上比对一致则验签通过不一致则提示记录已被改动。数据库允许被编辑链上却保留着编辑前的证据这比“让所有人都不许改数据”更符合农业现场的真实需求。3. SpringBoot调用区块链节点上链代码的写法与参数细节3.1 联盟链的选型与SDK配置农产品溯源用到的链基本都是联盟链而不是比特币、以太坊那种公有链。联盟链有节点准入控制、数据对联盟成员可见不涉及代币性能和合规性更适合国内企业级应用。常见选型是FISCO BCOS或者Hyperledger Fabric两者都有Java SDK可以在SpringBoot工程里直接调用。具体用哪条链经常看项目所在地的生态但配置逻辑是相通的。chain-service工程里通常要配节点地址、groupId、chainId和合约地址。我可以给出一个典型配置spring: application: name: chain-service blockchain: # 区块链节点RPC地址多个节点用逗号分隔 nodes: addresses: 127.0.0.1:20200,127.0.0.1:20201 # 群组ID一个链上可以分多个业务群组溯源业务单独用一个组 groupId: 1 # 链ID防止连错链 chainId: 1 # 存证合约部署后拿到的合约地址 contract: evidenceAddress: 0x9b2c... # 服务使用的链上账户私钥文件路径注意千万不要提交到git account: privateKeyPath: ./config/keystore/0x5a4d....pem这里最容易被忽略的参数是groupId。FISCO BCOS这类联盟链支持多群组不同业务可以跑在不同群组里。如果配置里groupId和查询时用的不一致会出现“明明写入成功了换台机器查链上记录却查不到”的诡异现象。链ID也是同理多套环境时一定要区分。3.2 上链方法的核心代码交易回执和事件解析把业务摘要写入链上合约的代码写在chain-service里给trace-core提供接口。核心逻辑是先加载账户再调用合约方法最后解析回执。/** * ChainService.java —— 区块链存证服务 * 职责接收上游传过来的批次摘要写入链上存证合约 */ Slf4j Service public class ChainService { Autowired private ChainConfig chainConfig; /** * 存证上链 * param batchNo 批次号 * param businessDigest 业务摘要由trace-core计算后传入 * return 链上交易哈希 */ public String storeDigest(String batchNo, String businessDigest) { // 1. 从配置指定的私钥文件加载账户 CryptoKeyPair account loadAccount(chainConfig.getAccount().getPrivateKeyPath()); // 2. 加载存证合约合约里维护的是 batchNo - digest 的映射 Evidence evidence Evidence.load( chainConfig.getContract().getEvidenceAddress(), chainConfig.getClient(), account ); // 3. 调用合约方法得到交易回执 TransactionReceipt receipt evidence.record(batchNo, businessDigest).send(); // 4. 解析合约事件而不是只看receipt的状态 ListEvidence.RecordEventResponse events evidence.getRecordEvents(receipt); if (events.isEmpty()) { // 事件为空说明合约内部逻辑可能没走到预期分支 throw new BizException(合约事件日志为空上链结果不可确认); } log.info(batchNo{} 上链成功, tx{}, block{}, batchNo, receipt.getTransactionHash(), receipt.getBlockNumber()); // 5. 把交易哈希和区块号落到本地SQLite或MySQL表里方便对账 chainRecordMapper.insert(batchNo, receipt.getTransactionHash(), receipt.getBlockNumber()); return receipt.getTransactionHash(); } }这段代码里最值得讲的是“为什么必须解析事件回执”。我见过很多同事只判断receipt.isStatusOK()就认为成功了但合约内可以写“查询到批次已存在就返回而不触发事件”这种逻辑交易在链上确实打包了状态码可能也是成功的可业务数据没写进去。只有事件日志能确认合约确实走到了存证分支。另一个细节是交易哈希不能当业务索引用——它只是这笔交易在链上的凭证真正定位业务记录要靠合约事件里的batchNo。3.3 溯源查询接口聚合业务明细和链上凭证扫码入口通过trace-core的接口完成。它按顺序做三件事根据溯源码解析出批次号从各业务服务聚合明细再从链上取凭证校验。/** * TraceQueryController.java —— 溯源查询入口 * 前端扫码拿到traceCode后调用此接口 */ RestController RequestMapping(/api/v1/trace) public class TraceQueryController { Autowired private TraceCoreService traceCoreService; Autowired private ChainClient chainClient; Autowired private DigestCalculator digestCalculator; GetMapping(/{code}) public ResultVOTraceVO query(PathVariable(code) String code) { // 1. 二维码里的溯源码解析成批次号 String batchNo traceCoreService.resolveBatchNo(code); // 2. 内部通过Feign聚合producer/quality/logistics的数据 TraceVO traceVO traceCoreService.aggregate(batchNo); // 3. 调用chain-service查询链上存证摘要 ChainProof proof chainClient.getProof(batchNo); // 4. 用聚合后的明细重新计算业务摘要与链上对比 String localDigest digestCalculator.calcDigest(traceVO); boolean valid localDigest.equals(proof.getDigest()); traceVO.setProof(proof); traceVO.setVerifyResult(valid ? 验签通过 : 数据被篡改); return ResultVO.ok(traceVO); } }聚合这一步要特别注意超时控制。一个扫码请求要串行调生产、质检、物流三个服务任何一个服务响应慢都会直接拖垮扫码体验。常见做法是在Feign层面设置连接超时3秒、读取超时5秒同时给每个Feign接口配Fallback降级——某个服务挂了就返回空列表不要让整个二维码扫描功能不可用。链上校验反而是最稳定的因为chain-service只查一次链耗时可控。4. 多系统微服务的通信链路与数据库初始化本地跑通的细节4.1 Nacos注册中心与Feign调用的超时参数多系统微服务要协作首先得让每个服务能找到对方。常见方案是Nacos做注册中心服务启动后自动注册trace-core要调producer-service时通过服务名解析实例地址。Feign接口就是这一步的载体。/** * ProducerFeignClient.java —— 在trace-core工程里定义 * 通过服务名调用producer-service的接口 */ FeignClient( name producer-service, path /producer, fallback ProducerFeignFallback.class ) public interface ProducerFeignClient { /** * 查询某个批次的生产农事记录列表 */ GetMapping(/batch/{batchNo}/records) ListProduceRecordDTO listRecords(PathVariable(batchNo) String batchNo); }fallback类不能省。我一般会在降级方法里打印日志并返回空列表至少保证扫码页面能展示质检和物流信息。对应的超时参数在trace-core的配置文件里feign: client: config: default: # 建立连接的超时时间单位毫秒 connectTimeout: 3000 # 读取数据的超时时间单位毫秒 readTimeout: 5000一个容易翻车的点是网关超时和Feign超时的配合。如果网关路由超时设的是5秒Feign整条链路可能要6秒你看到的现象就是后端日志显示Feign正常返回了但前端早就收到了504。我一般把网关路由超时设到10秒以上Feign的readTimeout保持5秒让网关兜得住聚合链路的最坏情况。4.2 批次号由统一服务签发避免数据串批次多服务协作最怕两件事时间对不上、批次对不上。批次号一旦有两个服务各自生成溯源链路就会断裂。所以设计约束必须是批次号只能由trace-core的t_batch表签发下游服务只接收这个批次号作为业务数据的外键。数据库层面不要做物理外键。虽然MySQL支持跨库外键但在微服务架构里物理外键会带来两个问题一是多个服务操作不同数据库外键约束跨库没法保持一致二是删除主记录时可能触发意外的级联删除。常见的做法是“软关联”——各业务表保留batch_no字段通过定时对账任务检查孤儿数据。这样既保证查询时可以按batch_no关联又不会因为物理外键把服务仓库耦合死。4.3 数据库初始化脚本顺序和一处典型的库表冲突一套多系统微服务源码包通常带着几个SQL文件导入顺序错了直接报错。合理的脚本组织方式大致是文件名作用依赖01_create_databases.sql创建trace_db、producer_db、quality_db等库无02_trace_core_tables.sql批次主表、溯源码表、链上记录表0103_producer_tables.sql农事记录表、采收批次表0104_quality_tables.sql质检报告表、样品表0105_logistics_tables.sql物流单表、温控记录表0106_init_data.sql默认管理员账号、字典数据、初始溯源码规则02-05为什么02必须在03之前执行业务子表里都存batch_no虽然不建物理外键但应用启动阶段trace-core要先把批次主表结构初始化好否则producer服务写入数据时batch_no没有参照后续聚合查询会查出大量孤儿数据。我见过有人先导入03再导02结果producer-service启动时报表不存在折腾了半小时才发现是顺序反了。导入完成后还有一个细节检查所有表的字符集是否统一。生产环境经常遇到一个库是utf8mb4另一个库是utf8导致多服务联查时中文乱码。初始化脚本里显式加DEFAULT CHARSETutf8mb4比事后手动改省事得多。启动顺序方面我一般先启动chain-service再启动trace-core、producer、quality、logistics最后启动gateway。chain-service先起是因为trace-core启动时要检测链连接配置链服务没起来日志会刷一堆连接异常。实际这也不绝对最少你在本地联调时确保chain-service先于trace-core注册到Nacos即可。5. 避坑指南区块链溯源系统最容易翻车的5个点5.1 上链回执显示成功查询却找不到记录现象日志里打出交易哈希但换一台机器或者换一个接口查该批次的链上记录结果却是空的。原因大概率是只保存了transactionHash没有解析合约事件日志。合约里如果写的是“batchNo存在则覆盖”第一次上链成功第二次查询时因为没解析事件本地表里没有任何可查询的索引。另一个常见原因是合约里batchNo的类型定义成了bytes32而Java端传的是String编码不一致导致键被转成了畸形值。解决上链代码里必须getRecordEvents(receipt)解析事件并把事件返回的batchNo连同交易哈希一起落库Java端和合约端的字段类型统一用String。排查时可以先把合约事件里的batchNo打印出来看是否和入参一致。5.2 运营改了数据库记录扫码页面没有任何提示现象后台把采收日期从本周三改成了上周五扫码页面显示的是新日期核验状态还是“通过”。原因做查询接口时只做了聚合展示没有真正去链上比对摘要verifyResult是前端写死的“验签通过”或者后端虽然在比对但结果没传给前端。解决查询链路里必须保留第3.3节那个比对步骤——后端拿到库里的明细重新计算摘要和链上摘要不一致时直接返回“数据被篡改”状态。这是区块链溯源系统的底线功能一旦这层校验被绕过整条链就变成了摆设。上线前用SQL直接改几条数据做验收测试确认扫码页能告警才算通过。5.3 每次重启服务链上账户换来换去现象服务重启后继续上链交易都成功但链上记录的账户地址变了审计时无法定位是哪个业务系统写的。原因代码里没有从固定私钥文件加载账户而是让SDK生成了临时账户。这种情况多半是私钥路径配置缺了程序自动回退到随机账户每次重启都是新身份。解决在配置中心统一管理私钥路径chain-service启动时显式加载固定私钥同时在数据库维护一张服务与链账户的映射表上链时带上来源标识。私钥文件不要放进git仓库用环境变量或配置中心下发。5.4 网关超时和Feign重试互相打架现象扫码偶发504后端日志里Feign调用正常返回但用户侧已经看到超时。原因网关层路由超时设得比Feign链路耗时短。Feign内部还有重试机制一次请求重试两次加上连接等待整条链路耗时超过网关阈值网关先断开了连接。解决把网关路由超时调到Feign总耗时的两倍以上写操作关掉Feign重试避免重复写入业务表。排查超时问题时不要只看单次请求耗时要把网关日志和Feign日志的时间戳对齐看。5.5 各服务本地时间不齐溯源时间轴错位现象同一批次的页面显示采收时间晚于出库时间两个服务记录的时间戳差了十几分钟。原因生产、质检、物流部署在不同机器系统时间没有同步。有的服务用DateTime.now()取应用服务器时间有的服务用数据库的now()两边时间基准不一样。解决所有服务部署时做NTP时间同步新数据的时间字段统一由数据库生成应用层不传时间对外展示的时间由trace-core统一按UTC转换。排查发现的时间错位数据按batchNo在相关表里查历史更新时间做修正。6. 用链上对账脚本给整套系统兜底增量校验与离线复核上链和展示都跑通后最容易被忽略的是数据变更监查。管理员误改业务库、定时任务重算覆盖了字段、下游系统回刷数据都会导致数据库内容和链上摘要分叉。MySQL里的数据是能改的链上不会自动跟着变所以一定要有一个对账机制兜底。我一般会在每天凌晨跑一个对账脚本从业务库读出当天有变动的批次重新计算摘要调chain-service的查询接口拿到链上摘要比对结果不一致的落到告警表。# reconcile_trace.py —— 每日对账脚本 # 作用比对MySQL业务数据和链上存证摘要发现差异后告警 import hashlib import pymysql import requests def calc_digest(batch): # 字段拼接顺序必须和chain-service里的DigestCalculator保持一致 raw {}|{}|{}|{}.format( batch[batch_no], batch[product_type], batch[producer], batch[harvest_date] ) return hashlib.sha256(raw.encode(utf-8)).hexdigest() def run(since_ts): conn pymysql.connect( host127.0.0.1, usertrace_ro, # 只读账号不要用业务主账号 password******, databasetrace_db ) cur conn.cursor() # 增量查询取更新时间大于上次对账时间戳的批次 cur.execute( SELECT batch_no, product_type, producer, harvest_date FROM t_batch WHERE updated_at %s, (since_ts,) ) for row in cur.fetchall(): batch { batch_no: row[0], product_type: row[1], producer: row[2], harvest_date: row[3], } digest calc_digest(batch) # 调用chain-service的REST接口查链上摘要脚本不直接连链 resp requests.get( http://127.0.0.1:8082/trace/proof/{}.format(batch[batch_no]), timeout3 ).json() chain_digest resp.get(digest) if digest ! chain_digest: # 落告警表同时打日志次日由运营人工复核 save_mismatch(batch[batch_no], digest, chain_digest) print(MISMATCH batch_no{}.format(batch[batch_no]))增量查的关键是updated_at字段。每个业务表只要规范维护这个字段对账脚本就能只扫当天变动的数据不用每天全量计算几万条批次。链接chain-service用REST接口而不是在脚本里引Java SDK省掉一套依赖环境换个机器也能跑。这个脚本我会挂在定时任务里每天凌晨2点跑一次查出差异后推给运营。后来有同事问我“这条链的价值到底体现在哪”我的回答是它不让数据库里的数据变不了而是让你知道数据哪一天变了、曾经是什么样。防篡改不是嘴上说说是要在每次改动后留一条可以被检查的痕迹。对账就是那个检查动作也是这套系统真正值钱的地方。希望帮到你。本文还有配套的精品资源点击获取
