CLI и конфигурация

Переменные окружения, пути хранения и настройки безопасности API.

У Traffic Jam нет файла конфигурации. Go-бэкенд читает переменные окружения при старте, Electron-оболочка выставляет их сама, а веб-фронтенд подхватывает одну переменную времени сборки. На этой странице перечислены все настройки, указано, где данные лежат на диске и как защищён локальный API.

Запуск dev-стека

npm run dev:api    # go run ./server — backend on 127.0.0.1:8790
npm run dev:web    # Vite dev server, proxies /api to http://127.0.0.1:8790
npm run desktop:dev # build frontend + macOS arm64 backend, launch Electron

Предварительные требования описаны в /docs/ru/getting-started/installation/ (mitmdump нужен для live-захвата, tshark — только для live-захвата пакетов; для импорта pcap/pcapng/HAR не требуется ни то ни другое).

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

Переменные бэкенда, читаются один раз при старте процесса:

Переменная	По умолчанию	Действие
`TRAFFIC_JAM_ADDR`	`127.0.0.1:8790`	Адрес прослушивания API.
`TRAFFIC_JAM_DB_PATH`	`.traffic-jam/traffic-jam-v2.sqlite3`	Файл базы данных SQLite (сессии, исследования, decode-скрипты, профили).
`TRAFFIC_JAM_CAPTURE_DIR`	`.traffic-jam/live-captures`	Каталог артефактов live-захвата. Если не задана, но задана `TRAFFIC_JAM_DB_PATH`, по умолчанию используется `live-captures` рядом с файлом базы данных.
`TRAFFIC_JAM_API_TOKEN`	(пусто)	Capability-токен. Пусто = токен не требуется; задан = каждый запрос должен его содержать (см. ниже).
`TRAFFIC_JAM_ALLOWED_ORIGINS`	(пусто)	Список дополнительных точных значений браузерного `Origin` через запятую, которые следует принимать.
`TRAFFIC_JAM_MAX_UPLOAD_BYTES`	`4294967296` (4 GiB)	Максимальный размер загружаемого захвата в байтах.

Переменные фронтенда и десктопа:

Переменная	Где	Действие
`VITE_TRAFFIC_JAM_API_TOKEN`	Сборка/dev Vite	Capability-токен, который отправляет веб-клиент при отсутствии десктопного моста.
`TRAFFIC_JAM_USER_DATA_DIR`	Electron	Переопределяет каталог пользовательских данных (используется smoke-тестом Electron для изоляции).
`TRAFFIC_JAM_DEBUG_MENU`	Electron	`1` добавляет в меню упакованного приложения пункты Inspect Element / DevTools.

Пример — dev-сессия с защитой токеном:

TRAFFIC_JAM_API_TOKEN=s3cret npm run dev:api
VITE_TRAFFIC_JAM_API_TOKEN=s3cret npm run dev:web

Пути хранения

Расположение	Содержимое
`.traffic-jam/traffic-jam-v2.sqlite3`	База данных dev-сервера (относительно рабочего каталога бэкенда).
`.traffic-jam/live-captures/`	Артефакты live-захвата (см. /docs/ru/capture/live-capture/).
`<userData>/traffic-jam-v2.sqlite3`	Десктопная база данных в каталоге пользовательских данных Electron; артефакты live-захвата хранятся рядом с ней. Открыть можно через Capture → Open Traffic Jam Data Folder.

Разобранные сессии захвата сохраняются в SQLite, поэтому импортированные сессии переживают перезапуски API.

Модель безопасности API

Каждый запрос /api/* проходит один middleware, выполняющий две независимые проверки.

Allowlist origin. Запрос с заголовком Origin принимается, только если origin:

точно совпадает с одной из записей в TRAFFIC_JAM_ALLOWED_ORIGINS;
является десктопным origin traffic-jam://app; либо
является http/https origin, чей хост — localhost или loopback-IP (127.0.0.1, ::1).

Любой другой origin отклоняется с HTTP 403 origin is not allowed. Запросы без заголовка Origin (curl, Go-клиенты) эту проверку пропускают.

Capability-токен. Если TRAFFIC_JAM_API_TOKEN задана, запрос должен содержать то же значение в заголовке X-Traffic-Jam-Token, сравнение выполняется за константное время; отсутствующий или неверный токен приводит к HTTP 401 invalid API capability token. Если переменная пуста, токен не требуется.

curl -H "X-Traffic-Jam-Token: $TOKEN" http://127.0.0.1:8790/api/health

Веб-клиент отправляет токен автоматически (из десктопного моста, с фолбэком на VITE_TRAFFIC_JAM_API_TOKEN).

[!WARNING] Dev-API без токена по-прежнему доверяет любому процессу на вашей машине, способному достучаться до loopback. Задавайте TRAFFIC_JAM_API_TOKEN, когда бэкенд работает рядом с недоверенным локальным ПО, и никогда не привязывайте TRAFFIC_JAM_ADDR к нелокалхостному интерфейсу.

Отличия dev от десктопа

	Dev (`npm run dev:api`)	Десктоп (Electron)
Порт	фиксированный `127.0.0.1:8790`	свободный порт `127.0.0.1`, выбирается при запуске
Токен	отсутствует, если вы не задали `TRAFFIC_JAM_API_TOKEN`	32-байтный криптографически случайный токен, генерируется при каждом запуске
Доставка токена	`VITE_TRAFFIC_JAM_API_TOKEN` во время сборки	передаётся рендереру только через изолированный preload-мост (`contextIsolation: true`, `nodeIntegration: false`)
База данных	`.traffic-jam/traffic-jam-v2.sqlite3`	`<userData>/traffic-jam-v2.sqlite3`
Фронтенд	Vite dev server	отдаётся с `traffic-jam://app`
`PATH`	из вашего shell	дополняется `PATH` вашего login shell, а также каталогами Homebrew и пользовательских бинарников (`/opt/homebrew/bin`, `~/.local/bin`, `~/go/bin`, …), чтобы `mitmdump`, `tshark`, `adb` и `frida` находились при запуске из GUI

Проверки и тесты

Команда	Что запускает
`npm run lint`	ESLint по коду фронтенда и Electron.
`npm test`	Тесты логики (Vitest, окружение Node).
`npm run test:ui`	Тесты React Testing Library + доступности (axe) в jsdom.
`npm run test:e2e`	Smoke-тест Playwright Chromium на `testdata/browser-smoke.har`; использует временную базу данных SQLite и каталог захватов.
`npm run test:electron`	Собирает фронтенд + бэкенд, запускает Electron с изолированным каталогом пользовательских данных.
`go test ./server/...`	Модульные тесты бэкенда.
`make check`	`lint` + `npm test` + `go test ./server/...`.
`make check-ui`	`make check` + тесты отрисованного UI.

[!NOTE] Браузерным тестам один раз нужен Chromium: npx playwright install chromium. И e2e-, и Electron-тесты направляют базу данных, каталог захватов и каталог пользовательских данных во временные пути, так что ваше обычное состояние разработчика они не затрагивают.

Replay, лимиты батчей и request workbench описаны в /docs/ru/replay/workbench/; плагины decode-скриптов — в /docs/ru/collector/decode-scripts/.