binance-api/specs/001-credential-manager/quickstart.md

快速开始：凭证管理模块

特性：001-credential-manager 版本：v1.0.0 状态：Phase 1 - 快速开始指南

概述

凭证管理模块提供简化的多平台账户管理，支持配置文件热加载、智能平台识别和统一签名接口。

安装和配置

1. 安装依赖

# 进入项目根目录
cd /path/to/your/project

# 安装凭证管理库
npm install ./libs/credential-manager

# 或使用 yarn
yarn add ./libs/credential-manager

2. 基础配置

创建账户配置文件 config/accounts.json：

{
  "version": "1.0",
  "accounts": [
    {
      "id": "pacifica-main-001",
      "platform": "pacifica",
      "credentials": {
        "type": "pacifica",
        "privateKey": "abcd1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab"
      },
      "metadata": {
        "alias": "Pacifica主账户",
        "description": "用于Pacifica交易的主要账户"
      }
    },
    {
      "id": "binance-api-001",
      "platform": "binance",
      "credentials": {
        "type": "binance",
        "apiKey": "your_binance_api_key",
        "secretKey": "your_binance_secret_key"
      },
      "metadata": {
        "alias": "Binance API账户"
      }
    }
  ]
}

快速开始示例

示例1：基础使用

import { CredentialManagerFactory } from '@your-org/credential-manager';

async function basicUsage() {
  // 1. 创建凭证管理器
  const factory = new CredentialManagerFactory();
  const manager = await factory.create({
    enableFileWatching: true,
    enableLogging: true
  });

  // 2. 加载配置文件
  const result = await manager.loadConfig('./config/accounts.json');
  console.log(`加载成功: ${result.accounts.length} 个账户`);

  // 3. 列出所有账户
  const accounts = manager.listAccounts();
  accounts.forEach(account => {
    console.log(`账户: ${account.id} (${account.platform})`);
  });

  // 4. 获取特定账户
  const account = manager.getAccount('pacifica-main-001');
  if (account) {
    console.log(`找到账户: ${account.metadata?.alias}`);
  }

  return manager;
}

示例2：签名操作

async function signingExample(manager) {
  // 1. 准备要签名的消息
  const message = new TextEncoder().encode('Hello, Pacifica!');

  // 2. 执行签名 (系统自动识别平台类型)
  const signResult = await manager.sign('pacifica-main-001', message);

  if (signResult.success) {
    console.log('签名成功:', {
      signature: signResult.signature,
      algorithm: signResult.algorithm,
      timestamp: signResult.timestamp
    });

    // 3. 验证签名
    const isValid = await manager.verify('pacifica-main-001', message, signResult.signature!);
    console.log('签名验证:', isValid ? '通过' : '失败');
  } else {
    console.error('签名失败:', signResult.error);
  }

  return signResult;
}

示例3：热加载监听

async function hotReloadExample(manager) {
  // 1. 开始监听配置文件变更
  manager.watchConfig('./config/accounts.json', (accounts) => {
    console.log(`配置文件已更新，重新加载了 ${accounts.length} 个账户`);

    accounts.forEach(account => {
      console.log(`- ${account.id}: ${account.platform} (${account.status})`);
    });
  });

  console.log('开始监听配置文件变更...');
  console.log('现在可以修改 accounts.json 文件来测试热加载功能');

  // 2. 模拟运行一段时间
  await new Promise(resolve => setTimeout(resolve, 30000));

  // 3. 停止监听
  manager.stopWatching();
  console.log('停止监听配置文件变更');
}

示例4：多平台签名

async function multiPlatformExample(manager) {
  const testMessage = new TextEncoder().encode('多平台测试消息');

  // 获取所有账户并按平台分组
  const accounts = manager.listAccounts();
  const platformGroups = accounts.reduce((groups, account) => {
    if (!groups[account.platform]) {
      groups[account.platform] = [];
    }
    groups[account.platform].push(account);
    return groups;
  }, {} as Record<string, any[]>);

  // 为每个平台的每个账户执行签名
  for (const [platform, platformAccounts] of Object.entries(platformGroups)) {
    console.log(`\n=== ${platform.toUpperCase()} 平台签名测试 ===`);

    for (const account of platformAccounts) {
      try {
        const startTime = Date.now();
        const result = await manager.sign(account.id, testMessage);
        const duration = Date.now() - startTime;

        if (result.success) {
          console.log(`✅ ${account.id}: 签名成功 (${duration}ms)`);
          console.log(`   算法: ${result.algorithm}`);
          console.log(`   签名: ${result.signature?.substring(0, 20)}...`);
        } else {
          console.log(`❌ ${account.id}: 签名失败 - ${result.error}`);
        }
      } catch (error) {
        console.log(`💥 ${account.id}: 签名异常 - ${error.message}`);
      }
    }
  }
}

完整集成测试

集成测试脚本

创建 test-credential-manager.ts 文件：

import { CredentialManagerFactory } from '@your-org/credential-manager';

async function runIntegrationTests() {
  console.log('🚀 开始凭证管理模块集成测试...\n');

  try {
    // 测试1: 基础使用
    console.log('📋 测试1: 基础使用');
    const manager = await basicUsage();
    console.log('✅ 基础使用测试通过\n');

    // 测试2: 签名操作
    console.log('🔐 测试2: 签名操作');
    const signResult = await signingExample(manager);
    console.log('✅ 签名操作测试通过\n');

    // 测试3: 多平台签名
    console.log('🌐 测试3: 多平台签名');
    await multiPlatformExample(manager);
    console.log('✅ 多平台签名测试通过\n');

    // 测试4: 性能测试
    console.log('⚡ 测试4: 性能测试');
    await performanceTest(manager);
    console.log('✅ 性能测试通过\n');

    console.log('🎉 所有集成测试通过！');

  } catch (error) {
    console.error('❌ 集成测试失败:', error);
    process.exit(1);
  }
}

async function performanceTest(manager) {
  const message = new TextEncoder().encode('性能测试消息');
  const iterations = 10;

  // 测试签名性能
  console.log(`执行 ${iterations} 次签名操作...`);
  const startTime = Date.now();

  const promises = Array.from({ length: iterations }, async (_, i) => {
    const result = await manager.sign('pacifica-main-001', message);
    return {
      iteration: i + 1,
      success: result.success,
      duration: Date.now() - startTime
    };
  });

  const results = await Promise.all(promises);
  const totalTime = Date.now() - startTime;
  const averageTime = totalTime / iterations;

  console.log(`性能测试结果:`);
  console.log(`- 总时间: ${totalTime}ms`);
  console.log(`- 平均时间: ${averageTime.toFixed(2)}ms`);
  console.log(`- 成功率: ${results.filter(r => r.success).length}/${iterations}`);

  // 验证性能要求
  if (averageTime > 50) {
    throw new Error(`签名性能不满足要求: ${averageTime}ms > 50ms`);
  }
}

// 运行测试
if (require.main === module) {
  runIntegrationTests();
}

export { runIntegrationTests };

运行测试

# 运行集成测试
npx tsx test-credential-manager.ts

# 使用Jest运行测试套件
npm test -- --testPathPattern=credential-manager

# 运行性能测试
npm run test:performance

配置文件示例

完整配置示例

{
  "version": "1.0",
  "accounts": [
    {
      "id": "pacifica-main-001",
      "platform": "pacifica",
      "credentials": {
        "type": "pacifica",
        "privateKey": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
      },
      "metadata": {
        "alias": "Pacifica主账户",
        "description": "主要用于Pacifica交易",
        "environment": "production",
        "maxDailyVolume": 100000
      }
    },
    {
      "id": "aster-test-001",
      "platform": "aster",
      "credentials": {
        "type": "aster",
        "privateKey": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12"
      },
      "metadata": {
        "alias": "Aster测试账户",
        "testnet": true
      }
    },
    {
      "id": "binance-api-001",
      "platform": "binance",
      "credentials": {
        "type": "binance",
        "apiKey": "your_binance_api_key_here",
        "secretKey": "your_binance_secret_key_here"
      },
      "metadata": {
        "alias": "Binance现货账户",
        "testnet": false,
        "permissions": ["SPOT"]
      }
    }
  ]
}

故障排除

常见问题

问题1: 配置文件加载失败

错误: CONFIG_LOAD_ERROR - 无法读取配置文件
解决: 检查文件路径和权限，确保JSON格式正确

问题2: 平台识别失败

错误: PLATFORM_DETECTION_ERROR - 无法识别平台类型
解决: 检查credentials格式，确保符合平台要求

问题3: 签名操作超时

错误: SIGNATURE_ERROR - 签名操作超时
解决: 增加签名超时时间或检查凭证有效性

调试模式

启用详细日志：

const manager = await factory.create({
  enableLogging: true,
  logLevel: 'debug'
});

API参考

主要接口

• ICredentialManager: 主要凭证管理接口
• loadConfig(path): 加载配置文件
• watchConfig(path, callback): 监听文件变更
• sign(accountId, message): 执行签名
• verify(accountId, message, signature): 验证签名
• getAccount(accountId): 获取账户信息
• listAccounts(): 列出所有账户

配置选项

• enableFileWatching: 启用文件监听（默认: true）
• signTimeout: 签名超时时间（默认: 30000ms）
• enableLogging: 启用日志记录（默认: true）
• logLevel: 日志级别（默认: 'info'）

下一步

1. 集成到主系统: 将凭证管理器集成到您的交易系统中
2. 添加更多平台: 根据需要实现其他平台支持
3. 监控和日志: 设置日志分析和监控
4. 性能优化: 根据实际使用情况调整性能参数

---

开发状态: ✅ Phase 1 完成 - 快速开始指南 下一阶段: Phase 2 - 任务生成 (运行 /tasks 命令)