From 61c60f80529fbb9366f975dac9dd958ece6eb17e Mon Sep 17 00:00:00 2001 From: lxp <2770281812@qq.com> Date: Fri, 16 Oct 2026 15:02:26 +0800 Subject: [PATCH] =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E6=96=B0=E5=A2=9EURDF?= =?UTF-8?q?=E5=AD=97=E6=AE=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 6 +- README.md | 7 +- .../api/controller/UrdfController.java | 52 +++++ .../src/main/resources/application.yml | 4 + .../community/api/FakeOssObjectStore.java | 44 ++++ .../community/api/SchemaSupport.java | 3 + .../linkerbot/community/api/WorkflowTest.java | 199 ++++++++++++++++++ .../linkerbot/community/bean/Contracts.java | 21 ++ .../community/bean/entity/Project.java | 3 + .../importer/ImportCoordinatorTest.java | 2 + community-service/pom.xml | 11 + .../community/service/UrdfService.java | 14 ++ .../service/config/OssProperties.java | 2 +- .../service/config/UrdfProperties.java | 19 ++ .../service/impl/ProjectServiceImpl.java | 16 +- .../service/impl/UrdfServiceImpl.java | 81 +++++++ .../service/oss/AliyunOssObjectStore.java | 94 +++++++++ .../community/service/oss/OssObjectStore.java | 10 + .../community/service/oss/OssPostSigner.java | 40 +++- .../community/service/oss/UrdfResources.java | 179 ++++++++++++++++ .../service/ProjectCodeAllocationTest.java | 5 +- .../service/oss/AliyunOssObjectStoreTest.java | 88 ++++++++ .../service/oss/OssPostSignerTest.java | 19 ++ .../service/oss/UrdfResourcesTest.java | 73 +++++++ docs/community-api.md | 137 ++++++++++++ docs/database.md | 25 ++- 26 files changed, 1136 insertions(+), 18 deletions(-) create mode 100644 community-api/src/main/java/com/linkerbot/community/api/controller/UrdfController.java create mode 100644 community-api/src/test/java/com/linkerbot/community/api/FakeOssObjectStore.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/UrdfService.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/config/UrdfProperties.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/impl/UrdfServiceImpl.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/oss/AliyunOssObjectStore.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/oss/OssObjectStore.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/oss/UrdfResources.java create mode 100644 community-service/src/test/java/com/linkerbot/community/service/oss/AliyunOssObjectStoreTest.java create mode 100644 community-service/src/test/java/com/linkerbot/community/service/oss/UrdfResourcesTest.java diff --git a/.env.example b/.env.example index 422867d..dbcbaaf 100644 --- a/.env.example +++ b/.env.example @@ -12,7 +12,7 @@ SPRING_PROFILES_ACTIVE=test # 与 cadworld 一致,默认日志目录为 logs,可改为部署环境中的绝对路径。 LOG_PATH=logs PORT=8993 -# OSS 封面直传默认关闭;地域 ID 不带 oss- 前缀,例如 cn-beijing。 +# OSS 封面和 URDF 直传默认关闭;地域 ID 不带 oss- 前缀,例如 cn-beijing。 # 目录由 profile 固定:test 为 vibemake_dev/,prod 为 vibemake/。 OSS_ENABLED=false OSS_REGION=cn-beijing @@ -21,6 +21,10 @@ OSS_ACCESS_KEY_ID='' OSS_ACCESS_KEY_SECRET='' # 可选,固定公开 CDN/OSS 基础地址;留空使用 Bucket 的标准 HTTPS 域名。 OSS_PUBLIC_BASE_URL='' +# URDF 直传限制:单文件 50 MiB、整包 200 MiB、最多 500 个文件,不受仓库 multipart 限制影响。 +URDF_MAX_FILE_BYTES=52428800 +URDF_MAX_TOTAL_BYTES=209715200 +URDF_MAX_FILES=500 # AI 默认关闭;启用后密钥仅在后端使用。两个环境均支持这些变量。 AI_ENABLED=false ARK_API_KEY='' diff --git a/README.md b/README.md index 8bdfd83..39f3e5e 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Spring Boot 社区后端,工程分层参考 cadworld。使用 Java 21、Spring | community-common | 通用响应、分页、异常处理、requestId 和基础工具 | | community-import | 固定 Excel 的 GitHub 项目运维导入命令,不提供 HTTP 接口 | -UserService、ProjectService、FileService、InteractionService、CoverUploadService 采用接口加实现类,Controller、安全模块和服务之间通过接口注入。GiteaClient 与 RestGiteaClient 定义仓库调用边界;项目锁、UTC 时间和分页检查归入 support。安全模块内的 TokenService、CaptchaService 保留具体类,首期沿用本机缓存。 +UserService、ProjectService、FileService、InteractionService、CoverUploadService、UrdfService 采用接口加实现类,Controller、安全模块和服务之间通过接口注入。GiteaClient 与 RestGiteaClient 定义仓库调用边界;项目锁、UTC 时间和分页检查归入 support。安全模块内的 TokenService、CaptchaService 保留具体类,首期沿用本机缓存。 ## 功能与边界 @@ -27,7 +27,7 @@ UserService、ProjectService、FileService、InteractionService、CoverUploadSer ## 启动 -1. 安装 Java 21、Maven 3.9+,准备 MySQL 8 和现有 Gitea。 +1. 安装 Java 21、Maven 3.9+,准备 MySQL 8.0.13 及以上和现有 Gitea。 2. 手动执行 [四表建表 SQL](docs/database.md),应用不会自动建表或修改数据库。 3. 在 Gitea 创建私有组织,将技术账号设为组织所有者,生成具有 write:repository、write:organization、read:user 权限的 Token。 4. 将 .env.example 复制为 .env,填写数据库连接与 Gitea 地址、组织、Token;默认使用 test 环境,.env 被 Git 忽略,不提交真实凭据。 @@ -54,6 +54,7 @@ prod 启动时检查数据库连接、用户名、密码、Gitea 地址和 Token | 数据库 | 默认本机 community,可用 DB_* 覆盖 | 必须配置 DB_URL、DB_USERNAME、DB_PASSWORD | | Gitea | 默认本机地址,使用 GITEA_* 覆盖 | 必须配置 GITEA_BASE_URL、GITEA_TOKEN;组织默认 community | | OSS 封面目录 | vibemake_dev/project-covers/ | vibemake/project-covers/ | +| OSS URDF 目录 | vibemake_dev/urdf/{projectCode}/{batchCode}/ | vibemake/urdf/{projectCode}/{batchCode}/ | | 连接池 | 最少 1、最多 10 个连接 | 最少 1、最多 20 个连接 | | 项目日志级别 | DEBUG | INFO | | 日志目录 | logs,可用 LOG_PATH 覆盖 | logs,可用 LOG_PATH 覆盖 | @@ -76,7 +77,7 @@ SPRING_PROFILES_ACTIVE=prod java -Djava.awt.headless=true -jar community-api/tar mvn clean verify ``` -普通测试固定使用 test 配置,覆盖连接为临时 H2 MySQL 模式及模拟 Gitea/AI,验证登录、权限、提交冲突、发布快照、Fork、评论、点赞,以及 AI 筛选、引用校验、创建、Fork 与候选选择、SSE、限流、超时和取消,不访问真实数据库、仓库或模型。未加载外部服务凭据时,执行 `AI_ENABLED=false OSS_ENABLED=false mvn test`;AI 流程测试自行启用模拟模型。完整安装验证可执行 `AI_ENABLED=false OSS_ENABLED=false mvn clean install`。 +普通测试固定使用 test 配置,覆盖连接为临时 H2 MySQL 模式及模拟 Gitea/AI/OSS,验证登录、权限、提交冲突、发布快照、Fork、评论、点赞、URDF 直传核验和独立复制,以及 AI 筛选、引用校验、创建、Fork 与候选选择、SSE、限流、超时和取消,不访问真实数据库、仓库、对象存储或模型。未加载外部服务凭据时,执行 `AI_ENABLED=false OSS_ENABLED=false mvn test`;AI 流程测试自行启用模拟模型。完整安装验证可执行 `AI_ENABLED=false OSS_ENABLED=false mvn clean install`。 真实 Gitea 联调: diff --git a/community-api/src/main/java/com/linkerbot/community/api/controller/UrdfController.java b/community-api/src/main/java/com/linkerbot/community/api/controller/UrdfController.java new file mode 100644 index 0000000..d2c2704 --- /dev/null +++ b/community-api/src/main/java/com/linkerbot/community/api/controller/UrdfController.java @@ -0,0 +1,52 @@ +package com.linkerbot.community.api.controller; + +import com.linkerbot.community.bean.Contracts.ProjectView; +import com.linkerbot.community.bean.Contracts.UrdfConfirmInput; +import com.linkerbot.community.bean.Contracts.UrdfUploadInput; +import com.linkerbot.community.bean.Contracts.UrdfUploadSignature; +import com.linkerbot.community.common.ApiResponse; +import com.linkerbot.community.security.CurrentUser; +import com.linkerbot.community.service.UrdfService; +import io.swagger.v3.oas.annotations.Operation; +import io.swagger.v3.oas.annotations.tags.Tag; +import jakarta.validation.Valid; +import lombok.RequiredArgsConstructor; +import org.springframework.http.CacheControl; +import org.springframework.http.ResponseEntity; +import org.springframework.web.bind.annotation.DeleteMapping; +import org.springframework.web.bind.annotation.PathVariable; +import org.springframework.web.bind.annotation.PostMapping; +import org.springframework.web.bind.annotation.PutMapping; +import org.springframework.web.bind.annotation.RequestBody; +import org.springframework.web.bind.annotation.RequestMapping; +import org.springframework.web.bind.annotation.RestController; + +@RestController +@RequiredArgsConstructor +@RequestMapping("/api/workspace/projects/{projectCode}/urdf") +@Tag(name = "项目 URDF") +public class UrdfController { + private final UrdfService urdf; + + @PostMapping("/signature") + @Operation(summary = "生成 URDF 文件夹 OSS 直传签名,自动识别唯一主文件") + public ResponseEntity> signature( + @PathVariable String projectCode, @Valid @RequestBody UrdfUploadInput input) { + return ResponseEntity.ok().cacheControl(CacheControl.noStore()) + .body(ApiResponse.success(urdf.signature(CurrentUser.required(), projectCode, input))); + } + + @PutMapping + @Operation(summary = "核验并绑定项目 URDF 资源包") + public ApiResponse confirm( + @PathVariable String projectCode, @Valid @RequestBody UrdfConfirmInput input) { + return ApiResponse.success(urdf.confirm(CurrentUser.required(), projectCode, input)); + } + + @DeleteMapping + @Operation(summary = "清除项目 URDF 绑定,保留 OSS 对象") + public ApiResponse clear(@PathVariable String projectCode) { + urdf.clear(CurrentUser.required(), projectCode); + return ApiResponse.success(null); + } +} diff --git a/community-api/src/main/resources/application.yml b/community-api/src/main/resources/application.yml index 6ffb99d..8f2a122 100644 --- a/community-api/src/main/resources/application.yml +++ b/community-api/src/main/resources/application.yml @@ -27,6 +27,10 @@ community: access-key-id: ${OSS_ACCESS_KEY_ID:} access-key-secret: ${OSS_ACCESS_KEY_SECRET:} public-base-url: ${OSS_PUBLIC_BASE_URL:https://linkerbot.oss-cn-beijing.aliyuncs.com} + urdf: + max-file-bytes: ${URDF_MAX_FILE_BYTES:52428800} + max-total-bytes: ${URDF_MAX_TOTAL_BYTES:209715200} + max-files: ${URDF_MAX_FILES:500} ai: enabled: ${AI_ENABLED:true} api-key: ${ARK_API_KEY:} diff --git a/community-api/src/test/java/com/linkerbot/community/api/FakeOssObjectStore.java b/community-api/src/test/java/com/linkerbot/community/api/FakeOssObjectStore.java new file mode 100644 index 0000000..b2bb739 --- /dev/null +++ b/community-api/src/test/java/com/linkerbot/community/api/FakeOssObjectStore.java @@ -0,0 +1,44 @@ +package com.linkerbot.community.api; + +import com.linkerbot.community.common.BusinessException; +import com.linkerbot.community.service.oss.OssObjectStore; +import java.util.Arrays; +import java.util.Map; +import java.util.concurrent.ConcurrentHashMap; + +final class FakeOssObjectStore implements OssObjectStore { + final Map objects = new ConcurrentHashMap<>(); + boolean failNextCopy; + Runnable afterHead; + + void reset() { + objects.clear(); + failNextCopy = false; + afterHead = null; + } + + @Override + public Metadata head(String objectKey) { + byte[] bytes = objects.get(objectKey); + if (bytes == null) + throw new BusinessException(400, "URDF_FILE_MISSING", "URDF 文件未上传完整,请重新上传"); + Metadata metadata = new Metadata(bytes.length, Integer.toHexString(Arrays.hashCode(bytes))); + if (afterHead != null) { + Runnable action = afterHead; + afterHead = null; + action.run(); + } + return metadata; + } + + @Override + public void copy(String sourceKey, String targetKey, String sourceEtag) { + if (failNextCopy) { + failNextCopy = false; + throw new BusinessException(502, "OSS_ERROR", "OSS 资源访问失败,请稍后重试"); + } + byte[] bytes = objects.get(sourceKey); + if (!head(sourceKey).etag().equals(sourceEtag)) throw BusinessException.conflict("源文件发生变化"); + objects.put(targetKey, bytes.clone()); + } +} diff --git a/community-api/src/test/java/com/linkerbot/community/api/SchemaSupport.java b/community-api/src/test/java/com/linkerbot/community/api/SchemaSupport.java index d123b50..5f8b35d 100644 --- a/community-api/src/test/java/com/linkerbot/community/api/SchemaSupport.java +++ b/community-api/src/test/java/com/linkerbot/community/api/SchemaSupport.java @@ -18,6 +18,9 @@ final class SchemaSupport { while (matcher.find()) { String ddl = matcher.group() + // H2 的 JSON 字符串绑定与 MySQL 不同,测试以文本列承接服务层 JSON。 + .replace("JSON NOT NULL DEFAULT (JSON_ARRAY())", "CLOB NOT NULL DEFAULT '[]'") + .replace(" CHARACTER SET utf8mb4 COLLATE utf8mb4_bin", "") .replaceAll(" COMMENT '[^']*'", "") .replaceAll("\\) ENGINE=InnoDB[^;]*;", ");"); jdbc.execute(ddl); diff --git a/community-api/src/test/java/com/linkerbot/community/api/WorkflowTest.java b/community-api/src/test/java/com/linkerbot/community/api/WorkflowTest.java index 173c5c4..bf0c27d 100644 --- a/community-api/src/test/java/com/linkerbot/community/api/WorkflowTest.java +++ b/community-api/src/test/java/com/linkerbot/community/api/WorkflowTest.java @@ -9,6 +9,7 @@ import com.fasterxml.jackson.databind.ObjectMapper; import com.linkerbot.community.security.CaptchaService; import com.linkerbot.community.service.config.CommunityProperties; import com.linkerbot.community.service.config.OssProperties; +import com.linkerbot.community.service.config.UrdfProperties; import org.junit.jupiter.api.*; import org.springframework.beans.factory.annotation.Autowired; @@ -41,6 +42,10 @@ import java.util.concurrent.*; class WorkflowTest { @TestConfiguration static class Config { + @Bean + @Primary + FakeOssObjectStore fakeOss() { return new FakeOssObjectStore(); } + @Bean @Primary FakeGiteaClient fakeGitea() { @@ -64,12 +69,18 @@ class WorkflowTest { @Autowired JdbcTemplate jdbc; @Autowired FakeGiteaClient gitea; @Autowired OssProperties oss; + @Autowired FakeOssObjectStore ossObjects; + @Autowired UrdfProperties urdfLimits; @BeforeEach void reset() throws Exception { SchemaSupport.reset(jdbc); gitea.reset(); oss.setEnabled(false); + ossObjects.reset(); + urdfLimits.setMaxFileBytes(52428800); + urdfLimits.setMaxTotalBytes(209715200); + urdfLimits.setMaxFiles(500); } private JsonNode perform(MockHttpServletRequestBuilder builder, int status) throws Exception { @@ -292,6 +303,194 @@ class WorkflowTest { .path("data").path("coverUrl").asText()).isEqualTo(max); } + private void enableUrdfOss() { + oss.setRegion("cn-hangzhou"); + oss.setEndpoint(""); + oss.setBucket("examplebucket"); + oss.setAccessKeyId("UnitTestAccessKey"); + oss.setAccessKeySecret("unit-test-secret"); + oss.setPublicBaseUrl("https://images.example.com/assets/"); + oss.setEnabled(true); + } + + private List> urdfFiles() { + return List.of(Map.of("relativePath", "urdf/机械 臂.URDF", "sizeBytes", 12), + Map.of("relativePath", "meshes/底盘.stl", "sizeBytes", 24), + Map.of("relativePath", "textures/a #?.png", "sizeBytes", 8)); + } + + private JsonNode uploadUrdf(String token, String code, List> files) throws Exception { + JsonNode signature = perform(body(auth(post("/api/workspace/projects/" + code + "/urdf/signature"), token), + Map.of("files", files)), 200).path("data"); + for (int index = 0; index < files.size(); index++) + ossObjects.objects.put(signature.path("files").get(index).path("objectKey").asText(), + new byte[((Number) files.get(index).get("sizeBytes")).intValue()]); + return signature; + } + + private JsonNode confirmUrdf(String token, String code, JsonNode signature, + List> files, int status) throws Exception { + return perform(body(auth(put("/api/workspace/projects/" + code + "/urdf"), token), + Map.of("batchCode", signature.path("batchCode").asText(), "files", files)), status); + } + + @Test + void urdfSignaturesAndConfirmationRejectMissingMultipleAndInvalidPaths() throws Exception { + String owner = login("urdf-validation@example.com"); + String other = login("urdf-stranger@example.com"); + String code = create(owner, "URDF 校验"); + String endpoint = "/api/workspace/projects/" + code + "/urdf"; + Map good = Map.of("files", urdfFiles()); + perform(body(post(endpoint + "/signature"), good), 401); + perform(body(auth(post(endpoint + "/signature"), owner), good), 503); + enableUrdfOss(); + perform(body(auth(post(endpoint + "/signature"), other), good), 404); + perform(body(auth(put(endpoint), other), Map.of("batchCode", "a".repeat(32), "files", urdfFiles())), 404); + perform(auth(delete(endpoint), other), 404); + List>> invalidCounts = List.of(List.of(), + List.of(Map.of("relativePath", "meshes/a.stl", "sizeBytes", 1)), + List.of(Map.of("relativePath", "a.urdf", "sizeBytes", 1), + Map.of("relativePath", "models/b.URDF", "sizeBytes", 1))); + for (int index = 0; index < invalidCounts.size(); index++) { + List> files = invalidCounts.get(index); + String message = index < 2 ? "文件夹中未找到 URDF 文件" + : "文件夹中存在多个 URDF 文件,请仅保留一个后重新上传"; + assertThat(perform(body(auth(post(endpoint + "/signature"), owner), Map.of("files", files)), 400) + .path("message").asText()).isEqualTo(message); + assertThat(perform(body(auth(put(endpoint), owner), + Map.of("batchCode", "a".repeat(32), "files", files)), 400) + .path("message").asText()).isEqualTo(message); + } + for (String path : List.of("../a.urdf", "/a.urdf", "a\\b.urdf", "a//b.urdf", "a/./b.urdf", + "a\u0000.urdf", "a".repeat(512) + ".urdf", "中".repeat(340) + ".urdf")) { + Map input = Map.of("files", List.of(Map.of("relativePath", path, "sizeBytes", 1))); + perform(body(auth(post(endpoint + "/signature"), owner), input), 400); + } + for (Object files : List.of( + List.of(Map.of("relativePath", "a.urdf", "sizeBytes", 1), Map.of("relativePath", "a.urdf", "sizeBytes", 1)), + List.of(Map.of("relativePath", "a.urdf", "sizeBytes", -1)), + List.of(Map.of("relativePath", "a.urdf")))) + perform(body(auth(post(endpoint + "/signature"), owner), Map.of("files", files)), 400); + perform(body(auth(put(endpoint), owner), Map.of("batchCode", "../another", "files", urdfFiles())), 400); + perform(body(auth(post(endpoint + "/signature"), owner), Map.of("files", + List.of(Map.of("relativePath", "a.urdf", "sizeBytes", 52428801)))), 413); + urdfLimits.setMaxTotalBytes(20); + perform(body(auth(post(endpoint + "/signature"), owner), good), 413); + urdfLimits.setMaxTotalBytes(209715200); + urdfLimits.setMaxFiles(2); + perform(body(auth(post(endpoint + "/signature"), owner), good), 413); + assertThat(jdbc.queryForObject("SELECT urdf_prefix FROM project WHERE project_code = ?", String.class, code)).isEmpty(); + assertThat(ossObjects.objects).isEmpty(); + } + + @Test + void urdfUploadReplacesClearsAndUpdatesCommunityWithoutChangingRepository() throws Exception { + String owner = login("urdf-owner@example.com"); + String code = create(owner, "URDF 项目"); + String path = "/api/workspace/projects/" + code; + JsonNode initial = perform(auth(get(path), owner), 200).path("data"); + assertThat(initial.path("urdfMainUrl").isNull()).isTrue(); + assertThat(initial.path("urdfBaseUrl").isNull()).isTrue(); + String sha = head(owner, code); + publish(owner, code, sha); + enableUrdfOss(); + List> files = urdfFiles(); + JsonNode signature = uploadUrdf(owner, code, files); + assertThat(signature.path("mainRelativePath").asText()).isEqualTo("urdf/机械 臂.URDF"); + assertThat(signature.path("uploadUrl").asText()).isEqualTo("https://examplebucket.oss-cn-hangzhou.aliyuncs.com"); + assertThat(signature.toString()).doesNotContain("unit-test-secret"); + assertThat(signature.has("id")).isFalse(); + assertThat(perform(auth(get(path), owner), 200).path("data").path("urdfMainUrl").isNull()).isTrue(); + String expectedPrefix = "vibemake_dev/urdf/" + code + "/" + signature.path("batchCode").asText() + "/"; + JsonNode bound = confirmUrdf(owner, code, signature, files, 200).path("data"); + String baseUrl = "https://images.example.com/assets/" + expectedPrefix; + assertThat(bound.path("urdfBaseUrl").asText()).isEqualTo(baseUrl); + assertThat(bound.path("urdfMainUrl").asText()).isEqualTo(baseUrl + "urdf/%E6%9C%BA%E6%A2%B0%20%E8%87%82.URDF"); + assertThat(bound.has("id")).isFalse(); + assertThat(jdbc.queryForObject("SELECT urdf_main_object_key FROM project WHERE project_code = ?", String.class, code)) + .isEqualTo(expectedPrefix + "urdf/机械 臂.URDF"); + assertThat(json.readTree(jdbc.queryForObject("SELECT urdf_files FROM project WHERE project_code = ?", String.class, code))) + .isEqualTo(json.valueToTree(files)); + assertThat(perform(get("/api/community/projects/" + code), 200).path("data").path("urdfMainUrl")).isEqualTo(bound.path("urdfMainUrl")); + JsonNode replacement = uploadUrdf(owner, code, files); + JsonNode next = confirmUrdf(owner, code, replacement, files, 200).path("data"); + assertThat(next.path("urdfMainUrl")).isNotEqualTo(bound.path("urdfMainUrl")); + assertThat(perform(get("/api/community/projects/" + code), 200).path("data").path("urdfMainUrl")).isEqualTo(next.path("urdfMainUrl")); + assertThat(head(owner, code)).isEqualTo(sha); + oss.setEnabled(false); // 清除绑定无需 OSS 可用。 + perform(auth(delete(path + "/urdf"), owner), 200); + JsonNode cleared = perform(get("/api/community/projects/" + code), 200).path("data"); + assertThat(cleared.path("urdfMainUrl").isNull()).isTrue(); + assertThat(cleared.path("urdfBaseUrl").isNull()).isTrue(); + assertThat(jdbc.queryForMap("SELECT urdf_main_object_key, urdf_prefix, urdf_files FROM project WHERE project_code = ?", code)) + .containsEntry("URDF_MAIN_OBJECT_KEY", "").containsEntry("URDF_PREFIX", ""); + assertThat(jdbc.queryForObject("SELECT urdf_files FROM project WHERE project_code = ?", String.class, code)).isEqualTo("[]"); + assertThat(ossObjects.objects).hasSize(6); + JsonNode spec = perform(get("/v3/api-docs"), 200); + assertThat(spec.path("paths").has("/api/workspace/projects/{projectCode}/urdf/signature")).isTrue(); + } + + @Test + void urdfMissingMismatchedOrInvalidConfirmationPreservesPreviousBinding() throws Exception { + String owner = login("urdf-failure@example.com"); + String code = create(owner, "URDF 失败保护"); + enableUrdfOss(); + List> files = urdfFiles(); + JsonNode first = uploadUrdf(owner, code, files); + JsonNode current = confirmUrdf(owner, code, first, files, 200).path("data"); + JsonNode next = uploadUrdf(owner, code, files); + String missingKey = next.path("files").get(1).path("objectKey").asText(); + ossObjects.objects.remove(missingKey); + assertThat(confirmUrdf(owner, code, next, files, 400).path("code").asText()).isEqualTo("URDF_FILE_MISSING"); + ossObjects.objects.put(missingKey, new byte[23]); + assertThat(confirmUrdf(owner, code, next, files, 400).path("code").asText()).isEqualTo("URDF_FILE_SIZE_MISMATCH"); + assertThat(confirmUrdf(owner, code, next, List.of(files.get(1)), 400).path("code").asText()).isEqualTo("URDF_MAIN_FILE_INVALID"); + assertThat(perform(auth(get("/api/workspace/projects/" + code), owner), 200).path("data").path("urdfMainUrl")) + .isEqualTo(current.path("urdfMainUrl")); + // 模拟核验期间项目被删除,落库前必须重新校验。 + ossObjects.objects.put(missingKey, new byte[24]); + ossObjects.afterHead = () -> jdbc.update("UPDATE project SET deleted = 1 WHERE project_code = ?", code); + confirmUrdf(owner, code, next, files, 404); + assertThat(jdbc.queryForObject("SELECT urdf_prefix FROM project WHERE project_code = ?", String.class, code)) + .contains(first.path("batchCode").asText()); + } + + @Test + void urdfForkCopiesIndependentObjectsAndCopyFailureDoesNotReturnReady() throws Exception { + String owner = login("urdf-fork-source@example.com"); + String other = login("urdf-fork-target@example.com"); + String code = create(owner, "URDF 来源"); + enableUrdfOss(); + List> files = urdfFiles(); + JsonNode uploaded = uploadUrdf(owner, code, files); + JsonNode source = confirmUrdf(owner, code, uploaded, files, 200).path("data"); + String sha = head(owner, code); + publish(owner, code, sha); + String forkEndpoint = "/api/community/projects/" + code + "/forks"; + Map forkInput = Map.of("name", "独立副本", "publishedCommitSha", sha); + JsonNode fork = perform(body(auth(post(forkEndpoint), other), forkInput), 200).path("data"); + String targetCode = fork.path("projectCode").asText(); + assertThat(fork.path("repoStatus").asText()).isEqualTo("READY"); + assertThat(fork.path("urdfMainUrl").asText()).contains("/urdf/" + targetCode + "/").doesNotContain("/urdf/" + code + "/"); + String targetPrefix = jdbc.queryForObject("SELECT urdf_prefix FROM project WHERE project_code = ?", String.class, targetCode); + for (int index = 0; index < files.size(); index++) + assertThat(ossObjects.objects.get(targetPrefix + files.get(index).get("relativePath"))) + .containsExactly(ossObjects.objects.get(uploaded.path("files").get(index).path("objectKey").asText())); + confirmUrdf(owner, code, uploadUrdf(owner, code, files), files, 200); + perform(auth(delete("/api/workspace/projects/" + code + "/urdf"), owner), 200); + assertThat(perform(auth(get("/api/workspace/projects/" + targetCode), other), 200).path("data").path("urdfMainUrl")) + .isEqualTo(fork.path("urdfMainUrl")); + confirmUrdf(owner, code, uploaded, files, 200); + ossObjects.failNextCopy = true; + JsonNode failure = perform(body(auth(post(forkEndpoint), other), forkInput), 502); + String failedCode = failure.path("data").path("projectCode").asText(); + assertThat(failedCode).isNotEmpty(); + assertThat(jdbc.queryForObject("SELECT repo_status FROM project WHERE project_code = ?", String.class, failedCode)).isEqualTo("FAILED"); + assertThat(jdbc.queryForObject("SELECT urdf_prefix FROM project WHERE project_code = ?", String.class, failedCode)).isEmpty(); + assertThat(perform(get("/api/community/projects/" + code), 200).path("data").path("urdfMainUrl")) + .isEqualTo(source.path("urdfMainUrl")); + } + @Test void coverSignaturesAuthenticateValidateAndReturnDirectUploadForms() throws Exception { String endpoint = "/api/uploads/project-covers/signature"; diff --git a/community-bean/src/main/java/com/linkerbot/community/bean/Contracts.java b/community-bean/src/main/java/com/linkerbot/community/bean/Contracts.java index 2399e78..dbaf9de 100644 --- a/community-bean/src/main/java/com/linkerbot/community/bean/Contracts.java +++ b/community-bean/src/main/java/com/linkerbot/community/bean/Contracts.java @@ -41,6 +41,25 @@ public final class Contracts { public record PublicationInput(@NotBlank String commitSha) {} + public record UrdfFile( + @NotBlank String relativePath, @NotNull @PositiveOrZero Long sizeBytes) {} + + public record UrdfUploadInput(@NotNull List<@NotNull @Valid UrdfFile> files) {} + + public record UrdfConfirmInput( + @NotBlank @Pattern(regexp = "[a-f0-9]{32}") String batchCode, + @NotNull List<@NotNull @Valid UrdfFile> files) {} + + public record UrdfFileSignature( + String relativePath, String objectKey, Map formFields) {} + + public record UrdfUploadSignature( + String batchCode, + String mainRelativePath, + String uploadUrl, + LocalDateTime expiresAt, + List files) {} + public record ForkInput( @NotBlank String publishedCommitSha, @NotBlank @Size(max = 100) String name) {} @@ -53,6 +72,8 @@ public final class Contracts { String name, String description, String coverUrl, + String urdfMainUrl, + String urdfBaseUrl, String projectType, PublicUser owner, String repoStatus, diff --git a/community-bean/src/main/java/com/linkerbot/community/bean/entity/Project.java b/community-bean/src/main/java/com/linkerbot/community/bean/entity/Project.java index a715a01..ee6f6d1 100644 --- a/community-bean/src/main/java/com/linkerbot/community/bean/entity/Project.java +++ b/community-bean/src/main/java/com/linkerbot/community/bean/entity/Project.java @@ -16,6 +16,9 @@ public class Project extends BaseEntity { private String name; private String description; private String coverUrl; + private String urdfMainObjectKey = ""; + private String urdfFiles = "[]"; + private String urdfPrefix = ""; private String projectType; private Long giteaRepoId; private String giteaOwner; diff --git a/community-import/src/test/java/com/linkerbot/community/importer/ImportCoordinatorTest.java b/community-import/src/test/java/com/linkerbot/community/importer/ImportCoordinatorTest.java index dc4f97a..475818e 100644 --- a/community-import/src/test/java/com/linkerbot/community/importer/ImportCoordinatorTest.java +++ b/community-import/src/test/java/com/linkerbot/community/importer/ImportCoordinatorTest.java @@ -72,6 +72,8 @@ class ImportCoordinatorTest { while (tables.find()) jdbc.execute( tables.group() + .replace("JSON NOT NULL DEFAULT (JSON_ARRAY())", "CLOB NOT NULL DEFAULT '[]'") + .replace(" CHARACTER SET utf8mb4 COLLATE utf8mb4_bin", "") .replaceAll(" COMMENT '[^']*'", "") .replaceAll("\\) ENGINE=InnoDB[^;]*;", ");")); owner = new User(); diff --git a/community-service/pom.xml b/community-service/pom.xml index 59e6f68..72d68cb 100644 --- a/community-service/pom.xml +++ b/community-service/pom.xml @@ -8,6 +8,17 @@ community-service + + com.aliyun.oss + aliyun-sdk-oss + 3.18.4 + + + commons-logging + commons-logging + + + com.github.ben-manes.caffeine caffeine diff --git a/community-service/src/main/java/com/linkerbot/community/service/UrdfService.java b/community-service/src/main/java/com/linkerbot/community/service/UrdfService.java new file mode 100644 index 0000000..360d551 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/UrdfService.java @@ -0,0 +1,14 @@ +package com.linkerbot.community.service; + +import com.linkerbot.community.bean.Contracts.ProjectView; +import com.linkerbot.community.bean.Contracts.UrdfConfirmInput; +import com.linkerbot.community.bean.Contracts.UrdfUploadInput; +import com.linkerbot.community.bean.Contracts.UrdfUploadSignature; + +public interface UrdfService { + UrdfUploadSignature signature(long userId, String projectCode, UrdfUploadInput input); + + ProjectView confirm(long userId, String projectCode, UrdfConfirmInput input); + + void clear(long userId, String projectCode); +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/config/OssProperties.java b/community-service/src/main/java/com/linkerbot/community/service/config/OssProperties.java index cbd56e5..8092f07 100644 --- a/community-service/src/main/java/com/linkerbot/community/service/config/OssProperties.java +++ b/community-service/src/main/java/com/linkerbot/community/service/config/OssProperties.java @@ -55,7 +55,7 @@ public class OssProperties { return "https://" + bucket + "." + uri.getRawAuthority(); } - private String resolvedEndpoint() { + public String resolvedEndpoint() { return endpoint == null || endpoint.isBlank() ? "https://oss-" + region + ".aliyuncs.com" : endpoint; } diff --git a/community-service/src/main/java/com/linkerbot/community/service/config/UrdfProperties.java b/community-service/src/main/java/com/linkerbot/community/service/config/UrdfProperties.java new file mode 100644 index 0000000..f00c217 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/config/UrdfProperties.java @@ -0,0 +1,19 @@ +package com.linkerbot.community.service.config; + +import jakarta.validation.constraints.Positive; +import lombok.Getter; +import lombok.Setter; +import org.springframework.boot.context.properties.ConfigurationProperties; +import org.springframework.stereotype.Component; +import org.springframework.validation.annotation.Validated; + +@Getter +@Setter +@Validated +@Component +@ConfigurationProperties(prefix = "community.oss.urdf") +public class UrdfProperties { + @Positive private long maxFileBytes = 50L * 1024 * 1024; + @Positive private long maxTotalBytes = 200L * 1024 * 1024; + @Positive private int maxFiles = 500; +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/impl/ProjectServiceImpl.java b/community-service/src/main/java/com/linkerbot/community/service/impl/ProjectServiceImpl.java index e950413..1e1fe4a 100644 --- a/community-service/src/main/java/com/linkerbot/community/service/impl/ProjectServiceImpl.java +++ b/community-service/src/main/java/com/linkerbot/community/service/impl/ProjectServiceImpl.java @@ -14,9 +14,11 @@ import com.linkerbot.community.service.UserService; import com.linkerbot.community.service.config.CommunityProperties; import com.linkerbot.community.service.gitea.*; import com.linkerbot.community.service.mapper.*; +import com.linkerbot.community.service.oss.UrdfResources; import com.linkerbot.community.service.support.ProjectLocks; import com.linkerbot.community.service.support.ProjectInputs; import org.springframework.dao.DuplicateKeyException; +import org.springframework.beans.factory.ObjectProvider; import lombok.RequiredArgsConstructor; @@ -38,6 +40,8 @@ public class ProjectServiceImpl implements ProjectService { private final GiteaClient gitea; private final CommunityProperties config; private final ProjectLocks locks; + // 离线导入只加载仓库和数据库组件,没有 URDF 时无需初始化 OSS 模块。 + private final ObjectProvider urdf; @Override public List types() { @@ -125,6 +129,8 @@ public class ProjectServiceImpl implements ProjectService { project.getName(), project.getDescription(), project.getCoverUrl(), + urdfUrl(project.getUrdfMainObjectKey()), + urdfUrl(project.getUrdfPrefix()), project.getProjectType(), users.publicView(project.getOwnerUserId()), project.getRepoStatus(), @@ -140,6 +146,10 @@ public class ProjectServiceImpl implements ProjectService { project.getUpdatedAt()); } + private String urdfUrl(String objectKey) { + return objectKey == null || objectKey.isEmpty() ? null : urdf.getObject().url(objectKey); + } + @Override public PageResponse list( Long ownerId, String type, String keyword, long page, long size, Long currentUser) { @@ -241,12 +251,16 @@ public class ProjectServiceImpl implements ProjectService { GiteaClient.Repository repo = gitea.createRepository(project.getGiteaRepoName(), fork == null); project.setGiteaRepoId(repo.id()); - if (fork != null) + if (fork != null) { copySnapshot( repository(fork.source()), fork.source().getPublishedCommitSha(), repo, fork.user()); + if (fork.source().getUrdfMainObjectKey() != null + && !fork.source().getUrdfMainObjectKey().isEmpty()) + urdf.getObject().copy(fork.source(), project); + } project.setRepoStatus("READY"); project.setUpdatedAt(now()); projects.updateById(project); diff --git a/community-service/src/main/java/com/linkerbot/community/service/impl/UrdfServiceImpl.java b/community-service/src/main/java/com/linkerbot/community/service/impl/UrdfServiceImpl.java new file mode 100644 index 0000000..0b75d00 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/impl/UrdfServiceImpl.java @@ -0,0 +1,81 @@ +package com.linkerbot.community.service.impl; + +import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper; +import com.linkerbot.community.bean.Contracts.ProjectView; +import com.linkerbot.community.bean.Contracts.UrdfConfirmInput; +import com.linkerbot.community.bean.Contracts.UrdfUploadInput; +import com.linkerbot.community.bean.Contracts.UrdfUploadSignature; +import com.linkerbot.community.bean.entity.Project; +import com.linkerbot.community.common.BusinessException; +import com.linkerbot.community.service.ProjectService; +import com.linkerbot.community.service.UrdfService; +import com.linkerbot.community.service.mapper.ProjectMapper; +import com.linkerbot.community.service.oss.UrdfResources; +import com.linkerbot.community.service.support.ProjectLocks; +import com.linkerbot.community.service.support.ProjectSupport; +import lombok.RequiredArgsConstructor; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.stereotype.Service; + +@Service +@RequiredArgsConstructor +public class UrdfServiceImpl implements UrdfService { + private static final Logger log = LoggerFactory.getLogger(UrdfServiceImpl.class); + private final ProjectService projects; + private final ProjectMapper mapper; + private final UrdfResources resources; + private final ProjectLocks locks; + + @Override + public UrdfUploadSignature signature(long userId, String projectCode, UrdfUploadInput input) { + projects.readyOwner(userId, projectCode); + return resources.sign(projectCode, input.files()); + } + + @Override + public ProjectView confirm(long userId, String projectCode, UrdfConfirmInput input) { + projects.readyOwner(userId, projectCode); + // OSS 网络调用在锁外执行,最终落库时重新检查项目归属及状态。 + resources.verify(projectCode, input.batchCode(), input.files()); + String prefix = resources.prefix(projectCode, input.batchCode()); + String main = resources.validate(prefix, input.files()); + String manifest = resources.manifest(input.files()); + return locks.serial(projectCode, () -> { + Project project = projects.readyOwner(userId, projectCode); + project.setUrdfPrefix(prefix); + project.setUrdfMainObjectKey(prefix + main); + project.setUrdfFiles(manifest); + persist(project); + log.info("绑定 URDF 资源 projectCode={} batchCode={} fileCount={}", + projectCode, input.batchCode(), input.files().size()); + return projects.view(project, userId); + }); + } + + @Override + public void clear(long userId, String projectCode) { + locks.serial(projectCode, () -> { + Project project = projects.owner(userId, projectCode); + project.setUrdfMainObjectKey(""); + project.setUrdfPrefix(""); + project.setUrdfFiles("[]"); + persist(project); + log.info("清除 URDF 绑定 projectCode={}", projectCode); + return null; + }); + } + + private void persist(Project project) { + project.setUpdatedAt(ProjectSupport.now()); + int updated = mapper.update(null, new LambdaUpdateWrapper() + .eq(Project::getProjectCode, project.getProjectCode()) + .eq(Project::getOwnerUserId, project.getOwnerUserId()) + .eq(Project::getDeleted, false) + .set(Project::getUrdfMainObjectKey, project.getUrdfMainObjectKey()) + .set(Project::getUrdfFiles, project.getUrdfFiles()) + .set(Project::getUrdfPrefix, project.getUrdfPrefix()) + .set(Project::getUpdatedAt, project.getUpdatedAt())); + if (updated != 1) throw BusinessException.notFound(); + } +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/oss/AliyunOssObjectStore.java b/community-service/src/main/java/com/linkerbot/community/service/oss/AliyunOssObjectStore.java new file mode 100644 index 0000000..8aa3e69 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/oss/AliyunOssObjectStore.java @@ -0,0 +1,94 @@ +package com.linkerbot.community.service.oss; + +import com.aliyun.oss.ClientBuilderConfiguration; +import com.aliyun.oss.ClientException; +import com.aliyun.oss.OSS; +import com.aliyun.oss.OSSClientBuilder; +import com.aliyun.oss.OSSException; +import com.aliyun.oss.common.comm.SignVersion; +import com.aliyun.oss.common.auth.DefaultCredentialProvider; +import com.aliyun.oss.model.CopyObjectRequest; +import com.aliyun.oss.model.ObjectMetadata; +import com.linkerbot.community.common.BusinessException; +import com.linkerbot.community.service.config.OssProperties; +import jakarta.annotation.PreDestroy; +import java.util.List; +import lombok.RequiredArgsConstructor; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.stereotype.Component; + +@Component +@RequiredArgsConstructor +public class AliyunOssObjectStore implements OssObjectStore { + private static final Logger log = LoggerFactory.getLogger(AliyunOssObjectStore.class); + private final OssProperties properties; + private OSS client; + + private synchronized OSS client() { + if (!properties.isEnabled()) + throw new BusinessException(503, "OSS_UNAVAILABLE", "OSS URDF 上传暂未开启"); + if (client == null) { + ClientBuilderConfiguration configuration = new ClientBuilderConfiguration(); + configuration.setSignatureVersion(SignVersion.V4); + configuration.setConnectionTimeout(5000); + configuration.setSocketTimeout(30000); + configuration.setMaxErrorRetry(1); + client = OSSClientBuilder.create() + .endpoint(properties.resolvedEndpoint()) + .region(properties.getRegion()) + .credentialsProvider(new DefaultCredentialProvider( + properties.getAccessKeyId(), properties.getAccessKeySecret())) + .clientConfiguration(configuration) + .build(); + } + return client; + } + + @Override + public Metadata head(String objectKey) { + try { + ObjectMetadata metadata = client().getObjectMetadata(properties.getBucket(), objectKey); + return new Metadata(metadata.getContentLength(), metadata.getETag()); + } catch (OSSException error) { + throw failure("head", objectKey, error); + } catch (ClientException error) { + throw transportFailure("head", objectKey, error); + } + } + + @Override + public void copy(String sourceKey, String targetKey, String sourceEtag) { + try { + CopyObjectRequest request = new CopyObjectRequest( + properties.getBucket(), sourceKey, properties.getBucket(), targetKey); + request.setMatchingETagConstraints(List.of(sourceEtag)); + client().copyObject(request); + } catch (OSSException error) { + throw failure("copy", targetKey, error); + } catch (ClientException error) { + throw transportFailure("copy", targetKey, error); + } + } + + private BusinessException failure(String operation, String key, OSSException error) { + log.warn("URDF OSS 请求失败 operation={} objectKey={} ossCode={} requestId={}", + operation, key, error.getErrorCode(), error.getRequestId()); + if ("NoSuchKey".equals(error.getErrorCode())) + return new BusinessException(400, "URDF_FILE_MISSING", "URDF 文件未上传完整,请重新上传"); + if ("PreconditionFailed".equals(error.getErrorCode())) + return BusinessException.conflict("URDF 资源已变化,请重新操作"); + return new BusinessException(502, "OSS_ERROR", "OSS 资源访问失败,请稍后重试"); + } + + private BusinessException transportFailure(String operation, String key, ClientException error) { + log.warn("URDF OSS 连接失败 operation={} objectKey={} errorType={}", + operation, key, error.getClass().getSimpleName()); + return new BusinessException(502, "OSS_ERROR", "OSS 资源访问失败,请稍后重试"); + } + + @PreDestroy + public synchronized void close() { + if (client != null) client.shutdown(); + } +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/oss/OssObjectStore.java b/community-service/src/main/java/com/linkerbot/community/service/oss/OssObjectStore.java new file mode 100644 index 0000000..5316e87 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/oss/OssObjectStore.java @@ -0,0 +1,10 @@ +package com.linkerbot.community.service.oss; + +/** URDF 所需的 OSS 操作边界,测试使用内存实现。 */ +public interface OssObjectStore { + record Metadata(long sizeBytes, String etag) {} + + Metadata head(String objectKey); + + void copy(String sourceKey, String targetKey, String sourceEtag); +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/oss/OssPostSigner.java b/community-service/src/main/java/com/linkerbot/community/service/oss/OssPostSigner.java index 3921e36..2f7ac79 100644 --- a/community-service/src/main/java/com/linkerbot/community/service/oss/OssPostSigner.java +++ b/community-service/src/main/java/com/linkerbot/community/service/oss/OssPostSigner.java @@ -46,25 +46,43 @@ public class OssPostSigner { } public CoverUploadSignature sign(String userCode, String contentType, String extension) { + String key = properties.getRootDirectory() + "/project-covers/" + userCode + "/" + + DATE.format(clock.instant()) + "/" + Codes.next() + "." + extension; + SignedPost post = post(key, contentType, 1, MAX_FILE_BYTES, VALIDITY, false); + return new CoverUploadSignature(properties.uploadUrl(), key, + properties.publicBaseUrl() + "/" + key, post.expiresAt(), post.formFields()); + } + + public record SignedPost(LocalDateTime expiresAt, Map formFields) {} + + public SignedPost signObject(String key, String contentType, long sizeBytes) { + return post(key, contentType, sizeBytes, sizeBytes, Duration.ofMinutes(15), true); + } + + private SignedPost post(String key, String contentType, long minBytes, long maxBytes, + Duration validity, boolean forbidOverwrite) { Instant now = clock.instant().truncatedTo(ChronoUnit.MILLIS); - Instant expiration = now.plus(VALIDITY); + Instant expiration = now.plus(validity); String date = DATE.format(now); String timestamp = TIMESTAMP.format(now); String credential = properties.getAccessKeyId() + "/" + date + "/" + properties.getRegion() + "/oss/aliyun_v4_request"; - String key = properties.getRootDirectory() + "/project-covers/" + userCode + "/" - + date + "/" + Codes.next() + "." + extension; Map policy = new LinkedHashMap<>(); policy.put("expiration", EXPIRATION.format(expiration)); - policy.put("conditions", List.of( + List conditions = new ArrayList<>(List.of( Map.of("bucket", properties.getBucket()), Map.of("x-oss-signature-version", VERSION), Map.of("x-oss-credential", credential), Map.of("x-oss-date", timestamp), List.of("eq", "$key", key), List.of("eq", "$content-type", contentType), - List.of("content-length-range", 1, MAX_FILE_BYTES), + List.of("content-length-range", minBytes, maxBytes), List.of("eq", "$success_action_status", "200"))); + if (forbidOverwrite) { + conditions.add(List.of("eq", "$x-oss-forbid-overwrite", "true")); + conditions.add(List.of("eq", "$x-oss-content-type", contentType)); + } + policy.put("conditions", conditions); try { String encoded = Base64.getEncoder().encodeToString(json.writeValueAsBytes(policy)); Map fields = new LinkedHashMap<>(); @@ -77,12 +95,14 @@ public class OssPostSigner { properties.getRegion(), encoded)); fields.put("content-type", contentType); fields.put("success_action_status", "200"); - return new CoverUploadSignature(properties.uploadUrl(), key, - properties.publicBaseUrl() + "/" + key, - LocalDateTime.ofInstant(expiration, ZoneOffset.UTC), Map.copyOf(fields)); + if (forbidOverwrite) { + fields.put("x-oss-forbid-overwrite", "true"); + fields.put("x-oss-content-type", contentType); + } + return new SignedPost(LocalDateTime.ofInstant(expiration, ZoneOffset.UTC), Map.copyOf(fields)); } catch (JsonProcessingException | GeneralSecurityException error) { - log.error("OSS 签名生成失败 userCode={} region={} errorType={}", - userCode, properties.getRegion(), error.getClass().getSimpleName()); + log.error("OSS 签名生成失败 objectKey={} region={} errorType={}", + key, properties.getRegion(), error.getClass().getSimpleName()); throw new IllegalStateException("OSS 签名生成失败"); } } diff --git a/community-service/src/main/java/com/linkerbot/community/service/oss/UrdfResources.java b/community-service/src/main/java/com/linkerbot/community/service/oss/UrdfResources.java new file mode 100644 index 0000000..92e853e --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/oss/UrdfResources.java @@ -0,0 +1,179 @@ +package com.linkerbot.community.service.oss; + +import com.fasterxml.jackson.core.JsonProcessingException; +import com.fasterxml.jackson.core.type.TypeReference; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.linkerbot.community.bean.Contracts.UrdfFile; +import com.linkerbot.community.bean.Contracts.UrdfFileSignature; +import com.linkerbot.community.bean.Contracts.UrdfUploadSignature; +import com.linkerbot.community.bean.entity.Project; +import com.linkerbot.community.common.BusinessException; +import com.linkerbot.community.common.Codes; +import com.linkerbot.community.common.FilePaths; +import com.linkerbot.community.service.config.OssProperties; +import com.linkerbot.community.service.config.UrdfProperties; +import java.nio.charset.StandardCharsets; +import java.time.LocalDateTime; +import java.util.ArrayList; +import java.util.HashSet; +import java.util.List; +import java.util.Locale; +import java.util.Set; +import lombok.RequiredArgsConstructor; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; +import org.springframework.http.MediaTypeFactory; +import org.springframework.stereotype.Component; +import org.springframework.web.util.UriUtils; + +@Component +@RequiredArgsConstructor +public class UrdfResources { + private static final Logger log = LoggerFactory.getLogger(UrdfResources.class); + private static final TypeReference> FILES_TYPE = new TypeReference<>() {}; + private final OssProperties oss; + private final UrdfProperties limits; + private final OssPostSigner signer; + private final OssObjectStore store; + private final ObjectMapper json; + + public void requireEnabled() { + if (!oss.isEnabled()) + throw new BusinessException(503, "OSS_UNAVAILABLE", "OSS URDF 上传暂未开启"); + } + + /** 不信任客户端文件名及大小;签名、确认和 Fork 使用同一套校验。 */ + public String validate(String prefix, List files) { + if (files == null) throw BusinessException.badRequest("必须提供 URDF 文件清单"); + if (files.size() > limits.getMaxFiles()) throw tooLarge(); + Set paths = new HashSet<>(); + long total = 0; + String main = null; + int mainCount = 0; + for (UrdfFile file : files) { + if (file == null || file.sizeBytes() == null || file.sizeBytes() < 0) + throw BusinessException.badRequest("文件大小不合法"); + String path = FilePaths.file(file.relativePath()); + if (!paths.add(path)) throw BusinessException.badRequest("上传路径不能重复"); + String key = prefix + path; + if (key.length() > 512 || key.getBytes(StandardCharsets.UTF_8).length > 1023) + throw BusinessException.badRequest("URDF 文件对象键过长"); + if (file.sizeBytes() > limits.getMaxFileBytes() + || file.sizeBytes() > limits.getMaxTotalBytes() - total) throw tooLarge(); + total += file.sizeBytes(); + if (path.toLowerCase(Locale.ROOT).endsWith(".urdf")) { + main = path; + mainCount++; + } + } + if (mainCount == 0) + throw new BusinessException(400, "URDF_MAIN_FILE_INVALID", "文件夹中未找到 URDF 文件"); + if (mainCount > 1) + throw new BusinessException(400, "URDF_MAIN_FILE_INVALID", + "文件夹中存在多个 URDF 文件,请仅保留一个后重新上传"); + return main; + } + + private BusinessException tooLarge() { + return new BusinessException(413, "URDF_UPLOAD_TOO_LARGE", "URDF 文件数量或大小超过限制"); + } + + public String prefix(String projectCode, String batchCode) { + if (projectCode == null || !projectCode.matches("[a-z0-9]{12}|[a-z0-9]{32}") + || batchCode == null || !batchCode.matches("[a-f0-9]{32}")) + throw BusinessException.badRequest("URDF 项目或批次编码不合法"); + return oss.getRootDirectory() + "/urdf/" + projectCode + "/" + batchCode + "/"; + } + + public UrdfUploadSignature sign(String projectCode, List files) { + requireEnabled(); + String batch = Codes.next(); + String prefix = prefix(projectCode, batch); + String main = validate(prefix, files); + List signatures = new ArrayList<>(); + LocalDateTime expiration = null; + for (UrdfFile file : files) { + String type = file.relativePath().equals(main) ? "application/xml" + : MediaTypeFactory.getMediaType(file.relativePath().toLowerCase(Locale.ROOT)) + .map(Object::toString).orElse("application/octet-stream"); + String key = prefix + file.relativePath(); + OssPostSigner.SignedPost post = signer.signObject(key, type, file.sizeBytes()); + if (expiration == null || post.expiresAt().isBefore(expiration)) expiration = post.expiresAt(); + signatures.add(new UrdfFileSignature(file.relativePath(), key, post.formFields())); + } + log.info("生成 URDF 上传签名 projectCode={} batchCode={} fileCount={} totalBytes={}", + projectCode, batch, files.size(), totalBytes(files)); + return new UrdfUploadSignature(batch, main, oss.uploadUrl(), expiration, List.copyOf(signatures)); + } + + public void verify(String projectCode, String batchCode, List files) { + requireEnabled(); + String prefix = prefix(projectCode, batchCode); + validate(prefix, files); + for (UrdfFile file : files) checkedMetadata(prefix, file); + } + + private OssObjectStore.Metadata checkedMetadata(String prefix, UrdfFile file) { + OssObjectStore.Metadata metadata = store.head(prefix + file.relativePath()); + if (metadata.sizeBytes() != file.sizeBytes()) { + log.warn("URDF 文件大小不符 objectKey={} expectedBytes={} actualBytes={}", + prefix + file.relativePath(), file.sizeBytes(), metadata.sizeBytes()); + throw new BusinessException(400, "URDF_FILE_SIZE_MISMATCH", "URDF 文件大小不符,请重新上传"); + } + return metadata; + } + + public String manifest(List files) { + try { + return json.writeValueAsString(files); + } catch (JsonProcessingException error) { + throw new IllegalStateException("URDF 文件清单序列化失败", error); + } + } + + public void copy(Project source, Project target) { + if (source.getUrdfMainObjectKey() == null || source.getUrdfMainObjectKey().isEmpty()) return; + requireEnabled(); + List files; + try { + files = json.readValue(source.getUrdfFiles(), FILES_TYPE); + } catch (JsonProcessingException error) { + log.error("URDF 文件清单读取失败 projectCode={} errorType={}", + source.getProjectCode(), error.getClass().getSimpleName()); + throw new BusinessException(500, "URDF_MANIFEST_INVALID", "URDF 文件清单异常"); + } + String sourcePrefix = source.getUrdfPrefix(); + String root = oss.getRootDirectory() + "/urdf/" + source.getProjectCode() + "/"; + if (sourcePrefix == null || !sourcePrefix.startsWith(root) + || !sourcePrefix.substring(root.length()).matches("[a-f0-9]{32}/")) + throw new BusinessException(500, "URDF_MANIFEST_INVALID", "URDF 资源目录异常"); + String main = validate(sourcePrefix, files); + if (!source.getUrdfMainObjectKey().equals(sourcePrefix + main)) + throw new BusinessException(500, "URDF_MANIFEST_INVALID", "URDF 主文件记录异常"); + String targetPrefix = prefix(target.getProjectCode(), Codes.next()); + validate(targetPrefix, files); + log.info("开始复制 Fork URDF sourceProjectCode={} projectCode={} fileCount={}", + source.getProjectCode(), target.getProjectCode(), files.size()); + for (UrdfFile file : files) { + OssObjectStore.Metadata metadata = checkedMetadata(sourcePrefix, file); + store.copy(sourcePrefix + file.relativePath(), targetPrefix + file.relativePath(), metadata.etag()); + } + target.setUrdfPrefix(targetPrefix); + target.setUrdfMainObjectKey(targetPrefix + main); + target.setUrdfFiles(manifest(files)); + log.info("Fork URDF 复制完成 projectCode={} fileCount={} totalBytes={}", + target.getProjectCode(), files.size(), totalBytes(files)); + } + + public String url(String objectKey) { + if (objectKey == null || objectKey.isEmpty()) return null; + String[] segments = objectKey.split("/", -1); + for (int index = 0; index < segments.length; index++) + segments[index] = UriUtils.encodePathSegment(segments[index], StandardCharsets.UTF_8); + return oss.publicBaseUrl() + "/" + String.join("/", segments); + } + + private long totalBytes(List files) { + return files.stream().mapToLong(UrdfFile::sizeBytes).sum(); + } +} diff --git a/community-service/src/test/java/com/linkerbot/community/service/ProjectCodeAllocationTest.java b/community-service/src/test/java/com/linkerbot/community/service/ProjectCodeAllocationTest.java index cfe2b91..c2dca69 100644 --- a/community-service/src/test/java/com/linkerbot/community/service/ProjectCodeAllocationTest.java +++ b/community-service/src/test/java/com/linkerbot/community/service/ProjectCodeAllocationTest.java @@ -13,11 +13,13 @@ import com.linkerbot.community.service.config.CommunityProperties; import com.linkerbot.community.service.gitea.GiteaClient; import com.linkerbot.community.service.impl.ProjectServiceImpl; import com.linkerbot.community.service.mapper.*; +import com.linkerbot.community.service.oss.UrdfResources; import com.linkerbot.community.service.support.ProjectLocks; import org.junit.jupiter.api.Test; import org.mockito.MockedStatic; import org.springframework.dao.DuplicateKeyException; +import org.springframework.beans.factory.support.StaticListableBeanFactory; class ProjectCodeAllocationTest { @Test @@ -84,6 +86,7 @@ class ProjectCodeAllocationTest { users, gitea, new CommunityProperties(), - new ProjectLocks()); + new ProjectLocks(), + new StaticListableBeanFactory().getBeanProvider(UrdfResources.class)); } } diff --git a/community-service/src/test/java/com/linkerbot/community/service/oss/AliyunOssObjectStoreTest.java b/community-service/src/test/java/com/linkerbot/community/service/oss/AliyunOssObjectStoreTest.java new file mode 100644 index 0000000..ecda76a --- /dev/null +++ b/community-service/src/test/java/com/linkerbot/community/service/oss/AliyunOssObjectStoreTest.java @@ -0,0 +1,88 @@ +package com.linkerbot.community.service.oss; + +import static org.assertj.core.api.Assertions.*; + +import com.linkerbot.community.common.BusinessException; +import com.linkerbot.community.service.config.OssProperties; +import com.sun.net.httpserver.HttpExchange; +import com.sun.net.httpserver.HttpServer; +import java.io.IOException; +import java.net.InetSocketAddress; +import java.nio.charset.StandardCharsets; +import java.util.concurrent.atomic.AtomicReference; +import org.junit.jupiter.api.AfterEach; +import org.junit.jupiter.api.BeforeEach; +import org.junit.jupiter.api.Test; + +/** 使用本机 HTTP 替身验证真实 SDK 的 V4 请求和 XML 解析,不访问阿里云。 */ +class AliyunOssObjectStoreTest { + private HttpServer server; + private AliyunOssObjectStore store; + private final AtomicReference copySource = new AtomicReference<>(); + private final AtomicReference copyEtag = new AtomicReference<>(); + private final AtomicReference authorization = new AtomicReference<>(); + + @BeforeEach + void start() throws IOException { + server = HttpServer.create(new InetSocketAddress("127.0.0.1", 0), 0); + server.createContext("/", this::respond); + server.start(); + OssProperties properties = new OssProperties(); + properties.setEnabled(true); + properties.setRegion("cn-hangzhou"); + properties.setBucket("examplebucket"); + properties.setAccessKeyId("UnitTestAccessKey"); + properties.setAccessKeySecret("unit-test-secret"); + properties.setEndpoint("http://127.0.0.1:" + server.getAddress().getPort()); + store = new AliyunOssObjectStore(properties); + } + + private void respond(HttpExchange exchange) throws IOException { + try (HttpExchange request = exchange) { + authorization.set(request.getRequestHeaders().getFirst("Authorization")); + request.getResponseHeaders().set("x-oss-request-id", "fake-request-id"); + if (request.getRequestMethod().equals("HEAD")) { + if (request.getRequestURI().getPath().endsWith("missing.urdf")) { + request.sendResponseHeaders(404, -1); + } else { + request.getResponseHeaders().set("Content-Length", "1234"); + request.getResponseHeaders().set("ETag", "\"source-etag\""); + request.getResponseHeaders().set("Last-Modified", "Fri, 16 Oct 2026 00:00:00 GMT"); + request.sendResponseHeaders(200, -1); + } + return; + } + copySource.set(request.getRequestHeaders().getFirst("x-oss-copy-source")); + copyEtag.set(request.getRequestHeaders().getFirst("x-oss-copy-source-if-match")); + byte[] body = ("2026-10-16T00:00:00.000Z" + + "\"target-etag\"").getBytes(StandardCharsets.UTF_8); + request.getResponseHeaders().set("Content-Type", "application/xml"); + request.sendResponseHeaders(200, body.length); + request.getResponseBody().write(body); + } + } + + @AfterEach + void stop() { + if (store != null) store.close(); + if (server != null) server.stop(0); + } + + @Test + void realSdkReadsMetadataAndCopiesWithV4AuthenticationAndSourceEtag() { + OssObjectStore.Metadata metadata = store.head("vibemake_dev/urdf/a/机械 臂.urdf"); + assertThat(metadata.sizeBytes()).isEqualTo(1234); + assertThat(metadata.etag()).isEqualTo("source-etag"); + assertThat(authorization.get()).startsWith("OSS4-HMAC-SHA256 "); + store.copy("vibemake_dev/urdf/a/机械 臂.urdf", "vibemake_dev/urdf/b/机械 臂.urdf", metadata.etag()); + assertThat(copySource.get()).contains("examplebucket/").contains("%E6%9C%BA%E6%A2%B0%20%E8%87%82.urdf"); + assertThat(copyEtag.get()).contains("source-etag"); + } + + @Test + void missingObjectReturnsBusinessErrorWithoutSdkDetails() { + assertThatThrownBy(() -> store.head("vibemake_dev/urdf/a/missing.urdf")) + .isInstanceOfSatisfying(BusinessException.class, + error -> assertThat(error.code()).isEqualTo("URDF_FILE_MISSING")); + } +} diff --git a/community-service/src/test/java/com/linkerbot/community/service/oss/OssPostSignerTest.java b/community-service/src/test/java/com/linkerbot/community/service/oss/OssPostSignerTest.java index f194f83..436c9c8 100644 --- a/community-service/src/test/java/com/linkerbot/community/service/oss/OssPostSignerTest.java +++ b/community-service/src/test/java/com/linkerbot/community/service/oss/OssPostSignerTest.java @@ -70,6 +70,25 @@ class OssPostSignerTest { assertThat(signer.sign(user, "image/png", "png").objectKey()).isNotEqualTo(result.objectKey()); } + @Test + void urdfPoliciesBindExactSizeKeyMimeAndFifteenMinuteExpiry() throws Exception { + Clock clock = Clock.fixed(Instant.parse("2026-10-14T23:58:30Z"), ZoneOffset.UTC); + OssPostSigner signer = new OssPostSigner(properties(), json, clock); + String key = "vibemake_dev/urdf/7m4k9x2p8q6r/" + "a".repeat(32) + "/urdf/机械 臂.URDF"; + OssPostSigner.SignedPost post = signer.signObject(key, "application/xml", 1234); + assertThat(post.expiresAt()).isEqualTo(LocalDateTime.parse("2026-10-15T00:13:30")); + JsonNode policy = json.readTree(Base64.getDecoder().decode(post.formFields().get("policy"))); + List conditions = json.convertValue(policy.path("conditions"), new TypeReference<>() {}); + assertThat(conditions).contains(List.of("eq", "$key", key), + List.of("content-length-range", 1234, 1234), + List.of("eq", "$content-type", "application/xml"), + List.of("eq", "$x-oss-content-type", "application/xml"), + List.of("eq", "$x-oss-forbid-overwrite", "true")); + assertThat(post.formFields()).containsEntry("key", key) + .containsEntry("x-oss-content-type", "application/xml") + .containsEntry("x-oss-forbid-overwrite", "true"); + } + @Test void usesProductionRootAndConfiguredCdnBasePath() { OssProperties properties = properties(); diff --git a/community-service/src/test/java/com/linkerbot/community/service/oss/UrdfResourcesTest.java b/community-service/src/test/java/com/linkerbot/community/service/oss/UrdfResourcesTest.java new file mode 100644 index 0000000..30f6cbe --- /dev/null +++ b/community-service/src/test/java/com/linkerbot/community/service/oss/UrdfResourcesTest.java @@ -0,0 +1,73 @@ +package com.linkerbot.community.service.oss; + +import static org.assertj.core.api.Assertions.*; +import static org.mockito.Mockito.*; + +import com.fasterxml.jackson.databind.ObjectMapper; +import com.linkerbot.community.bean.Contracts.UrdfFile; +import com.linkerbot.community.bean.entity.Project; +import com.linkerbot.community.common.BusinessException; +import com.linkerbot.community.service.config.OssProperties; +import com.linkerbot.community.service.config.UrdfProperties; +import java.util.List; +import org.junit.jupiter.api.Test; + +class UrdfResourcesTest { + private final OssProperties oss = new OssProperties(); + private final UrdfProperties limits = new UrdfProperties(); + private final OssObjectStore store = mock(OssObjectStore.class); + private final UrdfResources resources = new UrdfResources( + oss, limits, mock(OssPostSigner.class), store, new ObjectMapper()); + + @Test + void acceptsExactLimitsAndRejectsOverflowCountsAndCrossProjectBatches() { + oss.setRootDirectory("vibemake_dev"); + String prefix = resources.prefix("7m4k9x2p8q6r", "a".repeat(32)); + limits.setMaxFileBytes(10); + limits.setMaxTotalBytes(20); + assertThat(resources.validate(prefix, List.of(new UrdfFile("a.URDF", 10L), new UrdfFile("meshes/a.stl", 10L)))) + .isEqualTo("a.URDF"); + assertThatThrownBy(() -> resources.validate(prefix, List.of(new UrdfFile("a.urdf", Long.MAX_VALUE)))) + .isInstanceOfSatisfying(BusinessException.class, error -> assertThat(error.status()).isEqualTo(413)); + assertThatThrownBy(() -> resources.prefix("7m4k9x2p8q6r", "../another")) + .isInstanceOf(BusinessException.class); + assertThatThrownBy(() -> resources.prefix("../../other", "a".repeat(32))) + .isInstanceOf(BusinessException.class); + verifyNoInteractions(store); + } + + @Test + void encodesUrlSegmentsWithoutEncodingSlashesAndKeepsEmptyUrlsNull() { + oss.setPublicBaseUrl("https://cdn.example.com/assets/"); + assertThat(resources.url("vibemake/urdf/目录/a #?%+.urdf")) + .isEqualTo("https://cdn.example.com/assets/vibemake/urdf/%E7%9B%AE%E5%BD%95/a%20%23%3F%25+.urdf"); + assertThat(resources.url("vibemake/urdf/a/")).endsWith("/a/"); + assertThat(resources.url("")).isNull(); + assertThat(resources.url(null)).isNull(); + } + + @Test + void failedCopyLeavesTargetEmptyAndSuccessfulCopyUsesSourceEtag() { + oss.setEnabled(true); + oss.setRootDirectory("vibemake_dev"); + Project source = new Project(); + source.setProjectCode("7m4k9x2p8q6r"); + String sourcePrefix = resources.prefix(source.getProjectCode(), "a".repeat(32)); + source.setUrdfPrefix(sourcePrefix); + source.setUrdfMainObjectKey(sourcePrefix + "a.urdf"); + source.setUrdfFiles(resources.manifest(List.of(new UrdfFile("a.urdf", 12L)))); + Project target = new Project(); + target.setProjectCode("222222222222"); + when(store.head(sourcePrefix + "a.urdf")).thenReturn(new OssObjectStore.Metadata(12, "source-etag")); + doThrow(new BusinessException(502, "OSS_ERROR", "copy failed")).when(store).copy(anyString(), anyString(), anyString()); + assertThatThrownBy(() -> resources.copy(source, target)).isInstanceOf(BusinessException.class); + assertThat(target.getUrdfPrefix()).isEmpty(); + assertThat(target.getUrdfMainObjectKey()).isEmpty(); + reset(store); + when(store.head(sourcePrefix + "a.urdf")).thenReturn(new OssObjectStore.Metadata(12, "source-etag")); + resources.copy(source, target); + verify(store).copy(sourcePrefix + "a.urdf", target.getUrdfPrefix() + "a.urdf", "source-etag"); + assertThat(target.getUrdfPrefix()).startsWith("vibemake_dev/urdf/222222222222/"); + assertThat(target.getUrdfMainObjectKey()).isEqualTo(target.getUrdfPrefix() + "a.urdf"); + } +} diff --git a/docs/community-api.md b/docs/community-api.md index 5d65a2d..8cea1c7 100644 --- a/docs/community-api.md +++ b/docs/community-api.md @@ -13,6 +13,7 @@ - [类型与项目列表](#类型与项目列表) - [我的项目管理](#我的项目管理) - [项目封面与 OSS 直传](#项目封面与-oss-直传) +- [项目 URDF 文件夹](#项目-urdf-文件夹) - [目录和文件读取](#目录和文件读取) - [文件编辑与上传提交](#文件编辑与上传提交) - [社区发布和撤回](#社区发布和撤回) @@ -110,6 +111,9 @@ Git SHA 使用完整的 40 或 64 位十六进制字符串,不使用缩写。 | GET | `/api/workspace/projects/{projectCode}` | 是 | Project | | PATCH | `/api/workspace/projects/{projectCode}` | 是 | Project | | DELETE | `/api/workspace/projects/{projectCode}` | 是 | null | +| POST | `/api/workspace/projects/{projectCode}/urdf/signature` | 是 | UrdfUploadSignature | +| PUT | `/api/workspace/projects/{projectCode}/urdf` | 是 | Project | +| DELETE | `/api/workspace/projects/{projectCode}/urdf` | 是 | null | | GET | `/api/workspace/projects/{projectCode}/tree` | 是 | Tree | | GET | `/api/workspace/projects/{projectCode}/files` | 是 | ProjectFile 或下载二进制 | | POST | `/api/workspace/projects/{projectCode}/commits` | 是 | Commit | @@ -185,6 +189,8 @@ export interface Project { name: string; description: string; coverUrl: string | null; // 固定公开 HTTPS 图片地址,支持 OSS/CDN 和外部图片 + urdfMainUrl: string | null; // 当前 URDF 主文件公开地址,无资源时为 null + urdfBaseUrl: string | null; // 当前资源包公开目录地址,以 / 结尾,无资源时为 null projectType: string; owner: PublicUser; repoStatus: 'CREATING' | 'READY' | 'FAILED'; @@ -208,6 +214,23 @@ export interface CoverUploadSignature { formFields: Record; } +export interface UrdfFile { + relativePath: string; + sizeBytes: number; +} + +export interface UrdfUploadSignature { + batchCode: string; + mainRelativePath: string; + uploadUrl: string; + expiresAt: UtcDateTime; // 无时区后缀,按 UTC 解释 + files: Array<{ + relativePath: string; + objectKey: string; + formFields: Record; + }>; +} + export interface TreeEntry { path: string; // 从仓库根目录开始的完整相对路径 name: string; @@ -262,6 +285,8 @@ export interface Comment { "name": "机器人示例项目", "description": "模型、配置和说明文件", "coverUrl": "https://images.example.com/vibemake/project-covers/11111111111111111111111111111111/20261015/33333333333333333333333333333333.png", + "urdfMainUrl": null, + "urdfBaseUrl": null, "projectType": "GENERAL", "owner": { "userCode": "11111111111111111111111111111111", @@ -292,6 +317,7 @@ export interface Comment { | sourceProjectCode / sourceCommitSha | Fork 来源及复制的源版本;普通新项目为 null | | liked | 当前请求用户是否点赞,匿名访问为 false | | coverUrl | 固定公开封面地址,null 时展示前端默认图;工作区、社区、Fork 和 AI 卡片共用此字段 | +| urdfMainUrl / urdfBaseUrl | 当前 URDF 主文件与资源目录的公开地址,无资源时均为 null;工作区、社区、AI 卡片均返回,Fork 使用独立副本 | 工作区归属由 `owner.userCode` 判断,不存在 `workspaceCode`。`updatedAt` 不代表仓库最新提交时间。来源项目撤回或删除后,sourceProjectCode 仍可能存在,访问该来源的社区详情会返回 404。 @@ -545,6 +571,115 @@ 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)。 +## 项目 URDF 文件夹 + +URDF 为可选项目资源,不进入 Gitea,也不生成 Commit。先创建项目取得 `projectCode`,再选择整个文件夹直传 OSS。文件夹内必须恰好有一个 `.urdf` 文件(扩展名忽略大小写,可位于子目录);没有或多个都直接提示失败,无需用户手动选择主文件。前端提前检查,后端在签名、确认时独立校验。 + +保留所选文件夹内部层级:`relativePath` 去掉浏览器选择的最外层文件夹名称,以资源包根目录为基准;不要扁平化、重命名或改写 URDF 引用。例如 `robot-assets/urdf/robot.urdf` 对应 `urdf/robot.urdf`,`robot-assets/meshes/base.stl` 对应 `meshes/base.stl`。 + +### 获取 URDF 签名 + +`POST /api/workspace/projects/{projectCode}/urdf/signature`,需要登录且为项目所有者,项目必须 READY。JSON 请求: + +```json +{ + "files": [ + {"relativePath": "urdf/robot.urdf", "sizeBytes": 1234}, + {"relativePath": "meshes/base.stl", "sizeBytes": 5678}, + {"relativePath": "textures/base.png", "sizeBytes": 2048} + ] +} +``` + +成功 data 为 `UrdfUploadSignature`。`batchCode` 为后端生成的 32 位小写十六进制编码,`mainRelativePath` 自动识别。`uploadUrl` 为 OSS 表单上传地址;每个文件具有独立的 `objectKey`、`formFields`。签名有效 15 分钟,`expiresAt` 为所有文件签名的最早过期时间,响应禁止缓存。Policy 精确绑定对象键、文件声明大小、Content-Type 及成功状态 200,不允许客户端修改;MIME 由后端生成,主文件为 `application/xml`。 + +对象键为 `{环境根目录}/urdf/{projectCode}/{batchCode}/{relativePath}`:test 根目录为 `vibemake_dev`,prod 为 `vibemake`。每次签名产生新批次,不覆盖旧批次。将每个文件的 `formFields` 原样放入 FormData,最后追加该文件,再 POST 到 `uploadUrl`;不手动设置 multipart Content-Type,不携带平台 Authorization,OSS 成功应为 HTTP 200,响应体为空。 + +### 确认、替换和清除 + +全部文件上传成功后调用 `PUT /api/workspace/projects/{projectCode}/urdf`: + +```json +{ + "batchCode": "33333333333333333333333333333333", + "files": [ + {"relativePath": "urdf/robot.urdf", "sizeBytes": 1234}, + {"relativePath": "meshes/base.stl", "sizeBytes": 5678}, + {"relativePath": "textures/base.png", "sizeBytes": 2048} + ] +} +``` + +提交签名响应的真实 `batchCode` 和最初的完整清单,不提交 URL、目录前缀或主文件对象键。后端重新识别唯一主文件,生成当前环境、本项目的路径,通过 OSS 核验所有文件存在且实际大小一致后,一次性保存资源记录。成功 data 为更新后的 Project,包含 `urdfMainUrl`、`urdfBaseUrl`;URL 已编码,前端不要再次整体编码。未确认、上传失败、取消或核验失败均不会替换原绑定。 + +替换重复执行“签名 → 直传 → 确认”,并发以最后一次成功确认生效。签名过期时重新申请新批次并重新上传,不修改旧签名。没有上传会话或后台任务查询接口。 + +`DELETE /api/workspace/projects/{projectCode}/urdf` 清空当前绑定,无请求体,成功 data 为 null;重复清除也成功,OSS 未开启时仍可清除。未上传、清除后 `urdfMainUrl`、`urdfBaseUrl` 都为 null。项目创建和 PATCH 请求不接收 URDF 字段。 + +URDF 替换或清除立即影响社区,不需要重新发布仓库。Fork 在创建时读取当前 URDF 并复制到新项目目录,复制成功后才返回 READY;失败响应包含新项目的 `projectCode`,按现有初始化失败规则核对。源项目后续替换、清除不影响 Fork。替换、清除、删除项目均不自动删除 OSS 对象,旧公开 URL 仍可读取;撤回社区也不使已知的公开资源 URL 失效。 + +### 限制、错误与部署 + +| 项目 | 默认值 | +| --- | --- | +| 单文件 | 50 MiB,`URDF_MAX_FILE_BYTES=52428800` | +| 整包总量 | 200 MiB,`URDF_MAX_TOTAL_BYTES=209715200` | +| 文件数量 | 500,`URDF_MAX_FILES=500` | +| 对象键 | 最多 512 个 Java 字符且 UTF-8 最多 1023 字节;前缀占用也计入 | + +URDF 直传不受仓库上传的 multipart 10 MiB / 52 MiB 限制影响。路径必须是唯一相对路径,不能包含绝对路径、空段、`.`、`..`、反斜杠、控制字符、`.git` 目录或冒号。系统不解析 URDF 语义、不执行 Xacro、不自动修复 `package://` 等引用;渲染器的资源解析由前端处理。 + +| HTTP / code | 提示与处理 | +| --- | --- | +| 400 URDF_MAIN_FILE_INVALID | 没有:文件夹中未找到 URDF 文件;多个:文件夹中存在多个 URDF 文件,请仅保留一个后重新上传 | +| 400 BAD_REQUEST | 清单、路径、批次编码或字节数不合法 | +| 400 URDF_FILE_MISSING | URDF 文件未上传完整,请重新上传 | +| 400 URDF_FILE_SIZE_MISMATCH | URDF 文件大小不符,请重新上传 | +| 401 UNAUTHORIZED / 404 NOT_FOUND | 登录或检查项目归属、删除状态 | +| 409 CONFLICT | 项目尚未就绪,或 Fork 复制时源资源发生变化 | +| 413 URDF_UPLOAD_TOO_LARGE | 文件数量或大小超过限制 | +| 502 OSS_ERROR / 503 OSS_UNAVAILABLE | OSS 访问失败或未启用;保留原资源 | + +复用封面的 OSS 凭据及公开基础地址配置。上线前先执行 [URDF 加字段 SQL](database.md#已有数据库增加项目-urdf)。RAM 用户增加当前环境 `urdf/*` 范围的 `oss:PutObject`、`oss:GetObject` 权限,用于上传、元信息核验和服务端复制;不需要开放整个 Bucket 写权限。对 URDF 目录配置公开读取或使用公开 CDN,并为真实前端 Origin 配置 POST、GET、HEAD 的 CORS。应用不修改 Bucket ACL 或版本控制配置。表单附带禁止覆盖参数;Bucket 已开启或暂停版本控制时 OSS 不保证该参数有效,按新批次上传且不要复用成功签名修改资源。 + +### 浏览器文件夹上传示例 + +页面使用 `` 选择文件夹。以下示例复用本文的 `request` 方法;可直接展示抛出的错误消息,不提供主文件选择交互。 + +```ts +async function uploadProjectUrdf(projectCode: string, selected: FileList, token: string) { + const entries = Array.from(selected).map(file => { + const path = file.webkitRelativePath || file.name; + return { file, relativePath: file.webkitRelativePath ? path.slice(path.indexOf('/') + 1) : path }; + }); + const count = entries.filter(item => item.relativePath.toLowerCase().endsWith('.urdf')).length; + if (count === 0) throw new Error('文件夹中未找到 URDF 文件'); + if (count > 1) throw new Error('文件夹中存在多个 URDF 文件,请仅保留一个后重新上传'); + const files: UrdfFile[] = entries.map(item => ({ relativePath: item.relativePath, sizeBytes: item.file.size })); + const endpoint = `/workspace/projects/${encodeURIComponent(projectCode)}/urdf`; + const signature = await request(`${endpoint}/signature`, { + method: 'POST', token, body: { files }, + }); + const byPath = new Map(entries.map(item => [item.relativePath, item.file])); + for (const item of signature.files) { + const form = new FormData(); + for (const [key, value] of Object.entries(item.formFields)) form.append(key, value); + form.append('file', byPath.get(item.relativePath)!); + const uploaded = await fetch(signature.uploadUrl, { method: 'POST', body: form }); + if (uploaded.status !== 200) throw new Error(`URDF 上传失败:HTTP ${uploaded.status}`); + } + return request(endpoint, { + method: 'PUT', token, body: { batchCode: signature.batchCode, files }, + }); +} + +async function clearProjectUrdf(projectCode: string, token: string) { + return request(`/workspace/projects/${encodeURIComponent(projectCode)}/urdf`, { + method: 'DELETE', token, + }); +} +``` + ## 目录和文件读取 ### 工作区目录 @@ -1102,6 +1237,8 @@ const result = await chatAi( | 我的工作区 | users/me → workspace/projects,分别显示仓库状态和发布状态 | | 创建项目 | POST workspace/projects → 使用返回 projectCode 进入详情 → tree 获取当前版本 | | 上传封面 | uploads/project-covers/signature → 浏览器直接 POST OSS → 成功后将 coverUrl 写入项目创建或修改接口 | +| 上传或替换 URDF | 校验文件夹唯一主文件 → urdf/signature → 全部文件直传 OSS → PUT urdf 确认绑定 | +| 清除 URDF | DELETE urdf → 刷新项目详情 | | 文件编辑 | workspace 详情与 tree → files → 判断 editable → commits → 刷新版本、目录和文件 | | 上传文件 | tree 获取基准 SHA → uploads/commit → 刷新目录和当前版本 | | 发布或更新社区 | 获取最新工作区 SHA → publication → 刷新项目和社区页面 | diff --git a/docs/database.md b/docs/database.md index 9b518ce..939d27d 100644 --- a/docs/database.md +++ b/docs/database.md @@ -1,6 +1,6 @@ # 数据库初始化 -业务数据库名为 `community`,只包含以下四张表。由人工执行;应用不运行迁移或自动建表。以下 SQL 面向 MySQL 8。 +业务数据库名为 `community`,只包含以下四张表。由人工执行;应用不运行迁移或自动建表。以下 SQL 面向 MySQL 8.0.13 及以上(URDF JSON 默认值使用表达式)。 ```sql CREATE DATABASE IF NOT EXISTS community CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; @@ -26,6 +26,9 @@ CREATE TABLE project ( name VARCHAR(100) NOT NULL COMMENT '项目名称', description TEXT NOT NULL COMMENT '项目描述', cover_url VARCHAR(2048) NULL COMMENT '封面图片 HTTPS 地址', + urdf_main_object_key VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT 'URDF主文件OSS对象键,不保存完整URL', + urdf_files JSON NOT NULL DEFAULT (JSON_ARRAY()) COMMENT 'URDF文件清单数组,元素包含relativePath和sizeBytes,相对路径以urdf_prefix为基准', + urdf_prefix VARCHAR(512) CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' COMMENT 'URDF资源OSS目录前缀,包含环境根目录和上传批次,以斜杠结尾', project_type VARCHAR(64) NOT NULL COMMENT '配置中的项目类型编码', gitea_repo_id BIGINT NULL COMMENT 'Gitea 仓库标识', gitea_owner VARCHAR(100) NOT NULL COMMENT 'Gitea 仓库所属组织', @@ -92,3 +95,23 @@ ALTER TABLE project ``` 历史项目的封面为 NULL。字段保存固定公开地址,可以来自 OSS、CDN 或外部 HTTPS 图片;不存储临时签名下载地址。替换、清除封面和删除项目不会自动删除 OSS 对象,Fork 可能共用同一地址。 + +## 已有数据库增加项目 URDF + +先在对应业务库手动执行以下 SQL,再部署应用;新建数据库已包含三个字段,不重复执行。不要在应用启动时自动迁移。 + +```sql +ALTER TABLE project + ADD COLUMN urdf_main_object_key VARCHAR(512) + CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' + COMMENT 'URDF主文件OSS对象键,不保存完整URL', + ADD COLUMN urdf_files JSON NOT NULL DEFAULT (JSON_ARRAY()) + COMMENT 'URDF文件清单数组,元素包含relativePath和sizeBytes,相对路径以urdf_prefix为基准', + ADD COLUMN urdf_prefix VARCHAR(512) + CHARACTER SET utf8mb4 COLLATE utf8mb4_bin NOT NULL DEFAULT '' + COMMENT 'URDF资源OSS目录前缀,包含环境根目录和上传批次,以斜杠结尾'; +``` + +未上传或已清除时,两个字符串均为 `''`,文件清单为 `[]`。每个项目只绑定一个当前资源包,包内必须恰好有一个 `.urdf`(忽略扩展名大小写)。清单包含全部文件,例如 `[{"relativePath":"urdf/robot.urdf","sizeBytes":1234},{"relativePath":"meshes/base.stl","sizeBytes":5678}]`。 + +前缀为 `{环境根目录}/urdf/{projectCode}/{batchCode}/`,主文件对象键为此前缀加主文件相对路径。数据库不保存完整 URL;接口根据 OSS/CDN 配置生成并编码 URL。替换、清除、删除项目不物理删除对象,公开旧链接仍可读取;Fork 复制到新项目的独立目录,不共用源前缀。URDF 不进入 Gitea、不生成 Commit,更新立即影响社区展示。