From a1076d109841100797e7fe27ce0528e3ad3d55d2 Mon Sep 17 00:00:00 2001 From: lxp <2770281812@qq.com> Date: Thu, 15 Oct 2026 11:09:21 +0800 Subject: [PATCH] =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E6=96=B0=E5=A2=9E=E5=B0=81?= =?UTF-8?q?=E9=9D=A2=E5=9B=BE=E5=AD=97=E6=AE=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .env.example | 9 ++ AGENTS.md | 11 ++ README.md | 21 ++- .../api/controller/UploadController.java | 30 +++++ .../src/main/resources/application-prod.yml | 2 + .../src/main/resources/application-test.yml | 2 + .../src/main/resources/application.yml | 7 + .../linkerbot/community/api/AiSearchTest.java | 3 + .../community/api/OssProfileTest.java | 19 +++ .../linkerbot/community/api/WorkflowTest.java | 114 ++++++++++++++++ .../linkerbot/community/bean/Contracts.java | 15 ++- .../community/bean/entity/Project.java | 1 + .../community/service/CoverUploadService.java | 9 ++ .../service/config/OssProperties.java | 66 ++++++++++ .../service/impl/CoverUploadServiceImpl.java | 41 ++++++ .../service/impl/ProjectServiceImpl.java | 39 +++++- .../community/service/oss/OssPostSigner.java | 105 +++++++++++++++ .../service/oss/OssPostSignerTest.java | 82 ++++++++++++ .../service/oss/OssPropertiesTest.java | 77 +++++++++++ docs/community-api.md | 122 +++++++++++++++++- docs/database.md | 12 ++ 21 files changed, 780 insertions(+), 7 deletions(-) create mode 100644 AGENTS.md create mode 100644 community-api/src/main/java/com/linkerbot/community/api/controller/UploadController.java create mode 100644 community-api/src/test/java/com/linkerbot/community/api/OssProfileTest.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/CoverUploadService.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/config/OssProperties.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/impl/CoverUploadServiceImpl.java create mode 100644 community-service/src/main/java/com/linkerbot/community/service/oss/OssPostSigner.java create mode 100644 community-service/src/test/java/com/linkerbot/community/service/oss/OssPostSignerTest.java create mode 100644 community-service/src/test/java/com/linkerbot/community/service/oss/OssPropertiesTest.java diff --git a/.env.example b/.env.example index d1d9642..2729ac6 100644 --- a/.env.example +++ b/.env.example @@ -10,6 +10,15 @@ SPRING_PROFILES_ACTIVE=test # 与 cadworld 一致,默认日志目录为 logs,可改为部署环境中的绝对路径。 LOG_PATH=logs PORT=8993 +# OSS 封面直传默认关闭;地域 ID 不带 oss- 前缀,例如 cn-beijing。 +# 目录由 profile 固定:test 为 vibemake_dev/,prod 为 vibemake/。 +OSS_ENABLED=false +OSS_REGION=cn-beijing +OSS_BUCKET='' +OSS_ACCESS_KEY_ID='' +OSS_ACCESS_KEY_SECRET='' +# 可选,固定公开 CDN/OSS 基础地址;留空使用 Bucket 的标准 HTTPS 域名。 +OSS_PUBLIC_BASE_URL='' # AI 默认关闭;启用后密钥仅在后端使用。两个环境均支持这些变量。 AI_ENABLED=false ARK_API_KEY='' diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..071fced --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,11 @@ +## 代码实现原则 +- 优先保证业务正确性、可维护性、可读性,再考虑炫技。 +- Java代码统一使用显式类型声明,不使用var,包括局部变量、循环变量和try-with-resources资源变量。 +- 修改代码时忽略.sql文件,如果遇到需要改表结构,直接发我sql,要求表字段规范且有中文注释。 +- /api的用户请求返回数据不要暴露数据表id字段,只返回编码,增删改查都用唯一编码字段 +## 日志规范 +- 关键业务节点必须补充必要日志,方便线上排查。 +- 不要打印密码、Token、手机号、身份证、支付密钥等敏感信息。 +- 异常日志必须包含足够定位问题的信息。 +## 回复规范 +- 永远用中文回复。 diff --git a/README.md b/README.md index 2577441..62d7772 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ Spring Boot 社区后端,工程分层参考 cadworld。使用 Java 21、Spring | community-security | 平台登录会话、验证码、身份上下文、认证过滤器和安全配置 | | community-common | 通用响应、分页、异常处理、requestId 和基础工具 | -UserService、ProjectService、FileService、InteractionService 采用接口加实现类,Controller、安全模块和服务之间通过接口注入。GiteaClient 与 RestGiteaClient 定义仓库调用边界;项目锁、UTC 时间和分页检查归入 support。安全模块内的 TokenService、CaptchaService 保留具体类,首期沿用本机缓存。 +UserService、ProjectService、FileService、InteractionService、CoverUploadService 采用接口加实现类,Controller、安全模块和服务之间通过接口注入。GiteaClient 与 RestGiteaClient 定义仓库调用边界;项目锁、UTC 时间和分页检查归入 support。安全模块内的 TokenService、CaptchaService 保留具体类,首期沿用本机缓存。 ## 功能与边界 @@ -52,6 +52,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/ | | 连接池 | 最少 1、最多 10 个连接 | 最少 1、最多 20 个连接 | | 项目日志级别 | DEBUG | INFO | | 日志目录 | logs,可用 LOG_PATH 覆盖 | logs,可用 LOG_PATH 覆盖 | @@ -84,6 +85,22 @@ python3 scripts/test-gitea.py 该测试使用临时 H2 数据库,在配置的组织创建临时项目仓库,验证私有仓库、多文件提交、中文路径、二进制上传、固定发布版本及快照 Fork,结束后仅删除本次测试创建的仓库。Gitea 26.4.0 内置的 1.26.4 支持批量文件变更;以服务器 /swagger.v1.json 为对接依据。 +## 项目封面与 OSS 直传 + +项目通过 `coverUrl` 保存固定公开图片地址,支持 OSS/CDN 或外部 HTTPS 图片。无封面时返回 null;创建时可省略,修改时省略或 null 保留原值,传空字符串清除。Fork 继承同一地址,替换、清除或删除项目不自动删除 OSS 图片。 + +已有数据库必须先执行 [封面字段升级 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`,无需配置环境变量;特殊域名场景可显式配置 `community.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/community-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/`,图片地址不带临时下载签名。 + ## 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`;开启但没有密钥时停止启动。 @@ -104,7 +121,7 @@ python3 scripts/test-ai.py ## 运行约定 -项目名称、描述、类型修改直接更新展示;工作区代码提交后,社区仍读取已发布 SHA,需要手动更新。Fork 复制已发布文件快照,不继承上游提交历史,也不自动同步。项目删除采用逻辑删除,保留仓库和已有 Fork。 +项目名称、描述、类型、封面修改直接更新展示;工作区代码提交后,社区仍读取已发布 SHA,需要手动更新。Fork 复制已发布文件快照,不继承上游提交历史,也不自动同步。项目删除采用逻辑删除,保留仓库和已有 Fork。 创建或 Fork 前先写入 CREATING 项目,成功后标记 READY。结果不明或数据库回写失败需要人工核对;不提供后台自动恢复、无条件自动重试或跨重启完整幂等。具体恢复方式见接口文档。 diff --git a/community-api/src/main/java/com/linkerbot/community/api/controller/UploadController.java b/community-api/src/main/java/com/linkerbot/community/api/controller/UploadController.java new file mode 100644 index 0000000..53f8e28 --- /dev/null +++ b/community-api/src/main/java/com/linkerbot/community/api/controller/UploadController.java @@ -0,0 +1,30 @@ +package com.linkerbot.community.api.controller; + +import com.linkerbot.community.bean.Contracts.CoverUploadInput; +import com.linkerbot.community.bean.Contracts.CoverUploadSignature; +import com.linkerbot.community.common.ApiResponse; +import com.linkerbot.community.security.CurrentUser; +import com.linkerbot.community.service.CoverUploadService; +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.*; + +@RestController +@RequiredArgsConstructor +@RequestMapping("/api/uploads") +@Tag(name = "图片上传") +public class UploadController { + private final CoverUploadService uploads; + + @PostMapping("/project-covers/signature") + @Operation(summary = "生成项目封面 OSS POST V4 直传签名") + public ResponseEntity> signature( + @Valid @RequestBody CoverUploadInput input) { + return ResponseEntity.ok().cacheControl(CacheControl.noStore()) + .body(ApiResponse.success(uploads.signature(CurrentUser.required(), input))); + } +} diff --git a/community-api/src/main/resources/application-prod.yml b/community-api/src/main/resources/application-prod.yml index 9747b2a..f42e117 100644 --- a/community-api/src/main/resources/application-prod.yml +++ b/community-api/src/main/resources/application-prod.yml @@ -11,6 +11,8 @@ spring: connection-timeout: 5000 community: + oss: + root-directory: vibemake gitea: base-url: ${GITEA_BASE_URL} owner: ${GITEA_ORGANIZATION:community} diff --git a/community-api/src/main/resources/application-test.yml b/community-api/src/main/resources/application-test.yml index 0298d53..935d2b2 100644 --- a/community-api/src/main/resources/application-test.yml +++ b/community-api/src/main/resources/application-test.yml @@ -11,6 +11,8 @@ spring: connection-timeout: 5000 community: + oss: + root-directory: vibemake_dev gitea: base-url: ${GITEA_BASE_URL:http://localhost:3000} owner: ${GITEA_ORGANIZATION:community} diff --git a/community-api/src/main/resources/application.yml b/community-api/src/main/resources/application.yml index 01689fa..c5a9e82 100644 --- a/community-api/src/main/resources/application.yml +++ b/community-api/src/main/resources/application.yml @@ -20,6 +20,13 @@ mybatis-plus: configuration: map-underscore-to-camel-case: true community: + oss: + enabled: ${OSS_ENABLED:true} + region: ${OSS_REGION:cn-beijing} + bucket: ${OSS_BUCKET:linkerbot} + 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} ai: enabled: ${AI_ENABLED:true} api-key: ${ARK_API_KEY:} diff --git a/community-api/src/test/java/com/linkerbot/community/api/AiSearchTest.java b/community-api/src/test/java/com/linkerbot/community/api/AiSearchTest.java index 4a11bd3..2cdff5d 100644 --- a/community-api/src/test/java/com/linkerbot/community/api/AiSearchTest.java +++ b/community-api/src/test/java/com/linkerbot/community/api/AiSearchTest.java @@ -169,6 +169,8 @@ class AiSearchTest { @ValueSource(strings = {"GENERAL", "HUMANOID", "QUADRUPED", "WHEELED"}) void filtersConfiguredTypesAndKeepsProjectContract(String type) throws Exception { Project expected = project("教学机器人", type, "支持 ROS2 教学"); + expected.setCoverUrl("https://images.example.com/robot.png"); + projects.updateById(expected); project("其他机器人", "OTHER", "ROS2"); model.handler = (name, input) -> name.endsWith("intent") ? intent(type, List.of("ROS2", "ROS 2")) : rank(input); MvcResult initial = start(Map.of("message", "找教学项目")); @@ -178,6 +180,7 @@ class AiSearchTest { .containsExactly("understanding", "searching", "ranking", "validating"); JsonNode card = events.getLast().path("data").path("projects").get(0); assertThat(card.path("project").path("projectCode").asText()).isEqualTo(expected.getProjectCode()); + assertThat(card.path("project").path("coverUrl").asText()).isEqualTo(expected.getCoverUrl()); assertThat(card.path("project").path("owner").has("id")).isFalse(); assertThat(card.path("project").has("id")).isFalse(); assertThat(card.path("project").has("giteaRepoId")).isFalse(); diff --git a/community-api/src/test/java/com/linkerbot/community/api/OssProfileTest.java b/community-api/src/test/java/com/linkerbot/community/api/OssProfileTest.java new file mode 100644 index 0000000..f86ec5e --- /dev/null +++ b/community-api/src/test/java/com/linkerbot/community/api/OssProfileTest.java @@ -0,0 +1,19 @@ +package com.linkerbot.community.api; + +import static org.assertj.core.api.Assertions.*; + +import java.io.IOException; +import org.junit.jupiter.api.Test; +import org.springframework.boot.env.YamlPropertySourceLoader; +import org.springframework.core.io.ClassPathResource; + +class OssProfileTest { + @Test + void environmentProfilesKeepCoverDirectoriesSeparate() throws IOException { + YamlPropertySourceLoader loader = new YamlPropertySourceLoader(); + assertThat(loader.load("test", new ClassPathResource("application-test.yml")).getFirst() + .getProperty("community.oss.root-directory")).isEqualTo("vibemake_dev"); + assertThat(loader.load("prod", new ClassPathResource("application-prod.yml")).getFirst() + .getProperty("community.oss.root-directory")).isEqualTo("vibemake"); + } +} 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 f4d7367..d6b87e4 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 @@ -8,6 +8,7 @@ import com.fasterxml.jackson.databind.JsonNode; 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 org.junit.jupiter.api.*; import org.springframework.beans.factory.annotation.Autowired; @@ -62,11 +63,13 @@ class WorkflowTest { @Autowired ObjectMapper json; @Autowired JdbcTemplate jdbc; @Autowired FakeGiteaClient gitea; + @Autowired OssProperties oss; @BeforeEach void reset() throws Exception { SchemaSupport.reset(jdbc); gitea.reset(); + oss.setEnabled(false); } private JsonNode perform(MockHttpServletRequestBuilder builder, int status) throws Exception { @@ -168,6 +171,117 @@ class WorkflowTest { 200); } + @Test + void coverRoundTripsThroughMetadataPublicationAndForkWithoutFileCommit() throws Exception { + String owner = login("cover-owner@example.com"); + String other = login("cover-other@example.com"); + String first = "https://images.example.com/first.png"; + String next = "https://external.example.com/second.webp?version=2"; + Map input = new LinkedHashMap<>(Map.of( + "name", "封面项目", "description", "项目说明", "projectType", "GENERAL", "coverUrl", " " + first + " ")); + JsonNode created = perform(body(auth(post("/api/workspace/projects"), owner), input), 200).path("data"); + String code = created.path("projectCode").asText(); + String path = "/api/workspace/projects/" + code; + assertThat(created.path("coverUrl").asText()).isEqualTo(first); + assertThat(perform(auth(get(path), owner), 200).path("data").path("coverUrl").asText()).isEqualTo(first); + assertThat(perform(auth(get("/api/workspace/projects"), owner), 200) + .path("data").path("items").get(0).path("coverUrl").asText()).isEqualTo(first); + String sha = head(owner, code); + assertThat(perform(body(auth(put(path + "/publication"), owner), Map.of("commitSha", sha)), 200) + .path("data").path("coverUrl").asText()).isEqualTo(first); + assertThat(perform(get("/api/community/projects"), 200).path("data").path("items").get(0) + .path("coverUrl").asText()).isEqualTo(first); + + input.put("coverUrl", next); + perform(body(auth(patch(path), other), input), 404); + perform(body(auth(patch(path), owner), input), 200); + assertThat(perform(get("/api/community/projects/" + code), 200).path("data").path("coverUrl").asText()).isEqualTo(next); + assertThat(head(owner, code)).isEqualTo(sha); + + input.remove("coverUrl"); + assertThat(perform(body(auth(patch(path), owner), input), 200).path("data").path("coverUrl").asText()).isEqualTo(next); + input.put("coverUrl", null); + perform(body(auth(patch(path), owner), input), 200); + assertThat(perform(auth(get(path), owner), 200).path("data").path("coverUrl").asText()).isEqualTo(next); + + JsonNode fork = perform(body(auth(post("/api/community/projects/" + code + "/forks"), other), + Map.of("name", "封面副本", "publishedCommitSha", sha)), 200).path("data"); + assertThat(fork.path("coverUrl").asText()).isEqualTo(next); + input.put("coverUrl", " "); + assertThat(perform(body(auth(patch(path), owner), input), 200).path("data").path("coverUrl").isNull()).isTrue(); + assertThat(jdbc.queryForObject("SELECT cover_url FROM project WHERE project_code = ?", String.class, code)).isNull(); + assertThat(perform(get("/api/community/projects/" + code), 200).path("data").path("coverUrl").isNull()).isTrue(); + assertThat(perform(auth(get("/api/workspace/projects/" + fork.path("projectCode").asText()), other), 200) + .path("data").path("coverUrl").asText()).isEqualTo(next); + assertThat(head(owner, code)).isEqualTo(sha); + } + + @Test + void optionalCoversRemainCompatibleAndInvalidUrlsAreRejectedBeforeCreatingRepositories() throws Exception { + String owner = login("cover-validation@example.com"); + String code = create(owner, "旧请求"); + assertThat(perform(auth(get("/api/workspace/projects/" + code), owner), 200).path("data").path("coverUrl").isNull()).isTrue(); + Map input = new LinkedHashMap<>(Map.of("name", "封面", "projectType", "GENERAL")); + for (String empty : Arrays.asList(null, "", " ")) { + input.put("coverUrl", empty); + assertThat(perform(body(auth(post("/api/workspace/projects"), owner), input), 200) + .path("data").path("coverUrl").isNull()).isTrue(); + } + long before = jdbc.queryForObject("SELECT COUNT(*) FROM project", Long.class); + for (String invalid : List.of("http://images.example.com/a.png", "/a.png", "data:image/png;base64,abc", + "https://user:password@images.example.com/a.png", "https:///missing-host.png", + "https://invalid_host/a.png", "https://images.example.com:70000/a.png", + "https://images.example.com/" + "a".repeat(2048))) { + input.put("coverUrl", invalid); + perform(body(auth(post("/api/workspace/projects"), owner), input), 400); + perform(body(auth(patch("/api/workspace/projects/" + code), owner), input), 400); + } + assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM project", Long.class)).isEqualTo(before); + String prefix = "https://images.example.com/"; + String max = prefix + "a".repeat(2048 - prefix.length()); + input.put("coverUrl", " " + max + " "); + assertThat(perform(body(auth(patch("/api/workspace/projects/" + code), owner), input), 200) + .path("data").path("coverUrl").asText()).isEqualTo(max); + } + + @Test + void coverSignaturesAuthenticateValidateAndReturnDirectUploadForms() throws Exception { + String endpoint = "/api/uploads/project-covers/signature"; + Map input = Map.of("contentType", "image/png", "fileSize", 123); + perform(body(post(endpoint), input), 401); + String token = login("upload@example.com"); + assertThat(perform(body(auth(post(endpoint), token), input), 503).path("code").asText()).isEqualTo("OSS_UNAVAILABLE"); + assertThat(oss.getRootDirectory()).isEqualTo("vibemake_dev"); + oss.setRegion("cn-hangzhou"); + oss.setEndpoint(""); + oss.setBucket("examplebucket"); + oss.setAccessKeyId("UnitTestAccessKey"); + oss.setAccessKeySecret("unit-test-secret"); + oss.setPublicBaseUrl("https://images.example.com"); + oss.setEnabled(true); + String userCode = perform(auth(get("/api/users/me"), token), 200).path("data").path("userCode").asText(); + for (String type : List.of("image/jpeg", "image/png", "image/webp")) { + JsonNode result = perform(body(auth(post(endpoint), token), Map.of("contentType", type, "fileSize", 5242880)), 200).path("data"); + assertThat(result.path("objectKey").asText()).startsWith("vibemake_dev/project-covers/" + userCode + "/"); + assertThat(result.path("uploadUrl").asText()).isEqualTo("https://examplebucket.oss-cn-hangzhou.aliyuncs.com"); + assertThat(result.path("coverUrl").asText()).isEqualTo("https://images.example.com/" + result.path("objectKey").asText()); + assertThat(result.path("formFields").path("content-type").asText()).isEqualTo(type); + assertThat(result.toString()).doesNotContain("unit-test-secret"); + } + for (Object invalid : List.of( + Map.of("contentType", "image/svg+xml", "fileSize", 1), + Map.of("contentType", "image/png", "fileSize", 0), + Map.of("contentType", "image/png", "fileSize", -1), + Map.of("contentType", "image/png"), Map.of("fileSize", 1))) + perform(body(auth(post(endpoint), token), invalid), 400); + JsonNode tooLarge = perform(body(auth(post(endpoint), token), Map.of("contentType", "image/png", "fileSize", 5242881)), 413); + assertThat(tooLarge.path("code").asText()).isEqualTo("UPLOAD_TOO_LARGE"); + mvc.perform(body(auth(post(endpoint), token), input)).andExpect(header().string("Cache-Control", "no-store")); + assertThat(jdbc.queryForObject("SELECT COUNT(*) FROM project", Long.class)).isZero(); + JsonNode spec = perform(get("/v3/api-docs"), 200); + assertThat(spec.path("paths").has(endpoint)).isTrue(); + } + @Test void loginNormalizesEmailAndConsumesCaptchaAndLogout() throws Exception { JsonNode first = loginData("OWNER@example.com"); 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 20981f2..2399e78 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 @@ -5,6 +5,7 @@ import jakarta.validation.constraints.*; import java.time.LocalDateTime; import java.util.List; +import java.util.Map; public final class Contracts { private Contracts() {} @@ -25,7 +26,18 @@ public final class Contracts { public record ProjectInput( @NotBlank @Size(max = 100) String name, @Size(max = 2000) String description, - @NotBlank @Size(max = 64) String projectType) {} + @NotBlank @Size(max = 64) String projectType, + String coverUrl) {} + + public record CoverUploadInput( + @NotBlank String contentType, @NotNull @Positive Long fileSize) {} + + public record CoverUploadSignature( + String uploadUrl, + String objectKey, + String coverUrl, + LocalDateTime expiresAt, + Map formFields) {} public record PublicationInput(@NotBlank String commitSha) {} @@ -40,6 +52,7 @@ public final class Contracts { String projectCode, String name, String description, + String coverUrl, 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 d726f5d..a715a01 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 @@ -15,6 +15,7 @@ public class Project extends BaseEntity { private Long ownerUserId; private String name; private String description; + private String coverUrl; private String projectType; private Long giteaRepoId; private String giteaOwner; diff --git a/community-service/src/main/java/com/linkerbot/community/service/CoverUploadService.java b/community-service/src/main/java/com/linkerbot/community/service/CoverUploadService.java new file mode 100644 index 0000000..e32c741 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/CoverUploadService.java @@ -0,0 +1,9 @@ +package com.linkerbot.community.service; + +import com.linkerbot.community.bean.Contracts.CoverUploadInput; +import com.linkerbot.community.bean.Contracts.CoverUploadSignature; + +/** 为浏览器直传项目封面生成 OSS POST 表单,不接收图片内容。 */ +public interface CoverUploadService { + CoverUploadSignature signature(long userId, CoverUploadInput input); +} 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 new file mode 100644 index 0000000..cbd56e5 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/config/OssProperties.java @@ -0,0 +1,66 @@ +package com.linkerbot.community.service.config; + +import jakarta.validation.constraints.AssertTrue; +import java.net.URI; +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") +public class OssProperties { + private boolean enabled; + private String region = ""; + private String endpoint = ""; + private String bucket = ""; + private String accessKeyId = ""; + private String accessKeySecret = ""; + private String publicBaseUrl = ""; + private String rootDirectory = ""; + + @AssertTrue(message = "开启 OSS 时必须配置合法的地域 ID(如 cn-beijing)、Bucket、凭据及根目录;Endpoint 为可选 HTTPS 地址") + public boolean isConfigurationValid() { + if (!enabled) return true; + return region != null && region.matches("[a-z0-9]+(?:-[a-z0-9]+)+") + && !region.startsWith("oss-") + && bucket != null && bucket.matches("[a-z0-9][a-z0-9-]{1,61}[a-z0-9]") + && accessKeyId != null && accessKeyId.matches("[A-Za-z0-9]+") + && accessKeySecret != null && !accessKeySecret.isBlank() + && rootDirectory != null && rootDirectory.matches("[A-Za-z0-9_-]+") + && validBaseUrl(resolvedEndpoint(), false) + && (publicBaseUrl != null + && (publicBaseUrl.isBlank() || validBaseUrl(publicBaseUrl, true))); + } + + private boolean validBaseUrl(String value, boolean allowPath) { + try { + URI uri = URI.create(value); + return "https".equals(uri.getScheme()) && uri.getHost() != null + && uri.getRawUserInfo() == null && uri.getRawQuery() == null + && uri.getRawFragment() == null + && (uri.getPort() == -1 || (uri.getPort() > 0 && uri.getPort() <= 65535)) + && (allowPath || uri.getRawPath().isEmpty() || "/".equals(uri.getRawPath())); + } catch (IllegalArgumentException | NullPointerException error) { + return false; + } + } + + public String uploadUrl() { + URI uri = URI.create(resolvedEndpoint()); + return "https://" + bucket + "." + uri.getRawAuthority(); + } + + private String resolvedEndpoint() { + return endpoint == null || endpoint.isBlank() + ? "https://oss-" + region + ".aliyuncs.com" : endpoint; + } + + public String publicBaseUrl() { + return publicBaseUrl.isBlank() ? uploadUrl() : publicBaseUrl.replaceAll("/+$", ""); + } +} diff --git a/community-service/src/main/java/com/linkerbot/community/service/impl/CoverUploadServiceImpl.java b/community-service/src/main/java/com/linkerbot/community/service/impl/CoverUploadServiceImpl.java new file mode 100644 index 0000000..686694d --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/impl/CoverUploadServiceImpl.java @@ -0,0 +1,41 @@ +package com.linkerbot.community.service.impl; + +import com.linkerbot.community.bean.Contracts.CoverUploadInput; +import com.linkerbot.community.bean.Contracts.CoverUploadSignature; +import com.linkerbot.community.bean.entity.User; +import com.linkerbot.community.common.BusinessException; +import com.linkerbot.community.service.CoverUploadService; +import com.linkerbot.community.service.UserService; +import com.linkerbot.community.service.config.OssProperties; +import com.linkerbot.community.service.oss.OssPostSigner; +import java.util.Map; +import lombok.RequiredArgsConstructor; +import org.springframework.stereotype.Service; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +@Service +@RequiredArgsConstructor +public class CoverUploadServiceImpl implements CoverUploadService { + private static final Logger log = LoggerFactory.getLogger(CoverUploadServiceImpl.class); + private static final Map EXTENSIONS = Map.of( + "image/jpeg", "jpg", "image/png", "png", "image/webp", "webp"); + private final UserService users; + private final OssProperties properties; + private final OssPostSigner signer; + + @Override + public CoverUploadSignature signature(long userId, CoverUploadInput input) { + if (!properties.isEnabled()) + throw new BusinessException(503, "OSS_UNAVAILABLE", "OSS 封面上传暂未开启"); + String extension = EXTENSIONS.get(input.contentType()); + if (extension == null) throw BusinessException.badRequest("封面仅支持 JPG、PNG、WebP 图片"); + if (input.fileSize() > OssPostSigner.MAX_FILE_BYTES) + throw new BusinessException(413, "UPLOAD_TOO_LARGE", "封面图片不能超过 5 MiB"); + User user = users.require(userId); + CoverUploadSignature result = signer.sign(user.getUserCode(), input.contentType(), extension); + log.info("生成封面上传签名 userCode={} objectKey={} expiresAt={}", + user.getUserCode(), result.objectKey(), result.expiresAt()); + return result; + } +} 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 fca9268..3a89f77 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 @@ -4,6 +4,7 @@ import static com.linkerbot.community.service.support.ProjectSupport.now; import static com.linkerbot.community.service.support.ProjectSupport.pageCheck; import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper; +import com.baomidou.mybatisplus.core.conditions.update.LambdaUpdateWrapper; import com.baomidou.mybatisplus.extension.plugins.pagination.Page; import com.linkerbot.community.bean.Contracts.*; import com.linkerbot.community.bean.entity.*; @@ -21,6 +22,7 @@ import org.slf4j.Logger; import org.slf4j.LoggerFactory; import org.springframework.stereotype.Service; +import java.net.URI; import java.util.*; import java.util.function.Function; @@ -48,6 +50,23 @@ public class ProjectServiceImpl implements ProjectService { throw BusinessException.badRequest("项目类型不在可选列表中"); } + private String normalizeCoverUrl(String value) { + if (value == null || value.isBlank()) return null; + String normalized = value.trim(); + try { + URI uri = URI.create(normalized); + if (normalized.length() > 2048 + || !"https".equalsIgnoreCase(uri.getScheme()) + || uri.getHost() == null + || uri.getRawUserInfo() != null + || (uri.getPort() != -1 && (uri.getPort() < 1 || uri.getPort() > 65535))) + throw new IllegalArgumentException(); + } catch (IllegalArgumentException error) { + throw BusinessException.badRequest("封面地址必须是最多 2048 字符且不含用户凭据的 HTTPS 地址"); + } + return normalized; + } + @Override public Project owner(long userId, String code) { Project project = @@ -118,6 +137,7 @@ public class ProjectServiceImpl implements ProjectService { project.getProjectCode(), project.getName(), project.getDescription(), + project.getCoverUrl(), project.getProjectType(), users.publicView(project.getOwnerUserId()), project.getRepoStatus(), @@ -169,6 +189,7 @@ public class ProjectServiceImpl implements ProjectService { project.setOwnerUserId(userId); project.setName(input.name().trim()); project.setDescription(input.description() == null ? "" : input.description()); + project.setCoverUrl(normalizeCoverUrl(input.coverUrl())); project.setProjectType(input.projectType()); project.setGiteaOwner(config.getGitea().getOwner()); project.setGiteaRepoName("p_" + project.getProjectCode()); @@ -199,7 +220,8 @@ public class ProjectServiceImpl implements ProjectService { if (!source.getPublishedCommitSha().equals(FilePaths.sha(input.publishedCommitSha()))) throw BusinessException.conflict("社区版本已更新,请刷新后 Fork"); ProjectInput data = - new ProjectInput(input.name(), source.getDescription(), source.getProjectType()); + new ProjectInput( + input.name(), source.getDescription(), source.getProjectType(), source.getCoverUrl()); Project project = initialize(userId, data, source); return locks.write( project.getProjectCode(), @@ -331,6 +353,7 @@ public class ProjectServiceImpl implements ProjectService { @Override public ProjectView update(long userId, String code, ProjectInput input) { validateInput(input); + String coverUrl = normalizeCoverUrl(input.coverUrl()); return metadata( userId, code, @@ -338,8 +361,20 @@ public class ProjectServiceImpl implements ProjectService { project.setName(input.name().trim()); project.setDescription(input.description() == null ? "" : input.description()); project.setProjectType(input.projectType()); + if (input.coverUrl() != null) project.setCoverUrl(coverUrl); project.setUpdatedAt(now()); - projects.updateById(project); + // 显式 SET,确保空字符串清除封面时实际写入 NULL;省略字段仍保留旧值。 + projects.update( + null, + new LambdaUpdateWrapper() + .eq(Project::getProjectCode, code) + .set(Project::getName, project.getName()) + .set(Project::getDescription, project.getDescription()) + .set(Project::getProjectType, project.getProjectType()) + .set(input.coverUrl() != null, Project::getCoverUrl, coverUrl) + .set(Project::getUpdatedAt, project.getUpdatedAt())); + if (input.coverUrl() != null) + log.info("更新项目封面 projectCode={} hasCover={}", code, coverUrl != null); return view(project, userId); }); } 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 new file mode 100644 index 0000000..3921e36 --- /dev/null +++ b/community-service/src/main/java/com/linkerbot/community/service/oss/OssPostSigner.java @@ -0,0 +1,105 @@ +package com.linkerbot.community.service.oss; + +import com.fasterxml.jackson.core.JsonProcessingException; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.linkerbot.community.bean.Contracts.CoverUploadSignature; +import com.linkerbot.community.common.Codes; +import com.linkerbot.community.service.config.OssProperties; +import java.nio.charset.StandardCharsets; +import java.security.GeneralSecurityException; +import java.time.*; +import java.time.format.DateTimeFormatter; +import java.time.temporal.ChronoUnit; +import java.util.*; +import javax.crypto.Mac; +import javax.crypto.spec.SecretKeySpec; +import org.springframework.beans.factory.annotation.Autowired; +import org.springframework.stereotype.Component; +import org.slf4j.Logger; +import org.slf4j.LoggerFactory; + +@Component +public class OssPostSigner { + private static final Logger log = LoggerFactory.getLogger(OssPostSigner.class); + public static final long MAX_FILE_BYTES = 5L * 1024 * 1024; + private static final Duration VALIDITY = Duration.ofMinutes(5); + private static final String VERSION = "OSS4-HMAC-SHA256"; + private static final DateTimeFormatter DATE = + DateTimeFormatter.ofPattern("yyyyMMdd").withZone(ZoneOffset.UTC); + private static final DateTimeFormatter TIMESTAMP = + DateTimeFormatter.ofPattern("yyyyMMdd'T'HHmmss'Z'").withZone(ZoneOffset.UTC); + private static final DateTimeFormatter EXPIRATION = + DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'").withZone(ZoneOffset.UTC); + private final OssProperties properties; + private final ObjectMapper json; + private final Clock clock; + + @Autowired + public OssPostSigner(OssProperties properties, ObjectMapper json) { + this(properties, json, Clock.systemUTC()); + } + + OssPostSigner(OssProperties properties, ObjectMapper json, Clock clock) { + this.properties = properties; + this.json = json; + this.clock = clock; + } + + public CoverUploadSignature sign(String userCode, String contentType, String extension) { + Instant now = clock.instant().truncatedTo(ChronoUnit.MILLIS); + 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( + 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("eq", "$success_action_status", "200"))); + try { + String encoded = Base64.getEncoder().encodeToString(json.writeValueAsBytes(policy)); + Map fields = new LinkedHashMap<>(); + fields.put("key", key); + fields.put("policy", encoded); + fields.put("x-oss-signature-version", VERSION); + fields.put("x-oss-credential", credential); + fields.put("x-oss-date", timestamp); + fields.put("x-oss-signature", signature(properties.getAccessKeySecret(), date, + 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)); + } catch (JsonProcessingException | GeneralSecurityException error) { + log.error("OSS 签名生成失败 userCode={} region={} errorType={}", + userCode, properties.getRegion(), error.getClass().getSimpleName()); + throw new IllegalStateException("OSS 签名生成失败"); + } + } + + // OSS POST V4:Base64 Policy 为待签名文本,所有输入均按 UTF-8 编码。 + static String signature(String secret, String date, String region, String policy) + throws GeneralSecurityException { + byte[] key = hmac(("aliyun_v4" + secret).getBytes(StandardCharsets.UTF_8), date); + key = hmac(key, region); + key = hmac(key, "oss"); + key = hmac(key, "aliyun_v4_request"); + return HexFormat.of().formatHex(hmac(key, policy)); + } + + private static byte[] hmac(byte[] key, String value) throws GeneralSecurityException { + Mac mac = Mac.getInstance("HmacSHA256"); + mac.init(new SecretKeySpec(key, "HmacSHA256")); + return mac.doFinal(value.getBytes(StandardCharsets.UTF_8)); + } +} 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 new file mode 100644 index 0000000..f194f83 --- /dev/null +++ b/community-service/src/test/java/com/linkerbot/community/service/oss/OssPostSignerTest.java @@ -0,0 +1,82 @@ +package com.linkerbot.community.service.oss; + +import static org.assertj.core.api.Assertions.*; + +import com.fasterxml.jackson.databind.JsonNode; +import com.fasterxml.jackson.core.type.TypeReference; +import com.fasterxml.jackson.databind.ObjectMapper; +import com.linkerbot.community.bean.Contracts.CoverUploadSignature; +import com.linkerbot.community.service.config.OssProperties; +import java.time.*; +import java.util.*; +import org.junit.jupiter.api.Test; + +class OssPostSignerTest { + private final ObjectMapper json = new ObjectMapper(); + + private OssProperties properties() { + OssProperties properties = new OssProperties(); + properties.setEnabled(true); + properties.setRegion("cn-hangzhou"); + properties.setBucket("examplebucket"); + properties.setAccessKeyId("UnitTestAccessKey"); + properties.setAccessKeySecret("unit-test-secret"); + properties.setRootDirectory("vibemake_dev"); + return properties; + } + + @Test + void matchesIndependentPythonHmacSha256Vector() throws Exception { + // 固定向量由 Python 标准库 hmac/hashlib 独立计算,避免只验证本实现自身。 + String policy = "eyJleHBpcmF0aW9uIjoiMjAyNi0xMC0xNVQwMDowNTowMFoiLCJjb25kaXRpb25zIjpb" + + "eyJidWNrZXQiOiJleGFtcGxlYnVja2V0In0sWyJlcSIsIiRrZXkiLCJ2aWJlbWFrZV9k" + + "ZXYvcHJvamVjdC1jb3ZlcnMvZXhhbXBsZS5wbmciXV19"; + assertThat(OssPostSigner.signature("unit-test-secret", "20261015", "cn-hangzhou", policy)) + .isEqualTo("e9c75f4f2f35592de34488343285d851499ec5b96524a960b2b9a3f6cfea8d3c"); + assertThat(OssPostSigner.signature("unit-test-secret", "20261015", "cn-hangzhou", policy + "A")) + .isNotEqualTo("e9c75f4f2f35592de34488343285d851499ec5b96524a960b2b9a3f6cfea8d3c"); + } + + @Test + void bindsExactObjectAndMimeWithUtcDatesAndFiveMinuteExpiry() throws Exception { + OssProperties properties = properties(); + Clock clock = Clock.fixed(Instant.parse("2026-10-14T23:58:30.123456789Z"), ZoneId.of("Asia/Shanghai")); + OssPostSigner signer = new OssPostSigner(properties, json, clock); + String user = "1".repeat(32); + CoverUploadSignature result = signer.sign(user, "image/png", "png"); + assertThat(result.uploadUrl()).isEqualTo("https://examplebucket.oss-cn-hangzhou.aliyuncs.com"); + assertThat(result.objectKey()).matches("vibemake_dev/project-covers/" + user + "/20261014/[a-f0-9]{32}\\.png"); + assertThat(result.coverUrl()).isEqualTo(result.uploadUrl() + "/" + result.objectKey()); + assertThat(result.expiresAt()).isEqualTo(LocalDateTime.parse("2026-10-15T00:03:30.123")); + assertThat(result.formFields()).containsEntry("key", result.objectKey()) + .containsEntry("content-type", "image/png") + .containsEntry("success_action_status", "200") + .containsEntry("x-oss-date", "20261014T235830Z") + .containsEntry("x-oss-credential", "UnitTestAccessKey/20261014/cn-hangzhou/oss/aliyun_v4_request"); + JsonNode policy = json.readTree(Base64.getDecoder().decode(result.formFields().get("policy"))); + assertThat(policy.path("expiration").asText()).isEqualTo("2026-10-15T00:03:30.123Z"); + List conditions = json.convertValue(policy.path("conditions"), new TypeReference<>() {}); + assertThat(conditions).containsAll(List.of( + Map.of("bucket", "examplebucket"), + Map.of("x-oss-signature-version", "OSS4-HMAC-SHA256"), + Map.of("x-oss-credential", result.formFields().get("x-oss-credential")), + Map.of("x-oss-date", result.formFields().get("x-oss-date")), + List.of("eq", "$key", result.objectKey()), + List.of("eq", "$content-type", "image/png"), + List.of("content-length-range", 1, 5242880), + List.of("eq", "$success_action_status", "200"))); + assertThat(result.formFields().get("x-oss-signature")).matches("[a-f0-9]{64}"); + assertThat(result.formFields().toString()).doesNotContain("unit-test-secret"); + assertThat(signer.sign(user, "image/png", "png").objectKey()).isNotEqualTo(result.objectKey()); + } + + @Test + void usesProductionRootAndConfiguredCdnBasePath() { + OssProperties properties = properties(); + properties.setRootDirectory("vibemake"); + properties.setPublicBaseUrl("https://images.example.com/assets/"); + CoverUploadSignature result = new OssPostSigner(properties, json).sign("1".repeat(32), "image/webp", "webp"); + assertThat(result.objectKey()).startsWith("vibemake/project-covers/").endsWith(".webp"); + assertThat(result.coverUrl()).isEqualTo("https://images.example.com/assets/" + result.objectKey()); + } +} diff --git a/community-service/src/test/java/com/linkerbot/community/service/oss/OssPropertiesTest.java b/community-service/src/test/java/com/linkerbot/community/service/oss/OssPropertiesTest.java new file mode 100644 index 0000000..025ee4c --- /dev/null +++ b/community-service/src/test/java/com/linkerbot/community/service/oss/OssPropertiesTest.java @@ -0,0 +1,77 @@ +package com.linkerbot.community.service.oss; + +import static org.assertj.core.api.Assertions.*; + +import com.linkerbot.community.service.config.OssProperties; +import org.junit.jupiter.api.Test; +import org.springframework.boot.context.properties.EnableConfigurationProperties; +import org.springframework.boot.test.context.runner.ApplicationContextRunner; +import org.springframework.context.annotation.Configuration; + +class OssPropertiesTest { + @Configuration(proxyBeanMethods = false) + @EnableConfigurationProperties(OssProperties.class) + static class Config {} + + private final ApplicationContextRunner runner = new ApplicationContextRunner().withUserConfiguration(Config.class); + + private ApplicationContextRunner enabled() { + return runner.withPropertyValues( + "community.oss.enabled=true", + "community.oss.region=cn-hangzhou", + "community.oss.bucket=examplebucket", + "community.oss.access-key-id=UnitTestAccessKey", + "community.oss.access-key-secret=unit-test-secret", + "community.oss.root-directory=vibemake_dev"); + } + + @Test + void disabledNeedsNoCloudConfigurationAndEnabledRequiresAllFields() { + runner.run(context -> { + assertThat(context).hasNotFailed(); + assertThat(context.getBean(OssProperties.class).isEnabled()).isFalse(); + }); + runner.withPropertyValues("community.oss.enabled=true").run(context -> assertThat(context).hasFailed()); + enabled().run(context -> assertThat(context).hasNotFailed()); + for (String property : new String[] {"region", "bucket", "access-key-id", "access-key-secret", "root-directory"}) + enabled().withPropertyValues("community.oss." + property + "=") + .run(context -> assertThat(context).hasFailed()); + } + + @Test + void derivesPublicEndpointFromRegionAndSupportsExplicitOverrides() { + enabled().run(context -> { + assertThat(context).hasNotFailed(); + OssProperties properties = context.getBean(OssProperties.class); + assertThat(properties.uploadUrl()).isEqualTo("https://examplebucket.oss-cn-hangzhou.aliyuncs.com"); + assertThat(properties.publicBaseUrl()).isEqualTo(properties.uploadUrl()); + }); + enabled().withPropertyValues("community.oss.region=cn-beijing", "community.oss.endpoint=") + .run(context -> { + assertThat(context).hasNotFailed(); + assertThat(context.getBean(OssProperties.class).uploadUrl()) + .isEqualTo("https://examplebucket.oss-cn-beijing.aliyuncs.com"); + }); + enabled().withPropertyValues("community.oss.endpoint=https://oss-accelerate.aliyuncs.com/") + .run(context -> { + assertThat(context).hasNotFailed(); + assertThat(context.getBean(OssProperties.class).uploadUrl()) + .isEqualTo("https://examplebucket.oss-accelerate.aliyuncs.com"); + }); + } + + @Test + void rejectsInvalidCloudUrlsAndDirectoryTraversal() { + for (String property : new String[] { + "endpoint=http://oss-cn-hangzhou.aliyuncs.com", + "endpoint=https://user:password@oss-cn-hangzhou.aliyuncs.com", + "endpoint=https://oss-cn-hangzhou.aliyuncs.com/path", + "endpoint=https://oss-cn-hangzhou.aliyuncs.com?token=x", + "public-base-url=http://images.example.com", + "public-base-url=https://images.example.com/#fragment", + "region=oss-cn-beijing", + "root-directory=../vibemake", "bucket=vibemake_dev"}) + enabled().withPropertyValues("community.oss." + property) + .run(context -> assertThat(context).hasFailed()); + } +} diff --git a/docs/community-api.md b/docs/community-api.md index 40bd4d3..a29fba7 100644 --- a/docs/community-api.md +++ b/docs/community-api.md @@ -12,6 +12,7 @@ - [登录和用户](#登录和用户) - [类型与项目列表](#类型与项目列表) - [我的项目管理](#我的项目管理) +- [项目封面与 OSS 直传](#项目封面与-oss-直传) - [目录和文件读取](#目录和文件读取) - [文件编辑与上传提交](#文件编辑与上传提交) - [社区发布和撤回](#社区发布和撤回) @@ -101,6 +102,7 @@ Git SHA 使用完整的 40 或 64 位十六进制字符串,不使用缩写。 | POST | `/api/auth/logout` | 是 | null | | GET | `/api/users/me` | 是 | User | | GET | `/api/project-types` | 否 | ProjectType[] | +| POST | `/api/uploads/project-covers/signature` | 是 | CoverUploadSignature | | GET | `/api/workspace/projects` | 是 | PageResult<Project> | | POST | `/api/workspace/projects` | 是 | Project | | GET | `/api/workspace/projects/{projectCode}` | 是 | Project | @@ -180,6 +182,7 @@ export interface Project { projectCode: string; name: string; description: string; + coverUrl: string | null; // 固定公开 HTTPS 图片地址,支持 OSS/CDN 和外部图片 projectType: string; owner: PublicUser; repoStatus: 'CREATING' | 'READY' | 'FAILED'; @@ -195,6 +198,14 @@ export interface Project { updatedAt: UtcDateTime; } +export interface CoverUploadSignature { + uploadUrl: string; + objectKey: string; + coverUrl: string; + expiresAt: UtcDateTime; // 无时区后缀,按 UTC 解释 + formFields: Record; +} + export interface TreeEntry { path: string; // 从仓库根目录开始的完整相对路径 name: string; @@ -248,6 +259,7 @@ export interface Comment { "projectCode": "22222222222222222222222222222222", "name": "机器人示例项目", "description": "模型、配置和说明文件", + "coverUrl": "https://images.example.com/vibemake/project-covers/11111111111111111111111111111111/20261015/33333333333333333333333333333333.png", "projectType": "GENERAL", "owner": { "userCode": "11111111111111111111111111111111", @@ -277,6 +289,7 @@ export interface Comment { | publishedCommitSha / publishedAt | 撤回后可能仍保留上一次发布值,是否公开必须判断 publishStatus | | sourceProjectCode / sourceCommitSha | Fork 来源及复制的源版本;普通新项目为 null | | liked | 当前请求用户是否点赞,匿名访问为 false | +| coverUrl | 固定公开封面地址,null 时展示前端默认图;工作区、社区、Fork 和 AI 卡片共用此字段 | 工作区归属由 `owner.userCode` 判断,不存在 `workspaceCode`。`updatedAt` 不代表仓库最新提交时间。来源项目撤回或删除后,sourceProjectCode 仍可能存在,访问该来源的社区详情会返回 404。 @@ -393,6 +406,7 @@ data 示例中 image 仅展示格式前缀,实际值为完整图片: | --- | --- | --- | | name | 是 | 非空,最多 100 字符,保存时去掉首尾空格 | | description | 否 | 最多 2000 字符,省略或 null 时保存为空字符串 | +| coverUrl | 否 | 去掉首尾空格后最多 2048 字符;绝对 HTTPS 图片地址,主机名合法且不含用户凭据;省略、null 或空字符串表示无封面 | | projectType | 是 | 类型接口返回的 code,必须精确匹配,最多 64 字符 | ```json @@ -415,9 +429,9 @@ data 示例中 image 仅展示格式前缀,实际值为完整图片: `PATCH /api/workspace/projects/{projectCode}`。请求字段与创建项目相同,data 为更新后的 Project。 -虽然方法为 PATCH,当前接口要求同时提交 name、projectType;description 省略或 null 会清空描述。前端编辑表单应提交完整的三个字段。 +虽然方法为 PATCH,当前接口要求同时提交 name、projectType;description 省略或 null 会清空描述。前端编辑表单应提交完整的 name、description、projectType。coverUrl 省略或 null 保留原封面,传空字符串或纯空白字符串清除,非空值替换封面;后端不下载外部图片,也不校验图片是否存在。 -已发布项目的名称、描述、类型会直接更新社区展示,不生成文件 Commit。 +已发布项目的名称、描述、类型、封面会直接更新社区展示,不生成文件 Commit。Fork 继承源项目的封面地址;替换、清除、删除项目不自动删除 OSS 对象,避免影响共用地址的 Fork。 ### 删除项目 @@ -425,6 +439,109 @@ data 示例中 image 仅展示格式前缀,实际值为完整图片: 项目逻辑删除并从社区撤回,已有独立 Fork 不受影响。再次操作已删除项目返回 404。 +## 项目封面与 OSS 直传 + +封面可以填写外部 HTTPS 图片地址,也可以使用本节的 OSS 直传。图片二进制由浏览器直接发往 OSS;后端仅提供签名,支持创建项目之前上传,无需 projectCode。该流程与仓库文件上传分开,图片不进入 Gitea,也不生成文件 Commit。 + +### 获取封面上传签名 + +`POST /api/uploads/project-covers/signature`,需要登录,JSON 请求: + +```json +{ + "contentType": "image/png", + "fileSize": 123456 +} +``` + +| 字段 | 必填 | 约束 | +| --- | --- | --- | +| contentType | 是 | image/jpeg、image/png、image/webp;JPG 使用 image/jpeg,不支持 SVG、GIF | +| fileSize | 是 | 文件字节数,1~5242880(5 MiB),超过上限返回 413 | + +成功 data 为 CoverUploadSignature,响应带 `Cache-Control: no-store`。以下 Policy、凭据和签名是占位示意,前端必须使用实时返回值: + +```json +{ + "uploadUrl": "https://examplebucket.oss-cn-hangzhou.aliyuncs.com", + "objectKey": "vibemake_dev/project-covers/11111111111111111111111111111111/20261015/33333333333333333333333333333333.png", + "coverUrl": "https://images.example.com/vibemake_dev/project-covers/11111111111111111111111111111111/20261015/33333333333333333333333333333333.png", + "expiresAt": "2026-10-15T02:05:00", + "formFields": { + "key": "vibemake_dev/project-covers/11111111111111111111111111111111/20261015/33333333333333333333333333333333.png", + "policy": "", + "x-oss-signature-version": "OSS4-HMAC-SHA256", + "x-oss-credential": "/20261015/cn-hangzhou/oss/aliyun_v4_request", + "x-oss-date": "20261015T020000Z", + "x-oss-signature": "<十六进制签名>", + "content-type": "image/png", + "success_action_status": "200" + } +} +``` + +签名有效期为 5 分钟;策略绑定 Bucket、完整对象 key、Content-Type、1 字节~5 MiB 的大小范围和成功状态码 200。文件类型按声明的 MIME 约束,后端不读取或解码图片。对象路径由后端生成,日期使用 UTC:test 为 `vibemake_dev/project-covers/{userCode}/{yyyyMMdd}/{随机编码}.{扩展名}`,prod 为 `vibemake/project-covers/...`。不要修改 formFields、对象路径或上传类型。 + +### 浏览器直传与保存项目 + +1. 调用签名接口,取得 uploadUrl、formFields 和 coverUrl。 +2. 将 formFields 原样加入 FormData,最后追加 file 字段,直接 POST 到 uploadUrl。不手动设置 multipart Content-Type,不向 OSS 发送平台 Authorization。 +3. OSS 成功返回 HTTP 200,响应体为空,不要按平台 ApiResponse 解析。成功后再把 coverUrl 写入项目创建或修改请求;上传本身不会自动更新项目。 +4. 失败、取消或网络中断时保留现有项目封面。签名过期时重新获取;尚未绑定项目的对象不自动清理。 + +以下示例复用后文的 `request` 平台请求封装;发往 OSS 的请求直接使用 fetch: + +```typescript +async function uploadProjectCover(file: File, token: string, signal?: AbortSignal): Promise { + const signature = await request('/uploads/project-covers/signature', { + method: 'POST', token, signal, + body: { contentType: file.type, fileSize: file.size }, + }); + const form = new FormData(); + for (const [name, value] of Object.entries(signature.formFields)) form.append(name, value); + form.append('file', file); // 必须是最后一个字段 + const response = await fetch(signature.uploadUrl, { + method: 'POST', body: form, credentials: 'omit', signal, + }); + if (response.status !== 200) throw new Error(`封面上传失败:HTTP ${response.status}`); + return signature.coverUrl; +} + +async function replaceProjectCover(project: Project, file: File, token: string) { + const coverUrl = await uploadProjectCover(file, token); + return request(`/workspace/projects/${encodeURIComponent(project.projectCode)}`, { + method: 'PATCH', token, + body: { name: project.name, description: project.description, projectType: project.projectType, coverUrl }, + }); +} +``` + +创建项目时同样先上传,再将返回的 coverUrl 与 name、description、projectType 一起提交。仅修改外部封面地址不需要调用签名接口;图片加载失败时前端展示默认图。 + +| 位置 | HTTP / code | 处理 | +| --- | --- | --- | +| 签名接口 | 401 UNAUTHORIZED | 先登录 | +| 签名接口 | 400 BAD_REQUEST | 检查 MIME、字节数及必填字段 | +| 签名接口 | 413 UPLOAD_TOO_LARGE | 文件超过 5 MiB,压缩或选择其他图片 | +| 签名接口 | 503 OSS_UNAVAILABLE | OSS 未启用;可继续使用外部 HTTPS 图片 | +| OSS 请求 | 非 200 或网络错误 | 不保存新地址;检查签名过期、Policy 限制、Bucket 权限和 CORS;OSS 的错误响应不使用平台包装 | + +### 部署配置 + +服务端启用 `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`,例如北京为 `https://oss-cn-beijing.aliyuncs.com`,无需配置 Endpoint 环境变量。特殊域名场景可显式设置 `community.oss.endpoint`,优先使用配置值,要求为公网 HTTPS 地址,不带 Bucket、路径、凭据或查询参数。`OSS_PUBLIC_BASE_URL` 可选。启用时配置缺失或不合法会停止启动。密钥不提交仓库、不返回浏览器;浏览器只收到 AccessKeyId 派生的 credential、Policy 和签名。 + +公开基础地址可以是 OSS 或 CDN 域名,可带基础路径;最终地址为 `{公开基础地址}/{objectKey}`,CDN 路径需正确映射到同一对象。留空时为 `https://{Bucket}.{Endpoint 主机名}/{objectKey}`。数据库保存固定地址,不保存临时签名下载链接。 + +OSS 控制台配置步骤: + +1. 准备指定地域的 Bucket,确认 test/prod 的根目录分别为 `vibemake_dev/`、`vibemake/`。目录是对象前缀,不是 Bucket 名。 +2. 给服务端 RAM 用户授予对应环境目录的 `oss:PutObject` 权限,例如资源 `acs:oss:*:*:YOUR_BUCKET/vibemake_dev/project-covers/*`;正式环境改为 `vibemake/project-covers/*`,两个环境可使用各自凭据。 +3. 配置 Bucket CORS:AllowedOrigins 填真实前端开发、部署 Origin(含协议和端口),AllowedMethods 包含 POST,若使用 fetch 读图则增加 GET、HEAD;AllowedHeaders 允许 Content-Type,可按需要暴露 ETag、x-oss-request-id。调用签名接口仍走原有 `/api` 代理,不能用后端 OPTIONS 放行替代 OSS CORS。 +4. 对封面目录配置公开 GetObject 读取权限,或使用能够公开返回图片的 CDN;私有源站通过 CDN 时需配置回源鉴权。对象沿用 Bucket 的访问规则,应用不修改整个 Bucket 的 ACL,也不生成临时下载链接。 +5. 测试环境完成“获取签名 → 浏览器直传 → 保存项目 → 匿名读取图片”,核对对象 key 和浏览器网络请求;生产环境重复验收 `vibemake/` 路径。 + +协议参考:[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)。 + ## 目录和文件读取 ### 工作区目录 @@ -960,6 +1077,7 @@ const result = await chatAi( | 登录页 | captcha → login;失败后刷新验证码;成功后保存平台登录状态 | | 我的工作区 | users/me → workspace/projects,分别显示仓库状态和发布状态 | | 创建项目 | POST workspace/projects → 使用返回 projectCode 进入详情 → tree 获取当前版本 | +| 上传封面 | uploads/project-covers/signature → 浏览器直接 POST OSS → 成功后将 coverUrl 写入项目创建或修改接口 | | 文件编辑 | workspace 详情与 tree → files → 判断 editable → commits → 刷新版本、目录和文件 | | 上传文件 | tree 获取基准 SHA → uploads/commit → 刷新目录和当前版本 | | 发布或更新社区 | 获取最新工作区 SHA → publication → 刷新项目和社区页面 | diff --git a/docs/database.md b/docs/database.md index 76cd72b..fdb6aa3 100644 --- a/docs/database.md +++ b/docs/database.md @@ -25,6 +25,7 @@ CREATE TABLE project ( owner_user_id BIGINT NOT NULL COMMENT '所属平台用户', name VARCHAR(100) NOT NULL COMMENT '项目名称', description TEXT NOT NULL COMMENT '项目描述', + cover_url VARCHAR(2048) NULL COMMENT '封面图片 HTTPS 地址', project_type VARCHAR(64) NOT NULL COMMENT '配置中的项目类型编码', gitea_repo_id BIGINT NULL COMMENT 'Gitea 仓库标识', gitea_owner VARCHAR(100) NOT NULL COMMENT 'Gitea 仓库所属组织', @@ -78,3 +79,14 @@ CREATE TABLE project_like ( ``` 内部 ID 仅用于数据库关联,对外使用业务编码。时间均由后端写入 UTC。`CREATING` 项目表示仓库初始化未完成,不代表编辑草稿。Gitea 数据库与业务库分离,不修改 Gitea 内部表。 + +## 已有数据库增加项目封面 + +已使用旧版结构的环境,先在对应业务库执行以下 SQL,再部署新版本应用;新建数据库已包含此字段,不重复执行。应用不会自动迁移数据库。 + +```sql +ALTER TABLE project + ADD COLUMN cover_url VARCHAR(2048) NULL COMMENT '封面图片 HTTPS 地址' AFTER description; +``` + +历史项目的封面为 NULL。字段保存固定公开地址,可以来自 OSS、CDN 或外部 HTTPS 图片;不存储临时签名下载地址。替换、清除封面和删除项目不会自动删除 OSS 对象,Fork 可能共用同一地址。