跳到主要内容

CDN 版本管理

每个 embed 资源都通过一个 major-alias 路径提供：

https://cdn.kaleidr.com/embed/v1/kaleidr.js   ← the loader (façade)
https://cdn.kaleidr.com/embed/v1/chat.js      ← chat bundle
https://cdn.kaleidr.com/embed/v1/viewer.js    ← viewer loader
https://cdn.kaleidr.com/embed/v1/editor.js    ← editor bundle
https://cdn.kaleidr.com/embed/v1/tile.js      ← tile loader

您固定 kaleidr.js；随后它会依次请求每个产品 bundle 的 v1。

v1 实际代表什么​

  • v1 是主版本契约别名，而不是固定的 build。 /embed/v1/* 下不存在 patch 或 content-hash 路径。该 URL 所提供的文件 是当前的 v1 build，并直接发布到原位置；不存在可供您固定的 /embed/v1.2.3/…。
  • 向后兼容的修复会发布到 /embed/v1/ 下 — 您会 自动获得这些更新。这也包括行为扩展（新的稳定 SSE event、 新的 handle method）— 兼容规则要求客户端必须 忽略未知 wire 扩展，而不支持的 handle method 应 以带警告的 no-op 方式运行。
  • 破坏兼容性的 wire/postMessage 更改会作为新的主版本与 v1 并行发布： /embed/v2/kaleidr.js (+ /embed/v2/<product>.js)。您固定的 v1 URL 会继续原样工作；您可以按照自己的时间表，通过修改 路径进行迁移。

SSE wire contract 也以同样方式在 /inference-api/b2b/v1/* 下进行版本管理 — 只有发生破坏兼容性的 stream 更改时才会出现 v2。

缓存​

bundle 以 Cache-Control: public, max-age=300 提供，每次 publish 都会使 CloudFront distribution 失效 — 因此实际 传播时间为 edge 约 1–5 分钟，已经缓存旧文件的 浏览器最多还可能再延迟 300 秒。对于修复来说，这个速度很快； 也正因为如此，如果没有替换计划，不应对这些 文件进行 fingerprint 或长期本地缓存。

自托管​

仅将 kaleidr.js 指向您自己的 origin 并不能让您脱离 Kaleidr CDN — loader 在 mount 时仍会从 cdn.kaleidr.com 获取 lazy bundle （chat.js, editor.js, viewer.js, tile.js）。若要完全 self-host，请覆盖 loader base，并在 {origin}/embed/v1/ 镜像全部五个文件：

<script>window.__KALEIDR_EMBED_BASE__ = 'https://cdn.example.com';</script>
<script src="https://cdn.example.com/embed/v1/kaleidr.js"></script>

如果您的 embed 还会与 platform API 或 private tile CDN 通信， 请分别覆盖它们 — 参阅 api-base、 viewer-base 和 tile-base。