Files
community/docs/oss-storage-paths.md
T
2026-11-04 17:35:31 +08:00

7.3 KiB
Raw Blame History

数据库 OSS 引用统一规范与存量转换

所有平台托管 OSS 资源的专用数据库字段统一保存未进行 URL 编码、以 / 开头、不含域名和环境根目录的路径。目录字段保留末尾 /。实际上传对象键、HEAD/复制使用的 key 和公开访问 URL 由 vibemake.oss.root-directory 与公开基础地址在运行时生成。

位置 数据库存储示例 实际 OSS key 示例
CAD 当前设计及上传批次 /cad-projects/{项目编码}/{批次编码}/design.sc vibemake_dev/cad-projects/{项目编码}/{批次编码}/design.sc
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 批次和保存确认已采用此格式。项目完整保存、Fork 和导入工具状态回写统一规范资源引用;普通资源签名和确认继续使用已有相对路径。应用兼容读取当前环境的历史完整 key,但读取不自动迁移数据库。升级前签发的 CAD 批次仍可确认,确认时同时规范项目和该批次的引用。幂等重放保持原有回执规则。

现有数据手工转换 SQL

PCB 两张新表直接采用环境相对路径,建表见 PCB 工作空间 SQL,无需执行下列 CAD 与社区资源的历史转换。

无需修改字段结构。先升级所有在线写入进程与导入工具,再暂停资源写入并备份业务库。在对应环境的业务数据库连接中执行;test 使用 vibemake_dev,prod 将 @oss_root 改为 vibemake。不会移动、复制或删除 OSS 对象,也不修改项目版本、保存时间、上传回执和业务更新时间。

仅当字段精确以当前环境和对应资源目录开头时转换,使用二进制前缀比较避免大小写或下划线通配符误匹配,不使用全局 REPLACE。已经是相对路径的记录、空值和其他环境路径不变;本转换可重复执行。

-- 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 历史迁移。按当前 OSS/CDN 及已配置历史基础地址逐个执行;非标准、编码或带参数的历史图片先核验,正常重新保存时应用会按受控资源规则转换,不盲目截断成路径。

验证和回退

  • 抽查 CAD 两张表和 project 的资源字段均为 /cad-projects/、/urdf/、/project-resources/ 等相对路径。
  • 通过 API 重新获取的下载地址与转换前指向同一个真实对象,仍包含当前环境前缀。
  • 核验升级前未确认 CAD 批次、重复确认、重新保存、Fork 继承和项目资源列表。
  • 未转换的其他环境或异常路径单独核验,不能通过任意删除路径第一段重新定位对象。
  • 旧 CAD 后端的 HEAD 使用完整 key,回滚前需同时恢复该次迁移备份中的 CAD 原值;不能只回滚代码。保留上线后的有效写入,不用旧备份覆盖新保存。

应用不会自动执行这些 SQL,本仓库不修改任何 .sql 文件。