构建自己的应用
分步指南:用你自己的 Web 应用驱动 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) |
| 托管 Web 包 | /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。浏览器访问代理监听器(: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 最小 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();
- 在服务器端按请求签发。 切勿把 manage 令牌放进页面。launch 令牌可以放心交给签发给它的用户:它只会为该用户以该配置文件打开 SQLly,并且会过期(默认 10 分钟;传入
ttlSeconds在 10 到 86,400 之间)。 - 重复使用没问题。 令牌在过期前一直有效,因此页面重新加载不需要新令牌。示例应用会缓存每个用户的令牌,并在过期前一分钟重新生成。为同一用户重新生成令牌绝不会额外占用席位。
- 打开查询,而不仅仅是工作台。 添加
open传给 mint 调用,让用户直接进入一个查询标签页,其中的脚本、连接、参数值和光标都已设置好。每次这类启动都要铸造一个新令牌:标签页只为该令牌启动的第一个会话打开。 打开 SQLly 并定位到查询. - 用户 ID 由你决定。 传递一个稳定的、不透明的 ID。席位统计不同的 ID,并且持有席位的 ID 会在签到时报告给 sqlly.app。
- 如果你无法编辑 HTML,请传递
?proxy=<url>&token=<token>改放在页面 URL 上。注入的方式更好,因为令牌不会留在历史记录和日志里。 - 通过以该后缀结尾的 URL 提供页面
/(这里/sqlly/),这样捆绑包的相对./boot.js会解析到你自己那份web/.
5. 托管 Web 构建包
提供以下目录中的文件 web/ 的文件,路径与启动页面相同(/sqlly/boot.js, /sqlly/sqlly_browser_bg.wasm,…),如下:
Cross-Origin-Opener-Policy: same-origin和Cross-Origin-Embedder-Policy: require-corp在页面和每个 bundle 文件上都要有。SQLly 需要SharedArrayBuffer,而浏览器只在隔离页面上启用此功能。application/wasm作为.wasm。压缩在这里帮助很大:用 Brotli 或 gzip 一压,wasm 文件能小好几倍。- 如果你的页面发送内容安全策略 (Content-Security-Policy):
'wasm-unsafe-eval'inscript-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'inworker-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会被桥接服务本身拒绝:套接字会收到“<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 绑定到环回接口或私有网络。
- 每次启动都是在服务器端为通过身份验证的用户签发的,配置文件由你的授权规则选定。
- SQLly 页面和应用包都带有隔离头,你的 CSP 允许桥接器的
wss://来源。 - 注销和访问移除会释放用户的席位。
seat_limit和license_not_ok显示一条人类可读的消息,而不是堆栈跟踪。- 有东西在监视
GET /manage/status. - 你已经读过 走向生产环境.