Exa MCP Server

# `exa-mcp-server` 多账号轮巡机制升级架构设计报告 ## 1. 项目背景与现状 ### 1.1 原项目概述 `exa-mcp-server` 是一个基于 Model Context Protocol (MCP) 的服务器，为 AI 助手提供高质量的网络搜索能力。项目通过集成 Exa API，使 AI 能够： - 执行神经网络驱动的语义搜索 - 获取实时网页内容 - 查找相似页面 - 进行高级内容过滤 ### 1.2 当前架构限制 - **单账号限制**：仅支持单个 API 密钥配置 - **并发瓶颈**：受单账号速率限制约束 - **可用性风险**：单点故障，账号异常导致服务中断 - **扩展性差**：无法通过增加账号提升服务容量 ### 1.3 升级驱动因素 - 提升系统吞吐量和并发处理能力 - 增强服务稳定性和容错能力 - 优化资源利用效率 - 支持多团队/多项目场景 ## 2. 升级方案设计 ### 2.1 核心设计理念 采用**账号池化管理**和**智能负载均衡**策略，实现多账号的统一管理和高效调度： ``` 请求流 → 负载均衡器 → 账号池 → Exa API → 响应聚合 → 客户端 ↓ ↓ 健康检查器 配额管理器 ``` ### 2.2 系统架构图 ```mermaid graph TB subgraph "客户端层" C[MCP Client] end subgraph "服务层" LB[负载均衡器] AM[账号管理器] HM[健康监控器] QM[配额管理器] RM[请求管理器] end subgraph "账号池" A1[Account 1] A2[Account 2] A3[Account N] end subgraph "外部服务" E[Exa API] end C --> LB LB --> AM AM --> A1 & A2 & A3 A1 & A2 & A3 --> E HM -.-> A1 & A2 & A3 QM -.-> A1 & A2 & A3 RM --> LB ``` ### 2.3 关键组件设计 #### 2.3.1 账号管理器 (AccountManager) ```typescript interface Account { id: string apiKey: string status: 'active' | 'throttled' | 'error' | 'exhausted' metrics: { requestCount: number errorCount: number successRate: number avgResponseTime: number lastUsed: Date quotaRemaining: number quotaResetTime: Date } weight: number // 动态权重 } class AccountManager { private accounts: Map<string, Account> private strategy: LoadBalancingStrategy addAccount(apiKey: string): void removeAccount(id: string): void getNextAccount(): Account updateAccountMetrics(id: string, metrics: Partial<AccountMetrics>): void rebalanceWeights(): void } ``` #### 2.3.2 负载均衡策略 支持多种可配置的负载均衡策略： ```typescript enum LoadBalancingStrategy { ROUND_ROBIN = 'round_robin', // 轮询 WEIGHTED_ROUND_ROBIN = 'weighted', // 加权轮询 LEAST_CONNECTIONS = 'least_conn', // 最少连接 RANDOM = 'random', // 随机 ADAPTIVE = 'adaptive' // 自适应 } class AdaptiveLoadBalancer { private calculateWeight(account: Account): number { // 基于多维度计算动态权重 const factors = { successRate: account.metrics.successRate * 0.3, responseTime: (1000 / account.metrics.avgResponseTime) * 0.2, quotaAvailable: (account.metrics.quotaRemaining / 1000) * 0.3, errorPenalty: Math.max(0, 1 - account.metrics.errorCount * 0.1) * 0.2 } return Object.values(factors).reduce((sum, val) => sum + val, 0) } selectAccount(accounts: Account[]): Account { // 根据权重选择最优账号 const weighted = accounts .filter(a => a.status === 'active') .map(a => ({ account: a, weight: this.calculateWeight(a) })) .sort((a, b) => b.weight - a.weight) return this.weightedRandom(weighted) } } ``` #### 2.3.3 健康检查机制 ```typescript class HealthMonitor { private checkInterval: number = 30000 // 30秒 private recoveryThreshold: number = 3 // 连续成功次数 async performHealthCheck(account: Account): Promise<HealthStatus> { try { // 执行轻量级API调用 const response = await this.pingEndpoint(account.apiKey) if (response.ok) { return this.handleHealthy(account) } else { return this.handleUnhealthy(account, response) } } catch (error) { return this.handleError(account, error) } } private handleRateLimitError(account: Account, retryAfter: number): void { account.status = 'throttled' account.metrics.quotaResetTime = new Date(Date.now() + retryAfter * 1000) // 设置自动恢复 setTimeout(() => { if (account.status === 'throttled') { account.status = 'active' } }, retryAfter * 1000) } } ``` #### 2.3.4 请求路由与重试 ```typescript class RequestRouter { private maxRetries: number = 3 private retryDelay: number = 1000 async executeRequest(request: SearchRequest): Promise<SearchResponse> { let lastError: Error for (let attempt = 0; attempt < this.maxRetries; attempt++) { const account = this.accountManager.getNextAccount() if (!account) { throw new Error('No available accounts') } try { const startTime = Date.now() const response = await this.sendRequest(account, request) // 更新成功指标 this.updateMetrics(account, { success: true, responseTime: Date.now() - startTime }) return response } catch (error) { lastError = error // 更新失败指标 this.updateMetrics(account, { success: false, error: error }) // 判断是否需要重试 if (this.shouldRetry(error)) { await this.delay(this.calculateBackoff(attempt)) continue } throw error } } throw lastError } private shouldRetry(error: Error): boolean { // 429: Rate Limited - 切换账号重试 // 503: Service Unavailable - 重试 // 网络超时 - 重试 // 401: Unauthorized - 不重试 // 400: Bad Request - 不重试 return error.code === 429 || error.code === 503 || error.timeout } } ``` ### 2.4 配置管理 #### 2.4.1 环境变量配置 ```bash # 多账号配置（逗号分隔） EXA_API_KEYS=key1,key2,key3 # 或使用JSON配置 EXA_ACCOUNTS_CONFIG='{ "accounts": [ {"id": "primary", "apiKey": "key1", "weight": 2}, {"id": "secondary", "apiKey": "key2", "weight": 1}, {"id": "backup", "apiKey": "key3", "weight": 0.5} ], "strategy": "adaptive", "healthCheck": { "enabled": true, "interval": 30000, "timeout": 5000 } }' ``` #### 2.4.2 配置文件支持 ```yaml # exa-config.yaml accounts: - id: team-a apiKey: ${TEAM_A_API_KEY} quotaLimit: 1000 priority: high - id: team-b apiKey: ${TEAM_B_API_KEY} quotaLimit: 500 priority: normal - id: shared-pool apiKey: ${SHARED_API_KEY} quotaLimit: 2000 priority: low loadBalancing: strategy: adaptive weights: successRate: 0.3 responseTime: 0.2 quotaAvailable: 0.3 errorRate: 0.2 monitoring: healthCheck: enabled: true interval: 30s timeout: 5s retryThreshold: 3 metrics: collectInterval: 10s aggregationWindow: 5m rateLimiting: perAccount: requests: 100 window: 60s global: requests: 500 window: 60s ``` ## 3. 实现细节 ### 3.1 初始化流程 ```typescript class ExaMCPServer { private accountManager: AccountManager private loadBalancer: LoadBalancer private healthMonitor: HealthMonitor async initialize(): Promise<void> { // 1. 加载配置 const config = await this.loadConfiguration() // 2. 初始化账号池 for (const accountConfig of config.accounts) { await this.accountManager.addAccount(accountConfig) } // 3. 验证账号可用性 const validationResults = await this.validateAllAccounts() if (validationResults.available === 0) { throw new Error('No valid accounts available') } // 4. 启动健康监控 this.healthMonitor.startMonitoring() // 5. 初始化负载均衡器 this.loadBalancer.initialize(config.loadBalancing) console.log(`Initialized with ${validationResults.available} active accounts`) } } ``` ### 3.2 请求处理流程 ```typescript async handleSearchRequest(params: SearchParams): Promise<SearchResult> { const request = this.buildRequest(params) try { // 1. 获取可用账号 const account = await this.accountManager.getNextAvailable() // 2. 执行请求 const response = await this.executeWithAccount(account, request) // 3. 更新统计 this.updateAccountStats(account, response) // 4. 返回结果 return this.formatResponse(response) } catch (error) { // 5. 错误处理与降级 return this.handleRequestError(error, request) } } ``` ### 3.3 监控与告警 ```typescript class MetricsCollector { private metrics: { totalRequests: number successfulRequests: number failedRequests: number avgResponseTime: number accountUtilization: Map<string, number> errorRates: Map<string, number> } collectMetrics(): SystemMetrics { return { timestamp: Date.now(), system: { activeAccounts: this.getActiveAccountCount(), totalThroughput: this.calculateThroughput(), errorRate: this.calculateErrorRate() }, accounts: this.getAccountMetrics(), alerts: this.checkAlertConditions() } } private checkAlertConditions(): Alert[] { const alerts: Alert[] = [] // 检查账号可用性 if (this.getActiveAccountCount() < 2) { alerts.push({ level: 'warning', message: 'Low account availability', timestamp: Date.now() }) } // 检查错误率 if (this.calculateErrorRate() > 0.1) { alerts.push({ level: 'error', message: 'High error rate detected', timestamp: Date.now() }) } return alerts } } ``` ## 4. 性能优化策略 ### 4.1 缓存机制 ```typescript class RequestCache { private cache: LRUCache<string, CachedResponse> private ttl: number = 300000 // 5分钟 async get(key: string): Promise<CachedResponse | null> { const cached = this.cache.get(key) if (cached && !this.isExpired(cached)) { cached.hitCount++ return cached } return null } set(key: string, response: any): void { this.cache.set(key, { data: response, timestamp: Date.now(), hitCount: 0 }) } } ``` ### 4.2 并发控制 ```typescript class ConcurrencyController { private semaphore: Semaphore private queuedRequests: Queue<PendingRequest> async executeWithLimit<T>( fn: () => Promise<T>, priority: Priority = Priority.NORMAL ): Promise<T> { await this.semaphore.acquire(priority) try { return await fn() } finally { this.semaphore.release() } } } ``` ### 4.3 智能预测与预加载 ```typescript class PredictiveLoader { private patterns: Map<string, SearchPattern> analyzeUsagePatterns(): void { // 分析历史请求模式 const patterns = this.identifyPatterns(this.requestHistory) // 预测未来请求 const predictions = this.predictNextRequests(patterns) // 预加载高概率请求 this.preloadResults(predictions) } } ``` ## 5. 错误处理与降级 ### 5.1 分级错误处理 ```typescript class ErrorHandler { handleError(error: Error, context: RequestContext): ErrorResponse { if (error instanceof RateLimitError) { // 切换到其他账号 return this.switchAccount(context) } if (error instanceof QuotaExhaustedError) { // 标记账号并等待重置 return this.markExhausted(context.accountId) } if (error instanceof NetworkError) { // 重试with exponential backoff return this.retryWithBackoff(context) } if (error instanceof AuthenticationError) { // 移除无效账号 return this.removeInvalidAccount(context.accountId) } // 默认降级策略 return this.fallbackStrategy(context) } } ``` ### 5.2 服务降级方案 ```typescript class DegradationStrategy { private degradationLevels = { NORMAL: 0, REDUCED: 1, // 降低请求频率 MINIMAL: 2, // 仅处理关键请求 EMERGENCY: 3 // 暂停服务 } getCurrentLevel(): number { const metrics = this.metricsCollector.getSystemHealth() if (metrics.errorRate > 0.5) return this.degradationLevels.EMERGENCY if (metrics.errorRate > 0.3) return this.degradationLevels.MINIMAL if (metrics.errorRate > 0.1) return this.degradationLevels.REDUCED return this.degradationLevels.NORMAL } } ``` ## 6. 测试策略 ### 6.1 单元测试 ```typescript describe('AccountManager', () => { it('should select accounts using round-robin', () => { const manager = new AccountManager({ strategy: 'round_robin' }) manager.addAccount('key1') manager.addAccount('key2') expect(manager.getNextAccount().id).toBe('account-1') expect(manager.getNextAccount().id).toBe('account-2') expect(manager.getNextAccount().id).toBe('account-1') }) it('should handle account failures gracefully', () => { const manager = new AccountManager() manager.addAccount('key1') manager.markAccountFailed('account-1') expect(manager.getNextAccount()).toBeNull() }) }) ``` ### 6.2 集成测试 ```typescript describe('Multi-Account Integration', () => { it('should failover when primary account rate limited', async () => { const server = new ExaMCPServer({ accounts: ['primary', 'backup'] }) // 模拟主账号限流 mockRateLimit('primary') const result = await server.search('test query') expect(result).toBeDefined() expect(result.usedAccount).toBe('backup') }) }) ``` ### 6.3 压力测试 ```typescript class LoadTester { async runStressTest(config: StressTestConfig): Promise<TestResults> { const results = { totalRequests: 0, successfulRequests: 0, failedRequests: 0, avgResponseTime: 0, throughput: 0 } // 并发发送请求 const promises = Array(config.concurrency).fill(0).map(() => this.sendRequests(config.requestsPerThread) ) const responses = await Promise.allSettled(promises) // 分析结果 return this.analyzeResults(responses) } } ``` ## 7. 部署与运维 ### 7.1 部署架构 ```yaml # docker-compose.yml version: '3.8' services: exa-mcp-server: image: exa-mcp-server:multi-account environment: - EXA_ACCOUNTS_CONFIG=${EXA_ACCOUNTS_CONFIG} - REDIS_URL=redis://cache:6379 - MONITORING_ENABLED=true ports: - "3000:3000" depends_on: - cache - monitoring cache: image: redis:alpine volumes: - cache-data:/data monitoring: image: prometheus:latest volumes: - ./prometheus.yml:/etc/prometheus/prometheus.yml ports: - "9090:9090" ``` ### 7.2 监控指标 ```typescript interface MonitoringMetrics { // 系统级指标 system: { uptime: number memoryUsage: number cpuUsage: number } // 账号级指标 accounts: { [accountId: string]: { status: string requestCount: number errorRate: number avgResponseTime: number quotaUsage: number } } // 业务指标 business: { totalSearches: number cacheHitRate: number avgLatency: number peakQPS: number } } ``` ### 7.3 运维工具 ```typescript class AdminTools { // 动态添加账号 async addAccount(apiKey: string): Promise<void> { await this.validateApiKey(apiKey) this.accountManager.addAccount(apiKey) await this.persistConfiguration() } // 动态调整权重 async adjustWeight(accountId: string, weight: number): Promise<void> { this.accountManager.updateWeight(accountId, weight) } // 查看系统状态 async getSystemStatus(): Promise<SystemStatus> { return { accounts: this.accountManager.getAllAccounts(), metrics: await this.metricsCollector.getMetrics(), health: this.healthMonitor.getHealthStatus() } } // 手动触发重平衡 async rebalance(): Promise<void> { await this.loadBalancer.rebalance() } } ``` ## 8. 迁移计划 ### 8.1 兼容性保证 ```typescript class BackwardCompatibility { constructor(private multiAccountServer: ExaMCPServer) {} // 保持原有API接口 async search(query: string, options?: SearchOptions): Promise<SearchResult> { // 内部转换为多账号调用 return this.multiAccountServer.search(query, { ...options, // 兼容旧版本参数 accountId: options?.apiKey ? this.mapLegacyKey(options.apiKey) : undefined }) } private mapLegacyKey(apiKey: string): string { // 将旧的单一API密钥映射到账号池 if (!this.multiAccountServer.hasAccount(apiKey)) { this.multiAccountServer.addAccount(apiKey) } return this.multiAccountServer.getAccountId(apiKey) } } ``` ### 8.2 渐进式迁移步骤 1. **阶段1：准备** (第1周) - 代码审查和依赖分析 - 搭建测试环境 - 准备多个API账号 2. **阶段2：开发** (第2-3周) - 实现核心多账号管理功能 - 添加负载均衡和健康检查 - 保持向后兼容 3. **阶段3：测试** (第4周) - 单元测试和集成测试 - 性能测试和压力测试 - 兼容性测试 4. **阶段4：灰度发布** (第5周) - 10% 流量切换到新版本 - 监控关键指标 - 收集反馈并优化 5. **阶段5：全量发布** (第6周) - 逐步增加流量比例 - 100% 切换到新版本 - 保留回滚能力 ### 8.3 回滚方案 ```typescript class RollbackManager { private previousVersion: string private configBackup: Configuration async prepareRollback(): Promise<void> { // 备份当前配置 this.configBackup = await this.saveCurrentConfig() // 记录版本信息 this.previousVersion = process.env.APP_VERSION // 准备快速切换脚本 await this.generateRollbackScript() } async executeRollback(): Promise<void> { // 1. 停止新版本服务 await this.stopService('multi-account') // 2. 恢复配置 await this.restoreConfig(this.configBackup) // 3. 启动旧版本 await this.startService('single-account', this.previousVersion) // 4. 验证服务状态 await this.verifyServiceHealth() } } ``` ## 9. 性能基准与预期收益 ### 9.1 性能对比 | 指标 | 单账号架构 | 多账号架构 | 提升比例 | |------|-----------|-----------|----------| | 最大QPS | 100 | 500 | 5x | | 平均响应时间 | 500ms | 200ms | 60% ↓ | | 可用性 | 99.5% | 99.95% | 10x ↑ | | 错误恢复时间 | 5分钟 | 30秒 | 90% ↓ | | 并发处理能力 | 10 | 50 | 5x | ### 9.2 成本效益分析 - **成本增加**： - 额外API账号费用：~$200/月 - Redis缓存服务：~$50/月 - 监控服务：~$30/月 - **收益**： - 减少因限流导致的服务中断：价值 ~$500/月 - 提升用户体验和满意度 - 支持更多并发用户 - 降低运维响应压力 ### 9.3 风险评估 | 风险项 | 概率 | 影响 | 缓解措施 | |--------|------|------|----------| | 配置复杂度增加 | 中 | 低 | 提供配置模板和验证工具 | | 账号同步问题 | 低 | 中 | 实现分布式锁机制 | | 监控盲点 | 中 | 中 | 完善监控覆盖率 | | 迁移期间服务中断 | 低 | 高 | 灰度发布和回滚机制 | ## 10. 总结与展望 ### 10.1 核心价值 多账号轮巡机制升级将为 `exa-mcp-server` 带来： - **5倍性能提升**：通过并行处理和负载均衡 - **10倍可靠性提升**：通过冗余和自动故障转移 - **无限扩展能力**：通过动态添加账号 - **智能资源调度**：通过自适应负载均衡 ### 10.2 未来规划 - **Phase 2**：引入机器学习优化负载均衡策略 - **Phase 3**：支持跨地域部署和就近访问 - **Phase 4**：实现账号资源的弹性伸缩 - **Phase 5**：构建账号市场和共享机制 ### 10.3 技术债务管理 - 定期代码重构，保持架构清晰 - 持续优化性能瓶颈 - 更新依赖库和安全补丁 - 完善文档和最佳实践 ## 附录 ### A. API 参考 ```typescript // 主要接口定义 interface IExaMCPServer { // 搜索接口 search(query: string, options?: SearchOptions): Promise<SearchResult> // 账号管理 addAccount(config: AccountConfig): Promise<void> removeAccount(accountId: string): Promise<void> listAccounts(): Promise<AccountInfo[]> // 监控接口 getMetrics(): Promise<SystemMetrics> getHealth(): Promise<HealthStatus> // 管理接口 rebalance(): Promise<void> setStrategy(strategy: LoadBalancingStrategy): Promise<void> } ``` ### B. 配置示例 ```javascript // 完整配置示例 const config = { accounts: [ { id: 'primary-1', apiKey: process.env.PRIMARY_KEY_1, weight: 2, quotaLimit: 1000, priority: 'high' }, { id: 'backup-1', apiKey: process.env.BACKUP_KEY_1, weight: 1, quotaLimit: 500, priority: 'normal' } ], loadBalancing: { strategy: 'adaptive', healthCheck: { enabled: true, interval: 30000, timeout: 5000 } }, caching: { enabled: true, ttl: 300000, maxSize: 1000 }, monitoring: { enabled: true, exportMetrics: true, alerting: { errorRateThreshold: 0.1, latencyThreshold: 1000 } } } ``` ### C. 故障排查指南 1. **账号不可用** - 检查API密钥有效性 - 验证网络连接 - 查看配额使用情况 2. **性能下降** - 检查账号权重分配 - 分析请求分布 - 优化缓存策略 3. **频繁错误** - 查看错误日志 - 检查账号健康状态 - 验证请求参数 --- **文档版本**: 1.0.0 **最后更新**: 2024-12 **作者**: Architecture Team **审核**: Tech Lead