走向生产环境

TLS、反向代理、授权域名、服务管理器、备份、Content-Security-Policy 和隔离响应头,以及 SQLly Embedded 的生产检查清单。

在 localhost 上,默认配置开箱即用。而在生产环境中,要把桥接放在 TLS 后面、把许可证绑定到你的域名、保持管理 API 不对外,并把所有东西作为服务运行。本页提供了所需的设置、配置和检查清单。

推荐布局

  • 一个主机或私有网络 供你的应用和桥接使用。管理 API(127.0.0.1:8445)应该只有你的应用能够访问。
  • 反向代理 (nginx、Caddy、IIS、云负载均衡器) 终结 TLS,并在类似这样的路径上转发 WebSocket 升级,例如 /sqlly/proxy 到桥的 --bind 侦听器。
  • 同一个代理为你的应用提供服务,包括 SQLly 页面和 web/ 包,因此所有内容都在你获授权的域名下保持同源。
  • 桥接器需要 到 sqlly.app 的出站 HTTPS (仅限已连接的许可证),以及访问你数据库的网络权限。浏览器永远碰不到你的数据库或引擎。

反向代理

nginx
location /sqlly/proxy {
    proxy_pass http://127.0.0.1:8444/proxy;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header Origin $http_origin;      # the bridge checks it against your licensed domain
    proxy_read_timeout 1h;                     # long-running queries and idle editors
    proxy_send_timeout 1h;
}
侍童
portal.example.com {
    handle /sqlly/proxy {
        rewrite * /proxy
        reverse_proxy 127.0.0.1:8444
    }
    reverse_proxy 127.0.0.1:3000   # your app
}

然后启动桥接,使用 --public-url wss://portal.example.com/sqlly/proxy 所以每个启动令牌都会告诉 SQLly 要连接到哪里。要跳过代理,请提供桥接 --tls-cert 和 --tls-key 并且它起作用 wss:// 本身。

将其作为服务运行

systemd: /etc/systemd/system/sqlly-embedded.service
[Unit]
Description=SQLly Embedded bridge
After=network-online.target
Wants=network-online.target

[Service]
User=sqlly
EnvironmentFile=/etc/sqlly-embedded.env
ExecStart=/opt/sqlly-embedded/bin/sqlly-bridge embedded
Restart=on-failure
RestartSec=10
# systemd's default SIGTERM is a clean shutdown: the bridge releases its
# instance slot on sqlly.app at once.
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target
/etc/sqlly-embedded.env(chmod 600)
SQLLY_EMBEDDED_LICENSE_KEY=sqe_…
SQLLY_EMBEDDED_MANAGE_TOKEN=…
SQLLY_EMBEDDED_DOMAIN=portal.example.com
SQLLY_EMBEDDED_PUBLIC_URL=wss://portal.example.com/sqlly/proxy
SQLLY_EMBEDDED_BIND=127.0.0.1:8444
SQLLY_EMBEDDED_MANAGE_BIND=127.0.0.1:8445
SQLLY_EMBEDDED_STATE_DIR=/var/lib/sqlly-embedded
SQLLY_EMBEDDED_ALLOW_LOCALHOST_ORIGINS=false

在 macOS 上使用具有相同环境的 launchd plist。在 Windows 上运行 sqlly-bridge.exe embedded 在服务包装器或任务计划程序下运行。在容器中,将状态目录挂载为卷。如果启动时无法验证其许可证,桥接程序会输出一条明确的错误信息并退出,因此重启策略会不断重试,直到 sqlly.app 可访问。

使用普通的停止信号来停止它。 桥接器收到 SIGTERM 时会干净地退出(systemd、launchd 和 docker stop 发送)、SIGINT(Ctrl-C)、SIGHUP(终端窗口关闭、ssh 会话断开)、或者 Windows 上控制台窗口关闭:它会立即关闭会话并释放 sqlly.app 上的实例槽,如果 sqlly.app 没有响应会重试几秒钟。一个硬终止(SIGKILL、崩溃、断电)会保持槽位直到 40 分钟后过期,在此之前不会允许新的桥接。此更改之前的桥接仅在收到 SIGINT 时释放槽位;如果你运行一个,请添加 KillSignal=SIGINT 用于该装置或用途 STOPSIGNAL SIGINT 在 Docker 中。

每个桥接设置

每个标志都有一个环境变量,因此服务单元或 .env 文件就能容纳整个配置。

标志环境默认含义
--license-keySQLLY_EMBEDDED_LICENSE_KEY无你的 Embedded 页面上的联网许可证密钥。
--license-fileSQLLY_EMBEDDED_LICENSE_FILE无离线许可证文件。绝不联系 sqlly.app。key 和 file 最多只提供一个;两者都不提供时,使用已关联的密钥,否则桥接以未授权状态启动。
--domainSQLLY_EMBEDDED_DOMAIN无首次签入时绑定尚未绑定的许可证;如果许可证已绑定到其他地方,则拒绝启动。
--bindSQLLY_EMBEDDED_BIND0.0.0.0:8444浏览器 WebSocket 监听器(路径 /proxy)。在反向代理后面使用回环地址。
--public-urlSQLLY_EMBEDDED_PUBLIC_URLws://localhost:<port>/proxy浏览器使用的 URL,随每个启动令牌一起返回。
--manage-bindSQLLY_EMBEDDED_MANAGE_BIND127.0.0.1:8445管理 API 监听器。请保持私密:它保存着凭据。
--manage-tokenSQLLY_EMBEDDED_MANAGE_TOKEN必填管理 API 的 Bearer 令牌,至少 16 个字符。
--tls-cert, --tls-keySQLLY_EMBEDDED_TLS_CERT, SQLLY_EMBEDDED_TLS_KEY无服务 wss:// 服务。两个都给,或者都不给。
--state-dirSQLLY_EMBEDDED_STATE_DIR./sqlly-embedded-state配置文件、缓存的授权、关联密钥、每会话凭证文件。创建时仅限所有者访问。
--engine-binarySQLLY_CLI_BIN在桥接旁边,然后 PATH这 sqlly-cli 桥接程序按会话运行。
--max-sessionsSQLLY_EMBEDDED_MAX_SESSIONS64此主机上并发引擎的硬上限。
--allow-localhost-originsSQLLY_EMBEDDED_ALLOW_LOCALHOST_ORIGINStrue在授权域名之外也接受 localhost 来源。设置 false 在生产环境中。
--token-ttl-secondsSQLLY_EMBEDDED_TOKEN_TTL_SECONDS600默认启动令牌有效期。
--store-urlSQLLY_STORE_URLhttps://sqlly.app签到的数据存放在这里。开发以外请不要动它。
--allow-file-enginesSQLLY_EMBEDDED_ALLOW_FILE_ENGINESfalse接受使用基于文件的引擎(SQLite、DuckDB)的配置文件。关闭时会被拒绝,并提示 400 invalid_profile。请参见 基于文件的引擎.
--query-logSQLLY_EMBEDDED_QUERY_LOGtrue保留查询审计记录(GET /manage/queries, <state-dir>/queries.jsonl). false 时不记录任何内容。参见 查询审核记录.
--query-log-max-entriesSQLLY_EMBEDDED_QUERY_LOG_MAX_ENTRIES20000最新完成的查询会保留在内存和磁盘中(最少 100 条)。

状态目录和主机

状态目录存放每个配置文件及其密码、缓存的许可证授权、已关联安装的密钥、交给引擎的每会话凭证文件,以及查询审计记录。在 Linux 和 macOS 上,桥接程序会以仅所有者可访问的方式创建它(0700,文件 0600).

在 Windows 上,桥接程序无法收紧权限。 状态目录会继承其父文件夹的 ACL,桥接程序启动时会记录一条警告加以说明。请把它放在只有服务账户能读取的文件夹下,例如放在 %ProgramData% 下的专用目录中,移除继承并设置 ACL,仅授予服务账户权限,绝不要放在共享、同步或用户可浏览的路径下。

基于文件的引擎

基于文件的引擎默认关闭。 连接配置里的 SQLite 或 DuckDB 连接指向桥接主机上的一个文件。这些用户随后就能读取该文件、创建新文件,并能通过引擎自带的文件函数访问该服务账户可读的其他文件。因此,桥接会拒绝任何涉及基于文件的引擎的连接配置、连接测试和启动令牌,只要其中带有 400 invalid_profile 以及一个 problems[] 条目说明原因,除非运行时带上了 --allow-file-engines true。只为专用的、严格收紧的服务账号,以及你打算让用户访问的目录启用它。代理模式下,引擎还会额外禁止 DuckDB 扩展下载和外部访问(文件扫描、 COPY, ATTACH)为它打开的每个 DuckDB 实例。

查询审核记录

桥接器会记录其会话运行过的每一条查询和每一次行编辑:启动令牌对应的用户和配置文件、连接(名称、服务器、引擎、数据库)、SQL 文本、开始时间、结束方式以及耗时。因许可问题被拒绝的请求会连同许可消息记录为失败;会话关闭时仍在运行的内容则记录为已取消。你的应用通过 GET /manage/queries,按最新在前排序,可按用户、配置文件、状态或时间筛选。

最新的 --query-log-max-entries 条存放在内存和 <state-dir>/queries.jsonl (每行一个 JSON 对象,仅所有者可写,自动压实),因此这些记录在重启后依然保留。 SQL 文本以明文形式存储在桥接主机上。 让状态目录像它已保存的配置文件一样保持私密,并设置 --query-log false 如果你的安全政策完全不允许保留查询文本。

引擎自身的日志

每个 sqlly-cli 引擎会将请求/响应关联日志写入其数据目录,包括每个请求的完整 SQL 文本: ~/.local/share/sqlly/sqlly-engine.log (或者 $XDG_DATA_HOME/sqlly/sqlly-engine.log)在 Linux 上, ~/Library/Application Support/SQLLY/sqlly-engine.log 在 macOS 上, %APPDATA%\SQLLY\sqlly-engine.log 在 Windows 上,创建时仅所有者可访问。在写入一行之前,密码、令牌和密钥引用会被清除;ID、服务器、用户名和 SQL 会被保留。设置 SQLLY_ENGINE_LOG=<path> 在桥接的环境中(其引擎也会继承它)将日志移动到你可控制的位置,或者 SQLLY_ENGINE_LOG=/dev/null (NUL 在 Windows 上) 即为不保留任何内容。只有当引擎正常退出时,日志才会修剪到只剩最后几行。

AI 提供商设置

引擎会从自身环境中读取 AI 提供商配置(SQLLY_LLM_PROVIDER, SQLLY_EMBEDDING_PROVIDER 以及相关的模型和密钥变量)。除非你想让最终用户的 IntelliSense 和 AI 功能消耗那个账户的额度,否则不要在桥接主机上设置它们。

安全标志

配置文件的 only_allow_select (在客户端、项目或环境标签上)以及一个连接的 safety.block_all_but_select 由引擎在桥接主机上强制执行:凡是针对该连接引擎而言并非纯 SELECT 的语句,以及每一次行编辑,都会在到达数据库之前被拒绝,并提示“此连接按策略只读”,无论浏览器那边怎么声称。其他安全开关(确认对话框、回滚包装、无限制 UPDATE/DELETE 保护)是 SQLly 客户端在用户浏览器里的行为,不是服务器端控制。数据库权限才是真正的控制手段:给代理登录的权限,只给其用户真正需要的那些。

大小调整

每个打开的 SQLly 标签页都会运行一个 sqlly-cli 引擎进程各自持有独立的数据库连接。内存占用跟随使用方式:结果集以流式处理、溢写到磁盘,而不是整个留在内存里,但大量导出和许多并发选项卡会累积起来。主机容量按峰值并发选项卡数(最多按席位数 × 每席位选项卡数)来配,并使用 --max-sessions 作为后备。引擎会按需启动,并在标签页关闭时退出。

操作

  • 备份状态目录。 它保存每个配置文件及其凭证,以及关联安装的密钥。请把备份当作机密对待。
  • 跟踪日志 用于 embedded license state: 每次许可证状态变更都会记录其状态名。可轮询 GET /manage/status 来自你的监控系统,并使用 GET /healthz (无需令牌)来检查存活。
  • 确保时钟准确。 授权必须在距桥接程序时钟 5 分钟内发出,所以请运行 NTP。
  • 一起升级。 替换 bin/ 和 web/ 必须来自同一个包版本。重启桥接会关闭已打开的标签页,用户重新加载即可重新连接。
  • 轮换管理令牌 重启桥接和你的应用,让新值生效即可。已经签发的启动令牌在过期前仍然有效。
  • 迁移域名? 在你的 Embedded 页面上更改它,然后重启桥接,换上新的 --domain。离线许可证需要换一个新文件,因为域就写在文件里。

生产检查清单

  • 在浏览器监听器前启用 TLS,并将 --public-url 设置为 wss:// 地址。
  • SQLLY_EMBEDDED_DOMAIN 已设置,且许可证已绑定到该域名; --allow-localhost-origins=false.
  • 管理 API 只在环回或私有网络上开放;令牌仅存于服务器端的机密管理中。
  • 启动令牌通过 SQLLY_PROXY_URL / SQLLY_PROXY_TOKEN 以 globals 传递,绝不放进页面 URL(?token= 会进入历史记录、引荐来源和 Web 服务器日志)。
  • --allow-file-engines 除非先为它设置好严格受控的服务账户和目录,否则不会写上这一项。
  • 状态目录仅服务账户可读(Linux/macOS 上为仅所有者;Windows 上为显式 ACL); --query-log 和 SQLLY_ENGINE_LOG 根据你保留查询文本的策略进行设置。
  • 否 SQLLY_LLM_PROVIDER / SQLLY_EMBEDDING_PROVIDER 在桥接环境中,除非最终用户应控制该支出。
  • 桥接和应用作为服务在非特权用户下运行,失败时重启,支持优雅停止。
  • 状态目录放在持久存储上,仅所有者可访问,并有备份。
  • SQLly 页面和 web/ 以 COOP/COEP 响应头提供服务, application/wasm,以及一个允许桥接器来源的 CSP。
  • 允许出站 HTTPS 连接到 sqlly.app(连接的许可证),启用 NTP。
  • 监控 /manage/status: 提醒条件是 license.state 不是 ok.
  • 示例应用的默认管理员密码已更改,前提是你真的会部署示例应用。在你改掉它之前,它拒绝绑定到环回地址以外的地址。