32 KiB
仓库 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 页面入口和状态
- 工作区和社区详情提供 ZIP、TAR.GZ 下载;“克隆与本地开发”只在本人工作区提供。社区展示“Fork 到我的工作区”,完成后进入新项目。
- 打开本地开发面板时,可以并行获取连接信息和凭据列表;两者独立处理错误,功能关闭也保留列表、撤销入口。
- 展示 cloneUrl、username、main SHA、发布 SHA、写入状态,以及创建、列表、撤销操作。列表行以 tokenCode 为标识。
- 创建成功展示一次性明文,刷新列表和连接信息;复制命令中不包含任何 Token。
- 提供“刷新工作区”按钮,重新读取当前目录、已打开文件、历史及连接信息;有未保存输入时保留输入并提示版本变化,不静默覆盖。
- 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。