7. 归档中心使用文档

点击此链接查看归档中心设计方案

7.1. 本文档内容如下

部署方案
启动归档中心服务
使用cmc归档链上数据到归档中心服务
使用sdk查询已经归档数据
FAQ

7.2. `归档中心服务`部署方案

归档中心单实例部署.所有节点可共用一个归档中心服务。一条链可以仅部署一个归档中心。这样部署的优点在于节省存储空间。
归档中心多实例部署.每个节点都可单独部署一个归档中心服务。这样部署的优点在于，各节点数据分离，可以做到查询已经归档数据的高可用。

归档中心单实例部署

归档中心多实例部署

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

7.3.1. 环境依赖

linux 系统,开启mmap
golang 1.16+
7zip压缩工具
- centos下安装: sudo yum -y install p7zip p7zip-plugins
- ubuntu下安装: sudo apt install p7zip-full

7.3.2. 版本对应关系

链 chainmaker-go	归档中心服务 chainmaker-archive-service	CMC工具 chainmaker-go	SDK-Go	SDK-Java
v2.3.3	v1.0.0	v2.3.3	v2.3.4	v2.3.2

7.3.3. 设计方案详见 

7.3.4. 下载chainmaker-archive-service源码

git clone -b v1.0.0 https://git.chainmaker.org.cn/chainmaker/chainmaker-archive-service.git

7.3.5. 部署服务

下载代码后,可以根据代码编译docker镜像使用docker运行归档中心；也可以根据代码编译成二进制可执行文件运行归档中心

7.3.5.1. 编译,使用docker镜像

使用docker镜像,可以自行修改镜像挂载的目录(修改makefile中的MOUNT_PATH变量即可)

make docker-build # 编译docker镜像
make docker-start # 使用编译好的docker镜像启动服务
make docker-stop # 停止docker镜像服务

7.3.5.2. 编译,使用二进制:

make build # 编译归档中心可执行二进制
make start # 启动归档中心服务
make stop # 停止归档中心服务 
 

7.3.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  
  # 存储链的block信息
  bfdb_path: ../service_datas
  # 存储链的索引信息
  index_path: ../service_datas
  # 存储链的压缩信息
  compress_path: ../service_datas
  # 存储链的解压缩信息 
  decompress_path: ../service_datas

  # 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: 128 # 归档中心存储区块文件的单个文件大小限制,可以与链配置一致  

  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 

7.3.7. 记录`归档中心服务`的token

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

cd [log-dir] # 进入配置文件中指定的日志目录
grep token processor.log 

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

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

git clone -b v2.3.3  https://git.chainmaker.org.cn/chainmaker/chainmaker-go.git

7.4.2. 编译CMC工具:

cd tools/cmc
go build -o cmc  

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

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

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

config.yml文件解析:

  archive:
    # 数据归档链外存储相关配置
    # 如果使用了新版本的归档中心,这个地方配置为archivecenter
    type: "archivecenter"  # archivecenter 归档中心, mysql mysql数据库    
    dest: "root:123456:localhost:3306"
    secret_key: xxx
  # # 如果启用了归档中心,可以打开下面的归档中心配置  
  archive_center_query_first: false # 如果为true且归档中心配置打开,那么查询数据优先从归档中心查询;
  archive_center_config:
    chain_genesis_hash: cc94caf0ad4540b28e6b5e0ee10dd6c6375d68d10e912c56875a7139af55f6d0  #归档的链的块高为0的区块hash(hex编码)
    archive_center_http_url: http://127.0.0.1:13119 # 归档中心http服务地址,
    request_second_limit: 10 # 归档中心http请求超时时间,秒单位
    rpc_address: 127.0.0.1:13120 #归档中心rpc服务地址
    tls_enable: false # 不开启grpc的tls的时候,如下配置可忽略
    tls:
      server_name: archiveserver1.tls.wx-org.chainmaker.org # 归档中心tls服务注册的名称
      priv_key_file: ./testdata/archivecenter/archiveadmin1.tls.key  # cmc侧做tls的私钥
      cert_file: ./testdata/archivecenter/archiveadmin1.tls.crt  # cmc侧做tls的证书
      trust_ca_list:
        - ./testdata/archivecenter/ca.crt    # 归档中心服务根证书
    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]}'

7.4.4. 使用CMC工具归档数据

# 归档链上 区块块高的1-100的数据 
./cmc archive dump 100 --sdk-conf-path ./testdata/sdk_config.yml --mode quick

7.4.5. cmc查询归档中心当前已归档数据状态命令

./cmc archive query archived-status --sdk-conf-path ./testdata/sdk_config.yml

7.4.6. cmc查询链上当前已归档数据状态命令

./cmc archive query chain-archived-status --sdk-conf-path ./testdata/sdk_config.yml

7.4.7. cmc查询归档中心,根据高度查区块命令

./cmc archive query block-by-height 20  --sdk-conf-path ./testdata/sdk_config.yml

7.4.8. cmc查询归档中心,根据txId查询区块命令

./cmc archive query block-by-txid 17221b132a25209aca52fdfc07218265e4377ef0099d46a49edfd032001fc2be --sdk-conf-path ./testdata/sdk_config.yml

7.4.9. cmc查询归档中心,根据txId查询交易命令

./cmc archive query tx 17221b132a25209aca52fdfc07218265e4377ef0099d46a49edfd032001fc2be  --sdk-conf-path ./testdata/sdk_config.yml

7.4.10. cmc查询归档中心,根据block hash查询区块命令

./cmc archive query block-by-hash 17221b132a25209aca52fdfc07218265e4377ef0099d46a49edfd032001fc2be --sdk-conf-path ./testdata/sdk_config.yml

7.4.11. cmc清理链上区块数据命令

./cmc archive archive 10000 --timeout 20 --sdk-conf-path ./testdata/sdk_config.yml 

7.4.12. restore 恢复链上区块数据命令,恢复到指定高度,恢复过程按照区块块高倒序恢复

./cmc archive restore 3000 --timeout 20 --sdk-conf-path ./testdata/sdk_config.yml 

7.5. 使用`SDK`透明查询区块和交易信息

7.5.1. 下载sdk源码

git clone -b v2.3.4 https://git.chainmaker.org.cn/chainmaker/sdk-go.git

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

  archive:
    # 数据归档链外存储相关配置
    # 如果使用了新版本的归档中心,这个地方配置为archivecenter
    type: "archivecenter"  # archivecenter 归档中心, mysql mysql数据库    
    dest: "root:123456:localhost:3306"
    secret_key: xxx
  # # 如果启用了归档中心,可以打开下面的归档中心配置  
  archive_center_query_first: true # 如果为true且归档中心配置打开,那么查询数据优先从归档中心查询 
  archive_center_config:
    chain_genesis_hash: cc94caf0ad4540b28e6b5e0ee10dd6c6375d68d10e912c56875a7139af55f6d0  #归档的链的块高为0的区块hash(hex编码)
    archive_center_http_url: http://127.0.0.1:13119 # 归档中心http服务地址,
    request_second_limit: 10 # 归档中心http请求超时时间,秒单位
    rpc_address: 127.0.0.1:13120 #归档中心rpc服务地址
    tls_enable: false # 不开启grpc的tls的时候,如下配置可忽略
    tls:
      server_name: archiveserver1.tls.wx-org.chainmaker.org # 归档中心tls服务注册的名称
      priv_key_file: ./testdata/archivecenter/archiveadmin1.tls.key  # cmc侧做tls的私钥
      cert_file: ./testdata/archivecenter/archiveadmin1.tls.crt  # cmc侧做tls的证书
      trust_ca_list:
        - ./testdata/archivecenter/ca.crt    # 归档中心服务根证书
    max_send_msg_size: 200  # grpc 发送最大消息(MB为单位)
    max_recv_msg_size: 200 # grpc 接收最大消息(MB为单位)

7.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)

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

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

7.7. FAQ

Q:归档中心和链节点必须一一对应吗?
A: 归档中心不必和节点一一对应.归档中心可以归档(也即存储)任意节点的数据,并提供查询功能. 所以如果查询已经归档数据的需求比较高的情况下,可以部署多个归档中心提供查询
Q:已经在链上做了restore,但是再做archive或者restore失败了
A: 底链的restore和archive都是异步任务,相当耗时.底链会记录一个当前是否正在restore/archive的状态,来确保不会出现多个archive/restore任务并发执行
Q: 执行archive指令,失败了
A: 可能有如下原因: 1. 链上区块数目比较少,还不足以触发清理的操作,可以调整底链的配置项目 unarchive_block_height(在chainmaker.yml的storage模块中)小一点.重启底链再试一下；2. archive所在高度及以下没有可以清理的文件,可以继续运行区块链生产更多区块以后再做清理命令
Q: 执行archive指令,没有权限
A: archive指令和restore指令都是高权限操作,需要admin身份
Q: 执行archive指令,清理的是所有节点的数据吗?
A: archive指令针对的是单节点,而不是所有节点生效；执行archive指令的是sdk的yaml文件中指定的节点(在nodes中指定一个节点)
Q: sdk/cmc中的配置archive_center_query_first怎么设置?
A: archive_center_query_first,这个开关如果打开.那么使用sdk或者cmc的时候会优先从归档中心上查数据,如果查不到才会到链上去查询；所以在dump数据的时候,这个值应该设置为false,因为cmc或者sdk需要从链上查数据,再将数据转移到归档中心.