# 归档中心使用文档  

## 整体流程
1. 启动归档中心服务
2. 使用cmc归档链上数据到归档中心服务
3. 使用扫描工具,扫描链上已归档的数据文件.根据扫描结果转移(需要人工)或删除(使用清理模式)已归档文件
4. 使用sdk查询已经归档数据

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

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

### 版本对应关系  

| 链<br>chainmaker-go | 归档中心服务<br/>chainmaker-archive-service | CMC工具<br/>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 |

### [设计方案详见](../tech/%E5%BD%92%E6%A1%A3%E4%B8%AD%E5%BF%83%E8%AE%BE%E8%AE%A1%E5%92%8C%E5%AE%9E%E7%8E%B0.md)   
  
### 下载chainmaker-archive-service源码   
```bash
git clone  --depth=1 https://git.chainmaker.org.cn/chainmaker/chainmaker-archive-service.git
git checkout v1.0.0_alpha
``` 

### 编译源代码: 
```bash
cd chainmaker-archive-service/src   
go build -o chainmaker-archive-service  
```

### 服务配置 
- 整体配置概览  

```bash
├── 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 服务配置文件说明  

```bash
# 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 

```


### 启动/停止`归档中心服务`  
- 启动服务:   
```bash
nohup ./chainmaker-archive-service > service.log 2>&1 &   
```   
- 记录服务生成的token到server_token. token用于调用压缩归档中心数据和管理证书的接口使用   
```bash
grep token ../log/processor.log 
``` 
- 停止服务
```bash
# 查询归档中心服务进程
ps -ef | grep chainmaker-archive-service
# 停止服务
kill -9 [processid]
```   

## 使用`CMC`工具归档链上数据到`归档中心服务`    
 
### 下载支持CMC归档中心的源码   
```bash
git clone -b v2.3.0_archive_alpha --depth=1 https://git.chainmaker.org.cn/chainmaker/chainmaker-go.git
```

### 编译CMC工具:   

```bash
cd tools/cmc
go build -o cmc  
```

### CMC支持归档中心配置概览: 
- 配置概览: 如果GRPC开启了TLS验证,key和pem才有用,否则无用  
```bash

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

```
- config.yml文件解析:   

```bash
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的获取可以采用如下步骤:  
```bash
# 首先使用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]}'
```

### 使用CMC工具归档数据
```bash
# 归档链上 区块块高的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 
```
### 使用CMC工具归档数据,到归档中心查询已归档数据命令 (非必要步骤,可以跳过)  
```bash

# 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

```

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

### 下载归档中心chainmaker-archive-service源码    
```bash
git clone  --depth=1 https://git.chainmaker.org.cn/chainmaker/chainmaker-archive-service.git 
git checkout v1.0.0_alpha
```

### 编译扫描工具  
```bash
cd bfdb-clean-tools
go build
```    

### 将扫描工具拷贝到链节点所在的服务器的某路径下  
```bash
cp bfdb-clean-tools /[path]
cp config.yml /[path]
```

### 配置扫描工具  

- 整体描述: 扫描工具有两种工作模式:
    - 模式1(`mode` 为 1): 扫描工具执行会扫描所有区块高度小于等于配置中`clean_height`的区块文件,并输出命名规则为`stub[year][month][day][hour][minute][second].csv`文件
    - 模式2(`mode` 为 2): 扫描工具会根据配置中的`clean_stub`文件中所有标为'y'的记录进行删除对应的区块文件(如果不打算删除区块文件,则不用使用模式2),删除后将删除的每一个文件名作为一行写入到文件`clean_stub.result`作为存根  
- 配置概览: 

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

```
- config.yml文件解析: 

```bash
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接口超时时间
```

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

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

## 使用`SDK`透明查询区块和交易信息

### 下载sdk源码 
```bash
git clone -b v2.3.0_archive_alpha --depth=1 https://git.chainmaker.org.cn/chainmaker/sdk-go.git
```

### 如果启用了归档中心在sdk的配置文件中增加如下配置: 
```bash
  archive_center_config:
    chain_genesis_hash: 5b29b0a67c529352c0e3f512a4e8d329f967afcdb580ec76e6d1462d9ac969ec # 归档的链的创世区块的hash
    archive_center_http_url: http://127.0.0.1:13119 # 归档中心的http接口地址
    request_second_limit: 10 # 查询归档中心http请求超时时间
```

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

## 使用`HTTP`请求直接调用`归档中心服务`的接口
- 接口分为两类:
    - 管理类接口: 压缩已归档数据接口(/admin/compress_under_height)；若开启了GRPC的TLS功能,增加CA证书接口(/admin/add_ca)；这两个接口使用特别的token也就是部署服务时候写入到server_token文件的值
    - 普通查询类接口
- [归档服务的http接口文档](./%E5%BD%92%E6%A1%A3%E4%B8%AD%E5%BF%83HTTP%E6%8E%A5%E5%8F%A3.md)