Files

361 lines
47 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.
# Vibemake
Spring Boot 社区后端,工程分层参考 cadworld。使用 Java 21、Spring Boot 3.5.16、MyBatis-Plus 3.5.11、MySQL 和 Gitea API v1。业务库名为 vibemake,包含 sys_user、project、project_comment、project_like,以及管理端的 project_import_task。
项目模块和 Java 包名统一使用 `vibemake`,对外接口继续使用原有 `/api/community/**` 等路径,前端调用方式保持不变。
平台管理用户、项目归属、类型、发布、评论、点赞和 Fork 来源;Gitea 管理文件、目录、Commit 与历史。仓库统一存放在配置的 Gitea 组织下,为私有仓库。
内置项目类型为 GENERAL(通用)、HUMANOID(人形)、QUADRUPED(四足)、WHEELED(轮式)、ROBOTIC_ARM(机械臂)。前端通过 `/api/project-types` 获取类型列表,用于项目创建、修改和列表筛选。
## 工程结构
| 模块 | 职责与主要包 |
| --- | --- |
| vibemake-api | 应用入口、HTTP 接口和接口配置;使用 api.controller、api.config |
| vibemake-bean | 数据库实体在 bean.entity,常规请求与响应在 bean.Contracts,AI 协议在 bean.ai |
| vibemake-service | 业务 Service 接口在 service 根包,实现类在 service.impl;包含 mapper、config、gitea、ai、support |
| vibemake-security | 平台登录会话、验证码、身份上下文、认证过滤器和安全配置 |
| vibemake-common | 通用响应、分页、异常处理、requestId 和基础工具 |
| vibemake-adminapi | 独立管理端应用,用户角色鉴权、用户与全站项目管理、GitHub 在线迁移 |
| vibemake-import | 固定 Excel 的 GitHub 项目运维导入命令,不提供 HTTP 接口 |
UserService、ProjectService、FileService、InteractionService、CoverUploadService、UrdfService 采用接口加实现类,Controller、安全模块和服务之间通过接口注入。GiteaClient 与 RestGiteaClient 定义仓库调用边界;项目锁、上海业务时间(Asia/Shanghai)和分页检查归入 support。安全模块内的 TokenService、CaptchaService 保留具体类,短期状态使用 Redis,限流和共享响应组装位于 service。
## 功能与边界
支持邮箱加图片验证码登录、我的项目列表、在线文本编辑、新建文件和目录、上传及多文件提交、手动发布和撤回、已发布版本浏览、快照 Fork、平铺评论和点赞,以及可配置开启的 Maker AI(聊天问答、查找、创建空项目、Fork)。工作区是用户项目列表,没有 workspace 表。没有 repository_operation 表、草稿保存、类型表、标签、收藏、成员协作;管理后台接口由 vibemake-adminapi 提供。
**社区登录不验证邮箱归属,知道别人的邮箱并通过图片验证码即可登录其社区身份;USER 和 ADMIN 均使用邮箱加图片验证码登录前台,无需密码;后台仅允许 ADMIN 通过邮箱和密码登录;OFFICIAL 禁止登录。** 验证码、登录会话和请求频率使用 Redis;两个应用仍各单实例部署,应用重启后保留 Redis 中未过期的会话。首次从本机缓存版本升级需要重新登录。所有仓库写入统一经过平台后端。
## 启动
1. 安装 Java 21、Maven 3.9+,准备 MySQL 8.0.13 及以上和现有 Gitea。
2. 新建数据库手动执行 [基础四表 SQL](docs/database.md),并创建 [迁移任务表](docs/admin-database.md)。已有数据库执行管理端文档的增量 SQL;应用不会自动迁库。
3. 在 Gitea 创建私有组织,将技术账号设为组织所有者,生成具有 write:repository、write:organization、read:user 权限的 Token。
4. 将 .env.example 复制为 .env,填写数据库连接、Redis 连接与 Gitea 地址、组织、Token;默认使用 test 环境,.env 被 Git 忽略,不提交真实凭据。
5. 执行:
```bash
bash scripts/run-local.sh
```
当前机器已配置 Gitea 26.4.0,并建立私有组织 vibemake。本机 .env 已保存 Gitea Token,权限为 0600;没有保存管理员密码。保留这些 Gitea 配置,再补充 DB_URL、DB_USERNAME、DB_PASSWORD 和 REDIS_* 连接配置,不要用示例覆盖已有 Token。
直接部署时通过环境变量配置,运行打包后的 vibemake-api/target/vibemake-api-0.0.1-SNAPSHOT.jar。默认端口 8993,SERVER_PORT 或 PORT 可覆盖(SERVER_PORT 优先)。本机脚本会加载 .env,直接运行 jar 不会自动加载该文件。
接口文档:[前端接口对接文档](docs/vibemake-api.md),包含全部接口、字段结构、请求响应示例、页面调用顺序和错误处理。test 环境启动后访问 /swagger-ui.html;机器可读 OpenAPI 为 /v3/api-docs。prod 默认关闭这两个入口。
## 环境与日志
配置与日志方式参考 cadworld:application.yml 保存公共配置,application-test.yml 和 application-prod.yml 分别保存环境相关的数据库、Gitea、跨域白名单和日志配置。不指定环境时默认 test,通过 SPRING_PROFILES_ACTIVE 或启动参数切换。
prod 启动时检查数据库连接、用户名、密码、Gitea 地址和 Token 是否已配置且非空;缺失时停止启动,错误信息只包含配置项名称。
| 配置 | test | prod |
| --- | --- | --- |
| 数据库 | 默认本机 vibemake,可用 DB_* 覆盖 | 必须配置 DB_URL、DB_USERNAME、DB_PASSWORD |
| Gitea | 默认本机地址,使用 GITEA_* 覆盖 | 必须配置 GITEA_BASE_URL、GITEA_TOKEN、GITEA_ORGANIZATION |
| API 跨域来源 | `https://dev-vibemake.robotquan.com` | `https://vibemake.robotquan.com` |
| OSS 封面目录 | vibemake_dev/project-covers/ | vibemake/project-covers/ |
| OSS URDF 目录 | vibemake_dev/urdf/{projectCode}/{batchCode}/ | vibemake/urdf/{projectCode}/{batchCode}/ |
| OSS README 图片目录 | vibemake_dev/readme-images/ | vibemake/readme-images/ |
| 连接池 | 最少 1、最多 10 个连接 | 最少 1、最多 20 个连接 |
| 项目日志级别 | DEBUG | INFO |
| 日志目录 | logs,可用 LOG_PATH 覆盖 | logs,可用 LOG_PATH 覆盖 |
生产部署示例(先在部署环境配置以上连接变量):
```bash
SPRING_PROFILES_ACTIVE=prod java -Djava.awt.headless=true -jar vibemake-api/target/vibemake-api-0.0.1-SNAPSHOT.jar
```
本机脚本支持传递启动参数,例如 `bash scripts/run-local.sh --spring.profiles.active=prod`,此时加载 .env 中的连接信息并使用 prod 配置。测试和生产数据库、Gitea 组织需要各自隔离时,分别设置对应的 DB_*、GITEA_* 变量。
跨域白名单由 `vibemake.cors.allowed-origins` 指定,仅作用于 `/api/**`。支持 Bearer Token、JSON、文件上传下载和 AI SSE,预检缓存 3600 秒,暴露 `X-Request-Id`、`Content-Disposition`、`Retry-After`,不启用跨域 Cookie 凭据。启动日志会记录生效的白名单。默认不开放 HTTP、localhost、其他端口或跨环境来源;本地继续使用前端开发代理,配置见[开发代理示例](docs/vibemake-api.md#开发代理示例)。部署代理需透传预检请求、Origin 和后端 CORS 响应头,避免重复添加跨域头;OSS Bucket 的 CORS 仍需独立配置。
日志配置沿用 cadworld-common 的 logback-spring.xml 模板,放在 vibemake-common;应用名为 vibemake-api。测试和生产默认都写入 logs,可用 LOG_PATH 覆盖目录;目录相对于应用启动时的工作目录。本机启动脚本从项目根目录运行。
同时输出控制台、vibemake-api.log 和 vibemake-api-error.log,日志时间使用 Asia/Shanghai,格式包含线程、级别、requestId 和类名。应用日志按天或每 100MB 归档,保留 30 天、总归档上限 10GB;错误日志仅接收 ERROR,按天或每 50MB 归档,保留 60 天、总归档上限 5GB。归档写入 archive 子目录并压缩为 gzip。SQL Mapper 和 Spring Web 保持 INFO,不记录凭据、邮箱或代码内容。
业务数据库与接口中的日期时间统一使用 `Asia/Shanghai`,不依赖服务器默认时区;接口中不带时区后缀的时间需按 `+08:00` 解析。OSS 签名协议字段保留 UTC,Git 提交日期保留原时区。已有 UTC 数据库升级前,先按[业务时间迁移说明](docs/admin-database.md#业务时间由-utc-迁移到上海时间)完成一次性转换,再同时部署社区端、管理端与导入工具;前端同步调整解析方式。
## 仓库归档下载配置
用户端工作区与社区均支持 ZIP、TAR.GZ 仓库归档:工作区需登录且只能下载本人项目,支持当前 main 或指定历史 SHA;社区可匿名下载当前已发布 SHA。后端鉴权后直接流式转发 Gitea 原生归档,不向浏览器返回 Gitea 凭据或内部地址,无需数据库变更,也不新增本地 Git 或临时磁盘依赖。
| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| ARCHIVE_MAX_BYTES | 1073741824 | 压缩包最大字节数,默认 1 GiB,独立于单文件与 multipart 限制 |
| ARCHIVE_TIMEOUT | 5m | 获取当前 SHA、归档响应及响应体读取的上游预算 |
| ARCHIVE_MAX_CONCURRENT | 2 | 每实例独立归档并发,超限返回 ARCHIVE_BUSY,不占用普通文件并发额度 |
| RATE_ARCHIVE_READ_PER_MINUTE | 10 | 每 IP 每分钟归档额度,工作区与社区共用 |
对应配置为 `vibemake.archive.max-bytes`、`timeout`、`max-concurrent` 和 `vibemake.limits.per-minute.archive-read`;大小必须大于 0,并发为 1~32,超时为 100 毫秒~1 小时。沿用 Gitea 服务端 Token,需具有目标私有仓库的读取权限。上线前确认 `/api/v1/repos/{owner}/{repo}/archive/{SHA}.zip`、`{SHA}.tar.gz` 均直接返回 HTTP 200 文件;本服务不跟随重定向。Gitea 使用对象存储归档并返回重定向时,应配置 Gitea 直接输出归档(1.26.4 的 `[repository] STREAM_ARCHIVES=true` 支持此行为)。
代理读取超时至少 400 秒;调大 ARCHIVE_TIMEOUT 时同步增加代理超时,流式响应应关闭代理缓冲和缓存。中途超限、超时或连接断开会停止传输,已发送附件后不能再返回 JSON,下载文件可能不完整,应丢弃并手动重新下载。本期不支持断点续传、下载任务或进度查询。
归档沿用 Gitea 原生规则,LFS 保留指针,不下载实体,不递归下载子模块,也不包含单独绑定于 OSS 的封面、URDF、STEP、GLB、零件、拼装及行走资源。接口及支持取消的 fetch 示例见[仓库 ZIP、TAR.GZ 下载](docs/vibemake-api.md#仓库-ziptargz-下载)。
## 验证
```bash
mvn clean verify
```
普通测试固定使用 test 配置,覆盖连接为临时 H2 MySQL 模式及模拟 Gitea/AI/OSS,验证登录、权限、提交冲突、发布快照、Fork、评论、点赞、URDF 直传核验和独立复制,以及 AI 筛选、引用校验、创建、Fork 与候选选择、SSE、限流、超时和取消,不访问真实数据库、仓库、对象存储或模型。未加载外部服务凭据时,执行 `GIT_ENABLED=false AI_ENABLED=false VIBEMAKE_AI_ENABLED=false OSS_ENABLED=false mvn verify`;其中 `GIT_ENABLED` 关闭需要独立凭据的 Git 网关,`VIBEMAKE_AI_ENABLED` 用于覆盖管理端当前固定开启的 AI 配置,对应流程测试自行启用模拟服务。完整安装验证可执行 `GIT_ENABLED=false AI_ENABLED=false VIBEMAKE_AI_ENABLED=false OSS_ENABLED=false mvn clean install`。
PCB 个人工作空间提供 `/api/pcb/workspace/projects` 八个接口,支持独立列表、完整工程 ZIP 直传保存、幂等确认与版本冲突保护。上线前手工执行 [PCB 建表 SQL](docs/pcb-database.md),配置共用 OSS 后设置 `PCB_OSS_ENABLED=true`;默认关闭,ZIP 默认上限 256 MiB、上传有效期 15 分钟。前端对接与部署见 [PCB 工作空间文档](docs/frontend-pcb-workspace.md)。普通测试覆盖 PCB 与 CAD 保存链路,不访问真实 OSS。
真实 Gitea 联调:
```bash
python3 scripts/test-gitea.py
```
该测试使用临时 H2 数据库,在配置的组织创建临时项目仓库,验证私有仓库、多文件提交、中文路径、二进制上传、ZIP/TAR.GZ 归档、固定发布版本及快照 Fork,结束后仅删除本次测试创建的仓库。归档联调核对中文路径、二进制内容、LFS 指针及发布后继续提交时的版本隔离。Gitea 26.4.0 内置的 1.26.4 支持批量文件变更;以服务器 /swagger.v1.json 为对接依据。
## 测试 Gitea 组织仓库复制到生产
`scripts/migrate-gitea-org.py` 使用 Python 3.9+ 标准库,将测试 `vibemake` 下的 Git 仓库复制到生产 `vibemake`(组织可通过参数修改)。生产 Gitea 应先初始化,并创建目标组织。目标为同名私有普通仓库,保留默认分支、历史、分支和标签,并请求迁移 LFS;不复制 Issue、PR、Release、Wiki、用户、组织成员、权限、Webhook 或 Actions 执行记录,也不导入 Gitea 整库、不复制实例配置。
两端账号需是对应组织的所有者或站点管理员。测试 Token 需有 `read:repository`、`read:organization`、`read:user`、`read:misc`,生产 Token 需有 `write:repository`、`write:organization`、`read:user`、`read:misc`;仓库访问范围应包含私有仓库。迁移期间暂停源组织写入、导入任务以及目标后端写入,Gitea 本身保持运行。生产 Gitea 容器必须能通过 HTTP Git 和 LFS 访问测试地址,两端开启 HTTP Git/LFS,生产开启仓库迁移。
在项目根目录执行(替换地址):
```bash
# 两次提示分别输入测试、生产 Token,输入不回显,不会写入命令历史。
# 默认只读预览;不自动读取现有 .env,避免把两个环境的凭据混用。
python3 scripts/migrate-gitea-org.py \
--source-url https://测试Gitea域名 \
--target-url https://生产Gitea域名 \
--dry-run
# 先复制一个尚未处理的仓库。
python3 scripts/migrate-gitea-org.py \
--source-url https://测试Gitea域名 \
--target-url https://生产Gitea域名 \
--execute --limit 1
# 抽查通过后,用相同状态目录续跑其余仓库。
python3 scripts/migrate-gitea-org.py \
--source-url https://测试Gitea域名 \
--target-url https://生产Gitea域名 \
--execute
```
可重复指定 `--repo p_项目编码` 限定仓库;`--source-org` 默认 `vibemake`,`--target-org` 默认 `vibemake`。非交互执行可通过 `GITEA_MIGRATION_SOURCE_TOKEN`、`GITEA_MIGRATION_TARGET_TOKEN` 注入凭据,不接受 Token 命令行参数。默认只允许 HTTPS;仅在可信网络确需明文连接时指定 `--allow-http`。API 请求不跟随重定向,不将凭据放入 URL、状态文件或日志。迁移请求会将源账号和 Token 放在发往生产 Gitea 的请求体中,生产 Gitea 用它们读取源私有 Git/LFS。单仓库请求超时默认 1800 秒,可用 `--migration-timeout` 调整;生产反向代理的超时也应相应配置。
`--state-dir` 默认 `logs/gitea-org-migration`,同一批次只允许运行一个进程;目录权限 0700,文件权限 0600。目录绑定源/目标地址、组织和初始仓库清单;组织仓库发生增删或同名重建时停止,不自动改变迁移范围。`state.json` 保存进度、源分支/标签快照及成功迁移返回的目标仓库标识;`mapping.json` 仅包含已取得 HTTP 201 完成收据并核对仓库身份、私有属性、默认分支、分支和标签提交的记录。LFS 由 Gitea 迁移流程处理,脚本不逐对象下载核验;先试迁一个带 LFS 的仓库,用 `git lfs pull`/实际下载检查实体后再批量执行。子模块只保留 Git 引用,不递归复制其他仓库。
生产同名仓库标记 `CONFLICT`,不接管、不覆盖。超时、服务端错误、返回状态不明确或迁移中断时标记 `REVIEW`,停止本次新增仓库;Gitea 可能仍在后台执行,不能仅凭仓库存在认定 LFS 已完成。保留状态目录并核对生产日志及仓库;没有成功收据的记录不会自动重发。有成功收据、仅核验失败的记录,在续跑时只读核对。不要删除状态文件来盲目重试,也不要自动删除生产仓库。退出码 0 表示本次无冲突/待核对项(预览或 `--limit` 仍可能有 `PLANNED`),2 表示存在 `CONFLICT`/`REVIEW`,1 表示预检或运行环境错误。
历史导入中断后,源数据库的 `empty` 标记可能与磁盘内容不一致;脚本会检查实际 Git 引用,存在引用时按 Git 对象 SHA 核对分支和标签。LFS 还需核查迁移日志:Gitea 可能忽略源端缺失的 LFS 对象后仍返回 HTTP 201。出现 `Ignoring missing upstream LFS object` 时,应按对象 SHA-256、大小建立缺失清单,从可信原始上游或备份恢复,并验证生产端实体可下载;不能把成功响应当作缺失文件已补齐。
仓库复制后,生产社区后端设置自己的 `GITEA_BASE_URL`、`GITEA_TOKEN` 和 `GITEA_ORGANIZATION=vibemake`。此工具不连接业务数据库;已复制到生产的 `project` 记录还需按 `mapping.json` 核对项目编码及原仓库标识,再在生产业务库回写 `gitea_owner` 和新的 `gitea_repo_id`,保持 `gitea_repo_name`、发布提交 SHA 等值,并确认已发布 SHA 可读取。`gitea_repo_id` 有唯一索引,回写需处理旧标识与新标识的冲突;备份后在维护事务中执行,不改测试业务库。原 GitHub 导入批次的收据不能直接当作新生产仓库收据复用。OSS 封面、URDF、业务用户及项目记录的复制需单独处理。
## 项目封面与 OSS 直传
项目 API 的 `coverUrl` 接收和返回完整 HTTPS 地址,平台封面在数据库中保存 `/project-covers/...` 环境相对路径,外部图片保留完整 URL。无封面时返回 null;创建时可省略,修改时省略或 null 保留原值,传空字符串清除。Fork 继承同一资源引用,替换、清除或删除项目不自动删除 OSS 图片。URDF 同样保存 `/urdf/...` 环境相对路径,上传和 OSS 操作仍使用含环境根目录的真实 key。人工迁移和回退见 [数据库说明](docs/database.md#资源路径历史数据迁移)。
已有数据库必须先执行 [封面字段升级 SQL](docs/database.md#已有数据库增加项目封面),再部署新应用;新建数据库使用更新后的建表 SQL。应用不会自动变更表结构。
OSS 默认关闭,外部 HTTPS 封面仍可使用。启用时设置 `OSS_ENABLED=true`,并配置 `OSS_REGION`、`OSS_BUCKET`、`OSS_ACCESS_KEY_ID`、`OSS_ACCESS_KEY_SECRET`。地域 ID 使用 `cn-beijing` 等编码,不带 `oss-` 前缀。Endpoint 默认根据地域推导为 `https://oss-{region}.aliyuncs.com`,无需配置环境变量;特殊域名场景可显式配置 `vibemake.oss.endpoint`,使用可供浏览器访问的公网 HTTPS 地址,不包含 Bucket、路径或查询参数。`OSS_PUBLIC_BASE_URL` 可选,用于公开 CDN/OSS 基础地址;省略时使用 Bucket 标准 HTTPS 域名。启用但配置缺失或不合法时停止启动,未启用时签名接口返回 503 `OSS_UNAVAILABLE`。
目录由环境配置指定:test 使用 `vibemake_dev/`,prod 使用 `vibemake/`;二者均为桶内对象前缀。凭据使用仅能写入对应环境 `project-covers/*` 路径的 RAM 用户,密钥保留在服务端。实际 Bucket 和 CDN/OSS 域名由部署环境提供,不由应用创建。
登录后请求 `POST /api/uploads/project-covers/signature`,获得 OSS POST V4 表单和固定 `coverUrl`。签名有效期 5 分钟,支持 JPG、PNG、WebP,单张最多 5 MiB。浏览器直传成功后再保存项目,后端不接收图片内容。签名支持创建项目前上传;当前不提供上传完成回调、服务端图片内容检测或未绑定图片自动清理。
Bucket 需要配置前端实际域名的 CORS,允许 POST;图片通过公开读取规则或公开 CDN 地址访问。完整配置步骤、错误处理和前端 FormData 示例见[封面上传接口](docs/vibemake-api.md#项目封面与-oss-直传)。官方协议参考 [OSS POST V4](https://www.alibabacloud.com/help/en/oss/developer-reference/signature-version-4-recommend) 和[服务端签名直传](https://www.alibabacloud.com/help/en/oss/user-guide/obtain-signature-information-from-the-server-and-upload-data-to-oss)。
部署验收:在 test 环境登录,获取签名、浏览器直传、保存项目并匿名访问封面;确认 OSS 对象位于 `vibemake_dev/project-covers/`,网络请求中的图片内容直接发往 OSS。prod 切换到 `vibemake/project-covers/`,图片地址不带临时下载签名。
## Maker AI
设置 `AI_ENABLED=true` 和 `ARK_API_KEY` 后启用,默认模型为 `doubao-seed-2-1-lite-260915`,地址为 `https://ark.cn-beijing.volces.com/api/v3/responses`。使用 `ARK_MODEL`、`ARK_ENDPOINT` 可覆盖。与 cadworld 一样使用 Responses API 和 JSON Schema,关闭深度思考,`store=false`;密钥只在后端读取。未开启时接口返回 503 `AI_UNAVAILABLE`;开启但没有密钥时停止启动。
登录后调用 `POST /api/community/ai/chat`,通过 SSE 获取阶段、结果或错误。对话由前端保留最近6轮,刷新后清空,不保存到数据库。
Maker AI 支持身份介绍、日常闲聊、一般知识和技术问答,包括文本代码示例。聊天与意图识别共用一次模型调用,返回 CHAT、完整 reply、空 projects 和 null project,不联网、不执行代码、不写入项目。回复最多2000字符,可直接加入 history;聊天只有 understanding → result 两个 SSE 事件,不逐字输出。前端收到 CHAT 后追加历史并保留 previousProjectCodes,支持搜索后穿插闲聊再选择项目。
同时支持查找、创建空项目和 Fork 已发布项目;模型提取结构化项目意图,后端校验后复用现有项目服务,每轮最多一次写入。闲聊不会触发历史中的待办或已完成操作。创建时可生成名称和目标描述,类型无法判断时默认 GENERAL,仅初始化仓库和默认 README。Fork 默认沿用来源名称,按执行时的当前发布版本复制;查找并 Fork 仅在本轮唯一推荐结果时执行,多个候选返回 NEEDS_SELECTION 供下一轮选择。成功通过 CREATED/FORKED 和 project 返回新项目,前端使用 projectCode 进入工作区。
查找时仅检索已发布且仓库就绪项目的名称、描述、类型:先理解需求,再查询最多20个候选,最后排序并校验最多5个项目卡片。项目编码、引用原文和当前发布状态由后端校验;缺少依据的明确要求不算匹配,未证实的偏好单独列出。
每次模型调用默认30秒,模型/搜索阶段65秒;进入 Fork 阶段后采用独立5分钟预算并保留15秒入口及终态余量,前端和代理读取超时至少400秒;`AI_REQUEST_TIMEOUT`、`AI_SEARCH_TIMEOUT` 可调整。`AI_MAX_CONCURRENT` 默认4,`AI_REQUESTS_PER_MINUTE` 默认每用户10次,均为单实例内存控制,超限不排队。连接断开时尽力取消上游调用,实际工作结束后释放并发名额。写入开始后取消或超时不保证回滚;错误事件保留初始化异常中的 projectCode,先核对工作区,不自动重发创建或 Fork。AI 错误不影响普通项目搜索。前端请求和 SSE 解析示例见接口文档的“Maker AI”。
本期不读取 README、代码或评论,不建立向量索引,不修改四表结构。检索效果依赖项目描述,建议写清用途、技术栈、主要硬件和适用场景。描述修改即时生效;工作区文件提交仍须重新发布才更新社区代码。
真实模型联调(会调用方舟并产生模型用量):
```bash
python3 scripts/test-ai.py
```
脚本在内存 H2 中建立公开示例项目,验证 Maker AI 身份介绍、代码问答、多轮聊天、闲聊不重放创建/Fork,以及四足检索后穿插闲聊再改为轮式,默认 Maven 测试跳过该联调。密钥从当前项目 `.env` 或环境变量读取,脚本不输出密钥、不写真实数据库、不访问 Gitea。
## Git 快照 Fork
后端保留鉴权、项目编码、来源记录和 OSS 复制,仓库数据通过 Git 对象级传输。按发布 SHA 的根 tree 生成一个无父提交,只推送新 main;保留普通大文件、文件模式、符号链接和子模块引用,不继承上游历史、其他分支或标签。子模块依赖仓库不递归复制。LFS 仅传输发布快照所需实体,推送后从新副本独立下载校验;不会只有指针却缺少实际对象。
应用运行用户的 PATH 需要包含 Git 和 git-lfs(本机验证 Git 2.52 / git-lfs 3.8)。CI 同样安装这两个程序,执行本地 Git 仓库及模拟 LFS 协议测试;普通业务测试替换仓库传输边界,不访问外部服务。启动时检查依赖,缺失仅使 Fork 返回 FORK_UNAVAILABLE,不阻止普通创建或其他接口。
开发环境可通过 `brew install git git-lfs` 安装;Debian/Ubuntu 的 CI 或部署镜像安装 `git`、`git-lfs` 软件包。以应用运行用户执行 `git --version` 和 `git lfs version` 确认 PATH 生效,无需执行全局 `git lfs install`。LFS 传输通过任务内的本地端点校验转发,拒绝 HTTP 重定向及指向其他地址的 action URL;临时目录禁止写入 git-lfs 原始错误报告,防止环境凭据落盘。
| 配置 | 默认值 | 用途 |
| --- | --- | --- |
| FORK_GIT_EXECUTABLE | git | Git 可执行文件路径,git-lfs 从子进程 PATH 查找 |
| FORK_TIMEOUT | 5m | Git、LFS、核验和 OSS 共用的总时间预算 |
| FORK_MAX_CONCURRENT | 2 | 单实例并发上限,实际工作结束后释放名额 |
| FORK_MAX_TEMPORARY_BYTES | 5368709120 | 每次临时磁盘上限,含 LFS 源缓存与副本校验缓存 |
| FORK_TEMPORARY_DIRECTORY | 系统临时目录/vibemake-fork | 建议使用容量充足的独立临时磁盘 |
服务账号的 GITEA_TOKEN 需同时允许 REST 仓库创建、HTTP Git 读写及 LFS 读写。凭据通过进程环境注入,只用于配置的 Gitea 地址;不写入 URL、命令参数、Git 配置或日志。Fork 接口继续同步返回,前端和反向代理读取超时至少400秒;AI 进入 forking 后切换专用预算并继续发送心跳。
Fork 不受 JSON 文件预览的 50 MiB 限制或单文件流式下载的 1 GiB 限制。Fork 失败时先核对响应 data.projectCode:明确失败为 FAILED,远端写入或数据库状态待核对为 CREATING;不会自动重发、删除远端仓库或 OSS 对象。完成后清理本地临时目录。使用 scripts/test-gitea.py 可执行显式真实 Gitea 联调,仅创建并清理本次测试专用仓库,不修改已有社区项目。
JSON 预览保留原有上限;三个端的 `download=true` 使用流式传输,默认单文件最大 1 GiB、上游处理和读取预算 5 分钟,分别由 `FILE_DOWNLOAD_MAX_BYTES`、`FILE_DOWNLOAD_TIMEOUT` 配置,LFS 指针不在线展开。下载路径需关闭代理响应缓冲并为代理和客户端至少预留 400 秒超时,详见[文件接口](docs/vibemake-api.md#目录和文件读取)。
## 运行约定
项目名称、描述、类型、封面修改直接更新展示;工作区代码提交后,社区仍读取已发布 SHA,需要手动更新。Fork 复制已发布文件快照,不继承上游提交历史,也不自动同步。项目删除采用逻辑删除,保留仓库和已有 Fork。
创建或 Fork 前先写入 CREATING 项目,成功后标记 READY。结果不明或数据库回写失败需要人工核对;不提供后台自动恢复、无条件自动重试或跨重启完整幂等。具体恢复方式见接口文档。
## 项目短编码与 GitHub 初始化导入
### README 外链图片转存 OSS
GitHub 后台迁移和 Excel 命令行导入在分支适配后自动检查根目录 `README.md`(文件名不区分大小写)。支持 Markdown 图片、引用式图片、HTML `img src`、`srcset` 和 `picture` 图片;仓库相对路径、代码示例、普通超链接及已配置的 OSS/CDN 地址保持原样。动态徽章(shields.io、GitHub Actions、ROS 构建状态、常见覆盖率徽章)保留原链,普通静态 SVG 通过安全校验后可以转存;仅外部 DTD 声明会移除,脚本、内部实体和远程资源引用仍禁止。其他语言的 README 或子目录文档不在本次处理范围。
设置 `README_IMAGES_ENABLED=false` 可以暂停转存;默认启用,单图上限 `README_IMAGE_MAX_BYTES=20971520`,图片并发 `README_IMAGE_CONCURRENCY=2`(1~4)。可在配置的 `vibemake.readme-images.preserve-url-patterns` 中追加需要保留的完整 URL 正则。图片只下载公开 HTTP/HTTPS 地址,不携带业务凭据;单图总预算 45 秒,每次 DNS 解析及重定向都禁止内网地址。JPG、PNG、GIF、WebP 和安全 SVG 按内容摘要写入 `{环境根目录}/readme-images/{SHA256}.{扩展名}`,不覆盖已有对象;上传核验并从公开地址读取核验成功后才替换 README。RAM 账号需要对应前缀的 PutObject/GetObject 权限,资源需要公开可读或通过公开 CDN 访问。
存量项目在项目根目录运行:
```bash
# 仅扫描数据库与仓库,不下载外链、不上传图片、不修改项目。
bash scripts/migrate-readme-images.sh --dry-run
# 先处理一个含待转存图片的项目。
bash scripts/migrate-readme-images.sh --execute --limit 1
# 同一状态目录断点续跑其余项目。
bash scripts/migrate-readme-images.sh --execute
# 指定项目重新尝试仍失败的图片,使用新的状态目录保存独立收据。
bash scripts/migrate-readme-images.sh --execute --project-code 项目编码 --state-dir logs/readme-image-retry
```
默认状态目录 `logs/readme-image-migration` 绑定 Gitea、组织、OSS Bucket、环境目录和公开基础地址,禁止跨环境复用;同时只允许一个进程使用。保存精确预览、原 README 备份、原发布 SHA、每一步操作收据和结果报告,目录/文件权限分别为 0700/0600,写入原子替换并持久化。脚本使用 `java-with-env.py` 安全读取 `.env` 字面量,不进行 shell 求值;含 `&` 的 JDBC 地址可正常读取,文件中的配置覆盖同名进程变量,与原有启动脚本一致。不会修改 `.env` 或输出配置值。
未删除且仓库 READY 的项目才进入批处理。main 与原发布版本一致时复用一个图片提交;不一致时从原发布 SHA 创建 `maintenance/readme-oss/...` 维护分支,确认仅 README 变化后更新发布引用。维护分支保留以确保快照可下载和 Fork;不将 main 上其他未发布代码带入社区,不改变撤回/下架状态或发布时间。GitHub 后台迁移仍由管理员手动发布,Excel 导入仍自动发布处理后的版本,来源 SHA 与图片提交 SHA 分开保存,兼容历史迁移收据。
图片下载失败、格式不支持或 OSS 不可用时保留原链并记录告警,其余图片继续;Git 写入结果不明确则保持待核对状态,续跑只查收据,不重发提交。报告的 `failed` 是保留原链的图片引用数。恢复业务展示可在项目锁中对照备份条件回写原发布 SHA;恢复 main 需基于当前版本提交 README 的反向修改,不能强制重置分支。不要删除共享 OSS 对象或维护分支。一般日志只记录项目编码、来源主机、阶段和错误码,含完整图片地址的原文只保存在受限备份中。
### 历史外链封面转存 OSS
`scripts/migrate-project-covers.sh` 读取本项目 `.env`,将数据库现有外链图片下载并转存至当前环境 OSS,上传并核验成功后才更新 `cover_url`。配置 `DB_URL`、`DB_USERNAME`、`DB_PASSWORD`、`OSS_REGION`、`OSS_BUCKET`、`OSS_ACCESS_KEY_ID`、`OSS_ACCESS_KEY_SECRET`;带 `&` 的 JDBC 地址必须加引号。环境根目录沿用 test 的 `vibemake_dev` 或 prod 的 `vibemake`。
```bash
# 默认只读预览,不下载、不上传、不更新数据库。
bash scripts/migrate-project-covers.sh --dry-run
# 先迁移三个项目,核对新封面的访问效果。
bash scripts/migrate-project-covers.sh --execute --limit 3
# 迁移其余外链,默认并发 2。
bash scripts/migrate-project-covers.sh --execute
```
支持 JPG、PNG、GIF、WebP,按实际文件头识别类型,原图不压缩、不转码。默认单图最多 5 MiB,可用 `--max-bytes` 调整,上限 50 MiB;`--concurrency` 范围为 1~4。下载只允许公开 HTTPS 地址,每次跳转重新校验,不携带任何平台或 GitHub 凭据,不访问内网地址。失效、超时、超限及非图片资源保留原值并进入失败报告。
实际对象位于 `{环境根目录}/project-covers/migrated/{图片SHA256}.{扩展名}`;数据库只保存 `/project-covers/migrated/...`。相同外链只下载一次,相同图片内容复用对象,已转存记录在再次运行时自动跳过;已属于本平台的完整 URL 也跳过,可按数据库迁移说明归一化。扫描包含已逻辑删除项目,以完成历史数据统一。未来新提交外链的行为不由此批处理修改。
每次运行在 `logs/cover-migration/` 生成独立报告目录(可用 `--report-dir` 修改)。`preview.json`、`report.json` 只包含项目编码、来源主机、状态及错误码,不记录完整外链或查询参数。`backup.jsonl` 保存修改前原值和拟写入路径,更新前强制落盘;目录和备份文件分别仅允许当前用户访问。原值可能包含签名参数,应作为受限数据库备份保存,不上传仓库或发送聊天。回写通过项目编码和原始 URL 字节比较,跳过迁移期间被修改的封面,不改 `updated_at`,不覆盖其他字段。
失败时可以重跑;上传成功但回写未完成的对象也按内容哈希复用,不会自动删除可能共享的对象。退出码 0 表示成功或仅预览,1 表示配置、连接等整体错误,2 表示存在逐项失败。人工恢复时仅将仍等于 `newCoverPath` 的记录按项目编码还原为 `originalCoverUrl`,避免覆盖之后的编辑。
对已经核验过的失效链接,可使用 `--source-overrides /绝对路径/备用源.json` 指定备用下载地址,JSON 格式为 `{"项目编码":"https://可信图片地址"}`。下载走同一套 HTTPS、大小和图片类型校验;数据库条件比较及原值备份仍使用原来的外链。采用的备用源另存于受限权限的 `source-overrides-backup.json`,便于审计。已成功迁移的项目在重跑时照常跳过。网络中断最多重试三次,证书校验失败不会绕过验证。
### 项目编码与导入流程
普通创建、Fork 和导入的新项目使用 12 位小写项目编码,字符集为 `0123456789abcdefghjkmnpqrstvwxyz`。普通项目用安全随机数生成,项目编码唯一约束冲突最多重试 5 次;其他约束错误不重试。首次导入编码由 `github-import:v1:<GitHub仓库ID>` 的 SHA-256 前 60 位确定,避免重跑或仓库更名后重复创建。后台在线迁移仅对未删除项目做来源去重;旧项目删除后再次新建迁移,使用来源与迁移代次生成新编码、新任务和新仓库,重新拉取 GitHub 内容,保留旧记录及仓库。管理员列表和详情仍隐藏已删除项目。已有后台需先执行[来源索引调整 SQL](docs/admin-database.md#允许已删除项目的-github-来源再次迁移本次上线前执行)。Gitea 仓库名称为 `p_{projectCode}`。历史 32 位编码、仓库及链接继续使用,无需因编码长度修改数据库字段。
导入工具仅接受以下固定 Sheet:`1_轮式机器人`、`2_四足机器人`、`3_小人形机器人`、`4_大人形机器人`、`5_机械臂`、`6_其他类型`、`7_开源硬件`。只选 I 列精确为“可访问”、L 列有合法 HTTPS 封面、B 列为具体 GitHub 仓库的行。其他 Sheet 不参与导入;K 列图片公式不会执行。原始 A~H 数据列与表头存在错位,工具按实际位置读取,忽略 H 列的无意义备注 `100`,不将“待查”等信息改写成已确认。
外部封面保留原 URL 和 GIF,不转存 OSS;当前环境的平台封面统一转换为相对路径。描述由原中文简介和技术资料组合,不调用 AI。轮式、四足、人形分别映射对应类型,机械臂映射 ROBOTIC_ARM,其他和硬件映射 GENERAL,原始分类保留在描述里。
脚本加载本项目 `.env`,依赖 Java 21、Maven,以及正式执行时可用的 MySQL 和 Gitea。独立导入模块不启动 Web 服务,也不加载登录或 AI。资源地址转换无需 OSS 凭据;README 图片转存按需初始化 OSS 客户端,未配置凭据时保留原链并产生告警。test/prod 根目录与在线应用一致,历史公开地址使用 `OSS_LEGACY_PUBLIC_BASE_URLS`。Gitea 技术账号需具备组织所有者及仓库写权限,实例需开启迁移、HTTP Git 和 LFS。`GITHUB_TOKEN` 可选,仅用于 GitHub 元数据 API;API 限流时读取同一公开仓库的 GitHub 网页,交叉核验仓库 ID、规范地址、公开状态和默认分支,缺失或不一致则预检失败。网页和图片请求均不携带凭据。`GITEA_TOKEN` 仅访问配置的 Gitea,不能代替 `GITHUB_TOKEN`;切勿把 Token 放进 URL 或命令参数。
```bash
IMPORT_EXCEL='/绝对路径/项目.xlsx'
# 仅验证静态筛选,不访问网络、业务库或 Gitea。
bash scripts/import-github-projects.sh --excel "$IMPORT_EXCEL" --offline
# 默认 dry-run:在线检查仓库和图片,并生成清单;不写业务库或 Gitea。
bash scripts/import-github-projects.sh --excel "$IMPORT_EXCEL" --dry-run
# 先试导前三个尚未完成的候选。必须使用已有有效用户的 userCode。
bash scripts/import-github-projects.sh --excel "$IMPORT_EXCEL" --execute --owner-user-code '<用户编码>' --limit 3
# 试导检查通过后,用相同状态目录续跑其余项目。
bash scripts/import-github-projects.sh --excel "$IMPORT_EXCEL" --execute --owner-user-code '<用户编码>'
```
`--owner-email` 可替代 `--owner-user-code` 查找已有账号,二者互斥,工具不会创建用户;状态中始终保存查到的用户编码。`--state-dir` 默认 `logs/github-import`,包含原子写入的 `manifest.json` 和 `report.json`;此目录必须保留并备份,不能在迁移进行中删除。清单绑定 Excel 指纹、归属用户和 Gitea 目标,不能复用于另一文件或环境。同一目录有进程锁,`--concurrency` 默认为 2,可选 1~4;同一批次只运行一个进程。`--limit` 限制尚未完成候选的处理数量;已完成项目、迁移结果未知或不具备收据核对条件的 REVIEW 项目不计入。
导入清单和报告通过 `timeZone` 声明 `Asia/Shanghai`。旧版未声明时区的清单首次由新版读取时,会将 `reservedAt` 从 UTC 转为上海时间并原子保存,之后续跑不会重复转换;应先完成业务库历史时间迁移,并备份状态目录后再使用新版续跑。
工具先创建 CREATING 项目记录,直接调用 Gitea `/repos/migrate`,不先创建空仓库。迁移使用私有普通仓库、开启 LFS,保留 Git 内容、历史、分支和标签;不迁移工单、PR、Wiki 或 Release 附件。迁移成功收据先落盘,再关联项目并自动发布。独立迁移请求默认超时 1800 秒,可用 `--migration-timeout-seconds` 调整,普通 Gitea 请求超时不变。原默认分支不是 main 时补建 main 并设为默认,保留原分支;同名 main 内容冲突时停止该项目,不覆盖源分支或已冻结版本。
进程在 MIGRATING 阶段中断,或迁移超时、结果不明确时,项目进入 REVIEW,禁止自动重发或仅凭仓库存在判定成功。需要核对 Gitea 迁移及 LFS 完成情况、来源和提交后由维护人员处理;不要直接把 REVIEW 改为 READY 或删除仓库再重跑。已确认的迁移收据会用于数据库回写或发布失败后的续跑,避免重复迁移。对于已持久化成功收据、仅在主分支适配时出现不明写入结果的项目,续跑先只读核对仓库身份、来源、私有属性、默认分支和两条分支的冻结 SHA;全部一致才继续关联和发布,否则保持 REVIEW,不重发分支写入。已完成项目不会因后续人工撤回、修改或删除而被批次重新发布。
报告逐项包含 Sheet、行号、短编码、阶段、错误码和兼容性提醒。退出码 0 表示本次选定工作完成,1 表示命令、配置或持久化等致命错误,2 表示存在预检未通过、失败或待核对项目。在线仓库或图片失效会减少实际导入量;报告中的候选数仍与静态筛选对账。
本次只完成仓库迁移、关联和发布。在线浏览和下载仍有单文件限制,LFS 实体、子模块及符号链接的在线浏览能力未扩展;Git 快照 Fork 已支持大文件、LFS 实体、符号链接及子模块引用,依赖仓库仍不递归复制。当前发布快照检测到的限制会写入报告。子模块只保留引用,不递归迁移独立仓库,也不下载网盘或其他外链资源。保留所有分支不代表社区提供分支切换界面。
## 管理端
独立端口默认 `8994`,共用现有 `sys_user`,通过 `USER/ADMIN/OFFICIAL` 角色鉴权,不新增管理员或会话表。后台管理员以邮箱和 BCrypt 密码登录;会话使用 Redis,默认 8 小时,应用重启后保留未过期会话。社区端和后台各单实例,使用不同 Redis Key 域,Token 不互通。
启用前先手工执行 [管理端 SQL](docs/admin-database.md),停止并排空旧写入进程,更新社区端、后台和 Excel 导入工具,最后启用后台。全部仓库写入端使用相同数据库的项目命名锁;不可让仍使用本地锁的旧版应用并行写入。
```bash
bash scripts/run-admin-local.sh
# 将一个已有普通用户初始化为管理员,交互输入密码,不传明文密码参数。
bash scripts/run-admin-local.sh --bootstrap-admin-user-code='<已有用户编码>'
# 真实 MySQL 验证:创建并删除随机临时库,不改现有业务数据。
bash scripts/test-admin-mysql.sh
```
前端对接见 [管理后台接口文档](docs/admin-api.md),服务初始化、配置与故障处理见 [管理端部署说明](docs/admin-deployment.md)。数据库 SQL 不会由启动脚本自动执行;真实仓库迁移和正式发布需在部署后由管理员通过接口触发,普通测试不会访问真实 GitHub、Gitea 或 OSS。
## Redis、安全限制与批量查询
在线应用依赖 Redis 8.10.2,使用 Spring Data Redis/Lettuce。配置 `REDIS_HOST`、`REDIS_PORT`(6379)、`REDIS_USERNAME`(可选)、`REDIS_PASSWORD`、`REDIS_DATABASE`(0)、`REDIS_SSL_ENABLED`(false);连接/命令超时默认 2s/1s。prod 必须显式提供 Redis 主机、密码及 `GITEA_ORGANIZATION`,与数据库、Gitea 凭据一样只由环境注入。
环境 Key 前缀默认 `vibemake:test` / `vibemake:prod`,可用 `REDIS_KEY_PREFIX` 覆盖;后续自动追加 `api:v1:` / `admin:v1:`。会话 Key 使用 Token 的 SHA-256 摘要;会话 JSON 仅包含用户标识和会话版本。社区和后台 TTL 分别为 24h/8h,不滑动续期,验证码 2m 且一次消费。每次请求仍检查数据库账号状态、角色、会话版本。Redis 故障返回 503 `REDIS_UNAVAILABLE`,不回退本机或放行。离线导入和管理员初始化命令不检查 Redis。
全部默认限额、变量、ACL 与发布操作见 [部署说明](docs/admin-deployment.md#redis-安全与资源保护)。Fork 为每用户 10 次/分钟、URDF 批次签名 20 次/分钟;Fork 同时执行仍最多 2 个。请求频率统计的是尝试次数,包括繁忙或失败的调用,按首次请求建立 60 秒固定窗口;窗口内各操作独立,换 Token 或 IP 不重置用户额度。限流只计一次业务调用,AI 创建/Fork 共用业务入口。
项目响应采用数据库批量查询,不缓存业务列表。列表和 AI 检索不读取体积较大的 URDF 文件清单,Fork 来源仅批量读取标识和编码。按业务服务层统计(不包含安全过滤器独立账号查询),20 条带 Fork 来源、登录用户点赞和导入来源的项目列表最多 8 次 SQL,评论列表最多 4 次,后台用户列表最多 3 次;避免记录数增加造成逐条查询。昵称、互动和下架可见性仍读取当前数据。
普通 `AI_ENABLED=false OSS_ENABLED=false mvn verify` 使用只存在于 tests 分类制品中的状态存储,不依赖 Redis,生产 jar 不包含该实现。真实 Redis 联调不自动读取 `.env`,通过 `REDIS_TEST_HOST`、`REDIS_TEST_PORT`、`REDIS_TEST_USERNAME`、`REDIS_TEST_PASSWORD`、`REDIS_TEST_DATABASE`、`REDIS_TEST_SSL_ENABLED` 连接独立测试实例,执行 `bash scripts/test-redis.sh`;只使用随机测试 Key 前缀,不执行 FLUSHDB。真实联调验证 TTL、消费竞争、计数、断开后重建连接、会话撤销与账号禁用。
## HTTPS Git 网关
网站身份可通过项目独立凭据 clone、fetch、pull、push main,支持 LFS Basic Transfer;社区仍手动发布。默认关闭,普通用户无需 Gitea 账号。先执行 [Git 凭据建表 SQL](docs/database.md#项目-git-凭据) 和 [写入记录扩展 SQL](docs/admin-database.md#https-git-写入记录扩展),同时部署社区端和管理端兼容版本,再设置 `GIT_ENABLED=true`。应用不自动迁库,本次不修改 `.sql` 文件。
| 环境变量 | 默认值/含义 |
| --- | --- |
| GIT_ENABLED | false |
| GIT_PUBLIC_BASE_URL | 必填的固定公网 HTTPS 地址,例如 `https://git.example.com/git`,不根据 Host 构造 |
| GIT_UPSTREAM_USERNAME / GIT_UPSTREAM_TOKEN | 独立非管理员、非组织所有者技术账号及其 PAT;需要 read:user、write:repository 范围,与仓库管理 GITEA_TOKEN 分离 |
| GIT_REQUEST_TIMEOUT | 10m,覆盖请求及响应流 |
| GIT_MAX_PACK_BYTES / GIT_MAX_LFS_OBJECT_BYTES | 5368709120 / 1073741824 |
| GIT_MAX_METADATA_BYTES / GIT_MAX_BATCH_OBJECTS | 8388608 / 500 |
| GIT_READ_CONCURRENT / GIT_PUSH_CONCURRENT / GIT_LFS_CONCURRENT | 4 / 2 / 8,单实例 |
| GIT_REQUESTS_PER_MINUTE / GIT_LFS_REQUESTS_PER_MINUTE | 120 / 600,每用户 |
| GIT_AUTH_FAILURES_PER_MINUTE | 20,每IP;仅信任已配置代理 |
技术账号不能是仓库管理员;首次签发项目 Token 时后端管理凭据会给它授予该仓库 write 权限。首个读写 Token 初始化 main 保护,已有规则必须兼容;每次 push 重新核验,非快进和删除由 Gitea 接收钩子拒绝。仓库主存储、对象完整性和 LFS 保留在 Gitea。部署必须确保 Git/LFS 原生端点直接响应,无重定向、且上游 LFS action 使用配置的 Gitea origin 和本项目路径;不支持外部对象存储 action 直链。
代理 `/git/` 关闭请求/响应缓冲、缓存,透传 Authorization、Git-Protocol、Content-Type、Accept、Content-Encoding;请求大小允许 pack/LFS 额度,代理与 Gitea 超时至少覆盖10分钟预算,默认读取超时不低于660秒。服务端不得记录认证头或 action Bearer。使用 HTTPS 对外开放;本机真实联调才允许回环 HTTP。保持当前社区端、管理端各单实例部署范围。
前端对接见 [HTTPS Git 与本地开发](docs/vibemake-api.md#https-git-与本地开发),运维恢复与回滚见 [Git 网关运维](docs/admin-deployment.md#https-git-网关运维)。Git Token 继承现有网页登录身份边界:邮箱加图片验证码目前不验证邮箱归属。
验证:`AI_ENABLED=false VIBEMAKE_AI_ENABLED=false OSS_ENABLED=false mvn verify`。`python3 scripts/test-git-gateway.py` 读取 `.env`,在随机测试仓库及临时技术账号上运行真实 Git/Gitea/LFS(含大于50 MiB对象)闭环,测试完成后清理;需要 GITEA_TOKEN 具备创建/删除测试用户权限,以及可连接的 Redis(只使用随机 git-live 前缀)。配置 DB_URL 时还会创建随机 `vibemake_git_verify_*` 临时 MySQL 库,需建库权限;`GIT_GATEWAY_MYSQL=false` 可单独使用 H2 验证 Git/Redis。MySQL 锁测试只创建随机临时库,Redis 测试使用独立随机前缀,均不修改已有业务数据。