Выход в продакшн

TLS, обратные прокси, лицензируемый домен, менеджеры служб, резервные копии, Content-Security-Policy и заголовки изоляции, а также чеклист для развёртывания SQLly Embedded в production.

На localhost настройки по умолчанию просто работают. В продакшне разместите мост за TLS, привяжите лицензию к своему домену, держите API управления приватным и запускайте всё как службы. На этой странице есть настройки, конфигурации и контрольный список для этого.

Рекомендуемая компоновка

  • Один хост или частная сеть для вашего приложения и моста. API управления (127.0.0.1:8445) должен быть доступен только из вашего приложения.
  • Обратный прокси (nginx, Caddy, IIS, облачный балансировщик нагрузки) завершает TLS и пересылает обновления WebSocket по пути вида /sqlly/proxy к слушателю моста --bind прослушиватель.
  • Один и тот же прокси обслуживает ваше приложение, включая страницу SQLly и web/ пакет, так что всё живёт на одном источнике (same-origin) под вашим лицензированным доменом.
  • Мосту требуется исходящий HTTPS на sqlly.app (только подключённые лицензии) и сетевой доступ к вашим базам данных. Браузеры никогда не доходят до баз данных и движка.

Обратный прокси

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;
}
кэдди
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-keySQLLY_EMBEDDED_LICENSE_KEYнетКлюч подключённой лицензии со страницы Embedded.
--license-fileSQLLY_EMBEDDED_LICENSE_FILEнетОфлайн-файл лицензии. Не обращается к sqlly.app. Укажите не более одного из двух — ключа или файла; если не указано ни то ни другое, используется привязанный ключ, иначе мост запустится без лицензии.
--domainSQLLY_EMBEDDED_DOMAINнетПривязывает свободную лицензию при первой регистрации; отказывается запускаться, если лицензия уже привязана в другом месте.
--bindSQLLY_EMBEDDED_BIND0.0.0.0:8444Слушатель WebSocket для браузера (путь /proxy). Используйте loopback за обратным прокси.
--public-urlSQLLY_EMBEDDED_PUBLIC_URLws://localhost:<port>/proxyURL, который используют браузеры, — возвращается с каждым токеном запуска.
--manage-bindSQLLY_EMBEDDED_MANAGE_BIND127.0.0.1:8445Слушатель Management API. Не открывайте его наружу: он содержит учетные данные.
--manage-tokenSQLLY_EMBEDDED_MANAGE_TOKENобязательноBearer-токен для API управления, минимум 16 символов.
--tls-cert, --tls-keySQLLY_EMBEDDED_TLS_CERT, SQLLY_EMBEDDED_TLS_KEYнетРаздача файлов wss:// напрямую. Задайте оба или ни один.
--state-dirSQLLY_EMBEDDED_STATE_DIR./sqlly-embedded-stateПрофили, кэшированный грант, связанный ключ, файлы учётных данных на сессию. Создаются с доступом только для владельца.
--engine-binarySQLLY_CLI_BINрядом с мостом, затем PATHЭтот sqlly-cli мост запускается для каждой сессии.
--max-sessionsSQLLY_EMBEDDED_MAX_SESSIONS64Жесткий предел для одновременных движков на этом хосте.
--allow-localhost-originsSQLLY_EMBEDDED_ALLOW_LOCALHOST_ORIGINStrueРазрешить источники localhost помимо лицензированного домена. Установите false в продакшене.
--token-ttl-secondsSQLLY_EMBEDDED_TOKEN_TTL_SECONDS600Время жизни токена запуска по умолчанию.
--store-urlSQLLY_STORE_URLhttps://sqlly.appКуда отправляются проверки лицензии. Не меняйте вне разработки.
--allow-file-enginesSQLLY_EMBEDDED_ALLOW_FILE_ENGINESfalseПринимать профили с файловыми движками (SQLite, DuckDB). Если выключено, они отклоняются с 400 invalid_profile. См. Файловые движки.
--query-logSQLLY_EMBEDDED_QUERY_LOGtrueВедение журнала аудита запросов (GET /manage/queries, <state-dir>/queries.jsonl). false ничего не записывает. См. Журнал аудита запросов.
--query-log-max-entriesSQLLY_EMBEDDED_QUERY_LOG_MAX_ENTRIES20000Хранятся самые свежие выполненные запросы, в памяти и на диске (минимум 100).

Каталог состояния и хост

Каталог состояния содержит все профили с их паролями, кэшированную лицензию, ключ связанной установки, файлы учётных данных сеансов, передаваемые движкам, и журнал аудита запросов. В Linux и macOS мост создаёт его с доступом только для владельца (0700, файлы 0600).

В Windows мост не может ужесточить права доступа. Каталог состояния наследует ACL своей родительской папки, и мост при запуске пишет об этом предупреждение. Разместите его в папке, которую может читать только учётная запись службы, например в отдельном каталоге внутри %ProgramData% с удалённым наследованием и ACL, дающим доступ только учётной записи службы, и никогда не в общей, синхронизируемой или доступной пользователю папке.

Файловые движки

Файловые движки по умолчанию отключены. Подключение SQLite или DuckDB в профиле указывает файл на хосте моста. Пользователи профиля могут затем читать этот файл, создавать новые и — через файловые функции самого движка — добираться до других файлов, которые может читать служебная учётная запись. Поэтому мост отклоняет профили, проверки соединений и токены запуска, где задействован файловый движок, с 400 invalid_profile и problems[] запись, объясняющая почему, если только она не запускается с --allow-file-engines true. Включайте её только для выделённой, ограниченной учётной записи сервиса и директории, к которой вы планируете предоставить доступ пользователям. В режиме прокси движок дополнительно запрещает загрузку расширений DuckDB и внешний доступ (сканирование файлов, COPY, ATTACH) для каждого экземпляра DuckDB, который он открывает.

Журнал аудита запросов

Мост записывает каждый запрос и каждую правку строк, выполненные его сессиями: пользователь и профиль токена запуска, подключение (имя, сервер, движок, база данных), текст SQL, когда началось, чем закончилось и сколько заняло. Запросы, отклонённые из-за проблем с лицензией, записываются как неудачные с лицензионным сообщением; всё, что выполнялось на момент закрытия сессии, записывается как отменённое. Ваше приложение читает это с помощью GET /manage/queries, сначала новые, фильтруются по пользователю, профилю, статусу или времени.

Самые новые --query-log-max-entries записи находятся в памяти и в <state-dir>/queries.jsonl (по одному 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, с правами доступа только для владельца. Пароли, токены и ссылки на секреты вычищаются перед записью строки; идентификаторы, серверы, имена пользователей и SQL сохраняются. Задайте SQLLY_ENGINE_LOG=<path> в среде моста (движки наследуют её), чтобы перенести журнал туда, где им управляете вы, или SQLLY_ENGINE_LOG=/dev/null (NUL на Windows), чтобы ничего не сохранять. Журнал обрезается до последних строк только при чистом завершении работы движка.

Настройки ИИ-провайдера

Движок подхватывает конфигурацию ИИ-провайдера из своего окружения (SQLLY_LLM_PROVIDER, SQLLY_EMBEDDING_PROVIDER и соответствующие переменные модели и ключа). Не задавайте их на хосте моста, если не хотите, чтобы IntelliSense и AI-функции ваших конечных пользователей расходовали лимит этой учётной записи.

Флаги безопасности

Профиль only_allow_select (на уровне клиента, проекта или метки среды) и safety.block_all_but_select применяются движком на хосте моста: любой оператор, не сводящийся к SELECT для движка этого подключения, и любое редактирование строк отклоняются с сообщением «это подключение доступно только для чтения по политике» ещё до того, как запрос дойдёт до базы данных, — что бы ни утверждал браузер. Остальные флаги безопасности (диалоги подтверждения, обёртка с откатом, защита от неограниченных UPDATE/DELETE) — это поведение клиента SQLly в браузере пользователя, а не серверный контроль. Настоящий контроль — разрешения базы данных: давайте проксируемым логинам только то, что их пользователям можно делать.

Размер

Каждая открытая вкладка SQLly запускает один sqlly-cli процесс движка с собственными подключениями к базе данных. Память следует за тем, что делают пользователи: наборы результатов передаются потоком и сбрасываются на диск, а не держатся в памяти целиком, но большие экспорты и множество одновременных вкладок накапливаются. Подбирайте размер хоста под пиковое число одновременных вкладок (не больше, чем мест × вкладок на место), и используйте --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 управления на loopback или в частной сети; токен храните только в серверных хранилищах секретов.
  • Токены запуска, переданные странице через SQLLY_PROXY_URL / SQLLY_PROXY_TOKEN глобальные, никогда в URL страницы (?token= оказывается в истории, реферерах и журналах веб-сервера).
  • --allow-file-engines оставался выключенным, если для него не были настроены надёжно закрытый служебный аккаунт и каталог.
  • Каталог состояния читается только учетной записью службы (только для владельца на Linux/macOS; явный ACL на Windows); --query-log и SQLLY_ENGINE_LOG задаётся согласно вашей политике хранения текста запросов.
  • Нет SQLLY_LLM_PROVIDER / SQLLY_EMBEDDING_PROVIDER в среде моста, если только конечные пользователи не должны управлять этими расходами.
  • Мост и приложение работают как службы под непривилегированным пользователем, перезапуск при сбое, корректная остановка.
  • Директория состояния на постоянном хранилище, только для владельца, с резервным копированием.
  • Страница SQLly и web/ обслуживается с COOP/COEP, application/wasm, и CSP, разрешающий источник моста.
  • Разрешён исходящий HTTPS к sqlly.app (для лицензий с подключением), NTP включён.
  • Мониторинг включен /manage/status: оповещение, когда license.state нет. ok.
  • Дефолтный пароль администратора демо-приложения сменился — если вы вообще разворачиваете демо-приложение. Оно отказывается слушать что-либо вне loopback, пока вы его не смените.