它的運作方式
運作原理:橋接器、每個工作階段一個引擎、啟動權杖、簽署的授權核發、定期回報、席位、Origin 規則,以及憑證存放的位置。
SQLly Embedded 把 SQLly 分成需要機密資訊和不需要機密資訊的兩半。SQLly 使用者介面以 WebAssembly 在使用者的瀏覽器中執行;所有會接觸資料庫的部分都在你的伺服器上運行,位於 SQLly Bridge 及其啟動的引擎內。你的網頁應用程式坐在橋接器旁,告訴它誰可以用哪些連線開啟 SQLly。本頁說明每個組件的功用,以及為什麼要這樣設計。
架構
為什麼要分開
- 機密只留在伺服器端。 瀏覽器沒辦法對自己的使用者藏住資料庫密碼,所以乾脆不讓它拿到密碼:瀏覽器只取得連線清單、送出查詢訊框,實際執行的是橋接器,憑證只有伺服器那端持有。
- 你的應用程式依然掌管身分識別。 橋接器沒有使用者帳戶。你的應用程式已經知道誰已登入。它告訴橋接器「為 這個 使用者具備 這個 設定檔」,作法是簽發啟動權杖,而橋接程式信任該權杖。
- 每個工作階段一個引擎。 每個瀏覽器分頁都有自己的
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 頁面。
- 你的伺服器呼叫
POST /manage/tokens使用你的 ID 來指定使用者及其應得的設定檔,並可選擇開啟的內容:查詢分頁及其指令碼、連線、參數值和游標(啟動內容). - 橋接器會檢查授權與席位數,擷取設定檔,並回傳隨機權杖、其到期時間與公開代理 URL。
- 你的伺服器返回 SQLly 頁面 (
web/index.html),並在此之前設定了兩個全域變數boot.js:SQLLY_PROXY_URL和SQLLY_PROXY_TOKEN. - SQLly 開啟
wss://…/proxy?token=…。橋接程式依序檢查:瀏覽器的Origin(在升級時被 403 拒絕)、權杖、授權、使用者開啟中的工作階段,以及它自己的工作階段上限。瀏覽器無從得知升級失敗的原因,因此來源檢查之後的每一次拒絕,都會透過已開啟的 socket 以error含有原因的訊息,後面接著結束代碼4000 + HTTP status(4401 權杖不明或過期、4503 授權異常、4429 工作階段上限);SQLly 會顯示那句話。 - 橋接器會將設定檔的認證資訊寫入每個工作階段私有的檔案,並啟動
sqlly-cli以引擎模式搭配使用。 - 瀏覽器會收到一則 hello,其中帶有不含機密的連線目錄與目前的授權狀態。以啟動脈絡簽發的權杖,其第一個工作階段還會收到要開啟的分頁;SQLly 會載入它們,但不執行任何動作。
- 從這裡開始,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 · 開啟中的工作階段數 | 查詢 · 結果 · 資料庫名稱與主機 · 憑證 · 設定檔 · 使用者輸入的任何內容 |
離線授權完全不對外傳送任何資料。瀏覽器只跟你的應用程式和你的橋接器通訊。