Merge remote-tracking branch 'qiniu/develop'

Author: aice030

docs/deploy/README.md

@@ -26,8 +26,8 @@
 ┌─────────────────┐    方法调用    ┌─────────────────┐    网络通信    ┌─────────────────┐
 │   调度系统       │ ──────────────▶ │   发布系统       │ ──────────────▶ │   实例节点       │
 │                 │                │                 │                │                 │
-│  • 发布指令     │                │  • 执行发布操作  │                │  • 服务实例       │
-│  • 批次规划     │                │  • 状态跟踪      │                │  • 版本更新      │
+│  • 发布指令     │                │  • 发布操作      │                │  • 服务实例       │
+│  • 批次规划     │                │  • 实例管理      │                │  • 版本更新      │
 │  • 健康检查     │                │  • 回滚操作      │                │  • 状态上报      │
 │                 │                │                 │                │                │
 └─────────────────┘                └─────────────────┘                └─────────────────┘
@@ -80,25 +80,30 @@
 
 ### 4.1 DeployService接口
 
+#### 4.1.1 接口定义
+
 发布服务接口，负责发布和回滚操作的执行。
 
 ```go
 type DeployService interface {
-    ExecuteDeployment(params *DeployParams) (*OperationResult, error)
+    DeployNewService(params *DeployNewServiceParams) (*OperationResult, error)
+    DeployNewVersion(params *DeployNewVersionParams) (*OperationResult, error)
     ExecuteRollback(params *RollbackParams) (*OperationResult, error)
 }
 ```
 
-#### 4.1.1 ExecuteDeployment方法
+#### 4.1.2 方法说明
 
-触发指定服务版本的发布操作
+**DeployNewService方法**: 部署新服务并创建指定数量的实例
 
-#### 4.1.2 ExecuteRollback方法
+**DeployNewVersion方法**: 触发指定服务版本的发布操作
 
-对指定实例执行回滚操作，支持单实例或批量实例回滚
+**ExecuteRollback方法**: 对指定实例执行回滚操作，支持单实例或批量实例回滚
 
 ### 4.2 InstanceManager接口
 
+#### 4.2.1 接口定义
+
 实例管理接口，负责实例信息查询和状态管理，发布模块和服务管理模块都需要使用。
 
 ```go
@@ -108,20 +113,70 @@ type InstanceManager interface {
 }
 ```
 
-#### 4.2.1 方法说明
+#### 4.2.2 方法说明
 
-**GetServiceInstances**: 获取指定服务的实例详细信息，可选择按版本过滤
+**GetServiceInstances方法**: 获取指定服务的实例详细信息，可选择按版本过滤
 
-**GetInstanceVersionHistory**: 获取指定实例的版本历史记录
+**GetInstanceVersionHistory方法**: 获取指定实例的版本历史记录
 
 ## 5. 内部工具函数
 
-**ValidatePackageURL**: 验证包URL的有效性和安全性
+### 5.1 **ValidatePackageURL**: 验证包URL的有效性
+```go
+func ValidatePackageURL(packageURL string) error
+```
 
-**GetServiceInstanceIDs**: 根据服务名和版本获取实例ID列表，用于内部批量操作
+### 5.2 **GetServiceInstanceIDs**: 根据服务名和版本获取实例ID列表
+```go
+func GetServiceInstanceIDs(serviceName string, version ...string) ([]string, error)
+```
 
-**GetInstanceHost**: 根据实例ID获取实例的IP地址
+### 5.3 **GetInstanceIP**: 根据实例ID获取实例的IP地址
+```go
+func GetInstanceIP(instanceID string) (string, error)
+```
 
-**GetInstancePort**: 根据实例ID获取实例的端口号
+### 5.4 **GetInstancePort**: 根据实例ID获取实例的端口号
+```go
+func GetInstancePort(instanceID string) (int, error)
+```
+
+### 5.5 **CheckInstanceHealth**: 检查实例的健康状态
+```go
+func CheckInstanceHealth(instanceID string) (bool, error)
+```
 
-**CheckInstanceHealth**: 检查单个实例是否有响应，用于发布前验证目标实例的可用性
+### 5.6 **GetAvailableHosts**: 获取所有可用的主机列表
+```go
+func GetAvailableHosts() ([]string, error)
+```
+
+### 5.7 **GetHostIp**: 根据主机名获取主机IP地址
+```go
+func GetHostIp(hostName string) (string, error)
+```
+
+### 5.8 **CheckHostHealth**: 检查主机的健康状态
+```go
+func CheckHostHealth(hostIpAddress string) (bool, error)
+```
+
+### 5.9 **SelectHostForNewInstance**: 为新实例选择合适的主机
+```go
+func SelectHostForNewInstance(availableHosts []string, service string, version string) (string, error)
+```
+
+### 5.10 **GenerateInstanceID**: 根据服务名生成实例ID
+```go
+func GenerateInstanceID(serviceName string) (string, error)
+```
+
+### 5.11 **GenerateInstanceIP**: 生成实例IP地址
+```go
+func GenerateInstanceIP() (string, error)
+```
+
+### 5.12 **GenerateInstance**: 创建实例
+```go
+func GenerateInstance(instanceID string, instanceIP string) error
+```

docs/deploy/interface.md

@@ -15,31 +15,45 @@
 
 ```go
 type DeployService interface {
-    ExecuteDeployment(params *DeployParams) (*OperationResult, error)
+    DeployNewService(params *DeployNewServiceParams) (*OperationResult, error)
+    DeployNewVersion(params *DeployNewVersionParams) (*OperationResult, error)
     ExecuteRollback(params *RollbackParams) (*OperationResult, error)
 }
 ```
 
-### 2.2 ExecuteDeployment方法
+### 2.2 结构体定义
 
-**方法描述**: 触发指定服务版本的发布操作
-
-**方法签名**:
+**DeployNewServiceParams结构体**:
 ```go
-ExecuteDeployment(params *DeployParams) (*OperationResult, error)
+type DeployNewServiceParams struct {
+    Service    string   `json:"service"`     // 必填，服务名称
+    Version    string   `json:"version"`     // 必填，目标版本号
+    totalNum   int      `json:"totalNum"`    // 必填，新建实例数量
+    PackageURL string   `json:"package_url"` // 必填，包下载URL
+}
 ```
 
-**输入参数**:
+**DeployNewVersionParams结构体**:
 ```go
-type DeployParams struct {
+type DeployNewVersionParams struct {
     Service    string   `json:"service"`     // 必填，服务名称
     Version    string   `json:"version"`     // 必填，目标版本号
     Instances  []string `json:"instances"`   // 必填，实例ID列表
     PackageURL string   `json:"package_url"` // 必填，包下载URL
 }
 ```
 
-**返回结果**:
+**RollbackParams结构体**:
+```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结构体**:
 ```go
 type OperationResult struct {
     Service        string   `json:"service"`         // 服务名称
@@ -49,26 +63,44 @@ type OperationResult struct {
 }
 ```
 
-### 2.3 ExecuteRollback方法
+### 2.3 DeployNewService方法
 
-**方法描述**: 对指定实例执行回滚操作，支持单实例或批量实例回滚
+**方法描述**: 部署新服务并创建指定数量的实例
 
 **方法签名**:
 ```go
-ExecuteRollback(params *RollbackParams) (*OperationResult, error)
+DeployNewService(params *DeployNewServiceParams) (*OperationResult, error)
 ```
 
-**输入参数**:
+**输入参数**: `*DeployNewServiceParams` - 新服务部署参数
+
+**返回结果**: `*OperationResult` - 操作结果
+
+### 2.4 DeployNewVersion方法
+
+**方法描述**: 触发指定服务版本的发布操作
+
+**方法签名**:
 ```go
-type RollbackParams struct {
-    Service       string   `json:"service"`        // 必填，服务名称
-    TargetVersion string   `json:"target_version"` // 必填，目标版本号
-    Instances     []string `json:"instances"`      // 必填，实例ID列表
-    PackageURL    string   `json:"package_url"`    // 必填，包下载URL
-}
+DeployNewVersion(params *DeployNewVersionParams) (*OperationResult, error)
 ```
 
-**返回结果**: `*OperationResult` - 使用通用的操作结果结构体
+**输入参数**: `*DeployNewVersionParams` - 版本发布参数
+
+**返回结果**: `*OperationResult` - 操作结果
+
+### 2.5 ExecuteRollback方法
+
+**方法描述**: 对指定实例执行回滚操作，支持单实例或批量实例回滚
+
+**方法签名**:
+```go
+ExecuteRollback(params *RollbackParams) (*OperationResult, error)
+```
+
+**输入参数**: `*RollbackParams` - 回滚参数
+
+**返回结果**: `*OperationResult` - 操作结果
 
 ## 3. InstanceManager接口
 
@@ -83,7 +115,7 @@ type InstanceManager interface {
 }
 ```
 
-### 3.2 数据结构定义
+### 3.2 结构体定义
 
 **InstanceInfo结构体**:
 ```go
@@ -136,6 +168,7 @@ instanceID string // 必填，实例ID
 
 **返回结果**: `[]*VersionInfo` - 版本历史数组
 
+
 ## 4. 内部工具函数
 
 ### 4.1 ValidatePackageURL函数
@@ -171,13 +204,13 @@ version     ...string // 选填，指定版本号进行过滤，未输入则默
 
 **返回结果**: `[]string` - 实例ID数组
 
-### 4.3 GetInstanceHost函数
+### 4.3 GetInstanceIP函数
 
 **函数描述**: 根据实例ID获取实例的IP地址
 
 **函数签名**:
 ```go
-func GetInstanceHost(instanceID string) (string, error)
+func GetInstanceIP(instanceID string) (string, error)
 ```
 
 **输入参数**:
@@ -218,3 +251,112 @@ instanceID string // 必填，实例ID
 ```
 
 **返回结果**: `bool` - 健康检查结果，true表示实例有响应，false表示无响应
+
+### 4.6 GetAvailableHosts函数
+
+**函数描述**: 获取所有可用的主机列表
+
+**函数签名**:
+```go
+func GetAvailableHosts() ([]string, error)
+```
+
+**输入参数**: 无
+
+**返回结果**: `[]string` - 可用主机列表，获取失败时返回错误信息
+
+### 4.7 GetHostIp函数
+
+**函数描述**: 根据主机名获取主机IP地址
+
+**函数签名**:
+```go
+func GetHostIp(hostName string) (string, error)
+```
+
+**输入参数**:
+```go
+hostName string // 必填，主机名称
+```
+
+**返回结果**: `string` - 主机的IP地址，获取失败时返回错误信息
+
+### 4.8 CheckHostHealth函数
+
+**函数描述**: 判断主机运行状态，用于发布前验证目标主机的可用性
+
+**函数签名**:
+```go
+func CheckHostHealth(hostIpAddress string) (bool, error)
+```
+
+**输入参数**:
+```go
+hostIpAddress string // 必填，主机IP地址
+```
+
+**返回结果**: `bool` - 健康检查结果，true表示主机有响应，false表示无响应
+
+### 4.9 SelectHostForNewInstance函数
+
+**函数描述**: 为新实例选择合适的主机
+
+**函数签名**:
+```go
+func SelectHostForNewInstance(availableHosts []string, service string, version string) (string, error)
+```
+
+**输入参数**:
+```go
+availableHosts []string // 必填，可用主机列表
+service        string   // 必填，服务名称
+version        string   // 必填，版本号
+```
+
+**返回结果**: `string` - 选择的主机名，选择失败时返回错误信息
+
+### 4.10 GenerateInstanceID函数
+
+**函数描述**: 根据服务名生成实例ID
+
+**函数签名**:
+```go
+func GenerateInstanceID(serviceName string) (string, error)
+```
+
+**输入参数**:
+```go
+serviceName string // 必填，服务名称
+```
+
+**返回结果**: `string` - 生成的实例ID，生成失败时返回错误信息
+
+### 4.11 GenerateInstanceIP函数
+
+**函数描述**: 生成实例IP地址
+
+**函数签名**:
+```go
+func GenerateInstanceIP() (string, error)
+```
+
+**输入参数**: 无
+
+**返回结果**: `string` - 生成的实例IP地址，生成失败时返回错误信息
+
+### 4.12 GenerateInstance函数
+
+**函数描述**: 创建实例
+
+**函数签名**:
+```go
+func GenerateInstance(instanceID string, instanceIP string) error
+```
+
+**输入参数**:
+```go
+instanceID string // 必填，实例ID
+instanceIP string // 必填，实例IP地址
+```
+
+**返回结果**: `error` - 创建失败时返回错误信息