Переменные окружения

Большинство настроек читает apps/api/src/env.ts; журнальные — lib/log-buffer.ts и lib/retention.ts, а адрес API для серверной отрисовки лендинга — apps/web/src/lib/api.ts. При запуске из исходников он подхватывает корневой .env через dotenv; в контейнере переменные приходят из docker-compose.yml и .env рядом с ним. Образец со всеми ключами — .env.example.

Обязательных переменных две. Остальные имеют значения по умолчанию, и в .env.example они выписаны только для наглядности.

Обязательные

Пустое или отсутствующее значение — это не предупреждение, а остановка на старте с текстом «Не задана переменная окружения …. Скопируйте .env.example в .env».

Про JWT_SECRET

Это не только ключ подписи сессий. Тем же секретом считается HMAC-SHA256 от ключа API: в базе лежит хеш, а не ключ, и поиск ключа при запросе к шлюзу идёт по этому хешу.

Отсюда два следствия, о которых лучше знать заранее:

• Смена секрета обесценивает все выданные ключи. Хеши в базе перестают совпадать с хешами тех же ключей, и шлюз отвечает как на неизвестный ключ. Ключи придётся выпустить заново.
• Смена секрета гасит все сессии кабинета. Сессия живёт две недели, но подпись проверяется на каждом запросе.

Поэтому секрет задаётся один раз, при первом развёртывании, и хранится там же, где остальные секреты:

JWT_SECRET=$(openssl rand -base64 32)

Сеть и адреса

NEXT_PUBLIC_API_URL в контейнере задаётся аргументом сборки, а не переменной рантайма: значение вкомпилировано в клиентский бандл. Поменяли адрес — пересоберите образ.

APISTEND_PUBLIC_ORIGIN на HTTPS-адресе важен отдельно: из него строится схема туннеля, и http:// даст CLI ws:// вместо wss://.

База и журнал запросов

Пул больше не значит быстрее: PostgreSQL держит процесс на каждое соединение. Горячий путь шлюза до базы вообще не доходит — ключи лежат в LRU-кеше, логи пишутся пачками.

Management API

Это защита самого APIStend, а не эмуляция лимитов боевого сервиса: 240 в минуту — четыре запроса в секунду. У тяжёлых операций отдельный, более жёсткий счётчик.

Потолок на песочницы стоит рядом с лимитом частоты по той же причине: у каждой песочницы свои ключи, наложения демо-данных и журнал, и скрипт с правом sandboxes:write завёл бы их сотнями, не выйдя за обычную норму запросов.

Серии событий

Запрос выше потолка не отклоняется, а обрезается — и об этом сообщается в ответе. Молчаливое усечение читалось бы как «сделано, как просили».

Доставка вебхуков

Почему это отдельная настройка

Публичную доставку выполняет сервер APIStend, то есть запрос по адресу из песочницы он делает от своего имени. Без проверки любой пользователь общего стенда мог бы заставить его сходить во внутреннюю сеть — включая 169.254.169.254 и прочие адреса метаданных, — а серия событий превращает это ещё и в усилитель нагрузки.

Значение читается так:

Запрещённый адрес не приводит к молчаливой потере события: получатель отклоняется с текстом вида «Адрес 127.0.0.1 внутренний. Для доставки на свою машину используйте локальный получатель и apistend listen».

Проверка не ограничивается литералом адреса: имя резолвится, и домен, указывающий на приватный диапазон, тоже отклоняется. Что она не ловит — перепривязку DNS между проверкой и запросом; ограничение известное и записано в коде, а не забыто.

Прочее

APISTEND_SEED читает точка входа контейнера. При запуске из исходников сид зовётся руками — pnpm db:seed, — и он пересоздаёт демо-аккаунт всегда, а не только на пустой базе.