GameServerManager/server/data/plugins/插件开发文档.md

GSM3 插件开发文档

概述

GSM3 插件系统允许开发者创建自定义的Web界面和功能扩展，通过标准化的API与GSM3核心系统进行交互。

插件结构

每个插件都应该包含以下文件：

plugin-name/
├── plugin.json          # 插件配置文件（必需）
├── index.html           # 主界面文件（可选）
├── gsm3-api.js         # API客户端库（推荐）
└── assets/             # 静态资源目录（可选）
    ├── css/
    ├── js/
    └── images/

配置文件 (plugin.json)

插件配置文件定义了插件的基本信息和行为：

{
  "name": "plugin-name",              // 插件唯一标识符
  "displayName": "插件显示名称",        // 用户界面显示的名称
  "description": "插件功能描述",        // 插件功能说明
  "version": "1.0.0",                 // 插件版本号
  "author": "开发者名称",              // 插件作者
  "enabled": true,                    // 是否启用插件
  "hasWebInterface": true,            // 是否有Web界面
  "entryPoint": "index.html",         // 主入口文件
  "icon": "puzzle",                   // 图标名称
  "category": "工具"                   // 插件分类
}

配置字段说明

• name: 插件的唯一标识符，只能包含字母、数字、连字符
• displayName: 在用户界面中显示的插件名称
• description: 插件功能的详细描述
• version: 遵循语义化版本规范 (semver)
• author: 插件开发者信息
• enabled: 控制插件是否启用
• hasWebInterface: 是否提供Web界面
• entryPoint: Web界面的入口文件
• icon: 插件图标（支持FontAwesome图标名称）
• category: 插件分类，用于组织和筛选

API 使用

引入API客户端

在HTML文件中引入GSM3 API客户端：

<script src="gsm3-api.js"></script>
<script>
  // 初始化API客户端
  const api = new GSM3API();
  
  // 等待API准备就绪
  api.onReady(() => {
    console.log('GSM3 API 已准备就绪');
    // 在这里调用API方法
  });
</script>

可用API方法

系统信息API

// 获取系统状态
api.getSystemStatus().then(status => {
  console.log('系统状态:', status);
});

// 获取系统信息
api.getSystemInfo().then(info => {
  console.log('系统信息:', info);
});

// 健康检查
api.healthCheck().then(result => {
  console.log('健康检查:', result);
});

实例管理API

// 获取实例列表
api.getInstances().then(instances => {
  console.log('实例列表:', instances);
});

// 获取市场实例
api.getMarketInstances().then(marketInstances => {
  console.log('市场实例:', marketInstances);
});

// 创建实例
api.createInstance({
  name: '我的实例',
  game: 'minecraft',
  version: '1.20.1'
}).then(result => {
  console.log('创建结果:', result);
});

// 获取实例详情
api.getInstance('instance-id').then(instance => {
  console.log('实例详情:', instance);
});

// 启动实例
api.startInstance('instance-id').then(result => {
  console.log('启动结果:', result);
});

// 停止实例
api.stopInstance('instance-id').then(result => {
  console.log('停止结果:', result);
});

// 重启实例
api.restartInstance('instance-id').then(result => {
  console.log('重启结果:', result);
});

// 删除实例
api.deleteInstance('instance-id').then(result => {
  console.log('删除结果:', result);
});

终端管理API

// 获取终端列表
api.getTerminals().then(terminals => {
  console.log('终端列表:', terminals);
});

// 获取终端统计信息
api.getTerminalStats().then(stats => {
  console.log('终端统计:', stats);
});

// 获取终端会话
api.getTerminalSessions().then(sessions => {
  console.log('终端会话:', sessions);
});

// 获取活跃终端进程
api.getActiveTerminalProcesses().then(processes => {
  console.log('活跃进程:', processes);
});

// 更新终端会话名称
api.updateTerminalSessionName('session-id', '新名称').then(result => {
  console.log('更新结果:', result);
});

文件操作API

// 读取文件
api.readFile('/path/to/file.txt').then(content => {
  console.log('文件内容:', content);
});

// 写入文件
api.writeFile('/path/to/file.txt', '文件内容').then(result => {
  console.log('写入结果:', result);
});

// 列出目录
api.listDirectory('/path/to/directory').then(files => {
  console.log('目录内容:', files);
});

// 创建目录
api.createDirectory('/path/to/new/directory').then(result => {
  console.log('创建结果:', result);
});

// 删除文件
api.deleteFile('/path/to/file.txt').then(result => {
  console.log('删除结果:', result);
});

// 复制文件
api.copy('/source/path', '/destination/path').then(result => {
  console.log('复制结果:', result);
});

// 移动文件
api.move('/source/path', '/destination/path').then(result => {
  console.log('移动结果:', result);
});

游戏管理API

// 获取支持的游戏列表
api.getGames().then(games => {
  console.log('游戏列表:', games);
});

开发最佳实践

1. 错误处理

始终为API调用添加错误处理：

api.getInstances()
  .then(instances => {
    // 处理成功响应
    console.log('获取实例成功:', instances);
  })
  .catch(error => {
    // 处理错误
    console.error('获取实例失败:', error);
    alert('操作失败: ' + error.message);
  });

2. 用户界面设计

• 使用响应式设计，确保在不同屏幕尺寸下都能正常显示
• 提供清晰的操作反馈和状态指示
• 遵循GSM3的设计风格和色彩方案

3. 性能优化

• 避免频繁的API调用
• 使用适当的缓存策略
• 对大量数据进行分页处理

4. 安全考虑

• 验证用户输入
• 避免执行不安全的操作
• 遵循最小权限原则

调试和测试

开发模式

在开发过程中，可以通过浏览器的开发者工具查看API调用和响应：

1. 打开浏览器开发者工具 (F12)
2. 切换到Network标签页
3. 执行插件操作，观察API请求和响应

日志记录

使用console.log记录关键信息：

console.log('插件初始化完成');
console.log('API调用参数:', params);
console.log('API响应结果:', result);

示例插件

参考 example-plugin 目录中的示例代码，了解完整的插件实现。

常见问题

Q: 如何处理API认证？

A: GSM3 API客户端会自动处理认证，无需手动管理token。

Q: 插件如何与主系统通信？

A: 通过提供的API方法进行通信，所有操作都通过HTTP请求完成。

Q: 可以访问文件系统吗？

A: 可以通过文件操作API访问指定目录下的文件，但有安全限制。

Q: 如何更新插件？

A: 修改插件文件后，重新加载插件页面即可看到更新。

技术支持

如有问题，请联系GSM3开发团队或查看项目文档。