Files
community/docs/oss-storage-paths.md

76 lines
7.8 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 数据库 OSS 引用统一规范与存量转换
所有平台托管 OSS 资源的专用数据库字段统一保存**未进行 URL 编码、以 `/` 开头、不含域名和环境根目录的路径**。目录字段保留末尾 `/`。实际上传对象键、HEAD/复制使用的 key 和公开访问 URL 由 `vibemake.oss.root-directory` 与公开基础地址在运行时生成。
| 位置 | 数据库存储示例 | 实际 OSS key 示例 |
| --- | --- | --- |
| CAD 当前设计及上传批次 | `/cad-projects/{项目编码}/{批次编码}/design.sc` | `vibemake_dev/cad-projects/{项目编码}/{批次编码}/design.sc` |
| CAD 初始 STEP(initial_step_object_key) | `/project-resources/{工作区项目编码}/step/{批次编码}/model.step` | `vibemake_dev/project-resources/{工作区项目编码}/step/{批次编码}/model.step` |
| PCB 当前工程及上传批次 | `/pcb-projects/{项目编码}/{批次编码}/project.zip` | `vibemake_dev/pcb-projects/{项目编码}/{批次编码}/project.zip` |
| 平台托管封面(含 CAD、PCB 的 cover_url) | `/project-covers/{用户编码}/{日期}/{文件名}` | `vibemake_dev/project-covers/{用户编码}/{日期}/{文件名}` |
| URDF 主文件及目录 | `/urdf/{项目编码}/{批次编码}/...` | `vibemake_dev/urdf/{项目编码}/{批次编码}/...` |
| STEP、GLB、零件、拼装步骤、行走资源 | `/project-resources/{项目编码}/{类型}/{批次编码}/...` | `vibemake_dev/project-resources/{项目编码}/{类型}/{批次编码}/...` |
生产环境真实对象键使用 `vibemake/`;数据库格式相同。托管图片作为封面时,也可以引用 README 图片或其他受控资源目录,均按相同规则保存。外部 HTTPS 链接、带查询参数或片段的链接保持原有访问语义,不通过截断 URL 去掉参数或改写到其他环境。原始 Git README 内容、外部仓库来源地址不属于 OSS 绑定字段,不做全文替换。
新写入的 CAD 批次和保存确认已采用此格式。CAD 关联创建时也将初始 STEP 规范为相对路径,固定引用工作区项目的原对象,不复制或转换,具体表结构及增量 SQL 见 [CAD 数据库说明](cad-database.md#已有数据库增加工作区项目关联与初始-step);该字段为本次新增,无历史完整 key 需要迁移。项目完整保存、Fork 和导入工具状态回写统一规范资源引用;普通资源签名和确认继续使用已有相对路径。应用兼容读取当前环境的历史完整 key,但读取不自动迁移数据库。升级前签发的 CAD 批次仍可确认,确认时同时规范项目和该批次的引用。幂等重放保持原有回执规则。
## 现有数据手工转换 SQL
PCB 两张新表直接采用环境相对路径,建表见 [PCB 工作空间 SQL](pcb-database.md),无需执行下列 CAD 与社区资源的历史转换。
无需修改字段结构。先升级所有在线写入进程与导入工具,再暂停资源写入并备份业务库。在对应环境的业务数据库连接中执行;test 使用 `vibemake_dev`,prod 将 `@oss_root` 改为 `vibemake`。不会移动、复制或删除 OSS 对象,也不修改项目版本、保存时间、上传回执和业务更新时间。
仅当字段精确以当前环境和对应资源目录开头时转换,使用二进制前缀比较避免大小写或下划线通配符误匹配,不使用全局 REPLACE。已经是相对路径的记录、空值和其他环境路径不变;本转换可重复执行。
```sql
-- resource-path-all-bindings-migrate
SET @oss_root = 'vibemake_dev';
START TRANSACTION;
-- 仅去掉当前环境前缀,保留开头的 /;空绑定和其他环境不匹配。
UPDATE cad_project
SET document_object_key = SUBSTRING(document_object_key, CHAR_LENGTH(@oss_root) + 1)
WHERE BINARY LEFT(document_object_key, CHAR_LENGTH(@oss_root) + 14) = BINARY CONCAT(@oss_root, '/cad-projects/');
UPDATE cad_project_upload
SET object_key = SUBSTRING(object_key, CHAR_LENGTH(@oss_root) + 1)
WHERE BINARY LEFT(object_key, CHAR_LENGTH(@oss_root) + 14) = BINARY CONCAT(@oss_root, '/cad-projects/');
-- 项目资源的原始 key 与目录,统一为已有的环境相对格式。
UPDATE project
SET urdf_main_object_key = CASE WHEN BINARY LEFT(urdf_main_object_key, CHAR_LENGTH(@oss_root) + 6) = BINARY CONCAT(@oss_root, '/urdf/')
THEN SUBSTRING(urdf_main_object_key, CHAR_LENGTH(@oss_root) + 1) ELSE urdf_main_object_key END,
urdf_prefix = CASE WHEN BINARY LEFT(urdf_prefix, CHAR_LENGTH(@oss_root) + 6) = BINARY CONCAT(@oss_root, '/urdf/')
THEN SUBSTRING(urdf_prefix, CHAR_LENGTH(@oss_root) + 1) ELSE urdf_prefix END,
step_object_key = CASE WHEN BINARY LEFT(step_object_key, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
THEN SUBSTRING(step_object_key, CHAR_LENGTH(@oss_root) + 1) ELSE step_object_key END,
model_glb_object_key = CASE WHEN BINARY LEFT(model_glb_object_key, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
THEN SUBSTRING(model_glb_object_key, CHAR_LENGTH(@oss_root) + 1) ELSE model_glb_object_key END,
model_parts_prefix = CASE WHEN BINARY LEFT(model_parts_prefix, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
THEN SUBSTRING(model_parts_prefix, CHAR_LENGTH(@oss_root) + 1) ELSE model_parts_prefix END,
assembly_json_object_key = CASE WHEN BINARY LEFT(assembly_json_object_key, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
THEN SUBSTRING(assembly_json_object_key, CHAR_LENGTH(@oss_root) + 1) ELSE assembly_json_object_key END,
walking_resources_prefix = CASE WHEN BINARY LEFT(walking_resources_prefix, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
THEN SUBSTRING(walking_resources_prefix, CHAR_LENGTH(@oss_root) + 1) ELSE walking_resources_prefix END
WHERE BINARY LEFT(urdf_main_object_key, CHAR_LENGTH(@oss_root) + 6) = BINARY CONCAT(@oss_root, '/urdf/')
OR BINARY LEFT(urdf_prefix, CHAR_LENGTH(@oss_root) + 6) = BINARY CONCAT(@oss_root, '/urdf/')
OR BINARY LEFT(step_object_key, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
OR BINARY LEFT(model_glb_object_key, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
OR BINARY LEFT(model_parts_prefix, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
OR BINARY LEFT(assembly_json_object_key, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/')
OR BINARY LEFT(walking_resources_prefix, CHAR_LENGTH(@oss_root) + 19) = BINARY CONCAT(@oss_root, '/project-resources/');
COMMIT;
```
`project.cover_url` 的历史完整 HTTPS 地址还需要域名匹配和 URL 解码,不能直接用上述 SUBSTRING 处理。标准托管封面的预览、备份、转换和回退 SQL 见 [封面及 URDF 历史迁移](database.md#资源路径历史数据迁移)。按当前 OSS/CDN 及已配置历史基础地址逐个执行;非标准、编码或带参数的历史图片先核验,正常重新保存时应用会按受控资源规则转换,不盲目截断成路径。
## 验证和回退
- 抽查 CAD 两张表和 project 的资源字段均为 `/cad-projects/`、`/urdf/`、`/project-resources/` 等相对路径。
- 通过 API 重新获取的下载地址与转换前指向同一个真实对象,仍包含当前环境前缀。
- 核验升级前未确认 CAD 批次、重复确认、重新保存、Fork 继承和项目资源列表。
- 未转换的其他环境或异常路径单独核验,不能通过任意删除路径第一段重新定位对象。
- 旧 CAD 后端的 HEAD 使用完整 key,回滚前需同时恢复该次迁移备份中的 CAD 原值;不能只回滚代码。保留上线后的有效写入,不用旧备份覆盖新保存。
应用不会自动执行这些 SQL,本仓库不修改任何 `.sql` 文件。