项目下载ZIP、TAR.GZ

This commit is contained in:
lxp
2026-11-02 16:53:17 +08:00
parent 556dab4377
commit 674f0400db
13 changed files with 923 additions and 3 deletions
+96 -1
View File
@@ -55,7 +55,7 @@
### 统一响应
除成功的文件下载和 AI 对话 SSE 外,响应为以下 JSON 结构;SSE 每个事件的 data 也使用此包装。所有成功接口使用 HTTP 200,创建、删除、退出登录也不返回 201 或 204。
除成功的文件或仓库归档下载和 AI 对话 SSE 外,响应为以下 JSON 结构;SSE 每个事件的 data 也使用此包装。所有成功接口使用 HTTP 200,创建、删除、退出登录也不返回 201 或 204。
```json
{
@@ -127,6 +127,7 @@ Git SHA 使用完整的 40 或 64 位十六进制字符串,不使用缩写。
| DELETE | `/api/workspace/projects/{projectCode}/urdf` | 是 | null |
| GET | `/api/workspace/projects/{projectCode}/tree` | 是 | Tree |
| GET | `/api/workspace/projects/{projectCode}/files` | 是 | ProjectFile 或下载二进制 |
| GET | `/api/workspace/projects/{projectCode}/archive` | 是 | 当前或指定版本的 ZIP、TAR.GZ 仓库归档 |
| POST | `/api/workspace/projects/{projectCode}/commits` | 是 | Commit |
| GET | `/api/workspace/projects/{projectCode}/commits` | 是 | PageResult<HistoryEntry> |
| POST | `/api/workspace/projects/{projectCode}/uploads/commit` | 是 | Commit |
@@ -136,6 +137,7 @@ Git SHA 使用完整的 40 或 64 位十六进制字符串,不使用缩写。
| GET | `/api/community/projects/{projectCode}` | 可选 | Project |
| GET | `/api/community/projects/{projectCode}/tree` | 可选 | Tree |
| GET | `/api/community/projects/{projectCode}/files` | 可选 | ProjectFile 或下载二进制 |
| GET | `/api/community/projects/{projectCode}/archive` | 可选 | 当前已发布版本的 ZIP、TAR.GZ 仓库归档 |
| POST | `/api/community/projects/{projectCode}/forks` | 是 | Project |
| GET | `/api/community/projects/{projectCode}/comments` | 可选 | PageResult<Comment> |
| POST | `/api/community/projects/{projectCode}/comments` | 是 | Comment |
@@ -826,6 +828,99 @@ entries 仅包含当前目录的直接子项,目录在前,名称升序。展
禁止绝对路径、反斜杠、空路径段、`.`、`..`、`.git` 路径段、冒号及控制字符。读取普通文件接口不支持符号链接或 Git 子模块。使用 URLSearchParams 处理查询编码,不自行拼接未编码的 path。
## 仓库 ZIP、TAR.GZ 下载
- `GET /api/workspace/projects/{projectCode}/archive`:需要登录,只允许下载本人的未删除项目,仓库必须 READY。
- `GET /api/community/projects/{projectCode}/archive`:可匿名访问,只允许下载 READY、已发布且未删除项目的当前发布版本。
| 参数 | 工作区 | 社区 | 说明 |
| --- | --- | --- | --- |
| format | 可选 | 可选 | 省略为 `zip`;仅接受 `zip`、`tar.gz`,区分大小写,空字符串或其他值返回 400 |
| commitSha | 可选 | 禁止 | 工作区省略时下载当前 main,也可传入本项目的完整历史 SHA;社区传入该参数即返回 400,包括空字符串 |
示例:`GET /api/community/projects/{projectCode}/archive?format=tar.gz`。
服务端在请求受理时冻结完整 SHA,再向 Gitea 获取归档。发布 A 后工作区提交 B,社区仍下载 A;工作区默认下载 B,指定 A 的 SHA 可下载 A。下载过程中 main 或发布版本变化不会切换本次版本;撤回或删除后,新发起的社区下载返回 404。
成功返回 HTTP 200 二进制附件,不使用 ApiResponse 包装。ZIP 为 `application/zip`,TAR.GZ 为 `application/gzip`,文件名为 `{projectCode}-{SHA前12位}.{format}`;带 `Content-Disposition: attachment`、`Cache-Control: no-store` 和 `X-Request-Id`。归档内的根目录、文件层级、符号链接和 `.gitattributes` 导出规则沿用 Gitea 原生行为,不包含 Git 提交历史。
**这是 Git 仓库归档,不是项目全部资源打包。** LFS 文件保留指针,不替换为真实大文件;子模块依赖不递归下载。单独绑定于 OSS 的封面、URDF、STEP、GLB、零件、拼装及行走资源不会加入归档;如果仓库本身包含同类文件,则按仓库内容正常导出。
归档使用独立配置,不受普通单文件读取 50 MiB、仓库上传 200 MiB 限制影响:
| 配置 | 默认值 | 含义 |
| --- | --- | --- |
| ARCHIVE_MAX_BYTES | 1073741824(1 GiB) | 本次下载的压缩包字节数上限 |
| ARCHIVE_TIMEOUT | 5m | 获取当前版本、等待归档及读取上游响应体的预算 |
| ARCHIVE_MAX_CONCURRENT | 2 | 单实例同时处理的归档下载数,独立于普通文件并发,超限不排队 |
| RATE_ARCHIVE_READ_PER_MINUTE | 10 | 每 IP 每分钟下载请求数,工作区和社区共用额度 |
| HTTP / code | 处理 |
| --- | --- |
| 400 BAD_REQUEST | 检查格式和 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 |
错误发生在发送附件之前时返回上述 JSON 错误;开始传输后无法改写 HTTP 状态,服务端会停止传输,不向压缩包尾部追加 JSON。此时可能表现为网络中断或下载到不完整的压缩包,应丢弃残缺文件并手动重新下载。本期不提供断点续传、下载任务或进度查询。
工作区必须使用带 Bearer Token 的 fetch;不要将 Token 拼入 URL,也不要使用无法附加请求头的直接链接。成功后读取 Blob,失败先解析 JSON。以下示例支持两种入口和 AbortController,复用本文的 API_BASE、ApiError:
```typescript
async function downloadRepositoryArchive(
scope: 'workspace' | 'community',
projectCode: string,
format: 'zip' | 'tar.gz' = 'zip',
options: { token?: string; commitSha?: string; signal?: AbortSignal } = {},
) {
if (scope === 'workspace' && !options.token) throw new Error('请先登录');
if (scope === 'community' && options.commitSha !== undefined) {
throw new Error('社区归档仅支持当前已发布版本');
}
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.token ? { Authorization: `Bearer ${options.token}` } : {},
signal: options.signal,
},
);
if (!response.ok) {
const failure = await response.json();
throw new ApiError(response.status, failure.code, failure.message,
failure.requestId ?? response.headers.get('X-Request-Id'), failure.data);
}
const disposition = response.headers.get('Content-Disposition') ?? '';
const encodedName = disposition.match(/filename\*=UTF-8''([^;]+)/i)?.[1];
const filename = encodedName ? decodeURIComponent(encodedName) : `${projectCode}.${format}`;
const blob = await response.blob(); // 完整接收后再触发保存。
const objectUrl = URL.createObjectURL(blob);
const link = document.createElement('a');
link.href = objectUrl;
link.download = filename;
document.body.appendChild(link);
link.click();
link.remove();
setTimeout(() => URL.revokeObjectURL(objectUrl), 0);
}
const downloadController = new AbortController();
// 社区可省略 token;工作区传入平台 token。
await downloadRepositoryArchive('workspace', projectCode, 'zip', {
token, signal: downloadController.signal,
});
// 用户点击停止或离开页面时调用 downloadController.abort()。
```
Blob 下载会占用浏览器存储或内存,不代表服务端将整个归档缓存在内存中;前端应限制重复点击,捕获 AbortError 和网络错误。
## 文件编辑与上传提交
### 多文件提交