使用 API

更新于 2026-09-29在 GitHub 上编辑

面板对外提供的 HTTP API 全部位于 /api 前缀下。接口不是由一个统一的服务实现的，而是由各插件在加载时注册，因此可用的接口取决于当前安装并启用了哪些插件。

鉴权方式

外部脚本推荐使用 API Key；官方前端使用登录会话加请求令牌：

浏览器会话 + Bearer 请求令牌

登录 Cookie 保存会话身份。前端再从 /api/auth/token 或用户资料响应取得会话令牌，并在受保护请求中发送 Authorization: Bearer <token>。后端暂时兼容旧客户端的 ?token=，新代码不要把令牌放在 URL 中。此方式还要求同源 Cookie 与 X-Requested-With: XMLHttpRequest。

API Key

调用方在请求头 x-request-api-key 中携带，或用查询参数 ?apikey=<key>。适合脚本与外部系统。

获取 API Key

  1. 登录需要被该 Key 代表的用户账号。

  2. 进入个人设置 / 用户中心，打开 API Key 开关。

  3. 面板会生成一个只含字母与数字的 Key 并返回，请妥善保存。

每个用户有各自的 API Key，权限与所选用户一致。关闭开关会清空该 Key。

# 用 API Key 调用
curl http://localhost:23333/api/overview \
  -H "x-request-api-key: <your-api-key>"

# 或用查询参数
curl "http://localhost:23333/api/overview?apikey=<your-api-key>"

如果面板配置了路径前缀 prefix，请求路径要带上它，例如 /panel/api/overview。

路由前缀

各插件注册的接口大致落在以下前缀下：

前缀 提供方 / 内容

/api/auth

user 插件：登录、登出、SSO、鉴权设置。

/api

user 与 instance 插件的通用接口：用户资料、实例管理/操作、计划任务、Minecraft 版本查询等。

/api/overview

runtime / console / desktop / instance 等：总览、外观、操作日志、桌面布局。

/api/plugins

config 插件：插件清单、开关、设置读写。

/api/service

node 插件：节点（守护进程）列表与增删改查。

/api/market

market 插件：市场包浏览、安装、插件上下架。

/api/files

file 插件：文件管理器的全部接口。

/api/monitor

monitor 插件：性能与请求图表数据。

/api/java_manager

java 插件：JDK 的查询、下载与切换。

/api/mod

mod 插件：Minecraft 模组 / 服务端插件的搜索与安装。

/api/protected_instance

backup 插件：实例备份。

这是常见前缀的速查，不是完整清单。某个插件被禁用后，其前缀下的接口会随之消失。

约定

  • 请求/响应主体为 JSON；上传下载类接口除外。

  • 普通 API 响应由服务器包装为 { status, data, time }；业务数据位于 data。

  • 需要管理员权限的接口在未获授权时返回 403。

  • 没有统一的 API 版本号；破坏性改动跟随面板版本发布。插件包另有一套兼容元数据（elements.api / elements.sdk），那是给插件运行时用的，与 HTTP API 无关。

如何查具体接口

以源码为准。每个插件的路由定义都在它自己的目录里，例如：

panel/plugins/<plugin>/src/backend/index.ts
panel/plugins/<plugin>/src/backend/*_router.ts

搜索 ctx.koa.router("/api/…​") 即可定位前缀，其后的 router.get/post/put/delete(…​) 就是具体路径。

下一步

© 2026 ElementsPanel