Api Introduction

API 介绍

StackPanel 后端是一个 Fastify 服务，对外提供 REST 风格 HTTP API。Web 前端（Next.js） 以 BFF 方式在服务端调用这些接口，插件路由、开放平台与渠道伙伴也都走同一进程。

在线文档

API 进程启动后，Swagger UI 位于：

http://127.0.0.1:3001/docs

/docs 需要 platform.admin 权限。未授权的调用返回 404，而不是 401 或 403， 以避免暴露该端点的存在。

Swagger UI 包含内核路由、open-api 标签下的开放平台能力，以及 plugins 标签下 已安装插件注册的路由。

API 分组

分组	认证	说明
公开接口	无	健康、主题、平台信息、SEO 等
认证接口	会话（Bearer/Cookie）	当前用户、通知、权限检查等
管理接口	platform.admin 权限	用户、插件、主题、设置、备份、开发者等
开放平台	会话或 API Token（sp_ 前缀）	/api/v1、/mcp，按 scope 与权限鉴权
渠道接口	Ed25519 请求签名	/sp/v1，面向渠道伙伴
插件接口	视路由声明	由插件定义

开放平台契约（路径、方法、鉴权、必填参数）以 @stackpanel/spec 的投影为单一来源： 内核 app.ts 与契约快照共用同一实现（packages/spec/src/version.ts、 packages/spec/src/openapi.ts、packages/spec/src/contract.ts）。该投影只保留契约 语义，删除路由、收紧鉴权或新增必填参数都会被兼容性检查判为破坏性变更。

基础信息

项	值
Base URL	http://127.0.0.1:3001
契约版本	0.4.0（KERNEL_API_VERSION，@stackpanel/spec 单一来源）
开放平台	/api/v1（OPEN_API_NAMESPACE）
内容类型	application/json（文件上传为 multipart/form-data）
错误类型	application/problem+json（RFC 7807 / RFC 9457）
字符编码	UTF-8

KERNEL_API_VERSION 是插件 manifest.apiVersion 的兼容基准，与内核产品版本 KERNEL_VERSION 是两个独立概念。

响应格式

成功响应

返回 JSON 或空响应（204）。

错误响应

所有错误统一为 RFC 7807 / RFC 9457 problem details，Content-Type 为 application/problem+json：

{
  "type": "https://errors.stackpanel.dev/auth/unauthenticated",
  "title": "Unauthorized",
  "status": 401,
  "detail": "未登录或会话已过期",
  "instance": "/auth/me",
  "code": "auth.unauthenticated",
  "requestId": "req-1"
}

type 由 code 派生（. 替换为 /）。稳定契约是 code；title 是按状态码的 中性英文，detail 为可读说明，5xx 不返回内部信息。详见 错误处理。

速率限制

限流由中央策略表 apps/api/src/lib/rate-limit-policy.ts 定义，跨副本计数走 Redis：

接口	限制
POST /login、/register	5 次/分钟/IP（插件内置限流，LOGIN_RATE_LIMIT_MAX / REGISTER_RATE_LIMIT_MAX），同一邮箱同样限 5 次/分钟
OAuth 接口	10 次/分钟/IP（oauth 预设）
API Token 签发 / 轮换	30 次/分钟/IP（credentialWrite）
管理端写入（密钥 / 签名 / 平台身份等）	60 次/分钟/IP（adminWrite）
插件 / 主题 / 媒体上传	20 次/分钟/IP（upload）
前端审计等用户写入	120 次/分钟/IP（userWrite）
匿名重读（媒体内容 / 主题与插件资源 / SEO 订阅）	600 次/分钟/IP（publicRead）
开放平台 API Token	每 token RPM（OPEN_API_TOKEN_RPM，默认 240）与并发上限（OPEN_API_TOKEN_CONCURRENCY，默认 0 表示关闭）

API_RATE_LIMIT_MULTIPLIER 可整体放大限额；小于 1 的值会被钳制为 1，因此该开关 只能放宽，不能关闭限流。

安全头

所有响应包含以下安全头：

头	值
X-Content-Type-Options	nosniff
X-Frame-Options	DENY
Referrer-Policy	strict-origin-when-cross-origin
Permissions-Policy	camera=(), microphone=(), geolocation=()
Content-Security-Policy	default-src 'self'; frame-ancestors 'none'; ...

CORS

CORS 默认关闭。只有显式配置 API_CORS_ORIGINS 时才允许名单内的源跨域访问，并 同时开启凭证。

BFF 模式下浏览器只与 Web 服务通信，由 Web 服务在服务端转发到 API，因此通常不需要 CORS。