wurenzhi
2b86715c09
- 移除未使用的TabPane组件 - 修复类型定义和导入方式 - 优化mock数据源的环境变量判断逻辑 - 更新文档结构并归档旧文件 - 添加新的UI组件和Memo组件 - 调整API路径和响应处理
557 lines
19 KiB
Markdown
557 lines
19 KiB
Markdown
# 系统互通架构（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格式，统一错误处理 |
|
||
| **响应格式** | 统一响应体结构 |
|
||
|
||
**标准响应格式**：
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": { /* 业务数据 */ },
|
||
"timestamp": "2026-03-21T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
### 2.2 WebSocket通信
|
||
|
||
| 功能 | 说明 |
|
||
|------|------|
|
||
| **实时数据推送** | 店铺状态、任务进度、操作结果实时同步 |
|
||
| **事件通知** | 操作完成、异常告警、系统通知 |
|
||
| **心跳保活** | 保持连接活跃，支持断线重连机制 |
|
||
|
||
**WebSocket消息格式**：
|
||
```json
|
||
{
|
||
"type": "event|data|heartbeat",
|
||
"event": "task_completed|error|notification",
|
||
"payload": { /* 消息内容 */ },
|
||
"timestamp": "2026-03-21T10:30:00Z"
|
||
}
|
||
```
|
||
|
||
### 2.3 前端API调用示例
|
||
```typescript
|
||
// 绑定店铺
|
||
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消息格式 |
|
||
|
||
**任务下发消息格式**：
|
||
```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调用示例
|
||
```typescript
|
||
// 向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平台调用示例
|
||
```typescript
|
||
// 使用平台适配器同步商品
|
||
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 远程交互示例
|
||
```typescript
|
||
// 前端捕获点击操作
|
||
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管理示例
|
||
```typescript
|
||
// 分配任务到合适的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）<br>示例：`/api/v1/product-management/products` |
|
||
| **方法命名** | 驼峰命名法（camelCase），动词+名词格式<br>示例：`getProductList`、`createOrder` |
|
||
| **参数命名** | 驼峰命名法（camelCase），清晰表达参数含义<br>示例：`pageSize`、`sortBy` |
|
||
|
||
### 11.2 消息格式规范
|
||
|
||
| 项目 | 规范 |
|
||
|------|------|
|
||
| **数据格式** | 所有通信使用 JSON 格式（application/json） |
|
||
| **消息结构** | 统一包含 `type`、`data`、`timestamp`、`traceId` 等字段 |
|
||
| **错误处理** | 统一错误码和错误消息格式，支持国际化（i18n） |
|
||
|
||
**标准消息格式示例**：
|
||
```json
|
||
{
|
||
"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，减少延迟
|
||
- **本地处理**：部分计算在本地完成，减少网络传输
|
||
- **智能调度**：根据网络状况和负载自动调度任务 |