git clone功能
网站登录 → 创建项目 Git Token → clone → 本地修改、commit → push main → 网站工作区刷新后显示最新内容 → 网站手动发布到社区
This commit is contained in:
@@ -163,6 +163,10 @@ ALTER TABLE project_import_task
|
||||
```sql
|
||||
CREATE TABLE repository_write_operation (
|
||||
operation_code CHAR(32) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL COMMENT '写入操作业务编码,同时作为幂等键',
|
||||
operation_kind VARCHAR(16) NOT NULL DEFAULT 'WEB_COMMIT' COMMENT '操作类型 WEB_COMMIT网页提交 GIT_PUSH本地推送',
|
||||
target_commit_sha VARCHAR(64) NULL COMMENT 'Git推送请求的目标提交SHA,网页提交可为空',
|
||||
actor_user_code VARCHAR(32) NULL COMMENT '实际发起推送的网站用户业务编码',
|
||||
git_token_code CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NULL COMMENT '本次推送使用的Git凭据业务编码,不保存明文',
|
||||
project_code CHAR(32) NOT NULL COMMENT '项目业务编码',
|
||||
repository_id BIGINT NOT NULL COMMENT '操作发起时Gitea仓库内部标识,仅核验使用',
|
||||
repository_owner VARCHAR(255) NOT NULL COMMENT '操作发起时仓库所属账号',
|
||||
@@ -260,3 +264,16 @@ ALTER TABLE repository_write_operation
|
||||
```
|
||||
|
||||
旧导入状态首次由新版读取时,将未声明时区的 `reservedAt` 从 UTC 转为上海时间,原子保存并标记 `timeZone=Asia/Shanghai`,后续不会再次转换。应在业务库完成转换后再续跑;未迁移的数据库时间与清单不一致时,现有归属校验会阻止接管项目。回滚应用前需要同时恢复数据库和导入状态备份,并恢复前端的旧时间解析约定。
|
||||
|
||||
|
||||
## HTTPS Git 写入记录扩展
|
||||
|
||||
已有 `repository_write_operation` 表手工执行下列 SQL;新库使用上方完整建表语句,不重复执行 ALTER。先升级社区端和管理端兼容代码,再开启 Git 网关。既有记录默认归类为 WEB_COMMIT;Git 推送不使用网页提交尾注核对。
|
||||
|
||||
```sql
|
||||
ALTER TABLE repository_write_operation
|
||||
ADD COLUMN operation_kind VARCHAR(16) NOT NULL DEFAULT 'WEB_COMMIT' COMMENT '操作类型 WEB_COMMIT网页提交 GIT_PUSH本地推送',
|
||||
ADD COLUMN target_commit_sha VARCHAR(64) NULL COMMENT 'Git推送请求的目标提交SHA,网页提交可为空',
|
||||
ADD COLUMN actor_user_code VARCHAR(32) NULL COMMENT '实际发起推送的网站用户业务编码',
|
||||
ADD COLUMN git_token_code CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NULL COMMENT '本次推送使用的Git凭据业务编码,不保存明文';
|
||||
```
|
||||
|
||||
@@ -203,3 +203,23 @@ Gitea 原始文件有界读取,contents JSON 上限按单文件 Base64 膨胀
|
||||
项目 SQL 从 122 降到 8,评论列表从 23 降到 4,20 用户后台列表从 22 降到 3。MySQL 四并发 P95 从 2414.935ms 降到 221.998ms,约降低 91%。本地微基准受运行波动影响,不能将 SQL 数变化等同于所有环境的固定延迟收益。堆池峰值是各 heap memory pool 的峰值之和,并非进程 RSS;普通小请求的内存收益不稳定,本期内存保护主要针对超大正文、无界上游响应和大文件并发。
|
||||
|
||||
复测:`AI_ENABLED=false OSS_ENABLED=false mvn -pl vibemake-api -am -Dtest=QueryEfficiencyTest -Dsurefire.failIfNoSpecifiedTests=false '-DargLine=-Xms128m -Xmx512m' test`。默认使用 H2;显式设置 BENCHMARK_MYSQL_URL、BENCHMARK_MYSQL_USERNAME、BENCHMARK_MYSQL_PASSWORD 时,自动创建并最终删除 vibemake_benchmark_* 随机临时库,执行 DDL 前验证连接 catalog 必须等于本次随机库。账号需要创建和删除临时库权限,禁止将基准改为直接重置业务库。该小样本不代表正式环境容量,部署仍需结合真实项目体量验证。
|
||||
|
||||
## HTTPS Git 网关运维
|
||||
|
||||
仅社区 API 暴露 `/git/**`;管理端继续使用后台认证。按 [README 配置](../README.md#https-git-网关) 部署独立 Git 技术账号、HTTPS 地址与无缓冲代理。功能默认关闭;先人工执行 [Git Token 表](database.md#项目-git-凭据) 与 [operation_kind 等字段扩展](admin-database.md#https-git-写入记录扩展),再排空旧进程并升级两个 API,最后对测试项目验证后开放。不能让旧版后台核对器消费 GIT_PUSH 操作。
|
||||
|
||||
Git 技术账号须非 site admin、非组织所有者、非仓库管理员,PAT 只给 read:user、write:repository。首次 Token 签发会按项目给技术账号授予 write,不提升其已有 admin/owner 权限;权限不兼容必须先人工处理。已有 main 保护不覆盖,通配/多规则配置会保守拒绝开通;每次 push 复核。运维直接修改仓库引用或 main 保护前应停写,不能绕过网关并发控制。LFS action 以短期 Redis 状态承接,上游地址与认证头只保留服务端。Redis 丢失 action 后需重新请求 batch;原 Git 凭据存 MySQL,可撤销。
|
||||
|
||||
网页与本地写入使用同一 ProjectLocks 和 repo_write_status,跨进程由 MySQL 命名锁串行。操作记录必须在转发 receive-pack 前提交,operation_kind=GIT_PUSH 记录 base_commit_sha、target_commit_sha、actor_user_code、git_token_code,摘要不含 pack。HTTP200 不是成功证明;仅接受完整 report-status,成功后再次核对 main,并原子保存终态与 IDLE。推送作者来自本地提交,审计 actor_user_code 是网站发起者,两者可能不同。
|
||||
|
||||
后台核对按类型区分:WEB_COMMIT 继续查找原有尾注;GIT_PUSH 先校验项目/远端仓库身份、私有属性及 main,再仅在 main 精确等于 target_commit_sha 时确认成功。main 仍等于 base_commit_sha、为其他SHA、上游不可用或读取失败均保持 REVIEW,不能自动判失败。10分钟后状态为 NEEDS_REVIEW,每分钟继续只读核对,不重发 push。
|
||||
|
||||
人工恢复顺序:
|
||||
|
||||
1. 关闭 Git 入口、停止并排空社区/后台仓库写入和发布,暂停核对 worker,保留数据库和日志备份。
|
||||
2. 根据 requestId、projectCode、operationCode、actor_user_code、git_token_code、旧新 SHA 关联网关与 Gitea 接收日志。先确认对应 receive-pack/钩子任务已经结束;单次旧 SHA 查询不能作为结束证明。
|
||||
3. 核对仓库ID、owner/name、私有、非镜像、main 及对象可达性。精确目标SHA且验证完成可确认 SUCCEEDED;确认任务停止且 main 仍为旧 SHA、未发生引用变更时才可人工标记 FAILED。main 为其他 SHA 或身份变化继续待核对,不改历史、不重推。
|
||||
4. 在维护事务中同步更新操作 status/result_commit_sha/last_error_code/updated_at 和项目 repo_write_status=IDLE;必须校验项目只有这一条待核对操作,不能解除其他操作的保护。留存审批/排查依据和恢复审计,不能只执行孤立的 IDLE 更新。
|
||||
5. 重启恢复进程、恢复 worker,验证网页及本地正常写入后再开放 Git。不自动发布社区。
|
||||
|
||||
回滚先关闭 Git 功能并排空接收请求,核对处理中操作后再回退应用。旧版本不能消费未解决的 GIT_PUSH;未解决前保持维护停写。保留新增表/列/凭据/审计、仓库内容及 main 保护,不删对象或撤销保护。功能关闭后仍可在网站查询、撤销 Git Token。
|
||||
|
||||
+29
-1
@@ -1,6 +1,6 @@
|
||||
# 数据库初始化
|
||||
|
||||
业务数据库名为 `vibemake`,基础业务包含以下四张表;完整部署还需执行 [管理端增量 SQL](admin-database.md),新增迁移任务与仓库写入操作表。由人工执行;应用不运行迁移或自动建表。以下 SQL 面向 MySQL 8.0.13 及以上(URDF JSON 默认值使用表达式)。
|
||||
业务数据库名为 `vibemake`,基础业务包含以下四张表及项目 Git 凭据表;完整部署还需执行 [管理端增量 SQL](admin-database.md),新增迁移任务与仓库写入操作表。由人工执行;应用不运行迁移或自动建表。以下 SQL 面向 MySQL 8.0.13 及以上(URDF JSON 默认值使用表达式)。
|
||||
|
||||
```sql
|
||||
CREATE DATABASE IF NOT EXISTS vibemake CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
|
||||
@@ -310,3 +310,31 @@ WHERE LEFT(cover_url, 16) = '/project-covers/'
|
||||
```
|
||||
|
||||
最后查询必须为空,随后验证旧格式地址并回退应用,再恢复写入。旧版不识别相对路径,禁止只回退代码而跳过数据转换。
|
||||
|
||||
|
||||
## 项目 Git 凭据
|
||||
|
||||
HTTPS Git 功能默认关闭。已有数据库在启用前手工执行下列建表,以及 [仓库写入记录扩展](admin-database.md#https-git-写入记录扩展)。不自动迁库;回滚保留表和审计记录。所有时间为上海时间。
|
||||
|
||||
```sql
|
||||
CREATE TABLE project_git_token (
|
||||
id BIGINT NOT NULL AUTO_INCREMENT COMMENT '内部主键,不对用户端暴露',
|
||||
token_code CHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT 'Git凭据唯一业务编码',
|
||||
project_code CHAR(32) NOT NULL COMMENT '绑定的项目业务编码',
|
||||
owner_user_id BIGINT NOT NULL COMMENT '所属用户内部标识,仅内部关联',
|
||||
token_name VARCHAR(64) NOT NULL COMMENT '用户填写的凭据名称',
|
||||
token_hash CHAR(64) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '凭据明文的SHA256摘要,不保存明文',
|
||||
permission VARCHAR(16) NOT NULL COMMENT '权限 READ_ONLY只读 READ_WRITE读写',
|
||||
session_version BIGINT NOT NULL COMMENT '签发时账号会话版本,用于账号变更后失效',
|
||||
expires_at DATETIME(3) NOT NULL COMMENT '过期时间,上海时间',
|
||||
revoked_at DATETIME(3) NULL COMMENT '撤销时间,未撤销为空',
|
||||
last_used_at DATETIME(3) NULL COMMENT '最近成功认证时间,上海时间',
|
||||
created_at DATETIME(3) NOT NULL COMMENT '创建时间,上海时间',
|
||||
updated_at DATETIME(3) NOT NULL COMMENT '最近更新时间,上海时间',
|
||||
PRIMARY KEY (id),
|
||||
UNIQUE KEY uk_git_token_code (token_code),
|
||||
UNIQUE KEY uk_git_token_hash (token_hash),
|
||||
KEY idx_git_token_project_owner (project_code, owner_user_id, created_at)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4
|
||||
COLLATE=utf8mb4_unicode_ci COMMENT='项目级Git访问凭据';
|
||||
```
|
||||
|
||||
@@ -18,6 +18,7 @@
|
||||
- [项目 URDF 文件夹](#项目-urdf-文件夹)
|
||||
- [目录和文件读取](#目录和文件读取)
|
||||
- [文件编辑与上传提交](#文件编辑与上传提交)
|
||||
- [HTTPS Git 与本地开发](#https-git-与本地开发)
|
||||
- [社区发布和撤回](#社区发布和撤回)
|
||||
- [社区详情和 Fork](#社区详情和-fork)
|
||||
- [评论和点赞](#评论和点赞)
|
||||
@@ -128,6 +129,10 @@ Git SHA 使用完整的 40 或 64 位十六进制字符串,不使用缩写。
|
||||
| GET | `/api/workspace/projects/{projectCode}/tree` | 是 | Tree |
|
||||
| GET | `/api/workspace/projects/{projectCode}/files` | 是 | ProjectFile 或下载二进制 |
|
||||
| GET | `/api/workspace/projects/{projectCode}/archive` | 是 | 当前或指定版本的 ZIP、TAR.GZ 仓库归档 |
|
||||
| GET | `/api/workspace/projects/{projectCode}/git` | 是 | GitConnection |
|
||||
| GET | `/api/workspace/projects/{projectCode}/git/tokens` | 是 | PageResult<GitTokenView> |
|
||||
| POST | `/api/workspace/projects/{projectCode}/git/tokens` | 是 | credential 和仅返回一次的 token |
|
||||
| DELETE | `/api/workspace/projects/{projectCode}/git/tokens/{tokenCode}` | 是 | null |
|
||||
| POST | `/api/workspace/projects/{projectCode}/commits` | 是 | Commit |
|
||||
| GET | `/api/workspace/projects/{projectCode}/commits` | 是 | PageResult<HistoryEntry> |
|
||||
| POST | `/api/workspace/projects/{projectCode}/uploads/commit` | 是 | Commit |
|
||||
@@ -1625,3 +1630,106 @@ export default {
|
||||
Fork 每用户每分钟 10 次、URDF 批次签名 20 次、封面签名 30 次,均为独立请求尝试次数;一个 URDF 文件夹的一次批次签名算一次,不按文件数计。Fork 同时执行仍最多 2 个,文件读取/目录/历史/提交/上传合计最多 4 个。普通 JSON 256 KiB、URDF 清单 2 MiB、提交 JSON 64 MiB,原有单文件和总内容约束继续保留。全部规则和可配置变量见 [部署说明](admin-deployment.md#redis-安全与资源保护)。
|
||||
|
||||
登录和签名响应显式禁止缓存。CORS 新增暴露 Retry-After,不启用跨域 Cookie;正文、Token、邮箱及验证码答案不得写入前端日志。
|
||||
|
||||
## HTTPS Git 与本地开发
|
||||
|
||||
Git 网关默认关闭,开启后仅本人工作区可 clone/fetch/pull/push;社区项目先 Fork。网站身份沿用邮箱加图片验证码,当前不验证邮箱归属,Git Token 继承此身份校验边界。普通用户不需要 Gitea 账号。
|
||||
|
||||
### 接口清单与数据
|
||||
|
||||
以下接口均携带网站 `Authorization: Bearer <平台 Token>`,仅所有者可访问。所有成功响应仍为平台 ApiResponse,均设置 `Cache-Control: no-store`;Git 协议请求使用独立认证。
|
||||
|
||||
| 接口 | 作用 |
|
||||
| --- | --- |
|
||||
| `GET /api/workspace/projects/{projectCode}/git` | 获取克隆信息及写入状态 |
|
||||
| `GET /api/workspace/projects/{projectCode}/git/tokens?page=1&size=20` | 分页查询 Git 凭据元数据 |
|
||||
| `POST /api/workspace/projects/{projectCode}/git/tokens` | 创建凭据,明文只返回一次 |
|
||||
| `DELETE /api/workspace/projects/{projectCode}/git/tokens/{tokenCode}` | 撤销凭据,重复撤销成功 |
|
||||
|
||||
克隆信息 data:
|
||||
|
||||
```json
|
||||
{
|
||||
"cloneUrl": "https://git.example.com/git/projects/7m4k9x2p8q6r.git",
|
||||
"username": "111111111111",
|
||||
"defaultBranch": "main",
|
||||
"headCommitSha": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
|
||||
"publishedCommitSha": null,
|
||||
"writeStatus": "IDLE",
|
||||
"canPush": true
|
||||
}
|
||||
```
|
||||
|
||||
`canPush` 表示当前项目状态、main 保护及技术账号配置允许写入,不保证后续请求一定成功;仍需读写权限的 Git Token。`writeStatus=WRITING` 表示正在写入,`REVIEW` 表示结果待核对。仅刷新页面即可看到已推送内容,不使用项目 updatedAt 判断版本。
|
||||
|
||||
创建请求:
|
||||
|
||||
```json
|
||||
{"name":"我的笔记本","scope":"READ_WRITE","expiresInDays":90}
|
||||
```
|
||||
|
||||
name 必填、非空、最多64字符;scope 为 READ_ONLY 或 READ_WRITE;expiresInDays 省略默认90,允许1~365。每项目最多10个有效凭据。读写凭据创建前会核验或初始化 main 保护;配置不兼容返回错误,不覆盖已有规则。首次签发会由后端管理账号给独立技术账号授予该仓库 write 权限,用户侧权限仍由项目 Token 决定。
|
||||
|
||||
创建成功 data 为 `{ "credential": GitTokenView, "token": "vbg_..." }`;列表 data 为 `PageResult<GitTokenView>`。GitTokenView 只有 tokenCode、name、scope、status、createdAt、expiresAt、revokedAt、lastUsedAt。status 为 ACTIVE、EXPIRED、REVOKED(包括账号会话版本变化失效)。时间沿用本文上海时间约定。最近使用时间最多每5分钟写回一次。
|
||||
|
||||
明文仅在创建时展示一次,不能再次查询;遗失后撤销并新建。列表、日志、数据库均不保存或返回明文。普通退出网站不撤销 Git Token;撤销、过期、禁用账号或账号 sessionVersion 改变后,新 Git/LFS 请求会被拒绝。已经受理的传输不保证立即中止或回滚。
|
||||
|
||||
### 网站交互与本地使用
|
||||
|
||||
工作区提供“克隆与本地开发”入口,显示克隆 URL、用户名、main SHA、发布 SHA 和写入状态;提供 Token 创建、列表、撤销和一次性明文展示。明文只保存在当前展示状态,不写 localStorage、不放克隆 URL、查询参数或日志。用户可用操作系统凭据管理器保存。
|
||||
|
||||
Git 使用 HTTP Basic:用户名为网站 userCode,密码为项目 Git Token;网站 Bearer Token 不能用于 Git,Git Token 不能用于普通 `/api`。同域名不同项目必须配置 HTTP 路径级凭据:
|
||||
|
||||
```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 v0/v2 读取、main 正常快进更新和合并提交,保留本地提交作者、邮箱、时间、签名及 SHA。禁止强推、删除 main、创建其他分支或标签、多引用推送、push-options、signed-push 扩展;普通签名提交支持。仓库已有其他分支和标签可以读取,本期不清理历史数据。LFS Basic Transfer 支持实体上传、下载和 verify;不支持 LFS 文件锁,locks/verify 返回空集合,锁创建/删除返回501。不递归下载子模块,独立绑定的 OSS 封面、URDF、STEP、模型等资源不会自动进入仓库。
|
||||
|
||||
本地 push 后重新请求工作区 tree、files、commits 显示最新内容;社区仍固定 publishedCommitSha,需用户明确点击发布。网页编辑基准落后继续返回409,保留用户输入;本地 main 落后时先 pull、合并再 push。REVIEW 期间阻止仓库写入及发布,后台只读核对,不自动重推。网络断开或超时不能视为失败,先刷新核对。
|
||||
|
||||
前端创建示例(复用本文 request):
|
||||
|
||||
```ts
|
||||
interface GitTokenView {
|
||||
tokenCode: string;
|
||||
name: string;
|
||||
scope: 'READ_ONLY' | 'READ_WRITE';
|
||||
status: 'ACTIVE' | 'EXPIRED' | 'REVOKED';
|
||||
createdAt: string;
|
||||
expiresAt: string;
|
||||
revokedAt: string | null;
|
||||
lastUsedAt: string | null;
|
||||
}
|
||||
async function createGitToken(projectCode: string, token: string) {
|
||||
return request<{credential: GitTokenView; token: string}>(
|
||||
`/workspace/projects/${encodeURIComponent(projectCode)}/git/tokens`, {
|
||||
method: 'POST', token,
|
||||
body: {name: '我的笔记本', scope: 'READ_WRITE', expiresInDays: 90},
|
||||
});
|
||||
}
|
||||
```
|
||||
|
||||
协议路径 `/git/**` 成功响应为 Git pkt-line/pack 或 LFS 标准结构;错误使用 Git 文本或 LFS `{message}`,不使用平台包装。401 含 Basic challenge,429 含 Retry-After。不要用浏览器平台 JSON 请求封装访问协议路径。
|
||||
|
||||
| 错误码/状态 | 处理 |
|
||||
| --- | --- |
|
||||
| GIT_UNAVAILABLE / 503 | 功能关闭或依赖不可用,保留网站编辑入口;仍可查询、撤销已有凭据 |
|
||||
| GIT_POLICY_UNAVAILABLE / 503 | 技术账号或 main 保护不兼容,联系运维,不放宽规则 |
|
||||
| CONFLICT / 409 | 有效凭据已达上限,先撤销旧凭据 |
|
||||
| GIT_UNAUTHORIZED / 401 | 用户名或项目 Git Token 无效、过期或撤销 |
|
||||
| GIT_READ_ONLY / 403 | 使用读写 Token 后再推送或上传 LFS |
|
||||
| GIT_COMMAND_REJECTED / 400 | 仅推送 main,移除不支持的引用/扩展 |
|
||||
| GIT_STALE_MAIN / 409 | 先拉取、合并,再推送 |
|
||||
| GIT_BUSY / 429 | 用户限流、IP认证失败限流或并发已满,稍后手动重试 |
|
||||
| GIT_TRANSFER_TOO_LARGE、GIT_METADATA_TOO_LARGE、LFS_TOO_LARGE / 413 | 缩小请求或联系运维核对配置 |
|
||||
| GIT_TIMEOUT / 504、GIT_UPSTREAM_ERROR / 502、REMOTE_RESULT_UNKNOWN / 409或503 | 涉及 push 时先刷新工作区及历史,结果未确认前不能重复写入 |
|
||||
|
||||
默认 pack 5 GiB、LFS 单对象1 GiB、元数据8 MiB、batch最多500个对象;每次 Git/LFS 请求预算10分钟,含请求及响应流。读取/push/LFS 每实例并发4/2/8;每用户每分钟 Git120次、LFS600次,每IP每分钟最多20次认证失败。均可配置,独立于 JSON、multipart、在线50 MiB文件读取和归档下载限制。中途超限、超时或断开会终止传输;不提供任务、进度查询或断点续传接口。
|
||||
|
||||
Reference in New Issue
Block a user