走向生产环境
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 (仅限已连接的许可证),以及访问你数据库的网络权限。浏览器永远碰不到你的数据库或引擎。
反向代理
nginxlocation /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-key | SQLLY_EMBEDDED_LICENSE_KEY | 无 | 你的 Embedded 页面上的联网许可证密钥。 |
--license-file | SQLLY_EMBEDDED_LICENSE_FILE | 无 | 离线许可证文件。绝不联系 sqlly.app。key 和 file 最多只提供一个;两者都不提供时,使用已关联的密钥,否则桥接以未授权状态启动。 |
--domain | SQLLY_EMBEDDED_DOMAIN | 无 | 首次签入时绑定尚未绑定的许可证;如果许可证已绑定到其他地方,则拒绝启动。 |
--bind | SQLLY_EMBEDDED_BIND | 0.0.0.0:8444 | 浏览器 WebSocket 监听器(路径 /proxy)。在反向代理后面使用回环地址。 |
--public-url | SQLLY_EMBEDDED_PUBLIC_URL | ws://localhost:<port>/proxy | 浏览器使用的 URL,随每个启动令牌一起返回。 |
--manage-bind | SQLLY_EMBEDDED_MANAGE_BIND | 127.0.0.1:8445 | 管理 API 监听器。请保持私密:它保存着凭据。 |
--manage-token | SQLLY_EMBEDDED_MANAGE_TOKEN | 必填 | 管理 API 的 Bearer 令牌,至少 16 个字符。 |
--tls-cert, --tls-key | SQLLY_EMBEDDED_TLS_CERT, SQLLY_EMBEDDED_TLS_KEY | 无 | 服务 wss:// 服务。两个都给,或者都不给。 |
--state-dir | SQLLY_EMBEDDED_STATE_DIR | ./sqlly-embedded-state | 配置文件、缓存的授权、关联密钥、每会话凭证文件。创建时仅限所有者访问。 |
--engine-binary | SQLLY_CLI_BIN | 在桥接旁边,然后 PATH | 这 sqlly-cli 桥接程序按会话运行。 |
--max-sessions | SQLLY_EMBEDDED_MAX_SESSIONS | 64 | 此主机上并发引擎的硬上限。 |
--allow-localhost-origins | SQLLY_EMBEDDED_ALLOW_LOCALHOST_ORIGINS | true | 在授权域名之外也接受 localhost 来源。设置 false 在生产环境中。 |
--token-ttl-seconds | SQLLY_EMBEDDED_TOKEN_TTL_SECONDS | 600 | 默认启动令牌有效期。 |
--store-url | SQLLY_STORE_URL | https://sqlly.app | 签到的数据存放在这里。开发以外请不要动它。 |
--allow-file-engines | SQLLY_EMBEDDED_ALLOW_FILE_ENGINES | false | 接受使用基于文件的引擎(SQLite、DuckDB)的配置文件。关闭时会被拒绝,并提示 400 invalid_profile。请参见 基于文件的引擎. |
--query-log | SQLLY_EMBEDDED_QUERY_LOG | true | 保留查询审计记录(GET /manage/queries, <state-dir>/queries.jsonl). false 时不记录任何内容。参见 查询审核记录. |
--query-log-max-entries | SQLLY_EMBEDDED_QUERY_LOG_MAX_ENTRIES | 20000 | 最新完成的查询会保留在内存和磁盘中(最少 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. - 示例应用的默认管理员密码已更改,前提是你真的会部署示例应用。在你改掉它之前,它拒绝绑定到环回地址以外的地址。