构建自己的应用

分步指南:用你自己的 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 构建文档)你的管理界面、配置文件或从租户数据构建文档的代码
打开 SQLlyGET /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 模块标签:

javascript(express 风格)
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' in 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 by spill-worker.js, a worker script, which nonces don't cover: allow it with 'self' in worker-src (or in script-src,这 worker-src falls 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,然后:

  1. POST https://sqlly.app/api/embedded/links 使用显示名称(例如 "SQLly Embedded on " + hostname)。将返回的 secret 保存在服务器端。向管理员显示 code 并把它们发送到 linkUrl.
  2. 管理员登录 sqlly.app,核对代码是否一致,选择许可证并批准。
  3. 与此同时,轮询 POST https://sqlly.app/api/embedded/links/token 与 { linkId, secret } 每个 pollIntervalSeconds轮询一次。它会返回 202 挂起时,然后 200 一次,用 licenseKey. 410 表示重新开始(被拒绝、已过期或已使用)。
  4. 把密钥直接交给桥接程序: PUT /manage/license { "licenseKey": "…" }。桥接器在存储前会先向 sqlly.app 验证,跨重启保留,状态页上会显示 license.source: "linked"。不要自己存储密钥。
  5. 要断开连接, DELETE /manage/license: 该桥接器释放其槽位,撤销 sqlly.app 上的密钥,回到未许可状态。

示例应用程序的 lib/sqllyapp.js 及其 /admin/link 路由正是实现了这一点。

在发布之前

  • 管理令牌存在于服务器端配置中,管理 API 绑定到环回接口或私有网络。
  • 每次启动都是在服务器端为通过身份验证的用户签发的,配置文件由你的授权规则选定。
  • SQLly 页面和应用包都带有隔离头,你的 CSP 允许桥接器的 wss:// 来源。
  • 注销和访问移除会释放用户的席位。
  • seat_limit 和 license_not_ok 显示一条人类可读的消息,而不是堆栈跟踪。
  • 有东西在监视 GET /manage/status.
  • 你已经读过 走向生产环境.