Как это работает
Теория работы: мост, движок на каждый сеанс, токены запуска, подписанный грант лицензии, чек-ины, места, правило Origin и где хранятся учётные данные.
SQLly Embedded разделяет SQLly на две половины — ту, которой нужны секреты, и ту, которой не нужны. Интерфейс SQLly работает в браузере пользователя как WebAssembly. Всё, что обращается к базе данных, выполняется на вашем сервере, внутри моста SQLly и запускаемых им движков. Ваше веб-приложение работает рядом с мостом и сообщает ему, кто и с какими подключениями может открыть SQLly. На этой странице разобран каждый узел этой конструкции и то, почему она устроена именно так.
Архитектура
Зачем такое разделение
- Секреты остаются на сервере. Браузер не может скрыть пароль базы данных от собственного пользователя. Поэтому браузер его никогда не получает. Он получает список подключений, отправляет фреймы запросов, а мост выполняет их с учетными данными, которые есть только у сервера.
- Ваше приложение само отвечает за идентификацию. У моста нет пользовательских учётных записей. Ваше приложение и так знает, кто вошёл. Оно говорит мосту «открыть SQLly для этого пользователя с этого профилем" путем создания токена запуска, и мост доверяет этому токену.
- Один движок на сессию. Каждая вкладка браузера получает свой собственный
sqlly-cliпроцесс, поэтому сеансы никогда не используют общее состояние соединений, транзакции или временные таблицы, и сбой влияет на одну вкладку, а не на мост.
Внутри моста
sqlly-bridge embedded — это один процесс с тремя задачами:
| Задание | Прослушивает | Взаимодействует с |
|---|---|---|
| Браузерный прокси: принимает WebSocket для каждой вкладки SQLly, проверяет её Origin и токен запуска, запускает движок с профилем из токена и ретранслирует кадры в обоих направлениях. | --bind, по умолчанию 0.0.0.0:8444, путь /proxy | Браузеры (поставьте TLS впереди) |
| API управления: профили, токены запуска, рабочие места, проверки соединения, статус лицензии и журнал аудита запросов. Справочник. | --manage-bind, по умолчанию 127.0.0.1:8445 | Только серверная часть вашего приложения, с токеном Bearer |
| Монитор лицензий: связывается с sqlly.app при запуске и каждые 20 минут (когда есть сеть) или перечитывает файл лицензии каждую минуту (офлайн), а также переводит мост между состояниями лицензии. | Ничего | sqlly.app через HTTPS (только при подключении) |
Его директория состояния (--state-dir, создаваемая с правами только для владельца на Linux и macOS) хранит каждый профиль в виде profiles/<id>.json, последнюю действующую лицензию (license.json), ключ связанной установки (license-key, режим 0600), файлы учётных данных сессий, которые он передаёт своим движкам, и журнал аудита запросов (queries.jsonl: каждый запрос, выполненный в сессии, с его SQL-текстом). Сделайте резервную копию и храните его так же конфиденциально, как файл с паролями, потому что он таковым и является. Куда его поместить и что нужно Windows.
Профили: что видит пользователь
A профиль — это именованный документ учётных данных SQLly: тот же формат JSON, который настольное приложение SQLly импортирует и экспортирует. В нём перечислены подключения (сервер, база данных, движок, аутентификация, TLS, правила безопасности) и метки клиента, проекта и окружения, которые окрашивают и группируют их. Ваше приложение хранит профили в PUT /manage/profiles/{id}. Мост проверяет весь документ заранее и сообщает обо всех проблемах одновременно, поэтому опечатка вроде "pasword" приводит к явной ошибке, а не игнорируется.
Пользователи не привязаны к профилям в мосте — профиль задаётся при каждом запуске. Дайте аналитикам профиль только для чтения (метка с only_allow_select, или block_all_but_select в подключении: движок не пропускает ничего, кроме SELECT, прежде чем запрос попадёт в базу данных), а сотрудникам поддержки — другой, или создайте по одному профилю на клиента в многопользовательском приложении. Файловые движки (SQLite, DuckDB) отклоняются, если мост не запущен с --allow-file-engines, потому что они дают пользователям доступ к файлам на хосте моста. Чтобы выдать кому-то меньше подключений, создайте другой профиль. Когда сессия открывается, браузер получает из профиля в каталоге: имена соединений, движки, базы данных и метки, при этом все секреты удалены. Редактирование профиля применяется к следующему запуску. Уже открытые сессии сохраняют каталог, с которым они начали.
Жизненный цикл сессии
- Вошедший в систему пользователь открывает страницу SQLly в вашем приложении.
- Ваш сервер вызывает
POST /manage/tokensс вашим идентификатором пользователя и профилем, который он должен получить, а также (опционально) что открыть: вкладки запросов со скриптом, подключением, значениями параметров и курсором (контекст запуска). - Мост проверяет лицензию и число мест, снимает профиль и возвращает случайный токен, срок его действия и публичный URL прокси.
- Ваш сервер возвращает страницу SQLly (
web/index.html) с двумя глобальными переменными, заданными заранееboot.js:SQLLY_PROXY_URLиSQLLY_PROXY_TOKEN. - SQLly открывается
wss://…/proxy?token=…. Мост проверяет по порядку: сначала заголовокOrigin(отказ при обновлении с кодом 403), токен, лицензия, открытые сессии пользователя и собственный лимит сессий. Браузер не может узнать, почему обновление не удалось, поэтому каждый отказ после проверки источника доставляется через открытый сокет какerrorсообщение с причиной, за которым следует код закрытия4000 + HTTP status(4401 неизвестный или просроченный токен, 4503 недействительная лицензия, 4429 лимит сессий); SQLly показывает само сообщение. - Мост записывает учётные данные профиля в отдельный приватный файл сессии и запускает
sqlly-cliв режиме движка с ним. - Браузер получает приветствие с каталогом подключений без секретов и текущим состоянием лицензии. Первая сессия токена, выпущенного с контекстом запуска, также получает вкладки для открытия; SQLly загружает их, но ничего не выполняет.
- С этого момента запросы SQLly (подключение, выполнение, отмена, получение метаданных для IntelliSense, пролистывание результатов) передаются в виде бинарных фреймов. Мост пересылает их движку, фиксирует каждый запрос и изменение строки в своём журнал аудита, и отказывает в них с сообщением, если лицензия становится недействительной.
Места и сессии
A место — это отдельный id пользователя, у которого открыт сеанс или не истёк токен запуска. Места считаются по одновременному использованию, а не поимённо: как только у пользователя закрывается последняя вкладка и истекает последний токен, место освобождается, и его может занять кто-то другой. Bridge считает места по всем мостам лицензии, потому что sqlly.app при каждой регистрации сообщает пользователей с других экземпляров.
- Создание токена для пользователя, который уже занимает место, всегда удается. Создание токена для нового пользователя, когда все места заняты, завершается неудачей с
409 seat_limit, поэтому ваше приложение может показать понятное сообщение. - Каждое место допускает
sessionsPerSeatоткрытых вкладок: четыре на платных тарифах, одна на пробном. Лишняя вкладка получает отказ и закрывается (код 4429). Мост пингует каждую вкладку и сбрасывает ту, что молчит 90 секунд, — так вкладка, потерянная из-за уснувшего ноутбука, сама освобождает свою сессию; когда у пользователя закрывается последняя вкладка, его токены запуска истекают в течение двух минут. DELETE /manage/seats/{user}отзывает токены пользователя и закрывает его сессии. Вызывайте это, когда кто-то выходит из вашего приложения или теряет доступ.- ID пользователя — это то, что вы передадите. Используйте стабильный непрозрачный идентификатор (ключ базы данных или хеш), если не хотите отправлять адреса электронной почты: идентификаторы, занимающие места, передаются на sqlly.app, чтобы места можно было считать по всем мостам.
Кто может подключаться: правило Origin
Каждая лицензия привязана к одному домену. Мост принимает WebSocket браузера только тогда, когда его Origin заголовок соответствует этому домену или любому его поддомену (любая глубина, схема или порт), или localhost / 127.0.0.1 / [::1] в то время как --allow-localhost-origins включён (по умолчанию, для разработки). Лицензия без привязанного домена допускает только localhost. Привяжите домен на вашей странице Embeddedили запустите мост один раз с --domain.
API управления вообще не отправляет заголовков CORS. Это обмен между серверами: браузер с другого источника не может его вызвать, да и привязывать его в любом случае нужно к loopback.
Как применяется лицензия
Мост доверяет одной вещи: лицензионный грант, компактный JWS, который sqlly.app подписывает с помощью ES384 (ECDSA P-384). Ключ проверки встроен в мост. Каждое разрешение (места, сеансы на место, экземпляры моста, домен, конец периода, льготные дни, функции) читается из подписанных утверждений (claims) гранта. Неподписанный JSON вокруг него предназначен только для отображения.
Подключенные лицензии
- При запуске и каждые 20 минут мост отправляет
POST /api/embedded/checkinсо своим лицензионным ключом, идентификатором экземпляра, новым 32-байтовым нонсом, версией и именем хоста, доменом, для которого он был запущен, и идентификаторами пользователей, которые в данный момент занимают места. - Грант в ответе должен проходить проверку по вкомпилированному ключу, возвращать тот же nonce, называть этот экземпляр и ту же лицензию и быть выданным в пределах 5 минут по часам моста. Повторенный или подделанный ответ эти проверки не проходит и считается неудачной проверкой связи. Следите, чтобы часы на хосте были точны (NTP).
- Грант действует 40 минут. Если до sqlly.app не удается добраться, мост продолжает обслуживать на основе последнего действительного гранта до его окончания, а затем прекращает работу устаревший и отказывается работать до следующей успешной проверки связи — без перезапуска. Мост, перезапущенный во время простоя, стартует с кэшированным грантом, только пока тот не истёк.
- Каждая подключённая лицензия допускает несколько экземпляры одновременно (по умолчанию один). Второй мост с тем же ключом регистрируется, но не допускается, пока первый продолжает отзываться. Мост, завершившийся штатно, освобождает свой слот сразу; аварийно упавший — только через 40 минут.
Офлайн-лицензии
Офлайн-лицензия — это файл ({ "format": "sqlly-embedded-license", "version": 1, "token": "<grant>" }), который вы скачиваете с sqlly.app после настройки его домена. Внутренняя лицензия действует долго: срок истекает в конце периода плюс льготные дни. Мост проверяет её локально, никогда не связывается с сервером SQLly и перечитывает файл каждую минуту, поэтому продление — это замена файла. У офлайн-лицензий нет ограничения на количество экземпляров.
Привязанные установки
Мост, запущенный без ключа и без файла, является нелицензированного: API управления работает (можно настроить и проверить профили), но запуски отклоняются. Затем ваше админ-приложение может привязать мост, чтобы никому не пришлось копировать ключ: оно запрашивает у sqlly.app код привязки, владелец лицензии одобряет его в своём браузере, а приложение получает ключ, выпущенный только для этой установки, и передаёт его мосту с PUT /manage/license. Мост проверяет его, сохраняет и продолжает использовать при перезапусках. Каждая связанная установка имеет свой собственный ключ, поэтому владелец может отозвать один, не затрагивая другие. Как его собрать.
Когда лицензия недействительна
В каждом состоянии, кроме ok и grace, мост держит открытые сокеты подключёнными, но отвечает на каждый фрейм запроса ошибкой с понятной фразой («…не удалось подтвердить лицензию на sqlly.app в течение 40 минут; попросите администратора разобраться.»). Клиент SQLly показывает эту фразу в строке состояния и в виде уведомления, чтобы пользователи знали причину. Новым сессиям сообщается та же фраза, и они закрываются (код 4503), а токены запуска отклоняются с 503 license_not_ok. В течение 15-дневного льготного периода после окончания срока всё работает, но каждый пользователь видит обратный отсчёт. Каждое состояние — с объяснением.
Что покидает ваш сервер
| Отправляется на sqlly.app при регистрации | Никуда не отправляется |
|---|---|
| Лицензионный ключ · идентификатор экземпляра моста · версия моста · имя хоста · запрашиваемый домен · идентификаторы пользователей, занимающих места · количество открытых сессий | Запросы · результаты · имена баз данных и хосты · учетные данные · профили · все, что печатают ваши пользователи |
Офлайн-лицензии ничего не отправляют. Браузер общается только с вашим приложением и вашим мостом.