Merge pull request #81 from aice030/feat/deploy

Erickw87 · web-flow · commit 5b521c872f0b · 2025-09-19T15:49:41.000+08:00
feat/77: 发布系统功能和接口设计文档
diff --git a/docs/deploy/README.md b/docs/deploy/README.md
@@ -0,0 +1,127 @@
+# 发布系统设计文档
+
+## 1. 系统概述
+
+### 1.1 设计目标
+发布系统是一个专注于执行发布动作的轻量级系统，负责：
+- 接收调度系统的发布指令
+- 执行具体的发布操作
+- 管理服务实例的版本状态
+- 提供回滚功能
+
+### 1.2 设计原则
+- **单一职责**：只负责发布动作的执行，不涉及调度逻辑
+- **简单可靠**：提供稳定、可预测的发布操作
+- **状态透明**：实时反馈发布状态和实例版本信息
+- **快速回滚**：支持单实例和批量回滚操作
+
+### 1.3 系统边界
+- **负责**：发布动作执行、实例状态管理、回滚操作
+- **不负责**：发布调度、批次规划、版本状态管理、实例选择、健康检查
+
+## 2. 系统架构
+
+### 2.1 整体架构
+```
+┌─────────────────┐    方法调用    ┌─────────────────┐    网络通信    ┌─────────────────┐
+│   调度系统       │ ──────────────▶ │   发布系统       │ ──────────────▶ │   实例节点       │
+│                 │                │                 │                │                 │
+│  • 发布指令     │                │  • 执行发布操作  │                │  • 服务实例       │
+│  • 批次规划     │                │  • 状态跟踪      │                │  • 版本更新      │
+│  • 健康检查     │                │  • 回滚操作      │                │  • 状态上报      │
+│                 │                │                 │                │                │
+└─────────────────┘                └─────────────────┘                └─────────────────┘
+                                             │
+                                             │ 数据存储
+                                             ▼
+                                    ┌─────────────────┐
+                                    │   数据库         │
+                                    │                 │
+                                    │  • 实例版本     │
+                                    │  • 回滚记录     │
+                                    │  • 状态信息     │
+                                    └─────────────────┘
+```
+
+### 2.2 核心组件
+
+- **发布执行器**: 执行发布操作，更新实例版本
+- **回滚执行器**: 执行回滚操作，处理包下载
+- **实例管理器**: 感知执行结果，维护实例状态
+
+## 3. 核心功能模块
+
+### 3.1 发布执行模块
+负责执行具体的发布操作，包括：
+- 接收发布请求（服务名、版本、实例列表）
+- 执行发布动作
+- 更新实例版本状态
+- 记录发布日志
+
+### 3.2 回滚模块
+提供回滚功能：
+- 接受回滚请求（服务名、回滚的目标版本、实例列表）
+- 执行回滚任务
+- 更新实例版本状态
+- 记录回滚日志
+
+### 3.3 实例管理模块
+获取实例状态：
+- 获取运行某服务的全部实例（可通过版本号过滤）
+- 获取实例的详细信息
+- 获取实例历史版本
+
+## 4. 接口设计
+
+发布系统提供以下外部接口：
+
+- **DeployService**: 发布服务接口，负责发布和回滚操作的执行
+- **InstanceManager**: 实例管理接口，负责实例信息查询和状态管理
+
+### 4.1 DeployService接口
+
+发布服务接口，负责发布和回滚操作的执行。
+
+```go
+type DeployService interface {
+    ExecuteDeployment(params *DeployParams) (*OperationResult, error)
+    ExecuteRollback(params *RollbackParams) (*OperationResult, error)
+}
+```
+
+#### 4.1.1 ExecuteDeployment方法
+
+触发指定服务版本的发布操作
+
+#### 4.1.2 ExecuteRollback方法
+
+对指定实例执行回滚操作，支持单实例或批量实例回滚
+
+### 4.2 InstanceManager接口
+
+实例管理接口，负责实例信息查询和状态管理，发布模块和服务管理模块都需要使用。
+
+```go
+type InstanceManager interface {
+    GetServiceInstances(serviceName string, version ...string) ([]*InstanceInfo, error)
+    GetInstanceVersionHistory(instanceID string) ([]*VersionInfo, error)
+}
+```
+
+#### 4.2.1 方法说明
+
+**GetServiceInstances**: 获取指定服务的实例详细信息，可选择按版本过滤
+
+**GetInstanceVersionHistory**: 获取指定实例的版本历史记录
+
+## 5. 内部工具函数
+
+**ValidatePackageURL**: 验证包URL的有效性和安全性
+
+**GetServiceInstanceIDs**: 根据服务名和版本获取实例ID列表，用于内部批量操作
+
+**GetInstanceHost**: 根据实例ID获取实例的IP地址
+
+**GetInstancePort**: 根据实例ID获取实例的端口号
+
+**CheckInstanceHealth**: 检查单个实例是否有响应，用于发布前验证目标实例的可用性
diff --git a/docs/deploy/interface.md b/docs/deploy/interface.md
@@ -0,0 +1,220 @@
+# 发布系统接口参考文档
+
+## 1. 接口概览
+
+发布系统提供以下外部接口：
+
+- **DeployService**: 发布服务接口，负责发布和回滚操作的执行
+- **InstanceManager**: 实例管理接口，负责实例信息查询和状态管理
+
+## 2. DeployService接口
+
+### 2.1 接口定义
+
+发布服务接口，负责发布和回滚操作的执行。
+
+```go
+type DeployService interface {
+    ExecuteDeployment(params *DeployParams) (*OperationResult, error)
+    ExecuteRollback(params *RollbackParams) (*OperationResult, error)
+}
+```
+
+### 2.2 ExecuteDeployment方法
+
+**方法描述**: 触发指定服务版本的发布操作
+
+**方法签名**:
+```go
+ExecuteDeployment(params *DeployParams) (*OperationResult, error)
+```
+
+**输入参数**:
+```go
+type DeployParams struct {
+    Service    string   `json:"service"`     // 必填，服务名称
+    Version    string   `json:"version"`     // 必填，目标版本号
+    Instances  []string `json:"instances"`   // 必填，实例ID列表
+    PackageURL string   `json:"package_url"` // 必填，包下载URL
+}
+```
+
+**返回结果**:
+```go
+type OperationResult struct {
+    Service        string   `json:"service"`         // 服务名称
+    Version        string   `json:"version"`         // 操作的目标版本
+    Instances      []string `json:"instances"`       // 实际操作的实例ID列表
+    TotalInstances int      `json:"total_instances"` // 操作的实例总数
+}
+```
+
+### 2.3 ExecuteRollback方法
+
+**方法描述**: 对指定实例执行回滚操作，支持单实例或批量实例回滚
+
+**方法签名**:
+```go
+ExecuteRollback(params *RollbackParams) (*OperationResult, error)
+```
+
+**输入参数**:
+```go
+type RollbackParams struct {
+    Service       string   `json:"service"`        // 必填，服务名称
+    TargetVersion string   `json:"target_version"` // 必填，目标版本号
+    Instances     []string `json:"instances"`      // 必填，实例ID列表
+    PackageURL    string   `json:"package_url"`    // 必填，包下载URL
+}
+```
+
+**返回结果**: `*OperationResult` - 使用通用的操作结果结构体
+
+## 3. InstanceManager接口
+
+### 3.1 接口定义
+
+实例管理接口，负责实例信息查询和状态管理，发布模块和服务管理模块都需要使用。
+
+```go
+type InstanceManager interface {
+    GetServiceInstances(serviceName string, version ...string) ([]*InstanceInfo, error)
+    GetInstanceVersionHistory(instanceID string) ([]*VersionInfo, error)
+}
+```
+
+### 3.2 数据结构定义
+
+**InstanceInfo结构体**:
+```go
+type InstanceInfo struct {
+    InstanceID  string `json:"instance_id"`  // 实例唯一标识符
+    ServiceName string `json:"service_name"` // 所属服务名称
+    Version     string `json:"version"`      // 当前运行的版本号
+    Status      string `json:"status"`       // 实例运行状态 - 'active'运行中；'pending'发布中；'error'出现故障
+}
+```
+
+**VersionInfo结构体**:
+```go
+type VersionInfo struct {
+    Version string `json:"version"` // 版本号
+    Status  string `json:"status"`  // 版本状态 - 'acitve'当前运行版本；'stable'稳定版本；'deprecated'已废弃版本
+}
+```
+
+### 3.3 GetServiceInstances方法
+
+**方法描述**: 获取指定服务的实例详细信息，可选择按版本过滤
+
+**方法签名**:
+```go
+GetServiceInstances(serviceName string, version ...string) ([]*InstanceInfo, error)
+```
+
+**输入参数**:
+```go
+serviceName string   // 必填，服务名称
+version     ...string // 选填，指定版本号进行过滤，未输入则默认获取全部版本的运行实例
+```
+
+**返回结果**: `[]*InstanceInfo` - 实例信息数组
+
+### 3.4 GetInstanceVersionHistory方法
+
+**方法描述**: 获取指定实例的版本历史记录
+
+**方法签名**:
+```go
+GetInstanceVersionHistory(instanceID string) ([]*VersionInfo, error)
+```
+
+**输入参数**:
+```go
+instanceID string // 必填，实例ID
+```
+
+**返回结果**: `[]*VersionInfo` - 版本历史数组
+
+## 4. 内部工具函数
+
+### 4.1 ValidatePackageURL函数
+
+**函数描述**: 验证是否能通过URL找到包
+
+**函数签名**:
+```go
+func ValidatePackageURL(packageURL string) error
+```
+
+**输入参数**:
+```go
+packageURL string // 必填，包下载URL
+```
+
+**返回结果**: `error` - 验证失败时返回错误信息
+
+### 4.2 GetServiceInstanceIDs函数
+
+**函数描述**: 根据服务名和版本获取实例ID列表，用于内部批量操作
+
+**函数签名**:
+```go
+func GetServiceInstanceIDs(serviceName string, version ...string) ([]string, error)
+```
+
+**输入参数**:
+```go
+serviceName string   // 必填，服务名称
+version     ...string // 选填，指定版本号进行过滤，未输入则默认获取全部版本的运行实例
+```
+
+**返回结果**: `[]string` - 实例ID数组
+
+### 4.3 GetInstanceHost函数
+
+**函数描述**: 根据实例ID获取实例的IP地址
+
+**函数签名**:
+```go
+func GetInstanceHost(instanceID string) (string, error)
+```
+
+**输入参数**:
+```go
+instanceID string // 必填，实例ID
+```
+
+**返回结果**: `string` - 实例的IP地址，获取失败时返回错误信息
+
+### 4.4 GetInstancePort函数
+
+**函数描述**: 根据实例ID获取实例的端口号
+
+**函数签名**:
+```go
+func GetInstancePort(instanceID string) (int, error)
+```
+
+**输入参数**:
+```go
+instanceID string // 必填，实例ID
+```
+
+**返回结果**: `int` - 实例的端口号，获取失败时返回错误信息
+
+### 4.5 CheckInstanceHealth函数
+
+**函数描述**: 检查单个实例是否有响应，用于发布前验证目标实例的可用性
+
+**函数签名**:
+```go
+func CheckInstanceHealth(instanceID string) (bool, error)
+```
+
+**输入参数**:
+```go
+instanceID string // 必填，实例ID
+```
+
+**返回结果**: `bool` - 健康检查结果，true表示实例有响应，false表示无响应
