|
|
# Hadoop 集群启动与停止接口前端联调指南
|
|
|
|
|
|
本文档提供了 Hadoop 集群启动与停止相关 API 的详细说明，用于指导前端开发人员进行接口对接。
|
|
|
|
|
|
## 1. 接口基本信息
|
|
|
|
|
|
| 功能 | 请求方法 | 接口路径 | 权限要求 |
|
|
|
| :--- | :--- | :--- | :--- |
|
|
|
| **启动集群** | `POST` | `/api/v1/ops/clusters/{cluster_uuid}/start` | `cluster:start` |
|
|
|
| **停止集群** | `POST` | `/api/v1/ops/clusters/{cluster_uuid}/stop` | `cluster:stop` |
|
|
|
|
|
|
- **Base URL**: `http://<server-ip>:<port>`
|
|
|
- **Content-Type**: `application/json`
|
|
|
- **认证方式**: 需要在 Header 中携带有效 JWT Token：`Authorization: Bearer <your_token>`
|
|
|
|
|
|
## 2. 请求参数 (Path Parameters)
|
|
|
|
|
|
| 参数名 | 类型 | 必选 | 说明 |
|
|
|
| :--- | :--- | :--- | :--- |
|
|
|
| `cluster_uuid` | `string` | 是 | 集群的唯一标识符（UUID），可从 `/api/v1/clusters` 接口获取。 |
|
|
|
|
|
|
## 3. 响应结构
|
|
|
|
|
|
### 3.1 成功响应 (200 OK)
|
|
|
|
|
|
接口执行时间较长（涉及远程 SSH 指令），建议前端超时时间设置为 **60s**。
|
|
|
|
|
|
```json
|
|
|
{
|
|
|
"status": "success",
|
|
|
"logs": [
|
|
|
"NameNode (192.168.1.10) start: Starting namenodes on [localhost]\nlocalhost: starting namenode...",
|
|
|
"ResourceManager (192.168.1.11) start: Starting resourcemanager..."
|
|
|
]
|
|
|
}
|
|
|
```
|
|
|
|
|
|
**字段说明：**
|
|
|
- `status`: 固定为 `"success"`。
|
|
|
- `logs`: 字符串数组，包含各关键组件（NameNode, ResourceManager）执行脚本后的标准输出与错误信息。
|
|
|
|
|
|
### 3.2 错误响应
|
|
|
|
|
|
- **401 Unauthorized**: 未提供 Token 或 Token 已失效。
|
|
|
- **403 Forbidden**: 权限不足（仅 `admin` 或 `ops` 角色可操作）。
|
|
|
- **404 Not Found**: 集群 UUID 不存在。
|
|
|
- **400 Bad Request**: 请求参数错误。
|
|
|
- `{"detail": "invalid_uuid_format"}`: 传入的 UUID 格式不正确（例如前端误传了 `[object Object]`）。
|
|
|
- **500 Internal Server Error**: 后端连接 SSH 超时或内部逻辑错误。
|
|
|
|
|
|
## 4. 前端联调建议
|
|
|
|
|
|
1. **Loading 状态**: 由于是长耗时操作，UI 必须提供明确的加载提示，并禁用操作按钮以防重发。
|
|
|
2. **日志展示**: 建议将返回的 `logs` 数组内容渲染在侧边栏或弹窗的日志终端组件中。
|
|
|
3. **超时处理**: 请务必在 Axios 或 Fetch 配置中显式设置 `timeout: 60000`。
|
|
|
4. **状态刷新**: 操作成功后，建议前端重新触发一次集群状态列表查询，以获取最新的 `health_status`。
|
|
|
|
|
|
## 5. 代码参考 (JavaScript/Axios)
|
|
|
|
|
|
```javascript
|
|
|
import axios from 'axios';
|
|
|
|
|
|
const clusterApi = {
|
|
|
async controlCluster(uuid, action) {
|
|
|
// action: 'start' 或 'stop'
|
|
|
const response = await axios.post(`/api/v1/ops/clusters/${uuid}/${action}`, {}, {
|
|
|
timeout: 60000
|
|
|
});
|
|
|
return response.data;
|
|
|
}
|
|
|
};
|
|
|
```
|
