Passer en production
TLS, les proxies inverses, le domaine licencié, les gestionnaires de services, les sauvegardes, la Content-Security-Policy et les en-têtes d'isolation, et une checklist de production pour SQLly Embedded.
Sur localhost, les valeurs par défaut fonctionnent telles quelles. En production, placez le pont derrière TLS, liez votre licence à votre domaine, gardez l’API de gestion privée et faites tourner le tout en tant que services. Cette page rassemble les réglages, les configurations et la checklist pour y parvenir.
Disposition recommandée
- Un hôte ou un réseau privé pour votre application et le pont. L'API de gestion (
127.0.0.1:8445) ne doit être accessible que par votre application. - Un proxy inverse (nginx, Caddy, IIS, un équilibrage de charge cloud) termine le TLS et transfère les mises à niveau WebSocket sur un chemin tel que
/sqlly/proxyvers le--bindécouteur du pont. - Le même proxy sert votre application, y compris la page SQLly et
web/le bundle, de sorte que tout est servi en même origine sous votre domaine sous licence. - Le pont a besoin de du HTTPS sortant vers sqlly.app (licences connectées uniquement) et un accès réseau à vos bases de données. Les navigateurs n'accèdent jamais à vos bases de données ni au moteur.
Proxy inverse
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
}
Puis démarrez le pont avec --public-url wss://portal.example.com/sqlly/proxy pour que chaque jeton de lancement indique à SQLly où se connecter. Pour passer outre le proxy, donnez au pont --tls-cert et --tls-key et il sert wss:// lui-même.
Exécutez-le en tant que service
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
Sur macOS, utilisez un plist de launchd avec le même environnement. Sur Windows, exécutez sqlly-bridge.exe embedded sous un wrapper de service ou le Planificateur de tâches. Dans les conteneurs, montez le répertoire d'état en tant que volume. Le pont se termine avec un message clair si sa licence ne peut pas être vérifiée au démarrage, donc une politique de redémarrage continue de réessayer jusqu'à ce que sqlly.app soit accessible.
Arrêtez-le avec un signal d'arrêt normal. Le pont se ferme proprement sur SIGTERM (ce que systemd, launchd et docker stop envoient), SIGINT (Ctrl-C), SIGHUP (la fermeture de la fenêtre du terminal, une session ssh qui se déconnecte), ou la fermeture de la fenêtre de la console sur Windows : il ferme les sessions et libère immédiatement son emplacement d'instance sur sqlly.app, en réessayant pendant quelques secondes si sqlly.app ne répond pas. Un arrêt forcé (SIGKILL, un crash, une coupure de courant) laisse l'emplacement occupé jusqu'à ce qu'il devienne obsolète 40 minutes plus tard, et un pont de remplacement n'est pas admis avant cela. Les ponts d'avant ce changement ne libéraient l'emplacement que sur SIGINT ; si vous en exécutez un, ajoutez KillSignal=SIGINT à l'unité ou utilisez STOPSIGNAL SIGINT dans Docker.
Chaque paramètre du pont
Chaque option possède une variable d'environnement, donc une unité de service ou .env fichier peut contenir toute la configuration.
| Option | Environnement | Par défaut | Sens |
|---|---|---|---|
--license-key | SQLLY_EMBEDDED_LICENSE_KEY | aucun | Clé de licence connectée depuis votre page Embedded. |
--license-file | SQLLY_EMBEDDED_LICENSE_FILE | aucun | Fichier de licence hors ligne. Ne contacte jamais sqlly.app. Fournissez au plus l'un des deux : clé ou fichier ; sans aucun des deux, une clé liée est utilisée, sinon le pont démarre sans licence. |
--domain | SQLLY_EMBEDDED_DOMAIN | aucun | Lie une licence non liée lors du premier enregistrement ; refuse de démarrer si la licence est liée ailleurs. |
--bind | SQLLY_EMBEDDED_BIND | 0.0.0.0:8444 | Écouteur WebSocket pour navigateur (chemin /proxy). Utilisez le loopback derrière un reverse proxy. |
--public-url | SQLLY_EMBEDDED_PUBLIC_URL | ws://localhost:<port>/proxy | L'URL utilisée par les navigateurs, renvoyée avec chaque jeton de lancement. |
--manage-bind | SQLLY_EMBEDDED_MANAGE_BIND | 127.0.0.1:8445 | Point d'écoute de l'API de gestion. Gardez-le privé : il contient des identifiants. |
--manage-token | SQLLY_EMBEDDED_MANAGE_TOKEN | requis | Jeton Bearer pour l'API de gestion, au moins 16 caractères. |
--tls-cert, --tls-key | SQLLY_EMBEDDED_TLS_CERT, SQLLY_EMBEDDED_TLS_KEY | aucun | Servir wss:// directement. Fournissez les deux ou aucun des deux. |
--state-dir | SQLLY_EMBEDDED_STATE_DIR | ./sqlly-embedded-state | Profils, autorisation en cache, clé liée, fichiers d'identifiants par session. Créés avec des permissions limitées au propriétaire. |
--engine-binary | SQLLY_CLI_BIN | à côté du pont, puis PATH | Le sqlly-cli le pont fonctionne par session. |
--max-sessions | SQLLY_EMBEDDED_MAX_SESSIONS | 64 | Plafond strict de moteurs simultanés sur cet hôte. |
--allow-localhost-origins | SQLLY_EMBEDDED_ALLOW_LOCALHOST_ORIGINS | true | Accepter les origines localhost en plus du domaine sous licence. Définir false en production. |
--token-ttl-seconds | SQLLY_EMBEDDED_TOKEN_TTL_SECONDS | 600 | Durée de vie par défaut du jeton de lancement. |
--store-url | SQLLY_STORE_URL | https://sqlly.app | Où vont les check-ins. Ne pas y toucher en dehors du développement. |
--allow-file-engines | SQLLY_EMBEDDED_ALLOW_FILE_ENGINES | false | Accepter les profils avec moteurs basés sur fichiers (SQLite, DuckDB). Désactivé, ils sont refusés avec 400 invalid_profile. Voir Moteurs basés sur les fichiers. |
--query-log | SQLLY_EMBEDDED_QUERY_LOG | true | Conserver la piste d'audit des requêtes (GET /manage/queries, <state-dir>/queries.jsonl). false ne consigne rien. Voir Piste d'audit des requêtes. |
--query-log-max-entries | SQLLY_EMBEDDED_QUERY_LOG_MAX_ENTRIES | 20000 | Les requêtes terminées les plus récentes sont conservées, en mémoire et sur disque (minimum 100). |
Le répertoire d'état et l'hôte
Le répertoire d'état contient chaque profil avec ses mots de passe, la licence accordée en cache, la clé d'une installation liée, les fichiers d'identification par session remis aux moteurs et la piste d'audit des requêtes. Sur Linux et macOS, le pont le crée pour le propriétaire seulement (0700, fichiers 0600).
Sous Windows, le pont ne peut pas renforcer les permissions. Le répertoire d'état hérite de l'ACL de son dossier parent, et le pont enregistre un avertissement au démarrage pour le signaler. Placez-le sous un dossier que seul le compte de service peut lire, par exemple un répertoire dédié sous %ProgramData% avec l'héritage supprimé et une ACL accordant uniquement au compte de service, et jamais sous un chemin partagé, synchronisé ou accessible aux utilisateurs.
Moteurs basés sur les fichiers
Les moteurs basés sur des fichiers sont désactivés par défaut. Une connexion SQLite ou DuckDB dans un profil désigne un fichier sur l'hôte du pont. Ses utilisateurs peuvent alors lire ce fichier, en créer de nouveaux et, via les fonctions de fichiers du moteur, atteindre d'autres fichiers que le compte de service peut lire. Le pont refuse donc les profils, les tests de connexion et les jetons de lancement qui impliquent un moteur basé sur des fichiers avec 400 invalid_profile et un problems[] entrée expliquant pourquoi, à moins qu'il ne s'exécute avec --allow-file-engines true. Activez-le uniquement pour un compte de service dédié et verrouillé, et pour un répertoire que les utilisateurs doivent pouvoir atteindre. En mode proxy, le moteur interdit en outre le téléchargement d'extensions DuckDB et l'accès externe (lecture de fichiers, COPY, ATTACH) pour chaque instance DuckDB qu'il ouvre.
Piste d'audit des requêtes
Le pont enregistre chaque requête et modification de ligne exécutée par ses sessions : l'utilisateur et le profil du jeton de lancement, la connexion (nom, serveur, moteur, base de données), le texte SQL, le moment où elle a commencé, comment elle s'est terminée et combien de temps cela a pris. Les requêtes refusées en raison d'un problème de licence sont enregistrées comme échouées avec le message de licence ; tout ce qui était en cours d'exécution lorsque la session s'est fermée est enregistré comme annulé. Votre application le lit avec GET /manage/queries, les plus récents en premier, filtrés par utilisateur, profil, statut ou date.
Les plus récentes des --query-log-max-entries entrées vivent en mémoire et dans <state-dir>/queries.jsonl (un objet JSON par ligne, écrit uniquement pour le propriétaire, compacté automatiquement), donc la trace survit aux redémarrages. Le texte SQL est stocké sur l'hôte pont en clair. Gardez le répertoire d'état aussi privé que les profils qu'il contient déjà, et définissez --query-log false si votre politique interdit tout simplement de conserver le texte des requêtes.
Le journal du moteur lui-même
Chaque sqlly-cli le moteur écrit un journal de corrélation requête/réponse, incluant le texte SQL complet de chaque requête, dans son répertoire de données : ~/.local/share/sqlly/sqlly-engine.log (ou $XDG_DATA_HOME/sqlly/sqlly-engine.log) sur Linux, ~/Library/Application Support/SQLLY/sqlly-engine.log sur macOS, %APPDATA%\SQLLY\sqlly-engine.log sur Windows, créé uniquement pour le propriétaire. Les mots de passe, tokens et références secrètes sont effacés avant qu'une ligne soit écrite ; les identifiants, serveurs, noms d'utilisateur et SQL sont conservés. Définissez SQLLY_ENGINE_LOG=<path> dans l'environnement du pont (ses moteurs en héritent) pour déplacer le journal quelque part que vous contrôlez, ou SQLLY_ENGINE_LOG=/dev/null (NUL sur Windows) pour ne rien conserver. Le journal est réduit à ses dernières lignes seulement lorsqu'un moteur se ferme correctement.
Paramètres du fournisseur IA
Le moteur récupère la configuration du fournisseur IA depuis son environnement (SQLLY_LLM_PROVIDER, SQLLY_EMBEDDING_PROVIDER et les variables de modèle et de clé associées). Ne les définissez pas sur l'hôte du pont, sauf si vous voulez que l'IntelliSense et les fonctions d'IA de vos utilisateurs finaux consomment le quota de ce compte.
Flags de sécurité
Le only_allow_select (sur un client, un projet ou une étiquette d'environnement) et le safety.block_all_but_select sont appliqués par le moteur sur l'hôte du pont : une instruction qui n'est pas uniquement SELECT pour le moteur de la connexion, et chaque modification de ligne, sont refusées avec « cette connexion est en lecture seule par politique » avant d'atteindre la base de données, quoi qu'en prétende le navigateur. Les autres options de sécurité (boîtes de dialogue de confirmation, encapsulation de rollback, protection contre les UPDATE/DELETE illimités) sont un comportement du client SQLly dans le navigateur de l'utilisateur, pas un contrôle côté serveur. Les permissions de la base de données restent le véritable contrôle : n'accordez aux connexions relayées que ce que leurs utilisateurs doivent pouvoir faire.
Dimensionnement
Chaque onglet SQLly ouvert exécute un seul sqlly-cli processus du moteur avec ses propres connexions à la base de données. La mémoire suit ce que font les gens : les jeux de résultats sont transmis en continu puis déversés sur le disque au lieu d'être gardés en entier, mais les exports volumineux et les nombreux onglets simultanés s'additionnent. Dimensionnez l'hôte pour votre pic d'onglets simultanés (sièges × onglets par siège au maximum), et utilisez --max-sessions comme filet de sécurité. Les moteurs sont démarrés à la demande et se ferment lorsque leur onglet se ferme.
Opérations
- Sauvegardez le répertoire d'état. Il contient chaque profil avec ses identifiants et la clé d'une installation liée. Traitez les sauvegardes comme des secrets.
- Surveillez le journal pour
embedded license state: chaque transition de licence est enregistrée avec le nom de son état. InterrogezGET /manage/statusdepuis votre surveillance, et utilisezGET /healthz(pas de jeton) pour vérifier la disponibilité. - Gardez l'horloge à l'heure. Les autorisations doivent être émises à moins de 5 minutes d'écart avec l'horloge du pont, d'où l'importance d'exécuter NTP.
- Mettez à jour les deux ensemble. Remplacer
bin/etweb/à partir de la même version du package. Redémarrer le pont ferme les onglets ouverts, et les utilisateurs se reconnectent en rechargeant. - Renouvelez le jeton de gestion en redémarrant le pont et votre application avec la nouvelle valeur. Les jetons de lancement déjà émis continuent de fonctionner jusqu'à leur expiration.
- Vous déplacez des domaines ? Changez-le sur votre page Embedded et redémarrez le pont avec le nouveau
--domain. Les licences hors ligne nécessitent un nouveau fichier, car le domaine y est inclus.
Liste de contrôle pour la production
- TLS devant l'écouteur de navigateur, et
--public-urlréglé sur lewss://adresse. SQLLY_EMBEDDED_DOMAINl'ensemble et de la licence qui y est liée ;--allow-localhost-origins=false.- API de gestion sur loopback ou réseau privé ; jeton de gestion uniquement dans les secrets côté serveur.
- Jetons de lancement transmis à la page par le
SQLLY_PROXY_URL/SQLLY_PROXY_TOKENglobals, jamais dans une URL de page (?token=se retrouve dans l'historique, les référents et les journaux du serveur web). --allow-file-engineslaissé de côté, sauf si un compte de service verrouillé et un annuaire avaient été configurés pour lui.- Répertoire d'état lisible uniquement par le compte de service (propriétaire seul sur Linux/macOS ; une ACL explicite sur Windows) ;
--query-logetSQLLY_ENGINE_LOGdéfini selon votre politique de conservation du texte des requêtes. - Non
SQLLY_LLM_PROVIDER/SQLLY_EMBEDDING_PROVIDERdans l'environnement du pont sauf si les utilisateurs finaux doivent piloter cette dépense. - Pont et application exécutés comme services sous un utilisateur non privilégié, redémarrage en cas d'échec, arrêt en douceur.
- Répertoire d'état sur stockage persistant, réservé au propriétaire, sauvegardé.
- La page SQLly et
web/servie avec COOP/COEP,application/wasm, et un CSP qui autorise l'origine du pont. - HTTPS sortant vers sqlly.app autorisé (licences connectées), NTP activé.
- Surveillance activée
/manage/status: alerte lorsquelicense.staten'est pasok. - Le mot de passe administrateur par défaut de l'application exemple a changé, si vous déployez l'application exemple. Elle refuse de se lier au-delà de la boucle locale tant que vous ne le faites pas.