# 快速开始:凭证管理模块 **特性**:001-credential-manager **版本**:v1.0.0 **状态**:Phase 1 - 快速开始指南 ## 概述 凭证管理模块提供简化的多平台账户管理,支持配置文件热加载、智能平台识别和统一签名接口。 ## 安装和配置 ### 1. 安装依赖 ```bash # 进入项目根目录 cd /path/to/your/project # 安装凭证管理库 npm install ./libs/credential-manager # 或使用 yarn yarn add ./libs/credential-manager ``` ### 2. 基础配置 创建账户配置文件 `config/accounts.json`: ```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:基础使用 ```typescript 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:签名操作 ```typescript 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:热加载监听 ```typescript 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:多平台签名 ```typescript 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); // 为每个平台的每个账户执行签名 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` 文件: ```typescript 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 }; ``` ## 运行测试 ```bash # 运行集成测试 npx tsx test-credential-manager.ts # 使用Jest运行测试套件 npm test -- --testPathPattern=credential-manager # 运行性能测试 npm run test:performance ``` ## 配置文件示例 ### 完整配置示例 ```json { "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 - 签名操作超时 解决: 增加签名超时时间或检查凭证有效性 ``` ### 调试模式 启用详细日志: ```typescript 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` 命令)