Files
CloudLab c1babcb934
CloudLab CI/CD / 门禁 doctor (push) Failing after 41s
CloudLab CI/CD / 单元测试 (push) Skipped
CloudLab CI/CD / 归档完整性 (push) Skipped
CloudLab CI/CD / 构建站点与归档 (push) Skipped
CloudLab CI/CD / 部署到 lab.hdtime.space(rsync) (push) Skipped
CloudLab CI/CD / 构建镜像并推送 Gitea 容器仓库 (push) Skipped
CloudLab CI/CD / 容器部署到 lab.hdtime.space (push) Skipped
CloudLab CI/CD / 发布版本(Tag) (push) Skipped
feat(ui): 对比页结构强化、对比度门禁与 IDE 流式健壮性
- 对比页主栏对齐 1240,桌面 sticky 工具栏/表头,移动端修复与快捷条重叠
- 对比度自动化采样并修复 18 个 FAIL,ui_invariants 扩到 340 项(336 PASS / 0 FAIL / 4 SKIP)
- 页面级 <10px 声明清零;IDE 仍保留 189 条静态欠账,文档明示
- 新增 ide-stream.js:SSE 游标续传/去重/退避与提交幂等键;9 条单测
- 同步 UI/UX/品牌/验证/API 文档与 docs/evidence/sprint3 本地证据
2026-11-19 00:05:29 +00:00

46 KiB
Raw Permalink Blame History

CloudLab API 契约(API-CONTRACT)

文档状态(与 2026-11-18 源码同步):本文依据 2026-11-18 工作区 app/ide.js、app/bench.js 与 ../cloudlab-platform/server.py(1601 行)实测整理;行号为当日文件行号。服务端未实现或前端未使用的端点均显式标注"未实现/未验证",不作推测性描述。 适用范围:CloudLab IDE(app/ide.html + ide.js)及其依赖的控制面 API;实验台/资料浏览/生信数据库/对比页的静态数据读取单列 §9。认证、运行提交与生命周期、SSE、上传、项目/成员/配额、错误结构与 UI 状态映射。页面与视觉分别见 UX-AUDIT.md、UI-SYSTEM.md、BRAND-GUIDE.md;改动前基线见 UI-OPTIMIZATION-PLAN.md。 最后核对命令:见 §16(grep 调用点、路由与常量)。


1. 部署前提与约定

项 约定 证据
同源 前端全部用相对路径 /api/...,依赖同源部署;代码中无 API base URL、无 CORS 头 app/ide.js:477 起
凭据 credentials: 'same-origin',认证 Cookie cl_session ide.js:337
服务端 Python 3.11 标准库、SQLite 控制面;默认监听 0.0.0.0:8000,可用 CLOUDLAB_API_HOST/PORT 覆盖 server.py:1592-1594
站点 CLOUDLAB_SITE 默认 /opt/cloudlab/site;前端页面与 /app/data 静态数据由站点服务承载 common.py:17
编码 JSON UTF-8;JSON 响应 Content-Type: application/json; charset=utf-8、Cache-Control: no-store server.py:800-805
时间 字符串 ISO-8601(UTC),由 now_iso() 生成 common.py now_iso
版本 APP_VERSION = "3.0.0";Server 头 CloudLabAPI/3.0;/api/health 返回 version: "3.0.0" common.py:14、server.py:766、server.py:888-889
反向代理 未在代码中配置;若经 Nginx 等代理,SSE 需关闭缓冲(服务端已发 X-Accel-Buffering: no)。代理层行为未验证 server.py:1547-1560

请求头约定:

  • 所有写请求(POST/PUT/PATCH/DELETE)必须带 X-CloudLab-Client: ide,否则 403 csrf。/api/auth/login、/api/auth/logout 在鉴权之前处理,不受此限制。
  • Content-Type: application/json 用于 JSON;上传用 application/octet-stream。
  • 可选 Idempotency-Key:服务端已支持;IDE 前端自 S3-4 起在 POST /api/runs 自动生成并发送(同一提交重试复用,见 §4.1、§17.6)。

2. 客户端请求层(ide.js)

2.1 常量与函数

名称 行号 行为
REQ_TIMEOUT ide.js:307 15000 ms,普通请求默认超时
UPLOAD_TIMEOUT ide.js:308 60000 ms,上传专用
reqError(message, status, code, retryable) ide.js:310-316 构造带 status/code/retryable 的 Error;code 缺省为 http_<status> 或 network
errMessage(status, serverMsg) ide.js:318-328 服务端有 error 文本时优先使用;否则按状态给中文兜底
fetchTimeout(url, opt, ms) ide.js:332-347 AbortController 超时;credentials: same-origin;超时 code='timeout'、网络失败 code='network',均 retryable=true
api(path, opt) ide.js:350-377 统一封装:非 GET 自动加 X-CloudLab-Client;对象 body 自动 JSON 序列化;先 res.text() 再解析
getJson(url) ide.js:586-591 读取 /app/data/*.json,非 2xx 抛 static_<status>
fetchTimeout 直传(上传) ide.js:2014-2019 手动构造 60s 上传请求,不经过 api()

2.2 错误对象

err.status    // 0 = 网络/超时;否则 HTTP 状态码
err.code      // 'timeout' | 'network' | 'unauthorized' | 服务端 code | 'http_<n>'
err.retryable // 无 status、408、429、>=500 时为 true;401 显式 false
err.payload   // 非 2xx 时附带的解析后响应体
err.message   // 可直接展示的中文

api() 读取响应体的降级规则(ide.js:359-376):

  • 空 body → null;
  • 非 JSON 文本 → { error: text.slice(0, 300) },避免抛解析异常;
  • 读 body 失败 → reqError('响应读取失败,请重试', 0, 'network', true)。

2.3 401 特殊处理

api() 遇到 401 时执行(ide.js:363-367):

  1. showAuth() 切回登录界面;
  2. hideAlert() 清空应用内错误条;
  3. 抛出 code = (响应.code || 'unauthorized')、retryable=false 的错误。

因此 401 不会进入普通的 showAlert 重试路径,也不会在应用内弹 toast;登录页承担提示。/api/auth/status 未登录返回 200 {user:null},不触发 401 分支。

2.4 前端未使用的封装能力

  • 未设置 Accept、未使用 AbortSignal 取消用户主动取消;
  • 未统一处理 429 的 Retry-After(仅 queue_full 响应带该头,前端未读取);
  • 无请求 ID / trace 透传。

3. 认证

3.1 端点

方法 路径 鉴权 请求 成功响应
GET /api/health 无 — {ok:true, app:"CloudLab API", version:"3.0.0", time}
POST /api/auth/login 无 {username,password} 200 {user, projects} + Set-Cookie: cl_session
POST /api/auth/logout 无(读 Cookie) — {ok:true} + 清除 Cookie
GET /api/auth/status 可选 — 已登录 {user, projects, version};未登录 {user:null, projects:[]}
GET /api/me 必须 — {user, projects, version}
GET /api/meta 必须 — 平台计数与限额(见 §8.1)

user 字段(server.py:71-73):{id, username, role, disabled, createdAt},role 为全局 user|admin。

projects 字段(server.py:85-99):{id, name, description, createdAt, role, quota};管理员返回全部项目且 role="owner",普通用户只返回自己加入的项目。quota 为 {maxActiveRuns, maxRunning, usage:{active,running,queued}}。

3.2 登录

POST /api/auth/login
Content-Type: application/json

{"username":"alice","password":"********"}

服务端行为(server.py:924-946):

  1. 读取 JSON;同 IP 失败计数保留 600 秒,达到 10 次直接 429 rate_limited「登录尝试过多,请 10 分钟后再试」;
  2. 用户名或密码错误 → 401 bad_credentials「用户名或密码错误」,并记一次失败;
  3. disabled=1 → 403 disabled「账号已禁用」;
  4. 成功:生成 32 字节随机 token,写 sessions(7 天过期),写审计 login;
  5. 返回 {user, projects},并 Set-Cookie。

Cookie 属性(server.py:793-798):

cl_session=<token>; Path=/; HttpOnly; SameSite=Lax; Max-Age=604800
# X-Forwarded-Proto: https 或 CLOUDLAB_COOKIE_SECURE=1 时追加 ; Secure
  • 无 Domain,默认 host-only;无 Secure 时仅适合 HTTPS 终止在代理的场景,生产是否强制 Secure 需部署确认。
  • 也接受 Authorization: Bearer <token>(server.py:857-862),前端未使用。

3.3 状态、登出与 401

  • GET /api/auth/status:从未登录返回 200 而非 401,前端据此显示登录页;
  • 会话不存在/过期 → 401 unauthorized「登录已过期,请重新登录」;
  • 账号被禁用 → 403 disabled(即使会话存在);
  • POST /api/auth/logout:删除该 token 对应会话,返回 {ok:true},并设 cl_session=; Path=/; Max-Age=0; HttpOnly; SameSite=Lax;前端失败也静默(ide.js:578-583)。

3.4 CSRF

require_csrf 只校验请求头 X-CloudLab-Client 是否等于 ide(server.py:878-880),不是随机 token,也不校验 Origin/Referer。它依赖同源策略与自定义头不可被简单跨站表单伪造。所有 /api/ 下写请求在鉴权后执行该检查(server.py:900-903)。

3.5 未实现/未验证

  • 无注册、找回密码、修改密码(自助)、刷新 token、会话列表端点;
  • 无 OAuth/SSO;
  • 无 CSRF token 端点;
  • 登录失败计数为进程内字典(LOGIN_FAILS),多进程/重启后失效——未验证多实例部署行为;
  • /api/me 前端未调用(用 /api/auth/status 替代),仅服务端实现。

4. 运行生命周期

运行状态枚举(server.py:31、common.py:482-483):

queued → running → succeeded | failed | cancelled | timeout

cancelled 可在 queued 阶段直接产生;running 阶段取消先置 cancel_requested=1,由 worker 终止后落终态。

4.1 提交运行

POST /api/runs
Content-Type: application/json
X-CloudLab-Client: ide
Idempotency-Key: <可选,1-128 个可打印 ASCII>

{
  "projectId": "proj-...",
  "experimentId": "exp-...",
  "params": { "...": "..." },
  "inputs": {
    "inputId": {"kind": "builtin", "path": "data/..."} |
               {"kind": "upload", "uploadId": "up-..."}
  },
  "priority": "normal" | "batch"
}

服务端校验(server.py:1310-1382):

检查 失败响应
projectId、experimentId 必填 400 invalid
项目角色至少 runner 403 forbidden
实验存在 404 not_found
参数按 manifest 校验(数字范围/select/required) 400 invalid_input
输入按 manifest 校验(builtin 路径必须位于站点内;upload 必须属于当前用户) 400 invalid_input
priority 仅 `normal batch`
全局队列满(默认上限 1000) 429 queue_full + Retry-After
当前用户活跃运行(queued+running)达 MAX_RUNS_PER_USER(默认 2) 429 quota_exceeded
项目 active 达 max_active_runs 429 project_quota_exceeded
同 key 但项目/实验/参数/输入/优先级不同 409 idempotency_conflict

成功:

  • 首次提交 201 {"run": {...}};
  • 幂等重放 200 {"run": {...}, "idempotentReplay": true},响应头 Idempotent-Replayed: true;
  • 新运行初始 status="queued",并写一条 system 日志「运行已进入队列,等待 worker 领取。」;
  • timeoutSec 取 manifest runtime.resources.timeout,夹在 10–1800 秒。

run 基础字段(server.py:117-141):

id, projectId, experimentId, experimentVersion, userId, status,
createdAt, startedAt, finishedAt, exitCode, cancelRequested,
timeoutSec, attempt, priority, requeuedFrom, reproducedFrom,
params, inputs, error, note, quality

full=true(提交、详情)额外含:manifest, result, provenance。列表/详情还会补充 experimentCode/experimentTitle/experimentType/username;详情再加 artifacts/logCount/queue/timeline/reproduction。

幂等性说明:服务端在 BEGIN IMMEDIATE 内先查同用户同 key 的运行,冲突返回 409;同一 key 重放返回原 run。S3-4 起 IDE 对每次提交生成 Idempotency-Key(app/ide-stream.js 的 idempotencyKey()):以 {projectId,experimentId,params,inputs,priority} 指纹判断是否同一次提交,同指纹的重试复用同一个键,成功后清理;超时/网络/5xx 保留键供用户重试,401/400/403/404/409 清理。前端不自动重试提交;409 idempotency_conflict 显示中文提示并清理当前键。

4.2 运行列表

GET /api/runs?projectId=<可选>&experimentId=<可选>&limit=100
  • limit 夹在 1–200,默认 50;无 projectId 时最多取 limit*3 后再按项目权限过滤;
  • 必须至少是目标项目 viewer;按 created_at DESC;
  • 返回 {runs:[...]},每项为基础字段 + 实验标题/代码/类型 + 用户名;
  • 无分页游标、无 total;未实现更早记录翻页。

4.3 运行详情

GET /api/runs/{id}

返回 {run: {...}},包含:

  • manifest:提交时冻结的实验定义;
  • result:worker 产出的 result.json 内容(无则 null);
  • provenance:溯源快照;
  • artifacts[]:{id,name,size,mime,sha256,url},url 已 URL 编码;
  • logCount、queue(队列位置/预估)、timeline(见 §4.6);
  • 若 reproducedFrom 存在,附 reproduction 报告。

权限:项目 viewer 及以上;非成员 403(不泄露运行是否存在之外的信息;不存在则 404)。

4.4 日志流(SSE)

GET /api/runs/{id}/events?since=<最后已见日志 id,初始 0>
Accept: text/event-stream
Cookie: cl_session=...

前端 ensureStream 在 ide.js:763:

new EventSource(CLStream.streamUrl(id, S.logCursors[id] || 0))

服务端(server.py:1547-1591):

  • 先鉴权(viewer),后写 SSE 头: Content-Type: text/event-stream; charset=utf-8、Cache-Control: no-store、Connection: close、X-Accel-Buffering: no;
  • 首帧 retry: 3000;
  • 日志帧:
id: 123
event: log
data: {"id":123,"ts":"2026-11-18T...","stream":"stdout","line":"..."}
  • 终态帧:
event: status
data: {"status":"succeeded","error":null,"exitCode":0,"finishedAt":"..."}
  • 终态帧后关闭连接;空闲每 15 次循环写 : ping;
  • 游标:显式 ?since= 优先,否则 Last-Event-ID,非法值回退 0。

前端行为(S3-4 起,见 app/ide-stream.js 与 §17.6):

  • 打开运行/重连时 URL 带当前游标 since=S.logCursors[id](初始 0),优先于浏览器的 Last-Event-ID;
  • log 事件取 ev.lastEventId || item.id,仅接受严格大于游标的事件(CLStream.shouldAccept),接受后用 nextCursor 单调推进;浏览器自动重连重放旧日志时被丢弃,不会重复 push;
  • log 事件 push 到 S.logs[id],超过 2500 条裁到最近 1800 条;当前打开的运行实时 append;
  • status 事件关闭 EventSource、清理 stream/重连 timer(保留游标防止重开重放)、更新详情、refreshRuns(true)、按状态 toast(完成/失败/取消/超时);
  • es.onerror:CONNECTING 交给浏览器自动重连;仅在 readyState === CLOSED 时按 CLStream.nextRetry(attempt)(1/2/4/8/16/30 秒封顶)手动重连,最多 6 次并同步 aria-live 播报。

未验证:反向代理下 SSE 是否被缓冲、是否 60s 超时;服务端依赖 Connection: close 而非分块保活。

4.5 运行操作

方法 路径 权限 请求 成功响应 前端入口
POST /api/runs/{id}/cancel 项目 runner;非本人提交需 editor — 200 {ok:true};终态时 {ok:true,status,alreadyTerminal:true} 详情「取消运行」+ confirm
POST /api/runs/{id}/note runner {note}(截断 8000 字) {ok:true,note} 详情备注保存
POST /api/runs/{id}/requeue 未逐行核对(按新运行创建) — 201 {run} failed/timeout 的「重新提交」
POST /api/runs/{id}/reproduce 同上 — 201 {run}(新运行 reproducedFrom 指向源) succeeded 的「复现校验」

取消语义:

  • queued:立即置 cancelled,写 system 日志与 cancelled 事件;
  • running:置 cancel_requested=1,写日志「收到取消请求,正在终止容器。」,不立即改状态;
  • 终态:幂等返回,不改数据。

requeue/reproduce 的具体创建逻辑在 create_requeued_run/create_reproduced_run(未逐行展开);响应均为新运行,不修改原运行。配额不足时与提交相同 429。

4.6 只读导出与溯源

方法 路径 响应 前端用法
GET /api/runs/{id}/timeline {schema:"cloudlab.run-timeline.v1", runId, count, events:[{id,ts,type,workerId,detail}]} 详情已内嵌 run.timeline,该独立端点前端未调用
GET /api/runs/{id}/reproduction 复现报告(见下) 详情内嵌;独立端点由「校验 JSON」新窗口打开
GET /api/runs/{id}/provenance {runId, provenance, integrity} 「溯源 JSON」新窗口打开
GET /api/runs/{id}/package ZIP(application/zip,文件名 cloudlab-run-{id}.zip) 「下载复现包」
GET /api/runs/{id}/export {envelope:{schema:"cloudlab.run.v2", exportedAt, run, appVersion}} JSON 导出;记录批量导出
GET /api/runs/{id}/artifacts/{name} 产物字节;默认 inline,?download=1 为 attachment 产物预览/下载

复现报告字段(server.py:368-465):

schema:"cloudlab.reproduction.v1", targetRunId, sourceRunId, checkedAt, method, limitations[],
state: not_a_reproduction | unavailable | pending | target_failed | completed,
match, sourceStatus, targetStatus, sourceExperimentVersion, targetExperimentVersion,
byteIdentical, contentEqual, metricsEqual, tablesEqual, seriesEqual, artifactsEqual,
sourceResultSha256, targetResultSha256, sourceResultSize, targetResultSize,
sourceArtifactCount, targetArtifactCount, differences[]

报告明确声明:验证的是"同一实现与快照下的可复现性",不是科学结论或湿实验验证。

溯源完整性(server.py:525-600):integrity.ok 在 schema 存在且无 critical 非 ok 检查时为 true;checks[] 含 id/label/status(ok|mismatch|missing|unknown)/critical/expected/actual,并给出 summary{ok,mismatch,missing,unknown}。

产物下载安全:解析后必须位于 DATA/runs/{id} 目录下,否则 403 forbidden「非法产物路径」;文件丢失 404;响应带 Cache-Control: private, max-age=60。

4.7 未实现

  • 无 DELETE /api/runs/{id};运行记录不可删除;
  • 无批量取消/批量重跑;
  • 无运行搜索/按状态过滤(runFilter 为前端过滤);
  • 无 WebSocket;仅有 SSE + 轮询。

5. 上传

5.1 上传文件

POST /api/uploads?name=<URL 编码文件名>
X-CloudLab-Client: ide
Content-Type: application/octet-stream
Content-Length: <字节数>

<原始字节>

服务端(server.py:1130-1147):

  • 文件名经 os.path.basename 取基名、反斜杠归一、截断 160 字符;
  • 空文件 → 400 invalid「文件为空」;
  • 缺失 Content-Length → 411 length_required;
  • 超过 MAX_UPLOAD=50MB → 413 too_large「文件超过上限(50 MB)」;
  • 存储到 DATA/uploads/{upload_id}_{safe_name},权限 0644;
  • 写 uploads 表(含 sha256)与审计;
  • 201 {"upload":{"id","name","size","sha256"}}。

前端(ide.js:2010-2030):fetchTimeout(..., UPLOAD_TIMEOUT),成功取 data.upload.id 写入表单输入,toast「已上传 」;失败 toast 错误文本。上传中只显示 toast,无进度条。

5.2 我的上传列表

GET /api/uploads → {uploads:[{id,name,size,sha256,createdAt}]},最近 100 条,仅当前用户。前端未调用(上传后直接用返回值)。

5.3 约束

  • 仅支持单文件、整包 body;未实现分片/断点续传/多文件;
  • 无 MIME 白名单、无病毒扫描(服务端不校验内容类型);
  • 50MB 在 60s 超时下需要至少约 0.84MB/s 上行;弱网可能超时,前端无重试按钮,需重新选择文件;
  • 上传 ID 与运行输入绑定,validate_run_inputs 校验归属,防止引用他人上传。

6. 项目、成员与配额

方法 路径 权限 说明
GET /api/projects 登录 {projects:[...]};管理员看全部
POST /api/projects 平台 admin {name,description},201 {project};创建者自动 owner
PATCH /api/projects/{pid} 项目 owner 可改 name、description
GET /api/projects/{pid}/members 项目 viewer {members:[{id,username,globalRole,role,createdAt}]}
POST /api/projects/{pid}/members 项目 owner {username,role};用户不存在 404;角色非法 400;已存在则更新角色
PATCH /api/projects/{pid}/members/{uid} 项目 owner {role}
DELETE /api/projects/{pid}/members/{uid} 项目 owner 最后一个 owner 不可删,400 invalid
GET /api/projects/{pid}/quota 项目 viewer {quota:{maxActiveRuns,maxRunning,usage}}
PATCH /api/projects/{pid}/quota 项目 owner {maxActiveRuns,maxRunning},1–100 整数,maxRunning<=maxActiveRuns

角色顺序:viewer < runner < editor < owner(common.py:33)。写操作的最小角色按各端点实现:成员管理要求 owner;项目修改要求 owner;配额修改要求 owner;运行提交要求 runner。

前端实际使用:GET members、POST members、PATCH members/{uid}、DELETE members/{uid}、PATCH quota(ide.js:635/2096/2102/2126/2113)。GET/POST /api/projects、PATCH /api/projects/{pid} 前端未调用(项目列表来自登录/状态响应)。

6.1 未实现/未验证

  • 无邀请链接/邮件邀请;
  • 无成员转让 owner 的专用端点;只能用 PATCH 改角色。服务端仅对 DELETE 校验“至少保留一名 owner”,PATCH 降级最后一名 owner 未校验(潜在缺口,未验证后果);
  • 无项目删除;
  • 管理员创建用户时可选 projectId/projectRole,但仅当管理员是该项目的成员才会加入(server.py:1272-1275)——语义较隐蔽,未在 UI 验证。

7. 实验、模型卡与记录

7.1 实验

方法 路径 权限 说明
GET /api/experiments 登录 可选 `?type=bio
GET /api/experiments/{eid} 登录 {experiment: manifest}
PUT /api/experiments/{eid} 平台 admin 或任一项目 editor/owner {manifest};不可改 id/type/code/op/runtime/inputs/outputs;版本自增;校验 manifest
GET /api/model-cards 登录 {modelCards:[{id,code,type,title,version,modelCard,quality}]}

PUT 的不可变字段返回 400 immutable「字段不可修改: 」;校验失败由 validate_manifest 抛 400。前端用于"实验定义"编辑(ide.js:2084),不涉及运行提交。

/api/model-cards 服务端已实现,IDE 前端未调用,不在现有 UI 验证范围内。

7.2 记录

GET /api/records?projectId=<可选>(server.py:1194-1208):

  • 仅取终态运行(succeeded/failed/cancelled/timeout),最多 200 条,按创建时间倒序;
  • 必须对每个运行所属项目有角色,否则跳过;
  • 字段:id, projectId, experimentId, experimentCode, experimentTitle, type, status, createdAt, note, summary;
  • 无分页、无时间过滤、无全文搜索。

重要区分:records.html 使用 record-store.js 的 localStorage(cloudlab_room_records_v2),完全不调用 /api/records;两套"记录"不共享数据。详见 UX-AUDIT.md。


8. 容量、统计、Worker 与管理

8.1 平台元信息

GET /api/meta → {version, experiments:{type:n}, runs:{status:n}, maxRuns, maxRunsPerUser, maxQueuedRuns, projects}。前端未调用。

8.2 容量

GET /api/capacity(common.py:783-850):

capacity, active, queued, queueLimit, queueFull, acceptingRuns,
retryAfterSeconds, availableSlots, perUserLimit,
user:{active,queued,remaining,canSubmit},
workerOnline, workerCount, workers[], averageRuntimeSeconds,
estimatedWaitSeconds, estimateBasis, queuedRuns[], time
  • estimatedWaitSeconds 基于最近 20 次成功运行平均耗时与队列波次,服务端明确标注"不保证开始时间";
  • worker 离线或历史不足时 estimatedWaitSeconds=null,estimateBasis 给出原因;
  • queuedRuns[] 含每个排队运行的队列位置摘要。

前端每 10 秒 loadStats(其中会取 /api/capacity,ide.js:660),并渲染状态栏。

8.3 统计

GET /api/stats:

active, queued, capacity, perUserLimit, workerOnline, workerCount,
workers[], queue{}, time,
research:{experiments,validated,modelTier,unvalidated}

queue 为队列快照(见下)。前端每 10 秒刷新。

8.4 Worker

GET /api/workers → {workers:[...], queue:{...}, time}。

worker 字段(common.py:622-694):id,hostname,node,version,capacity,status(online|draining|offline),online,claiming,startedAt,lastSeen,currentRuns,runs[],legacy;在线窗口 20 秒。

管理员操作:

POST /api/admin/workers/{wid}/drain|resume,body {};仅平台 admin;未注册 404;成功 {ok:true,worker,queue}。

8.5 管理端点

方法 路径 权限 说明
GET /api/admin/users admin {users:[public_user]}
POST /api/admin/users admin {username,password,role,projectId?,projectRole?};用户名 ^[A-Za-z0-9_.-]{3,32}$,密码 ≥8,role `user
PATCH /api/admin/users/{uid} admin {password?} 或 {disabled?};密码 ≥8;返回 {ok:true};未校验 uid 是否存在,也不阻止管理员禁用自己(未测试)
GET /api/admin/audit admin {audit:[...]},最近 200 条,倒序

上述四个端点前端均使用(ide.js:668/2135/2363/2368/2154)。


9. 静态数据与无 API 页面

以下路径不是 /api 契约,但属于前端数据依赖,列出避免误判为后端接口:

页面/模块 路径 方式 失败表现
实验台 bench /app/data/mol/{key}.json fetchJSONTimed,15s 3D 面板空态 + 「重试」;toast
实验台 bench /{编码后的资料路径} fetchTextTimed,15s 序列/数据集读取失败 toast
资料浏览 browse /app/data/files.json 原生 fetch(无超时) 两栏分别显示失败 + 「重新加载」
生信数据库 /生信数据库资料库/catalog.json 原生 fetch(cache:no-store) .cl-error + 「重试」
对比-数据 meta.path 指向的静态文件 fetch(..., {cache:'force-cache'}) 需看页面实现,未逐页验证
资料库 shell /app/data/*、/{资料路径} 原生 fetch 各面板自定义

结论:browse/bio-databases/bench/compare 均不依赖控制面 API;只有 IDE 走 /api。因此 API 故障不影响"实验楼"页面浏览,但影响 IDE 登录与运行。


10. 错误结构

10.1 服务端响应

统一错误(server.py:907-911):

{"error": "人类可读中文", "code": "machine_code"}

未捕获异常(server.py:912-918):

{"error": "服务器内部错误", "detail": "<异常字符串>"}

注意:500 响应没有 code,且 detail 可能包含内部路径/异常信息,生产环境应视为信息泄露风险(当前实现如此,未做脱敏)。

10.2 错误码表

HTTP code 典型触发 前端可重试
400 invalid 参数缺失/非法、项目名空、配额非整数 否
400 invalid_input 缺参数/输入、数字越界、上传不存在 否
400 bad_json JSON 解析失败 否
400 immutable 修改实验不可变字段 否
400 bad_request Content-Length 非法 否
401 unauthorized 未登录/会话过期 否(转登录)
401 bad_credentials 登录用户名或密码错误 否
403 disabled 账号禁用 否
403 csrf 写请求缺 X-CloudLab-Client: ide 否
403 forbidden 角色不足/非项目成员/非法产物路径 否
404 not_found 运行/实验/用户/产物/接口不存在 否
405 method_not_allowed 路径存在但方法不支持 否
409 conflict 用户名已存在 否
409 idempotency_conflict 同 key 不同载荷 否
411 length_required 上传缺 Content-Length 否
413 too_large 上传 >50MB 否
429 rate_limited 登录失败过多 稍后
429 quota_exceeded 用户活跃运行达上限 稍后/取消
429 project_quota_exceeded 项目活跃运行达上限 稍后/取消/调额
429 queue_full 全局队列满(带 Retry-After) 是
500 (无 code) 未捕获异常 是

前端 retryable 默认规则:无 status、408、429、≥500 → true;401 显式 false。因此 queue_full、quota_exceeded 等 429 在 UI 上会显示重试按钮,但 quota_exceeded 立即重试通常仍失败——文案未区分"稍后重试"与"需取消/调额"。

10.3 客户端兜底文案(无服务端 error 时)

状态 文案
400 请求参数有误,请检查后重试
403 没有权限执行此操作,请联系项目管理员
404 请求的资源不存在或已被删除
409 请求冲突,请刷新后重试
413 文件超出大小限制
429 请求过于频繁,请稍后再试
≥500 服务器暂时不可用,请稍后重试
其他 请求失败(HTTP n)

11. 加载 / 空 / 错误 / 重试 UI 映射

场景 触发 UI 可访问性 重试
启动检查会话 checkAuth #boot-loading — 自动
服务不可达/5xx checkAuth catch #auth-offline + 文案(超时 15 秒 / 无法连接 / HTTP n) 文本 「重试连接」#login-retry 调 recheckAuth
登录失败 api('/api/auth/login') #login-error 文本;按钮恢复 按钮 aria-busy 期间禁用 err.retryable 时显示重试
初始化加载 afterLogin showAppLoading 在 #editor 内渲染 .req-loading[role=status][aria-live=polite] + spinner live region 失败 showAlert(err, afterLogin) + toast
应用内错误 showAlert #app-alert,含 <code>code</code>、关闭按钮;`data-kind=warn error` announce 写 #req-announce
提交运行 submitRun 按钮「提交中…」禁用;成功 toast「已提交:xxxxxx」;失败 toast — 无内联重试,需再点提交
上传 uploadFor toast「上传 …」→ 成功/失败 toast — 无重试按钮,需重新选择
取消 cancelRun confirm → toast「已发送取消请求」 — —
运行结束 SSE status toast(完成/失败/取消/超时)+ 刷新详情 — —
空记录 loadRecords 空态(前端渲染) — —
空运行列表 refreshRuns 空态 — —
静态资料缺失 getJson(...).catch(null) 静默降级,不阻塞 IDE — 无
3D 分子缺失 bench openMolecule 面板 .cl-empty + 「重试」按钮 面板 aria-live=polite 是

12. SSE 与轮询

机制 频率/触发 用途 证据
SSE 打开运行详情时 实时日志 + 终态通知 ide.js:763
loadStats 10 秒 /api/stats + /api/capacity,状态栏/队列 ide.js:531
refreshRuns(true) 20 秒且页面可见 运行列表兜底刷新 ide.js:532-534
详情手动刷新 「刷新」按钮 GET /api/runs/{id} ide.js

设计意图:SSE 为主,轮询兜底。缺口:

  • SSE 断线由浏览器自动重连;致命关闭时客户端按 1→30 秒退避手动重连,最多 6 次,事件按 id 去重(§4.4、§17.6);
  • 轮询固定 20 秒,后台标签页暂停(visibilityState==='visible'),恢复可见后需等下一次;
  • 无"最后更新时间"提示,用户可能不知道数据已陈旧。

13. 契约兼容与变更流程

13.1 当前版本标识

  • HTTP Server: CloudLabAPI/3.0;
  • JSON 内 version/appVersion: "3.0.0";
  • 导出信封 schema:cloudlab.run.v2、cloudlab.records.v2;
  • 溯源:cloudlab.provenance.v1;
  • 时间线:cloudlab.run-timeline.v1;
  • 复现:cloudlab.reproduction.v1。

未实现:OpenAPI/Swagger、JSON Schema 文件、契约测试、版本协商头。本文即当前唯一契约说明。

13.2 兼容规则

  1. 加法优先:新增响应字段不视为破坏;前端应忽略未知字段(现有代码多为按名取用,兼容)。
  2. 不改语义:已有字段的类型/含义不变;需要改语义时新增字段并双写一段时间。
  3. 不改状态枚举:新增运行状态必须同步前端 statusLabel/样式/SSE 处理,否则会显示未知状态。
  4. 错误码稳定:新增 code 可以,但不要把已有 code 改义;前端仅对 401 做特殊分支。
  5. URL 版本化未实现:/api/ 无 /v1 前缀;破坏性变更只能靠部署协调。

13.3 变更流程(建议,尚未强制)

  1. 先改 server.py 并保持旧字段;在本文更新端点/字段/错误码;
  2. 再改 ide.js,所有请求仍走 api()/fetchTimeout;
  3. 若涉及写请求,确认 X-CloudLab-Client: ide 仍发送;
  4. 若涉及运行/导出,校验 schema 字符串是否需要升版;
  5. 跑 §14 回归;UI 侧对照 UX-AUDIT.md 的验收项;
  6. 部署时同步前端缓存版本(?v=)与 API 版本。

14. 回归检查点

14.1 接口冒烟(curl,替换 host/cookie)

BASE=http://127.0.0.1:8000

# 1. 健康检查
curl -sS $BASE/api/health

# 2. 未登录状态应 200 + user:null
curl -sS $BASE/api/auth/status

# 3. 未登录访问受保护接口应 401
curl -sS -i $BASE/api/runs

# 4. 登录失败应 401 bad_credentials
curl -sS -i -X POST $BASE/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"nobody","password":"wrong"}'

# 5. 登录成功并保存 Cookie
curl -sS -c /tmp/cl.cookie -X POST $BASE/api/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"<user>","password":"<pass>"}'

# 6. 写请求缺客户端头应 403 csrf
curl -sS -b /tmp/cl.cookie -i -X POST $BASE/api/runs \
  -H 'Content-Type: application/json' -d '{}'

# 7. 带客户端头后应进入业务校验(非 403 csrf)
curl -sS -b /tmp/cl.cookie -i -X POST $BASE/api/runs \
  -H 'X-CloudLab-Client: ide' -H 'Content-Type: application/json' -d '{}'

# 8. 列表与详情
curl -sS -b /tmp/cl.cookie "$BASE/api/runs?limit=5"
curl -sS -b /tmp/cl.cookie "$BASE/api/runs/<run-id>"

# 9. SSE(应看到 retry: 3000 与 event: log)
curl -sS -N -b /tmp/cl.cookie "$BASE/api/runs/<run-id>/events?since=0"

# 10. 导出信封
curl -sS -b /tmp/cl.cookie "$BASE/api/runs/<run-id>/export"

# 11. 上传超限(应 413 too_large)
head -c 52428801 /dev/zero > /tmp/big.bin
curl -sS -b /tmp/cl.cookie -i -X POST "$BASE/api/uploads?name=big.bin" \
  -H 'X-CloudLab-Client: ide' -H 'Content-Type: application/octet-stream' \
  --data-binary @/tmp/big.bin

# 12. 退出
curl -sS -b /tmp/cl.cookie -X POST $BASE/api/auth/logout

14.2 前端回归

  • 未登录打开 IDE → 登录页,无控制台异常;
  • 错误密码 → #login-error 中文文案,按钮恢复可用;
  • 断网打开 → #auth-offline + 「重试连接」;
  • 登录成功 → 初始化 loading → 三栏数据渲染;
  • 提交运行 → 按钮「提交中…」→ toast → 列表出现 queued;
  • 打开运行 → SSE 日志增长;结束收到 status toast;
  • 取消 queued/running → 状态变化符合预期;
  • 上传 >50MB → 413 文案;上传正常文件 → 输入绑定成功;
  • 列表空态/记录空态不报错;
  • 401(手动清 Cookie 后点操作)→ 回登录页;
  • 429 配额 → toast 文案可理解(当前无专门引导)。

14.3 契约静态检查

cd /root/dsh_workspace/cloudlab-app
# 所有 API 调用点
grep -nE "\b(api|fetch|EventSource)\(|/api/" app/ide.js | sed -n '1,120p'
# 服务端路由
grep -nE 'path == "/api/|re\.match\(r"\^/api/' ../cloudlab-platform/server.py
# CSRF / 超时 / 状态机
grep -nE "REQ_TIMEOUT|UPLOAD_TIMEOUT|X-CloudLab-Client|Idempotency-Key|TERMINAL" app/ide.js app/ide-stream.js ../cloudlab-platform/server.py

15. 未实现 / 未验证清单

15.1 未实现(代码中不存在)

  • OpenAPI/Swagger、JSON Schema、契约版本协商;
  • 注册、找回密码、自助改密、刷新 token、会话管理;
  • CSRF token(只有自定义头标记);
  • DELETE /api/runs/{id}、运行批量操作、运行搜索分页;
  • 分片/断点续传、多文件上传、上传进度;
  • 项目删除、邀请链接、owner 转让专用接口;
  • CORS 配置(当前仅同源可用);
  • 请求 ID/审计追踪 ID 透传;
  • 429 Retry-After 的前端消费;
  • 500 detail 脱敏。

15.2 服务端已实现但前端未调用(未在 UI 验证)

端点 说明
GET /api/me 前端用 /api/auth/status
GET /api/meta 无调用
GET /api/model-cards 无调用
GET /api/runs/{id}/timeline 详情已内嵌 timeline,独立端点未调用
GET /api/uploads 上传后直接用响应,不拉列表
GET/POST /api/projects 项目来自登录响应;无创建 UI
PATCH /api/projects/{pid} 无编辑项目 UI
GET /api/projects/{pid}/quota 只 PATCH,不单独 GET

15.3 未验证(需环境/代理/人工确认)

  1. 反向代理对 SSE 的缓冲与超时;X-Accel-Buffering 是否生效;
  2. Secure Cookie 在生产 HTTPS 下是否强制(依赖 X-Forwarded-Proto 或环境变量);
  3. 多进程/多实例下的登录失败计数与 SQLite 写并发;
  4. 上传 50MB 在真实弱网下是否触及 60 秒超时;
  5. PATCH /api/admin/users/{uid} 对不存在 uid 的行为(当前返回 ok,未测试);
  6. 管理员禁用自己后的会话行为;
  7. requeue/reproduce 的完整创建逻辑与配额边界(未逐行展开);
  8. 运行详情 queue 字段的具体形状(run_queue_summary 未逐字段核对);
  9. 各浏览器 EventSource 对 Connection: close 的重连表现;
  10. /api/records 与本地记录的产品语义是否应合并(当前是两套系统)。

16. 最后核对命令

cd /root/dsh_workspace/cloudlab-app

# 1. 前端所有请求点
grep -nE "\b(api|fetch|fetchTimeout|EventSource|window\.open)\(" app/ide.js
grep -nE "\b(fetch|fetchJSONTimed|fetchTextTimed|fetchTimed)\(" app/bench.js
grep -rnE "fetch\(|EventSource\(" app/*.js | grep -vE 'ide.js|bench.js'

# 2. 请求层常量/错误
sed -n '300,380p' app/ide.js
sed -n '1,60p' app/bench.js

# 3. 服务端路由与鉴权
grep -nE '^    def (dispatch|login|logout|route|create_run|list_runs|get_run|cancel_run|note_run|run_events|read_raw)' ../cloudlab-platform/server.py
sed -n '878,955p' ../cloudlab-platform/server.py
sed -n '1130,1320p' ../cloudlab-platform/server.py
sed -n '1547,1601p' ../cloudlab-platform/server.py

# 4. 常量与 schema
grep -nE '^(VERSION|MAX_RUNS|MAX_RUNS_PER_USER|MAX_UPLOAD|MAX_QUEUE_RUNS|QUEUE_RETRY_AFTER|ROLE_ORDER)' ../cloudlab-platform/common.py
grep -n 'schema' ../cloudlab-platform/server.py | head -20

# 5. 前端是否使用可选端点
grep -nE '/api/(me|meta|model-cards|uploads|projects)' app/ide.js
grep -n 'Idempotency-Key' app/ide.js ../cloudlab-platform/server.py

17. IDE 页面规格(S2-5:标题栏 64/58 与登录文案下限,非接口)

本节记录纯前端视觉规格,不改变任何 /api/* 接口。S2-5 仅修改 app/ide.css;app/ide.js、app/ide.html、server.py 未改动。

17.1 规格与选择器(app/ide.css,行号为 2026-11-18 修改后)

选择器 属性 桌面 移动端(≤900px / ≤560px) 当前行号
.ide grid-template-rows 首行 64px 58px(≤900px) 62 / 427
.ide.panel-closed grid-template-rows 首行 64px 58px(≤900px) 63 / 428
.ide-titlebar min-height 64px 58px(≤560px) 73 / 466
.ide-sidebar top / bottom 由 grid 决定 固定 top:58px、bottom:54px(≤900px) 436
.side-backdrop inset — 58px 0 54px 0(≤900px) 438
.brand-mark width/height 32×32 同左(登录页 .auth-brand .brand-mark 32×32,行 353) 76
.brand-name font-size 15.5px 12.5px(≤560px,行 467) 77 / 467
.brand-sub font-size 12px ≤1050px 隐藏(行 422、443) 78
.icon-btn width/height 34×34 32×32(≤560px) 90 / 470
.user-chip font-size 11.5px 同左,用户名 ≤900px 隐藏(行 451) 94
.worker-pill font-size 11.5px 同左,文字 ≤900px 隐藏(行 449) 87
.auth-kicker font-size 11px 同左 355
.auth-note / .auth-note code font-size 11px / 11px 同左 372 / 373

未改动(保持不变):底部 activity 栏 height:54px(行 431)、移动端面板 bottom:54px(行 452)、.ide-status 26px 等。

17.2 实测(Chromium 130.0.6723.31,静态服务 http://127.0.0.1:8099)

验证方式:headless Chromium + CDP,加载 /app/ide.html 后隐藏 #boot-loading/#auth/#app-alert、移除 #app 的 hidden(静态服务无 API 后端时 /api/auth/status 返回 404,属预期环境限制),再读取 getBoundingClientRect()。

视口 .ide-titlebar 高度 主区 top→bottom 横向溢出 #editor 溢出 标题栏子元素越界/文字截断 JS 控制台错误
1440×1000 64.00px 65 → 750px(状态栏 26px) 0(scrollWidth 1440) 0 / 0 无(最右 1424 ≤ 1440) 0
390×844 58.00px 58 → 790px(底部 54px activity 栏) 0(scrollWidth 390) 0 / 0 无(最右 380 ≤ 390) 0
  • 390×844 下 .ide-sidebar 计算样式为 position:fixed; top:58px,与标题栏底部对齐。
  • 唯一失败请求:GET /api/auth/status 404(静态服务无 API 后端,非本次样式改动引入)。
  • 截图:/tmp/cloudlab-s2-task14/ide-1440.png、/tmp/cloudlab-s2-task14/ide-390.png;测量原始数据 /tmp/cloudlab-s2-task14/measure.json(临时文件,不入库)。

17.3 登录页文案下限

#auth 内最小字号为 11px(.auth-kicker、.auth-note、.auth-note code、.auth-brand em),表单标签/错误/重试/离线提示 12–13px,输入 15px;本次将原 10px 的 .auth-kicker 与 10.5px 的 .auth-note code 提升到 11px。 工作台内部仍有 8.5–10.5px 的密集信息文本(状态栏、表格工具等),属于 IDE 密排界面的既有例外,不在 S2-5 范围,后续如需统一另行立项。

17.4 回滚方式

纯 CSS 改动,无 JS/HTML/接口依赖。按选择器回退即可(行号为当前文件位置,插入其他规则后以选择器为准):

  1. .ide(行 62)与 .ide.panel-closed(行 63)首行 64px → 54px;
  2. .ide-titlebar(行 73)删除 min-height:64px;
  3. ≤900px 的 .ide/.ide.panel-closed 首行 58px → 54px(行 427/428),.ide-sidebar top:58px → 54px(行 436),.side-backdrop inset 首值 58px → 54px(行 438),≤560px 的 .ide-titlebar 删除 min-height:58px(行 466);
  4. 尺寸回退(可选):.brand-mark 32→29、.brand-name 15.5→15、.brand-sub 12→11、.icon-btn 34→31(≤560px 32→29)、.user-chip 11.5→11、.worker-pill 11.5→10.5、.auth-kicker 11→10、.auth-note code 11→10.5。

也可在文件末尾追加覆盖块(如 .ide{grid-template-rows:54px minmax(0,1fr) 224px 26px} 等)快速回滚,但 64/58 是 Sprint 2 目标规格,不建议回滚。

17.5 兼容性

  • 不涉及 API:端点、方法、请求/响应字段、X-CloudLab-Client 头、15s 超时与重试逻辑均未变,本文件第 1–16 节继续有效。
  • 未改 app.css、shell.js 或其他页面;IDE 仍使用独立 CSS,不引入全局样式表。

17.6 S3-4 SSE 续传与提交幂等(客户端行为;服务端未改)

新增 app/ide-stream.js 纯函数模块(UMD:浏览器 window.CLStream、Node module.exports),ide.html 在 ide.js 之前以 <script src="/app/ide-stream.js" defer> 引入。ide.js 通过 CLStream 调用,helper 缺失时保留最小回退;/api/* 路径、方法、请求体语义均未变,仅 POST /api/runs 新增可选 Idempotency-Key 请求头(使用服务端既有能力)。

项 状态 实现与行为 证据
SSE 续传 已实现 ensureStream 读取 S.logCursors[id] 生成 ?since=;log 帧以 ev.lastEventId || item.id 推进游标;手动重连沿用同一游标 ide.js:763 ensureStream;app/ide-stream.js streamUrl/nextCursor
SSE 去重 已实现 shouldAccept 只接受严格大于游标的事件;浏览器自动重连重放旧日志时丢弃,S.logs 不重复 app/ide-stream.js shouldAccept
断线退避 已实现 CONNECTING 交给浏览器;CLOSED 时 nextRetry 1/2/4/8/16/30 秒封顶,最多 6 次;status 终态清理 stream/timer,保留游标 app/ide-stream.js nextRetry/canRetry;ide.js:760 clearStreamTimer
提交幂等键 已实现 submitRun 按请求体指纹生成/复用键;成功或 4xx 清理;超时/网络/5xx 保留供重试;参数变化生成新键 ide.js:2026 submitRun;app/ide-stream.js idempotencyKey
409 处理 已实现 idempotency_conflict 中文提示、不自动重试、清理当前键 ide.js submitRun catch
PATCH 最后 owner 校验 仍遗留 服务端未拦截「最后一个 owner 被降级」;本轮不改服务端,仅记录 server.py 成员 PATCH

验证(2026-11-18):

cd /root/dsh_workspace/cloudlab-app
node --check app/ide.js && node --check app/ide-stream.js
node tests/ide-stream.test.js   # 9 passed, 0 failed

浏览器端 mock 验证(Chromium 130 headless + CDP 注入假 API/EventSource,静态服务 http://127.0.0.1:8099):首次 POST /api/runs 返回 503、用户再次提交复用同一 Idempotency-Key(cl-mwmfq4ml-c366d8db2f089bdba926facf,36 字符、可打印)且请求体一致;SSE 首连 ?since=0,日志 id 11/12/13 后重放 id 12 未重复渲染,模拟 CLOSED 后 1.3s 重连为 ?since=13 并补 id 14(共 4 行),status succeeded 后 stream 关闭、toast「运行完成:abc123」;console 异常 0、横向溢出 0。证据:/tmp/cloudlab-s3-task19/functional.json、functional-1440.png。

回滚方式:删除 app/ide-stream.js 与 tests/ide-stream.test.js,移除 ide.html 中 helper <script>,并将 ide.js 的 ensureStream/submitRun 恢复为改动前版本(?since=0、无 Idempotency-Key);接口契约本身未变化,无服务端回滚。

18. 交叉引用