Skip to content

API 接口文档 ​

Utopia Server Panel 提供了一套完整的 HTTP REST API 与 WebSocket 实时通道,支持使用个人 API 访问令牌进行自动化脚本调用、外部监控集成或第三方工具对接。

认证方式与令牌格式 ​

用户登录后可在 个人设置 -> API 访问令牌 页面创建个人访问令牌。令牌以 usp_ 为前缀,仅在创建时完整展示一次,服务端数据库仅保存其 SHA-256 哈希值。

发起 HTTP 请求时,在请求头中携带 Bearer 令牌:

http
Authorization: Bearer usp_your_token_here

连接 WebSocket /ws 时,可在连接后发送认证消息帧:

json
{
  "action": "auth",
  "token": "usp_your_token_here"
}

作用域与权限规则 ​

个人访问令牌的最终生效权限由所属账号的角色权限与令牌自身的作用域 scopes 共同决定,两者取交集:

  • 当令牌作用域为 * 时,拥有所属账号的全部权限。
  • 当令牌指定了受限作用域,例如 dashboard:1,terminal:2 时,仅允许访问匹配模块且不超过令牌等级的接口。
  • 涉及账号敏感凭证与绑定变更的写操作,包括 /api/me/* 与 /api/binding/* 下的非 GET 请求,仅允许作用域为 * 的令牌执行,受限作用域令牌会被拦截并返回 INSUFFICIENT_SCOPE。

HTTP 接口参考 ​

以下按功能模块列出可通过 API 访问令牌调用的主要接口。

个人资料与自身状态 ​

方法路径权限或作用域要求说明
GET/api/me已认证用户,受限令牌需 profile:1 或 read获取当前账号信息与权限矩阵
GET/api/me/sessions同上获取当前活跃会话列表
GET/api/me/login-history同上获取最近 20 条登录审计记录
GET/api/me/tokens同上列出当前账号创建的 API 令牌元数据
POST/api/me/tokens仅 * 作用域创建新的个人访问令牌
DELETE/api/me/tokens/{id}仅 * 作用域吊销指定 API 令牌
GET/api/binding/list已认证用户,受限令牌需 profile:1 或 read获取当前账号绑定的 Minecraft 角色列表
GET/api/player/me同上获取主绑定角色的游戏内实时数据

服务器状态与监控日志 ​

方法路径权限或作用域要求说明
GET/api/statusdashboard:1获取服务器实时状态快照、TPS、MSPT、在线人数与硬件资源
GET/api/monitor/config公开或已认证获取监控展示配置
GET/api/monitor/perflogs:1查询历史性能采样记录
GET/api/monitor/playerslogs:1查询玩家上下线事件记录
GET/api/monitor/lifecyclelogs:1分页查询服务器启停生命周期记录
GET/api/monitor/lifecycle/rangelogs:1按时间区间查询服务器启停记录

性能分析与网页小地图 ​

方法路径权限或作用域要求说明
GET/api/profiler/snapshotprofiler:1获取当前维度耗时与区块热点快照
POST/api/profiler/teleportprofiler:2将绑定角色传送至热点坐标
GET/api/map/bootstrapmap:1获取小地图初始化配置、维度列表与权限信息
GET/api/map/tilemap:1获取指定维度与缩放层级的地图瓦片图像
GET/api/map/regionsmap:1查询已渲染或可用区域坐标
GET/api/map/overlaysmap:1获取实时玩家、实体、生物与路径点叠加数据
POST/api/map/waypointsmap:2创建地图路径点
DELETE/api/map/waypoints/{id}map:2删除指定路径点
POST/api/map/teleportmap:1 与地图传送配置传送至地图指定坐标
POST/api/map/reset-healthadmin:2重置地图渲染健康度状态
POST/api/map/clear-cacheadmin:2清理小地图磁盘瓦片缓存

模组与服务器配置 ​

方法路径权限或作用域要求说明
GET/api/mods/overviewmods_config:1获取已安装模组列表与配置文件树
GET/api/mods/configmods_config:1读取指定模组配置文件内容
PUT/api/mods/configmods_config:2保存修改后的模组配置文件
GET/api/mods/server-propertiesmods_config:1读取 server.properties 内容
PUT/api/mods/server-propertiesmods_config:2保存修改后的 server.properties
POST/api/mods/restartmods_config:2触发服务端重启命令

白名单与聊天消息 ​

方法路径权限或作用域要求说明
GET/api/whitelist/admin/applicationswhitelist_manage:1获取白名单申请列表
POST/api/whitelist/admin/applications/{id}/reviewwhitelist_manage:2审核通过或拒绝白名单申请
GET/api/whitelist/admin/entrieswhitelist_manage:1获取服务端当前白名单成员
POST/api/whitelist/admin/entrieswhitelist_manage:2手动添加白名单成员
DELETE/api/whitelist/admin/entries/{name}whitelist_manage:2手动移除白名单成员
GET/api/messages/inbox已认证用户,受限令牌需 messages:1 或 chat:1获取站内信收件箱
GET/api/messages/sent同上获取已发送站内信
GET/api/messages/unread-count同上获取未读站内信数量
POST/api/messages/send已认证用户,受限令牌需 messages:2 或 chat:2发送站内信
POST/api/messages/read-all同上全部标为已读
POST/api/messages/{id}/read同上标记单条站内信已读
GET/api/chat/history已认证用户,受限令牌需 chat:1 或 messages:1获取游戏内聊天同步历史
POST/api/chat/send已认证用户,受限令牌需 chat:2 或 messages:2通过网页向游戏内发送聊天消息

系统管理 ​

方法路径权限或作用域要求说明
GET/api/admin/usersadmin:1获取用户列表
POST/api/admin/usersadmin:2创建用户
PATCH/api/admin/users/{id}admin:2更新用户信息或状态
DELETE/api/admin/users/{id}admin:2删除用户
POST/api/admin/users/{id}/unbindadmin:2解除用户绑定的游戏角色
POST/api/admin/users/{id}/reset-2faadmin:2重置用户两步验证
POST/api/admin/users/{id}/unlockadmin:2解锁被锁定的账号
GET/api/admin/rolesadmin:1获取角色列表
GET/api/admin/roles/{id}admin:1获取角色详情与权限矩阵
POST/api/admin/rolesadmin:2创建自定义角色
PUT/api/admin/roles/{id}admin:2更新角色权限矩阵
DELETE/api/admin/roles/{id}admin:2删除自定义角色
GET/api/admin/permissionsadmin:1获取系统全部权限键定义
GET/api/admin/settingsadmin:1获取系统全局设置
PATCH/api/admin/settingsadmin:2更新系统全局设置
GET/api/admin/worldsadmin:1获取已索引的世界存档与数据库统计

WebSocket 接口参考 ​

连接到 /ws 并通过 auth 帧完成认证后,可发送以下 action 指令:

Action权限要求参数说明
auth无,按令牌赋予权限token绑定或刷新当前连接的认证身份
fetch_statusdashboard:1无主动拉取一次完整状态 JSON
fetch_logsterminal:1无拉取控制台缓冲区历史日志
fetch_command_historyterminal:1无拉取历史执行指令列表
fetch_completionsterminal:1command、requestId请求指令自动补全候选
execute_commandterminal:2command在服务端执行一条控制台指令

服务端同时会主动向具备对应权限的连接推送 status_delta 状态增量、new_log 新增日志以及 new_monitor_log 监控采样事件。

调用示例 ​

使用 curl 获取服务器实时状态:

bash
curl -s -H "Authorization: Bearer usp_your_token_here" \
  http://127.0.0.1:55533/api/status