11. 归档中心使用文档

11.1. 整体流程

  1. 启动归档中心服务

  2. 使用cmc归档链上数据到归档中心服务

  3. 使用扫描工具,扫描链上已归档的数据文件.根据扫描结果转移(需要人工)或删除(使用清理模式)已归档文件

  4. 使用sdk查询已经归档数据

11.2. 归档中心服务的安装,配置和运行

11.2.1. 环境依赖

  • linux 系统,开启mmap

  • golang 1.16+

  • 7zip压缩工具

    • centos下安装: sudo yum -y install p7zip p7zip-plugins

    • ubuntu下安装: sudo apt install p7zip-full

11.2.2. 版本对应关系

链
chainmaker-go		 归档中心服务
chainmaker-archive-service		 CMC工具
chainmaker-go		 SDK-Go SDK-Java
v2.3.0 v1.0.0_alpha v2.3.0_archive_alpha v2.3.0_archive_alpha v2.3.0_archive_alpha
v2.2.1 v1.0.0_alpha v2.2.1_archive_alpha v2.2.1_archive_alpha v2.2.1_archive_alpha

11.2.3. 设计方案详见

11.2.4. 下载chainmaker-archive-service源码

git clone  --depth=1 https://git.chainmaker.org.cn/chainmaker/chainmaker-archive-service.git
git checkout v1.0.0_alpha

11.2.5. 编译源代码:

cd chainmaker-archive-service/src   
go build -o chainmaker-archive-service

11.2.6. 服务配置

  • 整体配置概览

├── configs # 归档中心服务配置文件夹
│   ├── config.yml # 归档中心服务配置
│   ├── server_cert # 如果开启GRPC的TLS,下面配置有效.为归档中心的证书和私钥
│   │   ├── archive-server.key # 归档中心的私钥
│   │   └── archive-server.pem # 归档中心的证书
│   └── trust_list # 如果开启了GRPC的TLS,为连接归档中心的CMC所使用的根证书
│       └── baec-client-root.pem # 签发CMC的根证书

  • config.yml 服务配置文件说明

# Logger settings
log: # 日志配置 
  # Logger configuration file path.
  log_path: ../log # 日志输出的根路径  
  log_level: debug 
  log_in_console: false
  show_color: true
  max_size: 200 # MB
  max_backups: 3 
  max_age: 3 # day 
  compress: false
# api server setting 

http: # http服务配置
  port: 13119  
  ratelimit:
    # Ratelimit switch. Default is false.
    enabled: false

    # Rate limit type
    # 0: limit globally, 1: limit by ip
    type: 0

    # Token number added to bucket per second.
    # -1: unlimited, by default is 10000.
    token_per_second: -1

    # Token bucket size.
    # -1: unlimited, by default is 10000.
    token_bucket_size: -1

  white_list: # 白名单配置
    enabled: false 
    address:
      - 127.0.0.1      

# RPC service setting
rpc: # grpc 服务配置 
  # RPC port
  port: 13120 # grpc port    

  # Rate limit related settings
  # Here we use token bucket to limit rate.
  ratelimit:
    # Ratelimit switch. Default is false.
    enabled: false

    # Rate limit type
    # 0: limit globally, 1: limit by ip
    type: 0

    # Token number added to bucket per second.
    # -1: unlimited, by default is 10000.
    token_per_second: -1

    # Token bucket size.
    # -1: unlimited, by default is 10000.
    token_bucket_size: -1

  white_list: # rpc接口白名单配置
    enabled: false 
    address:
      - 127.0.0.1  
  tls_enable : false  # 只有使用RPC的TLS的时候才设置为true，其余为false 
  # RPC TLS settings
  tls: # RPC的TLS配置 
    # RPC TLS private key file path
    priv_key_file:  ../configs/server_cert/archive-server.key # 私钥
    # RPC TLS public key file path
    cert_file:      ../configs/server_cert/archive-server.pem # 证书
    trust_ca_list: # 可调用RPC端的签发根证书  
     # - ../configs/trust_list/archive-client.pem
      - ../configs/trust_list/baec-client-root.pem
     # - "configs/trust_list/ca1.ca"
     # - "configs/trust_list/ca2.ca"

  # RPC server max send/receive message size in MB
  max_send_msg_size: 200
  max_recv_msg_size: 200  


# Monitor related settings
monitor: # prometheus 监控配置
  # Monitor service switch, default is false.
  enabled: false

  # Monitor service port
  port: 13122

# PProf Settings
pprof: # golang的pprof配置   
  # If pprof is enabled or not
  enabled: false

  # PProf port
  port: 13123

# Storage config settings
storage_template:
  # 存储系统信息
  store_path: ../service_datas/system_info  
  # 存储链的block信息
  bfdb_path: ../service_datas/block_data
  # 存储链的索引信息
  index_path: ../service_datas/index_data
  # 存储链的压缩信息
  compress_path: ../service_datas/compress_data
  # 存储链的解压缩信息 
  decompress_path: ../service_datas/decompress_data

  # async write block in file block db to disk, default: false, so default is sync write disk
  logdb_segment_async: false # 是否异步写入,false的时候不会丢数据；

  # file size of .fdb, MB, default: 20
  logdb_segment_size: 32 # 归档中心存储区块文件的单个文件大小限制,可以与链配置一致  

  segment_cache_size: 10  # 系统读文件时同时保留的最大文件句柄数目

  use_mmap: true  # 操作系统需要支持mmap
  # 扫描已经解压或已经压缩的文件列表的时间间隔,单位为秒
  scan_interval_seconds: 300
  # 最大保留已解压或已压缩文件的时长  ,单位为秒.系统按照 scan_interval_seconds频率扫描已压缩或解压缩的文件,发现该文件上次读取时间与当前时间间隔大于retain_seconds,则删除该文件(节省磁盘空间)
  retain_seconds: 3600
  # compress_method: 7z # 7z or gzip
  compress_seconds: 2000 # 单位为秒,压/解压缩超时时间,配置与logdb_segment_size 的大小有关系,文件大小越大,这个值设置的越大.
  leveldb_config: # leveldb的配置,
    bloom_filter_bits: 10

11.2.7. 启动/停止归档中心服务

  • 启动服务:

nohup ./chainmaker-archive-service > service.log 2>&1 &

  • 记录服务生成的token到server_token. token用于调用压缩归档中心数据和管理证书的接口使用

grep token ../log/processor.log

  • 停止服务

# 查询归档中心服务进程
ps -ef | grep chainmaker-archive-service
# 停止服务
kill -9 [processid]

11.3. 使用CMC工具归档链上数据到归档中心服务

11.3.1. 下载支持CMC归档中心的源码

git clone -b v2.3.0_archive_alpha --depth=1 https://git.chainmaker.org.cn/chainmaker/chainmaker-go.git

11.3.2. 编译CMC工具:

cd tools/cmc
go build -o cmc

11.3.3. CMC支持归档中心配置概览:

  • 配置概览: 如果GRPC开启了TLS验证,key和pem才有用,否则无用

├── archivecenter
│   ├── archive-client.key # Grpc调用客户端的私钥   
│   ├── archive-client.pem # Grpc调用客户端的证书  
│   ├── baec-root.pem # 如果归档中心服务GRPC开启了TLS,这个是签发归档中心服务证书的根证书
│   ├── config.yml # 归档中心配置文件
├── cmc # CMC可执行文件
├── main.go # CMC源码入口文件

  • config.yml文件解析:

chain_genesis_hash: bdaeaa2b435ad98d553019d1455234c4dd6341671018fd571b5498d68eacd7b5 #归档的链的块高为0的区块hash(hex编码)
rpc_address: 127.0.0.1:13120 #归档中心rpc服务地址
archive_center_http_url: http://127.0.0.1:13119 # 归档中心http服务地址,非必要
request_second_limit: 10 # 归档中心http请求超时时间,秒单位
tls_enable: false # 归档中心是否启用grpc的tls
tls: # 不开启grpc的tls的时候,如下配置可忽略
  server_name: baec-archive # 归档中心tls服务注册的名称
  priv_key_file: ./archivecenter/archive-client.key # cmc侧做tls的私钥
  cert_file: ./archivecenter/archive-client.pem # cmc侧做tls的证书
  trust_ca_list:
    - ./archivecenter/baec-root.pem # 归档中心服务根证书
max_send_msg_size: 200 # grpc 发送最大消息(MB为单位)
max_recv_msg_size: 200 # grpc 接收最大消息(MB为单位)

其中创世块chain_genesis_hash的获取可以采用如下步骤:

# 首先使用cmc从链上查询创世块的blockhash
./cmc query block-by-height 0 \
--sdk-conf-path './testdata/sdk_config.yml' 
# 调用归档中心http接口,获取hex编码的genesis_block_hash,其中[blockhash]即为上面cmc查询出来的base64编码的hash
curl -X POST 'http://127.0.0.1:13119/get_hashhex_by_hashbyte' -d '{"block_hash": [blockhash]}'

11.3.4. 使用CMC工具归档数据

# 归档链上 区块块高的1-100的数据 ,使用quick模式进行归档
./cmc archivecenter dump  \ 
--sdk-conf-path ./testdata/sdk_config.yml \ 
--chain-id chain1 \ 
--archive-conf-path ./archivecenter/config.yml \
--archive-begin-height 1 \
--archive-end-height 100 \
--mode quick 

# 也可以使用如下命令进行归档,速度较慢
# 归档链上 区块块高的1-100的数据 ,使用normal模式进行归档
./cmc archivecenter dump \
--sdk-conf-path ./testdata/sdk_config.yml \
--chain-id chain1 \
--archive-conf-path ./archivecenter/config.yml \
--archive-begin-height 1 \
--archive-end-height 100 \
--mode normal

11.3.5. 使用CMC工具归档数据,到归档中心查询已归档数据命令 (非必要步骤,可以跳过)

# cmc查询归档中心当前已归档数据状态命令
./cmc archivecenter  query archived-status \
--archive-conf-path archivecenter/config.yml 

# cmc查询归档中心,根据高度查区块命令
./cmc archivecenter query block-by-height 20 \
--archive-conf-path ./archivecenter/config.yml

# cmc查询归档中心,根据tx查询区块命令
./cmc archivecenter query block-by-txid [txid] \
--archive-conf-path ./archivecenter/config.yml

# cmc查询归档中心,根据tx查询事务命令
./cmc archivecenter query tx [txid] \
--archive-conf-path ./archivecenter/config.yml  

# cmc查询归档中心,根据hash查询区块命令
./cmc archivecenter query block-by-hash [blockhash] \
 --archive-conf-path ./archivecenter/config.yml

11.4. 使用扫描工具扫描区块数据

扫描工具是一个可执行文件,可以根据配置来扫描链节点的文件数据,进而进行清理.当前版本的归档方案未改造链本身的代码,使用了扫描工具这个临时方案,来清理区块文件数据. 到2.3.2版本的时候会在cmc工具中增加一个清理数据的功能,清理数据后,可以直接从链上查询已经归档的高度

11.4.1. 下载归档中心chainmaker-archive-service源码

git clone  --depth=1 https://git.chainmaker.org.cn/chainmaker/chainmaker-archive-service.git 
git checkout v1.0.0_alpha

11.4.2. 编译扫描工具

cd bfdb-clean-tools
go build

11.4.3. 将扫描工具拷贝到链节点所在的服务器的某路径下

cp bfdb-clean-tools /[path]
cp config.yml /[path]

11.4.4. 配置扫描工具

  • 整体描述: 扫描工具有两种工作模式:

    • 模式1(mode 为 1): 扫描工具执行会扫描所有区块高度小于等于配置中clean_height的区块文件,并输出命名规则为stub[year][month][day][hour][minute][second].csv文件

    • 模式2(mode 为 2): 扫描工具会根据配置中的clean_stub文件中所有标为’y’的记录进行删除对应的区块文件(如果不打算删除区块文件,则不用使用模式2),删除后将删除的每一个文件名作为一行写入到文件clean_stub.result作为存根

  • 配置概览:

├── bfdb-clean-tools
│   ├── bfdb-clean-tools # 清理工具可执行文件  
│   ├── config.yml # 清理工具配置文件
│   ├── main.go # 清理工具源码入口
│   ├── stub20221021151245.csv # 扫描区块数据生成的文件
│   ├── stub20221021151245.csv.result # 根据上面生成的文件删除区块文件后生成的存根

  • config.yml文件解析:

log: # 清理文件输出的日志配置,可忽略
  # Logger configuration file path.
  log_path: ./log 
  log_level: info   
  log_size: 100
  log_age: 30
  log_num: 100
bfdb_path: ./bfdb # 区块链节点存储区块bfdb文件的根文件夹目录
mode: 1 # 1 为输出清理信息模式; 2 为根据输出的清理信息,做文件清理；默认为1 
clean_stub: ./stub20221021151245.csv # mode为2的时候,有意义. 根据这个配置删除所有csv中标记为y的区块链节点文件
clean_height: 11120000 # mode为1的时候有意义. 已经归档到归档中心的高度(可以清理的区块的最大高度),工具会扫描解析这个高度下所有的区块文件,输出CSV. 
archive_center_config:
  chain_genesis_hash: 5b29b0a67c529352c0e3f512a4e8d329f967afcdb580ec76e6d1462d9ac969ec # 待清理链的创世区块hash
  archive_center_http_url: http://127.0.0.1:13119 # 归档中心的http接口地址
  request_second_limit: 10 # 调用归档中心http接口超时时间

11.4.5. 执行扫描工具

  • 扫描信息. 配置mode为1,bfdb_path为节点上存储fdb区块文件的路径,clean_height配置为已经归档的高度(或小于已经归档的高度也可以).执行在同级目录下会生成一个stub*.csv文件

./bfdb-clean-tools

  • 删除链数据. (非必要步骤,可以跳过) 配置mode为2,clean_stub为扫描时生成的csv文件.再次执行

./bfdb-clean-tools

11.5. 使用SDK透明查询区块和交易信息

11.5.1. 下载sdk源码

git clone -b v2.3.0_archive_alpha --depth=1 https://git.chainmaker.org.cn/chainmaker/sdk-go.git

11.5.2. 如果启用了归档中心在sdk的配置文件中增加如下配置:

  archive_center_config:
    chain_genesis_hash: 5b29b0a67c529352c0e3f512a4e8d329f967afcdb580ec76e6d1462d9ac969ec # 归档的链的创世区块的hash
    archive_center_http_url: http://127.0.0.1:13119 # 归档中心的http接口地址
    request_second_limit: 10 # 查询归档中心http请求超时时间

11.5.3. sdk修改的方法列举如下:

  • GetChainConfigByBlockHeight(blockHeight uint64) (*config.ChainConfig, error)

  • GetTxByTxId(txId string) (*common.TransactionInfo, error)

  • GetTxWithRWSetByTxId(txId string) (*common.TransactionInfoWithRWSet, error)

  • GetBlockByHeight(blockHeight uint64, withRWSet bool) (*common.BlockInfo, error)

  • GetBlockByHash(blockHash string, withRWSet bool) (*common.BlockInfo, error)

  • GetBlockByTxId(txId string, withRWSet bool) (*common.BlockInfo, error)

  • GetFullBlockByHeight(blockHeight uint64) (*store.BlockWithRWSet, error)

  • GetBlockHeaderByHeight(blockHeight uint64) (*common.BlockHeader, error)

  • GetMerklePathByTxId(txId string) ([]byte, error)

  • GetBlockByHeightTruncate(blockHeight uint64, withRWSet bool, truncateLength int,truncateModel string)(*common.BlockInfo, error)

  • GetTxByTxIdTruncate(txId string, withRWSet bool, truncateLength int,truncateModel string) (*common.TransactionInfoWithRWSet, error)

11.6. 使用HTTP请求直接调用归档中心服务的接口

  • 接口分为两类:

    • 管理类接口: 压缩已归档数据接口(/admin/compress_under_height)；若开启了GRPC的TLS功能,增加CA证书接口(/admin/add_ca)；这两个接口使用特别的token也就是部署服务时候写入到server_token文件的值

    • 普通查询类接口

  • 归档服务的http接口文档