makemd/docs/ARCHIVE/01_Architecture/02_System_Interoperability.md

系统互通架构（System Interoperability Architecture）

本文档定义 Crawlful Hub 系统各组件之间的互通机制和通信规范。

1. 互通架构总览

1.1 核心互通模型

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────────────┐
│   前端控制台         │────▶│    后端服务          │────▶│   运营代理（Agent）   │
│  (Frontend Console) │◀────│  (Backend Service)  │◀────│  (Operation Agent)  │
└─────────────────────┘     └─────────────────────┘     └─────────────────────┘
                                    │
                                    ▼
                          ┌─────────────────────┐
                          │    平台适配器         │
                          │ (Platform Adapter)  │
                          └─────────────────────┘
                                    │
                                    ▼
                          ┌─────────────────────┐
                          │    第三方平台         │
                          │ (External Platform) │
                          └─────────────────────┘

1.2 互通层次

互通层次	通信协议	说明
前端与后端互通	RESTful API、WebSocket	前端控制台与后端服务的通信
后端与Agent互通	WebSocket、消息队列（MQ）	后端服务与运营代理的通信
Agent与平台互通	平台API、浏览器自动化	运营代理与第三方平台的通信

2. 前端与后端互通

2.1 API通信

项目	规范
基础API	RESTful风格，支持CRUD操作
认证机制	JWT Token（JSON Web Token），支持Bearer认证
请求格式	JSON格式，统一错误处理
响应格式	统一响应体结构

标准响应格式：

{
  "code": 200,
  "message": "success",
  "data": { /* 业务数据 */ },
  "timestamp": "2026-03-21T10:30:00Z"
}

2.2 WebSocket通信

功能	说明
实时数据推送	店铺状态、任务进度、操作结果实时同步
事件通知	操作完成、异常告警、系统通知
心跳保活	保持连接活跃，支持断线重连机制

WebSocket消息格式：

{
  "type": "event|data|heartbeat",
  "event": "task_completed|error|notification",
  "payload": { /* 消息内容 */ },
  "timestamp": "2026-03-21T10:30:00Z"
}

2.3 前端API调用示例

// 绑定店铺
const bindStore = async (storeData) => {
  const response = await fetch('/api/operation-agent/stores', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    body: JSON.stringify(storeData)
  });
  return response.json();
};

// 同步商品
const syncProducts = async (storeId) => {
  const response = await fetch(`/api/operation-agent/stores/${storeId}/products/sync`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`
    }
  });
  return response.json();
};

3. 后端与运营代理（Agent）互通

3.1 WebSocket通信

特性	说明
双向通信	后端下发任务，Agent回传执行结果
加密传输	TLS/SSL加密，确保通信安全
认证机制	Agent注册时进行身份验证（Token-based）
消息格式	统一JSON消息格式

任务下发消息格式：

{
  "type": "task",
  "taskId": "task-123",
  "action": "syncProducts",
  "params": {
    "storeId": "store-123",
    "limit": 100
  },
  "priority": "high|normal|low",
  "timeout": 300000
}

3.2 消息队列（Message Queue）

特性	说明	技术选型
任务分发	异步任务分发，解耦前后端	RabbitMQ / Redis / BullMQ
任务优先级	支持高、中、低优先级任务	Priority Queue
任务持久化	确保任务不丢失，支持故障恢复	Persistent Storage
失败重试	自动重试机制，支持指数退避（Exponential Backoff）	Retry Policy

3.3 状态同步

机制	说明	频率
心跳保活	Agent定期发送心跳，报告运行状态	每30秒
状态回传	任务执行状态实时回传到后端	实时
健康检查	后端定期检查Agent健康状态	每60秒

3.4 后端API调用示例

// 向Agent下发任务
const sendTaskToAgent = async (agentId, task) => {
  const ws = getAgentWebSocket(agentId);
  if (ws && ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({
      type: 'task',
      taskId: generateTaskId(),
      action: task.action,
      params: task.params
    }));
  } else {
    // 发送到消息队列
    await messageQueue.send('agent-tasks', {
      agentId,
      task
    });
  }
};

// 处理Agent回传
const handleAgentResponse = (message) => {
  const data = JSON.parse(message);
  switch (data.type) {
    case 'task_result':
      handleTaskResult(data.taskId, data.result);
      break;
    case 'heartbeat':
      updateAgentStatus(data.agentId, data.status);
      break;
    case 'error':
      handleAgentError(data.agentId, data.error);
      break;
  }
};

4. 运营代理与第三方平台互通

4.1 平台API调用

项目	说明
认证机制	OAuth 2.0、API密钥（API Key）、签名认证等
请求格式	符合各平台API规范（RESTful/GraphQL）
响应处理	统一解析和错误处理，标准化输出
速率限制	遵守平台API Rate Limit，实现限流保护

4.2 浏览器自动化（Browser Automation）

技术	说明
无界面浏览器	Puppeteer / Playwright / Selenium
操作模拟	点击、输入、滚动、表单提交等用户行为模拟
数据提取	DOM解析、XPath/CSS选择器、数据抓取
异常处理	页面变化检测、验证码识别、反爬策略应对

4.3 适配器模式（Adapter Pattern）

组件	说明
统一接口	IPlatformAdapter 接口定义标准操作
平台实现	每个平台独立实现适配器（Platform-specific Adapter）
数据标准化	统一数据模型，标准化输出格式
错误处理	平台特定错误捕获、转换、上报

4.4 Agent平台调用示例

// 使用平台适配器同步商品
async function syncProducts(storeId, platform) {
  const adapter = platformAdapterFactory.createAdapter(platform);
  try {
    // 授权
    await adapter.authorize(getAuthInfo(storeId));
    
    // 获取商品列表
    const products = await adapter.getProducts(100, 0);
    
    // 处理商品数据
    const processedProducts = processProducts(products);
    
    // 回传数据
    await sendToBackend({
      type: 'products_synced',
      storeId,
      products: processedProducts
    });
  } catch (error) {
    // 处理错误
    await sendToBackend({
      type: 'error',
      storeId,
      error: error.message
    });
  }
}

5. 远程人工交互互通

5.1 实时屏幕传输（Real-time Screen Streaming）

技术	说明
屏幕捕获	使用 Puppeteer / Playwright 捕获浏览器屏幕
编码压缩	JPEG / WEBP / H.264 编码，降低传输带宽
实时传输	WebSocket / WebRTC 实时传输屏幕数据
前端渲染	Canvas / Video 元素渲染远程屏幕

5.2 操作指令传输（Remote Control）

环节	说明
操作捕获	前端捕获用户点击、输入、滚动等操作
坐标映射	将前端坐标转换为远程浏览器坐标（Resolution Mapping）
指令传输	WebSocket 传输操作指令到 Agent
指令执行	Agent 在远程浏览器执行操作指令

5.3 会话管理（Session Management）

功能	说明
会话创建	后端创建远程交互会话，分配资源
权限验证	验证用户权限，确保操作安全
状态跟踪	会话状态机：初始化 → 活跃 → 空闲 → 结束
资源清理	会话结束时清理资源，保存操作日志

5.4 远程交互示例

// 前端捕获点击操作
const handleCanvasClick = (e) => {
  const rect = canvas.getBoundingClientRect();
  const x = e.clientX - rect.left;
  const y = e.clientY - rect.top;
  
  // 发送点击指令
  ws.send(JSON.stringify({
    type: 'user_action',
    action: {
      type: 'click',
      x,
      y
    }
  }));
};

// Agent执行操作指令
const handleUserAction = async (page, action) => {
  switch (action.type) {
    case 'click':
      await page.mouse.click(action.x, action.y);
      break;
    case 'type':
      await page.keyboard.type(action.text);
      break;
    case 'keypress':
      await page.keyboard.press(action.key);
      break;
  }
};

6. 多Agent互通

6.1 Agent管理服务（Agent Management Service）

功能	说明
Agent注册	Agent启动时向管理服务注册，上报元数据
资源分配	根据店铺需求、任务类型分配Agent资源
负载均衡	基于负载的任务分发（Load Balancing）
健康监控	实时监控Agent健康状态、性能指标

6.2 Agent间通信（Inter-Agent Communication）

场景	说明
任务协调	避免多Agent操作同一店铺产生冲突
资源共享	共享配置、状态信息、缓存数据
故障转移	Agent故障时自动转移任务（Failover）

6.3 多VPS部署（Multi-VPS Deployment）

功能	说明
VPS管理	管理多VPS资源池，动态分配
IP隔离	同平台店铺使用不同IP，避免关联
网络配置	配置VPS网络、防火墙、代理
自动化部署	CI/CD自动化部署和配置Agent

6.4 Agent管理示例

// 分配任务到合适的Agent
function assignTask(task) {
  const store = getStoreById(task.storeId);
  
  if (store.requiresIpIsolation) {
    // 需要IP隔离的店铺，使用专用Agent
    return findDedicatedAgent(store);
  } else {
    // 不需要IP隔离的店铺，使用负载最低的Agent
    return findLeastLoadedAgent(store.platform);
  }
}

// 监控Agent健康状态
function monitorAgents() {
  setInterval(async () => {
    const agents = await getAllAgents();
    for (const agent of agents) {
      if (!agent.heartbeatReceived) {
        // Agent可能离线，触发故障转移
        await failoverAgent(agent.id);
      }
    }
  }, 30000); // 每30秒检查一次
}

7. 安全互通

7.1 认证与授权（Authentication & Authorization）

层级	机制	说明
API认证	JWT Token + Refresh Token	定期轮换，支持无感知续期
Agent认证	API Key + HMAC签名	基于密钥的双向认证
权限控制	RBAC（基于角色的访问控制）	角色-权限-资源三级管控
操作审计	Audit Log	全链路操作记录，支持追溯

7.2 数据安全（Data Security）

措施	说明
传输加密	TLS 1.3 / SSL，端到端加密
存储加密	AES-256-GCM 加密敏感数据
凭证管理	使用密钥管理服务（KMS），禁止明文存储
数据脱敏	API返回数据按需脱敏（PII保护）
访问控制	细粒度权限控制，最小权限原则

7.3 网络安全（Network Security）

措施	说明
TLS加密	所有通信强制使用TLS 1.3
防火墙	VPS防火墙 + 云防火墙双层防护
速率限制	API限流（Rate Limiting），防止滥用
DDoS防护	云厂商DDoS防护 + 应用层限流
IP白名单	关键接口限制访问IP范围

7.4 安全最佳实践

实践	说明
最小权限原则	Agent仅获取执行任务所需的最小权限
安全审计	定期安全审计，检查配置和代码
漏洞扫描	自动化漏洞扫描（SAST/DAST）
依赖管理	及时更新依赖，修复安全漏洞
密钥轮换	定期轮换API密钥和证书

8. 性能优化

8.1 通信优化

优化手段	说明
消息压缩	Gzip / Brotli 压缩传输数据，减少带宽使用
批量处理	批量发送和处理数据，减少请求次数（Batch Processing）
缓存策略	Redis 缓存常用数据，减少重复请求
异步处理	非关键操作异步处理，提高响应速度（Async/Await）
长连接	WebSocket 长连接，减少连接建立开销

8.2 资源优化

资源类型	优化措施
连接池	数据库连接池、HTTP连接池，复用连接
内存管理	优化内存使用，避免内存泄漏，定期GC
CPU优化	减少CPU密集型操作，使用Worker线程
磁盘I/O	减少磁盘I/O，使用内存缓存和SSD
网络I/O	合并请求，使用HTTP/2或HTTP/3

8.3 监控与调优

环节	说明
性能监控	APM工具（如Prometheus + Grafana）实时监控系统性能指标
瓶颈分析	识别性能瓶颈（CPU/内存/网络/磁盘），进行针对性优化
负载测试	使用JMeter/k6模拟高负载场景，测试系统性能
自动调优	根据负载自动调整系统参数（Auto-scaling）

9. 容错与灾备（Fault Tolerance & Disaster Recovery）

9.1 错误处理（Error Handling）

机制	说明
异常捕获	全局异常捕获，统一错误处理（Try-Catch + Global Handler）
错误重试	自动重试失败操作，支持指数退避（Exponential Backoff）
降级策略	服务降级（Degradation），保障核心功能可用
错误通知	实时告警通知（钉钉/飞书/邮件），及时响应

9.2 故障恢复（Fault Recovery）

措施	说明
数据备份	定期全量+增量备份，异地多副本存储
灾难恢复	制定DR计划，RPO<1小时，RTO<4小时
高可用性	多Agent部署，无单点故障（HA Architecture）
自动恢复	Agent故障自动重启，任务自动重分配

9.3 容灾方案（Disaster Recovery）

方案	说明
多区域部署	多可用区（AZ）部署，避免单点故障
数据同步	跨区域数据实时同步，确保数据一致性
故障转移	自动故障转移（Automatic Failover）
业务连续性	确保业务持续运行（Business Continuity）

10. 总结

系统互通是 Crawlful Hub 的核心设计之一，通过标准化的通信机制和接口，实现了前端控制台、后端服务、运营代理（Agent）和第三方平台之间的无缝互通。这种设计不仅提高了系统的可扩展性和可维护性，也为 100% AI 开发测试落地提供了坚实的技术基础。

在实际部署中，需要根据具体的业务需求和技术环境，选择合适的互通方案，并不断优化和改进，以适应不断变化的业务需求和技术发展。

---

11. 互通规范

11.1 接口命名规范

项目	规范
API路径	RESTful风格，小写字母，单词间用连字符（kebab-case） 示例：/api/v1/product-management/products
方法命名	驼峰命名法（camelCase），动词+名词格式 示例：getProductList、createOrder
参数命名	驼峰命名法（camelCase），清晰表达参数含义 示例：pageSize、sortBy

11.2 消息格式规范

项目	规范
数据格式	所有通信使用 JSON 格式（application/json）
消息结构	统一包含 type、data、timestamp、traceId 等字段
错误处理	统一错误码和错误消息格式，支持国际化（i18n）

标准消息格式示例：

{
  "type": "event|data|error|heartbeat",
  "event": "task_completed|error|notification",
  "data": { /* 业务数据 */ },
  "timestamp": "2026-03-21T10:30:00Z",
  "traceId": "trace-123456",
  "code": 200,
  "message": "success"
}

11.3 安全规范

• 认证：所有API调用必须进行身份认证
• 授权：基于角色的访问控制
• 加密：所有传输数据必须加密
• 审计：所有操作必须记录审计日志

11.4 性能规范

• 响应时间：API响应时间不超过500ms
• 并发处理：支持高并发请求
• 缓存策略：合理使用缓存减少响应时间
• 批量处理：支持批量操作减少请求次数

12. 互通示例

12.1 完整业务流程示例

商品采集流程

1. 前端：用户选择平台，设置采集参数
2. 后端：ProductController接收请求，调用ProductService
3. 后端：ProductService生成采集任务，发送到消息队列
4. Agent：接收任务，调用对应平台Adapter执行采集
5. Agent：回传采集结果到后端
6. 后端：ProductService处理采集结果，存储到数据库
7. 后端：通过WebSocket推送采集结果到前端
8. 前端：展示采集结果，提供后续操作入口

自动上架流程

1. 前端：用户设置上架参数，触发自动上架
2. 后端：AutoListingController接收请求，调用AutoListingService
3. 后端：AutoListingService生成上架任务，发送到消息队列
4. Agent：接收任务，调用平台Adapter执行上架
5. Agent：回传上架结果和截图到后端
6. 后端：AutoListingService更新任务状态，存储上架结果
7. 后端：通过WebSocket推送上架结果到前端
8. 前端：展示上架状态，提供效果分析

13. 未来扩展

13.1 微服务架构

• 服务拆分：将核心服务拆分为独立的微服务
• 服务发现：使用服务发现机制管理服务实例
• 负载均衡：自动负载均衡提高系统可用性
• 容错机制：服务降级和熔断保护

13.2 事件驱动架构

• 事件总线：使用消息队列实现事件驱动
• 事件溯源：通过事件记录系统状态变更
• CQRS：命令查询责任分离，提高系统性能

13.3 边缘计算

• 边缘Agent：在边缘节点部署Agent，减少延迟
• 本地处理：部分计算在本地完成，减少网络传输
• 智能调度：根据网络状况和负载自动调度任务