# Spear 项目架构概述

## 项目简介
Spear 是一个用 Rust 构建的分布式无服务器计算平台，旨在跨多个运行时环境（包括 WASM、Docker 和原生进程）提供可扩展的函数执行。

## 核心架构

### 1. SMS (Spear 管理服务)
负责以下功能的中央管理层：
- **节点管理**: 计算节点的注册、健康监控和生命周期管理
- **资源管理**: 跨集群的计算资源跟踪和分配
- **任务管理**: 执行任务的注册、调度和协调

#### 关键组件:
- `NodeService`: 处理节点注册、心跳和状态管理
- `ResourceService`: 管理资源分配和监控
- `TaskService`: 协调任务分发和执行跟踪

### 2. Spearlet (执行节点)
执行函数和任务的独立计算节点：
- **函数执行**: 支持多运行时的直接函数调用
- **实例管理**: 基于池的实例生命周期管理
- **资源监控**: 实时资源使用跟踪和报告

#### 关键组件:
- `FunctionService`: 用于函数调用和管理的 gRPC 服务
- `TaskExecutionManager`: 跨运行时环境协调任务执行
- `InstancePool`: 管理可重用的执行实例以优化性能
- `RuntimeManager`: 抽象不同的执行环境（WASM、Docker、Process）

## 运行时支持

### 1. WASM 运行时
- **安全性**: 沙箱执行环境
- **性能**: 快速启动和低开销
- **资源限制**: 可配置的 CPU 和内存约束
- **验证**: 全面的配置验证

### 2. Docker 运行时
- **隔离**: 基于容器的执行环境
- **灵活性**: 支持复杂的依赖和环境
- **可扩展性**: 动态容器生命周期管理

### 3. 进程运行时
- **原生性能**: 直接进程执行
- **系统集成**: 需要时的完整系统访问
- **遗留支持**: 与现有应用程序的兼容性

## 关键特性

### 分布式架构
- **水平扩展**: 动态添加计算节点
- **负载分发**: 跨节点的智能任务分发
- **容错性**: 优雅处理节点故障

### 多运行时支持
- **运行时抽象**: 跨不同执行环境的统一接口
- **配置管理**: 每个运行时的配置和验证
- **资源管理**: 运行时特定的资源限制和监控

### gRPC API
- **高性能**: 用于服务间通信的高效二进制协议
- **类型安全**: 协议缓冲区定义确保 API 一致性
- **流支持**: 实时执行监控和日志记录

### 资源管理
- **动态分配**: 实时资源分配和释放
- **监控**: 全面的资源使用跟踪
- **限制执行**: 每次执行的可配置资源限制

## 数据流

### 函数调用流程
1. **请求接收**: Spearlet 接收函数调用请求
2. **运行时选择**: 根据函数要求确定适当的运行时
3. **实例分配**: 从池中获取或创建执行实例
4. **执行**: 在选定的运行时环境中执行函数
5. **结果收集**: 收集执行结果和资源使用指标
6. **响应**: 将结果和执行元数据返回给客户端

### 任务管理流程
1. **任务注册**: SMS 从客户端接收任务注册
2. **资源规划**: 分析资源需求和可用性
3. **节点选择**: 根据资源和负载选择最优执行节点
4. **任务分发**: 将任务发送到选定的 Spearlet 执行
5. **执行监控**: 跟踪任务进度和资源使用
6. **结果聚合**: 收集和存储执行结果

## 配置管理

### 分层配置
- **全局设置**: 系统范围的配置参数
- **服务特定**: 单个服务配置（SMS、Spearlet）
- **运行时特定**: 每个运行时的配置和限制
- **实例级别**: 每个执行实例的配置

### 存储后端
- **内存**: 用于开发和测试的内存存储
- **RocksDB**: 用于生产的高性能嵌入式数据库
- **Sled**: 替代的嵌入式数据库选项

## API 设计

### RESTful HTTP API
- **网关集成**: 用于外部客户端访问的 HTTP 网关
- **OpenAPI 文档**: 带有 Swagger UI 的全面 API 文档
- **内容协商**: 支持多种内容类型

### gRPC 服务
- **内部通信**: 高性能的服务间通信
- **流式传输**: 用于监控和日志记录的实时数据流
- **错误处理**: 全面的错误处理和状态报告

## 测试策略

### 单元测试
- **组件隔离**: 使用模拟的单个组件测试
- **运行时验证**: 全面的运行时配置测试
- **错误场景**: 测试错误处理和边缘情况

### 集成测试
- **服务集成**: 端到端服务通信测试
- **运行时集成**: 多运行时执行测试
- **资源管理**: 资源分配和清理测试

### 性能测试
- **负载测试**: 高并发执行测试
- **资源监控**: 性能指标收集和分析
- **可扩展性测试**: 多节点部署测试

## 安全考虑

### 执行隔离
- **沙箱**: WASM 和基于容器的隔离
- **资源限制**: 严格的资源使用执行
- **网络隔离**: 执行的受控网络访问

### API 安全
- **身份验证**: 服务到服务的身份验证
- **授权**: 基于角色的访问控制
- **输入验证**: 全面的输入清理

## 监控和可观测性

### 指标收集
- **执行指标**: 函数执行时间、成功/失败率
- **资源指标**: CPU、内存、磁盘和网络使用
- **系统指标**: 节点健康、服务可用性

### 日志记录
- **结构化日志**: 用于分析的 JSON 格式日志
- **分布式跟踪**: 跨服务的请求跟踪
- **错误跟踪**: 全面的错误日志记录和警报

## 未来路线图

### 计划增强
- **自动扩展**: 基于负载的自动节点扩展
- **高级调度**: 基于机器学习的任务调度优化
- **多云支持**: 跨多个云提供商的部署
- **增强安全**: 高级隔离和安全功能

### 性能优化
- **冷启动减少**: 实例预热和预分配
- **网络优化**: 高级网络和缓存
- **资源优化**: 智能资源分配算法