傅洋

Retire-Cluster 系统架构

概述

Retire-Cluster 是一个分布式系统，旨在将闲置设备重新利用为统一的计算集群。该架构遵循主从模式，具有智能任务调度和实时监控功能。

系统架构

┌─────────────────────────────────────────────────────────────┐
│                         主节点                               │
│                    (NAS / 常开服务器)                        │
│                                                              │
│  ┌────────────────────────────────────────────────────┐     │
│  │              核心组件                               │     │
│  │                                                     │     │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │     │
│  │  │设备注册表    │  │任务调度器    │  │心跳监控  │ │     │
│  │  │& 元数据管理  │  │& 队列管理    │  │器        │ │     │
│  │  └──────────────┘  └──────────────┘  └──────────┘ │     │
│  │                                                     │     │
│  │  ┌──────────────────────────────────────────────┐  │     │
│  │  │             通信层                          │  │     │
│  │  │  - TCP 套接字服务器 (端口 8080)            │  │     │
│  │  │  - JSON 消息协议                           │  │     │
│  │  │  - 连接池管理                              │  │     │
│  │  └──────────────────────────────────────────────┘  │     │
│  └────────────────────────────────────────────────────┘     │
│                                                              │
│  ┌────────────────────────────────────────────────────┐     │
│  │                Web仪表板                           │     │
│  │                                                     │     │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │     │
│  │  │CLI界面       │  │终端UI        │  │REST API  │ │     │
│  │  │(xterm.js)    │  │渲染器        │  │端点      │ │     │
│  │  └──────────────┘  └──────────────┘  └──────────┘ │     │
│  │                                                     │     │
│  │  ┌──────────────────────────────────────────────┐  │     │
│  │  │            Flask Web服务器                   │  │     │
│  │  │  - 多格式API (JSON/CSV/文本)                │  │     │
│  │  │  - 服务器发送事件 (SSE)                     │  │     │
│  │  │  - 实时流式传输                             │  │     │
│  │  └──────────────────────────────────────────────┘  │     │
│  └────────────────────────────────────────────────────┘     │
│                                                              │
│  ┌────────────────────────────────────────────────────┐     │
│  │              数据持久化                             │     │
│  │                                                     │     │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────┐ │     │
│  │  │SQLite        │  │配置文件      │  │日志文件  │ │     │
│  │  │数据库        │  │JSON格式      │  │轮转      │ │     │
│  │  └──────────────┘  └──────────────┘  └──────────┘ │     │
│  └────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────┘
                              ↕ TCP/JSON
                     网络通信
                              ↕ 心跳/任务
┌─────────────────────────────────────────────────────────────┐
│                        工作节点                              │
│                   (分布式设备)                               │
│                                                              │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐     │
│  │   Android     │  │   旧笔记本    │  │ 树莓派       │     │
│  │   设备        │  │   / 台式机    │  │   / IoT      │     │
│  │              │  │              │  │              │     │
│  │ ┌──────────┐ │  │ ┌──────────┐ │  │ ┌──────────┐ │     │
│  │ │Termux    │ │  │ │Linux/Win │ │  │ │Linux ARM │ │     │
│  │ │Python    │ │  │ │Python    │ │  │ │Python    │ │     │
│  │ └──────────┘ │  │ └──────────┘ │  │ └──────────┘ │     │
│  │              │  │              │  │              │     │
│  │ ┌──────────┐ │  │ ┌──────────┐ │  │ ┌──────────┐ │     │
│  │ │设备      │ │  │ │系统      │ │  │ │硬件      │ │     │
│  │ │分析器    │ │  │ │监控器    │ │  │ │接口      │ │     │
│  │ └──────────┘ │  │ └──────────┘ │  │ └──────────┘ │     │
│  │              │  │              │  │              │     │
│  │ ┌──────────┐ │  │ ┌──────────┐ │  │ ┌──────────┐ │     │
│  │ │任务      │ │  │ │任务      │ │  │ │任务      │ │     │
│  │ │执行器    │ │  │ │执行器    │ │  │ │执行器    │ │     │
│  │ └──────────┘ │  │ └──────────┘ │  │ └──────────┘ │     │
│  └──────────────┘  └──────────────┘  └──────────────┘     │
└─────────────────────────────────────────────────────────────┘

核心组件

主节点组件

1. 设备注册表 & 元数据管理器

目的: 集中式设备信息存储和管理
职责:
- 设备注册和注销
- 能力跟踪（CPU、内存、平台、服务）
- 设备角色管理（计算、移动、存储等）
- SQLite数据库中的元数据持久化

class DeviceRegistry:
    def register_device(self, device_info: DeviceInfo) -> bool
    def update_device_status(self, device_id: str, status: DeviceStatus)
    def get_devices_by_capability(self, requirements: TaskRequirements) -> List[Device]
    def mark_device_offline(self, device_id: str, reason: str)

2. 任务调度器 & 队列管理器

目的: 智能任务分发和执行管理
特性:
- 基于优先级的任务队列
- 设备能力匹配
- 负载均衡算法
- 任务超时和重试机制
- 容错和故障转移

class TaskScheduler:
    def submit_task(self, task: Task) -> str  # 返回 task_id
    def schedule_task(self, task: Task) -> Optional[Device]
    def handle_task_completion(self, task_id: str, result: TaskResult)
    def handle_device_failure(self, device_id: str)

3. 心跳监控器

目的: 实时设备健康监控和故障检测
特性:
- 定期心跳收集（60秒间隔）
- 设备离线检测（300秒超时）
- 自动故障转移和任务重新分配
- 性能指标聚合

class HeartbeatMonitor:
    def process_heartbeat(self, device_id: str, metrics: SystemMetrics)
    def check_device_timeouts(self) -> List[str]  # 返回离线设备
    def update_cluster_metrics(self)

4. 通信层

协议: TCP套接字与JSON消息传递
特性:
- 异步连接处理
- 消息类型路由和验证
- 连接池管理
- 错误处理和恢复

class ClusterServer:
    def start_server(self, host: str, port: int)
    def handle_client_connection(self, client_socket: socket.socket)
    def process_message(self, message: Message) -> Response
    def broadcast_message(self, message: Message, target_devices: List[str])

Web仪表板组件

1. CLI界面 (xterm.js)

目的: 用于集群管理的终端风格Web界面
特性:
- 使用xterm.js的完整终端仿真
- 命令自动完成和历史记录
- 实时命令执行
- 多主题支持（Matrix、琥珀色、蓝色）

2. 终端UI渲染器

目的: CLI输出的ASCII艺术和表格渲染
特性:
- ASCII表格生成
- 进度条和状态指示器
- 设备网格可视化
- 日志条目格式化
- 彩色编码输出

3. REST API层

目的: 为人机和机器访问提供多格式API
端点:
- /text/* - 纯文本、CSV、TSV格式（AI友好）
- /api/v1/* - 编程访问的JSON API
- /stream/* - 实时更新的服务器发送事件

# 文本API示例
GET /text/devices              # 管道分隔的设备列表
GET /text/status               # 键值对集群状态
GET /text/metrics              # Prometheus格式指标

# JSON API示例
GET /api/v1/devices            # 结构化设备数据
POST /api/v1/command           # 执行CLI命令
GET /api/v1/cluster/status     # 集群信息

# 流式API示例
GET /stream/devices            # 实时设备更新
GET /stream/logs               # 实时日志流

工作节点组件

1. 设备分析器

目的: 自动硬件和软件能力检测
检测能力:
- 系统信息（操作系统、架构、Python版本）
- 硬件资源（CPU核心、内存、磁盘空间）
- 网络配置
- 可用服务和工具
- 平台特定功能

class DeviceProfiler:
    def get_system_info(self) -> SystemInfo
    def get_hardware_specs(self) -> HardwareSpecs
    def detect_capabilities(self) -> List[Capability]
    def get_performance_metrics(self) -> PerformanceMetrics

2. 系统监控器

目的: 持续资源监控和报告
收集指标:
- CPU使用率和负载平均值
- 内存利用率
- 磁盘I/O和空间使用
- 网络统计
- 温度和电池状态（移动设备）

3. 任务执行器

目的: 执行分配的任务并报告结果
特性:
- 沙盒任务执行
- 资源限制强制执行
- 进度报告
- 错误处理和恢复
- 平台特定优化

class TaskExecutor:
    def execute_task(self, task: Task) -> TaskResult
    def monitor_task_progress(self, task_id: str) -> ProgressReport
    def cancel_task(self, task_id: str) -> bool
    def cleanup_task_resources(self, task_id: str)

通信协议

消息类型

系统使用基于JSON的消息协议通过TCP套接字进行通信：

1. 注册消息

{
  "message_type": "register",
  "sender_id": "device-001",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "device_info": {
      "hostname": "android-phone",
      "platform": "android",
      "architecture": "aarch64",
      "python_version": "3.11.0",
      "role": "mobile"
    },
    "hardware_specs": {
      "cpu_cores": 8,
      "memory_total": 8589934592,
      "disk_space": 128849018880,
      "network_interfaces": ["wlan0"]
    },
    "capabilities": [
      "computational",
      "network_services",
      "mobile_specific"
    ]
  }
}

2. 心跳消息

{
  "message_type": "heartbeat",
  "sender_id": "device-001",
  "timestamp": "2024-01-15T10:31:00Z",
  "data": {
    "system_metrics": {
      "cpu_usage": 25.5,
      "memory_usage": 45.2,
      "disk_usage": 12.8,
      "load_average": [0.5, 0.3, 0.2],
      "uptime": 86400
    },
    "status": "online",
    "active_tasks": 2,
    "last_activity": "2024-01-15T10:30:45Z"
  }
}

3. 任务分配消息

{
  "message_type": "task_assign",
  "sender_id": "main-node",
  "target_id": "device-001",
  "timestamp": "2024-01-15T10:32:00Z",
  "data": {
    "task": {
      "task_id": "task-abc123",
      "task_type": "python_eval",
      "priority": "normal",
      "timeout": 300,
      "payload": {
        "expression": "sum(range(100000))",
        "environment": {}
      },
      "requirements": {
        "min_cpu_cores": 2,
        "min_memory_gb": 1
      }
    }
  }
}

4. 任务结果消息

{
  "message_type": "task_result",
  "sender_id": "device-001",
  "timestamp": "2024-01-15T10:32:30Z",
  "data": {
    "task_id": "task-abc123",
    "status": "completed",
    "execution_time": 28.5,
    "result": {
      "output": "4999950000",
      "exit_code": 0,
      "metrics": {
        "cpu_time": 25.2,
        "memory_peak": 1048576
      }
    }
  }
}

连接管理

连接生命周期

客户端连接: 工作节点建立到主节点的TCP连接
注册: 工作节点发送设备信息和能力
心跳循环: 每60秒定期状态更新
任务执行: 双向任务分配和结果报告
优雅断开: 关闭时正确的连接清理

错误处理

连接丢失: 指数退避的自动重连
消息损坏: JSON验证和错误恢复
超时处理: 不同操作的可配置超时
资源清理: 错误时正确的资源清理

数据流

设备注册流程

工作节点                       主节点
     │                            │
     │──── TCP连接 ──────────────►│
     │◄─── 连接确认 ──────────────│
     │                            │
     │──── 注册消息 ──────────────►│
     │                            │ ┌─────────────────┐
     │                            │ │ 验证设备        │
     │                            │ │ 存储元数据      │
     │                            │ │ 更新注册表      │
     │                            │ └─────────────────┘
     │◄─── 注册确认 ──────────────│
     │                            │
     │──── 心跳循环 ──────────────►│

任务执行流程

主节点                        工作节点
     │                            │
     │ ┌─────────────────┐        │
     │ │ 接收任务        │        │
     │ │ 匹配设备        │        │
     │ │ 检查资源        │        │
     │ └─────────────────┘        │
     │                            │
     │──── 任务分配 ─────────────►│
     │                            │ ┌─────────────────┐
     │                            │ │ 验证任务        │
     │                            │ │ 安全执行        │
     │                            │ │ 监控进度        │
     │                            │ └─────────────────┘
     │◄─── 任务进度 ─────────────│
     │◄─── 任务结果 ─────────────│
     │                            │
     │ ┌─────────────────┐        │
     │ │ 处理结果        │        │
     │ │ 更新状态        │        │
     │ │ 通知客户端      │        │
     │ └─────────────────┘        │

实时监控流程

工作节点              主节点              Web仪表板
     │                   │                   │
     │──── 心跳数据 ────►│                   │
     │                   │ ┌─────────────────┐ │
     │                   │ │ 聚合指标        │ │
     │                   │ │ 更新状态        │ │
     │                   │ └─────────────────┘ │
     │                   │                   │
     │                   │◄─── API请求 ─────│
     │                   │──── SSE事件 ────►│
     │                   │──── JSON/文本数据 ►│

部署架构

单主机开发

┌─────────────────────────────────┐
│         开发主机                 │
│                                 │
│  ┌───────────┐ ┌─────────────┐  │
│  │主节点     │ │工作节点     │  │
│  │(终端1)    │ │(终端2)      │  │
│  └───────────┘ └─────────────┘  │
│                                 │
│  ┌─────────────────────────────┐ │
│  │      Web仪表板              │ │
│  │     (终端3/浏览器)          │ │
│  └─────────────────────────────┘ │
└─────────────────────────────────┘

分布式生产环境

┌─────────────────────┐         ┌──────────────────┐
│    NAS服务器         │         │   旧笔记本       │
│                     │         │                  │
│ ┌─────────────────┐ │         │ ┌──────────────┐ │
│ │ 主节点          │ │         │ │ 工作节点     │ │
│ │ (Docker)        │ │◄───────►│ │ (原生)       │ │
│ └─────────────────┘ │         │ └──────────────┘ │
│                     │         └──────────────────┘
│ ┌─────────────────┐ │         
│ │ Web仪表板       │ │         ┌──────────────────┐
│ │ (Docker)        │ │         │  Android手机     │
│ └─────────────────┘ │         │                  │
└─────────────────────┘         │ ┌──────────────┐ │
                                │ │ 工作节点     │ │
┌─────────────────────┐         │ │ (Termux)     │ │
│   树莓派            │         │ └──────────────┘ │
│                     │         └──────────────────┘
│ ┌─────────────────┐ │         
│ │ 工作节点        │ │         ┌──────────────────┐
│ │ (原生)          │ │         │   其他设备       │
│ └─────────────────┘ │         │                  │
└─────────────────────┘         │ ┌──────────────┐ │
                                │ │ 工作节点     │ │
                                │ │ (原生)       │ │
                                │ └──────────────┘ │
                                └──────────────────┘

基于Docker的生产环境（推荐）

┌─────────────────────────────────────────────────────────────┐
│                       NAS服务器                             │
│                                                             │
│  ┌────────────────────────────────────────────────────┐     │
│  │              Docker环境                             │     │
│  │                                                     │     │
│  │  ┌──────────────────────┐  ┌──────────────────┐   │     │
│  │  │    retire-cluster    │  │      nginx       │   │     │
│  │  │     main-node        │  │   反向代理       │   │     │
│  │  │                      │  │   (可选)         │   │     │
│  │  │ ┌──────────────────┐ │  │                  │   │     │
│  │  │ │  主节点          │ │  │                  │   │     │
│  │  │ │  (端口 8080)     │ │  │                  │   │     │
│  │  │ └──────────────────┘ │  │                  │   │     │
│  │  │                      │  │                  │   │     │
│  │  │ ┌──────────────────┐ │  │                  │   │     │
│  │  │ │  Web仪表板       │ │  │                  │   │     │
│  │  │ │  (端口 5000)     │ │  │                  │   │     │
│  │  │ └──────────────────┘ │  │                  │   │     │
│  │  └──────────────────────┘  └──────────────────┘   │     │
│  └────────────────────────────────────────────────────┘     │
│                                                             │
│  ┌────────────────────────────────────────────────────┐     │
│  │            持久化卷                                 │     │
│  │  /volume1/docker/retire-cluster/                   │     │
│  │  ├── config/    (配置文件)                         │     │
│  │  ├── database/  (SQLite数据库)                     │     │
│  │  └── logs/      (应用程序日志)                     │     │
│  └────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────┘

可扩展性和性能

水平扩展

工作节点: 无限数量的工作节点可以加入集群
负载分配: 基于设备能力的智能任务分配
容错性: 设备离线时自动故障转移

性能优化

连接池: 高效的TCP连接管理
异步处理: 处理多个连接的非阻塞I/O
数据库优化: WAL模式、索引和查询优化
缓存: 频繁访问数据的内存缓存

资源管理

内存限制: 任务执行的可配置内存限制
CPU限制: 防止任务消耗过多CPU
磁盘空间监控: 自动清理旧日志和临时文件
网络带宽: 心跳和数据传输的速率限制

安全架构

网络安全

内部网络: 专为可信内部网络设计
防火墙集成: 基于端口的访问控制
TLS/SSL: 未来支持加密通信

应用程序安全

输入验证: 所有消息的JSON模式验证
资源限制: 具有资源约束的沙盒任务执行
访问控制: 基于设备的访问控制和角色管理
审计日志: 所有操作的综合日志记录

容器安全（Docker）

非root执行: 容器以非特权用户运行
资源隔离: 强制执行CPU和内存限制
只读根: 可选的只读根文件系统
密钥管理: 安全处理配置和凭据

监控和可观察性

指标收集

系统指标: CPU、内存、磁盘、网络使用率
应用程序指标: 任务执行时间、成功率
集群指标: 设备数量、任务队列、吞吐量

日志策略

结构化日志: 带有关联ID的JSON格式日志
日志级别: 可配置的日志级别（DEBUG、INFO、WARN、ERROR）
日志轮转: 自动轮转和保留策略
集中日志: 转发日志到外部系统的选项

健康监控

健康检查: 服务健康验证的HTTP端点
警报: 故障和性能问题的可配置警报
仪表板: 实时集群可视化
指标导出: 兼容Prometheus的指标导出

未来架构增强

计划功能

多集群联邦: 连接多个集群
高级调度: 基于ML的任务放置优化
持久存储: 分布式文件系统集成
自动扩展: 动态工作节点配置
API网关: 集中API管理和安全

集成点

Kubernetes: 用于编排的原生Kubernetes操作器
云提供商: 与AWS、Azure、GCP集成
监控系统: Prometheus、Grafana、ELK堆栈集成
CI/CD管道: GitHub Actions、GitLab CI集成

该架构为Retire-Cluster系统提供了坚实的基础，同时保持了未来增强和可扩展性需求的灵活性。