Files
webup-cloud/docs/API.md
T

215 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 当前控制面 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` | 当前已启用的模型、供应商名称、能力、价格及版本生效时间(`price_effective_at`) |
供应商字段: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;不抢占已运行任务。无执行端时拒绝新任务、恢复或购买,已存在任务仍可暂停 / 取消。详见 [调度与接入说明](QUEUE.md)。
| 方法 | 路径 | 行为 |
| --- | --- | --- |
| GET / POST | `/api/tasks` | 本人最近 100 条 / 创建并预留预算 |
| GET | `/api/tasks/{id}` | 本人任务、预算与消费,不返回租约令牌 |
| GET | `/api/tasks/{id}/events` | 本人最近 1000 条任务事件,按时间从早到晚返回 |
| GET | `/api/tasks/{id}/messages` | 本人持久化消息与工具上下文 |
| GET | `/api/tasks/{id}/changes?page=0` | 本任务 Agent 文件变更,含累计增删行、最后一次操作和统计是否完整。每页 100 个文件 |
| 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 开发说明](AI-DEVELOPMENT.md)。正常停止 / 输出上限 / 异常中断分别处理,不把输出截断当作正常结束。日志目前采用每 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 |
| POST | `/api/projects/{id}/deployments/source` | 使用当前 AI 工作区源码创建发布,提交 idempotencyKey |
| 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 边缘自动化还未完成;详细步骤与幂等、归属、证书和单副本边界见 [域名说明](DOMAINS.md)。
## AI 自动核算报告
独立代码验收接口:`GET/PUT /api/admin/code-reviews/config`、`GET/POST /api/admin/tasks/{id}/code-reviews`。仅管理员可见 / 发起,源码快照与模型 / 价格留档,不扣用户钱包,不覆盖历史版本。权限、请求字段、真实构建覆盖及未验证范围见 [独立验收](CODE-REVIEWS.md)。
- `GET /api/admin/tasks/{id}/reports`:`tasks:manage` / `finance:write` / `audit:read`,仅管理员获取每次执行的核算凭据、AI 报告、报告模型成本和错误。普通任务所有者无权限。
- 异常任务距最后更新三分钟后自动核算:只保留已确认消费,释放剩余预算,未知上游费用由平台承担;不自动重放任务。原有人工结算不被覆盖。
- AI 分析与资金事务分开;报告失败不阻塞已完成的预算释放,用户事件不包含内部核算记录。详见 [自动核算](AUTOMATIC-REPORTS.md)。
## 项目对象存储
| 方法 | 路径 | 行为 |
| --- | --- | --- |
| 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`,只确认已读取的版本。