工作原理
工作原理:桥接程序、每会话引擎、启动令牌、签名的许可证授权、签到校验、席位、Origin 规则,以及凭证的存放位置。
SQLly Embedded 把 SQLly 拆成需要凭据的一半和不需要凭据的一半。SQLly 的界面以 WebAssembly 形式在用户的浏览器中运行。所有接触数据库的部分都在你的服务器上运行,位于 SQLly 桥及其启动的引擎之内。你的 Web 应用与桥并列,告诉它谁可以用哪些连接打开 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、安全规则),以及为它们着色、分组的 client、project 和 environment 标签。你的应用存放 profile 用的是 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 被拒)、令牌、许可证、用户已打开的会话,以及它自身的会话上限。浏览器无法得知升级被拒的原因,因此源检查之后的每一次拒绝都会通过已打开的套接字以error一条带有原因的消息,随后是关闭代码4000 + HTTP status(4401 令牌未知或已过期,4503 许可证状态异常,4429 达到会话上限);SQLly 会显示这句话。 - 桥接器将配置文件的凭据写入每个会话专用的私有文件,然后启动
sqlly-cli以引擎模式启动它。 - 浏览器会收到一条 hello 消息,其中包含不含机密信息的连接目录以及当前许可状态。使用带启动上下文签发的令牌的第一个会话还会收到要打开的标签页;SQLly 加载它们,但不执行任何操作。
- 从这里开始,SQLly 的请求(连接、运行、取消、为 IntelliSense 获取元数据、分页获取结果)都以二进制帧传输。桥接会把它们转发给引擎,并把每个查询和每处行编辑都记录到它的 审计追踪,并且如果许可证停止有效,会以消息拒绝它们。
席位和会话
A 席位 是一个拥有打开着的会话或未过期启动令牌的独立用户 ID。席位按并发计,不按人名计:用户的最后一个标签页关闭、最后一个令牌过期后,席位立即释放,别人就能用。桥接会把许可证下所有桥接的席位合起来统计,因为 sqlly.app 每次签到时都会报告其他实例上的用户。
- 为这样的用户签发令牌:该用户 已经 已持有席位的用户总是成功;而在席位全被占满时为新用户分配席位会失败,错误为
409 seat_limit,这样你的应用程序可以显示清晰的消息。 - 每个席位可容纳
sessionsPerSeat打开的标签页:付费计划 4 个,试用 1 个。多出的标签页会收到提示并被关闭(代码 4429)。桥接会 ping 每个标签页,静默 90 秒的会被断开,因此因笔记本休眠而失联的标签页会自行释放其会话;用户的最后一个标签页关闭后,其启动令牌会在两分钟内过期。 DELETE /manage/seats/{user}撤销用户的令牌并关闭他们的会话。当有人从你的应用登出或失去访问权限时调用它。- 用户 ID 由你自己指定。如果不想发送电子邮件地址,可以使用稳定、不透明的 ID(数据库键或哈希):持有席位的 ID 会上报给 sqlly.app,以便跨桥接统计席位数。
谁可以连接:Origin 规则
每个许可证绑定一个域名。桥接接受浏览器 WebSocket 的前提是其 Origin 请求头是该域名或其任意子域(不限深度、协议或端口),或者 localhost / 127.0.0.1 / [::1] 当 --allow-localhost-origins 处于开启状态(这是默认值,方便开发)。没有绑定域的许可证只放行 localhost。要绑定域,请前往 你的 Embedded 页面,或者先带着 --domain.
管理 API 完全不发送 CORS 头。它是服务器对服务器的调用:其他源的浏览器无法调用它,何况它本来也该绑定到环回地址。
许可证的执行方式
桥接器只信任一样东西: 许可证授权,一种由 sqlly.app 用 ES384(ECDSA P-384)签名的紧凑 JWS。验证密钥编译在桥接器里。每一项许可额度(席位数、每席位会话数、桥接器实例数、域名、期限截止日、宽限天数、功能)都从授权文件的签名声明中读取。包在外面的未签名 JSON 只用于显示。
联网许可证
- 启动时以及每 20 分钟,网桥都会发送
POST /api/embedded/checkin其许可密钥、实例 ID、新的 32 字节随机数、版本和主机名、启动时的域以及当前持有座位的用户 ID。 - 回复中的授权必须能用编译时内置的密钥通过验证,回显那个一次性随机数,注明此实例和同一许可证,并且签发时间距网桥时钟不超过 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 · 打开的会话数量 | 查询 · 结果 · 数据库名称和主机 · 凭证 · 配置文件 · 用户输入的任何内容 |
离线许可证什么都不发送。浏览器只与你的应用和你的桥通信。