本番運用へ
TLS、リバースプロキシ、ライセンス対象ドメイン、サービスマネージャー、バックアップ、Content-Security-Policy と分離ヘッダー、そして SQLly Embedded 向けの本番環境チェックリスト。
localhost ならデフォルトのままで動きます。本番環境では、ブリッジを TLS の背後に置き、ライセンスをドメインに紐づけ、管理 API を非公開に保ち、すべてをサービスとして実行します。このページには、そのための設定、構成ファイル、チェックリストがあります。
推奨レイアウト
- 1 つのホストまたはプライベートネットワーク アプリとブリッジ用。管理 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;
}
Caddy
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 には一切接続しません。キーとファイルはどちらか一方だけを指定できます。どちらも指定しない場合はリンクされたキーが使われ、それもなければブリッジはライセンスなしで起動します。 |
--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 用のベアラートークン。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 を付けた場所に置き、共有・同期・ユーザーが閲覧できるパスの下には決して置かないこと。
ファイルベースのエンジン
ファイルベースのエンジンは既定でオフです。 そのためブリッジは、ファイルベースのエンジンが関わるプロファイル、接続テスト、起動トークンを拒否します。応答コードは 400 invalid_profile と、1つの problems[] 理由を説明するエントリ。ただし次を付けて実行する場合は除きます --allow-file-engines true。専用でロックダウンしたサービスアカウントと、ユーザーに公開してよいディレクトリに対してのみ有効にしてください。プロキシモードでは、エンジンはさらに DuckDB 拡張機能のダウンロードと外部アクセス(ファイルスキャン、 COPY, ATTACH)を、開くすべての DuckDB インスタンスに対して設定します。
クエリ監査証跡
ブリッジは、セッションが実行したすべてのクエリと行の編集を記録します。記録するのは、起動トークンのユーザーとプロファイル、接続(名前、サーバー、エンジン、データベース)、SQL テキスト、開始時刻、終了の仕方、所要時間です。ライセンスの問題で拒否されたリクエストは、ライセンスのメッセージ付きの失敗として記録され、セッションが閉じられたときに実行中だったものはキャンセルとして記録されます。アプリは次の方法でそれを読み取ります: GET /manage/queries、新しい順で、ユーザー、プロファイル、ステータス、時間で絞り込めます。
最新の --query-log-max-entries エントリはメモリ内と <state-dir>/queries.jsonl (1 行に 1 つの 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 タブは 1 つの sqlly-cli 独自のデータベース接続を持つエンジンプロセス。メモリの使い方は操作次第です:結果セットは丸ごと保持せずストリーミングしてディスクにスピルしますが、大きなエクスポートや多数の同時タブは積み重なります。ホストは同時タブ数のピーク(多くても同時利用者数×1人あたりのタブ数)に合わせてサイズを決め、次を使用します --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グローバルスコープのみで、ページ URL には決して含めません (?token=履歴、リファラー、ウェブサーバーのログに残ります)。 --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。 - sqlly.app への送信 HTTPS を許可(接続型ライセンス)、NTP はオン。
- 監視は
/manage/status: 次の場合にアラートlicense.stateではありませんok. - サンプルアプリを展開する場合は、サンプルアプリの既定の管理者パスワードを変更してください。変更するまで、ループバック以外へのバインドは拒否されます。