基于IPFS与以太坊的去中心化文件存证平台实战-北京尧图网络

简介这是一份基于区块链与IPFS技术构建去中心化文件存储平台的完整项目源码面向具备JavaScript基础、希望学习以太坊智能合约与分布式存储的开发者。项目整合了Solidity编写的存储合约、Web3.js链上交互逻辑、React.js前端界面以及IPFS文件分发机制能够清晰展示文件上传、哈希写入、权限控制与下载验证等核心流程。资源共26个文件包含10个js、4个json、2个sol合约及若干配置、样式和说明文档压缩包仅1.23MB目录划分合理便于按模块研读。已有334人学习下载。通过学习这份代码读者可以掌握Truffle部署与迁移脚本的写法、合约测试用例的组织方式并借助项目中的环境配置文件快速搭建本地开发环境前端素材与交互逻辑的对应关系也有助于理解链上状态与页面展示的联动。整套工程可作为构建个人云盘或数字资产管理DApp的起始模板具有实用的参考价值。1. 去中心化文件存储平台把文件哈希写进链上做一个能追溯的网盘你把合同扫描件传到一个网盘上两个月后对方反口说“你从来没传过这个文件”。传统网盘只能回答“我帮你存着”却拿不出一个可验证的时间证明。如果把文件的哈希同时写进一条区块链文件本体交给 IPFS 保存上传时间戳和上传者身份由 Solidity 智能合约记录这个“网盘”就从存储工具变成了一台存证机。我基于以太坊、JavaScript 和 React.js 做了一套去中心化文件存储平台体验对标常见网盘应用浏览器里连接钱包、上传、列出和下载文件。适合想完整走一遍 web3 全栈流程的前端开发者也适合想把数据存证和内容寻址讲清楚的 JavaScript 学习者。2. 架构与目录设计一次上传在 IPFS 与区块链之间绕了多远做这个项目之前我先问了自己一个很实际的问题网盘这东西核心是存储区块链到底能帮什么忙如果把文件本体塞进以太坊交易里传一张照片或许还能接受传一个视频可能就要烧掉几百美元。所以这套项目的设计原则只有一句话链上只存“凭据”链下才放“内容”。IPFS 负责内容Solidity 合约负责记录内容指纹与上传证明React 和 Web3.js 负责把两端拼成用户能看懂的界面。2.1 三层架构设计IPFS 管内容合约管凭证React 管操作整个项目可以拆成三层分别对应一个文件的存储期、存证期和使用期。第一层是 IPFS 存储层我选择 IPFS 而不是普通服务器是因为它是内容寻址的两个文件内容一样算出来的哈希就一样能天然去重。第一层只需要回答“给我这个哈希我返回文件内容”这件事。第二层是智能合约层合约部署在以太坊网络上保存文件元数据文件名、CID、大小、上传者地址、时间戳。第三层是 React 应用层负责把文件转成 IPFS 能接受的格式、调用 Web3.js 发起交易、再从合约读回文件列表。这样分层最直接的好处是换存储节点不用迁移链上记录换前端框架也不影响已经上链的凭证。文件内容可以随时被复制到别的 IPFS 节点只要 CID 不变链上的证明就依然有效。合约只存字符串和数字不碰二进制内容天然避开了区块链的存储成本。前端拿到一个 CID 后拼上 IPFS 网关地址就能生成下载链接也不需要额外维护一张“文件真实位置”的表。用这种方式构思 DApp比一开始就想着“把文件传到链上”要少走很多弯路。链上合约是公共账本任何人都能读到所以永远不要指望用它保存隐私文件这一版的功能定位是“公开文件存证网盘”。后续要加隐私保护需要在浏览器里先加密再上传这点我在最后一章会展开。2.2 项目目录结构与关键依赖这一版我没有引入重型开发框架依赖非常克制前端用 React 管理界面状态Web3.js 负责与以太坊交互ipfs-http-client 负责与本地 IPFS 节点通信solc 负责在 Node 环境里编译合约。核心文件结构如下路径作用contracts/FileStorage.sol文件元数据存证合约项目唯一与链交互的接口scripts/compile.js用 solc 编译合约输出 ABI 到 src/contractsscripts/deploy.js部署合约到本地链打印合约地址src/config.js存放合约地址、链 ID、IPFS API 地址src/utils/web3.js初始化 Web3连接钱包或本地链src/utils/ipfs.js封装 ipfs-http-client上传文件返回 CIDsrc/components/FileUpload.js上传表单先走 IPFS 再走合约src/components/FileList.js从合约读取列表生成 IPFS 下载链接src 下还有一个隐藏的 contracts/FileStorage.json这是 compile.js 生成出来的编译产物包含 ABI 和字节码。前端合约实例依赖这份 ABI部署脚本依赖字节码所以每次改合约第一步永远是重新编译否则前后端就会拿到两套不一致的接口定义。项目里其它目录都是脚手架这三份文件才是核心骨架。2.3 一次文件上传的完整链路我在 FileUpload 组件里放了一个文件输入框用户选中文件后整个链路会经历五次关键转换。第一步前端用 FileReader 或 file.arrayBuffer() 把文件转成二进制 Buffer因为 IPFS 节点接收的是字节流而不是浏览器 File 对象。第二步调用 ipfs.add()本地节点返回一个 CID这一步通常几十毫秒就能完成。第三步把文件名、CID、文件大小作为参数调用合约的 uploadFile 方法浏览器钱包弹窗要求确认签名。第四步交易被打包后合约触发 FileUploaded 事件前端拿到交易哈希。第五步FileList 组件重新调用合约的 getFileCount 和 getFile把最新的列表刷出来。这条链路里最容易让新手误判的是第四步和第五步之间的间隔。交易哈希出现只代表交易被接收不代表已经确认我用固定间隔轮询合约状态等文件数量真正增加才更新界面避免上传完看不到文件导致用户反复点击。实际测试中本地模拟链自动挖矿模式下确认时间通常在一秒左右但换到真实测试网就可能变成十几秒界面必须做好“等待确认中”的状态提示。除了文件本身我还在 IPFS 上传时设置了 pin: true。这个参数的意义是让本地节点把这份内容标记为“要保留”否则节点运行一段时间后触发垃圾回收会把没有被引用的内容清掉。CID 仍在链上但通过 CID 拉不到文件存证就会变成一张没有对应实物的证书。这条经验放在谁身上都值得提前埋好。3. 核心模块拆解Solidity 合约、Web3.js 与 IPFS 上传的三段关键代码整个项目的代码量不大但每一段都承担着不同职责。我把可运行的代码按执行顺序拆成三段来讲先写合约再写前端连接最后写上传链路。这样读起来就像跟着用户操作走了一遍。3.1 Solidity 合约用动态数组和事件记录文件凭证合约是整个平台的证据锚点。我定义了 File 结构体字段对应一次完整上传记录。用动态数组而不是映射来存储文件是为了让前端能通过循环遍历拿到“第 0 个文件、第 1 个文件……”否则还要额外维护一套 ID 列表增加复杂度。// SPDX-License-Identifier: MIT pragma solidity ^0.8.0; contract FileStorage { struct File { string fileName; // 原始文件名仅作展示 string cid; // IPFS 内容标识符 uint256 fileSize; // 文件大小单位字节 address uploader; // 上传者钱包地址 uint256 timestamp; // 区块时间戳可信存证时间 bool exists; // 软删除标记 } File[] private files; event FileUploaded( uint256 indexed id, string fileName, string cid, uint256 fileSize, address indexed uploader, uint256 timestamp ); function uploadFile( string memory _fileName, string memory _cid, uint256 _fileSize ) external returns (uint256) { require(bytes(_cid).length 0, cid is empty); require(bytes(_fileName).length 0, fileName is empty); files.push(File({ fileName: _fileName, cid: _cid, fileSize: _fileSize, uploader: msg.sender, timestamp: block.timestamp, exists: true })); uint256 id files.length - 1; emit FileUploaded(id, _fileName, _cid, _fileSize, msg.sender, block.timestamp); return id; } function getFile(uint256 _id) external view returns( string memory fileName, string memory cid, uint256 fileSize, address uploader, uint256 timestamp ) { require(_id files.length, file not found); File storage f files[_id]; require(f.exists, file was deleted); return (f.fileName, f.cid, f.fileSize, f.uploader, f.timestamp); } function getFileCount() external view returns (uint256) { return files.length; } }逻辑说明uploadFile 接收文件名、CID、文件大小三个参数把当前调用者 msg.sender 和区块时间 block.timestamp 一并存入结构体然后塞进动态数组。事件 FileUploaded 里带 indexed 的参数只有两个因为 Solidity 规定事件最多对三个参数做索引索引参数会生成单独的主题方便前端按上传者地址过滤历史记录。exists 字段从这一版就留好了后面做软删除时不需要改合约的数据结构。参数说明_fileName 和 _cid 都是 memory 类型表示只读入内存不写入存储避免不必要的 gas 消耗。_fileSize 用 uint256 是因为前端 file.size 返回的数字本身就来自 JavaScript Number最大安全整数远小于 uint256 上限不会溢出。getFile 用 external view 修饰view 表示这不修改链上状态前端可以直接用 .call() 方式读取不产生交易费用。3.2 Web3.js 初始化兼容浏览器钱包与本地 RPC前端连接以太坊绕不开 Web3.js。我把它封装在 utils/web3.js 里统一对外暴露初始化方法和合约实例获取方法。浏览器钱包插件会向页面注入一个全局对象通过这个对象可以拿到用户授权的账户地址。开发环境下如果没有钱包插件我直接连本地模拟链的 RPC 端口用链上的测试账户。import Web3 from web3; let web3; let account; export async function initWeb3() { // 优先使用浏览器钱包插件注入的全局对象 if (window.ethereum) { web3 new Web3(window.ethereum); const accounts await window.ethereum.request({ method: eth_requestAccounts }); account accounts[0]; return account; } // 开发回退方案直接连接本地模拟链 RPC web3 new Web3(http://127.0.0.1:8545); const accounts await web3.eth.getAccounts(); if (!accounts.length) { throw new Error(本地链没有可用账户请检查模拟链是否启动); } account accounts[0]; return account; } export function getContractInstance(abi, address) { return new web3.eth.Contract(abi, address); } export function getCurrentAccount() { return account; }逻辑说明window.ethereum 是钱包插件约定俗成的注入名称Web3.js 能直接识别这个对象。eth_requestAccounts 会触发钱包弹窗向用户索要账户授权这一步必须是用户手动点击确认前端无法静默获取地址。回退分支里 new Web3(http://127.0.0.1:8545) 表示走普通 HTTP 的 JSON-RPC这种方式没有签名能力只适合本地测试读取数据或发起无签名交易。参数说明initWeb3 返回的 account 是当前连接账户的首个地址格式是形如 0x 开头的 42 位十六进制字符串。getContractInstance 接收合约 ABI 和合约部署地址ABI 来自编译产物的 abi 字段地址来自部署脚本打印出来的 deploy 输出。把这两个参数留在外部传入是为了方便切换测试网和本地链不需要改动工具函数本身。3.3 IPFS 上传与哈希上链先拿 CID再发交易IPFS 上传的核心库是 ipfs-http-client它会通过 HTTP API 和本地 IPFS 守护进程通信。上传成功后返回的不是一个字符串而是一个包含 CID 对象的复杂结构必须调用 .toString() 才能拿到存证用的哈希。这一步是很多新手掉坑的地方因为它拿到的结果在 console.log 里看起来很像字符串实际却是一个对象。import { create } from ipfs-http-client; const ipfs create({ url: http://127.0.0.1:5001 }); export async function uploadFileToIpfs(file) { const fileBuffer await file.arrayBuffer(); const result await ipfs.add( { path: file.name, content: Buffer.from(fileBuffer) }, { pin: true } ); return result.cid.toString(); } export async function uploadMetadataToChain(cid, file) { const contract getContractInstance(abi, contractAddress); const from getCurrentAccount(); const tx await contract.methods .uploadFile(file.name, cid, file.size) .send({ from }); return tx.transactionHash; }逻辑说明uploadFileToIpfs 先通过 file.arrayBuffer() 拿到文件二进制数据再包成 Buffer最后交给 ipfs.add。第二个参数 { pin: true } 让节点保留这份内容防止垃圾回收。uploadMetadataToChain 使用之前封装的 getContractInstance 拿到合约实例调用 uploadFile 方法并发送交易。send({ from }) 会触发钱包弹窗用户确认后返回一个交易收据收据里有 transactionHash。参数说明cid 是 IPFS 内容标识符它是文件的加密哈希不包含文件内容本身。file.size 是文件字节数这个值要和合约里记录的 _fileSize 保持一致。send 方法的事务选项里只传了 fromgas 值我不手动指定让钱包和节点自动估算。手动写死一个过高的 gasLimit 在本地链上可能没问题换成公共测试网会白白浪费测试币这是我之前翻车换来的经验。4. 运行与调试从空目录开始跑通一次链上上传拿到源码后最容易卡住的不是写业务逻辑而是环境之间没有对齐。下面是我整理出的四步启动顺序每一步都会产生可验证的结果照着做不至于跑到一半不知道在哪看日志。4.1 准备本地 IPFS 节点与模拟区块链环境我假设你的机器已经装好了 Node.js 环境。先把项目依赖装全React 和 Web3.js 都从 npm 拉取IPFS 客户端库用 ipfs-http-client编译合约用 solc。npm init -y npm install react react-dom web3 ipfs-http-client solc npm install -D babel/core babel/preset-env babel/preset-react babel-loader webpack webpack-cli webpack-dev-server html-webpack-plugin安装完成后启动 IPFS 节点。IPFS 命令行工具初始化后会默认生成存储目录daemon 子命令启动守护进程默认监听 5001 端口这个端口就是 ipfs-http-client 的默认入口。ipfs init ipfs daemon看到类似“API listening on /ip4/127.0.0.1/tcp/5001”的日志说明 IPFS 就绪了。接下来启动本地模拟区块链这一步没有固定命令因为不同开发链工具的启动方式不一样。我的做法是让模拟链监听 127.0.0.1:8545并把链 ID 固定为 1337同时打开自动挖矿模式。自动挖矿保证每笔交易都能快速被打包手动挖矿模式下交易会一直 pending。注意两个节点必须同时保持运行。IPFS 负责内容寻址模拟链负责合约执行任何一个挂了对应的调用都会直接超时。前端报错时先不要急着改代码看一眼这两个终端窗口是否还活着能省下不少排查时间。4.2 编译部署合约拿到 ABI 与合约地址编译合约我用的是 solc 的 JavaScript 版本脚本读取 contracts/FileStorage.sol把编译产物里的 ABI 和字节码写到 src/contracts/FileStorage.json。这样做的好处是前端和部署脚本可以共用同一个编译产物避免手工复制 ABI 导致两端对不上。const fs require(fs); const solc require(solc); const source fs.readFileSync(contracts/FileStorage.sol, utf8); const input { language: Solidity, sources: { FileStorage.sol: { content: source } }, settings: { outputSelection: { *: { *: [abi, evm.bytecode.object] } } } }; const output JSON.parse(solc.compile(JSON.stringify(input))); const contract output.contracts[FileStorage.sol][FileStorage]; const build { abi: contract.abi, bytecode: contract.evm.bytecode.object }; fs.writeFileSync(src/contracts/FileStorage.json, JSON.stringify(build, null, 2));运行 node scripts/compile.js 后src/contracts/FileStorage.json 会多出来。紧接着执行部署脚本部署逻辑是先连接本地链的 8545 端口取第一个测试账户用编译产物里的字节码发布合约。node scripts/deploy.js如果一切顺利终端会打印“Contract deployed at”加一个合约地址。把这个地址填到 src/config.js 的 contractAddress 字段里。这里我吃过一次亏部署成功之后前端还是空白找半天才发现前端 config.js 里的地址还是旧合约的重跑部署后忘记覆盖。从那以后我每次重新部署第一件事就是把新地址同步到前端配置。4.3 启动前端并在浏览器里完成第一次上传验证前端启动方式取决于你的构建工具本质上是起一个开发服务器打包 React 组件。启动后浏览器打开对应端口页面会先显示一个连接钱包按钮。点击按钮后如果模拟链和钱包插件配置正确页面会显示当前账户地址。这时上传一个文本文件观察三个地方的输出浏览器控制台、模拟链终端、IPFS 节点终端。浏览器控制台会打印上传文件的 CID 和交易哈希模拟链终端会出现一条交易记录IPFS 节点终端会输出“stored”之类的接收日志。三者都出现说明上传链路是通的。验证下载时我习惯把合约里取到的 CID 复制出来直接拼上本地 IPFS 网关地址访问一次。网关默认监听 8080 端口URL 格式是 http://127.0.0.1:8080/ipfs/ 能正常下载说明文件没有被垃圾回收。如果上传结束后文件列表没有刷新最常见的原因是前端轮询间隔太短交易还没确认就读取合约。我在代码里把轮询间隔设成 2 秒并判断返回的文件数量是否比之前多避免较早之前出现过的“列表迟迟不更新”假死现象。完成这一步验证整个项目核心流程就算跑通了。5. 避坑与排查本地跑分布式存储最容易翻车的五个点这个项目看起来模块不多但分布式系统的坑往往不在代码逻辑而在环境之间的互相等待。下面的五条都是我实际踩过、再回头排查记录下来的按现象、原因、解决的顺序讲透。5.1 钱包一直转圈链 ID 与网络配置对不上现象点击连接钱包后弹窗一直停在“等待确认”或者连接成功但交易发起后没有任何反应。前端代码没有任何报错模拟链终端也不见交易进来。原因钱包插件当前选择的网络是某条公共测试网而不是本地模拟链。交易被广播到了错误的网络本地节点自然收不到。即使钱包能手动加网络如果链 ID 和模拟链不一致也会出现同样的沉默现象。解决在钱包插件的自定义网络设置里添加本地模拟链RPC URL 填 http://127.0.0.1:8545链 ID 填 1337与模拟链启动参数保持一致。启动模拟链时不要用默认随机链 ID显式固定成 1337钱包配置写死。这样每次重启开发环境网络配置都不会漂移。5.2 合约部署成功但前端读不到文件列表现象部署脚本正常打印合约地址前端连接钱包也成功但文件列表一直是空数组控制台偶尔出现“call returned undefined”的提示。原因前端代码里读取的是旧合约地址或者 ABI 文件没有随合约更新重新编译。合约地址填错时前端指向的是一个不存在或已废弃的合约调用当然拿不到有效数据。解决把合约地址集中放在 src/config.js 一个文件里部署脚本每跑一次就同步替换一次。再把编译、部署、启动前端这三条命令串成一个 npm script例如 npm run build:contract 之后自动复制地址。这个流程看起来繁琐却能把最隐蔽的版本问题从源头杜绝。5.3 IPFS 文件隔天就拉不下来现象上传当天一切正常第二天打开页面还能看到文件列表但点击下载时 IPFS 网关返回 404提示 File not found。链上的 CID 还在内容却没了。原因本地 IPFS 节点默认会在内容不被引用时执行垃圾回收。上传时如果没有显式固定内容节点清理存储后就会把文件数据丢掉。CID 可以链上永久存在但没有节点保存文件内容就等同于证书在、实物消失。解决ipfs.add 的第二个参数设置 pin: true上传成功后再执行一次 ipfs pin add 。如果使用远程固定服务需要把固定操作放在可靠性更高的节点上不能只依赖本地开发节点。养成上传后立刻验证下载的习惯能及时发现固定失效。5.4 交易确认一直 pending上传按钮反复 loading现象钱包已经弹窗确认但交易在本地链上迟迟没有打包含块前端一直停在 loading 状态甚至超时抛错。原因本地模拟链被切成了手动挖矿模式交易只进入交易池需要手动触发挖矿才会打包。或者代码里给交易写死了不合理的 gasLimit导致节点认为交易参数异常。解决把模拟链切回到自动挖矿模式每个交易进入后自动打包。前端代码里不要写死 gas 参数send({ from }) 里只传必要的 fromgas 交给 Web3.js 和节点估算。本地链若做不到自动挖矿需要写脚本在发送交易后手动触发一次挖矿才能推动交易确认。5.5 改完合约后前端提示方法未定义现象在合约里新增了一个查询接口编译部署都成功但前端调用 instance.methods.newMethod() 时报错 newMethod is not a function。原因前端加载的 ABI 还是旧版本。合约没有重编译或者重编译后 ABI 文件没有同步到前端目录。ABI 是前端理解合约接口的唯一凭据两端只要有一个不是最新版就会出现这类错位。解决约定一个硬性顺序先 node scripts/compile.js再 node scripts/deploy.js最后启动前端。每次只改合约不改流程基本不会遇到这个问题。我后来在 compile.js 里加了 md5 校验编译产物变化时自动弹出提示从机制上防住旧 ABI。6. 二次开发思路给文件分享加一个固定链接和软删除跑通原始版本后我第一件想做的事是补上“分享”和“删除”两个体验短板。链上数据不可篡改删除并不是真的把文件抹掉而是做软删除。我在合约里已经留了 exists 字段前端读取列表时过滤掉 exists 为 false 的记录对用户来说文件就像被删除了但链上历史依然保留存证逻辑不受影响。改造时只需要在合约里增加一个 setFileDeleted(uint256 _id) 方法要求调用者必须是该文件的 uploader满足条件才把 exists 置为 false接口语义非常清楚。分享功能不需要动合约直接利用 IPFS 网关。每条记录里都有 CID组装成固定链接放到文件列表的操作列const shareUrl http://127.0.0.1:8080/ipfs/${file.cid}; async function handleCopy(file) { await navigator.clipboard.writeText(shareUrl); }这个链接的优点是天然去中心化只要内容在任意 IPFS 节点被固定复制链接的人都能访问。缺点是没有权限控制知道 CID 就等于能拿文件所以适合公开资料分享。想要私密分享就把文件在浏览器里用对称密钥加密后再上传密钥通过私下渠道单独发送链上只保存加密后的 CID别人拿不到密钥就看不了内容这才是分布式网盘补全隐私的最短路径。我还建议在 FileList 组件里加一层加载状态控制因为涉及 IPFS 网关的下载和合约读取是两条不同的网络链路慢的那一端会成为整个页面的瓶颈。把“列出文件”和“下载文件”拆成两个独立请求列表先渲染下载链接随后填充体验会顺畅很多。做这些改造时我一直守着那条血泪教训区块链交易的不可逆性决定了修改前必须先在本地链完整验证一遍。从那以后我每次改合约都会强制走一遍“重编译、重部署、同步地址、连接钱包、测试上传下载”五步流程确认无误再想上线的事。希望帮到你。本文还有配套的精品资源点击获取

基于IPFS与以太坊的去中心化文件存证平台实战

相关推荐

PGD对抗训练实战：从数学原理到鲁棒模型调参避坑指南

贾子理论：拆解AI实验室全员大会的三层信号模型

C++数据结构与算法课后练习刷题指南：环境搭建、解题套路与验证方法

更多资讯

鸿蒙录音实时转文字：音频流采集与流式语音识别实战

Strassen矩阵乘法：Python实现、分治优化与性能分析

论文格式总错？AI写作工具用“样式驱动”重构目录与参考文献

宝塔面板安装教程：从零搭建LNMP环境与安全配置

QC 2.0 快速充电接口控制器D1531

Activiti运行表ACT_RU_VARIABLE深度解析：变量作用域与存储机制

今日更新

NetSpot 实战：用信道分析与频宽优化解决 Wi-Fi 卡顿

C++ split() 字符串分割的五种实现与性能实测

R语言坐标轴范围设置：从xlim/ylim到coord_cartesian的完整指南

本周精选

交通拥堵预测毕设：基于Python+LSTM的车辆流量预测系统全流程解析

MATLAB/Simulink搭建10机39节点电力系统暂态稳定仿真实战

无人机航拍三维重建全流程：从SfM到网格生成的避坑指南

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？