Ir a producción
TLS, proxies inversos, dominio con licencia, gestores de servicios, copias de seguridad, Content-Security-Policy, encabezados de aislamiento y una lista de comprobación para pasar SQLly Embedded a producción.
En localhost los valores por defecto funcionan tal cual. En producción, pon el puente detrás de TLS, vincula tu licencia a tu dominio, mantén privada la API de gestión y ejecuta todo como servicios. Esta página reúne los ajustes, la configuración y la lista de verificación para lograrlo.
Diseño recomendado
- Un host o red privada para tu aplicación y el puente. La API de gestión (
127.0.0.1:8445) solo debería ser accesible desde tu aplicación. - Un proxy inverso (nginx, Caddy, IIS, un balanceador de carga en la nube) termina TLS y reenvía actualizaciones de WebSocket en una ruta como
/sqlly/proxyal--bindlistener del puente. - El mismo proxy sirve tu aplicación, incluida la página de SQLly y
web/bundle, por lo que todo está bajo el mismo origen en tu dominio licenciado. - El puente necesita HTTPS saliente hacia sqlly.app (solo licencias conectadas) y acceso por red a tus bases de datos. Los navegadores nunca acceden a tus bases de datos ni al motor.
Proxy inverso
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
}
Luego inicia el puente con --public-url wss://portal.example.com/sqlly/proxy para que cada token de lanzamiento le indique a SQLly dónde conectarse. Para omitir el proxy, dale al puente --tls-cert y --tls-key y sirve wss:// se sirve a sí mismo.
Ejecutarlo como un servicio
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
En macOS, usa un plist de launchd con el mismo entorno. En Windows, ejecuta sqlly-bridge.exe embedded bajo un envoltorio de servicio o el Task Scheduler. En contenedores, monta el directorio de estado como un volumen. El puente se cierra con un mensaje claro si no puede verificar su licencia al arrancar, así que una política de reinicio seguirá intentándolo hasta que sqlly.app responda.
Detenlo con una señal de detención normal. El puente se apaga de forma limpia con SIGTERM (lo que systemd, launchd y docker stop enviar), SIGINT (Ctrl-C), SIGHUP (el cierre de la ventana de terminal, la desconexión de una sesión ssh), o el cierre de la ventana de la consola en Windows: cierra sesiones y libera su ranura de instancia en sqlly.app de inmediato, reintentando durante unos segundos si sqlly.app no responde. Una terminación forzada (SIGKILL, un fallo, pérdida de energía) mantiene la ranura ocupada hasta que caduque 40 minutos después, y un puente de reemplazo no es admitido hasta entonces. Los puentes anteriores a este cambio liberaban la ranura solo con SIGINT; si ejecutas uno, agrega KillSignal=SIGINT a la unidad o usa STOPSIGNAL SIGINT en Docker.
Cada ajuste de bridge
Cada flag tiene una variable de entorno, así que una unidad de servicio o .env el archivo puede contener toda la configuración.
| Indicador | Entorno | Predeterminado | Significado |
|---|---|---|---|
--license-key | SQLLY_EMBEDDED_LICENSE_KEY | ninguno | Clave de licencia conectada desde tu página de Embedded. |
--license-file | SQLLY_EMBEDDED_LICENSE_FILE | ninguno | Archivo de licencia sin conexión. Nunca contacta con sqlly.app. Indica como máximo una clave o un archivo; si no indicas ninguno, se usa una clave vinculada; de lo contrario, el puente arranca sin licencia. |
--domain | SQLLY_EMBEDDED_DOMAIN | ninguno | Vincula una licencia sin vincular en el primer registro; se niega a iniciar si la licencia está vinculada en otro lugar. |
--bind | SQLLY_EMBEDDED_BIND | 0.0.0.0:8444 | Listener WebSocket del navegador (ruta /proxy). Usa loopback detrás de un proxy inverso. |
--public-url | SQLLY_EMBEDDED_PUBLIC_URL | ws://localhost:<port>/proxy | La URL que usan los navegadores, devuelta con cada token de inicio. |
--manage-bind | SQLLY_EMBEDDED_MANAGE_BIND | 127.0.0.1:8445 | Listener de la API de gestión. Mantenlo privado: contiene credenciales. |
--manage-token | SQLLY_EMBEDDED_MANAGE_TOKEN | obligatorio | Token de portador para la API de gestión, al menos 16 caracteres. |
--tls-cert, --tls-key | SQLLY_EMBEDDED_TLS_CERT, SQLLY_EMBEDDED_TLS_KEY | ninguno | Servir wss:// directamente. Indica ambos o ninguno. |
--state-dir | SQLLY_EMBEDDED_STATE_DIR | ./sqlly-embedded-state | Perfiles, concesión en caché, clave vinculada, archivos de credenciales por sesión. Creados con permisos solo para el propietario. |
--engine-binary | SQLLY_CLI_BIN | junto al puente, luego PATH | La sqlly-cli el puente se ejecuta por sesión. |
--max-sessions | SQLLY_EMBEDDED_MAX_SESSIONS | 64 | Límite estricto de motores concurrentes en este host. |
--allow-localhost-origins | SQLLY_EMBEDDED_ALLOW_LOCALHOST_ORIGINS | true | Aceptar orígenes localhost además del dominio con licencia. Establece false en producción. |
--token-ttl-seconds | SQLLY_EMBEDDED_TOKEN_TTL_SECONDS | 600 | Duración predeterminada del token de lanzamiento. |
--store-url | SQLLY_STORE_URL | https://sqlly.app | Dónde van los check-ins. No lo toques fuera del desarrollo. |
--allow-file-engines | SQLLY_EMBEDDED_ALLOW_FILE_ENGINES | false | Aceptar perfiles con motores basados en archivos (SQLite, DuckDB). Si está desactivado, se rechazan con 400 invalid_profile. Ver Motores basados en archivos. |
--query-log | SQLLY_EMBEDDED_QUERY_LOG | true | Mantener el registro de auditoría de consultas (GET /manage/queries, <state-dir>/queries.jsonl). false no registra nada. Ver Registro de auditoría de consultas. |
--query-log-max-entries | SQLLY_EMBEDDED_QUERY_LOG_MAX_ENTRIES | 20000 | Se conservan las últimas consultas terminadas, en memoria y en disco (mínimo 100). |
El directorio de estado y el host
El directorio de estado contiene cada perfil con sus contraseñas, la concesión de licencia en caché, la clave de una instalación vinculada, los archivos de credenciales por sesión entregados a los motores y el registro de auditoría de consultas. En Linux y macOS el puente lo crea solo para el propietario (0700, archivos 0600).
En Windows, el puente no puede restringir los permisos. El directorio de estado hereda la ACL de su carpeta contenedora, y el puente registra una advertencia al inicio para indicarlo. Ponlo en una carpeta que solo pueda leer la cuenta de servicio, por ejemplo en un directorio dedicado bajo %ProgramData% con la herencia eliminada y un ACL que otorgue únicamente a la cuenta de servicio, y nunca bajo una ruta compartida, sincronizada o navegable por el usuario.
Motores basados en archivos
Los motores basados en archivos están desactivados por defecto. Una conexión SQLite o DuckDB en un perfil apunta a un archivo del host puente. Sus usuarios pueden luego leer ese archivo, crear otros nuevos y, mediante las propias funciones de archivos del motor, acceder a otros archivos que la cuenta de servicio puede leer. Por eso, el puente rechaza perfiles, pruebas de conexión y tokens de lanzamiento que impliquen un motor basado en archivos con 400 invalid_profile y un problems[] entrada que explique por qué, a menos que se ejecute con --allow-file-engines true. Actívalo solo para una cuenta de servicio dedicada y bien restringida y para un directorio que quieras que alcancen los usuarios. En modo proxy, el motor además prohíbe las descargas de extensiones de DuckDB y el acceso externo (escaneos de archivos, COPY, ATTACH) para cada instancia de DuckDB que abre.
Registro de auditoría de consultas
El puente registra cada consulta y edición de filas que se ejecute en sus sesiones: el usuario y el perfil del token de lanzamiento, la conexión (nombre, servidor, motor, base de datos), el texto SQL, cuándo empezó, cómo terminó y cuánto duró. Las solicitudes rechazadas por un problema de licencia se registran como fallidas con el mensaje de licencia; lo que se estaba ejecutando cuando se cerró la sesión queda registrado como cancelado. Tu aplicación lo lee con GET /manage/queries, primero las más recientes, filtradas por usuario, perfil, estado o tiempo.
Las más recientes --query-log-max-entries las entradas se guardan en memoria y en <state-dir>/queries.jsonl (un objeto JSON por línea, con permisos de escritura solo para el propietario, compactado automáticamente), de modo que el registro sobrevive a los reinicios. El texto SQL se guarda en claro en el host del puente. Mantén el directorio de estado tan privado como los perfiles que ya contiene, y configura --query-log false si tu política prohíbe mantener el texto de las consultas por completo.
El registro del propio motor
Cada sqlly-cli el motor escribe un registro de correlación de solicitudes/respuestas, incluyendo el texto SQL completo de cada solicitud, en su directorio de datos: ~/.local/share/sqlly/sqlly-engine.log (o $XDG_DATA_HOME/sqlly/sqlly-engine.log) en Linux, ~/Library/Application Support/SQLLY/sqlly-engine.log en macOS, %APPDATA%\SQLLY\sqlly-engine.log en Windows, creado con permisos solo para el propietario. Las contraseñas, los tokens y las referencias a secretos se eliminan antes de escribir cada línea; los IDs, servidores, nombres de usuario y SQL se conservan. Configura SQLLY_ENGINE_LOG=<path> en el entorno del puente (sus motores lo heredan) para mover el registro a un lugar bajo tu control, o SQLLY_ENGINE_LOG=/dev/null (NUL en Windows) para no conservar nada. El registro se recorta a sus últimas líneas solo cuando un motor sale correctamente.
Ajustes del proveedor de IA
El motor toma la configuración del proveedor de IA de su entorno (SQLLY_LLM_PROVIDER, SQLLY_EMBEDDING_PROVIDER y las variables de modelo y clave relacionadas). No las establezcas en el host del puente, a menos que quieras que el IntelliSense y las funciones de IA de tus usuarios finales consuman de esa cuenta.
Opciones de seguridad
Un perfil only_allow_select (en una etiqueta de cliente, proyecto o entorno) y una conexión safety.block_all_but_select los aplica el motor en el host del puente: una instrucción que no sea de solo SELECT para el motor de la conexión, y cada edición de filas, se rechaza con «esta conexión es de solo lectura por política» antes de llegar a la base de datos, diga lo que diga el navegador. Los demás flags de seguridad (diálogos de confirmación, el envoltorio de rollback, la protección contra UPDATE/DELETE sin límites) son comportamiento del cliente SQLly en el navegador del usuario, no un control del lado del servidor. Los permisos de la base de datos siguen siendo el control real: da a los inicios de sesión proxy solo lo que sus usuarios deben poder hacer.
Dimensionamiento
Cada pestaña abierta de SQLly ejecuta uno sqlly-cli proceso del motor con sus propias conexiones de base de datos. El uso de memoria depende de lo que se haga: los conjuntos de resultados se transmiten y se descargan a disco en vez de mantenerse completos en memoria, pero las exportaciones grandes y muchas pestañas concurrentes suman. Dimensiona el host para el máximo de pestañas concurrentes (usuarios × pestañas por usuario, como máximo) y usa --max-sessions como respaldo. Los motores se inician bajo demanda y se cierran cuando se cierra su pestaña.
Operaciones
- Haz una copia de seguridad del directorio de estado. Contiene cada perfil con sus credenciales y la clave de una instalación vinculada. Trata las copias de seguridad como secretos.
- Observa el registro para
embedded license state: cada transición de licencia se registra con el nombre de su estado. ConsultaGET /manage/statusdesde tu monitoreo, y usaGET /healthz(sin token) para comprobar que está vivo. - Ten el reloj en hora. Los permisos deben emitirse dentro de un margen de 5 minutos del reloj del puente, así que ejecuta NTP.
- Actualiza ambos a la vez. Reemplazar
bin/yweb/desde la misma versión del paquete. Reiniciar el puente cierra las pestañas abiertas, y los usuarios se reconectan recargando. - Rota el token de gestión reiniciando el puente y tu aplicación con el nuevo valor. Los tokens de lanzamiento ya emitidos siguen funcionando hasta que expiren.
- ¿Cambiando de dominio? Cámbialo en tu página Embedded y reinicia el puente con el nuevo
--domain. Las licencias sin conexión necesitan un archivo nuevo, porque el dominio va dentro.
Lista de verificación de producción
- TLS frente al listener del navegador, y
--public-urlestablecido en lawss://dirección. SQLLY_EMBEDDED_DOMAINconfigurado y la licencia vinculada a él;--allow-localhost-origins=false.- API de gestión en loopback o en una red privada; gestiona el token solo mediante secretos del lado del servidor.
- Los tokens de lanzamiento se entregan a la página a través de las
SQLLY_PROXY_URL/SQLLY_PROXY_TOKENglobales, nunca en una URL de página (?token=termina en el historial, en los referrers y en los registros del servidor web). --allow-file-enginesse deja desactivado a menos que se configure para ello una cuenta de servicio con permisos restringidos y un directorio.- Directorio de estado legible solo por la cuenta de servicio (solo el propietario en Linux/macOS; una ACL explícita en Windows);
--query-logySQLLY_ENGINE_LOGestablecido según tu política de conservación del texto de las consultas. - No
SQLLY_LLM_PROVIDER/SQLLY_EMBEDDING_PROVIDERen el entorno del puente a menos que el gasto deba correr a cuenta de los usuarios finales. - El puente y la app corren como servicios bajo un usuario sin privilegios, con reinicio ante fallos y parada ordenada.
- Directorio de estado en almacenamiento persistente, solo para el propietario y con copia de seguridad.
- La página de SQLly y
web/servida con COOP/COEP,application/wasm, y un CSP que permita el origen del puente. - HTTPS saliente a sqlly.app permitido (licencias conectadas), NTP activado.
- Monitoreo activado
/manage/status: alerta cuandolicense.stateno seaok. - La contraseña de administrador por defecto de la aplicación de ejemplo ha cambiado, si es que la despliegas. Se niega a escuchar fuera de loopback hasta que la cambies.