215 lines
17 KiB
Markdown
215 lines
17 KiB
Markdown
# 当前控制面 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`,只确认已读取的版本。
|