市级机关数字档案馆接入档案联盟链全流程实操指南

一、前期准备：必备条件与资源

本次基于国内政务通用的FISCO BCOS联盟链底层（2.9.1稳定版）和「国家档案局数字档案馆区块链应用试点通用接口」完成，需提前准备以下资源：

• 1台或2台配置≥4核8G、50G SSD、Ubuntu 20.04 LTS的云服务器/物理机（单台用于链节点+网关，双台可做节点主备）
• 已部署完成的符合《数字档案馆系统测试办法》的市/区县级机关数字档案馆系统（需预留API对接端口）
• 国家档案局试点通用接口的权限申请文档（无需试点资质也可测试通用Demo链）
• 已注册的公钥基础设施（PKI）证书（个人测试可使用链内置的CA签发）

二、FISCO BCOS联盟链节点部署（通用Demo链环境）

2.1 安装基础依赖

登录服务器，切换到root用户，执行以下命令：

```bash 更新软件源 apt update && apt upgrade -y 安装Git、OpenSSL、Curl、Java 8 apt install git openssl curl openjdk-8-jdk -y 配置Java环境变量 echo 'export JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64' >> ~/.bashrc echo 'export PATH=$PATH:$JAVA_HOME/bin' >> ~/.bashrc source ~/.bashrc ```

2.2 下载并启动FISCO BCOS Demo链

执行官方一键部署脚本：

```bash cd ~ git clone https://github.com/FISCO-BCOS/FISCO-BCOS.git cd FISCO-BCOS git checkout v2.9.1 cd tools bash build_chain.sh -l "127.0.0.1:4" -p 30300,20200,8545 启动链节点 cd nodes/127.0.0.1/ bash start_all.sh 验证链是否启动成功 bash check.sh ```

若输出所有节点（node0-node3）状态为Alive，说明部署完成。

三、安装部署档案区块链应用网关

3.1 下载网关Demo包

网关Demo基于Spring Boot开发，包含数字档案馆对接通用接口，执行以下命令：

```bash cd ~ git clone https://github.com/FISCO-BCOS/archive-chain-gateway-demo.git cd archive-chain-gateway-demo git checkout v1.0.0 ```

3.2 配置网关连接链节点

编辑配置文件src/main/resources/application.yml，以下为完整可复制配置：

```yaml server: port: 8081 网关对外暴露的端口 spring: application: name: archive-chain-gateway fisco: bcos: 链节点配置，注意路径要和部署的链一致 group-id: 1 channel-access-key: "" 节点连接列表，默认部署4个通道节点 nodes: - 127.0.0.1:20200 - 127.0.0.1:20201 - 127.0.0.1:20202 - 127.0.0.1:20203 链证书路径 cert-path: /root/FISCO-BCOS/tools/nodes/127.0.0.1/sdk/ 合约地址，首次部署后需替换 contract: archive-contract-address: "" ```

3.3 部署档案存证、验证智能合约

网关Demo内置了符合档案局要求的存证、验证合约，执行部署脚本：

```bash cd ~/archive-chain-gateway-demo bash deploy_contract.sh ```

部署成功后会输出archive-contract-address，将其复制到application.yml中替换空值。

3.4 启动网关

编译并启动Spring Boot应用：

```bash mvn clean package -DskipTests java -jar target/archive-chain-gateway-1.0.0.jar & 验证网关是否启动成功 curl http://127.0.0.1:8081/actuator/health ```

若输出{"status":"UP"}，说明网关运行正常。

四、机关数字档案馆系统对接配置

4.1 配置对接IP与端口

在数字档案馆系统的「系统配置-区块链对接」页面，填写以下信息：

• 区块链网关地址：http://网关服务器IP:8081
• 对接超时时间：10秒
• 重试次数：3次

4.2 数字档案元数据/电子文件哈希值映射

需在数字档案馆系统中配置「归档触发-自动上链」规则，映射上链字段（符合档案局通用接口要求）：

• 上链主体：机关全称+统一社会信用代码
• 档案唯一标识：档号
• 电子文件哈希值算法：SHA-256
• 电子文件哈希值：系统自动计算
• 归档时间：系统自动获取
• 档案密级：公开/内部/秘密/机密（机密及以上需符合涉密信息系统要求，本次不涉及）

4.3 测试上链存证接口

使用Postman或curl工具测试上链接口，接口地址为http://网关服务器IP:8081/api/archive/save，请求方式为POST，请求头为Content-Type: application/json，请求体示例：

```json { "subject": "XX市人民政府办公室+123456789012345678", "archiveId": "XX府办〔202X〕001号", "hashAlgorithm": "SHA-256", "fileHash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2", "archiveTime": "202X-01-01T00:00:00+08:00", "securityLevel": "公开", "extension": "{\"归档人\":\"张三\",\"保管期限\":\"永久\"}" } ```

请求成功后会返回交易哈希（txHash），可通过FISCO BCOS的区块链浏览器（首次需手动部署，或使用链内置的getTxByHash接口查询）验证存证内容。

五、验证已上链档案的真实性

验证接口地址为http://网关服务器IP:8081/api/archive/verify，请求方式为POST，请求头同存证接口，请求体仅需提供archiveId和fileHash，示例：

```json { "archiveId": "XX府办〔202X〕001号", "fileHash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2" } ```

若返回{"code":200,"msg":"验证成功","data":true}，说明电子文件未被篡改；若返回false，说明电子文件哈希值与链上不一致。

六、常见问题排查

• 链节点无法启动：检查端口30300-30303、20200-20203、8545-8548是否被占用，执行lsof -i :端口号查看进程并kill
• 网关无法连接链节点：检查application.yml中的cert-path和nodes配置是否正确，确保链证书与节点在同一台服务器或已同步到网关服务器
• 上链失败：检查请求体中的字段是否完整，hashAlgorithm是否为SHA-256，fileHash是否为64位十六进制字符串