项目新增封面图字段

This commit is contained in:
lxp
2026-10-15 11:09:21 +08:00
parent 92b2251f25
commit a1076d1098
21 changed files with 780 additions and 7 deletions
+9
View File
@@ -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=''
+11
View File
@@ -0,0 +1,11 @@
## 代码实现原则
- 优先保证业务正确性、可维护性、可读性,再考虑炫技。
- Java代码统一使用显式类型声明,不使用var,包括局部变量、循环变量和try-with-resources资源变量。
- 修改代码时忽略.sql文件,如果遇到需要改表结构,直接发我sql,要求表字段规范且有中文注释。
- /api的用户请求返回数据不要暴露数据表id字段,只返回编码,增删改查都用唯一编码字段
## 日志规范
- 关键业务节点必须补充必要日志,方便线上排查。
- 不要打印密码、Token、手机号、身份证、支付密钥等敏感信息。
- 异常日志必须包含足够定位问题的信息。
## 回复规范
- 永远用中文回复。
+19 -2
View File
@@ -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。结果不明或数据库回写失败需要人工核对;不提供后台自动恢复、无条件自动重试或跨重启完整幂等。具体恢复方式见接口文档。
@@ -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<ApiResponse<CoverUploadSignature>> signature(
@Valid @RequestBody CoverUploadInput input) {
return ResponseEntity.ok().cacheControl(CacheControl.noStore())
.body(ApiResponse.success(uploads.signature(CurrentUser.required(), input)));
}
}
@@ -11,6 +11,8 @@ spring:
connection-timeout: 5000
community:
oss:
root-directory: vibemake
gitea:
base-url: ${GITEA_BASE_URL}
owner: ${GITEA_ORGANIZATION:community}
@@ -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}
@@ -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:}
@@ -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();
@@ -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");
}
}
@@ -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<String, Object> 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<String, Object> 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<String, Object> 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");
@@ -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<String, String> 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,
@@ -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;
@@ -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);
}
@@ -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("/+$", "");
}
}
@@ -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<String, String> 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;
}
}
@@ -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<Project>()
.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);
});
}
@@ -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<String, Object> 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<String, String> 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));
}
}
@@ -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<Object> 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());
}
}
@@ -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());
}
}
+120 -2
View File
@@ -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&lt;Project&gt; |
| 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<string, string>;
}
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": "<Base64 编码的 Policy>",
"x-oss-signature-version": "OSS4-HMAC-SHA256",
"x-oss-credential": "<AccessKeyId>/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<T>` 平台请求封装;发往 OSS 的请求直接使用 fetch:
```typescript
async function uploadProjectCover(file: File, token: string, signal?: AbortSignal): Promise<string> {
const signature = await request<CoverUploadSignature>('/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<Project>(`/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 → 刷新项目和社区页面 |
+12
View File
@@ -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 可能共用同一地址。