GameServerManager/docs/云构建部署功能说明.md

# 云构建部署功能说明

## 功能概述

云构建部署是 GameServerManager3 提供的一项创新功能，通过 GSManager 云端构建服务在云端直接运行核心成功后将其打包，拥有接近百分百的开服成功率，从根源解决因本地环境和问题造成的启动失败等疑难杂症。

### 核心优势

- ✅ **高成功率**：云端构建确保环境一致性，避免本地环境问题
- ✅ **零配置**：无需本地安装Java、Python等依赖环境
- ✅ **快速部署**：预构建缓存加速，支持一键部署
- ✅ **智能检测**：自动识别启动命令和运行环境
- ✅ **实时监控**：可视化构建进度和日志输出

## 功能特性

### 1. 支持的构建平台

目前支持以下构建平台：

- **我的世界原版Java部署** (`msl_Official`)
  - Paper
  - Purpur
  - Fabric
  - Spigot
  - 等多种主流服务端核心

### 2. 核心功能

#### 2.1 核心列表获取
- 自动从云端获取可用的服务端核心列表
- 支持版本筛选和排序
- 显示核心描述和特性

#### 2.2 构建与缓存
- 智能缓存机制：已构建的版本直接从缓存获取
- 实时构建：未缓存版本在云端实时构建
- 构建限流：防止滥用，1小时内最多2次构建

#### 2.3 下载与解压
- 后端自动下载zip文件到临时目录
- 自动解压到用户指定的部署目录
- 自动清理临时文件

#### 2.4 启动命令检测
智能检测启动脚本，优先级如下：

**Windows平台：**
1. `.\run.bat` / `.\run` （优先）
2. `.\start.bat` （次选）
3. `.\start.bat` （默认）

**Linux/Unix平台：**
1. `bash run.sh` / `./run` （优先）
2. `bash start.sh` （次选）
3. `bash start.sh` （默认）

#### 2.5 实例创建
- 自动填充实例名称（核心名称+版本号）
- 自动设置启动命令
- 支持手动修改所有配置

## 使用指南

### 1. 进入云构建部署页面

1. 登录 GameServerManager3
2. 进入"游戏部署"页面
3. 点击"云构建部署"标签页

### 2. 选择构建平台

在左侧面板中：

1. **选择构建平台**：当前支持"我的世界原版Java部署"
2. **选择服务端核心**：从下拉列表中选择（如 Paper、Purpur 等）
3. **选择Minecraft版本**：选择要部署的版本

### 3. 配置部署

在右侧面板中：

1. **设置部署路径**：输入服务端要安装到的目录
   - 系统会自动填充默认游戏路径
   - 可以手动修改为自定义路径
   - 路径会根据选择的核心和版本自动生成

2. **查看统计信息**（可选）：
   - 显示该核心的总下载次数
   - 显示当前版本的下载次数

### 4. 开始构建部署

1. 点击"开始构建部署"按钮
2. 系统会执行以下步骤：
   - 检查缓存状态
   - 创建构建任务（如需）
   - 实时显示构建进度
   - 下载文件到后端
   - 自动解压到部署目录
   - 检测启动命令

3. 观察实时日志输出：
   - 查看构建进度百分比
   - 查看详细日志信息
   - 等待部署完成

### 5. 创建实例

部署完成后：

1. 点击"创建实例"按钮
2. 确认自动填充的信息：
   - 实例名称
   - 实例描述
   - 启动命令
3. 点击"创建实例"完成

## 技术实现

### 前端实现

**位置**：`client/src/pages/GameDeploymentPage.tsx`

**核心状态管理**：
```typescript
// 云构建相关状态
const [cloudBuildType, setCloudBuildType] = useState('msl_Official')
const [cloudBuildCores, setCloudBuildCores] = useState<any[]>([])
const [selectedCloudCore, setSelectedCloudCore] = useState<any>(null)
const [selectedCloudVersion, setSelectedCloudVersion] = useState<string>('')
const [cloudBuildPath, setCloudBuildPath] = useState('')
const [buildingCloud, setBuildingCloud] = useState(false)
const [cloudBuildProgress, setCloudBuildProgress] = useState<number>(0)
const [cloudBuildLogs, setCloudBuildLogs] = useState<string[]>([])
```

**主要功能函数**：
- `fetchCloudBuildCores()` - 获取核心列表
- `fetchCloudBuildStats()` - 获取统计数据
- `handleCloudBuild()` - 开始构建
- `monitorCloudBuildProgress()` - 监控进度
- `handleCloudDownload()` - 下载和解压
- `handleCreateCloudInstance()` - 创建实例

### 后端实现

**位置**：`server/src/routes/cloudBuild.ts`

**API路由**：

| 路由 | 方法 | 说明 |
|------|------|------|
| `/:type/cores` | GET | 获取核心列表 |
| `/build` | POST | 创建构建任务 |
| `/build/:taskId` | GET | 查询构建状态 |
| `/download` | POST | 下载并解压到目标目录 |
| `/stats` | GET | 获取统计数据 |

**核心逻辑**：
```typescript
// 下载并解压流程
1. 生成下载链接
2. 下载文件到临时目录 (server/temp/)
3. 解压到用户指定目录
4. 检测启动脚本
5. 清理临时文件
6. 返回部署结果
```

### API客户端

**位置**：`client/src/utils/api.ts`

**新增方法**：
```typescript
// 获取核心列表
async getCloudBuildCores(type: string = 'msl_Official')

// 创建构建任务
async createCloudBuildTask(data: {
  coreName: string
  version: string
  type?: string
})

// 查询构建状态
async getCloudBuildTaskStatus(taskId: string)

// 下载并解压
async downloadAndExtractCloudBuild(data: {
  fileName?: string
  taskId?: string
  coreName: string
  version: string
  targetPath: string
})

// 获取统计数据
async getCloudBuildStats()
```

## 云端服务API

**服务器地址**：`https://download.mc.xiaozhuhouses.asia:4433`

### 1. 获取核心列表

**请求**：
```
GET /api/{type}/cores
```

**参数**：
- `type`：构建平台类型（如：`msl_Official`）

**响应**：
```json
{
  "success": true,
  "data": [
    {
      "name": "paper",
      "version": "1.21.10",
      "versions": ["1.21.10", "1.21.9", ...],
      "displayName": "Paper",
      "description": "高性能的 Minecraft 服务端"
    }
  ],
  "cached": true
}
```

### 2. 创建构建任务

**请求**：
```
POST /api/build
```

**请求体**：
```json
{
  "coreName": "paper",
  "version": "1.21.10",
  "type": "msl_Official"
}
```

**响应（缓存命中）**：
```json
{
  "success": true,
  "message": "已从缓存获取",
  "data": {
    "cached": true,
    "fileName": "paper-1.21.10.zip"
  }
}
```

**响应（需要构建）**：
```json
{
  "success": true,
  "message": "构建任务已创建",
  "data": {
    "taskId": "e2a4d9f2-2637-4e02-af21-980a44910e44",
    "status": "PROCESSING",
    "message": "任务已创建,正在处理",
    "queued": false
  }
}
```

**错误响应（超限）**：
```json
{
  "success": false,
  "message": "您已超过部署次数限制（1小时内最多 2 次）。请在 14:30:00 后重试。",
  "resetTime": 1729567890000
}
```
状态码：429

### 3. 查询构建状态

**请求**：
```
GET /api/build/{taskId}
```

**响应**：
```json
{
  "success": true,
  "data": {
    "taskId": "e2a4d9f2-2637-4e02-af21-980a44910e44",
    "status": "COMPLETED",
    "progress": 100,
    "downloadUrl": "/download/723d5aa3-79b7-4836-8b93-0cfbe5f188af",
    "expireTime": "2025-10-22 09:30:55",
    "message": "构建完成",
    "activeBuilds": 0,
    "queueSize": 0
  }
}
```

### 4. 下载文件

**请求**：
```
POST /api/download
```

**请求体**：
```json
{
  "fileName": "paper-1.21.10.zip",
  "taskId": "task-id",
  "coreName": "paper",
  "version": "1.21.10"
}
```

### 5. 获取统计数据

**请求**：
```
GET /api/stats
```

**响应**：
```json
{
  "success": true,
  "data": [
    {
      "coreName": "paper",
      "totalDownloads": 1250,
      "versions": {
        "1.21.10": 350,
        "1.21.9": 280
      }
    }
  ]
}
```

## 工作流程图

```
用户操作                    前端                     后端                  云端服务
    │                        │                        │                        │
    ├─选择核心和版本────────>│                        │                        │
    │                        ├─获取核心列表─────────>│                        │
    │                        │                        ├─请求核心列表─────────>│
    │                        │                        │<──返回核心列表─────────┤
    │                        │<──返回核心列表─────────┤                        │
    │                        │                        │                        │
    ├─开始构建部署────────>│                        │                        │
    │                        ├─创建构建任务─────────>│                        │
    │                        │                        ├─创建构建任务─────────>│
    │                        │                        │<──返回任务ID/缓存──────┤
    │                        │<──返回任务状态─────────┤                        │
    │                        │                        │                        │
    │                        ├─轮询构建进度─────────>│                        │
    │                        │(每2秒)                 ├─查询任务状态─────────>│
    │                        │                        │<──返回进度─────────────┤
    │<───显示进度和日志─────┤<──返回进度─────────────┤                        │
    │                        │                        │                        │
    │                        │(构建完成)              │                        │
    │                        ├─下载并解压───────────>│                        │
    │                        │                        ├─下载zip文件──────────>│
    │                        │                        │<──返回文件流───────────┤
    │                        │                        ├─解压到部署目录         │
    │                        │                        ├─检测启动命令           │
    │                        │                        ├─清理临时文件           │
    │                        │<──返回部署结果─────────┤                        │
    │<───显示部署完成───────┤                        │                        │
    │                        │                        │                        │
    ├─创建实例──────────────>│                        │                        │
    │                        ├─创建实例请求─────────>│                        │
    │                        │                        ├─创建实例配置           │
    │                        │<──返回创建结果─────────┤                        │
    │<───实例创建成功────────┤                        │                        │
```

## 注意事项

### 1. 部署限制
- 构建限流：1小时内最多2次构建请求
- 下载链接有效期：24小时
- 临时文件存储：使用 `server/temp/` 目录

### 2. 路径要求
- 部署路径必须存在或可创建
- 建议使用绝对路径
- Windows路径使用反斜杠 `\`，Linux使用正斜杠 `/`

### 3. 网络要求
- 需要能够访问云端服务器
- 建议稳定的网络连接
- 下载大文件时请耐心等待

### 4. 权限要求
- 需要对部署目录有写入权限
- 临时目录需要可写
- 所有API请求需要认证token

## 故障排除

### 1. 无法获取核心列表
- 检查网络连接
- 确认云端服务器可访问
- 检查后端日志

### 2. 构建失败
- 查看详细日志信息
- 检查是否超过构建限制
- 尝试选择其他版本

### 3. 下载失败
- 检查磁盘空间
- 确认部署路径可写
- 查看后端错误日志

### 4. 解压失败
- 确认zip文件完整
- 检查目标目录权限
- 查看后端日志详情

### 5. 启动命令错误
- 手动修改启动命令
- 检查解压后的文件列表
- 确认平台类型正确

## 最佳实践

1. **使用默认路径**：让系统自动生成部署路径，避免路径冲突
2. **查看统计信息**：选择下载量高的版本，通常更稳定
3. **保留日志**：部署完成后可以截图保存日志，便于排查问题
4. **测试启动**：创建实例后先测试启动，确认一切正常
5. **定期更新**：关注新版本发布，及时更新服务端

## 更新日志

### v1.0.0 (2024-10-23)
- ✅ 初始版本发布
- ✅ 支持我的世界原版Java部署
- ✅ 实现云端构建和缓存机制
- ✅ 自动下载解压功能
- ✅ 智能启动命令检测
- ✅ 实时进度监控
- ✅ 统计数据展示

## 相关链接

- [开发文档](../开发.md)
- [运行指令](./运行指令.md)
- [网络检测功能](./网络检测功能说明.md)
- [项目主页](../README.md)

## 技术支持

如遇到问题或有建议，请通过以下方式联系：

- 提交 Issue
- 查看项目文档
- 联系开发团队

---

**注意**：本功能依赖于云端服务的稳定性，建议在生产环境使用前充分测试。