mirror of
https://github.com/GSManagerXZ/GameServerManager.git
synced 2025-11-28 16:40:30 +08:00
13 KiB
13 KiB
云构建部署功能说明
功能概述
云构建部署是 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平台：
.\run.bat/.\run（优先）.\start.bat（次选）.\start.bat（默认）
Linux/Unix平台：
bash run.sh/./run（优先）bash start.sh（次选）bash start.sh（默认）
2.5 实例创建
- 自动填充实例名称（核心名称+版本号）
- 自动设置启动命令
- 支持手动修改所有配置
使用指南
1. 进入云构建部署页面
- 登录 GameServerManager3
- 进入"游戏部署"页面
- 点击"云构建部署"标签页
2. 选择构建平台
在左侧面板中：
- 选择构建平台：当前支持"我的世界原版Java部署"
- 选择服务端核心：从下拉列表中选择（如 Paper、Purpur 等）
- 选择Minecraft版本：选择要部署的版本
3. 配置部署
在右侧面板中：
-
设置部署路径：输入服务端要安装到的目录
- 系统会自动填充默认游戏路径
- 可以手动修改为自定义路径
- 路径会根据选择的核心和版本自动生成
-
查看统计信息（可选）：
- 显示该核心的总下载次数
- 显示当前版本的下载次数
4. 开始构建部署
-
点击"开始构建部署"按钮
-
系统会执行以下步骤：
- 检查缓存状态
- 创建构建任务（如需）
- 实时显示构建进度
- 下载文件到后端
- 自动解压到部署目录
- 检测启动命令
-
观察实时日志输出：
- 查看构建进度百分比
- 查看详细日志信息
- 等待部署完成
5. 创建实例
部署完成后：
- 点击"创建实例"按钮
- 确认自动填充的信息：
- 实例名称
- 实例描述
- 启动命令
- 点击"创建实例"完成
技术实现
前端实现
位置：client/src/pages/GameDeploymentPage.tsx
核心状态管理：
// 云构建相关状态
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 | 获取统计数据 |
核心逻辑：
// 下载并解压流程
1. 生成下载链接
2. 下载文件到临时目录 (server/temp/)
3. 解压到用户指定目录
4. 检测启动脚本
5. 清理临时文件
6. 返回部署结果
API客户端
位置：client/src/utils/api.ts
新增方法：
// 获取核心列表
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）
响应：
{
"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
请求体：
{
"coreName": "paper",
"version": "1.21.10",
"type": "msl_Official"
}
响应（缓存命中）：
{
"success": true,
"message": "已从缓存获取",
"data": {
"cached": true,
"fileName": "paper-1.21.10.zip"
}
}
响应（需要构建）：
{
"success": true,
"message": "构建任务已创建",
"data": {
"taskId": "e2a4d9f2-2637-4e02-af21-980a44910e44",
"status": "PROCESSING",
"message": "任务已创建,正在处理",
"queued": false
}
}
错误响应（超限）：
{
"success": false,
"message": "您已超过部署次数限制（1小时内最多 2 次）。请在 14:30:00 后重试。",
"resetTime": 1729567890000
}
状态码：429
3. 查询构建状态
请求：
GET /api/build/{taskId}
响应：
{
"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
请求体：
{
"fileName": "paper-1.21.10.zip",
"taskId": "task-id",
"coreName": "paper",
"version": "1.21.10"
}
5. 获取统计数据
请求：
GET /api/stats
响应：
{
"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. 启动命令错误
- 手动修改启动命令
- 检查解压后的文件列表
- 确认平台类型正确
最佳实践
- 使用默认路径：让系统自动生成部署路径，避免路径冲突
- 查看统计信息：选择下载量高的版本，通常更稳定
- 保留日志：部署完成后可以截图保存日志，便于排查问题
- 测试启动：创建实例后先测试启动，确认一切正常
- 定期更新：关注新版本发布，及时更新服务端
更新日志
v1.0.0 (2024-10-23)
- ✅ 初始版本发布
- ✅ 支持我的世界原版Java部署
- ✅ 实现云端构建和缓存机制
- ✅ 自动下载解压功能
- ✅ 智能启动命令检测
- ✅ 实时进度监控
- ✅ 统计数据展示
相关链接
技术支持
如遇到问题或有建议，请通过以下方式联系：
- 提交 Issue
- 查看项目文档
- 联系开发团队
注意：本功能依赖于云端服务的稳定性，建议在生产环境使用前充分测试。