Hugging Face's logo

Spaces:
StarrySkyWorld
/
InterConnectServer
Sleeping

App Files Community
InterConnectServer / docs /API.md
GitHub Actions
Sync from GitHub (excluding README)
6d43d9c
preview code
|
raw
history blame contribute delete
13.7 kB

InterConnect-Server API Documentation

本文档描述了 InterConnect-Server 的所有 API 接口（AI 相关接口请参考 AI_API.md）。

概述

InterConnect-Server 是一个 Minecraft WebSocket API 服务器，提供 API Key 管理、事件广播、服务器命令等功能。

默认端口: 8000

认证

除健康检查接口外，所有 API 请求需要在 Header 中携带 API Key：

Authorization: Bearer <your_api_key>

API Key 类型

类型 前缀 说明
Admin Key mc_admin_ 管理员密钥，拥有所有权限
Regular Key mc_key_ 普通密钥，可管理关联的 Server Key
Server Key mc_server_ 服务器密钥，供 Minecraft 服务器使用

健康检查

获取服务器状态

获取服务器健康状态和统计信息，无需认证。

请求

GET /health

成功响应 200 OK

{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "active_ws": 5,
  "keys_total": 10,
  "admin_active": 2,
  "server_active": 4,
  "regular_active": 4
}
字段 类型 说明
status string 服务器状态 (healthy / unhealthy)
timestamp string 当前时间戳
active_ws number 活跃的 WebSocket 连接数
keys_total number API Key 总数
admin_active number 活跃的 Admin Key 数量
server_active number 活跃的 Server Key 数量
regular_active number 活跃的 Regular Key 数量

错误响应 500 Internal Server Error

{
  "status": "unhealthy",
  "error": "Database connection failed"
}

API Key 管理

基础路径: /manage/keys

获取所有 API Key

获取所有 API Key 的信息列表。

权限: Admin Key

请求

GET /manage/keys
Authorization: Bearer <admin_key>

成功响应 200 OK

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Server Key",
    "description": "Production server",
    "keyPrefix": "mc_key_",
    "keyType": "regular",
    "serverId": "server-1",
    "regularKeyId": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "lastUsed": "2024-01-15T12:00:00.000Z",
    "isActive": true
  }
]

创建 API Key

创建新的 API Key。创建 Regular Key 时会自动生成关联的 Server Key。

权限: Admin Key

请求

POST /manage/keys
Authorization: Bearer <admin_key>
Content-Type: application/json

请求体 - 创建 Regular Key（推荐）

{
  "name": "My Server",
  "description": "Production Minecraft server",
  "key_type": "regular",
  "server_id": "server-1"
}

请求体 - 创建 Admin Key

{
  "name": "New Admin",
  "description": "Backup admin key",
  "key_type": "admin"
}
字段 类型 必填 说明
name string ✅ Key 名称
description string ❌ 描述信息
key_type string ❌ Key 类型：regular（默认）、admin
server_id string ❌ 服务器 ID

成功响应 - Regular Key 201 Created

{
  "regularKey": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "My Server",
    "description": "Production Minecraft server",
    "keyPrefix": "mc_key_",
    "keyType": "regular",
    "serverId": "server-1",
    "regularKeyId": null,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "lastUsed": null,
    "isActive": true,
    "key": "mc_key_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
  },
  "serverKey": {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "My Server - Server Key",
    "description": "Server Key for My Server",
    "keyPrefix": "mc_server_",
    "keyType": "server",
    "serverId": "server-1",
    "regularKeyId": "550e8400-e29b-41d4-a716-446655440000",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "lastUsed": null,
    "isActive": true,
    "key": "mc_server_x1y2z3a4b5c6d7e8f9g0h1i2j3k4l5m6"
  }
}

成功响应 - Admin Key 201 Created

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "name": "New Admin",
  "description": "Backup admin key",
  "keyPrefix": "mc_admin_",
  "keyType": "admin",
  "serverId": null,
  "regularKeyId": null,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastUsed": null,
  "isActive": true,
  "key": "mc_admin_p1q2r3s4t5u6v7w8x9y0z1a2b3c4d5e6"
}

⚠️ 重要: key 字段只在创建时返回一次，请妥善保存！

获取 API Key 详情

获取指定 API Key 的详细信息。

权限: Admin Key

请求

GET /manage/keys/:key_id
Authorization: Bearer <admin_key>

成功响应 200 OK

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Server Key",
  "description": "Production server",
  "keyPrefix": "mc_key_",
  "keyType": "regular",
  "serverId": "server-1",
  "regularKeyId": null,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastUsed": "2024-01-15T12:00:00.000Z",
  "isActive": true
}

错误响应 404 Not Found

{
  "detail": "API Key not found"
}

获取 Server Key 列表

获取当前用户可访问的 Server Key 列表。

权限: Regular Key 或 Admin Key

请求

GET /manage/keys/server-keys
Authorization: Bearer <regular_key_or_admin_key>

成功响应 200 OK

[
  {
    "id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "My Server - Server Key",
    "description": "Server Key for My Server",
    "keyPrefix": "mc_server_",
    "keyType": "server",
    "serverId": "server-1",
    "createdAt": "2024-01-15T10:30:00.000Z",
    "lastUsed": "2024-01-15T12:00:00.000Z",
    "isActive": true
  }
]
  • Admin Key: 返回所有 Server Key
  • Regular Key: 只返回关联的 Server Key

创建 Server Key

为指定的 Regular Key 创建新的 Server Key。

权限: Admin Key（仅限管理员，Regular Key 不能为自己创建 Server Key）

请求

POST /manage/keys/server-keys
Authorization: Bearer <admin_key>
Content-Type: application/json

请求体

{
  "name": "Backup Server Key",
  "description": "Backup key for server-1",
  "server_id": "server-1",
  "regular_key_id": "550e8400-e29b-41d4-a716-446655440000"
}
字段 类型 必填 说明
name string ✅ Key 名称
description string ❌ 描述信息
server_id string ❌ 服务器 ID
regular_key_id string ✅ 关联的 Regular Key ID

成功响应 201 Created

{
  "id": "880e8400-e29b-41d4-a716-446655440003",
  "name": "Backup Server Key",
  "description": "Backup key for server-1",
  "keyPrefix": "mc_server_",
  "keyType": "server",
  "serverId": "server-1",
  "regularKeyId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "lastUsed": null,
  "isActive": true,
  "key": "mc_server_n1o2p3q4r5s6t7u8v9w0x1y2z3a4b5c6"
}

错误响应 400 Bad Request

{
  "detail": "Name is required"
}

{
  "detail": "regular_key_id is required"
}

错误响应 404 Not Found

{
  "detail": "Invalid Regular Key ID"
}

⚠️ 重要:

  • 只有 Admin Key 可以为 Regular Key 创建额外的 Server Key
  • Regular Key 不能为自己创建或删除 Server Key
  • key 字段只在创建时返回一次，请妥善保存！

激活 API Key

激活指定的 API Key。

权限:

  • Admin Key: 可激活任意 Key
  • Regular Key: 只能激活关联的 Server Key

请求

PATCH /manage/keys/:key_id/activate
Authorization: Bearer <api_key>

成功响应 200 OK

{
  "message": "Key '550e8400-e29b-41d4-a716-446655440000' activated."
}

停用 API Key

停用指定的 API Key。

权限:

  • Admin Key: 可停用任意 Key（不能停用最后一个活跃的 Admin Key）
  • Regular Key: 只能停用关联的 Server Key

请求

PATCH /manage/keys/:key_id/deactivate
Authorization: Bearer <api_key>

成功响应 200 OK

{
  "message": "Key '550e8400-e29b-41d4-a716-446655440000' deactivated."
}

错误响应 400 Bad Request

{
  "detail": "Cannot deactivate your own key."
}

{
  "detail": "Cannot deactivate last active Admin Key."
}

删除 API Key

永久删除指定的 API Key。

权限: Admin Key

请求

DELETE /manage/keys/:key_id
Authorization: Bearer <admin_key>

成功响应 204 No Content

无响应体

错误响应 400 Bad Request

{
  "detail": "Cannot delete your own key."
}

{
  "detail": "Cannot delete the last Admin Key"
}

事件接口

基础路径: /api/events

发送事件

发送 Minecraft 事件并广播给所有 WebSocket 连接。

权限: 任意有效 API Key

请求

POST /api/events
Authorization: Bearer <api_key>
Content-Type: application/json

请求体

{
  "event_type": "player_join",
  "server_name": "server-1",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "player_name": "Steve",
    "player_uuid": "550e8400-e29b-41d4-a716-446655440000"
  }
}
字段 类型 必填 说明
event_type string ✅ 事件类型
server_name string ✅ 服务器名称
timestamp string ✅ 事件时间戳 (ISO 8601)
data object ✅ 事件数据

支持的事件类型

事件类型 说明
player_join 玩家加入服务器
player_leave 玩家离开服务器
message 聊天消息
server_command 服务器命令
ai_chat AI 聊天

成功响应 200 OK

{
  "message": "Event received and broadcasted"
}

错误响应 400 Bad Request

{
  "detail": "Missing required event fields"
}

{
  "detail": "Invalid event_type: unknown_event"
}

服务器接口

基础路径: /api/server

获取服务器信息

获取 Minecraft 服务器信息。

权限: Regular Key 或 Admin Key

请求

GET /api/server/info
Authorization: Bearer <api_key>

查询参数（仅 Admin Key）

参数 类型 说明
server_id string 指定服务器 ID

成功响应 200 OK

{
  "server_id": "server-1",
  "status": "running",
  "online_players": 5,
  "max_players": 20,
  "version": "1.20.1",
  "uptime": "2h 30m",
  "tps": 19.8
}

错误响应 400 Bad Request

{
  "detail": "server_id is required for this key"
}

发送服务器命令

向 Minecraft 服务器发送命令。

权限: Regular Key 或 Admin Key

请求

POST /api/server/command
Authorization: Bearer <api_key>
Content-Type: application/json

请求体

{
  "command": "say Hello World",
  "server_id": "server-1"
}
字段 类型 必填 说明
command string ✅ 要执行的命令
server_id string ❌ 服务器 ID（Admin Key 可指定）

成功响应 200 OK

{
  "message": "Command sent successfully",
  "command": "say Hello World",
  "server_id": "server-1"
}

错误响应 400 Bad Request

{
  "detail": "Command is required"
}

错误响应 403 Forbidden

{
  "detail": "Command is not allowed for Admin Key"
}

Admin Key 默认禁止的命令

以下命令默认禁止 Admin Key 执行（可通过环境变量配置）：

  • stop, restart, reload
  • op, deop
  • ban, ban-ip, banlist, pardon, pardon-ip
  • whitelist, kick
  • save-all, save-on, save-off

WebSocket 接口

连接 WebSocket

建立 WebSocket 连接以接收实时事件。

端点

ws://<host>:<port>/ws?api_key=<your_api_key>

示例

ws://localhost:8000/ws?api_key=mc_server_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

连接成功后

服务器会推送 Minecraft 事件消息：

{
  "type": "minecraft_event",
  "event": {
    "event_type": "player_join",
    "server_name": "server-1",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "data": {
      "player_name": "Steve"
    }
  },
  "source_key_id_prefix": "550e8400"
}

心跳检测

客户端可以发送 ping 消息保持连接：

发送

{
  "type": "ping"
}

响应

{
  "type": "pong"
}

根路径

获取服务器信息

请求

GET /

成功响应 200 OK

{
  "message": "Minecraft WebSocket API Server (Node.js)",
  "dashboard": "/dashboard",
  "websocket": "ws://localhost:8000/ws",
  "version": "1.0.0"
}

错误码参考

HTTP 状态码 说明
200 请求成功
201 创建成功
204 删除成功（无内容）
400 请求参数错误
401 未认证或 API Key 无效
403 权限不足
404 资源不存在
500 服务器内部错误

环境变量配置

变量名 默认值 说明
SERVER_HOST 0.0.0.0 服务器监听地址
SERVER_PORT 8000 服务器端口
DATABASE_PATH minecraft_ws.db 数据库文件路径
DASHBOARD_PORT 3000 Dashboard 独立端口（可选）
ADMIN_ALLOWED_COMMANDS - Admin Key 允许的命令（逗号分隔）
ADMIN_BLOCKED_COMMANDS - Admin Key 禁止的命令（逗号分隔）