33 lines
4.5 KiB
Markdown
33 lines
4.5 KiB
Markdown
# 前后端接口对接
|
||
|
||
根目录 API.md 是接口契约。公共请求封装与响应类型在 src/api.ts，实例、备份及管理员等组件也通过 api.request 发起业务请求。本文记录当前前端依赖，不将界面入口或请求成功等同于端到端验收。
|
||
|
||
## 运行与认证
|
||
|
||
Vite 开发监听 127.0.0.1，默认端口 5173（占用时自动尝试后续端口），代理至 http://127.0.0.1:8088；/dsh 启用 WebSocket 代理。生产构建目录为 web/dist，需由后端同源提供静态页面、/api 和 /dsh。
|
||
|
||
- 登录和 /api/me 返回 {user,csrf_token}。认证使用 HttpOnly Cookie；浏览器请求携带同源 Cookie，非 GET 请求从可读的 dsh_csrf Cookie 设置 X-CSRF-Token，而不是只使用内存中的旧 token。
|
||
- 存在 CSRF token 时，非登录/刷新请求的首次 401 会尝试恢复会话，再重试原请求；使用页内共享 Promise 和可用时的 Web Locks 协调刷新，刷新冲突后复验 /api/me。无法恢复的会话通过 session-expired 通知界面。
|
||
- 错误响应读取 {error:string}；网络错误和非 JSON 成功响应均显示明确错误，不模拟成功。文件/备份下载和图片预览直接使用同源资源地址，不经过 JSON 请求封装。
|
||
|
||
## 响应结构与镜像构建
|
||
|
||
- 实例、镜像、构建历史、工作区目录、用户、审计、备份及孤儿容器的 GET 列表响应为顶层数组，不使用 data envelope；空列表应返回 []。其中 /api/orphans 返回容器 ID 字符串数组；详情、用量和操作结果不适用此列表约定。
|
||
- 镜像类型含 id、可选 image_id、version、status、admission、admission_reason、selectable 等字段；前端提交镜像标识时使用 image_id || id，仅允许 status=available 且 selectable=true 的镜像用于创建/升级。
|
||
- 构建历史通过 GET /api/builds?limit=...&offset=... 获取摘要；前端每页显示 20 条、多取 1 条判断下一页，不读取 X-Has-More。日志按需通过 GET /api/builds/{id} 的 logs 字段获取。
|
||
- 管理员通过 GET /api/releases/latest 检查 Git 发布，确认后 POST /api/releases/build {commit}；构建来源字段包括 release_id、source_commit、source_repository。镜像准入使用 POST /api/images/admission {image_id,state,evidence}。不使用旧的 /api/latest、/api/compatibility、POST /api/builds 或创建意图接口。
|
||
- 工作区目录项读取 name/path/is_dir/size/mod_time；用量读取 used_bytes/quota_bytes；审计读取 user_id/created_at 等字段；备份读取 id/size/created_at。
|
||
|
||
## 已接入的业务操作
|
||
|
||
- 创建实例：POST /api/instances {name,image_id}，当前前端不发送 version。启动/停止/重启调用实例对应子路径；删除使用 DELETE /api/instances/{id}。显示后端返回的实例状态，不把操作名称当作运行状态。
|
||
- Profile：读取 /profile 和 /profile-preview；停止实例后 PUT /profile {content,restart:true} 保存并启动验证。日志读取 /logs 的 logs 字段。上述路径均位于 /api/instances/{id} 下。
|
||
- 备份：GET /api/instances/{id}/backups 列表，POST 同路径 JSON {password} 创建，multipart file,password 导入；GET 同路径 ?download={backup_id} 下载；POST /api/instances/{id}/restore {backup_id,password} 恢复。
|
||
- 升级：POST /api/instances/{id}/upgrade {image_id,password}。创建备份和升级使用当前登录密码；导入/恢复使用原包密码，旧平台 key 包可留空。恢复和升级有二次确认。
|
||
- 工作区：/api/ws/tree、usage、mkdir、rename、delete、upload、download，并通过 instance 参数选择实例；上传使用 multipart file,path。图片预览使用 /api/ws/image；文本读取 /api/ws/text 返回 {content,version}，保存 PUT 同路径 {content,version}，冲突不静默覆盖。
|
||
- 账户管理：本人 POST /api/me/password；管理员通过 /api/users 创建用户、PATCH 修改配额，通过 /api/users/reset-password 重设密码，并读取 /api/audit。本人改密后重新登录，管理员重设按 reauthenticate 决定是否退出当前会话。孤儿容器回收使用 /api/orphans，删除提交 id 与 confirm。
|
||
|
||
## 验证边界
|
||
|
||
在 web/ 执行 npm test 和 npm run build 获取当前测试与构建结果，不沿用早期测试数量或临时服务状态。单元测试包含 fetch 替身，不能证明真实后端、Docker、WS/SSE 或数据恢复流程已验收；真实联调需独立测试环境和授权账号，具体后端限制与验收记录见根目录 API.md、README.md、ACCEPTANCE.md。
|