rwadurian/backend/services/blockchain-service/scripts/README.md

测试和健康检查脚本

使用流程

1️⃣ 启动基础服务

# 启动 Redis
redis-server --daemonize yes

# 或使用 Docker
docker compose up -d redis

2️⃣ 启动 Blockchain Service

# 在项目根目录
npm run start:dev

3️⃣ 运行健康检查

# 进入 scripts 目录
cd scripts

# 运行健康检查
./health-check.sh

期望输出：

🏥 开始健康检查...

=== 数据库服务 ===
Checking PostgreSQL ... ✓ OK
=== 缓存服务 ===
Checking Redis ... ✓ OK
=== 消息队列服务 ===
Checking Kafka ... ✓ OK
=== 区块链 RPC ===
Checking KAVA RPC ... ✓ OK
Checking BSC RPC ... ✓ OK
=== 应用服务 ===
Checking Blockchain Service ... ✓ OK
=== API 文档 ===
Checking Swagger UI ... ✓ OK

======================================
健康检查完成！
正常: 7
异常: 0
======================================
✓ 所有服务正常！

现在可以运行测试：
  ./scripts/quick-test.sh

4️⃣ 运行快速功能测试

./quick-test.sh

这个脚本会自动测试所有核心功能：

• ✅ 健康检查
• ✅ 余额查询（单链/多链）
• ✅ 地址派生
• ✅ 用户地址查询
• ✅ 错误场景处理
• ✅ API 文档可访问性

---

脚本说明

health-check.sh

• 作用: 检查所有依赖服务是否正常运行
• 使用场景: 部署前、调试时
• 检查项目:
  • PostgreSQL 数据库
  • Redis 缓存
  • Kafka 消息队列
  • KAVA/BSC RPC 端点
  • Blockchain Service 应用

quick-test.sh

• 作用: 快速测试所有核心 API 功能
• 使用场景: 验证功能完整性、回归测试
• 前置条件: health-check.sh 通过

start-all.sh

• 作用: 一键启动所有服务
• 使用场景: 初次启动、快速启动环境
• 前置条件: 依赖已安装

stop-service.sh

• 作用: 停止 Blockchain Service
• 使用场景: 需要停止服务时

rebuild-kafka.sh

• 作用: 重建 Kafka 容器
• 使用场景: Kafka 配置变更后

---

主要 API 端点

端点	方法	描述
/health	GET	健康检查
/health/ready	GET	就绪检查
/balance	GET	查询单链余额
/balance/multi-chain	GET	查询多链余额
/internal/derive-address	POST	从公钥派生地址
/internal/user/:userId/addresses	GET	获取用户地址
/api	GET	Swagger 文档

---

部署脚本 (deploy.sh)

主部署脚本位于项目根目录，提供以下命令：

# 构建 Docker 镜像
./deploy.sh build

# 启动服务
./deploy.sh start

# 停止服务
./deploy.sh stop

# 重启服务
./deploy.sh restart

# 查看日志
./deploy.sh logs

# 健康检查
./deploy.sh health

# 运行数据库迁移
./deploy.sh migrate

# 打开 Prisma Studio
./deploy.sh prisma-studio

# 进入容器 shell
./deploy.sh shell

# 查询余额
./deploy.sh check-balance KAVA 0x1234...

# 触发区块扫描
./deploy.sh scan-blocks

---

常见问题

Q: 为什么 RPC 检查失败？

A: 检查网络连接，或者 RPC 端点可能暂时不可用

Q: Redis 启动失败？

A: 检查是否已经在运行

ps aux | grep redis
redis-cli shutdown  # 如果已运行
redis-server --daemonize yes

Q: Kafka 连接失败？

A: 重建 Kafka 容器

./scripts/rebuild-kafka.sh

---

完整测试流程

# 1. 进入项目目录
cd ~/work/rwadurian/backend/services/blockchain-service

# 2. 安装依赖（首次）
npm install

# 3. 生成 Prisma Client
npx prisma generate

# 4. 运行数据库迁移
npx prisma migrate dev

# 5. 启动所有服务
./scripts/start-all.sh

# 6. 运行健康检查
./scripts/health-check.sh

# 7. 运行快速测试
./scripts/quick-test.sh

# 8. 运行完整测试
npm test
npm run test:e2e

---

区块链特定测试

测试余额查询

# KAVA 链
curl "http://localhost:3012/balance?chainType=KAVA&address=0x..."

# 多链查询
curl "http://localhost:3012/balance/multi-chain?address=0x..."

测试地址派生

curl -X POST "http://localhost:3012/internal/derive-address" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "12345",
    "publicKey": "0x02..."
  }'