In Produktion gehen

TLS, Reverse-Proxys, die lizenzierte Domain, Service-Manager, Backups, Content-Security-Policy und Isolations-Header sowie eine Produktions-Checkliste für SQLly Embedded.

Auf localhost funktionieren die Standardwerte einfach. In der Produktion gehört die Bridge hinter TLS, die Lizenz wird an deine Domain gebunden, die Management-API bleibt privat, und alles läuft als Dienste. Diese Seite hat die Einstellungen, Konfigurationen und die Checkliste dafür.

Empfohlenes Layout

  • Ein Host oder privates Netzwerk für deine App und die Brücke. Die Management-API (127.0.0.1:8445) sollte nur von deiner App erreichbar sein.
  • Ein Reverse-Proxy (nginx, Caddy, IIS, ein Cloud-Load-Balancer) beendet TLS und leitet WebSocket-Upgrades auf einem Pfad wie /sqlly/proxy zur Brücke --bind Listener.
  • Derselbe Proxy liefert deine App aus, einschließlich der SQLly-Seite und web/ Bundle, sodass alles unter deiner lizenzierten Domain auf derselben Origin liegt.
  • Die Bridge benötigt ausgehendes HTTPS zu sqlly.app (nur verbundene Lizenzen) und Netzwerkzugriff auf deine Datenbanken. Browser erreichen deine Datenbanken oder die Engine nie.

Reverse-Proxy

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;
}
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
}

Dann starte die Bridge mit --public-url wss://portal.example.com/sqlly/proxy sodass jedes Start-Token SQLly sagt, wohin es sich verbinden soll. Um den Proxy zu überspringen, gib der Bridge --tls-cert und --tls-key und sie dient wss:// selbst.

Als Dienst ausführen

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

Nimm auf macOS eine launchd-Plist mit derselben Umgebung. Starte unter Windows sqlly-bridge.exe embedded unter einem Service-Wrapper oder dem Aufgabenplaner laufen. In Containern binde das Zustandsverzeichnis als Volume ein. Die Bridge beendet sich mit einer klaren Meldung, wenn sich ihre Lizenz beim Start nicht prüfen lässt, sodass eine Neustart-Richtlinie weiter versucht, bis sqlly.app erreichbar ist.

Stoppe es mit einem normalen Stoppsignal. Die Bridge fährt bei SIGTERM sauber herunter (was systemd, launchd und docker stop senden), SIGINT (Strg-C), SIGHUP (das Schließen des Terminalfensters, das Abbrechen einer SSH-Sitzung) oder das Schließen des Konsolenfensters unter Windows: sie schließt Sitzungen und gibt ihren Instanzplatz auf sqlly.app sofort frei und wiederholt das ein paar Sekunden lang, wenn sqlly.app nicht antwortet. Ein hartes Beenden (SIGKILL, ein Absturz, Stromausfall) hält den Platz belegt, bis er 40 Minuten später verfällt, und vorher wird keine Ersatzbrücke zugelassen. Brücken vor dieser Änderung gaben den Platz nur bei SIGINT frei; betreibst du eine davon, ergänze KillSignal=SIGINT zur Einheit hinzu oder verwende STOPSIGNAL SIGINT in Docker.

Jede Bridge-Einstellung

Jede Option hat eine Umgebungsvariable, sodass eine Service-Unit oder .env -Datei kann die gesamte Konfiguration enthalten.

FlagUmgebungStandardBedeutung
--license-keySQLLY_EMBEDDED_LICENSE_KEYkeinerVerbundener Lizenzschlüssel von deiner Embedded-Seite.
--license-fileSQLLY_EMBEDDED_LICENSE_FILEkeinerOffline-Lizenzdatei. Kontaktiert niemals sqlly.app. Gib höchstens eines von beiden an, Schlüssel oder Datei; ohne beide wird ein verknüpfter Schlüssel verwendet, andernfalls startet die Bridge ohne Lizenz.
--domainSQLLY_EMBEDDED_DOMAINkeinerBindet eine ungebundene Lizenz beim ersten Check-in; verweigert den Start, wenn die Lizenz anderweitig gebunden ist.
--bindSQLLY_EMBEDDED_BIND0.0.0.0:8444Browser-WebSocket-Listener (Pfad /proxy). Verwende Loopback hinter einem Reverse-Proxy.
--public-urlSQLLY_EMBEDDED_PUBLIC_URLws://localhost:<port>/proxyDie URL, die Browser verwenden, wird zusammen mit jedem Start-Token zurückgegeben.
--manage-bindSQLLY_EMBEDDED_MANAGE_BIND127.0.0.1:8445Management-API-Listener. Halte ihn privat: Er enthält Zugangsdaten.
--manage-tokenSQLLY_EMBEDDED_MANAGE_TOKENErforderlichBearer-Token für die Management-API, mindestens 16 Zeichen.
--tls-cert, --tls-keySQLLY_EMBEDDED_TLS_CERT, SQLLY_EMBEDDED_TLS_KEYkeinerBereitstellen wss:// direkt. Gib beides oder keines.
--state-dirSQLLY_EMBEDDED_STATE_DIR./sqlly-embedded-stateProfile, zwischengespeicherte Berechtigung, verknüpfter Schlüssel, sitzungsbezogene Anmeldedateien. Mit Zugriff nur für den Besitzer angelegt.
--engine-binarySQLLY_CLI_BINneben der Bridge, dann PATHdas sqlly-cli die Bridge läuft pro Sitzung.
--max-sessionsSQLLY_EMBEDDED_MAX_SESSIONS64Obergrenze für gleichzeitige Engines auf diesem Host.
--allow-localhost-originsSQLLY_EMBEDDED_ALLOW_LOCALHOST_ORIGINStrueAkzeptiert localhost-Ursprünge zusätzlich zur lizenzierten Domain. Setze false in Produktion.
--token-ttl-secondsSQLLY_EMBEDDED_TOKEN_TTL_SECONDS600Standard-Lebensdauer von Launch-Tokens.
--store-urlSQLLY_STORE_URLhttps://sqlly.appWohin die Check-ins gehen. Außerhalb der Entwicklung nicht anfassen.
--allow-file-enginesSQLLY_EMBEDDED_ALLOW_FILE_ENGINESfalseAkzeptiert Profile mit dateibasierten Engines (SQLite, DuckDB). Ist die Option aus, werden sie abgelehnt mit 400 invalid_profile. Siehe Dateibasierte Engines.
--query-logSQLLY_EMBEDDED_QUERY_LOGtrueAbfrage-Prüfprotokoll beibehalten (GET /manage/queries, <state-dir>/queries.jsonl). false zeichnet nichts auf. Siehe Abfrage-Auditprotokoll.
--query-log-max-entriesSQLLY_EMBEDDED_QUERY_LOG_MAX_ENTRIES20000Die neuesten abgeschlossenen Abfragen werden im Speicher und auf der Festplatte aufbewahrt (mindestens 100).

Das Zustandsverzeichnis und der Host

Das Zustandsverzeichnis enthält jedes Profil mit seinen Passwörtern, die zwischengespeicherte Lizenzerteilung, den Schlüssel einer verknüpften Installation, die pro Sitzung an Engines übergebenen Berechtigungsdateien und das Abfrage-Audit-Protokoll. Unter Linux und macOS erstellt die Bridge es nur für den Besitzer (0700, Dateien 0600).

Unter Windows kann die Bridge die Berechtigungen nicht verschärfen. Das Zustandsverzeichnis erbt die ACL seines übergeordneten Ordners, und die Bridge loggt beim Start eine Warnung dazu. Lege es unter einen Ordner, den nur das Dienstkonto lesen kann, zum Beispiel ein dediziertes Verzeichnis unter %ProgramData% mit entfernter Vererbung und einer ACL, die nur dem Servicekonto Zugriffsrechte gewährt, und niemals unter einem gemeinsamen, synchronisierten oder von Benutzern durchsuchbaren Pfad.

Dateibasierte Engines

Dateibasierte Engines sind standardmäßig deaktiviert. Eine SQLite- oder DuckDB-Verbindung in einem Profil benennt eine Datei auf dem Bridge-Host. Ihre Benutzer können diese Datei dann lesen, neue erstellen und über die dateibezogenen Funktionen der Engine auch andere Dateien erreichen, die das Dienstkonto lesen kann. Die Bridge lehnt deshalb Profile, Verbindungstests und Launch-Tokens ab, die eine dateibasierte Engine mit 400 invalid_profile und ein problems[] Eintrag, der den Grund erklärt, es sei denn, es läuft mit --allow-file-engines true. Aktiviere es nur für ein dediziertes, abgeschottetes Servicekonto und ein Verzeichnis, das die Nutzer erreichen sollen. Im Proxy-Modus verbietet die Engine zusätzlich DuckDB-Erweiterungs-Downloads und externen Zugriff (Datei-Scans, COPY, ATTACH) für jede DuckDB-Instanz, die es öffnet.

Abfrage-Auditprotokoll

Die Bridge protokolliert jede Abfrage und jede Zeilenbearbeitung, die ihre Sitzungen ausführen: Benutzer und Profil des Start-Tokens, die Verbindung (Name, Server, Engine, Datenbank), den SQL-Text, wann sie gestartet wurde, wie sie endete und wie lange sie dauerte. Wegen eines Lizenzproblems abgelehnte Anfragen werden mit der Lizenzmeldung als fehlgeschlagen protokolliert; was beim Schließen einer Sitzung noch lief, wird als abgebrochen protokolliert. Deine App liest das mit GET /manage/queries, neueste zuerst, gefiltert nach Benutzer, Profil, Status oder Zeit.

Die neuesten --query-log-max-entries Einträge leben im Speicher und in <state-dir>/queries.jsonl (ein JSON-Objekt pro Zeile, nur für den Besitzer geschrieben, automatisch komprimiert), sodass die Aufzeichnung Neustarts überlebt. Der SQL-Text wird auf dem Bridge-Host im Klartext gespeichert. Halte das Zustandsverzeichnis so privat wie die Profile, die es schon enthält, und setze --query-log false wenn deine Richtlinie das Speichern von Abfragetext überhaupt verbietet.

Das eigene Log der Engine

Jedes sqlly-cli Die Engine schreibt ein Anforderungs-/Antwort-Korrelationsprotokoll, einschließlich des vollständigen SQL-Texts jeder Anfrage, in ihr Datenverzeichnis: ~/.local/share/sqlly/sqlly-engine.log (oder $XDG_DATA_HOME/sqlly/sqlly-engine.log) unter Linux, ~/Library/Application Support/SQLLY/sqlly-engine.log auf macOS, %APPDATA%\SQLLY\sqlly-engine.log unter Windows, nur für den Besitzer erstellt. Passwörter, Token und geheime Referenzen werden gelöscht, bevor eine Zeile geschrieben wird; IDs, Server, Benutzernamen und SQL werden beibehalten. Setze SQLLY_ENGINE_LOG=<path> in der Umgebung der Bridge (ihre Engines erben sie), um das Protokoll an einen Ort zu verschieben, den du kontrollierst, oder SQLLY_ENGINE_LOG=/dev/null (NUL unter Windows), um nichts zu behalten. Das Protokoll wird nur auf die letzten Zeilen gekürzt, wenn eine Engine sauber beendet wird.

KI-Anbietereinstellungen

Die Engine übernimmt die Konfiguration des KI-Anbieters aus ihrer Umgebung (SQLLY_LLM_PROVIDER, SQLLY_EMBEDDING_PROVIDER und die zugehörigen Modell- und Schlüsselvariablen). Setze sie nicht auf dem Bridge-Host, es sei denn, du willst, dass IntelliSense und KI-Funktionen deiner Endbenutzer auf dieses Konto angerechnet werden.

Sicherheitsflags

Ein Profil only_allow_select (bei einem Client, Projekt oder Umgebungslabel) und eine Verbindung safety.block_all_but_select werden von der Engine auf dem Bridge-Host durchgesetzt: Eine Anweisung, die für die Engine der Verbindung nicht ausschließlich SELECT ist, und jede Zeilenbearbeitung werden mit „diese Verbindung ist richtlinienbedingt schreibgeschützt“ abgelehnt, bevor sie die Datenbank erreicht, egal was der Browser behauptet. Die anderen Sicherheitsflags (Bestätigungsdialoge, der Rollback-Wrapper, Schutz vor unbegrenzten UPDATE/DELETE) sind Verhalten des SQLly-Clients im Browser des Nutzers, keine serverseitige Kontrolle. Datenbankberechtigungen bleiben die eigentliche Kontrolle: Gib Logins, die über den Proxy laufen, nur das, was deren Nutzer tun können sollen.

Größenanpassung

Jeder offene SQLly-Tab läuft in einem sqlly-cli Engine-Prozess mit eigenen Datenbankverbindungen. Der Speicherbedarf folgt der Nutzung: Ergebnismengen werden gestreamt und bei Bedarf auf die Festplatte ausgelagert, statt vollständig im Speicher zu liegen, aber große Exporte und viele gleichzeitige Tabs summieren sich. Plane den Host für deine Spitzenzahl gleichzeitiger Tabs aus (höchstens Sitze × Tabs pro Sitz) und verwende --max-sessions als Sicherheitsnetz. Engines werden bei Bedarf gestartet und beenden sich, wenn ihr Tab geschlossen wird.

Operationen

  • Sichere das Statusverzeichnis. Es enthält jedes Profil mit seinen Anmeldedaten und dem Schlüssel einer verknüpften Installation. Behandle Backups wie Geheimnisse.
  • Beobachte das Protokoll für embedded license state: jeder Lizenzwechsel wird mit seinem Statusnamen protokolliert. Überwache GET /manage/status aus deinem Monitoring, und verwende GET /healthz (kein Token) für die Verfügbarkeit.
  • Halte die Uhr korrekt. Berechtigungen müssen innerhalb von 5 Minuten zur Uhr der Bridge ausgestellt werden, daher nutze NTP.
  • Gemeinsam aktualisieren. Ersetzen bin/ und web/ Von derselben Paketversion. Das Neustarten der Brücke schließt offene Tabs, und Benutzer verbinden sich durch Neuladen erneut.
  • Verwaltungs-Token rotieren indem du die Bridge und deine App mit dem neuen Wert neu startest. Bereits ausgestellte Launch-Token funktionieren weiter, bis sie ablaufen.
  • Domain-Wechsel? Ändere es auf deiner Embedded-Seite und starte die Bridge mit dem neuen --domain. Offline-Lizenzen benötigen eine neue Datei, weil die Domain darin enthalten ist.

Produktions-Checkliste

  • TLS vor dem Browser-Listener, und --public-url auf die wss:// Adresse gesetzt.
  • SQLLY_EMBEDDED_DOMAIN gesetzt und die Lizenz daran gebunden; --allow-localhost-origins=false.
  • Management-API auf Loopback oder in einem privaten Netzwerk; das Management-Token nur in serverseitigen Secrets aufbewahren.
  • Launch-Tokens, die der Seite über SQLLY_PROXY_URL / SQLLY_PROXY_TOKEN Globals, niemals in einer Seiten-URL (?token= landet im Verlauf, in Referrern und in Webserver-Protokollen).
  • --allow-file-engines nicht aktiviert, sofern kein abgesicherter Service-Account und Verzeichnis dafür eingerichtet wurden.
  • State-Verzeichnis nur für den Service-Account lesbar (auf Linux/macOS nur für den Eigentümer; unter Windows eine explizite ACL); --query-log und SQLLY_ENGINE_LOG entsprechend deiner Richtlinie zur Aufbewahrung des Abfragetexts festgelegt.
  • Nein SQLLY_LLM_PROVIDER / SQLLY_EMBEDDING_PROVIDER in der Umgebung der Bridge, es sei denn, Endbenutzer sollen diese Ausgaben tragen.
  • Bridge und App laufen als Dienste unter einem nicht privilegierten Benutzer, Neustart bei Fehler, ordentliches Herunterfahren.
  • State-Verzeichnis auf persistentem Speicher, nur für den Besitzer zugänglich, mit Backup.
  • Die SQLly-Seite und web/ mit COOP/COEP ausgeliefert, application/wasm, und einer CSP, die den Bridge-Ursprung erlaubt.
  • Ausgehendes HTTPS zu sqlly.app erlaubt (verbundene Lizenzen), NTP eingeschaltet.
  • Monitoring auf /manage/status: Alarm, wenn license.state nicht verfügbar ist ok.
  • Das Standard-Admin-Passwort der Beispiel-App hat sich geändert, falls du die Beispiel-App überhaupt einsetzt. Sie bindet sich nicht über Loopback hinaus, bis du das tust.