Files

7.4 KiB
Raw Permalink Blame History

正式部署与 OSS 直传

上传职责

本项目遵循 admin-api.md 的正式上传契约。开发环境、生产构建使用同一份代码:

  1. 浏览器向 /admin-api/storage/upload-signature 申请授权。
  2. 后端分配组件编码并返回短期上传签名、目标地址及允许的对象键前缀。
  3. 浏览器将原始授权字段和文件直接 POST 到签名响应中的 OSS uploadUrl,不签名、不持有长期 AccessKey Secret,也不自行决定 Bucket。
  4. OSS 返回 204 后,浏览器向组件新增/修改接口提交表单、令牌和文件引用。
  5. 后端校验 OSS 中的实际文件、路径、大小和令牌后入库。只有组件保存成功,前端才显示完成。

签名、文件校验和业务入库归后端,文件传输由浏览器完成。这是阿里云的“服务端签名直传”方案;参考 官方说明。如果产品改为文件先经过业务服务器,需要后端提供相应 multipart 上传接口,再统一修改 API 契约。当前没有擅自创建这种接口。

上传不依赖 Vite、本机转发地址或固定 Bucket。先前的本机上传代理已删除。

部署网络配置

2026-10-14 改为按网站域名直连 API,规则由 ../../shared/api-origin.ts 统一管理:开发网站(dev-cadworld / dev-cadworld-admin)使用 dev-cadworld-api.robotquan.com,正式网站(cadworld / cadworld-admin)使用 cadworld-api.robotquan.com,所有线上域名均为 HTTPS。本机/局域网访问保留 Vite 开发代理。

执行 npm run build,上传 dist 到静态网站目录;网页网站不再需要 /admin-api 反向代理,只需 SPA 回退:

location / {
    try_files $uri $uri/ /index.html;
}

管理业务接口使用当前环境 API 并携带 credentials: include。URDF、STEP 和网格下载统一直连 https://linkerbot.oss-cn-beijing.aliyuncs.com,按对象键逐段编码,不带 Cookie;不再调用 /admin-api/component-assets/ 下载接口。OSS 上传仍使用后端签名返回的地址和字段。后端需开放对应网站来源的 CORS 和 X-Request-Id / Content-Type 预检,允许业务方法;返回匹配 Origin 和 Allow-Credentials: true。详细规则和当前远端预检结果见 ../../Client/docs/ai-deployment.md。

2026-10-14 实测:正式 API 对正式网站预检已通过;开发 API 对开发网站预检返回 403 Invalid CORS request,需后端补齐开发来源。前端静态打包无法代替后端的跨域许可。

OSS CORS:由存储管理员配置

正式前端域名目前未定。拥有 Bucket 配置权限的人需要先核对现有 CORS 规则,再新增或合并本项目规则;不能覆盖其他应用的规则。当前没有访问 OSS 控制台或修改 Bucket 配置的授权凭据,尚未执行云端配置。

配置项 本项目需要
AllowedOrigin 页面实际来源,包括协议和端口;正式环境填写最终 HTTPS 前端域名
AllowedMethod POST
AllowedHeader Content-Type(如果以后添加自定义请求头,应按实际请求同步配置)
MaxAgeSeconds 600 可作为配置值
返回 Vary: Origin 多来源时勾选,避免缓存混用来源
ExposeHeader 可选 x-oss-request-id,用于诊断;当前上传不依赖此项
凭据 上传不带浏览器 Cookie,无需凭据跨域

当前开发来源为 http://127.0.0.1:8091;若使用 http://localhost:8091 或局域网地址,也分别添加实际来源。正式域名确定后只调整 Bucket 的配置,不修改前端上传逻辑。来源不带路径或尾部 /,HTTP/HTTPS、不同端口是不同来源。表单里的 x-oss-* 是授权表单字段,不是需要额外允许的请求头。

建议明确列出需要的来源。CORS 不替代签名权限,不要开放 Bucket 公共写入、关闭 TLS 校验或在前端放长期密钥。

验收命令与上线条件

只读跨域检查,不上传文件、不读取云密钥、不修改 OSS:

npm run check:oss-cors -- \
  --endpoint https://linkerbot.oss-cn-beijing.aliyuncs.com/ \
  --origin http://127.0.0.1:8091

部署时把 endpoint 换成正式签名返回的实际地址,origin 换成最终前端来源。可以重复 --origin 检查多个来源。失败退出码为 1,不能当作验收通过。脚本只检查 POST/CORS 通路,不能代替实际文件上传和后端保存验证。

部署验收必须在正式静态站点上执行:组件列表、用户与日志筛选;仅 STEP 且表单全部留空上传并保存、STEP + 完整 URDF 上传并保存;刷新详情与两种预览;单独替换 STEP、单独替换 URDF;版本冲突及失败重试;资源下载内容一致。大文件、批量文件及慢网络也需按实际业务规模验证。正式来源 CORS 和实际端到端验收通过之前,不能宣称上线完成。

服务端筛选

前端原样展示 API 的 items 和 total,不在本地筛选或排序业务记录。

页面 接口支持的筛选
组件库 keyword、category
用户管理 keyword、userType、status
操作日志 module、action、success、operatorId、keyword、targetType、targetId、targetCode、from、to

每个列表另使用接口的 page / size。未知日志模块和动作按返回值显示,不生成前端业务日志。组件没有分类目录接口,因此提供分类精确匹配输入框,不生成预设筛选选项。登录保留用户要求的现有行为,不在此次工作中新增认证 API。

STEP 必填规则同步(2026-10-14)

管理页面只要求 STEP;URDF、名称、分类、描述、BOM 和其他表单字段均选填。只上传 STEP 时签名响应无需提供 URDF 授权,保存请求不含 urdfObjectKeys,urdfInfo 为 null;未填质量、扭矩和自由度为 null。已有 STEP 的组件编辑不要求重新上传。

真实开发 API 校验仍返回 422:componentName / category must not be blank,urdfObjectKeys must not be empty。必须由后端同步取消这三项必填校验及服务层对 URDF 资源的强制要求,保留 STEP、上传令牌和已选资源有效性校验。旧 admin-api.md 记录的是此前契约,不能据此判断新规则已在服务器生效。同步要求和实测返回见 ../../releases/后台STEP必填-后端同步说明.txt。仅 STEP 的真实端到端入库仍待后端更新后验收。

模型文件直接下载(2026-10-14)

本地、开发站点和正式站点均使用同一桶域名,保留 API 返回对象键的环境目录;不自动把 cadworld_dev 改成其他目录。共享实现见 ../../shared/object-storage.ts。下载无业务 Cookie 和自定义请求头,桶需对实际页面来源允许 GET/HEAD。仅资源下载方式改变,业务 API 和服务端签名直传上传流程不变。