Files
frontend/Client/docs/ai-deployment.md

6.0 KiB
Raw Permalink Blame History

按网站域名选择 API 与静态部署

2026-10-14 更新:Client 与 Management 共用 ../../shared/api-origin.ts。同一份 dist 可部署到对应的开发或正式网站,由浏览器实际访问的 hostname 决定 API。

网站来源 API
https://dev-cadworld.robotquan.com https://dev-cadworld-api.robotquan.com
https://dev-cadworld-admin.robotquan.com https://dev-cadworld-api.robotquan.com
https://cadworld.robotquan.com https://cadworld-api.robotquan.com
https://cadworld-admin.robotquan.com https://cadworld-api.robotquan.com
localhost、回环及局域网 IP 本地开发代理

未知网站域名会明确报告未配置,不自动连到正式环境。.env.local 的 ROBOT_API_TARGET 仅控制本地代理。新增域名需在共享模块中明确配置并重新构建。

部署

运行 npm run build,将 dist 上传至对应的静态网站目录。网页网站只需配置路由回退:

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

线上业务请求直接访问 API 域名,无需在网页站点增加 /api/robot-* 或模型资源代理。服务端开发代理仅服务本地开发。旧说明中要求网页站点配置同源接口代理的内容已被本次直连方案取代。

请求与资源

JSON、multipart 图片上传、POST SSE、查询、重试与取消使用同一 API 地址规则。需求请求保留 credentials: include。后端返回的私有图片预览地址也转换为当前环境 API。

URDF、STL/OBJ/DAE 及贴图直接从 https://linkerbot.oss-cn-beijing.aliyuncs.com 下载。返回的 /admin-api/component-assets/ 或旧 /api/robot-model-assets/ 前缀只用于提取对象键,不再调用该下载接口。对象键中的 cadworld_dev/cadworld 等目录按接口返回值保留,不随页面环境替换。中文路径每段正确编码,查询参数和已返回的直连签名地址保留。模型请求不带业务 Cookie。JSON、SSE 和用户上传需求图片仍按网站域名访问业务 API。

后端跨域

网页与 API 域名不同。后端应允许对应网站的 Origin;OPTIONS 不应被鉴权或 CSRF 提前拦截。支持 GET、POST、PUT、PATCH、DELETE、HEAD、OPTIONS 及 Content-Type、X-Request-Id 请求头。响应需提供匹配的 Access-Control-Allow-Origin、Access-Control-Allow-Credentials: true,不能与通配 Origin * 组合。普通响应、SSE 和模型资源响应都应正确包含 CORS 头,不只是预检。

会话 Cookie 由 API 域名设置与接收,保留 HttpOnly / Secure 和合适的 SameSite 策略,前端不读写 Cookie。线上网站和 API 均使用 HTTPS。

验证结果

2026-10-14:前台 53 项测试通过,管理后台 82 项测试通过,两套构建成功。覆盖环境域名选择、本地代理、直连 JSON、multipart、SSE、私有图片和模型资源路径。

只读远端检查:正式 API 对正式后台的 GET /admin-api/components(X-Request-Id)预检以及正式前台 POST /api/robot-conversations(Content-Type)预检返回 200,包含准确 Origin、允许的请求头及 Allow-Credentials: true。开发 API 对开发前台/后台预检返回 403 Invalid CORS request,未携带 CORS 许可头,需后端补齐开发来源。此检查没有创建线上会话或执行上传,不等于完整线上业务验收。

文件坐标与接口对齐(2026-10-14)

连接计算统一使用 T_child_root = T_parent_root × T_parent_port × inverse(T_child_port)。接口位置和三个坐标轴同时重合,不再插入 X 轴 180° 翻转,不根据“头应该朝上”修改文件定义。局部关节、visual origin、网格和源文件字节保持不变,变换只作用于组件外层组。

后端可标识资源和配对节点,但额外装配矩阵不覆盖实际 URDF 接口计算。对齐只施加刚体变换,不缩放、镜像或剪切。没有唯一安装点的零件单独展示,不猜用根节点。跨零件关系缺失只影响连接,不隐藏正常加载的零件。

前后台联合回归测试使用含非零 XYZ/RPY、多级父节点和倒置接口的 URDF,检查前台组件内的累计矩阵与后台原始预览逐节点一致,装配后两接口完整世界矩阵重合,上传 File 内容没有变化。后台点位悬停和适配视图只调整相机与独立标记。颜色和光照是既有显示效果,不属于原始几何坐标。

本地来源与资源接口复查(2026-10-14,后续)

已修复 Vite 本地代理将浏览器 localhost Origin 转发到远端 API 后被 CORS 拒绝的问题。开发和 preview 在代理前校验请求 Origin 与当前 Host 一致,拒绝外站来源,校验通过后不向上游转发本地 Origin;该规则与独立 Node 本地代理一致。Management 使用同一中间件。线上按域名直连规则不变。

错误处理已修复:403/502 等非 JSON 网关响应保留 HTTP 状态,不再误报为后端字段格式不完整。新增回归测试通过,当前前台 59 项、后台 83 项测试通过;本地原需求已完成真实解析、匹配及两个模型加载。

开发 API 会话业务路径当前已允许开发前台。当前剩余线上问题仅限已测模型资源路径:/admin-api/component-assets/** 对开发后台 Origin 返回 200,对开发前台 Origin 返回 403 Invalid CORS request,同一文件匿名无 Origin 请求也是 200。后端需要在模型资源 CORS 规则中加入前台来源,不应仅开放 /api/**。此前文档中的整体开发来源失败记录是早期结果,以本段按路径区分的后续实测为准。

模型桶直连更新(2026-10-14)

前台和后台共用 ../../shared/object-storage.ts。管理后台 STEP、URDF 及全部依赖资源直接拼接对象键下载;前台将接口返回的模型资源 URL 转成同一桶地址。业务接口和后端签名直传上传流程保持原有契约。此前模型下载接口的 403 排查记录只适用于旧下载方式。存储桶需对实际网站来源允许 GET/HEAD;前台开发来源的示例 URDF 已实测 200。前台 61 项、后台 88 项测试通过,均生产构建成功。