Indo para produção
TLS, proxies reversos, o domínio licenciado, gerenciadores de serviço, backups, Content-Security-Policy e cabeçalhos de isolamento, e um checklist de produção para SQLly Embedded.
No localhost, os padrões simplesmente funcionam. Em produção, coloque a ponte atrás de TLS, vincule sua licença ao seu domínio, mantenha a API de gerenciamento privada e execute tudo como serviços. Esta página tem as configurações, os arquivos de configuração e o checklist para isso.
Layout recomendado
- Um host ou rede privada para o seu app e o bridge. A API de gerenciamento (
127.0.0.1:8445) deve ser acessível apenas pelo seu app. - Um proxy reverso (nginx, Caddy, IIS, um balanceador de carga na nuvem) encerra o TLS e encaminha atualizações do WebSocket em um caminho como
/sqlly/proxyda ponte--bindouvinte. - O mesmo proxy serve seu aplicativo, incluindo a página SQLly e
web/pacote, então tudo é da mesma origem sob seu domínio licenciado. - A ponte precisa HTTPS de saída para sqlly.app (apenas licenças conectadas) e acesso em rede aos seus bancos de dados. Os navegadores nunca acessam seus bancos de dados ou o mecanismo.
Proxy reverso
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
}
Então inicie a ponte com --public-url wss://portal.example.com/sqlly/proxy para que cada token de inicialização diga ao SQLly onde se conectar. Para pular o proxy, forneça à ponte --tls-cert e --tls-key e ela serve wss:// a si mesmo.
Execute como um serviço
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
No macOS, use um plist do launchd com o mesmo ambiente. No Windows, execute sqlly-bridge.exe embedded sob um wrapper de serviço ou o Agendador de Tarefas. Em contêineres, monte o diretório de estado como um volume. A ponte sai com uma mensagem clara se a licença dela não puder ser verificada na inicialização, então uma política de reinício continua tentando até que sqlly.app fique acessível.
Encerre com um sinal de parada normal. A ponte se encerra de forma limpa com SIGTERM (o que systemd, launchd e docker stop enviam), SIGINT (Ctrl-C), SIGHUP (o fechamento da janela do terminal, uma sessão ssh sendo interrompida) ou o fechamento da janela do console no Windows: ela fecha sessões e libera seu slot de instância no sqlly.app imediatamente, tentando por alguns segundos se o sqlly.app não responder. Um encerramento forçado (SIGKILL, uma falha, perda de energia) mantém o slot ocupado até que ele se torne obsoleto 40 minutos depois, e uma ponte substituta não é admitida até então. Pontes anteriores a esta mudança liberavam o slot apenas no SIGINT; se você executar uma, adicione KillSignal=SIGINT a unidade ou use STOPSIGNAL SIGINT no Docker.
Cada configuração de ponte
Cada flag tem uma variável de ambiente, então uma unidade de serviço ou .env arquivo pode conter toda a configuração.
| Flag | Ambiente | Padrão | Significado |
|---|---|---|---|
--license-key | SQLLY_EMBEDDED_LICENSE_KEY | nenhum | Chave de licença conectada da sua página Embedded. |
--license-file | SQLLY_EMBEDDED_LICENSE_FILE | nenhum | Forneça no máximo um de chave ou arquivo; sem nenhum, uma chave vinculada é usada; caso contrário, o bridge inicia sem licença. |
--domain | SQLLY_EMBEDDED_DOMAIN | nenhum | Vincula uma licença não vinculada no primeiro check-in; recusa iniciar se a licença estiver vinculada em outro lugar. |
--bind | SQLLY_EMBEDDED_BIND | 0.0.0.0:8444 | Ouvinte WebSocket do navegador (caminho /proxy). Use loopback atrás de um proxy reverso. |
--public-url | SQLLY_EMBEDDED_PUBLIC_URL | ws://localhost:<port>/proxy | A URL que os navegadores usam, retornada com cada token de inicialização. |
--manage-bind | SQLLY_EMBEDDED_MANAGE_BIND | 127.0.0.1:8445 | Listener da API de gerenciamento. Mantenha-o privado: ele guarda credenciais. |
--manage-token | SQLLY_EMBEDDED_MANAGE_TOKEN | obrigatório | Token Bearer para a API de gerenciamento, com pelo menos 16 caracteres. |
--tls-cert, --tls-key | SQLLY_EMBEDDED_TLS_CERT, SQLLY_EMBEDDED_TLS_KEY | nenhum | Servir wss:// diretamente. Dê ambos ou nenhum. |
--state-dir | SQLLY_EMBEDDED_STATE_DIR | ./sqlly-embedded-state | Perfis, concessão em cache, chave vinculada, arquivos de credenciais por sessão. Criado apenas para o proprietário. |
--engine-binary | SQLLY_CLI_BIN | ao lado da ponte, então PATH | O sqlly-cli o bridge roda por sessão. |
--max-sessions | SQLLY_EMBEDDED_MAX_SESSIONS | 64 | Limite máximo de mecanismos simultâneos neste host. |
--allow-localhost-origins | SQLLY_EMBEDDED_ALLOW_LOCALHOST_ORIGINS | true | Aceitar origens localhost além do domínio licenciado. Definir false em produção. |
--token-ttl-seconds | SQLLY_EMBEDDED_TOKEN_TTL_SECONDS | 600 | Tempo de vida padrão do token de inicialização. |
--store-url | SQLLY_STORE_URL | https://sqlly.app | Onde os check-ins vão. Não mexa fora do desenvolvimento. |
--allow-file-engines | SQLLY_EMBEDDED_ALLOW_FILE_ENGINES | false | Aceitar perfis com engines baseadas em arquivo (SQLite, DuckDB). Desligado, eles são recusados com 400 invalid_profile. Veja Mecanismos baseados em arquivo. |
--query-log | SQLLY_EMBEDDED_QUERY_LOG | true | Mantenha a trilha de auditoria de consultas (GET /manage/queries, <state-dir>/queries.jsonl). false não registra nada. Veja Trilha de auditoria de consultas. |
--query-log-max-entries | SQLLY_EMBEDDED_QUERY_LOG_MAX_ENTRIES | 20000 | As consultas concluídas mais recentes são mantidas na memória e no disco (mínimo de 100). |
O diretório de estado e o host
O diretório de estado guarda todos os perfis com suas senhas, a licença concedida em cache, a chave de uma instalação vinculada, os arquivos de credenciais por sessão entregues aos mecanismos e o registro de auditoria de consultas. No Linux e no macOS, o bridge o cria com permissões só para o dono (0700, arquivos 0600).
No Windows, o bridge não consegue restringir permissões. O diretório de estado herda a ACL da pasta pai, e o bridge registra um aviso na inicialização para dizer isso. Coloque-o em uma pasta que só a conta de serviço possa ler, por exemplo, um diretório dedicado dentro de %ProgramData% com a herança removida e uma ACL que dá acesso só à conta de serviço, e nunca em um caminho compartilhado, sincronizado ou navegável pelo usuário.
Mecanismos baseados em arquivo
Mecanismos baseados em arquivo ficam desativados por padrão. Uma conexão SQLite ou DuckDB em um perfil aponta para um arquivo no host da ponte. Seus usuários podem então ler esse arquivo, criar novos e, através das próprias funções de arquivo do motor, alcançar outros arquivos que a conta de serviço consiga ler. Por isso a ponte recusa perfis, testes de conexão e tokens de inicialização que envolvam um motor baseado em arquivos com 400 invalid_profile e um problems[] entrada explicando o motivo, a menos que seja executada com --allow-file-engines true. Ative apenas para uma conta de serviço dedicada e travada, e para um diretório que você pretenda que os usuários alcancem. No modo proxy, o mecanismo também proíbe download de extensões do DuckDB e acesso externo (varreduras de arquivos, COPY, ATTACH) para cada instância do DuckDB que abre.
Trilha de auditoria de consultas
A ponte registra cada consulta e edição de linhas executadas em suas sessões: o usuário e o perfil do token de inicialização, a conexão (nome, servidor, mecanismo, banco de dados), o texto SQL, quando começou, como terminou e quanto tempo levou. Solicitações recusadas por problema de licença são registradas como falhas com a mensagem de licença; tudo o que estava em execução quando uma sessão é encerrada é registrado como cancelado. Seu aplicativo lê isso com GET /manage/queries, mais recentes primeiro, filtrados por usuário, perfil, status ou hora.
As mais recentes --query-log-max-entries entradas vivem na memória e em <state-dir>/queries.jsonl (um objeto JSON por linha, gravado com permissão só do dono, compactado automaticamente), para que a trilha sobreviva a reinicializações. O texto SQL fica armazenado no host da ponte em texto puro. Mantenha o diretório de estado tão privado quanto os perfis que ele já contém, e configure --query-log false se a sua política proíbe guardar o texto da consulta.
O próprio log do mecanismo
Cada sqlly-cli o mecanismo escreve um log de correlação de requisição/resposta, incluindo o texto SQL completo de cada requisição, em seu diretório de dados: ~/.local/share/sqlly/sqlly-engine.log (ou $XDG_DATA_HOME/sqlly/sqlly-engine.log) no Linux, ~/Library/Application Support/SQLLY/sqlly-engine.log no macOS, %APPDATA%\SQLLY\sqlly-engine.log no Windows, criado apenas para o proprietário. Senhas, tokens e referências secretas são limpos antes que uma linha seja escrita; ids, servidores, nomes de usuário e SQL são mantidos. Defina SQLLY_ENGINE_LOG=<path> no ambiente do bridge (os motores dele herdam) para mover o log para um lugar que você controla, ou SQLLY_ENGINE_LOG=/dev/null (NUL no Windows) para não manter nada. O log é reduzido às suas últimas linhas apenas quando um mecanismo encerra normalmente.
Configurações do provedor de IA
O mecanismo lê do ambiente a configuração do provedor de IA (SQLLY_LLM_PROVIDER, SQLLY_EMBEDDING_PROVIDER e as variáveis de modelo e de chave relacionadas). Não as defina no host da ponte, a menos que queira que o IntelliSense e os recursos de IA dos seus usuários finais consumam a cota dessa conta.
Flags de segurança
Um perfil only_allow_select (em um cliente, projeto ou etiqueta de ambiente) e uma conexão safety.block_all_but_select são aplicados pelo mecanismo no host da ponte: uma instrução que não seja somente SELECT para o mecanismo da conexão, e toda edição de linha, é recusada com «esta conexão é somente leitura por política» antes de chegar ao banco de dados, independentemente do que o navegador alegar. As outras flags de segurança (diálogos de confirmação, o wrap de rollback, proteção contra UPDATE/DELETE ilimitado) são comportamento do cliente SQLly no navegador do usuário, não um controle do lado do servidor. As permissões do banco de dados continuam sendo o controle real: dê aos logins de proxy apenas o que os usuários deles devem poder fazer.
Dimensionamento
Cada aba SQLly aberta executa uma sqlly-cli processo do mecanismo com suas próprias conexões de banco de dados. A memória segue o que as pessoas fazem: conjuntos de resultados são transmitidos e despejados no disco em vez de mantidos inteiros, mas grandes exportações e muitas abas simultâneas se acumulam. Dimensione o host para o pico de abas simultâneas (assentos × abas por assento, no máximo), e use --max-sessions como uma rede de segurança. Os mecanismos são iniciados sob demanda e saem quando a aba deles fecha.
Operações
- Faça backup do diretório de estado. Ele contém todos os perfis com suas credenciais e a chave de uma instalação vinculada. Trate backups como segredos.
- Acompanhe o log para
embedded license state: toda transição de licença é registrada com o nome do estado. ConsulteGET /manage/statusdo seu monitoramento, e useGET /healthz(sem token) para verificação de atividade. - Mantenha o relógio correto. As concessões devem ser emitidas dentro de 5 minutos do relógio da ponte, então execute o NTP.
- Atualize os dois juntos. Substituir
bin/eweb/da mesma versão do pacote. Reiniciar o bridge fecha as abas abertas, e os usuários se reconectam recarregando. - Rotacionar o token de gerenciamento reiniciando a ponte e seu aplicativo com o novo valor. Tokens de launch já emitidos continuam funcionando até expirarem.
- Mudando de domínios? Altere na sua página Embedded e reinicie a ponte com o novo
--domain. Licenças offline precisam de um arquivo novo, porque o domínio está dentro dele.
Lista de verificação de produção
- TLS na frente do ouvinte do navegador, e
--public-urldefinido para owss://endereço. SQLLY_EMBEDDED_DOMAINdefinido e a licença vinculada a ele;--allow-localhost-origins=false.- API de gerenciamento em loopback ou em uma rede privada; guarde o token apenas em segredos do lado do servidor.
- Tokens de inicialização entregues à página através das
SQLLY_PROXY_URL/SQLLY_PROXY_TOKENglobals, nunca em uma URL da página (?token=acaba no histórico, nos referrers e nos logs do servidor web). --allow-file-enginesse deixa desativado, a menos que se configure para isso uma conta de serviço restrita e um diretório.- Diretório de estado legível apenas pela conta de serviço (somente proprietário no Linux/macOS; uma ACL explícita no Windows);
--query-logeSQLLY_ENGINE_LOGdefinido de acordo com sua política de retenção do texto da consulta. - Não
SQLLY_LLM_PROVIDER/SQLLY_EMBEDDING_PROVIDERno ambiente do bridge, a menos que você queira que o gasto fique por conta dos usuários finais. - Ponte e aplicativo rodando como serviços sob um usuário sem privilégios, reinício em caso de falha, parada graciosa.
- Diretório de estado em armazenamento persistente, somente para o proprietário, com backup.
- A página SQLly e
web/servida com COOP/COEP,application/wasm, e uma CSP que permite a origem da ponte. - HTTPS de saída para sqlly.app permitido (licenças conectadas), NTP ativado.
- Monitoramento ativado
/manage/status: alerta quandolicense.statenão estiverok. - A senha de administrador padrão do aplicativo de exemplo mudou, caso você implante o aplicativo de exemplo. Ele se recusa a escutar fora do loopback até que você faça isso.