Skip to content

Commit 8e4957f

Browse files
aice030aice030
committed
Merge remote-tracking branch 'qiniu/develop'
2 parents e29a2f6 + 5b521c8 commit 8e4957f

File tree

15 files changed

+1469
-37
lines changed

15 files changed

+1469
-37
lines changed

‎docs/deploy/README.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
# 发布系统设计文档
2+
3+
## 1. 系统概述
4+
5+
### 1.1 设计目标
6+
发布系统是一个专注于执行发布动作的轻量级系统，负责：
7+
- 接收调度系统的发布指令
8+
- 执行具体的发布操作
9+
- 管理服务实例的版本状态
10+
- 提供回滚功能
11+
12+
### 1.2 设计原则
13+
- **单一职责**：只负责发布动作的执行，不涉及调度逻辑
14+
- **简单可靠**：提供稳定、可预测的发布操作
15+
- **状态透明**：实时反馈发布状态和实例版本信息
16+
- **快速回滚**：支持单实例和批量回滚操作
17+
18+
### 1.3 系统边界
19+
- **负责**：发布动作执行、实例状态管理、回滚操作
20+
- **不负责**：发布调度、批次规划、版本状态管理、实例选择、健康检查
21+
22+
## 2. 系统架构
23+
24+
### 2.1 整体架构
25+
```
26+
┌─────────────────┐ 方法调用 ┌─────────────────┐ 网络通信 ┌─────────────────┐
27+
│ 调度系统 │ ──────────────▶ │ 发布系统 │ ──────────────▶ │ 实例节点 │
28+
│ │ │ │ │ │
29+
│ • 发布指令 │ │ • 执行发布操作 │ │ • 服务实例 │
30+
│ • 批次规划 │ │ • 状态跟踪 │ │ • 版本更新 │
31+
│ • 健康检查 │ │ • 回滚操作 │ │ • 状态上报 │
32+
│ │ │ │ │ │
33+
└─────────────────┘ └─────────────────┘ └─────────────────┘
34+
│
35+
│ 数据存储
36+
▼
37+
┌─────────────────┐
38+
│ 数据库 │
39+
│ │
40+
│ • 实例版本 │
41+
│ • 回滚记录 │
42+
│ • 状态信息 │
43+
└─────────────────┘
44+
```
45+
46+
### 2.2 核心组件
47+
48+
- **发布执行器**: 执行发布操作，更新实例版本
49+
- **回滚执行器**: 执行回滚操作，处理包下载
50+
- **实例管理器**: 感知执行结果，维护实例状态
51+
52+
## 3. 核心功能模块
53+
54+
### 3.1 发布执行模块
55+
负责执行具体的发布操作，包括：
56+
- 接收发布请求（服务名、版本、实例列表）
57+
- 执行发布动作
58+
- 更新实例版本状态
59+
- 记录发布日志
60+
61+
### 3.2 回滚模块
62+
提供回滚功能：
63+
- 接受回滚请求（服务名、回滚的目标版本、实例列表）
64+
- 执行回滚任务
65+
- 更新实例版本状态
66+
- 记录回滚日志
67+
68+
### 3.3 实例管理模块
69+
获取实例状态：
70+
- 获取运行某服务的全部实例（可通过版本号过滤）
71+
- 获取实例的详细信息
72+
- 获取实例历史版本
73+
74+
## 4. 接口设计
75+
76+
发布系统提供以下外部接口：
77+
78+
- **DeployService**: 发布服务接口，负责发布和回滚操作的执行
79+
- **InstanceManager**: 实例管理接口，负责实例信息查询和状态管理
80+
81+
### 4.1 DeployService接口
82+
83+
发布服务接口，负责发布和回滚操作的执行。
84+
85+
```go
86+
type DeployService interface {
87+
ExecuteDeployment(params *DeployParams) (*OperationResult, error)
88+
ExecuteRollback(params *RollbackParams) (*OperationResult, error)
89+
}
90+
```
91+
92+
#### 4.1.1 ExecuteDeployment方法
93+
94+
触发指定服务版本的发布操作
95+
96+
#### 4.1.2 ExecuteRollback方法
97+
98+
对指定实例执行回滚操作，支持单实例或批量实例回滚
99+
100+
### 4.2 InstanceManager接口
101+
102+
实例管理接口，负责实例信息查询和状态管理，发布模块和服务管理模块都需要使用。
103+
104+
```go
105+
type InstanceManager interface {
106+
GetServiceInstances(serviceName string, version ...string) ([]*InstanceInfo, error)
107+
GetInstanceVersionHistory(instanceID string) ([]*VersionInfo, error)
108+
}
109+
```
110+
111+
#### 4.2.1 方法说明
112+
113+
**GetServiceInstances**: 获取指定服务的实例详细信息，可选择按版本过滤
114+
115+
**GetInstanceVersionHistory**: 获取指定实例的版本历史记录
116+
117+
## 5. 内部工具函数
118+
119+
**ValidatePackageURL**: 验证包URL的有效性和安全性
120+
121+
**GetServiceInstanceIDs**: 根据服务名和版本获取实例ID列表，用于内部批量操作
122+
123+
**GetInstanceHost**: 根据实例ID获取实例的IP地址
124+
125+
**GetInstancePort**: 根据实例ID获取实例的端口号
126+
127+
**CheckInstanceHealth**: 检查单个实例是否有响应，用于发布前验证目标实例的可用性

‎docs/deploy/interface.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
# 发布系统接口参考文档
2+
3+
## 1. 接口概览
4+
5+
发布系统提供以下外部接口：
6+
7+
- **DeployService**: 发布服务接口，负责发布和回滚操作的执行
8+
- **InstanceManager**: 实例管理接口，负责实例信息查询和状态管理
9+
10+
## 2. DeployService接口
11+
12+
### 2.1 接口定义
13+
14+
发布服务接口，负责发布和回滚操作的执行。
15+
16+
```go
17+
type DeployService interface {
18+
ExecuteDeployment(params *DeployParams) (*OperationResult, error)
19+
ExecuteRollback(params *RollbackParams) (*OperationResult, error)
20+
}
21+
```
22+
23+
### 2.2 ExecuteDeployment方法
24+
25+
**方法描述**: 触发指定服务版本的发布操作
26+
27+
**方法签名**:
28+
```go
29+
ExecuteDeployment(params *DeployParams) (*OperationResult, error)
30+
```
31+
32+
**输入参数**:
33+
```go
34+
type DeployParams struct {
35+
Service string `json:"service"` // 必填，服务名称
36+
Version string `json:"version"` // 必填，目标版本号
37+
Instances []string `json:"instances"` // 必填，实例ID列表
38+
PackageURL string `json:"package_url"` // 必填，包下载URL
39+
}
40+
```
41+
42+
**返回结果**:
43+
```go
44+
type OperationResult struct {
45+
Service string `json:"service"` // 服务名称
46+
Version string `json:"version"` // 操作的目标版本
47+
Instances []string `json:"instances"` // 实际操作的实例ID列表
48+
TotalInstances int `json:"total_instances"` // 操作的实例总数
49+
}
50+
```
51+
52+
### 2.3 ExecuteRollback方法
53+
54+
**方法描述**: 对指定实例执行回滚操作，支持单实例或批量实例回滚
55+
56+
**方法签名**:
57+
```go
58+
ExecuteRollback(params *RollbackParams) (*OperationResult, error)
59+
```
60+
61+
**输入参数**:
62+
```go
63+
type RollbackParams struct {
64+
Service string `json:"service"` // 必填，服务名称
65+
TargetVersion string `json:"target_version"` // 必填，目标版本号
66+
Instances []string `json:"instances"` // 必填，实例ID列表
67+
PackageURL string `json:"package_url"` // 必填，包下载URL
68+
}
69+
```
70+
71+
**返回结果**: `*OperationResult` - 使用通用的操作结果结构体
72+
73+
## 3. InstanceManager接口
74+
75+
### 3.1 接口定义
76+
77+
实例管理接口，负责实例信息查询和状态管理，发布模块和服务管理模块都需要使用。
78+
79+
```go
80+
type InstanceManager interface {
81+
GetServiceInstances(serviceName string, version ...string) ([]*InstanceInfo, error)
82+
GetInstanceVersionHistory(instanceID string) ([]*VersionInfo, error)
83+
}
84+
```
85+
86+
### 3.2 数据结构定义
87+
88+
**InstanceInfo结构体**:
89+
```go
90+
type InstanceInfo struct {
91+
InstanceID string `json:"instance_id"` // 实例唯一标识符
92+
ServiceName string `json:"service_name"` // 所属服务名称
93+
Version string `json:"version"` // 当前运行的版本号
94+
Status string `json:"status"` // 实例运行状态 - 'active'运行中；'pending'发布中；'error'出现故障
95+
}
96+
```
97+
98+
**VersionInfo结构体**:
99+
```go
100+
type VersionInfo struct {
101+
Version string `json:"version"` // 版本号
102+
Status string `json:"status"` // 版本状态 - 'acitve'当前运行版本；'stable'稳定版本；'deprecated'已废弃版本
103+
}
104+
```
105+
106+
### 3.3 GetServiceInstances方法
107+
108+
**方法描述**: 获取指定服务的实例详细信息，可选择按版本过滤
109+
110+
**方法签名**:
111+
```go
112+
GetServiceInstances(serviceName string, version ...string) ([]*InstanceInfo, error)
113+
```
114+
115+
**输入参数**:
116+
```go
117+
serviceName string // 必填，服务名称
118+
version ...string // 选填，指定版本号进行过滤，未输入则默认获取全部版本的运行实例
119+
```
120+
121+
**返回结果**: `[]*InstanceInfo` - 实例信息数组
122+
123+
### 3.4 GetInstanceVersionHistory方法
124+
125+
**方法描述**: 获取指定实例的版本历史记录
126+
127+
**方法签名**:
128+
```go
129+
GetInstanceVersionHistory(instanceID string) ([]*VersionInfo, error)
130+
```
131+
132+
**输入参数**:
133+
```go
134+
instanceID string // 必填，实例ID
135+
```
136+
137+
**返回结果**: `[]*VersionInfo` - 版本历史数组
138+
139+
## 4. 内部工具函数
140+
141+
### 4.1 ValidatePackageURL函数
142+
143+
**函数描述**: 验证是否能通过URL找到包
144+
145+
**函数签名**:
146+
```go
147+
func ValidatePackageURL(packageURL string) error
148+
```
149+
150+
**输入参数**:
151+
```go
152+
packageURL string // 必填，包下载URL
153+
```
154+
155+
**返回结果**: `error` - 验证失败时返回错误信息
156+
157+
### 4.2 GetServiceInstanceIDs函数
158+
159+
**函数描述**: 根据服务名和版本获取实例ID列表，用于内部批量操作
160+
161+
**函数签名**:
162+
```go
163+
func GetServiceInstanceIDs(serviceName string, version ...string) ([]string, error)
164+
```
165+
166+
**输入参数**:
167+
```go
168+
serviceName string // 必填，服务名称
169+
version ...string // 选填，指定版本号进行过滤，未输入则默认获取全部版本的运行实例
170+
```
171+
172+
**返回结果**: `[]string` - 实例ID数组
173+
174+
### 4.3 GetInstanceHost函数
175+
176+
**函数描述**: 根据实例ID获取实例的IP地址
177+
178+
**函数签名**:
179+
```go
180+
func GetInstanceHost(instanceID string) (string, error)
181+
```
182+
183+
**输入参数**:
184+
```go
185+
instanceID string // 必填，实例ID
186+
```
187+
188+
**返回结果**: `string` - 实例的IP地址，获取失败时返回错误信息
189+
190+
### 4.4 GetInstancePort函数
191+
192+
**函数描述**: 根据实例ID获取实例的端口号
193+
194+
**函数签名**:
195+
```go
196+
func GetInstancePort(instanceID string) (int, error)
197+
```
198+
199+
**输入参数**:
200+
```go
201+
instanceID string // 必填，实例ID
202+
```
203+
204+
**返回结果**: `int` - 实例的端口号，获取失败时返回错误信息
205+
206+
### 4.5 CheckInstanceHealth函数
207+
208+
**函数描述**: 检查单个实例是否有响应，用于发布前验证目标实例的可用性
209+
210+
**函数签名**:
211+
```go
212+
func CheckInstanceHealth(instanceID string) (bool, error)
213+
```
214+
215+
**输入参数**:
216+
```go
217+
instanceID string // 必填，实例ID
218+
```
219+
220+
**返回结果**: `bool` - 健康检查结果，true表示实例有响应，false表示无响应

0 commit comments

Comments
 (0)