Api Reference

API 路由参考

交互式文档：http://127.0.0.1:3001/docs（需 platform.admin 权限）。所有错误响应 为 RFC 7807 application/problem+json，格式与错误码见 错误处理。

路径中未特别说明的 :id、:ns、:name 均为路径参数。

公开接口

无需认证。

健康检查

方法	路径	说明
GET	/health	存活探针，返回 status/uptime/timestamp
GET	/ready	就绪探针，探测 PostgreSQL + Redis + 对象存储，任一不可用返回 503
GET	/metrics	Prometheus 指标。设置 METRICS_TOKEN 时要求 Authorization: Bearer <token> 匹配，否则只应答回环调用者，非回环请求返回 404

认证（公开）

方法	路径	限流	说明
POST	/login	5/min（插件）	本地登录，返回 token + user
POST	/register	5/min（插件）	本地注册（201），返回 token + user
GET	/auth/oauth/providers	10/min	OAuth 提供者列表
GET	/auth/oauth/:id/authorize	10/min	获取 OAuth 授权 URL
POST	/auth/oauth/:id/callback	10/min	OAuth 回调，返回 token + user
GET	/auth/session	无	轻量会话探针，未登录返回 { user: null }

平台信息

方法	路径	说明
GET	/platform/info	公开平台信息（Cache-Control: max-age=60）
GET	/platform/brand	平台品牌（logo/favicon 相对 URL）
GET	/platform/brand/:kind	品牌文件字节（logo / favicon）

SEO 输送

方法	路径	说明
GET	/seo/sitemap	聚合各插件的 sitemap
GET	/seo/feed	聚合 feed
GET	/seo/meta	单页 SEO meta（path、params 查询参数）
GET	/seo/robots	robots

主题

方法	路径	说明
GET	/themes	已安装主题列表
GET	/themes/active	当前激活主题
GET	/themes/:id/theme.css	主题 CSS
GET	/themes/:id/manifest.json	主题清单
GET	/themes/:id/frontend	主题前端描述符
GET	/themes/:id/frontend/*	主题前端文件
GET	/themes/:id/settings-schema	主题设置 schema
GET	/themes/:id/settings	主题解析后设置
GET	/themes/:id/assets/*	主题静态资源

插件

方法	路径	说明
GET	/plugins/frontends	激活插件前端列表
GET	/plugins/:id/frontend	插件前端描述符
GET	/plugins/:id/frontend/*	插件前端文件
GET	/plugins/:id/settings-schema	插件设置 schema
GET	/plugins/:id/settings	插件解析后设置

导航

方法	路径	认证	说明
GET	/nav/public	无	公开导航
GET	/nav/account	需认证	账户导航
GET	/nav/admin	platform.admin	管理导航

认证用户接口

需要会话（Bearer token 或 Cookie）。

方法	路径	说明
POST	/logout	登出（吊销会话并清除 Cookie，204）
GET	/auth/me	当前用户信息
GET	/auth/identities	已绑定的外部身份
GET	/permissions/check?permission=xxx	权限检查
POST	/frontend/audit	前端审计事件（120/min）
GET	/plugins/:id/action-targets	插件可操作路由（POST/PATCH/DELETE）
GET	/notifications	当前用户通知（cursor / limit 游标分页）
GET	/notifications/unread-count	未读通知数
GET	/notifications/stream	通知 SSE 流（text/event-stream）
POST	/notifications/:id/read	标记单条已读
POST	/notifications/read-all	全部标记已读
GET	/me/api-tokens	本人 API Token 列表
GET	/me/api-tokens/scopes	可授予的 scope
POST	/me/api-tokens	创建 API Token（30/min）
PATCH	/me/api-tokens/:id	更新 API Token（30/min）
DELETE	/me/api-tokens/:id	吊销 API Token（30/min）
GET	/me/api-tokens/:id/usage	本人该 Token 调用审计

媒体

方法	路径	认证	说明
POST	/media	需认证	上传媒体（20/min）
GET	/media	需认证	媒体列表
GET	/media/:id	无	媒体元数据
GET	/media/:id/content	无	媒体内容（600/min）
GET	/media/:id/references	需认证	媒体的引用位置
PATCH	/media/:id	需认证	更新媒体
DELETE	/media/:id	需认证	删除媒体

自定义模型

插件通过 defineModel 注册的自定义资源，按 :ns / :name 暴露：

方法	路径	说明
GET	/custom/:ns/:name	列表
POST	/custom/:ns/:name	创建
GET	/custom/:ns/:name/:id	详情
PATCH	/custom/:ns/:name/:id	更新
DELETE	/custom/:ns/:name/:id	删除

管理员接口

需要 platform.admin 权限。

用户管理

方法	路径	说明
GET	/admin/users?page=1&pageSize=20&q=	用户列表
POST	/admin/users	创建用户
GET	/admin/users/:id	用户详情聚合
PATCH	/admin/users/:id	更新用户（状态/权限组）
POST	/admin/users/:id/reset-password	重置密码
POST	/admin/users/:id/wallet	调整钱包余额
POST	/admin/users/:id/impersonate	代登录（签发会话）
GET	/admin/users/:id/services	用户服务列表
POST	/admin/users/:id/services	赠送服务
PATCH	/admin/users/:id/services/:serviceId	更新服务（过期/状态）
DELETE	/admin/users/:id/services/:serviceId	删除服务

权限与 RBAC

方法	路径	说明
GET	/admin/permissions	全部权限声明
GET	/admin/permission-groups	权限组列表
POST	/admin/permission-groups	创建权限组
PATCH	/admin/permission-groups/:id	更新权限组
DELETE	/admin/permission-groups/:id	删除权限组（结构组拒绝）

审计日志

方法	路径	说明
GET	/admin/audit-log?page=1&pageSize=20	审计日志列表（可按 action/resource/actorId 过滤）

设置 / 密钥 / 签名

方法	路径	说明
GET	/admin/settings	设置列表
PUT	/admin/settings/:key	设置键值（保留键不可用）
GET	/admin/secrets	密钥列表（不返回明文）
GET	/admin/secrets/:key	密钥存在性
PUT	/admin/secrets/:key	设置密钥
GET	/admin/signing	签名状态
PATCH	/admin/signing	设置/清除签名公钥

密钥存储未启用时，密钥读写接口统一返回 501 secret.storage.disabled。

平台信息与品牌

方法	路径	说明
GET	/admin/platform/info	平台信息
PATCH	/admin/platform/info	更新平台信息
POST	/admin/platform/brand	上传 logo/favicon
DELETE	/admin/platform/brand	恢复默认品牌

插件管理

方法	路径	说明
GET	/admin/plugins	插件列表（含状态/依赖/签名）
GET	/admin/plugins/frontend-status	前端重建/重载进度
POST	/admin/plugins/upload	上传插件 ZIP
PATCH	/admin/plugins/:id	启停插件
DELETE	/admin/plugins/:id	删除插件（内置不可删）
GET	/admin/plugins/:id/settings	插件设置
PATCH	/admin/plugins/:id/settings	更新插件设置

主题管理

方法	路径	说明
GET	/admin/themes	主题管理列表
POST	/admin/themes	上传主题 ZIP
PATCH	/admin/themes/:id	激活/停用主题
DELETE	/admin/themes/:id	删除主题（default 不可删）
GET	/admin/themes/preview	获取预览主题
POST	/admin/themes/preview	设置预览主题
DELETE	/admin/themes/preview	退出预览
GET	/admin/themes/:id/settings	主题设置
PATCH	/admin/themes/:id/settings	更新主题设置

应用市场 / 任务 / 汇率 / 支付 / 销售渠道

方法	路径	说明
GET	/admin/market/plugins	市场插件列表
GET	/admin/market/themes	市场主题列表
POST	/admin/market/plugins/:id/install	安装/升级插件
POST	/admin/market/themes/:id/install	安装/升级主题
GET	/admin/jobs/dead-letter	死信任务列表
POST	/admin/jobs/dead-letter/:id/retry	重试死信任务
GET	/admin/currency-rates	汇率列表
PUT	/admin/currency-rates	设置汇率
DELETE	/admin/currency-rates	删除汇率
GET	/admin/payments/manual	人工支付列表
POST	/admin/payments/:id/confirm	确认支付
POST	/admin/payments/:id/cancel	取消支付
GET	/admin/sales-channels	销售渠道列表
POST	/admin/sales-channels	创建销售渠道
PATCH	/admin/sales-channels/:id	更新销售渠道
DELETE	/admin/sales-channels/:id	删除销售渠道
POST	/admin/payment-methods	创建支付方式
PATCH	/admin/payment-methods/:id	更新支付方式
DELETE	/admin/payment-methods/:id	删除支付方式

备份 / 开发者控制台 / API Token 监管

方法	路径	说明
GET	/admin/backup	备份状态与能力
POST	/admin/backup/export	排队导出（202）
POST	/admin/backup/import	上传归档并导入
POST	/admin/backup/inspect	仅校验归档并回显 manifest
GET	/admin/backup/download?key=...	下载导出产物
GET	/admin/developer/overview	分发概览
GET	/admin/developer/resellers	渠道列表
GET	/admin/developer/resellers/:id	渠道详情 + 最近 webhook 投递
POST	/admin/developer/resellers	新建渠道（一次性返回入站私钥）
PATCH	/admin/developer/resellers/:id	更新渠道
POST	/admin/developer/resellers/:id/rotate-key	轮换渠道密钥
DELETE	/admin/developer/resellers/:id	删除渠道
GET	/admin/developer/webhook-deliveries	webhook 投递记录
GET	/admin/developer/calls	SP v1 调用审计
GET	/admin/api-tokens	全部 API Token（可按 userId 过滤）
DELETE	/admin/api-tokens/:id	吊销任意 API Token
GET	/admin/api-tokens/:id/usage	任意 Token 的调用审计
GET	/admin/custom/models	已注册自定义模型

Admin UI 扩展

方法	路径	说明
GET	/admin/ui/widgets	Dashboard Widget 列表
GET	/admin/rbac/templates	RBAC 角色模板
GET	/admin/ui/actions	Admin Actions 列表

开放平台接口（/api/v1）

对外承诺的稳定契约。认证为会话或平台 API Token；声明了 scope 的端点要求 Token 具备 该 scope，写操作还需 Idempotency-Key 请求头。内核拥有的端点见 apps/api/src/routes/open-api-v1.ts，插件能力经 manifest.capabilities 贡献并由 dispatcher 分发。完整清单以 /docs 的 open-api 标签与 /api/v1/capabilities 为准。

方法	路径	鉴权	说明
GET	/api/v1/platform	无（Cache-Control: 60s）	平台信息
PATCH	/api/v1/platform	platform.admin	更新平台信息（幂等写）
GET	/api/v1/me	会话 / Token	当前身份与 scope
GET	/api/v1/capabilities	会话 / Token	可用能力项
GET	/api/v1/wallet/balance	会话 / Token	钱包余额
GET	/api/v1/wallet/ledger	会话 / Token	钱包流水
GET	/api/v1/wallet/accounts	platform.admin	全部钱包账户
GET	/api/v1/users	user:read	用户列表
GET	/api/v1/users/:id	user:read	用户详情
POST	/api/v1/users	user:write	创建用户（幂等写）
PATCH	/api/v1/users/:id	user:write	更新用户（幂等写）
POST	/api/v1/users/:id/reset-password	user:write	重置密码（幂等写）
POST	/api/v1/users/:id/wallet	user:write	调整钱包（幂等写）
POST	/api/v1/users/:id/services	user:write	赠送服务（幂等写）

MCP

方法	路径	说明
POST	/mcp	JSON-RPC（Streamable HTTP），凭证同 /api/v1
GET	/mcp	本服务端不提供 SSE 流，返回 405
DELETE	/mcp	无状态会话终止，返回 204

渠道接口（/sp/v1）

Ed25519 请求签名认证，按渠道 scope 授权；写操作需 Idempotency-Key。

方法	路径	scope	说明
GET	/sp/v1/catalog	catalog:read	商品列表
GET	/sp/v1/catalog/:id	catalog:read	商品详情
GET	/sp/v1/orders	order:read	订单列表
GET	/sp/v1/orders/:id	order:read	订单详情
POST	/sp/v1/orders	order:write	创建订单
GET	/sp/v1/services	service:read	服务列表
GET	/sp/v1/services/:id	service:read	服务详情
POST	/sp/v1/services/:id/:action	service:write	生命周期（suspend/resume/terminate）

插件路由

插件路由由 PluginDispatcher 动态分发，路径由插件声明。在 /docs 的 plugins 标签 下查看已安装插件的路由。

插件路由支持 :param 路径参数，认证和权限由插件声明。