建立你自己的應用程式
逐步教學:從你自己的網頁應用程式操控 SQLly Embedded 橋接器——儲存設定檔、簽發啟動權杖、代管瀏覽器版、釋放席位並綁定安裝。
範例應用程式是你產品的替身。它做的每一件事都會經過橋接程式的 管理 API,所以任何伺服器端堆疊都能取代它:Node、ASP.NET、Django、Rails、Go、PHP。本頁會逐步走過範例應用程式做的每一項工作,以及如何在你自己的應用程式裡完成。範例以 JavaScript (Node 20+) 和 C# (ASP.NET Core) 撰寫,同樣的呼叫在任何說得出 HTTP 和 JSON 的環境都適用。
直接產生用戶端,不必自己手寫。 swagger.json 是整個管理 API 的 OpenAPI 3.0 描述。把它交給 openapi-generator、NSwag、Kiota 或你順手的 HTTP 工具。範例應用程式的 sample-app/lib/bridge.js 也是一個完整的手寫客戶端,大約 120 行。
你的應用程式接管的部分
| 作業 | 在範例應用程式中 | 在你的應用程式中 |
|---|---|---|
| 讓使用者登入 | 它自己的使用者檔案,使用 scrypt 密碼 (lib/auth.js) | 你現有的登入、SSO、工作階段 |
| 決定誰可以看到哪些連線 | 每個使用者都會被指派一個設定檔 | 你的角色、團隊、租用戶或方案決定設定檔 ID |
| 定義連線 | 設定檔編輯器,「標籤」分頁(lib/credentials.js 建立這份文件) | 你的管理介面、設定檔,或是以你的租用戶資料建立文件的程式碼 |
| 開啟 SQLly | GET /app/ 會簽發一個權杖並把它注入 index.html | 一個路由即可做到同樣的事(步驟 4) |
| 提供網頁封裝 | /app/* 使用隔離標頭 | 你的靜態檔案伺服器或具備相同標頭的 CDN 路徑 (步驟 5) |
| 免費席位 | 使用者頁面, 釋放席位 | 在登出時以及移除存取時呼叫它(步驟 6) |
| 顯示授權狀態 | 狀態頁面 | 健康檢查或管理小工具(步驟 7) |
| 連結到授權 | 連線到 sqlly.app | 可選:或者設定金鑰或授權檔案(步驟 8) |
1. 在你的應用程式旁邊執行橋接程式
沒有啟動腳本的話,橋接器只要一個命令。管理權杖產生一次,把同一個值交給橋接器和你的應用程式(環境變數或機密存放庫,絕不放進你的儲存庫):
export SQLLY_EMBEDDED_MANAGE_TOKEN="$(openssl rand -base64 24)"
export SQLLY_EMBEDDED_LICENSE_KEY=sqe_… # or SQLLY_EMBEDDED_LICENSE_FILE, or neither and link later
./bin/sqlly-bridge embedded \
--domain portal.example.com \
--public-url wss://portal.example.com/sqlly/proxy \
--manage-bind 127.0.0.1:8445 \
--state-dir /var/lib/sqlly-embedded
你的應用程式會與 http://127.0.0.1:8445 與 Authorization: Bearer $SQLLY_EMBEDDED_MANAGE_TOKEN。瀏覽器會連到 Proxy 監聽器(:8444)透過你的反向代理。 正式環境詳細資料.
2. 一個小型管理用戶端
javascript (node 20+)const BRIDGE = process.env.SQLLY_BRIDGE_URL ?? 'http://127.0.0.1:8445';
const TOKEN = process.env.SQLLY_EMBEDDED_MANAGE_TOKEN;
export async function bridge(method, path, body) {
const res = await fetch(BRIDGE + path, {
method,
headers: {
authorization: `Bearer ${TOKEN}`,
...(body ? { 'content-type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
});
if (res.status === 204) return null;
const json = await res.json().catch(() => null);
if (!res.ok) {
// Every error is { error, message } (+ problems for invalid documents).
throw Object.assign(new Error(json?.message ?? `bridge HTTP ${res.status}`),
{ code: json?.error, status: res.status, problems: json?.problems });
}
return json;
}
c# (asp.net core)
builder.Services.AddHttpClient("sqlly-bridge", c =>
{
c.BaseAddress = new Uri(builder.Configuration["Sqlly:BridgeUrl"] ?? "http://127.0.0.1:8445");
c.DefaultRequestHeaders.Authorization =
new("Bearer", builder.Configuration["Sqlly:ManageToken"]);
});
public sealed record BridgeError(string Error, string Message, string[]? Problems);
public sealed record MintedToken(string Token, DateTimeOffset ExpiresAt, string ProxyUrl,
string User, string Profile, int SeatsUsed, int Seats);
3. 儲存設定檔
設定檔是一個 SQLly 憑證文件 外加一個顯示名稱。要怎麼建立都行:從你資料庫裡的資料列、從各租戶專屬的範本,或從管理表單。 GET /manage/engines 列出每個引擎 ID、其預設連接埠以及接受的登入類型,這樣表單就不會寫死它們。
await bridge('PUT', '/manage/profiles/acme-analysts', {
name: 'Acme analysts',
credentials: {
format: 'sqlly-credentials',
version: 1,
clients: [{ name: 'Acme', color: '#1E88E5' }],
environments: [{ name: 'Production', safety: { only_allow_select: true } }],
sql_auth_accounts: [{ name: 'Reader', username: 'acme_ro', password: secrets.acmeReader }],
connections: [
{ name: 'Orders', engine: 'postgres', server: 'pg1.internal', database: 'orders',
environment: 'production', client: 'Acme',
authentication: { type: 'sql-login', account: 'Reader' }, tls: { mode: 'verify-full' } },
],
},
});
- 設定檔 ID 範圍為 1-64 的
A-Z a-z 0-9 _ -。使用你自己的穩定識別碼(租用戶 ID、角色名稱)。 - 橋接器會在儲存前驗證整份文件。格式錯誤的文件會傳回
400 invalid_profile與problems會列出每一個錯誤。未知鍵一律算錯誤,所以打錯字也逃不掉。 - 橋接器是機密資料的權威儲存庫。真實來源你想放哪裡都行,但每次變更都要重新
PUT設定檔。範例應用程式在啟動時會重新傳送每個設定檔,因此新的狀態目錄會自行重新填入。 - 使用標籤與安全旗標。
only_allow_select在生產環境中,或者confirm_data_changes在連線上設定的內容,SQLly 會對所有開啟該設定檔的人強制執行。
在儲存之前,你可以使用 POST /manage/test-connection 以及一份只含該連線的文件。失敗會回傳為 { "ok": false, "message": "<the engine's own error>" } 並附帶 HTTP 200,準備顯示在表單旁。
4. 為已登入的使用者啟動 SQLly
這是每個整合都必備的路由:當已登入的使用者開啟 SQLly 時,替他們簽發權杖,並回傳套件的 index.html 在兩個全域變數都設定的情況下 在 這 boot.js 模組標籤:
import { readFile } from 'node:fs/promises';
const ISOLATION = {
'Cross-Origin-Opener-Policy': 'same-origin',
'Cross-Origin-Embedder-Policy': 'require-corp',
};
const BOOT_TAG = '<script type="module" src="./boot.js"></script>';
// JSON for an inline script: never let a value close the tag.
const js = (v) => JSON.stringify(v).replace(/</g, '\\u003c');
app.get('/sqlly/', requireSignIn, async (req, res) => {
const profile = profileFor(req.user); // your rule: role, team, tenant…
let minted;
try {
minted = await bridge('POST', '/manage/tokens', { user: req.user.id, profile });
} catch (err) {
if (err.code === 'seat_limit') return res.status(409).send('All SQLly seats are in use right now.');
if (err.code === 'license_not_ok') return res.status(503).send(err.message);
throw err;
}
const html = (await readFile('web/index.html', 'utf8')).replace(BOOT_TAG,
`<script>globalThis.SQLLY_PROXY_URL=${js(minted.proxyUrl)};` +
`globalThis.SQLLY_PROXY_TOKEN=${js(minted.token)};</script>` + BOOT_TAG);
res.set(ISOLATION).set('Cache-Control', 'no-store').type('html').send(html);
});
c#(asp.net core minimal api)
app.MapGet("/sqlly/", async (HttpContext http, IHttpClientFactory clients, IWebHostEnvironment env) =>
{
var user = http.User.FindFirst("sub")!.Value;
var bridge = clients.CreateClient("sqlly-bridge");
var reply = await bridge.PostAsJsonAsync("/manage/tokens", new { user, profile = ProfileFor(http.User) });
if (!reply.IsSuccessStatusCode)
{
var error = await reply.Content.ReadFromJsonAsync<BridgeError>();
return Results.Text(error?.Message ?? "SQLly is unavailable.", statusCode: (int)reply.StatusCode);
}
var minted = (await reply.Content.ReadFromJsonAsync<MintedToken>())!;
const string bootTag = "<script type=\"module\" src=\"./boot.js\"></script>";
// JsonSerializer escapes < > & by default, so the values can't close the tag.
var globals = $"<script>globalThis.SQLLY_PROXY_URL={JsonSerializer.Serialize(minted.ProxyUrl)};" +
$"globalThis.SQLLY_PROXY_TOKEN={JsonSerializer.Serialize(minted.Token)};</script>";
var html = (await File.ReadAllTextAsync(Path.Combine(env.ContentRootPath, "sqlly-web", "index.html")))
.Replace(bootTag, globals + bootTag);
http.Response.Headers["Cross-Origin-Opener-Policy"] = "same-origin";
http.Response.Headers["Cross-Origin-Embedder-Policy"] = "require-corp";
http.Response.Headers.CacheControl = "no-store";
return Results.Content(html, "text/html");
}).RequireAuthorization();
- 在伺服器端依每次請求簽發。 永遠不要將管理權杖放在頁面中。啟動權杖可以安全地交給它所簽發對象的使用者:它只會以該使用者的設定檔開啟 SQLly,並且會過期(預設為 10 分鐘;傳入
ttlSeconds在 10 到 86,400 之間)。 - 重複使用沒問題。 權杖在到期前都有效,所以重新載入頁面不需要新的權杖。範例應用程式會快取每個使用者的權杖,並在到期前一分鐘重新簽發。為同一位使用者重新簽發權杖,絕不會多佔一個席位。
- 直接開到查詢,而不只是工作臺。 新增
open傳給 mint 呼叫,使用者就會直接進入已設定好腳本、連線、參數值與游標的查詢分頁。這些啟動每一次都要 mint 一個全新的權杖:分頁只會在該權杖啟動的第一個工作階段開啟。 在查詢上開啟 SQLly. - 使用者 ID 由你決定。 請傳遞穩定且不含個資的 ID。席位以不重複的 ID 計算,持有席位的 ID 會在簽入時回報給 sqlly.app。
- 如果你無法編輯 HTML,請傳遞
?proxy=<url>&token=<token>在頁面 URL 上。注入會比較好,因為權杖不會留在歷史記錄和記錄檔中。 - 在結尾如下的 URL 提供頁面
/(此處/sqlly/),這樣套件的相對./boot.js就會解析到你自己的副本web/.
5. 提供網頁套件
提供下列目錄中的檔案 web/ 在與啟動頁相同的路徑下(/sqlly/boot.js, /sqlly/sqlly_browser_bg.wasm,…),包括:
Cross-Origin-Opener-Policy: same-origin和Cross-Origin-Embedder-Policy: require-corp要加在頁面和每個套件檔案中。SQLly 需要SharedArrayBuffer,而瀏覽器只會在隔離的頁面上才啟用它。application/wasm作為型別,用於.wasm。壓縮在這裡幫助很大:用 Brotli 或 gzip 一壓,wasm 檔案能縮小好幾倍。- 如果你的頁面傳送 Content-Security-Policy:
'wasm-unsafe-eval'在script-src,橋接器的wss://來源在connect-src, and a nonce or hash on the inline globals script (or the query-parameter form above). Large results are kept in browser storage byspill-worker.js, a worker script, which nonces don't cover: allow it with'self'在worker-src(or inscript-src,該worker-srcfalls back to). If it is blocked, large results stay in memory. - 跨來源隔離適用於頁面載入的所有內容,因此請從你自己的來源提供套件,而不是使用沒有 CORP 標頭的第三方 CDN。
套件組合中的檔案版本與套件本身一致。升級時,請替換 web/ 以及橋接器一併設定。
6. 處理席次
409 seat_limit在 mint 上表示每個席位都已被使用。明確告訴使用者,並為管理員提供釋放其中一個的選項。GET /manage/seats會列出誰佔用了席次,以及從什麼時候開始。- 登出時釋放:
DELETE /manage/seats/{user}會撤銷使用者的權杖並關閉其 SQLly 分頁。當你移除某人的存取權時,也請照做。否則對方的權杖會持續有效,直到到期為止。 - 超過
sessionsPerSeat會被橋接本身拒絕:socket 收到「<user> 已經開啟了最大數量的 SQLly 工作階段」的訊息並以代碼 4429 關閉,SQLly 會顯示這句話。
7. 顯示授權健康狀態
GET /manage/status 擁有管理小工具或健康檢查所需的一切:
const s = await bridge('GET', '/manage/status');
// s.license.state: ok | grace | stale | not_admitted | expired | revoked | domain_mismatch | unlicensed
// s.license.message: the sentence your users see when something is wrong
// s.license.daysRemaining, s.license.planName, s.seatsUsed / s.license.seats
const healthy = ['ok', 'grace'].includes(s.license.state);
發出警示,除非狀態為 ok,並把 grace 為「本週續約」。 POST /manage/license/checkin 會強制簽入(或重新讀取離線檔案),適合 立即簽到 按鈕,在修好網路存取之後。 每個狀態代表什麼.
8. 從你的管理介面連結至授權(可選)
你可以用金鑰或授權檔設定橋接器,跳過這個步驟。綁定是給為多個客戶安裝 SQLly Embedded 的產品用的:每位客戶的管理員會把自己安裝的執行個體連到 他們自己的 sqlly.app 授權只要幾下點擊就能啟用,而且金鑰永遠不會被複製。啟動橋接器時,兩個旗標都不要加 --license-key 也不 --license-file,然後:
POST https://sqlly.app/api/embedded/links使用顯示名稱(例如"SQLly Embedded on " + hostname。保留傳回的secret儲存在伺服器端。向管理員顯示code,並傳送到linkUrl.- 管理員登入 sqlly.app,確認配對碼相符,選擇授權並核准。
- 在此期間,持續輪詢
POST https://sqlly.app/api/embedded/links/token與{ linkId, secret }每個pollIntervalSeconds。它會回應202當待處理時,然後200一次,用licenseKey.410表示重新開始(被拒、已過期或已使用)。 - 把金鑰直接交給橋接器:
PUT /manage/license { "licenseKey": "…" }。橋接程式會先用 sqlly.app 驗證它,儲存起來,並跨重新啟動保留,狀態頁會顯示license.source: "linked"。不要自己儲存金鑰。 - 要中斷連線,
DELETE /manage/license:橋接器會釋放它的席次、撤銷 sqlly.app 上的金鑰,並回到未授權狀態。
範例應用程式的 lib/sqllyapp.js 及其 /admin/link 路由正是實現了這一點。
在發布之前
- 管理權杖存放在伺服器端設定中,而管理 API 只繫結到 loopback 或私人網路。
- 每次啟動都是在伺服器端為已驗證的使用者簽發,使用你的授權規則所選擇的設定檔。
- SQLly 頁面和套件攜帶隔離標頭,而你的 CSP 允許橋接器的
wss://來源。 - 登出與存取移除會釋放使用者的席位。
seat_limit和license_not_ok顯示給人看的訊息,而不是堆疊追蹤。- 有東西在監看
GET /manage/status. - 你已經讀過 正式上線.