fiscoBcosJDK/doc/FISCO_BCOS_TPS测试指南.md

# FISCO BCOS TPS压力测试指南

> **文档版本**: v2.0  
> **更新日期**: 2026-02-10  
> **适用版本**: FISCO BCOS 2.x / 3.x

---

## 📋 目录

1. [测试工具介绍](#测试工具介绍)
2. [快速开始](#快速开始)
3. [测试参数配置](#测试参数配置)
4. [运行测试](#运行测试)
5. [结果分析](#结果分析)
6. [常见问题排查](#常见问题排查)
7. [性能优化建议](#性能优化建议)

---

## 测试工具介绍

### 🎯 TPSTest.java

本项目提供的 `TPSTest.java` 是一个完整的TPS压测工具，具有以下特性：

**核心功能：**
- ✅ 自动连接FISCO BCOS节点
- ✅ 使用 ParallelTransfer 合约进行并行转账测试
- ✅ 支持多线程并发压测
- ✅ 实时监控TPS、成功率
- ✅ 自动生成详细测试报告
- ✅ 支持QPS限流控制

**测试原理：**
```
多线程并发 → 发送转账交易 → 统计响应时间 → 计算TPS和延迟
```

**文件位置：**
```
src/main/java/com/org/fisco/TPSTest.java
```

---

## 快速开始

### 前提条件

1. **合约已部署**
   - 合约地址：在代码第284行设置
   - 默认使用：`0x06ac2fe406f1ae06494946ee281d58f1c79c39e4`

2. **账户已初始化**
   - 使用 `fisco/console/init_accounts.sh` 脚本初始化账户余额
   - 或手动在控制台初始化至少100个账户

3. **SDK配置正确**
   - 配置文件：`src/main/resources/config.toml`
   - 确保能连接到你的链节点

### 5分钟快速测试

```bash
cd /Users/kiro/IdeaProjects/contract

# 1. 编译项目
./gradlew build

# 2. 直接运行测试
./gradlew run
```

测试会自动：
1. 连接到链节点
2. 初始化合约对象
3. 生成测试账户
4. 开始压测
5. 输出测试报告

---

## 测试参数配置

### 🔧 核心参数说明

在 `TPSTest.java` 的 `main` 方法中（第277-281行）配置：

```java
tester.setTestParams(
    threadCount,       // 并发线程数
    totalTransactions, // 总交易数
    qpsLimit          // QPS限制（0表示不限制）
);
```

### 参数详解

#### 1. 并发线程数 (threadCount)

**作用：** 控制同时发送交易的线程数量

**推荐值：**
| 测试场景 | 推荐值 | 说明 |
|---------|--------|------|
| 基准测试 | 1 | 测试单笔交易延迟 |
| 初步压测 | 50-100 | 找到基本TPS水平 |
| 寻找峰值 | 100-200 | 逐步增加找峰值 |
| 极限压测 | 200-500 | 测试系统极限 |

**⚠️ 注意：**
- 并发数过高会导致成功率下降
- 并发数过低无法达到TPS峰值
- **建议从小到大逐步测试**

#### 2. 总交易数 (totalTransactions)

**作用：** 本次测试发送的交易总数

**推荐值：**
| 测试类型 | 推荐值 | 测试时长（估算） |
|---------|--------|----------------|
| 快速验证 | 1,000 | 1-5秒 |
| 基础测试 | 10,000 | 10-30秒 |
| 标准测试 | 50,000 | 1-2分钟 |
| 长期测试 | 100,000+ | 5分钟以上 |

**原则：**
- ✅ 测试时长至少30秒以上才准确
- ✅ 交易数太少会受启动开销影响
- ✅ 交易数太多会耗时过长

#### 3. QPS限制 (qpsLimit)

**作用：** 限制每秒发送的交易数

**设置建议：**
- `0`：不限制，全力压测（推荐）
- `5000`：温和测试，适合生产环境验证
- `10000+`：根据节点能力设置上限

---

## 运行测试

### 方法1：使用默认参数运行

```bash
cd /Users/kiro/IdeaProjects/contract
./gradlew run
```

### 方法2：修改参数后运行

编辑 `src/main/java/com/org/fisco/TPSTest.java`：

```java
// 第277-281行
tester.setTestParams(
    100,     // 改为你想要的并发数
    10000,   // 改为你想要的交易总数
    0        // 0表示不限速
);
```

然后运行：
```bash
./gradlew build && ./gradlew run
```

### 观察实时输出

测试运行时会显示：

```
========================================
    FISCO BCOS TPS压力测试工具
========================================

连接FISCO BCOS节点成功
当前区块高度: 12345
使用已部署的合约地址: 0x06ac...
合约对象初始化完成

生成测试账户列表...
已生成 100 个测试账户
账户列表生成完成，账户余额已通过 init_accounts.sh 脚本初始化

[3/3] 开始压力测试...
测试配置:
  - 并发线程数: 100
  - 总交易数: 10000
  - QPS限制: 无限制
  - 预热交易数: 100

正在预热 (100 笔交易)...
预热完成!

开始正式压测...
实时TPS监控 (每5秒更新):
  当前进度: 2145/10000 | 实时TPS: 675.64 | 成功率: 99.87%
  当前进度: 4523/10000 | 实时TPS: 682.31 | 成功率: 99.91%
  ...
```

---

## 结果分析

### 📊 测试报告解读

测试完成后会自动生成报告（同时保存到文件）：

```
========================================
         FISCO BCOS TPS测试报告
========================================

测试配置:
  开始时间: 2026-02-10 15:30:00
  结束时间: 2026-02-10 15:32:15
  测试时长: 135.45 秒
  并发线程数: 100
  QPS限制: 无限制

交易统计:
  总交易数: 10000
  成功交易: 9987
  失败交易: 13
  成功率: 99.87%

性能指标:
  ★ TPS (每秒交易数): 675.64
  平均延迟: 148.23 ms
  中位数延迟: 125 ms
  P95延迟: 287 ms
  P99延迟: 456 ms

报告时间: 2026-02-10 15:32:15
========================================
```

### 📈 核心指标说明

#### 1. TPS（每秒交易数）

**含义：** 每秒成功处理的交易数量

**评判标准：**
| TPS范围 | 评价 | 说明 |
|---------|------|------|
| > 1000 | 优秀 ✅ | 性能良好 |
| 500-1000 | 良好 👍 | 基本满足需求 |
| 100-500 | 一般 ⚠️ | 需要优化 |
| < 100 | 较差 ❌ | 存在严重问题 |

**影响因素：**
- 节点配置（CPU、内存、磁盘）
- 网络延迟
- 并发线程数
- 节点 config.ini 配置

#### 2. 成功率

**含义：** 成功交易数 / 总交易数

**评判标准：**
- ✅ ≥ 99%：健康状态
- ⚠️ 95-99%：压力过大，需降低并发
- ❌ < 95%：存在严重问题

**低成功率原因：**
- 并发数设置过高
- 交易池容量不足
- 节点资源不足
- 账户余额不足

#### 3. 延迟指标

**平均延迟：** 所有交易的平均响应时间
**P95延迟：** 95%的交易在此时间内完成
**P99延迟：** 99%的交易在此时间内完成

**评判标准：**
| 指标 | 优秀 | 良好 | 一般 | 需优化 |
|------|------|------|------|--------|
| 平均延迟 | <100ms | 100-300ms | 300-500ms | >500ms |
| P99延迟 | <500ms | 500-1000ms | 1-2s | >2s |

---

## 常见问题排查

### ❌ 问题1：TPS很低（<100）

**可能原因及解决方案：**

1. **网络延迟过高**
   ```bash
   # 测试网络延迟
   ping -c 10 121.196.226.157
   ```
   - 延迟 > 100ms：考虑在云服务器上直接运行测试
   - 延迟 > 50ms：TPS会受明显影响

2. **节点配置未优化**
   
   SSH到云服务器检查 `config.ini`：
   ```bash
   cd ~/fisco/nodes/*/node0
   cat config.ini | grep -A 3 "\[tx_execute\]"
   cat config.ini | grep -A 3 "\[consensus\]"
   ```
   
   确认配置：
   ```ini
   [tx_execute]
   enable_parallel=true              # 必须为true
   
   [consensus]
   max_trans_num_per_block=1000      # 建议≥1000
   ```

3. **日志级别过低**
   ```ini
   [log]
   level=error  # 改为error减少IO开销
   ```

### ❌ 问题2：成功率低（<99%）

**排查步骤：**

1. **检查错误日志**
   
   测试运行时会输出错误信息：
   ```
   交易失败 - Status: 18, Message: ...
   交易异常: ContractException - ...
   ```

2. **降低并发数**
   
   如果成功率 < 99%，说明并发过高：
   ```java
   // 从当前并发数降低50%
   tester.setTestParams(
       50,      // 从100降到50
       10000,
       0
   );
   ```

3. **检查账户余额**
   ```bash
   cd fisco/console
   bash start.sh
   # 在控制台执行
   call ParallelTransfer 0x06ac... balanceOf "user_000000"
   ```

### ❌ 问题3：程序运行时资源耗尽

**现象：** 出现大量线程创建失败错误

**原因：** 之前的bug（每笔交易创建新合约对象）已修复

**确认修复：** 检查代码第29行是否有：
```java
private ParallelTransfer contract;  // 复用合约对象
```

### ❌ 问题4：程序一直不退出

**原因：** SDK后台线程持续运行

**解决：** 已在代码第318行添加：
```java
System.exit(0);
```

如果仍然卡住，按 `Ctrl+C` 强制终止。

---

## 性能优化建议

### 🎯 找到准确TPS的方法

**错误做法 ❌：**
- 用最高并发数跑一次就认为是TPS
- 忽略成功率指标
- 测试时间过短（<10秒）

**正确做法 ✅：**

#### 阶段1：基准测试
```java
tester.setTestParams(1, 100, 0);  // 单线程
```
记录：平均延迟 = X ms

#### 阶段2：二分法找最佳并发

逐步测试，找到成功率≥99%的最大并发数：

| 轮次 | 并发数 | 交易数 | 观察 |
|------|--------|--------|------|
| 测试1 | 50 | 5000 | 成功率≥99%？ |
| 测试2 | 100 | 5000 | 成功率≥99%？ |
| 测试3 | 200 | 5000 | 成功率≥99%？ |
| 测试4 | 400 | 5000 | 成功率<99%则停止 |

**结论：** 成功率≥99%的最大并发数 = 最佳并发数

#### 阶段3：峰值测试
```java
tester.setTestParams(
    [最佳并发数],  // 从阶段2得到
    50000,         // 大批量测试
    0
);
```

**这就是你链的真实TPS！**

### 🔧 节点优化Checklist

#### 云服务器配置

SSH到服务器，编辑 `config.ini`：

```ini
[tx_execute]
enable_parallel=true              # ✅ 开启并行

[consensus]
max_trans_num_per_block=1000      # ✅ 每块至少1000笔

[tx_pool]
limit=150000                      # ✅ 交易池容量

[log]
level=error                       # ✅ 降低日志级别
```

重启节点：
```bash
cd ~/fisco/nodes/*/
bash stop_all.sh
bash start_all.sh
```

#### 系统优化

```bash
# 增加文件描述符
ulimit -n 65535

# 检查磁盘类型（必须是SSD）
lsblk -d -o name,rota
# rota=0 表示SSD
```

### 📊 并发数与TPS的关系

**理论公式：**
```
TPS = 并发数 / 平均延迟（秒）
```

**示例：**
- 平均延迟 = 100ms = 0.1秒
- 并发数 = 100
- 理论TPS = 100 / 0.1 = **1000**

**实际调优：**

| 并发数 | TPS | 成功率 | 决策 |
|--------|-----|--------|------|
| 50 | 400 | 100% | ⬆️ 继续增加 |
| 100 | 700 | 99.8% | ⬆️ 可以继续 |
| 200 | 850 | 99.2% | ⬆️ 接近最佳 |
| 400 | 870 | 97% | ❌ 过高，回退 |

**最佳并发数 = 200**

---

## 测试结果记录模板

建议每次测试记录：

```
测试日期: 2026-02-10
测试轮次: 第X次

测试参数:
- 并发线程数: 
- 总交易数: 
- QPS限制: 

测试环境:
- 节点数量: 4个
- 网络延迟: XXms
- enable_parallel: true/false
- max_trans_num_per_block: XXX

测试结果:
- TPS: 
- 成功率: 
- 平均延迟: 
- P99延迟: 

问题记录:


优化措施:


下次改进:

```

---

## 快速参考

### 常用命令

```bash
# 编译运行测试
cd /Users/kiro/IdeaProjects/contract
./gradlew build && ./gradlew run

# 查看最近的测试报告
ls -lt tps_test_report_*.txt | head -5
cat tps_test_report_*.txt

# 测试网络延迟
ping -c 10 121.196.226.157

# 检查节点配置（SSH到服务器）
ssh root@121.196.226.157
cd ~/fisco/nodes/*/node0
cat config.ini | grep -E "enable_parallel|max_trans_num_per_block|limit|level"
```

### 推荐测试流程

```bash
# 1. 基准测试（修改代码为1线程100笔）
./gradlew run

# 2. 初步压测（修改代码为100线程10000笔）
./gradlew run

# 3. 根据成功率调整并发数
# 成功率≥99% → 增加并发
# 成功率<99% → 减少并发

# 4. 峰值测试（用最佳并发数跑50000笔）
./gradlew run
```

---

## 常见TPS参考值

| 区块链 | 单链TPS | 备注 |
|--------|---------|------|
| FISCO BCOS v2.x | 500-2000 | enable_parallel=true |
| FISCO BCOS v3.x | 2000-5000 | 性能优化版 |
| Hyperledger Fabric | 1000-3000 | 企业级联盟链 |
| 以太坊 | 15-30 | 公链 |

**你的目标：** 根据节点配置，达到 **500-1000 TPS** 即为良好水平。

---

## 总结

### ✅ 正确的测试姿势

1. **从小到大测试**：1线程 → 50线程 → 100线程 → 200线程
2. **关注成功率**：必须≥99%，否则降低并发
3. **测试足够久**：至少30秒以上
4. **记录每次结果**：对比优化前后差异

### ⚠️ 常见误区

1. ❌ 用最高并发测出来的数字就是TPS
2. ❌ 忽略成功率指标
3. ❌ 测试时间太短
4. ❌ 不检查节点配置
5. ❌ 网络延迟过高还在本地测试

### 🎯 核心原则

**准确的TPS = 在成功率≥99%的前提下，能持续达到的最高TPS**

---

**祝测试顺利！** 🚀

有问题请查看"常见问题排查"章节，或检查测试报告中的错误信息。