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

32 KiB
Raw Blame History

仓库 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/**。

浏览器: /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。

{
  "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=
GET /api/workspace/projects/7m4k9x2p8q6r/archive?format=zip
Authorization: Bearer <网站登录 Token>
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:

{
  "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:

{
  "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 请求:

{
  "name": "我的笔记本",
  "scope": "READ_WRITE",
  "expiresInDays": 90
}
字段 必填 约束
name 是 非空,最多 64 字符;提交前去掉首尾空格,后端保存时也会去掉
scope 是 精确使用 READ_ONLY 或 READ_WRITE
expiresInDays 否 整数 1~365;省略或 null 为 90 天

每项目默认最多 10 个有效凭据,服务端可调低额度;过期、已撤销及会话版本失效的凭据不占有效额度。达到额度返回 409 CONFLICT。读写凭据创建时后端会核验或初始化 main 保护;不兼容时拒绝创建,不覆盖已有更严格规则。

成功 data 为:

{
  "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 替换下方占位符:

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 的类型及约束见 用户端完整接口文档。

7. 可复用 TypeScript 示例

以下两个代码块可放入同一个前端模块。示例无需依赖完整接口文档中的 request 方法;platformToken 始终指网站登录 Token。

7.1 类型、JSON 请求和凭据管理

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 归档下载、文件保存与主动取消

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。

完整业务接口见 用户端接口文档,部署细节见 README。