# 运维工具

## 前言

ChainMaker Keeper 是长安链官方提供的命令行运维工具集，主要用于区块链数据的存储管理、数据完整性检查和数据重建等运维场景。当区块链数据出现损坏或需要重建历史数据时，可以使用该工具进行处理。

## 工具简介

ChainMaker Keeper 是一个用于 ChainMaker 区块链的命令行工具集，提供以下核心功能：

- **数据重建** - 从区块文件重建区块链数据库，支持选择性重建
- **完整性检查** - 验证区块链数据的完整性和一致性
- **多数据库支持** - 支持 LevelDB、BadgerDB 等多种存储后端

## 系统要求

- Go 1.18 或更高版本
- Linux 操作系统
- 足够的磁盘空间用于区块链数据操作

## 安装部署

### 从源码构建

```bash
# 克隆仓库
git clone https://git.chainmaker.org.cn/chainmaker/chainmaker-keeper.git
cd chainmaker-keeper

# 安装依赖
go mod download

# 构建
make build

# 移动到长安链bin目录
mv cmk /path/to/chainmaker/bin/
```

## 快速开始

### 基本使用

```bash
# 查看帮助
./cmk --help

# 查看版本信息
./cmk version

# 重建区块链数据
./cmk store rebuild --chain-id=chain1 --chainmaker-config=./chainmaker.yml

# 检查数据完整性
./cmk store check --chain-id=chain1 --chainmaker-config=./chainmaker.yml
```

## 命令参考

### store rebuild — 存储重建

从区块文件（bfdb）重建区块链数据库，当前支持重建 historyDB。

```bash
cmk store rebuild [flags]
```

**主要参数：**

| 选项 | 类型 | 说明 | 默认值 |
|:-----|:-----|:-----|:-------|
| `--chainmaker-config` | string | Chainmaker 配置文件路径 | `./chainmaker.yml` |
| `--config, -c` | string | Keeper 日志配置文件路径 | - |
| `--chain-id` | string | 链 ID | `chain1` |
| `--start-height` | uint | 起始区块高度（不指定则从头开始） | - |
| `--end-height` | uint | 结束区块高度（不指定则到最新区块） | - |
| `--log-level` | string | 日志级别 (DEBUG/INFO/WARN/ERROR) | `INFO` |

**使用示例：**

```bash
# 完整重建（不指定高度范围 = 全量重建）
./cmk store rebuild \
  --chain-id=chain1 \
  --chainmaker-config=./chainmaker.yml

# 重建指定区块范围
./cmk store rebuild \
  --chain-id=chain1 \
  --chainmaker-config=./chainmaker.yml \
  --start-height=50000 \
  --end-height=100000
```

### store check — 数据完整性检查

验证区块链数据的完整性和一致性。

```bash
cmk store check [flags]
```

**主要参数：**

| 选项 | 类型 | 说明 | 默认值 |
|:-----|:-----|:-----|:-------|
| `--chainmaker-config` | string | Chainmaker 配置文件路径 | `./chainmaker.yml` |
| `--config, -c` | string | Keeper 日志配置文件路径 | - |
| `--chain-id` | string | 链 ID | `chain1` |
| `--db-types` | strings | 要检查的数据库类型 | `historyDB` |
| `--log-level` | string | 日志级别 (DEBUG/INFO/WARN/ERROR) | `INFO` |

**使用示例：**

```bash
./cmk store check \
  --chain-id=chain1 \
  --chainmaker-config=./chainmaker.yml \
  --db-types=historyDB
```

## 使用场景

### 场景：重建历史数据

当需要重建 ChainMaker 的历史数据库时，按照以下步骤操作。

> **前提条件**：cmk 必须放置在 ChainMaker 节点的 `bin/` 目录下使用，因为工具依赖配置文件中的相对路径来定位数据目录。

#### 节点目录结构

以 `chain1` 为例，节点目录结构如下：

```
chainmaker-node/
├── bin/
│   ├── chainmaker
│   ├── cmk          # ← 放置在此处
│   ├── start.sh
│   ├── stop.sh
│   └── ...
├── config/
│   └── node1/
│       ├── chainmaker.yml
│       ├── log.yml
│       └── ...
├── data/                 # 数据目录（相对路径读取）
└── lib/
```

#### 操作步骤

**1. 准备工作（无需停止服务）**

将 cmk 放入 ChainMaker 的 bin 目录：

```bash
cp cmk /path/to/chainmaker-node/bin/
cd /path/to/chainmaker-node/bin/
```

复制配置文件（避免修改正在使用的配置文件）：

```bash
cd ../config/node1
cp chainmaker.yml ./chainmaker.rebuild.yml
```

修改复制后的配置文件 `chainmaker.rebuild.yml`：

> **⚠️ 核心原则**：重建时必须指定新的存储路径，**禁止**使用原路径，否则会覆盖原数据造成不可逆损失！

根据您使用的存储后端类型修改对应配置项：

```yaml
# LevelDB：将 `leveldb_config.store_path` 改为新目录

historydb_config:
  provider: leveldb
  leveldb_config:
    store_path: ../data/ledgerData1/rebuild_history   # ← 改为新目录

# BadgerDB：将 `badgerdb_config.store_path` 改为新目录

historydb_config:
  provider: badgerdb
  badgerdb_config:
    store_path: ../data/ledgerData1/rebuild_history   # ← 改为新目录

# SQL：在 `sqldb_config.db_prefix` 添加前缀

historydb_config:
  provider: sqlkv
  sqldb_config:
    sqldb_type: mysql
    dsn: root:password@tcp(127.0.0.1:3306)/
    db_prefix: rebuild_                         # ← 添加前缀
```

**2. 执行重建**

执行 rebuild 命令完整重建数据：

```bash
./cmk store rebuild \
  --chain-id=chain1 \
  --chainmaker-config=../config/node1/chainmaker.rebuild.yml
```

执行过程中会逐块读取并写入，看到以下日志表示重建完成：

```
Starting rebuild from height 0 to 604
...
async read block [height: 604] done, cost: 150.24µs
async write batch [height: 604, dbType: historyDB] done, cost: 2.468657ms
Rebuild operation completed successfully, cost 639.970436ms
```

**3. 执行检查**

执行 check 命令检查数据完整性：

```bash
./cmk store check \
  --chain-id=chain1 \
  --chainmaker-config=../config/node1/chainmaker.rebuild.yml \
  --db-types=historyDB
```

看到以下日志表示检查通过：

```
Successfully initialized historyDB checker
Checker 1/1 completed successfully
Blockchain data integrity check completed successfully in 393.336µs
```

**4. 应用重建数据**

停止服务，备份原数据，替换为新数据：

```bash
# 停止 ChainMaker 服务
./stop.sh

# 备份原有 historydb（用于快速恢复）
mv ../data/node1/history/chain1 ../data/node1/history/chain1.old

# 重命名重建的 rebuild_history/chain1 为 history/chain1
mv ../data/node1/rebuild_history/chain1 ../data/node1/history/chain1

# 重启 ChainMaker 服务
./start.sh
```

**快速恢复方案**（如果替换后服务异常）：

```bash
# 停止服务
./stop.sh
# 恢复原数据
rm -rf ../data/node1/history/chain1
mv ../data/node1/history/chain1.old ../data/node1/history/chain1
# 重启服务
./start.sh
```

#### 注意事项

- ✅ 重建过程**可以在服务运行时执行**，不影响正常业务
- ✅ **复制配置文件后再修改**，避免影响正在运行的服务
- ⚠️ **应用新数据时需要短暂停止服务**，建议在维护窗口执行
- ⚠️ **确保有足够的磁盘空间**（重建期间新旧数据并存，通常需要 2 倍以上空间）
- 🔄 **保留原数据备份**，直到确认新数据库稳定运行
- ⚠️ `provider` 类型（leveldb / badgerdb / sqlkv）**必须与原配置保持一致**，否则重建后的数据格式与服务不兼容
- 💡 `disable_key_history`、`disable_contract_history`、`disable_account_history` 等开关**建议与原配置保持一致**，确保重建的数据范围与原数据一致

## 日志配置

通过 `--config`（`-c`）参数指定 Keeper 日志配置文件，支持灵活控制日志输出策略。不指定时使用硬编码默认配置。

**配置文件格式（YAML）：**

```yaml
log:
  log_level_default: INFO       # 日志级别：DEBUG / INFO / WARN / ERROR
  file_path: ./log/cmk.log     # 日志文件路径
  max_age: 365                  # 日志文件最大保留天数
  rotation_time: 1              # 日志文件滚动周期（天）
  log_in_console: true          # 是否输出到控制台
  show_color: true              # 控制台输出是否启用颜色
```

**使用示例：**

```bash
# 使用配置文件控制日志
./cmk store rebuild \
  --chain-id=chain1 \
  --chainmaker-config=./chainmaker.yml \
  --config=./config/config.yml

# --log-level 可覆盖配置文件中的日志级别
./cmk store rebuild \
  --chain-id=chain1 \
  --chainmaker-config=./chainmaker.yml \
  --config=./config/config.yml \
  --log-level=DEBUG
```

**优先级**：硬编码默认值 < 配置文件值 < 命令行 `--log-level` 值