17 KiB
当前控制面 API
所有响应为 JSON。错误形如 {"message":"原因"};输入校验错误另有 fields。所有时间按带时区时间戳输出。私有接口使用 Authorization: Bearer <token>;Cookie、查询参数中的 token 均不被接受。禁止将会话令牌放入 URL 或日志。
公共接口
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/public/settings |
平台品牌和公告,不含密钥 |
| GET | /api/auth/captcha |
返回 id、PNG data URL、expiresIn;30 次 / IP / 分钟 |
| POST | /api/auth/register |
email、displayName、password、captchaId、captchaCode |
| POST | /api/auth/login |
email、password、captchaId、captchaCode;返回 token、expiresIn |
| GET | /actuator/health |
不公开健康详情 |
验证码有效期 180 秒,每个挑战一次性使用,错误答案也会消费。注册与登录共享 IP 20 次 / 分钟和邮箱 10 次 / 5 分钟限额。验证码之外的格式校验失败可能先被 Bean Validation 拒绝,不进入验证码验证步骤。密码 12–72 字节,包含字母及数字。邮箱按小写存储且唯一。登录会话有效期默认 12 小时。
账户接口
| 方法 | 路径 | 参数 / 行为 |
|---|---|---|
| GET | /api/me |
当前资料、角色和权限 |
| POST | /api/auth/logout |
撤销当前会话 |
| PUT | /api/account/profile |
displayName |
| POST | /api/account/password |
currentPassword、newPassword;撤销全部会话 |
| GET | /api/account/sessions |
最近 100 条设备会话;不返回令牌摘要 |
| DELETE | /api/account/sessions/{id} |
仅撤销自己的会话 |
| GET | /api/account/logins |
最近 100 条本人登录记录 |
不采集设备指纹或其他不必要的身份信息。设备展示来自受长度限制的 User-Agent,可能由客户端伪造。
项目需求接口
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/projects |
本人最近 200 个项目(当前版本上限) |
| POST | /api/projects |
创建项目需求 |
| GET | /api/projects/{id} |
查询本人项目 |
| PUT | /api/projects/{id} |
编辑本人项目需求 |
| POST | /api/projects/{id}/archive |
归档,数据保留 |
创建 / 编辑的请求字段:name(1–100 字符)、description(最多 2000)、stack、requirements(最多 10000)。stack 为 Vue 3 / React / Next.js / Nuxt / HTML / Node.js / FastAPI / Laravel 之一。这里只记录用户选择,不执行 AI 或技术栈构建。跨用户访问统一 404。
管理接口
| 方法 | 路径 | 权限 |
|---|---|---|
| GET | /api/admin/users?search=&page=0 |
users:read,每页 20 条 |
| PUT | /api/admin/users/{id}/status |
users:write;status 为 ACTIVE / DISABLED,reason 必填 |
| DELETE | /api/admin/users/{id}/sessions |
users:write;撤销全部会话并审计 |
| GET | /api/admin/settings |
settings:write |
| PUT | /api/admin/settings |
settings:write;允许列表内的键值映射 |
| GET | /api/admin/audit |
audit:read,最近 100 条 |
设置允许项:siteName、siteDescription、logoUrl(HTTPS)、mainDomain、filing、footer、registrationEnabled(字符串 true / false)、announcement。域名字段当前仅配置展示,不会调用 DNS。设置及账户状态变更与审计在同一事务提交。
内置角色:USER、SUPER_ADMIN、ADMIN、FINANCE、OPS、SUPPORT。后端实际实现用户、设置、审计的操作权限;finance:write 与 nodes:write 是后续模块预留权限,当前没有资金或节点管理 API。角色授权编辑器尚未实现,不提供任意写入角色的用户接口。
常见错误码:400 输入或验证码错误、401 未认证 / 会话失效、403 无权或注册关闭、404 不存在 / 不属于当前用户、409 唯一约束冲突、429 限流、503 基础服务不可用。
模型和供应商
管理接口需要 models:write;用户模型列表只返回已开放的模型和已启用供应商。所有接口均需会话认证。
| 方法 | 路径 | 行为 |
|---|---|---|
| GET / POST | /api/admin/providers |
列表 / 新建;列表不含完整密钥或密文 |
| PUT | /api/admin/providers/{id} |
编辑或轮换密钥,apiKey 留空保持原值 |
| POST | /api/admin/providers/{id}/test |
实际调用上游模型列表,记录连接结果 |
| GET / POST | /api/admin/models |
管理列表 / 创建模型及初始价格版本 |
| PUT | /api/admin/models/{id} |
更新能力与开放状态,新增价格版本 |
| GET | /api/models |
当前用户可选模型及价格 |
供应商字段:name、baseUrl(HTTPS 443;连接时校验 DNS、拒绝私网 / 元数据地址)、apiType(OPENAI / ANTHROPIC / GEMINI)、authMode(BEARER / API_KEY / X_API_KEY)、apiKey、enabled、timeoutSeconds(5–180)。供应商预设接口 /api/admin/providers/presets 提供 MiMo、DeepSeek、Kimi 等官方模板及自定义兼容中转配置,不预造模型或价格。已有模型引用的供应商不能原地更换地址或协议,需新建供应商。
模型字段:providerId、name、modelId、contextLength、maxOutput、toolsEnabled、visionEnabled、enabled、inputPrice、outputPrice、cacheReadPrice、cacheWritePrice。价格为 CNY / 百万 Token,最多 8 位小数。modelId 与 providerId 创建后不可更改,避免破坏历史任务语义。
钱包
| 方法 | 路径 | 行为 |
|---|---|---|
| GET | /api/wallet |
本人 balance、reserved、available、currency |
| GET | /api/wallet/ledger |
本人最近 200 条真实交易 |
| POST | /api/admin/wallets/{user}/adjust |
finance:write;amount、idempotencyKey、reason 必填 |
资金调整以用户为范围幂等。金额为有符号 CNY 数值,0 无效;负数不能动用已预留资金。余额不足返回 402 / 409。线上支付尚未实现,调整不能冒充支付到账。
AI 任务
执行就绪与调度接口:
| 方法 | 路径 | 行为 |
|---|---|---|
| GET | /api/tasks/execution-status |
近期真实 Worker 心跳与隔离环境状态;无可用执行端时不允许新预留 |
| GET | /api/queue |
并发配置、执行 / 待核对 / 排队数量与本人排队名次 |
| GET | /api/queue/orders |
本人的优先权订单与退款状态 |
| POST | /api/tasks/{id}/priority |
本人排队任务购买优先,expectedPrice、idempotencyKey |
| PUT | /api/admin/queue/config |
queue:manage;maxConcurrent、priorityEnabled、priorityPrice、reason |
| POST | /api/admin/tasks/{id}/priority |
tasks:manage;priority、runNext、reason;下一位请求仍等待真实 Worker 领取 |
| GET | /api/admin/workers |
nodes:write 或 tasks:manage;实例心跳、容量、正在执行数量和健康状态 |
优先费独立于模型预算,首次执行前结束自动退款,开始执行后不自动退费。人工指定 / 人工权重高于付费优先,同级 FIFO;不抢占已运行任务。无执行端时拒绝新任务、恢复或购买,已存在任务仍可暂停 / 取消。详见 调度与接入说明。
| 方法 | 路径 | 行为 |
|---|---|---|
| GET / POST | /api/tasks |
本人最近 100 条 / 创建并预留预算 |
| GET | /api/tasks/{id} |
本人任务、预算与消费,不返回租约令牌 |
| GET | /api/tasks/{id}/events |
本人任务事件(最多 1000 条) |
| GET | /api/tasks/{id}/messages |
本人持久化消息与工具上下文 |
| POST | /api/tasks/{id}/pause |
暂停新的调用,保留剩余预算 |
| POST | /api/tasks/{id}/resume |
PAUSED 任务重新入队 |
| POST | /api/tasks/{id}/cancel |
结算当前调用,停止后续工具并释放未用预留 |
| GET | /api/admin/tasks |
tasks:manage 或 finance:write,最近 200 条 |
| POST | /api/admin/tasks/{id}/resolve |
finance:write,人工核对 REVIEW_REQUIRED 任务 |
创建字段:projectId、modelId、prompt、budget、idempotencyKey。仅本人的未归档项目可发起;每个项目只允许一个活动任务。同一幂等键与相同内容重放返回原任务,不重复预留。
人工核对字段:additionalAmount(已产生但尚未入账的追加费用,可为 0)、reason。已结算部分不会重复扣除;追加金额不能超过剩余预留。处理后关闭异常任务并释放剩余预留。人工记录与精确 Token 使用记录区分保存。
队列状态、租约、费用边界、上下文和恢复限制详见 AI 开发说明。正常停止 / 输出上限 / 异常中断分别处理,不把输出截断当作正常结束。日志目前采用每 3 秒查询;SSE / WebSocket 实时输出尚未实现。
文件、版本和源码
| 方法 | 路径 | 行为 |
|---|---|---|
| GET | /api/projects/{id}/files?path=. |
本人工作区目录 |
| GET | /api/projects/{id}/file?path=src/main.ts |
本人 UTF-8 文件 |
| PUT | /api/projects/{id}/file |
path、content,写入本人工程 |
| GET / POST | /api/projects/{id}/versions |
Git 版本列表 / 保存版本(message) |
| GET | /api/projects/{id}/source |
application/zip 源码,10MB / 5000 文件上限 |
这些接口需要真实隔离网关;未配置返回 503。文件工具的业务失败(如文件不存在、路径越界)由隔离工具返回 error 字段,前端明确显示。归档排除依赖缓存和 Git 数据,不提供虚假下载地址。
托管与运行
| 方法 | 路径 | 行为 |
|---|---|---|
| GET | /api/public/plans |
首页开放套餐,无需登录 |
| GET | /api/plans |
用户可购买套餐 |
| GET / POST / PUT | /api/admin/plans[/{id}] |
finance:write,管理套餐及资源配额 |
| GET / POST | /api/projects/{id}/subscription |
本人订阅 / 使用钱包购买月度套餐,planId、idempotencyKey |
| GET / POST / PUT | /api/projects/{id}/services[/{service}] |
本人 OCI 服务配置;环境变量加密,留空保留 |
| GET / POST | /api/projects/{id}/deployments |
本人部署记录 / 创建发布,idempotencyKey、可选 rollbackId |
| GET | /api/projects/{id}/deployments/{deployment}/events |
发布阶段与错误记录 |
| GET | /api/projects/{id}/runtime/services/{service} |
实际运行状态,需要运行网关 |
| GET / POST | /api/projects/{id}/runtime/services/{service}/logs、.../restart |
实际日志 / 重启,禁止封禁项目重启 |
配置保存不会冒充已发布。发布由独立运行 Worker 执行,健康检查通过后才切流;失败保持旧版本。未配置真实网关时不能成功启动容器。
运营、审核与集成
| 方法 | 路径 | 行为 |
|---|---|---|
| GET | /api/admin/overview |
真实统计、14 天增长、任务分布与权限范围内的近期表格 |
| GET | /api/admin/nodes、/api/admin/nodes/control-plane |
节点快照 / 当前控制面实际指标 |
| POST | /api/admin/nodes/refresh |
从 K8s 网关刷新,未配置或失败不会生成虚假节点 |
| GET | /api/admin/sites |
用户网站、订阅、部署与审核状态筛选 |
| POST | /api/admin/sites/{project}/review |
moderation:write,status、reason;封禁 / 拒绝会排队暂停运行 |
| GET | /api/admin/sites/{project}/operations |
查看暂停 / 恢复任务的实际结果 |
| GET | /api/admin/integrations |
integrations:write,配置结构与脱敏状态 |
| PUT | /api/admin/integrations/{kind} |
配置 enabled、values;密钥加密,空密钥保持原值 |
| POST | /api/admin/integrations/{kind}/test |
实际连接测试,结果持久化 |
| POST | /api/admin/integrations/{kind}/send-test |
SMTP / SMS 显式测试发送,幂等记录;可能产生供应商费用 |
| GET | /api/admin/integrations/logs、/api/admin/integrations/messages |
连接测试 / 消息发送记录 |
kind:SMTP、ALIYUN_SMS、ALIYUN_ESA、ALIYUN_CDN、ALIYUN_DNS、S3。配置与适配器不等于域名自动开通流程已实现。网站审核状态与实际运行执行状态分别展示;仅审核通过不会伪造“已恢复运行”。
项目域名与 HTTPS
| 方法 | 路径 | 行为 |
|---|---|---|
| GET | /api/projects/{id}/domains |
本人绑定、TXT 申请、部署根域名与入口目标 |
| POST | /api/projects/{id}/domains/platform |
serviceId、slug;分配稳定平台域名 |
| POST | /api/projects/{id}/domains/claims |
hostname;生成二十四小时有效的 TXT 验证申请 |
| POST | /api/projects/{id}/domains/claims/{claim}/verify |
serviceId;查询匹配 TXT 后创建自定义绑定 |
| POST | /api/projects/{id}/domains/{domain}/configure |
购买有效托管、审核通过且已发布服务后,排队配置入口 |
| POST | /api/projects/{id}/domains/{domain}/primary |
设置项目主域名 |
| DELETE | /api/projects/{id}/domains/{domain} |
请求解绑,保留历史与名称归属 |
| GET | /api/projects/{id}/domains/{domain}/events |
本人域名阶段 / 错误记录 |
| GET | /api/admin/domains?search= |
domains:write;用户 / 项目 / 域名 / 状态列表 |
| GET | /api/admin/domains/{domain}/events |
domains:write;执行记录 |
| POST | /api/admin/domains/{domain}/actions |
domains:write;action(CONFIGURE / REMOVE)、reason,审计真实操作者 |
当前为直接 Ingress + DNS + cert-manager 链路。DNS、证书和路由分别核对,不把配置 API 返回成功直接当成 ACTIVE。ESA 边缘自动化还未完成;详细步骤与幂等、归属、证书和单副本边界见 域名说明。
AI 自动核算报告
独立代码验收接口:GET/PUT /api/admin/code-reviews/config、GET/POST /api/admin/tasks/{id}/code-reviews。仅管理员可见 / 发起,源码快照与模型 / 价格留档,不扣用户钱包,不覆盖历史版本。权限、请求字段、真实构建覆盖及未验证范围见 独立验收。
GET /api/admin/tasks/{id}/reports:tasks:manage/finance:write/audit:read,仅管理员获取每次执行的核算凭据、AI 报告、报告模型成本和错误。普通任务所有者无权限。- 异常任务距最后更新三分钟后自动核算:只保留已确认消费,释放剩余预算,未知上游费用由平台承担;不自动重放任务。原有人工结算不被覆盖。
- AI 分析与资金事务分开;报告失败不阻塞已完成的预算释放,用户事件不包含内部核算记录。详见 自动核算。
项目对象存储
| 方法 | 路径 | 行为 |
|---|---|---|
| GET | /api/projects/{id}/storage?page=0&trash=false |
本人文件,50 条一页、total;summary 包含真实用量、配额和是否已启用存储 |
| POST | /api/projects/{id}/storage |
multipart/form-data:file、idempotencyKey;最大 25MiB |
| GET | /api/projects/{id}/storage/{object}/content |
认证私有下载,强制附件、nosniff、no-store;校验长度与 SHA256 |
| DELETE | /api/projects/{id}/storage/{object} |
软删除,保留三十天,期间仍占用空间 |
| POST | /api/projects/{id}/storage/{object}/restore |
期限内恢复;开始物理清理后禁止恢复 |
| POST | /api/projects/{id}/storage/{object}/reconcile |
请求结束五分钟后核对 S3 对象长度和元数据 SHA256 |
对象键由服务器生成并按项目隔离。上传失败 / 超时不直接认定远端未写入,继续占用配额;核对完整匹配才设为可用。未匹配可移入回收站,待过期删除确认后释放用量。清理 Worker 需显式设置 STORAGE_WORKER_ENABLED=true,使用原子租约处理恢复竞态和删除超时重试。预览中不启用自动清理。
支持工单
- 用户接口
GET/POST /api/tickets、GET /api/tickets/{id}、POST /api/tickets/{id}/actions、POST /api/tickets/{id}/read。仅工单提交者能访问,关联项目必须归其所有。 - 管理接口
GET /api/admin/tickets、GET /api/admin/tickets/agents、GET /api/admin/tickets/{id}、POST /api/admin/tickets/{id}/actions。需要tickets:manage,由超级管理员、普通管理员和客服角色获得。 - 列表接受
status、category、search、从 0 开始的page,返回items、counts、hasMore,每页 25 条。统计基于当前角色可见的全量工单。详情返回ticket、messages、hasOlder,用最早一条消息的 UUID 作为before分页,每页 30 条。 - 提交参数为
requestId、subject、category(AI/HOSTING/BILLING/ACCOUNT/OTHER)、可选的projectId、content。同一个 UUID 和相同参数重试返回原工单。用户最多同时处理 10 条工单,每 24 小时提交上限 20 条。 - 操作参数为
requestId和operation。双方可REPLY、CLOSE、REOPEN。客服还可NOTE、ASSIGN、PRIORITY、RESOLVE。回复和备注传content,分派传可空的assigneeId,调整优先级传priority(NORMAL/HIGH/URGENT)。同一工单上的相同操作可用同一请求 UUID 重试。 - 工单状态为
WAITING_SUPPORT、WAITING_CUSTOMER、RESOLVED、CLOSED。客服公开回复后等待用户回复,用户回复后重新进入客服队列。客服备注、分派和优先级仅在管理接口可见。已读接口传详情返回的reply_revision作为revision,只确认已读取的版本。