Files
webup-cloud/docs/API.md
T
WebUp Cloud db82325ed7
Verify control plane / verify (push) Canceled after 0s
Initial import of WebUp Cloud
2026-11-07 13:31:14 +08:00

17 KiB
Raw Blame History

当前控制面 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,只确认已读取的版本。