跳至主要内容

內容安全策略

如果網站發送 Content-Security-Policy 請求頭，瀏覽器會阻止所有策略未明確允許的內容，包括 Kaleidr 的腳本、iframe 和請求。本頁說明使用各產品時需要允許哪些資源。如果網站沒有發送該請求頭，則無需閱讀本頁。

所需授權取決於產品在哪裡運行：

產品運行位置策略必須允許的內容
ViewerKaleidr 托管的 iframe 中加載器腳本和 iframe。
TileKaleidr 托管的 iframe 中加載器腳本、會話請求及 iframe。
Chat你自己的網頁中加載器腳本、API 請求、注入樣式、內嵌字體及圖片。
Editor你自己的網頁中，帶獨立地圖以上所有內容，加上底圖主機、地圖 worker 和地圖圖片。

對於 Viewer 和 Tile 兩種 iframe 產品，iframe 內的地圖及其加載的所有內容受 Kaleidr 自己的安全策略約束，而不是你的網頁策略。因此需要允許的內容較少。

使用的主機​

主機提供的資源使用產品
https://cdn.kaleidr.comkaleidr.js 及其加載的產品包（chat.js、viewer.js、editor.js、tile.js）。使用 SDK 時的所有產品。
https://api.kaleidr.com會話交換及 Chat 回答時發送的請求。Chat、Editor、Tile。
https://map-embed.kaleidr.comViewer 和 Tile iframe 內顯示的網頁。Viewer、Tile。
https://tile.kaleidr.comEditor 頁面內地圖的底圖，包括樣式、瓦片、精靈圖和字體。Editor。

Kaleidr 的任何產品都不要求允許 Mapbox、MapTiler 或 OpenStreetMap 的主機。此前版本曾列出這些地址，現在可以移除。如果你在網頁中運行自己的地圖，則仍需允許該地圖所用的主機。

Viewer​

使用 SDK 元素或 Kaleidr.mount 時：

script-src  https://cdn.kaleidr.com;
frame-src   https://map-embed.kaleidr.com;

使用 Studio 提供的普通 iframe 代碼時，不需要腳本：

frame-src   https://map-embed.kaleidr.com;

Viewer 不需要 connect-src 配置，因為沒有密鑰的 Viewer 不會從你的網頁發出請求。

Tile​

script-src  https://cdn.kaleidr.com;
connect-src https://api.kaleidr.com;
frame-src   https://map-embed.kaleidr.com;

connect-src 用於允許 SDK 在創建 iframe 之前，使用可公開密鑰進行會話交換。

Chat​

script-src  https://cdn.kaleidr.com;
connect-src https://api.kaleidr.com;
style-src   'unsafe-inline';
font-src    data:;
img-src     data: https:;
指令原因
script-src https://cdn.kaleidr.com加載器及 chat.js。
connect-src https://api.kaleidr.com會話交換，以及每次提問和回答。
style-src 'unsafe-inline'Chat 會在文檔 head 中添加一個沒有 nonce 的 <style> 元素。
font-src data:Chat 字體以 data: URL 形式內嵌在產品包中。
img-src data:Chat 圖標以內嵌的 data: URL 提供。
img-src https:地點卡片顯示照片，照片主機會因地點而異，無法在此全部列出。如果收緊 img-src，未允許的主機上的照片將無法加載。
img-src https:（網站圖標）回答中的鏈接和地點卡片中的網站會顯示網站圖標。圖標來自 Google 的 favicon 服務 https://www.google.com，並重定向到 https://t0.gstatic.com 至 https://t3.gstatic.com。如果收緊 img-src，就需要允許 https://www.google.com 和 https://*.gstatic.com，否則圖標缺失，但鏈接仍然可用。

Chat 產品包不包含地圖類庫，也不需要 'wasm-unsafe-eval'。它會繪制在網頁已有的地圖上，因此你仍需允許自身地圖庫要求的資源：腳本主機、connect-src 和 img-src 中的瓦片與樣式主機，以及 Mapbox GL JS、MapLibre GL JS 所需的 worker-src blob:。

如果 Chat 控制的是 Kaleidr 的 Viewer 或 Tile 元素，而不是你自己的地圖，還需添加該產品的指令，包括 frame-src https://map-embed.kaleidr.com。

Editor​

script-src  'self' https://cdn.kaleidr.com;
style-src   'self' 'unsafe-inline';
connect-src 'self' https://api.kaleidr.com https://tile.kaleidr.com;
img-src     'self' data: blob: https://tile.kaleidr.com;
worker-src  blob:;
font-src    'self' data:;
指令原因
script-src https://cdn.kaleidr.com加載器及 editor.js。
style-src 'unsafe-inline'Editor 通過 JavaScript 向文檔添加樣式表，不使用 nonce。
connect-src https://api.kaleidr.com會話交換。
connect-src https://tile.kaleidr.comEditor 從網頁獲取的底圖樣式、瓦片、精靈圖和標注字體。
img-src data: blob: https://tile.kaleidr.com地圖圖像及圖標；地圖通過 blob: 和 data: URL 創建圖像。
worker-src blob:地圖通過 blob: URL 運行其 worker。
font-src data:Editor 界面字體以 data: URL 形式內嵌。

'wasm-unsafe-eval' 不包含在默認列表中。只有控制台明確報告策略阻止了 editor.js 的 WebAssembly 編譯（用於解碼 3D 模型）時，才把它添加到 script-src。

如果通過 styleId 傳入完整樣式 URL，還必須在 connect-src 和 img-src 中允許該樣式自己的主機。

一個網頁使用多個產品​

將各產品的列表合併。例如，同時使用 Tile 地圖和控制它的 Chat 面板時，需要：

script-src  https://cdn.kaleidr.com;
connect-src https://api.kaleidr.com;
frame-src   https://map-embed.kaleidr.com;
style-src   'unsafe-inline';
font-src    data:;
img-src     data: https:;

完整策略示例​

以上代碼塊僅展示 Kaleidr 新增的許可要求。實際策略還要允許你自己的資源。以下是一個完整請求頭示例：網站從自己的來源提供其他所有資源，同時嵌入 Viewer 和 Tile：

Content-Security-Policy: default-src 'self'; script-src 'self' https://cdn.kaleidr.com; connect-src 'self' https://api.kaleidr.com; frame-src https://map-embed.kaleidr.com; style-src 'self' 'unsafe-inline'

示例中使用 style-src 'unsafe-inline' 的原因並非 Kaleidr 代碼本身，而是文檔示例使用內聯屬性 style="display:block; height:480px" 設置元素尺寸。不含 'unsafe-inline' 的策略會忽略內聯樣式屬性。如果你希望繼續阻止內聯樣式，可在自己的 CSS 樣式表中設置尺寸：

kaleidr-map { display: block; height: 480px; }

SDK 為 iframe 設置的尺寸不會受到影響，因為它是通過腳本設置的，而樣式策略不會阻止這一操作。元素默認的 display:block 也不受影響，因為它不是通過 <style> 標籤或 style 屬性實現的，因此不需要 'unsafe-inline'。

Nonce、哈希及 strict-dynamic​

  • 腳本。 加載器會將各產品包添加為 <script src> 元素。基於主機的 script-src 可以放行。如果策略使用 nonce 和 'strict-dynamic'，請把 nonce 放在加載器腳本標籤上。加載器隨後添加的腳本會通過 'strict-dynamic' 獲得信任，無需單獨列出主機。
  • 樣式。 SDK 無法為 Chat 和 Editor 注入的樣式設置 nonce，其內容會隨著版本發佈而變化，因此也無法固定哈希。這兩個產品需要在 style-src 中使用 'unsafe-inline'。Viewer 和 Tile 不會向你的網頁注入樣式。
  • 完整性。 不要為加載器腳本標籤添加 integrity 屬性，因為文件會在原地址更新。參見 CDN 版本管理。

如何識別被阻止的資源​

瀏覽器會在控制台報告每次阻止操作及觸發的策略指令。請對照下表排查。

現象控制台指出的指令需要添加的許可
無法掛載任何內容。Kaleidr is not defined。script-src在 script-src 中允許 https://cdn.kaleidr.com。
元素為空。控制台：[kaleidr:<product>] [kaleidr] failed to load …/embed/v1/<product>.jsscript-src允許相同主機。加載器已被放行（例如通過哈希），但它加載的產品包沒有被允許。
Viewer 或 Tile 顯示空白區域。frame-src（或 child-src、default-src）在 frame-src 中允許 https://map-embed.kaleidr.com。
Tile、Chat 或 Editor 無法啓動，sessions 請求被阻止。connect-src在 connect-src 中允許 https://api.kaleidr.com。
Chat 面板沒有樣式。style-src在 style-src 中允許 'unsafe-inline'。
Chat 圖標或字體缺失。img-src、font-src兩處都允許 data:。
Chat 中地點照片或鏈接旁圖標缺失。img-src在 img-src 中允許 https:，或控制台指出的主機。
Editor 面板顯示正常，但地圖空白。connect-src、worker-src 或 img-src在 connect-src 和 img-src 中允許 https://tile.kaleidr.com，在 worker-src 和 img-src 中允許 blob:。
Editor 沒有樣式。style-src在 style-src 中允許 'unsafe-inline'。
元素忽略 style 屬性中的高度。style-src無需新增許可，改用 CSS 樣式表設置尺寸。

並非所有故障都由策略導致。如果 sessions 請求已發出，但返回 401、403 或 429，說明策略放行了請求，是 API 拒絕了它。參見錯誤參考和 CORS 與允許的來源。

先以僅報告模式上線​

要在嚴格策略下引入 Kaleidr，又不影響生產環境網頁，可按以下流程進行：

  1. 保留現有策略，同時通過 Content-Security-Policy-Report-Only 發佈待測試的策略，並配置自己的報告端點。
  2. 測試嵌入組件：打開頁面、移動地圖，並在 Chat 中提問，確保返回帶照片的地點。
  3. 按報告指出的指令允許相應來源。地點照片通常會引入新的圖片主機。
  4. 報告中不再出現違反策略的情況後，改用 Content-Security-Policy。

不需要添加的內容​

  • 任何 Kaleidr 產品都不需要 Mapbox、MapTiler 或 OpenStreetMap 主機。
  • script-src 中的 'unsafe-inline'。加載器通過 <script src> 元素加載產品包，從不添加內聯腳本。
  • frame-ancestors。該指令控制哪些網站可將你的網頁放進 iframe，而不是你的網頁可加載哪些 iframe。
  • Viewer 或 Tile iframe 內部資源對應的許可項。

相關頁面​