正式上線
TLS、反向代理、授權網域、服務管理工具、備份、內容安全政策與隔離標頭,以及 SQLly Embedded 的正式環境檢查清單。
在 localhost 上,預設值直接就能用。正式環境請把橋接器放在 TLS 後面、將你的授權綁到你的網域、不對外公開管理 API,並把一切都以服務方式執行。本頁備有為此所需的設定、組態與檢查清單。
建議的版面配置
- 單一主機或私有網路 供你的應用程式與橋接器使用。管理 API(
127.0.0.1:8445)應該只能由你的應用程式存取。 - 反向代理 (nginx、Caddy、IIS、雲端負載平衡器)會終止 TLS,並在例如下列的路徑轉送 WebSocket 升級
/sqlly/proxy到橋接器的--bind監聽器。 - 同一個代理伺服器也會為你的應用程式提供服務,包括 SQLly 頁面和
web/bundle,所以在你授權的網域下,所有內容都是同源的。 - 橋接器需要 連往 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 send)、SIGINT(Ctrl-C)、SIGHUP(終端機視窗關閉、ssh 工作階段中斷),或 Windows 主控台視窗關閉:它會立即關閉工作階段,並釋放它在 sqlly.app 上的執行個體名額;若 sqlly.app 沒有回應,會重試幾秒。強制終止(SIGKILL、當機、斷電)會讓名額一直被佔用,40 分鐘後才會逾時失效,在那之前替代的橋接器不會被接受。此變更之前的橋接器只會在 SIGINT 時釋放名額;如果你還在跑其中一個,請加上 KillSignal=SIGINT 加進 unit 檔,或使用 STOPSIGNAL SIGINT 在 Docker 中。
每個橋接設定
每個旗標都有一個環境變數,因此服務單元或 .env 檔案就能裝下整份設定。
| 旗標 | 環境 | 預設 | 意義 |
|---|---|---|---|
--license-key | SQLLY_EMBEDDED_LICENSE_KEY | 無 | 來自你 Embedded 頁面的連線版授權金鑰。 |
--license-file | SQLLY_EMBEDDED_LICENSE_FILE | 無 | 離線授權檔案。完全不會連上 sqlly.app。金鑰與檔案最多只提供其中一個;兩者皆無時,會使用已連結的金鑰,否則橋接器會以未授權狀態啟動。 |
--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。請只為專用且嚴格限縮權限的服務帳戶,以及你打算讓使用者存取的目錄啟用。在 Proxy 模式下,引擎還會禁止下載 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-only 的陳述式,以及每一次資料列編輯,都會在抵達資料庫之前以「此連線依政策為唯讀」拒絕,無論瀏覽器怎麼宣稱。其他安全旗標(確認對話方塊、回滾包裝、無界限 UPDATE/DELETE 保護)是 SQLly 用戶端在使用者瀏覽器裡的行為,不是伺服器端控制。資料庫權限才是真正的控制:給代理登入帳戶的權限,只該有它的使用者該做的部分。
容量規劃
每個開啟的 SQLly 分頁都會執行一個 sqlly-cli 引擎處理程序,各自持有自己的資料庫連線。記憶體用量跟著使用行為走:結果集會串流並溢寫到磁碟而非整份保留,但大型匯出和大量同時開啟的分頁會累積。請按同時分頁數的高峰(最多為席位數 × 每席位分頁數)來規劃主機規格,並使用 --max-sessions 作為最後的保險。引擎會視需要啟動,分頁關閉時就結束。
維運
- 備份狀態目錄。 它保存每個設定檔及其憑證,還有已連結安裝的金鑰。請將備份視為機密。
- 監控記錄 針對
embedded license state:每次授權狀態變更都會記錄其狀態名稱。請輪詢GET /manage/status從你的監控系統取得,並使用GET /healthz(無 token)來檢查存活狀態。 - 讓時鐘保持準確。 授權憑證必須在橋接器時鐘的 5 分鐘內簽發,因此請執行 NTP。
- 一起升級。 取代
bin/和web/來自同一個套件版本。重新啟動橋接器會關閉已開啟的分頁,使用者重新載入即可回連。 - 輪替管理權杖 需重新以新值啟動橋接器與你的應用程式才會生效。已核發的啟動權杖在到期前仍持續有效。
- 要更換網域? 請在你的 Embedded 頁面上變更,然後以新值重新啟動橋接器
--domain。離線授權需要一份新的檔案,因為網域就寫在檔案裡。
正式環境檢查清單
- 在瀏覽器監聽器前使用 TLS,並且
--public-url設定為wss://位址。 SQLLY_EMBEDDED_DOMAIN設定後,授權綁定到它;--allow-localhost-origins=false.- 管理 API 僅限回送或私人網路使用;權杖只存放在伺服器端的機密設定中。
- 啟動權杖會透過
SQLLY_PROXY_URL/SQLLY_PROXY_TOKEN這類全域變數傳遞,絕不放在頁面 URL 中(?token=會留在歷史記錄、referrer 與網頁伺服器日誌裡)。 --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. - 如果你打算部署範例應用程式,請更改它的預設系統管理員密碼。在你更改之前,它會拒絕繫結到回圈位址以外的任何介面。