零门槛搭建可落地区块链档案溯源系统 手把手实操指南

一、前置准备（5分钟完成）

1.1 安装基础工具

只需安装两个工具，全部默认安装即可，无复杂配置：

• Node.js 18.x版本：Windows直接下载安装包 https://nodejs.org/dist/v18.17.0/node-v18.17.0-x64.msi，Mac用户执行终端命令：brew install node@18
• Git工具：Windows下载地址 https://git-scm.com/download/win，Mac系统自带Git无需额外安装

安装完成后打开命令提示符（CMD），执行以下命令验证安装：

``` node -v git --version ```

如果输出对应版本号，说明安装正确，可进入下一步。

二、拉取代码与基础配置（3分钟完成）

2.1 拉取开源溯源模板代码

打开CMD，进入你要存放项目的目录，比如D盘根目录，执行以下命令：

``` cd D: git clone https://github.com/WeBankBlockchain/FileTrace-Demo.git cd FileTrace-Demo ```

2.2 安装项目依赖

直接执行npm命令安装所有依赖，国内用户建议切换淘宝源加速：

``` npm install --registry=https://registry.npmmirror.com ```

等待依赖安装完成，无红色报错即可进入下一步。

2.3 配置区块链节点（无需自己搭建节点，直接用免费公共测试节点）

打开项目根目录下的src/config.js文件，直接替换为以下完整可运行配置：

``` export default { chainId: 1024, rpcUrl: "https://rpc.ankr.com/bcos_testnet", contractAddress: "0x5f7ad61cF6341f87B8605d5a3760967982219B89", ipfsUrl: "https://ipfs.infura.io:5001" } ```

以上配置使用免费的FISCO BCOS测试网公共节点和IPFS存储服务，不需要自己搭建节点和存储服务，可直接使用。

三、启动系统验证（1分钟完成）

在项目根目录执行启动命令：

``` npm run dev ```

命令执行完成后，打开浏览器访问 http://localhost:5173，即可看到区块链档案溯源系统的首页，说明系统搭建成功。

四、核心功能实操（可直接上手使用）

4.1 上传档案生成上链溯源记录

1. 点击首页的【上传档案】按钮，选择需要上链的档案文件，支持PDF、图片、Word等所有常见格式，单文件不超过10MB
2. 填写档案基础信息：档案名称、档案创建时间、责任主体，所有信息上链后不可篡改，填写前请核对准确
3. 点击【确认上链】按钮，等待10-30秒，系统会自动生成档案的唯一哈希，将哈希存入区块链，原文件加密存储到IPFS，最终生成唯一的溯源哈希码。

4.2 档案溯源验证操作

1. 回到首页，在溯源查询框输入已经上链的档案溯源哈希码
2. 点击【查询验证】按钮，系统会自动对比区块链上存储的原始档案哈希和当前档案哈希
3. 如果页面显示验证通过，档案未被篡改，说明当前档案是原始未修改版本；如果显示验证不通过，说明档案已经被篡改。

五、对接自有业务改造（可选）

如果需要对接企业自有档案系统，只需要修改两个核心部分即可：

5.1 修改存储配置

如果不想使用公共IPFS存储，可以把config.js里的ipfsUrl改成自有存储服务地址，档案原始哈希仍然存储在区块链，保证不可篡改。

5.2 新增自定义业务字段

打开项目下的src/components/UploadForm.vue文件，找到表单定义部分，直接新增需要的业务字段，比如档案编号、归档部门、保管期限等，修改保存后刷新页面自动生效。

5.3 部署到公网对外提供服务

如果需要对外提供服务，执行打包命令生成静态文件：

``` npm run build ```

打包完成后，把生成的dist目录下的所有文件上传到你的静态文件服务器（比如Nginx、Vercel、阿里云OSS）即可通过公网访问。

常见问题解决

• 依赖安装失败：删除项目下的node_modules目录和package-lock.json，重新执行npm install --registry=https://registry.npmmirror.com
• 上链超时：更换网络节点，把config.js里的rpcUrl改成https://bcos-testnet.rpcblockchain.com即可
• 端口5173被占用：打开项目根目录的vite.config.js，新增配置server: { port: 8080 }，重启项目即可。