# 数据库 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` 文件。