> Markdown-версия страницы https://tuna.am/docs/tunnels/inspect/. Оглавление документации — [llms.txt](https://tuna.am/llms.txt), весь текст одним файлом — [llms-full.txt](https://tuna.am/llms-full.txt). Markdown-версия есть у любой страницы: добавьте `.md` к адресу без слеша на конце. # Инспектор ## Обзор Инспектор показывает в браузере всё, что прошло через туннель: HTTP-запросы с заголовками и телами, SQL-запросы и команды Redis по сессиям. Запрос можно повторить, в том числе с правками, а ИИ-агент читает те же данные через API. Инспектор есть у туннелей: | Команда | По умолчанию | Что видно | | --------------------------------------------------------------- | ------------ | ---------------------------- | | [`tuna http`](https://tuna.am/docs/tunnels/http.md) | включён | HTTP-запросы и ответы | | [`tuna 1c`](https://tuna.am/docs/tunnels/1c.md) | включён | запросы к публикации 1С | | [`tuna kubernetes`](https://tuna.am/docs/tunnels/kubernetes.md) | включён | запросы гостя к API кластера | | [`tuna postgres`](https://tuna.am/docs/tunnels/postgres.md) | всегда | сессии и SQL-запросы | | [`tuna mysql`](https://tuna.am/docs/tunnels/mysql.md) | всегда | сессии и SQL-запросы | | [`tuna redis`](https://tuna.am/docs/tunnels/redis.md) | всегда | сессии и команды | CLI пишет адрес инспектора в лог строкой `Web Interface: http://127.0.0.1:4040` и показывает в шапке [интерфейса в терминале](https://tuna.am/docs/tunnels/tui.md). Клавиша `i` открывает его в браузере. Последние запросы видны и в самом терминале: ![Инспектор: список запросов слева, справа — вебхук Stripe с JSON-телом](/docs/img/inspect/http-webhook.webp) ## Запуск и порт Первый туннель занимает `127.0.0.1:4040`, следующие — 4041, 4042 и дальше. Порт 4045 пропускается: браузеры его блокируют. Чтобы адрес не зависел от порядка запуска, задайте порт явно: ```shell tuna http 8080 --inspect-port=4100 TUNA_INSPECT_PORT=4100 tuna http 8080 ``` Если явно заданный порт занят, туннель не запустится и назовёт в ошибке, кто его занял: ```text inspector port 4100 is used by tuna http (pid 81234, https://acme-shop.a.2na.am). Set another --inspect-port or unset TUNA_INSPECT_PORT ``` ### Выключение У `tuna http`, `tuna 1c` и `tuna kubernetes` инспектор выключается флагом `--inspect=false` или переменной `TUNA_INSPECT=false`. У баз данных он включён всегда; если он не нужен, используйте [TCP туннель](https://tuna.am/docs/tunnels/tcp.md). Инспектор хранит в памяти до 2048 записей, но не больше 256 МБ: старые записи вытесняются новыми. Очистить историю можно в разделе «Настройки». На серверах и встраиваемых устройствах (IP-KVM, Raspberry Pi) его лучше выключать. В [сервисе](https://tuna.am/docs/tunnels/guides/service.md) он выключен по умолчанию, включается явным `--inspect`. ### Несколько туннелей В [`tuna start`](https://tuna.am/docs/tunnels/guides/multi-tunnels.md) каждый туннель берёт следующий свободный порт. Фиксированный порт задаётся в `commandLine`: ```yaml tunnels: web: commandLine: tuna http 5173 --subdomain=web --inspect-port=4100 api: commandLine: tuna http 8080 --subdomain=api --inspect-port=4101 ``` `TUNA_INSPECT_PORT` при запуске нескольких туннелей задаёт начало диапазона: первый туннель получит этот порт, остальные — следующие. ### Доступ из сети По умолчанию инспектор слушает только `127.0.0.1`. Открыть его для других машин можно переменной `TUNA_INSPECT_ADDR`: ```shell TUNA_INSPECT_ADDR=0.0.0.0 tuna http 8080 ``` > **Инспектор без авторизации.** Любой, кто достучится до адреса инспектора, прочитает и повторит запросы: токены, cookie и тела в нём не маскируются. При адресе не на loopback CLI пишет предупреждение в лог, а инспектор показывает баннер. Порт в `TUNA_INSPECT_ADDR` (`0.0.0.0:4100`) пока работает, но устарел — используйте `--inspect-port`. Ключ `inspectAddr` в [конфигурационном файле](https://tuna.am/docs/guides/config-file.md) больше не читается: CLI предупредит о нём в логе. ### Docker В Docker-образе `yuccastream/tuna` инспектор `tuna http`, `tuna 1c` и `tuna kubernetes` выключен. Включить — флагом `--inspect` или переменной `TUNA_INSPECT=true`, а чтобы открыть его снаружи контейнера, нужен ещё `TUNA_INSPECT_ADDR=0.0.0.0` и проброшенный порт: ```yaml services: tuna: image: yuccastream/tuna:latest command: http app:8080 ports: - "127.0.0.1:4040:4040" environment: TUNA_API_KEY: tak_*** TUNA_INSPECT: "true" TUNA_INSPECT_ADDR: 0.0.0.0 ``` > **Изменение.** Раньше в Docker хватало `TUNA_INSPECT_ADDR`. Теперь без `TUNA_INSPECT=true` инспектор не запустится. ## HTTP Список запросов и детали занимают всю высоту окна, границу между ними можно перетащить. На широком мониторе запрос и ответ стоят в две колонки, на ноутбуке между ними переключатель «Запрос / Ответ». ![Инспектор на широком мониторе: запрос и ответ в две колонки](/docs/img/inspect/http-wide-webhook.webp) На телефоне список и детали открываются отдельными экранами. ![Список запросов на телефоне](/docs/img/inspect/http-mobile-list.webp)![Детали запроса на телефоне](/docs/img/inspect/http-mobile-detail.webp) ### Детали запроса Заголовки, параметры строки запроса и cookie разнесены по вкладкам «Заголовки», «Параметры» и «Печенье». JSON-тело подсвечивается и сворачивается, формы показываются таблицей, режим «Сырой» показывает запрос как есть. Из значения заголовка открываются инструменты: «Разобрать JWT», «Как время», «Декодировать Base64». Значение передаётся в инструмент напрямую, в адрес страницы токен не попадает. ![Заголовки запроса с меню действий над значением](/docs/img/inspect/http-headers.webp) ### Фильтры В строку поиска можно ввести путь или фильтр-токен: `method:POST`, `status:500`, заголовок, IP, кто ответил, сработавшее правило. Клик по статусу, методу или пути в деталях добавляет фильтр, с Alt — исключает. Оператор токена меняется кликом. ![Фильтры-токены в строке поиска](/docs/img/inspect/http-filter-tokens.webp) ### Отклонённые запросы Запрос, который отбили `--basic-auth`, `--key-auth`, `--cidr-allow`, `--cidr-deny`, [политика трафика](https://tuna.am/docs/traffic-policy.md) или проверка подписи вебхука, тоже попадает в инспектор. В списке у него метка «Политика», в деталях — кто ответил вместо приложения и какие правила сработали. ![Запрос отклонён политикой трафика: до приложения не дошёл, сработало правило deny](/docs/img/inspect/http-rejected-policy.webp) Сработавшие правила политики видны у каждого запроса. В разделе «Настройки» — правила с номерами и счётчиками срабатываний, вкладка с YAML и ссылка на отладчик политик. ![Настройки: правила политики трафика со счётчиками срабатываний](/docs/img/inspect/http-settings.webp) ### Повтор запроса «Повторить» отправляет запрос через публичный адрес туннеля ещё раз. Тело уходит байт в байт, поэтому подпись вебхука на повторе сходится. «Изменить» открывает редактор на месте запроса: метод, путь, заголовки таблицей и тело, рядом — исходный ответ. ![Редактор повтора: метод, путь, заголовки и тело, рядом исходный ответ](/docs/img/inspect/http-replay-editor.webp) ## Базы данных У `tuna postgres`, `tuna mysql` и `tuna redis` инспектор показывает сессии: пользователь и база, первый запрос, время начала, число событий и ошибок, открыта сессия или закрыта. Поиск идёт по пользователю, базе и тексту запросов, список можно свернуть. В логе сессии у каждого запроса длительность и результат, ошибки с кодом. Транзакции отмечены полосой, откат — красной. Вкладки «Ошибки» и «Медленные» фильтруют лог. Рядом с командой — ссылка на её документацию, рядом с ошибкой — на описание кода. ![Сессия Postgres: ошибка 42P01 со ссылкой на описание кода](/docs/img/inspect/pg-error.webp) Очистка истории удаляет только закрытые сессии. ### PostgreSQL Результат показывается командным тегом и числом строк (`UPDATE 1`). У prepared statements виден текст запроса и параметры `$1`, `$2`. ![Prepared statement в Postgres: текст запроса и значения параметров](/docs/img/inspect/pg-params.webp) ### MySQL Видны запросы, транзакции и `PREPARE`/`EXECUTE`. Ответы сервера инспектор не разбирает, поэтому числа строк и ошибок у MySQL нет. ![Сессия MySQL с транзакцией](/docs/img/inspect/my-transaction.webp) ### Redis Номер базы виден в имени сессии: после `SELECT 1` она становится `default@db1`. Аргументы с пробелами и бинарные значения показываются в кавычках, как в `redis-cli`. `MULTI`/`EXEC` отмечены полосой, как транзакции. ![Сессия Redis: бинарное значение в кавычках, как в redis-cli](/docs/img/inspect/rd-binary.webp) Через туннель работают RESP3 (`HELLO 3`, `redis-cli -3`), inline-команды (`PING` из `nc` или `telnet`) и `redis-cli --pipe`. ## ИИ-агенты Claude Code, Cursor и другие агенты читают инспектор через HTTP API. Инструкция для агента лежит по адресу `http://127.0.0.1:4040/llms.txt`: в ней живые адреса и готовые команды `curl`. Отдельная команда CLI не нужна — дайте агенту ссылку на `llms.txt`. ![llms.txt инспектора: рецепты curl и описание API](/docs/img/inspect/http-llms.webp) Основные запросы: ```shell I=http://127.0.0.1:4040 curl -s "$I/v1/events?status=5xx&since=15m" # что упало за 15 минут curl -s "$I/v1/events?path=~hook&wait=60s" # дождаться следующего вебхука curl -s "$I/v1/events/.md" # событие в Markdown curl -s "$I/v1/events/.curl" # команда curl для повтора curl -s -X POST "$I/v1/events//replay" # повторить через туннель curl -s "$I/v1/events?errors=true" # ошибки в базе curl -s "$I/v1/events?min_duration=200ms" # медленные запросы ``` | Метод | Что возвращает | | ----------------------------- | ------------------------------------------------------------------- | | `GET /v1/info` | адрес туннеля, состояние, политика, счётчики истории | | `GET /v1/events` | список событий, новые сверху | | `GET /v1/events/{id}` | событие целиком в JSON, `.md` — в Markdown, `.curl` — команда curl | | `POST /v1/events/{id}/replay` | повтор запроса, в теле можно поменять метод, путь, заголовки и тело | | `GET /v1/sessions` | сессии баз данных | Фильтры `GET /v1/events`: `status`, `method`, `path`, `header`, `remote_addr`, `answered_by`, `rule`, `session`, `q` (текст), `errors=true`, `min_duration`, `since` и `until`, курсор `before` и `after`, `limit`, `format=jsonl`. Префикс `!` исключает значение, `~` ищет подстроку: `status=!200`, `path=~hook`. `wait=60s` (до 5 минут) держит запрос, пока не придёт подходящее событие. Так агент ждёт вебхук, не опрашивая инспектор в цикле. Без `after`, `before` и `since` ждёт только новые события. Кнопка «Скопировать для ИИ» в деталях запроса копирует ссылку на событие и на `llms.txt`. По ссылке `/events/{id}` человек увидит экран инспектора, а агент получит Markdown. > **Данные уходят к провайдеру модели.** Инспектор ничего не маскирует. Токены, cookie, тела и параметры запросов попадут в контекст агента и к провайдеру модели. Инспектор предупреждает об этом при копировании, а `llms.txt` просит агента не повторять секреты в ответах. С боевыми данными будьте осторожны. ![Предупреждение при копировании события для ИИ-агента](/docs/img/inspect/http-copy-for-agent.webp) ## Инструменты В разделе «Инструменты» собраны утилиты разработчика. Все работают локально, данные никуда не отправляются. ![Раздел «Инструменты» инспектора](/docs/img/inspect/http-tools.webp) * URL Encode/Decode; * Base64; * JWT с проверкой подписи ключом; * хэш и HMAC; * форматирование JSON; * конвертер JSON, YAML, CSV и ENV; * Query-параметры в JSON; * время и Unix timestamp; * системы счисления; * UUID v4, v7 и KSUID; * Regex с движками JavaScript и Go — Go тот же, что у `matches` в [политиках трафика](https://tuna.am/docs/traffic-policy.md); * Lorem Ipsum; * цвета; * единицы CSS и CSS в инлайн-стили; * изменение размера изображений. *Не нашли нужный инструмент — [напишите нам](mailto:info@tuna.am).* ## Тема, язык и QR-код Тёмная тема и английский язык переключаются в меню профиля. Там же имя и email аккаунта и ссылка в личный кабинет. ![Инспектор в тёмной теме](/docs/img/inspect/http-dark-webhook.webp) Иконка QR-кода рядом с адресом туннеля в шапке показывает ссылку на туннель — удобно открыть его с телефона.