git功能前端接口文档
This commit is contained in:
@@ -0,0 +1,617 @@
|
||||
# 仓库 ZIP、TAR.GZ 下载与 HTTPS Git 前端对接文档
|
||||
|
||||
本文供前端开发独立对接已实现的仓库归档下载、Git 克隆信息和项目 Git 凭据管理。前置条件是网站已有登录态,并已取得项目的 `projectCode`。本文所有域名、编码、SHA 和 Token 示例均为占位值。
|
||||
|
||||
## 1. 功能范围
|
||||
|
||||
| 功能 | 工作区 | 社区 |
|
||||
| --- | --- | --- |
|
||||
| 下载 ZIP、TAR.GZ | 登录用户下载本人项目;默认最新 main,也支持历史提交 | 可匿名下载当前已发布版本 |
|
||||
| clone、fetch、pull、push | 通过项目 Git Token 操作本人仓库 | 先 Fork 到自己的工作区,再使用副本的 Git 接入 |
|
||||
| Git LFS | 支持实体上传、下载和 verify | 不提供社区 Git 协议入口 |
|
||||
| 本地 push 后的网站变化 | 刷新工作区后显示最新内容和历史 | 保持原发布版本,用户手动发布后才更新 |
|
||||
|
||||
归档与 Git 的资源边界不同:
|
||||
|
||||
- ZIP、TAR.GZ 是仓库文件快照,不含提交历史;LFS 保留指针,不下载实体;子模块不递归下载。
|
||||
- Git clone/fetch 获取 Git 数据;安装并启用 git-lfs 后,客户端可通过 LFS 协议获取实体。子模块仍需客户端自行处理,不会自动递归下载。
|
||||
- 单独绑定于 OSS 的封面、URDF、STEP、GLB、零件、拼装及行走资源均不会自动加入归档或 Git 仓库。仓库内本来就有的同类文件按仓库内容处理。
|
||||
|
||||
## 2. 地址、身份与通用约定
|
||||
|
||||
### 2.1 两类入口
|
||||
|
||||
浏览器调用本文 `/api/**` 接口;本地 Git/git-lfs 客户端使用后端返回的 `cloneUrl`,访问 `/git/**`。
|
||||
|
||||
```text
|
||||
浏览器: /api/workspace/projects/{projectCode}/git → 获取连接信息
|
||||
浏览器: /api/workspace/projects/{projectCode}/git/tokens → 管理项目 Git Token
|
||||
终端: /git/projects/{projectCode}.git/... → Git/LFS 协议
|
||||
```
|
||||
|
||||
这两类路径由同一个社区 API 应用处理。`/git` 不带 `/api` 前缀。`cloneUrl` 可能使用与业务 API 不同的公网域名,前端必须使用接口返回值,不自行拼接、替换域名或改成 `/api/git`。
|
||||
|
||||
前端只需配置业务 `API_BASE`,例如同源代理 `/api`,或后端提供的完整 `https://api.example.com/api`。后文请求示例的 `path` 均不再重复 `/api`。
|
||||
|
||||
### 2.2 两类 Token
|
||||
|
||||
| 凭据 | 获取方式 | 使用位置 |
|
||||
| --- | --- | --- |
|
||||
| 网站登录 Token | 现有网页登录流程 | 浏览器请求头 `Authorization: Bearer <网站登录 Token>` |
|
||||
| 项目 Git Token | 本文创建凭据接口 | 本地 Git 的 HTTP Basic 密码;用户名使用连接信息中的 `username` |
|
||||
|
||||
两类 Token 不能互用。普通用户不需要 Gitea 账号;前端不接收、不配置 Gitea 管理凭据或技术账号凭据。项目 Git Token 继承现有网站登录的身份边界:当前邮箱加图片验证码不验证邮箱归属。
|
||||
|
||||
社区匿名下载建议不发送 Authorization;失效的网站 Token 即使用于公开接口,也可能导致 401。
|
||||
|
||||
### 2.3 JSON、编码与时间
|
||||
|
||||
成功的归档下载返回二进制,其余本文浏览器接口使用以下统一 JSON。所有成功响应均为 HTTP 200,包括创建、撤销;撤销成功 `data=null`。
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "OK",
|
||||
"message": "成功",
|
||||
"data": null,
|
||||
"requestId": "44444444444444444444444444444444"
|
||||
}
|
||||
```
|
||||
|
||||
失败使用非 2xx HTTP 状态及同样的包装,`code` 为错误码。按 HTTP 状态和 `code` 判断,不通过中文 `message` 区分错误;提示可展示 `message`,排查时提供 `requestId`。反向代理异常也可能返回非 JSON,前端需要兜底。
|
||||
|
||||
- `projectCode`、`userCode` 作为不透明字符串传递,兼容现有 12 位和历史 32 位编码;不要固定长度或使用数据库 ID。`tokenCode` 也是接口返回的业务编码。
|
||||
- SHA 必须使用完整的 40 或 64 位十六进制字符串,不提交页面展示的缩写。
|
||||
- 本文凭据时间为上海时间 `Asia/Shanghai`,格式如 `2026-11-03T10:00:00`,可能带小数秒、没有时区后缀;解析时补 `+08:00`,不要补 `Z`。
|
||||
- 请求体使用 JSON 时设置 `Content-Type: application/json`。无需跨域 Cookie,不设置 `credentials: 'include'`。
|
||||
- `/api/**` 按部署白名单支持跨域,暴露 `X-Request-Id`、`Content-Disposition`、`Retry-After`。本地开发可代理 `/api`;浏览器不需要代理或调用 `/git`。
|
||||
|
||||
## 3. 浏览器接口清单
|
||||
|
||||
以下路径均为完整路径;“登录”指网站 Bearer Token。
|
||||
|
||||
| 方法 | 路径 | 登录 | 成功 data / 响应 |
|
||||
| --- | --- | --- | --- |
|
||||
| GET | `/api/workspace/projects/{projectCode}/archive` | 必须,本人项目 | ZIP 或 TAR.GZ 附件 |
|
||||
| GET | `/api/community/projects/{projectCode}/archive` | 可匿名 | 当前发布版本附件 |
|
||||
| GET | `/api/workspace/projects/{projectCode}/git` | 必须,本人项目 | `GitConnection` |
|
||||
| GET | `/api/workspace/projects/{projectCode}/git/tokens` | 必须,本人项目 | `PageResult<GitTokenView>` |
|
||||
| POST | `/api/workspace/projects/{projectCode}/git/tokens` | 必须,本人项目 | `IssuedGitToken`,明文只返回一次 |
|
||||
| DELETE | `/api/workspace/projects/{projectCode}/git/tokens/{tokenCode}` | 必须,本人项目 | `null` |
|
||||
|
||||
## 4. ZIP、TAR.GZ 下载
|
||||
|
||||
### 4.1 请求参数与版本
|
||||
|
||||
两个归档接口使用以下查询参数,无请求体:
|
||||
|
||||
| 参数 | 工作区 | 社区 | 约束 |
|
||||
| --- | --- | --- | --- |
|
||||
| `format` | 可选 | 可选 | 省略为 `zip`;仅接受 `zip`、`tar.gz`,区分大小写。空字符串也返回 400 |
|
||||
| `commitSha` | 可选 | 禁止 | 工作区省略时读取当前 main;指定时使用本项目完整提交 SHA。社区只要出现该参数就返回 400,包括 `commitSha=` |
|
||||
|
||||
```http
|
||||
GET /api/workspace/projects/7m4k9x2p8q6r/archive?format=zip
|
||||
Authorization: Bearer <网站登录 Token>
|
||||
```
|
||||
|
||||
```http
|
||||
GET /api/community/projects/7m4k9x2p8q6r/archive?format=tar.gz
|
||||
```
|
||||
|
||||
工作区仅允许本人未删除且 READY 的项目;社区仅允许 READY、已发布且未删除的项目。其他用户的工作区项目返回 404。
|
||||
|
||||
服务端在受理时固定本次下载的完整 SHA。假设发布 A 后工作区又提交 B:社区下载 A,工作区默认下载 B,工作区传入 A 的 SHA 则下载 A。传输期间的新提交或重新发布不会切换本次版本;撤回或删除后的新社区下载返回 404。
|
||||
|
||||
### 4.2 成功响应与下载交互
|
||||
|
||||
| 项目 | ZIP | TAR.GZ |
|
||||
| --- | --- | --- |
|
||||
| HTTP 状态 | 200 | 200 |
|
||||
| Content-Type | `application/zip` | `application/gzip` |
|
||||
| 文件名 | `{projectCode}-{SHA前12位}.zip` | `{projectCode}-{SHA前12位}.tar.gz` |
|
||||
|
||||
响应带 `Content-Disposition: attachment`、`Cache-Control: no-store`、`X-Request-Id`。`Content-Length` 不保证存在。归档根目录、文件层级、符号链接及 `.gitattributes` 导出行为沿用 Gitea。
|
||||
|
||||
页面提供“下载 ZIP”“下载 TAR.GZ”,历史版本页面的工作区下载传入对应完整 SHA。点击后展示下载中状态、防止重复点击,提供取消;成功按 Blob 保存,失败先按 JSON 解析。工作区不能用无法附加 Bearer 请求头的普通下载链接,也不能把 Token 拼到 URL。
|
||||
|
||||
归档默认最大 1 GiB、上游处理和读取预算 5 分钟、每实例并发 2、每 IP 每分钟 10 次,部署可调整。此限制独立于普通文件 50 MiB 读取限制。通用请求拦截器不要使用 10~30 秒超时提前截断归档;如设置超时,应与后端约定,默认预留至少 400 秒。
|
||||
|
||||
发附件前的错误返回 JSON;传输开始后的错误会停止响应,此时 HTTP 可能仍为 200,不能再返回 JSON。网络错误、超时、取消后应丢弃残缺文件;没有长度信息时浏览器也不一定识别所有截断情况,解压失败应提示手动重新下载。不提供断点续传、下载任务或进度查询;没有总长度时不要展示虚构百分比。
|
||||
|
||||
### 4.3 下载错误
|
||||
|
||||
| HTTP / code | 前端处理 |
|
||||
| --- | --- |
|
||||
| 400 `BAD_REQUEST` | 检查 format、完整 SHA;社区删除 commitSha 参数 |
|
||||
| 401 `UNAUTHORIZED` | 工作区引导登录;匿名社区请求移除失效 Token |
|
||||
| 404 `NOT_FOUND` | 项目、提交不存在,或无权限、未发布、已撤回、已删除 |
|
||||
| 409 `CONFLICT` | 工作区项目尚未就绪,刷新项目状态 |
|
||||
| 413 `ARCHIVE_TOO_LARGE` | 告知归档超过服务端上限 |
|
||||
| 429 `ARCHIVE_BUSY` / `RATE_LIMITED` | 参考 Retry-After,允许用户稍后手动重试 |
|
||||
| 502 `GITEA_ERROR` | 上游归档异常,展示 requestId 便于排查 |
|
||||
| 503 `GITEA_NOT_CONFIGURED` | 服务端仓库配置未完成,联系后端 |
|
||||
| 504 `ARCHIVE_TIMEOUT` | 提示下载超时,可手动重新下载 |
|
||||
| 499 `ARCHIVE_CANCELLED` | 发包前取消;浏览器主动取消通常直接抛出 AbortError |
|
||||
|
||||
## 5. Git 连接信息与凭据管理
|
||||
|
||||
以下四个接口全部使用网站 Bearer Token,响应均设置 `Cache-Control: no-store`。
|
||||
|
||||
### 5.1 获取连接信息
|
||||
|
||||
`GET /api/workspace/projects/{projectCode}/git`,无查询参数、无请求体。需要项目 READY。成功 data:
|
||||
|
||||
```json
|
||||
{
|
||||
"cloneUrl": "https://git.example.com/git/projects/7m4k9x2p8q6r.git",
|
||||
"username": "111111111111",
|
||||
"defaultBranch": "main",
|
||||
"headCommitSha": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
|
||||
"publishedCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||||
"writeStatus": "IDLE",
|
||||
"canPush": true
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 类型 | 页面用途 |
|
||||
| --- | --- | --- |
|
||||
| `cloneUrl` | string | 克隆地址、复制命令;原样使用 |
|
||||
| `username` | string | Git Basic 用户名,即当前网站用户 userCode |
|
||||
| `defaultBranch` | string | 当前固定 `main` |
|
||||
| `headCommitSha` | string | 本次读取到的工作区 main 完整 SHA |
|
||||
| `publishedCommitSha` | string 或 null | 当前发布 SHA;未发布时为 null,发布状态仍以项目详情为准 |
|
||||
| `writeStatus` | `IDLE` / `WRITING` / `REVIEW` | 仓库写入状态 |
|
||||
| `canPush` | boolean | 当前写入状态、技术账号及 main 保护核验是否允许推送;实际推送仍会重新校验 |
|
||||
|
||||
`canPush=true` 也需要 READ_WRITE 凭据,不能理解为只读 Token 可以 push。`canPush=false` 时仍可展示克隆信息和凭据管理,不要仅凭它禁止创建首个读写 Token:创建读写 Token 时后端会初始化或核验 main 保护。
|
||||
|
||||
Git 是否可用由部署开关 `GIT_ENABLED` 控制。关闭时本接口及创建凭据返回 503 `GIT_UNAVAILABLE`,凭据列表和撤销仍可使用。当前没有单独的功能开关查询接口,前端按本接口结果展示“本地开发暂未启用”。
|
||||
|
||||
### 5.2 查询凭据列表
|
||||
|
||||
`GET /api/workspace/projects/{projectCode}/git/tokens?page=1&size=20`。
|
||||
|
||||
| 参数 | 默认值 | 范围 |
|
||||
| --- | --- | --- |
|
||||
| `page` | 1 | 1~100000 |
|
||||
| `size` | 20 | 1~100 |
|
||||
|
||||
成功 data:
|
||||
|
||||
```json
|
||||
{
|
||||
"items": [
|
||||
{
|
||||
"tokenCode": "33333333333333333333333333333333",
|
||||
"name": "我的笔记本",
|
||||
"scope": "READ_WRITE",
|
||||
"status": "ACTIVE",
|
||||
"createdAt": "2026-11-03T10:00:00",
|
||||
"expiresAt": "2027-02-01T10:00:00",
|
||||
"revokedAt": null,
|
||||
"lastUsedAt": null
|
||||
}
|
||||
],
|
||||
"page": 1,
|
||||
"size": 20,
|
||||
"total": 1
|
||||
}
|
||||
```
|
||||
|
||||
列表包含有效、过期、已撤销凭据,按创建时间倒序,空列表 `items=[]`。不返回明文、摘要或数据库 ID。
|
||||
|
||||
| 字段 | 类型与含义 |
|
||||
| --- | --- |
|
||||
| `tokenCode` | string,撤销时使用的业务编码 |
|
||||
| `name` | string,凭据名称 |
|
||||
| `scope` | `READ_ONLY`:clone/fetch/pull、LFS 下载;`READ_WRITE`:同时允许 push main 和 LFS 上传 |
|
||||
| `status` | `ACTIVE`:有效;`EXPIRED`:过期;`REVOKED`:已撤销或因账号会话版本变化失效 |
|
||||
| `createdAt` / `expiresAt` | string,创建和到期时间 |
|
||||
| `revokedAt` | string 或 null;会话版本导致失效时 status 可为 REVOKED,但此字段仍为 null |
|
||||
| `lastUsedAt` | string 或 null;最近成功认证时间,最多每 5 分钟写回一次,不能视作实时在线状态 |
|
||||
|
||||
### 5.3 创建凭据
|
||||
|
||||
`POST /api/workspace/projects/{projectCode}/git/tokens`,JSON 请求:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "我的笔记本",
|
||||
"scope": "READ_WRITE",
|
||||
"expiresInDays": 90
|
||||
}
|
||||
```
|
||||
|
||||
| 字段 | 必填 | 约束 |
|
||||
| --- | --- | --- |
|
||||
| `name` | 是 | 非空,最多 64 字符;提交前去掉首尾空格,后端保存时也会去掉 |
|
||||
| `scope` | 是 | 精确使用 `READ_ONLY` 或 `READ_WRITE` |
|
||||
| `expiresInDays` | 否 | 整数 1~365;省略或 null 为 90 天 |
|
||||
|
||||
每项目默认最多 10 个有效凭据,服务端可调低额度;过期、已撤销及会话版本失效的凭据不占有效额度。达到额度返回 409 `CONFLICT`。读写凭据创建时后端会核验或初始化 main 保护;不兼容时拒绝创建,不覆盖已有更严格规则。
|
||||
|
||||
成功 data 为:
|
||||
|
||||
```json
|
||||
{
|
||||
"credential": {
|
||||
"tokenCode": "33333333333333333333333333333333",
|
||||
"name": "我的笔记本",
|
||||
"scope": "READ_WRITE",
|
||||
"status": "ACTIVE",
|
||||
"createdAt": "2026-11-03T10:00:00",
|
||||
"expiresAt": "2027-02-01T10:00:00",
|
||||
"revokedAt": null,
|
||||
"lastUsedAt": null
|
||||
},
|
||||
"token": "vbg_<仅本次响应返回的项目Git凭据明文>"
|
||||
}
|
||||
```
|
||||
|
||||
`credential` 是元数据,`token` 才是 Git 密码。明文仅返回一次,不能再次查询。成功后刷新凭据列表和连接信息,并在独立区域一次性展示明文、提供复制按钮。明文仅保留在当前展示状态,关闭弹窗、切换项目或离开页面时清除;不要写入 localStorage、sessionStorage、URL、埋点或日志,也不要直接记录整个创建响应。
|
||||
|
||||
创建请求不要自动重试。超时、断网或用户取消时可能已经创建成功;先刷新列表核对,无法取得明文的凭据应撤销后重新创建。
|
||||
|
||||
### 5.4 撤销凭据
|
||||
|
||||
`DELETE /api/workspace/projects/{projectCode}/git/tokens/{tokenCode}`,无请求体,成功 `data=null`。重复撤销同一已存在凭据也成功;不存在、属于其他项目或其他用户的凭据返回 404。
|
||||
|
||||
成功后刷新列表。撤销、过期、账号禁用或账号会话版本改变后,新的 Git/LFS 请求会被拒绝;已受理传输不保证立即中止或回滚。普通网站退出登录不撤销项目 Git Token。
|
||||
|
||||
当前没有修改凭据名称、修改权限、续期或重新查询明文的接口;需要调整时撤销并新建。
|
||||
|
||||
### 5.5 浏览器管理接口错误
|
||||
|
||||
| HTTP / code | 前端处理 |
|
||||
| --- | --- |
|
||||
| 400 `BAD_REQUEST` | 检查字段、枚举、名称长度、到期天数和分页参数 |
|
||||
| 401 `UNAUTHORIZED` | 网站登录失效,按现有登录流程处理 |
|
||||
| 404 `NOT_FOUND` | 项目或凭据不存在、已删除或不属于本人 |
|
||||
| 409 `CONFLICT` | 创建凭据时可能为有效额度已满;连接信息或创建凭据时也可能为项目未就绪,展示服务端 message 并刷新核对 |
|
||||
| 409 `PROJECT_BUSY` | 项目正在处理,稍后手动重试 |
|
||||
| 503 `GIT_UNAVAILABLE` | 功能未启用或依赖不可用;已有凭据仍可查询和撤销 |
|
||||
| 503 `GIT_POLICY_UNAVAILABLE` | 技术账号、仓库或 main 保护不兼容,联系后端处理 |
|
||||
| 502 / 503 / 504 其他依赖错误 | 展示 message 和 requestId;创建结果不明时先核对列表,不自动重发 |
|
||||
|
||||
## 6. 页面流程与本地开发指引
|
||||
|
||||
### 6.1 页面入口和状态
|
||||
|
||||
1. 工作区和社区详情提供 ZIP、TAR.GZ 下载;“克隆与本地开发”只在本人工作区提供。社区展示“Fork 到我的工作区”,完成后进入新项目。
|
||||
2. 打开本地开发面板时,可以并行获取连接信息和凭据列表;两者独立处理错误,功能关闭也保留列表、撤销入口。
|
||||
3. 展示 cloneUrl、username、main SHA、发布 SHA、写入状态,以及创建、列表、撤销操作。列表行以 tokenCode 为标识。
|
||||
4. 创建成功展示一次性明文,刷新列表和连接信息;复制命令中不包含任何 Token。
|
||||
5. 提供“刷新工作区”按钮,重新读取当前目录、已打开文件、历史及连接信息;有未保存输入时保留输入并提示版本变化,不静默覆盖。
|
||||
6. push 成功后仍显示“需要手动发布到社区”。刷新版本后让用户确认发布,不能自动调用发布接口。
|
||||
|
||||
| writeStatus | 建议提示与操作 |
|
||||
| --- | --- |
|
||||
| `IDLE` | 当前无写入保护;结合 canPush 展示推送可用性 |
|
||||
| `WRITING` | 正在写入,请稍后刷新;暂缓新的网页保存、上传和发布 |
|
||||
| `REVIEW` | 写入结果核对中;禁用新的仓库写入和发布,保留用户未保存输入,允许刷新核对 |
|
||||
|
||||
canPush=false 且 IDLE 时可提示“当前暂不可推送,请创建读写凭据或联系管理员核对配置”,不能仅凭此布尔值猜测唯一原因。canPush、SHA 和状态都是读取时的快照,不代替后端实时校验。没有面向前端的 push 任务或进度查询接口,不要求接入 Webhook。
|
||||
|
||||
### 6.2 可展示给用户的终端步骤
|
||||
|
||||
克隆前安装 Git 和 git-lfs。使用接口返回的实际 cloneUrl 替换下方占位符:
|
||||
|
||||
```bash
|
||||
git lfs install
|
||||
git -c credential.useHttpPath=true clone --single-branch --branch main <cloneUrl>
|
||||
cd <本地仓库目录>
|
||||
git config credential.useHttpPath true
|
||||
|
||||
git add .
|
||||
git commit -m "更新项目"
|
||||
git push origin main
|
||||
|
||||
# 后续拉取
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
终端询问用户名时填写连接信息中的 `username`,密码填写刚创建的项目 Git Token。操作系统凭据管理器可保存凭据。同一域名的不同项目使用不同 Token,示例中的 `credential.useHttpPath=true` 必须保留。
|
||||
|
||||
仅允许 main 正常快进更新和合并提交,禁止强推、删除 main、推送其他分支或标签、多引用推送、push-options、signed-push 扩展;普通签名提交支持,本地作者、邮箱、时间、签名及 SHA 原样保留。已有其他分支和标签可读取,本期不清理历史数据。
|
||||
|
||||
LFS 支持实体上传、下载和 verify;不支持文件锁,锁创建/删除返回 501,locks/verify 返回空集合。只读 Token 不能 push 或上传 LFS。
|
||||
|
||||
本地版本落后时先 pull、处理冲突再 push,不提示用户强推。push 超时或断开不能直接当作失败,也不要自动重推;先刷新工作区和历史核对。
|
||||
|
||||
### 6.3 与现有网站接口配合
|
||||
|
||||
| 场景 | 已有接口与用法 |
|
||||
| --- | --- |
|
||||
| 社区 Fork | `POST /api/community/projects/{projectCode}/forks`,body 为 `{ "name": "我的副本", "publishedCommitSha": "社区详情的完整发布SHA" }`;成功 data 为新项目,使用其 projectCode 进入工作区 |
|
||||
| 刷新根目录 | `GET /api/workspace/projects/{projectCode}/tree`;读取最新 main 时省略 commitSha;响应 data.commitSha 为本次版本 |
|
||||
| 刷新文件 | `GET /api/workspace/projects/{projectCode}/files?path=...`;查询值用 URLSearchParams 编码,可传相同 commitSha 保持目录和文件版本一致 |
|
||||
| 刷新历史 | `GET /api/workspace/projects/{projectCode}/commits?page=1&size=20` |
|
||||
| 手动发布 | `PUT /api/workspace/projects/{projectCode}/publication`,body 为 `{ "commitSha": "用户确认发布的最新main完整SHA" }`;成功 data 为更新后的项目 |
|
||||
| 刷新社区 | `GET /api/community/projects/{projectCode}`;社区目录和文件禁止传 commitSha |
|
||||
|
||||
上述工作区、Fork、发布接口使用网站 Bearer Token。发布版本已变化导致 409 时,刷新版本并让用户重新确认,不自动换 SHA 再发布。网页保存同样使用原编辑基准 SHA;409 时保留输入,处理差异后再提交。`updatedAt` 不代表仓库最新提交时间,版本比较使用 SHA;是否当前已发布使用项目详情的 `publishStatus`。
|
||||
|
||||
Fork 也是写操作,不自动重试;失败或超时先核对工作区列表。完整项目、目录、文件和 Fork 的类型及约束见 [用户端完整接口文档](vibemake-api.md)。
|
||||
|
||||
## 7. 可复用 TypeScript 示例
|
||||
|
||||
以下两个代码块可放入同一个前端模块。示例无需依赖完整接口文档中的 request 方法;`platformToken` 始终指网站登录 Token。
|
||||
|
||||
### 7.1 类型、JSON 请求和凭据管理
|
||||
|
||||
```typescript
|
||||
const API_BASE = '/api'; // 同源代理;也可替换为部署提供的完整 API 基础地址,无末尾斜杠。
|
||||
|
||||
export interface ApiResponse<T> {
|
||||
code: string;
|
||||
message: string;
|
||||
data: T;
|
||||
requestId: string;
|
||||
}
|
||||
|
||||
export interface PageResult<T> {
|
||||
items: T[];
|
||||
page: number;
|
||||
size: number;
|
||||
total: number;
|
||||
}
|
||||
|
||||
export interface GitConnection {
|
||||
cloneUrl: string;
|
||||
username: string;
|
||||
defaultBranch: string;
|
||||
headCommitSha: string;
|
||||
publishedCommitSha: string | null;
|
||||
writeStatus: 'IDLE' | 'WRITING' | 'REVIEW';
|
||||
canPush: boolean;
|
||||
}
|
||||
|
||||
export type GitScope = 'READ_ONLY' | 'READ_WRITE';
|
||||
|
||||
export interface GitTokenView {
|
||||
tokenCode: string;
|
||||
name: string;
|
||||
scope: GitScope;
|
||||
status: 'ACTIVE' | 'EXPIRED' | 'REVOKED';
|
||||
createdAt: string;
|
||||
expiresAt: string;
|
||||
revokedAt: string | null;
|
||||
lastUsedAt: string | null;
|
||||
}
|
||||
|
||||
export interface CreateGitTokenInput {
|
||||
name: string;
|
||||
scope: GitScope;
|
||||
expiresInDays?: number | null;
|
||||
}
|
||||
|
||||
export interface IssuedGitToken {
|
||||
credential: GitTokenView;
|
||||
token: string; // 仅本次展示,不持久化、不记录整个响应。
|
||||
}
|
||||
|
||||
export class ApiError extends Error {
|
||||
constructor(
|
||||
public readonly status: number,
|
||||
public readonly code: string,
|
||||
message: string,
|
||||
public readonly requestId: string | null,
|
||||
public readonly retryAfter: string | null = null,
|
||||
) {
|
||||
super(message);
|
||||
this.name = 'ApiError';
|
||||
}
|
||||
}
|
||||
|
||||
async function readEnvelope<T>(response: Response): Promise<ApiResponse<T>> {
|
||||
let body: ApiResponse<T>;
|
||||
try {
|
||||
body = await response.json();
|
||||
} catch {
|
||||
throw new ApiError(response.status, 'BAD_RESPONSE', '接口响应异常,请稍后重试',
|
||||
response.headers.get('X-Request-Id'), response.headers.get('Retry-After'));
|
||||
}
|
||||
if (!body || typeof body.code !== 'string' || typeof body.message !== 'string') {
|
||||
throw new ApiError(response.status, 'BAD_RESPONSE', '接口响应格式异常',
|
||||
response.headers.get('X-Request-Id'));
|
||||
}
|
||||
return body;
|
||||
}
|
||||
|
||||
function responseError(response: Response, body: ApiResponse<unknown>): ApiError {
|
||||
return new ApiError(response.status, body.code, body.message,
|
||||
body.requestId ?? response.headers.get('X-Request-Id'),
|
||||
response.headers.get('Retry-After'));
|
||||
}
|
||||
|
||||
async function apiRequest<T>(
|
||||
path: string,
|
||||
platformToken: string,
|
||||
options: { method?: 'GET' | 'POST' | 'DELETE'; body?: unknown; signal?: AbortSignal } = {},
|
||||
): Promise<T> {
|
||||
const headers: Record<string, string> = { Authorization: `Bearer ${platformToken}` };
|
||||
if (options.body !== undefined) headers['Content-Type'] = 'application/json';
|
||||
const response = await fetch(`${API_BASE}${path}`, {
|
||||
method: options.method ?? 'GET',
|
||||
headers,
|
||||
credentials: 'omit',
|
||||
cache: 'no-store',
|
||||
body: options.body === undefined ? undefined : JSON.stringify(options.body),
|
||||
signal: options.signal,
|
||||
});
|
||||
const body = await readEnvelope<T>(response);
|
||||
if (!response.ok || body.code !== 'OK') throw responseError(response, body);
|
||||
return body.data;
|
||||
}
|
||||
|
||||
function gitPath(projectCode: string): string {
|
||||
return `/workspace/projects/${encodeURIComponent(projectCode)}/git`;
|
||||
}
|
||||
|
||||
export function getGitConnection(projectCode: string, platformToken: string, signal?: AbortSignal) {
|
||||
return apiRequest<GitConnection>(gitPath(projectCode), platformToken, { signal });
|
||||
}
|
||||
|
||||
export function listGitTokens(
|
||||
projectCode: string, platformToken: string, page = 1, size = 20, signal?: AbortSignal,
|
||||
) {
|
||||
const query = new URLSearchParams({ page: String(page), size: String(size) });
|
||||
return apiRequest<PageResult<GitTokenView>>(
|
||||
`${gitPath(projectCode)}/tokens?${query}`, platformToken, { signal });
|
||||
}
|
||||
|
||||
export function createGitToken(
|
||||
projectCode: string, platformToken: string, input: CreateGitTokenInput, signal?: AbortSignal,
|
||||
) {
|
||||
return apiRequest<IssuedGitToken>(`${gitPath(projectCode)}/tokens`, platformToken, {
|
||||
method: 'POST', body: { ...input, name: input.name.trim() }, signal,
|
||||
}); // 不添加自动重试。
|
||||
}
|
||||
|
||||
export function revokeGitToken(projectCode: string, tokenCode: string, platformToken: string) {
|
||||
return apiRequest<null>(
|
||||
`${gitPath(projectCode)}/tokens/${encodeURIComponent(tokenCode)}`,
|
||||
platformToken, { method: 'DELETE' });
|
||||
}
|
||||
|
||||
export function parseShanghaiTime(value: string): Date {
|
||||
return new Date(`${value}+08:00`); // 仅用于本文无时区后缀的时间字段。
|
||||
}
|
||||
```
|
||||
|
||||
### 7.2 归档下载、文件保存与主动取消
|
||||
|
||||
```typescript
|
||||
export async function downloadRepositoryArchive(
|
||||
scope: 'workspace' | 'community',
|
||||
projectCode: string,
|
||||
format: 'zip' | 'tar.gz' = 'zip',
|
||||
options: { platformToken?: string; commitSha?: string; signal?: AbortSignal } = {},
|
||||
): Promise<void> {
|
||||
if (scope === 'workspace' && !options.platformToken) throw new Error('请先登录');
|
||||
if (scope === 'community' && options.commitSha !== undefined) {
|
||||
throw new Error('社区归档仅支持当前已发布版本,请移除 commitSha');
|
||||
}
|
||||
const query = new URLSearchParams({ format });
|
||||
if (options.commitSha !== undefined) query.set('commitSha', options.commitSha);
|
||||
const response = await fetch(
|
||||
`${API_BASE}/${scope}/projects/${encodeURIComponent(projectCode)}/archive?${query}`,
|
||||
{
|
||||
headers: options.platformToken
|
||||
? { Authorization: `Bearer ${options.platformToken}` } : {},
|
||||
credentials: 'omit',
|
||||
cache: 'no-store',
|
||||
signal: options.signal,
|
||||
},
|
||||
);
|
||||
if (!response.ok) {
|
||||
const failure = await readEnvelope<unknown>(response);
|
||||
throw responseError(response, failure);
|
||||
}
|
||||
|
||||
const expectedType = format === 'zip' ? 'application/zip' : 'application/gzip';
|
||||
const actualType = response.headers.get('Content-Type')?.split(';')[0].trim().toLowerCase();
|
||||
if (actualType !== expectedType) {
|
||||
await response.body?.cancel();
|
||||
throw new ApiError(response.status, 'BAD_RESPONSE', '接口未返回预期的压缩包',
|
||||
response.headers.get('X-Request-Id'));
|
||||
}
|
||||
const blob = await response.blob(); // 收到响应头后,取消仍可中止响应体读取。
|
||||
const requestId = response.headers.get('X-Request-Id');
|
||||
const contentLength = response.headers.get('Content-Length');
|
||||
if (contentLength !== null && blob.size !== Number(contentLength)) {
|
||||
throw new ApiError(response.status, 'ARCHIVE_INCOMPLETE', '压缩包接收不完整,请重新下载', requestId);
|
||||
}
|
||||
if (options.signal?.aborted) throw new DOMException('下载已取消', 'AbortError');
|
||||
|
||||
const disposition = response.headers.get('Content-Disposition') ?? '';
|
||||
const encodedName = disposition.match(/filename\*=UTF-8''([^;]+)/i)?.[1];
|
||||
const plainName = disposition.match(/filename="([^"]+)"/i)?.[1];
|
||||
let filename = plainName ?? `${projectCode}.${format}`;
|
||||
if (encodedName) {
|
||||
try { filename = decodeURIComponent(encodedName); } catch { /* 使用后备文件名。 */ }
|
||||
}
|
||||
filename = filename.replace(/[\\/\u0000-\u001f\u007f]/g, '_');
|
||||
const objectUrl = URL.createObjectURL(blob);
|
||||
try {
|
||||
const link = document.createElement('a');
|
||||
link.href = objectUrl;
|
||||
link.download = filename;
|
||||
document.body.appendChild(link);
|
||||
link.click();
|
||||
link.remove();
|
||||
} finally {
|
||||
setTimeout(() => URL.revokeObjectURL(objectUrl), 1000);
|
||||
}
|
||||
}
|
||||
|
||||
// 示例:在点击事件中传入实际项目编码和网站登录 Token。
|
||||
export async function handleWorkspaceDownload(
|
||||
projectCode: string, platformToken: string, controller: AbortController,
|
||||
) {
|
||||
try {
|
||||
await downloadRepositoryArchive('workspace', projectCode, 'zip', {
|
||||
platformToken, signal: controller.signal,
|
||||
});
|
||||
} catch (error) {
|
||||
if (controller.signal.aborted) return; // 用户主动停止,不提示“服务器错误”。
|
||||
throw error; // 页面统一提示 ApiError.message 或网络异常,不记录 Token。
|
||||
}
|
||||
}
|
||||
|
||||
// 点击下载:创建并保留 const controller = new AbortController(),传给上面的函数。
|
||||
// 点击停止或离开页面:controller.abort()。下一次下载必须创建新的 controller。
|
||||
// 社区匿名下载:downloadRepositoryArchive('community', projectCode, 'tar.gz')。
|
||||
```
|
||||
|
||||
`BAD_RESPONSE`、`ARCHIVE_INCOMPLETE` 是示例前端封装错误码,不是后端业务码。网络错误、用户取消及接收二进制时的异常未必有 JSON 或 requestId。Blob 会占用浏览器内存或存储,页面应限制重复下载;HTTP 200、Blob 保存成功均不能替代压缩包完整性校验。
|
||||
|
||||
## 8. Git 协议说明与用户故障提示
|
||||
|
||||
本节用于编写终端指引和排查,不要求前端实现 Git/LFS 协议。Git 客户端自动访问这些路径:
|
||||
|
||||
| 方法 | 路径 |
|
||||
| --- | --- |
|
||||
| GET | `/git/projects/{projectCode}.git/info/refs?service=git-upload-pack` |
|
||||
| GET | `/git/projects/{projectCode}.git/info/refs?service=git-receive-pack` |
|
||||
| POST | `/git/projects/{projectCode}.git/git-upload-pack` |
|
||||
| POST | `/git/projects/{projectCode}.git/git-receive-pack` |
|
||||
| Git LFS 客户端自动调用 | `/git/projects/{projectCode}.git/info/lfs/**` |
|
||||
|
||||
协议响应为 Git pkt-line/pack 或 LFS 标准结构,不是网站 ApiResponse。401 带 Basic challenge,429 带 Retry-After;LFS action 使用服务端签发的短期凭据,由 git-lfs 自动处理。不要用浏览器的 apiRequest 包装去请求上述路径,也不要将它们作为普通网页打开方式。
|
||||
|
||||
| 协议错误码/状态 | 给用户的处理指引 |
|
||||
| --- | --- |
|
||||
| 401 `GIT_UNAUTHORIZED` | 检查网站 userCode、项目 Git Token、是否过期或撤销;不要使用网站登录 Token |
|
||||
| 403 `GIT_READ_ONLY` | 使用 READ_WRITE 凭据后再 push 或上传 LFS |
|
||||
| 400 `GIT_COMMAND_REJECTED` | 仅推送 main,去掉其他引用及不支持的推送扩展 |
|
||||
| 409 `GIT_STALE_MAIN` | 先拉取并处理冲突,再推送 |
|
||||
| 409 `CONFLICT` / `PROJECT_BUSY` | 项目未就绪或正在处理,刷新核对 |
|
||||
| 409 或 503 `REMOTE_RESULT_UNKNOWN` | 结果核对中,暂缓写入和发布,先刷新工作区及历史 |
|
||||
| 429 `GIT_BUSY` | 请求频率或并发超限,稍后手动重试 |
|
||||
| 413 `GIT_TRANSFER_TOO_LARGE` / `GIT_METADATA_TOO_LARGE` / `LFS_TOO_LARGE` | 请求超过服务端限制,缩小请求或联系管理员 |
|
||||
| 503 `GIT_UNAVAILABLE` / `GIT_POLICY_UNAVAILABLE` | 功能或依赖暂不可用,联系管理员 |
|
||||
| 504 `GIT_TIMEOUT` / 502 `GIT_UPSTREAM_ERROR` | 涉及 push 时先核对工作区,不能仅凭断网或超时判定未写入 |
|
||||
| 501 `LFS_LOCKS_UNSUPPORTED` | 当前不支持 LFS 文件锁 |
|
||||
|
||||
原生 Git 也可能输出标准引用拒绝信息;不能仅凭 HTTP 200 判断 push 成功,应以 Git 客户端最终结果和刷新后的工作区 SHA 为准。
|
||||
|
||||
默认 Git pack 单次上限 5 GiB、LFS 单对象 1 GiB、元数据 8 MiB、LFS batch 最多 500 对象;单次 Git/LFS 请求预算 10 分钟。每实例读取/push/LFS 并发为 4/2/8;每用户每分钟 Git 120 次、LFS 600 次,每 IP 每分钟认证失败最多 20 次。均可由部署调整,与归档、JSON、multipart 和在线文件读取限制独立。
|
||||
|
||||
## 9. 前端联调验收
|
||||
|
||||
- [ ] 本人工作区和匿名社区均可下载 ZIP、TAR.GZ,文件名及解压后的中文路径、子目录、二进制正确。
|
||||
- [ ] 发布 A 后提交 B:社区归档仍为 A,工作区默认 B,指定历史 SHA 可下载 A;社区请求不携带 commitSha。
|
||||
- [ ] 下载处理 401、404、413、429、非 JSON 代理错误、取消、网络中断;限制重复点击并释放 Blob URL。
|
||||
- [ ] 只有本人工作区提供本地开发入口;社区先 Fork,再使用新项目编码;非本人项目、已删除项目的管理请求被拒绝。
|
||||
- [ ] 正确区分网站登录 Token、项目 Git Token、tokenCode;cloneUrl 原样使用,明文不进入缓存、URL、日志或埋点。
|
||||
- [ ] 凭据列表支持分页、有效/过期/撤销状态和空时间;创建校验名称、权限、到期天数及额度,创建结果未知不自动重试。
|
||||
- [ ] 一次性明文正确展示和复制,关闭展示后清除;列表无法重新获取明文;撤销后刷新列表。
|
||||
- [ ] 功能关闭时展示不可用提示,仍可查询、撤销已有凭据;canPush=false 不直接阻止创建首个读写凭据。
|
||||
- [ ] 按网站展示的地址、用户名和凭据完成 clone、commit、push、pull;同域名两个项目可使用不同凭据,LFS 正常上传下载。
|
||||
- [ ] push 后刷新工作区显示最新目录、文件和历史,保留未保存输入;社区保持原版本,确认手动发布后才更新。
|
||||
- [ ] 正确展示 WRITING、REVIEW;结果未知时不重复写入、不自动发布;只读、强推、其他引用等拒绝场景有明确指引。
|
||||
|
||||
部署联调前由后端确认 Git 功能已开启、数据库扩展已执行、返回的 cloneUrl 可达,公网 `/git/**` 保留路径转发至社区 API。归档代理读取超时默认至少 400 秒,Git/LFS 至少 660 秒并关闭请求、响应缓冲及缓存。前端不负责保存上游凭据或配置 Gitea。
|
||||
|
||||
完整业务接口见 [用户端接口文档](vibemake-api.md),部署细节见 [README](../README.md#https-git-网关)。
|
||||
@@ -6,6 +6,8 @@
|
||||
|
||||
当前支持项目、文件、目录、提交、手动发布、快照 Fork、评论和点赞,以及可配置开启的 Maker AI(聊天问答、查找、创建空项目、Fork)。项目发布后,后续提交只更新工作区,需要再次调用发布接口才更新社区代码。没有服务端草稿保存、独立工作区实体或项目类型表。
|
||||
|
||||
ZIP、TAR.GZ 下载和 HTTPS Git 本地开发的独立前端交付文档见 [仓库下载与 Git 接入](frontend-repository-download-git.md),包含六个浏览器接口、页面流程、TypeScript 示例及联调清单。
|
||||
|
||||
## 阅读导航
|
||||
|
||||
- [接入约定](#接入约定)
|
||||
@@ -1633,7 +1635,7 @@ Fork 每用户每分钟 10 次、URDF 批次签名 20 次、封面签名 30 次
|
||||
|
||||
## HTTPS Git 与本地开发
|
||||
|
||||
Git 网关默认关闭,开启后仅本人工作区可 clone/fetch/pull/push;社区项目先 Fork。网站身份沿用邮箱加图片验证码,当前不验证邮箱归属,Git Token 继承此身份校验边界。普通用户不需要 Gitea 账号。
|
||||
Git 网关由部署开关 `GIT_ENABLED` 控制,开启后仅本人工作区可 clone/fetch/pull/push;社区项目先 Fork。网站身份沿用邮箱加图片验证码,当前不验证邮箱归属,Git Token 继承此身份校验边界。普通用户不需要 Gitea 账号。
|
||||
|
||||
### 接口清单与数据
|
||||
|
||||
|
||||
Reference in New Issue
Block a user