Files
community/docs/frontend-repository-download-git.md

618 lines
32 KiB
Markdown
Raw Permalink 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.
# 仓库 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 次,部署可调整。此限制独立于 JSON 文件预览的 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-网关)。