已按原有 OSS 规则统一:

- 上传继承 Bucket 权限,不再强制 private。
- 读取使用共用的 OSS/CDN 普通地址,不再生成临时下载签名,expiresAt=null。
- 保留项目归属、版本冲突和幂等保存校验。
This commit is contained in:
lxp
2026-11-03 18:16:53 +08:00
parent 4707f7e4f1
commit c931903738
14 changed files with 104 additions and 198 deletions
+3 -3
View File
@@ -2,7 +2,7 @@
在启用 CAD 接口前,由运维在现有 `vibemake` 数据库手工执行以下 SQL(MySQL 8.0.13+)。应用不自动建表,不修改现有项目表。所有业务时间按上海时间写入。
`id` 和归属外键仅供服务内部使用,对外使用 `cad_project_code` 和 `upload_code`。两张表与 Git 项目无关联。上线顺序:执行 SQL → 部署后端 → 配置并验证 CAD 私有 OSS → 开放前端入口。回滚代码时保留两张表和 OSS 对象。
`id` 和归属外键仅供服务内部使用,对外使用 `cad_project_code` 和 `upload_code`。两张表与 Git 项目无关联。上线顺序:执行 SQL → 部署后端 → 验证共用 OSS 配置及文件读取 → 开放前端入口。回滚代码时保留两张表和 OSS 对象。
```sql
CREATE TABLE cad_project (
@@ -11,7 +11,7 @@ CREATE TABLE cad_project (
owner_user_id BIGINT NOT NULL COMMENT '所属用户内部主键,关联sys_user.id',
name VARCHAR(100) NOT NULL COMMENT 'CAD项目名称',
description VARCHAR(2000) NOT NULL DEFAULT '' COMMENT 'CAD项目描述',
document_object_key VARCHAR(512) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT '' COMMENT '当前原生设计文件的私有OSS对象键',
document_object_key VARCHAR(512) CHARACTER SET ascii COLLATE ascii_bin NOT NULL DEFAULT '' COMMENT '当前原生设计文件的OSS对象键',
file_name VARCHAR(255) NOT NULL DEFAULT '' COMMENT '当前原生设计文件名称',
size_bytes BIGINT NOT NULL DEFAULT 0 COMMENT '当前设计文件大小,单位字节',
version BIGINT NOT NULL DEFAULT 0 COMMENT '当前保存版本,空项目为0,每次成功保存递增',
@@ -29,7 +29,7 @@ CREATE TABLE cad_project_upload (
upload_code VARCHAR(32) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '上传批次唯一业务编码',
cad_project_id BIGINT NOT NULL COMMENT '所属CAD项目内部主键,关联cad_project.id',
expected_version BIGINT NOT NULL COMMENT '签发上传时的项目基础版本,用于并发保存校验',
object_key VARCHAR(512) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '本批次不可覆盖的私有OSS对象键',
object_key VARCHAR(512) CHARACTER SET ascii COLLATE ascii_bin NOT NULL COMMENT '本批次设计文件的OSS对象键',
file_name VARCHAR(255) NOT NULL COMMENT '本批次原生设计文件名称',
size_bytes BIGINT NOT NULL COMMENT '本批次声明的文件大小,单位字节',
expires_at DATETIME(3) NOT NULL COMMENT '未确认批次的截止上海时间,与上传签名一致',
+17 -12
View File
@@ -2,6 +2,8 @@
CAD 与 Vibemake 共用 `/api/auth/login`、`/api/auth/logout` 和 `/api/users/me`,使用同一个 `Authorization: Bearer <平台 token>`。CAD 工作空间独立于现有 `/api/workspace/projects`,不创建 Git 仓库、不自动发布社区。只支持当前用户的单个自包含原生 `.sc` 设计文件,不管理外部引用的多文件装配。
文件沿用现有 OSS 资源规则:上传继承 Bucket 权限,读取使用 `OSS_PUBLIC_BASE_URL` 对应的普通 OSS/CDN 地址。工作空间和平台接口按用户隔离,文件直链的访问权限由现有 Bucket/CDN 配置决定;公开配置下,拿到直链即可读取文件。
通用响应、上海时间格式、分页和跨域规则沿用 [Vibemake 接入约定](vibemake-api.md#接入约定)。CAD 所有接口返回 `Cache-Control: no-store`。业务编码为不透明字符串,不使用数据库 ID。
## 接口与数据
@@ -49,7 +51,7 @@ interface CadSaveResult {
}
interface CadDocument {
downloadUrl: string;
expiresAt: string;
expiresAt: null;
version: number;
fileName: string;
sizeBytes: number;
@@ -68,9 +70,9 @@ interface CadDocument {
6. 只有确认成功才显示云端已保存;序列化期间及上传期间又产生的修改仍应标为未保存。每个项目前端串行执行云端保存。
7. 打开项目先读详情;空项目进入新设计,否则 GET `document`,fetch `downloadUrl` 得到原始文件字节并交给 SolidCraft 打开。**本次编辑基础版本使用 `document.version`**,文件与版本来自同一快照,不混用先前详情中的版本。
上传签名默认 15 分钟,未确认批次同一时刻过期;文件上传完成但确认已过期时,重新申请批次。下载地址默认 5 分钟,用完即丢弃,不存为永久地址;过期时重新调用 API 获取。业务时间为上海时间字符串,无时区后缀,解析时补 `+08:00`。
上传签名默认 15 分钟,未确认批次同一时刻过期;文件上传完成但确认已过期时,重新申请批次。`downloadUrl` 为普通 OSS/CDN 文件地址,不附加临时下载签名,`expiresAt` 为兼容前端保留且固定返回 null;前端直接读取地址,不做下载签名续期。业务时间为上海时间字符串,无时区后缀,解析时补 `+08:00`。
相同 `uploadCode` 重复确认返回首次保存回执,不重复增加版本。即使之后已有更新版本,重试旧批次也不会恢复旧文件;回执版本可能小于最新项目版本,需要时重新读取详情。网络超时先保留原批次并重试确认,不直接创建新项目或新批次。OSS 同一对象禁止覆盖,OSS 上传超时先尝试确认,缺文件再处理上传,不无条件重复上传。
相同 `uploadCode` 重复确认返回首次保存回执,不重复增加版本。即使之后已有更新版本,重试旧批次也不会恢复旧文件;回执版本可能小于最新项目版本,需要时重新读取详情。网络超时先保留原批次并重试确认,不直接创建新项目或新批次。上传使用现有 `signObject` 策略及其禁止覆盖参数,每次申请使用新的批次对象键;OSS 上传超时先尝试确认,缺文件再处理上传,不无条件重复上传。
两个标签页使用相同基础版本保存时,只有一个成功,另一个收到 `CAD_VERSION_CONFLICT`。保留本地修改并提供重新打开最新设计、下载本地副本或另存新项目的处理入口;不能只换成最新版本号后自动覆盖。
@@ -91,10 +93,10 @@ interface CadDocument {
| 413 `CAD_FILE_TOO_LARGE` / `REQUEST_TOO_LARGE` | 文件超限或 JSON 超限,调整请求 |
| 429 `RATE_LIMITED` | 按 Retry-After 等待后重试 |
| 502 `CAD_OSS_ERROR` | 保留当前设计及批次,稍后重试 |
| 503 `CAD_STORAGE_UNAVAILABLE` / `CAD_STORAGE_UNSAFE` | 存储未开启或配置不符合要求,联系管理员 |
| 503 `CAD_STORAGE_UNAVAILABLE` / `CAD_STORAGE_UNSAFE` | 存储未开启或本地 OSS 连接参数不完整,联系管理员 |
| 503 `CAD_CODE_BUSY` / `REDIS_UNAVAILABLE` | 暂时无法处理,保留输入后重试 |
删除为逻辑删除,之后列表、详情、读取、编辑及保存确认均不可访问,不提供恢复;已签发的 OSS 下载链接在到期前仍可能使用。上传失败、替换、删除均保留旧 OSS 对象,首期没有历史恢复和对象自动清理。
删除为逻辑删除,之后列表、详情、文件地址获取、编辑及保存确认均不可访问,不提供恢复。上传失败、替换、删除均保留旧 OSS 对象,已有文件直链仍按 Bucket/CDN 规则访问,删除项目不会撤销已有直链。首期没有历史恢复和对象自动清理。
## 部署配置
@@ -114,20 +116,23 @@ vibemake:
| `OSS_ENDPOINT` | 与现有 OSS 共用,可选 HTTPS Endpoint;不填写时按地域生成 |
| `OSS_BUCKET` | 与现有资源共用同一个 Bucket |
| `OSS_ACCESS_KEY_ID` / `OSS_ACCESS_KEY_SECRET` | 与现有 OSS 共用,通过部署环境注入 |
| `OSS_PUBLIC_BASE_URL` | 与现有资源共用普通 OSS/CDN 访问基础地址,配置为空时使用 Bucket 域名 |
| `vibemake.oss.root-directory` | CAD 直接使用各环境根目录:test 为 vibemake_dev,prod 为 vibemake |
| `CAD_MAX_FILE_BYTES` | 268435456;配置范围为 1 字节至 OSS 表单上限 5 GiB,需同时兼容编辑器读取上限 |
| `CAD_UPLOAD_VALIDITY` / `CAD_DOWNLOAD_VALIDITY` | 15m / 5m;范围 1 秒至 7 天 |
| `CAD_UPLOAD_VALIDITY` | 默认 15m;范围 1 秒至 7 天 |
| `RATE_CAD_CREATE_PER_MINUTE` / `RATE_CAD_SIGN_PER_MINUTE` | 5 / 20,按当前用户独立限流 |
| `RATE_CAD_SAVE_PER_MINUTE` / `RATE_CAD_READ_PER_MINUTE` | 30 / 60,保存确认和下载签名尝试次数 |
| `RATE_CAD_SAVE_PER_MINUTE` / `RATE_CAD_READ_PER_MINUTE` | 30 / 60,保存确认和文件地址读取尝试次数 |
CAD 独立开关与 `OSS_ENABLED` 分开控制:公共资源上传关闭时,只要共用连接参数完整,CAD 仍可独立开启。只有 `CAD_OSS_ENABLED` 继续生效;旧的 `CAD_OSS_BUCKET`、`CAD_OSS_REGION`、`CAD_OSS_ENDPOINT`、`CAD_OSS_ACCESS_KEY_ID`、`CAD_OSS_ACCESS_KEY_SECRET` 和 `CAD_OSS_ROOT_DIRECTORY` 均不再读取,可从 `.env` 移除。
共用 Bucket 可以是 private 或 public-read,CAD 对象必须显式为 private,不能继承 Bucket 权限;不允许 public-read-write Bucket 或公共 Bucket Policy。当前对公共 Policy 采用保守检查,任何公共 Policy 都会使 CAD 返回 `CAD_STORAGE_UNSAFE`,包括仅用于其他资源目录的公共 Policy。若现有公开资源依赖此类 Policy,需在部署时调整访问方案,应用不会自动修改整个 Bucket 的 ACL 或 Policy。
上传签名仅在本地生成,保存确认只通过 HEAD 核验对象存在和大小;文件地址沿用现有 `OssResourcePaths.publicUrl` 规则生成。后端不查询 Bucket ACL、公共访问策略、版本控制状态或对象 ACL,不修改 Bucket 配置,也不为 CAD 单独强制 private ACL。
Bucket 必须从未开启版本控制(Off,Suspended 也不允许)。共用 RAM 凭据需要根目录 `cad-projects/*` 的 `oss:PutObject`、`oss:PutObjectAcl`、`oss:GetObject`、`oss:GetObjectAcl`,以及 Bucket 的 `oss:GetBucketAcl`、`oss:GetBucketPolicyStatus`、`oss:GetBucketVersioning`。后端只读取这些配置,不修改 Bucket。不要给前端 RAM 密钥。
共用 RAM 凭据只需覆盖当前环境 `cad-projects/*` 的 `oss:PutObject`、`oss:GetObject`,分别用于普通文件上传和 HEAD 元数据读取。不额外要求 CAD 的 ACL 或 Bucket 配置读取/修改权限。不要给前端 RAM 密钥。
上传策略精确绑定对象键、大小、MIME、Content-Disposition、private ACL 和禁止覆盖;后端签发凭据时检查 Bucket ACL、策略及版本控制,确认保存和签发下载时额外核验对象 ACL 必须为 private。对象 ACL 优先于 Bucket ACL,依据 [OSS 权限控制说明](https://help.aliyun.com/en/oss/user-guide/permissions-and-access-control-overview)。[OSS PostObject 官方文档](https://www.alibabacloud.com/help/en/oss/developer-reference/postobject)说明版本控制开启或暂停时会忽略禁止覆盖参数,因此部署要求 Off。
上传策略与原有 STEP 等资源相同,精确绑定对象键、大小、MIME、Content-Disposition 和禁止覆盖参数,不设置 `x-oss-object-acl`。文件是否公开、CDN 是否需要鉴权、同名对象覆盖行为均遵循已有 OSS/CDN 配置,应用不增加 CAD 专属限制;数据库仍校验归属、基础版本、批次截止时间和幂等回执。
若此前已经使用独立 CAD Bucket 保存过文件,切换前需将文件按原对象键复制到 `OSS_BUCKET` 并设置 private ACL;应用只保存对象键,不记录历史 Bucket,不会自动迁移旧对象。
旧的 `CAD_DOWNLOAD_VALIDITY` 不再读取。前端如曾按下载签名过期时间续期,需调整为直接读取普通地址,允许 `expiresAt=null`。
OSS CORS 允许真实编辑器来源的 POST、GET,允许 Content-Type;需要时暴露 Content-Length 和 Content-Disposition。直传和文件下载不携带平台 Token。生产联调须验证:匿名 GET 原对象被拒绝、有效签名能读取、过期签名不能读取、同对象二次上传被拒绝,以及完整原生设计保存后能恢复编辑。API 自动化使用存储替身,不能替代真实 Bucket 的这些验证。
若此前使用独立 CAD Bucket 保存过文件,切换前需按原对象键复制到 `OSS_BUCKET`。若旧文件曾单独设为 private,且现有普通地址无法读取,需按已有资源访问方式调整为继承 Bucket(default)或配置相应的 CDN 回源授权;代码不会自动迁移文件或修改历史对象 ACL。
OSS/CDN 沿用现有 CORS 规则,允许真实编辑器来源的 POST、GET 和 Content-Type;需要时暴露 Content-Length 和 Content-Disposition。直传和文件读取不携带平台 Token。联调验证上传、确认保存、通过配置的普通 OSS/CDN 地址读取,以及原生设计重新打开后可继续编辑。API 自动化使用存储替身,不替代真实 OSS/CDN 和编辑器联调。
+1 -1
View File
@@ -8,7 +8,7 @@
ZIP、TAR.GZ 下载和 HTTPS Git 本地开发的独立前端交付文档见 [仓库下载与 Git 接入](frontend-repository-download-git.md),包含六个浏览器接口、页面流程、TypeScript 示例及联调清单。
CAD 个人工作空间使用独立的 `/api/cad/workspace/projects`,共用登录,但不创建 Git 仓库、不混入现有项目列表。接口、保存续编流程和私有 OSS 配置见 [CAD 工作空间前端对接](frontend-cad-workspace.md),上线前执行 [CAD 建表 SQL](cad-database.md)。
CAD 个人工作空间使用独立的 `/api/cad/workspace/projects`,共用登录,但不创建 Git 仓库、不混入现有项目列表。接口、保存续编流程和共用 OSS 配置见 [CAD 工作空间前端对接](frontend-cad-workspace.md),上线前执行 [CAD 建表 SQL](cad-database.md)。
## 阅读导航