它的運作方式

運作原理:橋接器、每個工作階段一個引擎、啟動權杖、簽署的授權核發、定期回報、席位、Origin 規則,以及憑證存放的位置。

SQLly Embedded 把 SQLly 分成需要機密資訊和不需要機密資訊的兩半。SQLly 使用者介面以 WebAssembly 在使用者的瀏覽器中執行;所有會接觸資料庫的部分都在你的伺服器上運行,位於 SQLly Bridge 及其啟動的引擎內。你的網頁應用程式坐在橋接器旁,告訴它誰可以用哪些連線開啟 SQLly。本頁說明每個組件的功用,以及為什麼要這樣設計。

架構

SQLLY Embedded 架構 使用者的瀏覽器從你的網頁應用程式載入 SQLly,並透過 WebSocket 連上 SQLly 橋接器。你的應用程式透過其 loopback 管理 API 驅動橋接器。橋接器為每個工作階段執行一個 SQLly 引擎,由該引擎連線到你的資料庫。橋接器每 20 分鐘向 sqlly.app 檢查一次授權。 你的使用者 你的伺服器 sqlly.app 瀏覽器 SQLly(WebAssembly) 這裡沒有密碼 你的網頁應用程式 登入 · 誰獲得哪個設定檔 · 提供 web/ 嵌入的 sqlly-bridge :8444 /proxy(瀏覽器,wss) :8445 /manage(你的應用程式,回送) 設定檔 · 權杖 · 席位 · 授權 sqlly-cli 引擎 每個工作階段一個 你的資料庫 任何 SQLly 引擎 sqlly.app 簽署授權 每次簽入授予 https wss 持有人權杖 標準輸入輸出 每 20 分鐘報到一次
藍色路徑承載的是使用者的工作;虛線路徑則是授權簽到,不承載任何查詢、結果或憑證。離線授權完全不走這條路徑。

為什麼要分開

  • 機密只留在伺服器端。 瀏覽器沒辦法對自己的使用者藏住資料庫密碼,所以乾脆不讓它拿到密碼:瀏覽器只取得連線清單、送出查詢訊框,實際執行的是橋接器,憑證只有伺服器那端持有。
  • 你的應用程式依然掌管身分識別。 橋接器沒有使用者帳戶。你的應用程式已經知道誰已登入。它告訴橋接器「為 這個 使用者具備 這個 設定檔」,作法是簽發啟動權杖,而橋接程式信任該權杖。
  • 每個工作階段一個引擎。 每個瀏覽器分頁都有自己的 sqlly-cli 處理序,因此各個工作階段永不共用連線狀態、交易或暫存資料表,而當某個處理序當機時,只會影響一個分頁,而不是橋接程式。

在橋接內部

sqlly-bridge embedded 是一個處理程序,擔三個職責:

作業監聽於連線對象
瀏覽器代理:為每個 SQLly 分頁接受一條 WebSocket 連線,檢查其 Origin 與啟動權杖,以權杖所屬的設定檔啟動引擎,並雙向轉送訊框。--bind,預設 0.0.0.0:8444,路徑 /proxy瀏覽器(前方加上 TLS)
管理 API:設定檔、啟動權杖、席次、連線測試、授權狀態,以及查詢稽核記錄。 參考文件.--manage-bind,預設 127.0.0.1:8445僅限你應用程式的伺服器端,並使用 Bearer 權杖
授權監控器:啟動時以及每 20 分鐘(連線時)向 sqlly.app 報到,離線時每分鐘重新讀取授權檔,並讓橋接器在授權狀態之間切換。無透過 HTTPS 連到 sqlly.app(僅在連線時)

它的 狀態目錄 (--state-dir,在 Linux 和 macOS 上以僅限擁有者權限建立) 會把每個設定檔存成 profiles/<id>.json,最近一次有效的授權 (license.json)、已連結安裝的金鑰(license-key,模式 0600)、它交給引擎的各工作階段認證檔,以及查詢稽核軌跡(queries.jsonl:工作階段執行過的每個查詢及其 SQL 文字)。請備份它,並像對待密碼檔一樣保守其機密,因為它就是一份密碼檔。 放在哪裡,以及 Windows 需要什麼.

設定檔:使用者可以看到的內容

A 設定檔 是一份有名稱的 SQLly 憑證文件:與 SQLly 桌面應用程式匯入匯出相同的 JSON 格式。其中列出連線(伺服器、資料庫、引擎、驗證、TLS、安全規則),以及用來上色和分組的客戶、專案和環境標籤。你的應用程式儲存設定檔時會一併附上 PUT /manage/profiles/{id}。橋接程式會預先驗證整份文件,並一次回報所有問題,所以像 "pasword" 會明顯報錯,而不是被默默忽略。

在橋接程式中,使用者不屬於任何設定檔;每次啟動都會指明一個。給分析人員一個唯讀設定檔(一個帶有 only_allow_select,或 block_all_but_select :引擎在到達資料庫之前會拒絕 SELECT 以外的任何操作),給支援人員另一個設定檔,或者在多租戶應用程式中為每個客戶建立一個設定檔。檔案型引擎(SQLite、DuckDB)會被拒絕,除非橋接器是以 --allow-file-engines,因為它們會讓使用者能存取橋接主機上的檔案。想給某個人少一點連線數,就再建一個設定檔。工作階段開啟時,瀏覽器會收到該設定檔的 目錄:連線名稱、引擎、資料庫與標籤,所有機密一概移除。編輯設定檔會在下一次啟動時生效。已開啟的工作階段則沿用啟動當下的目錄。

一個工作階段的生命週期

為使用者啟動 SQLly 瀏覽器向你的應用程式請求 SQLly。你的應用程式向橋接器取得啟動權杖,並傳回附帶代理 URL 與權杖的 SQLly 頁面。瀏覽器帶著權杖對橋接器開啟 WebSocket。橋接器檢查 Origin、權杖、授權與席位數,用設定檔的認證資訊啟動引擎,並向瀏覽器送出一則附帶連線目錄與授權狀態的 hello。查詢訊框接著從瀏覽器經由橋接器與引擎送抵資料庫,再傳回來。 瀏覽器 你的應用程式 橋接 引擎 資料庫 1 個開啟的 SQLly(已登入) 2 POST /manage/tokens 3 201 {token, proxyUrl} 4 SQLly 頁面 + 權杖 5 wss /proxy?token=…(會檢查 Origin) 6 start,附帶憑證 7 hello {catalog, license} - 不含機密 8 查詢訊框 SQL 資料列 9 結果串流回來 權杖在過期前可以重複使用(重新載入頁面就會過期);關閉最後一個分頁會立即釋放席位。
步驟 2-4 是你的應用程式唯一需要實作的部分。WebSocket 開啟之後的一切,都是瀏覽器與橋接器之間的事。
  1. 已登入的使用者在你的應用程式中開啟 SQLly 頁面。
  2. 你的伺服器呼叫 POST /manage/tokens 使用你的 ID 來指定使用者及其應得的設定檔,並可選擇開啟的內容:查詢分頁及其指令碼、連線、參數值和游標(啟動內容).
  3. 橋接器會檢查授權與席位數,擷取設定檔,並回傳隨機權杖、其到期時間與公開代理 URL。
  4. 你的伺服器返回 SQLly 頁面 (web/index.html),並在此之前設定了兩個全域變數 boot.js: SQLLY_PROXY_URL 和 SQLLY_PROXY_TOKEN.
  5. SQLly 開啟 wss://…/proxy?token=…。橋接程式依序檢查:瀏覽器的 Origin (在升級時被 403 拒絕)、權杖、授權、使用者開啟中的工作階段,以及它自己的工作階段上限。瀏覽器無從得知升級失敗的原因,因此來源檢查之後的每一次拒絕,都會透過已開啟的 socket 以 error 含有原因的訊息,後面接著結束代碼 4000 + HTTP status (4401 權杖不明或過期、4503 授權異常、4429 工作階段上限);SQLly 會顯示那句話。
  6. 橋接器會將設定檔的認證資訊寫入每個工作階段私有的檔案,並啟動 sqlly-cli 以引擎模式搭配使用。
  7. 瀏覽器會收到一則 hello,其中帶有不含機密的連線目錄與目前的授權狀態。以啟動脈絡簽發的權杖,其第一個工作階段還會收到要開啟的分頁;SQLly 會載入它們,但不執行任何動作。
  8. 從這裡開始,SQLly 的請求(連線、執行、取消、擷取 IntelliSense 中繼資料、翻頁瀏覽結果)都會以二進位訊框傳輸。橋接器會把它們轉送給引擎,並將每個查詢與資料列編輯記錄到它的 稽核軌跡,而且當授權失效時會拒絕它們並顯示訊息。

席位與工作階段

A 席 是一個仍有進行中工作階段或未過期啟動權杖的個別使用者 ID。席位以同時使用計,而非以人名綁定:當使用者的最後一個分頁關閉、最後一個權杖也過期,席位立即釋放,別人就能使用。授權下的所有橋接會合併計算席位,因為 sqlly.app 在每次簽入時會回報其他執行個體上的使用者。

  • 為這樣的使用者簽發權杖:該使用者 已經 持有席次的使用者一律會成功;當所有席次都被佔用時,為新使用者簽發權杖會失敗,錯誤為 409 seat_limit,因此你的應用程式可以顯示明確訊息。
  • 每個席位可以容納 sessionsPerSeat 開啟的分頁:付費方案四個,試用方案一個。多出來的分頁會收到通知並關閉(代碼 4429)。橋接器會 ping 每個分頁,90 秒沒有回應的分頁會被中斷,因此因筆電休眠而失聯的分頁會自行釋放其工作階段;使用者的最後一個分頁關閉時,其啟動權杖會在兩分鐘內過期。
  • DELETE /manage/seats/{user} 會撤銷使用者的權杖並關閉其工作階段。當有人從你的應用程式登出或失去存取權時,就呼叫它。
  • 使用者 ID 由你自行決定。如果不想傳送電子郵件地址,請使用穩定、不透明的 ID(資料庫鍵值或雜湊):持有席位的 ID 會回報給 sqlly.app,以便跨橋接器統計席位。

誰可以連線:Origin 規則

每個授權都綁定到一個網域。橋接器僅在其 Origin 標頭允許的是該網域或其任何子網域(不限深度、通訊協定或連接埠),或 localhost / 127.0.0.1 / [::1] 當 --allow-localhost-origins 開啟時(預設值,供開發用)。沒有綁定網域的授權只允許 localhost。請在 你的 Embedded 頁面,或 --domain.

管理 API 完全不送出 CORS 標頭。這是伺服器對伺服器的通訊:其他來源的瀏覽器無法呼叫它,而且它本來就應該繫結到 loopback。

授權如何強制執行

橋接器只信任一樣東西: 授權授與,一份由 sqlly.app 以 ES384 (ECDSA P-384) 簽署的精簡 JWS。驗證金鑰已編譯進橋接器。每項授權內容(席次、每席次的工作階段數、橋接器執行個體、網域、期間結束日、寬限天數、功能)都讀自授權的簽章聲明,外層未簽署的 JSON 只用於顯示。

連線版授權

  • 在啟動時以及每 20 分鐘,橋接器會發送 POST /api/embedded/checkin 內容包含其授權金鑰、執行個體 ID、全新的 32 位元組 nonce、版本與主機名稱、啟動時所屬的網域,以及目前持有席位的使用者 ID。
  • 回覆中的授權必須能以編譯時內建的金鑰驗證、回傳同一個 nonce、指明這個執行個體與同一份授權,且簽發時間與橋接器的時鐘相差不得超過 5 分鐘。重放或偽造的回覆過不了這些檢查,會計為一次簽到失敗。請保持主機時鐘正確(NTP)。
  • 授權有效期為 40 分鐘。如果無法連上 sqlly.app,橋接器會以最後一份有效授權繼續提供服務,直到用完為止,屆時就會變為 過期 並在下一次成功簽入之前拒絕工作,過程不必重新啟動。在中斷期間重啟的橋接器,只會在快取的授權尚未過期時,才憑該授權啟動。
  • 每個已連線的授權可同時允許一定數量的橋接 執行個體 同時(預設一個)。同一把金鑰的第二個橋接器會被記錄下來,但在第一個還持續簽入時不會獲准。正常關閉的橋接器會立刻釋出名額;異常終止的則要 40 分鐘後才釋出。

離線授權

離線授權是一個檔案({ "format": "sqlly-embedded-license", "version": 1, "token": "<grant>" })在網域設定完成後就能從 sqlly.app 下載。裡面的授權長期有效:到期日是週期結束日再加寬限天數。橋接器會在本機驗證授權,完全不會聯絡 SQLly 的任何伺服器,並且每分鐘重新讀取檔案一次,所以續約就是換掉檔案。離線授權沒有執行個體數量上限。

關聯安裝

沒有金鑰、也沒有檔案就啟動的橋接器是 未授權:管理 API 可以運作(你可以設定並測試設定檔),但啟動會被拒絕。你的管理應用程式之後就能把它連結起來,過程中沒有人需要複製金鑰:它先向 sqlly.app 索取連結碼,由授權擁有者在自己的瀏覽器裡核准,應用程式再取得一把專為這個安裝鑄造的金鑰,並將它交給橋接程式,靠的是 PUT /manage/license。橋接程式會驗證它、儲存它,並在重新啟動後繼續使用。每份已連結的安裝都有自己的金鑰,所以擁有者可以撤銷其中一份,不影響其他。 如何建置它.

當授權無效時

在每種狀態下都是如此,除了 ok 和 grace,橋接器會讓已開啟的通訊端保持連線,但對每個請求框架回以一則夾帶簡短說明的失敗(「…40 分鐘無法向 sqlly.app 確認授權;請你的管理員查看。」)。SQLly 用戶端會在狀態列和通知中顯示這句話,讓使用者知道原因。新的工作階段會收到同一句話然後被關閉(代碼 4503),啟動權杖則會被拒絕,並收到 503 license_not_ok。在期限結束後的 15 天寬限期內,一切正常,但每個使用者都會看到倒數計時。 每種狀態,都有說明.

有哪些資料會離開你的伺服器

回報時傳送給 sqlly.app 的內容絕不傳送到任何地方
授權金鑰 · 橋接執行個體 ID · 橋接版本 · 主機名稱 · 要求的網域 · 持有席位的使用者 ID · 開啟中的工作階段數 查詢 · 結果 · 資料庫名稱與主機 · 憑證 · 設定檔 · 使用者輸入的任何內容

離線授權完全不對外傳送任何資料。瀏覽器只跟你的應用程式和你的橋接器通訊。