Postman прокси настройка: поля посредника, сертификаты и прогон коллекций через newman

Раздел 3.3 · Рабочие программы

Разбор идёт по шагам. Где в Postman лежат поля посредника и что вписывать в каждое, чем глобальная настройка отличается от настройки на уровне окружения прогона, когда включать системный посредник и когда собственный, откуда берётся ошибка проверки сертификата, как прочитать реальный запрос в консоли, что меняется в Insomnia и как запустить готовую коллекцию из командной строки через newman.

1. Что понадобится

Понадобится настольная сборка Postman. В браузерной версии запросы уходят через агент Postman Desktop Agent, и поля посредника там берутся из настроек агента, поэтому весь разбор ниже я веду по настольному клиенту. Версию беру свежую с сайта разработчика: расположение вкладки Proxy за последние сборки не менялось, названия полей тоже.

Понадобится Insomnia, если работаете с ней. Клиент ставится рядом с Postman и конфликтов не создаёт, настройки у них раздельные.

Понадобится Node.js и пакет newman, он ставится одной командой:

npm install -g newman
newman --version

Понадобится строка подключения. В кабинете сервиса список выдаётся в двух форматах: IP:PORT, когда адрес рабочей машины уже привязан к пакету, и IP:PORT:LOGIN:PASS для авторизации по паре логин и пароль. Забрать список можно ссылкой или файлом. Для работы с интерфейсами по TLS я беру HTTPS-прокси для обращений к API: туннель до чужого эндпоинта строится методом CONNECT, и посредник должен уметь его открывать. Пакет включается примерно за 5 минут, бесплатный тест до 2 часов позволяет прогнать коллекцию целиком до покупки.

Понадобится сама коллекция и файл окружения. Экспорт делается через меню коллекции, формат v2.1, файл окружения выгружается отдельно. Оба файла кладу в одну папку рядом с будущими отчётами.

2. Поля настройки посредника в Postman

Окно настроек открывается шестерёнкой в правом верхнем углу, дальше вкладка Proxy. Внутри два независимых блока и список исключений. Разберу каждое поле.

Строка 203.0.113.5:8000:u8134:h2Kq7Rm4 из кабинета раскладывается по четырём полям: адрес, порт, логин, пароль. Ничего склеивать не надо, Postman собирает заголовок авторизации сам.

Отдельно про список исключений. Я вношу туда localhost и 127.0.0.1 с первого дня работы. Локальная сборка API поднимается на своей машине, и попытка достучаться до неё через внешний посредник даёт отказ соединения, который потом ищешь глазами полчаса.

Глобальная настройка

Блок Proxy в настройках клиента действует на всё сразу: на любой запрос в любой коллекции любого рабочего пространства. Профиль настроек хранится локально и переезжает вместе с учётной записью пользователя операционной системы. Переключение адреса делается руками: открыть окно, стереть старый адрес, вписать новый. Для ручной отладки одного эндпоинта такой порядок удобен.

Настройка на уровне окружения прогона

Второй путь: параметры посредника берутся из переменных окружения того процесса, который отправляет запрос. Клиент подхватывает их через режим Use the system proxy, а newman читает напрямую. Здесь адрес живёт внутри одного терминала или одного контейнера, и соседний прогон видит собственный набор.

Я держу оба способа. В клиенте прописан адрес, через который смотрю ответы вручную, а прогоны коллекций гоняю через переменные окружения с отдельным набором адресов. Пул сервиса насчитывает около 12 000 активных адресов с автоматической ротацией внутри пула, поэтому набрать разные строки под ручную работу и под прогон труда не составляет.

3. Системный посредник против собственного

Режим Use the system proxy забирает параметры из операционной системы: в Windows это раздел Параметры, Сеть и Интернет, Прокси-сервер, в macOS вкладка сетевых настроек активного подключения. В Linux и при запуске из терминала клиент читает переменные HTTP_PROXY, HTTPS_PROXY и NO_PROXY.

Плюс режима: адрес прописан один раз и работает во всех программах машины сразу, включая браузер и сторонние утилиты. Минус проявляется, когда браузеру нужен один маршрут, а клиенту API другой: системная настройка тянет обоих в одну сторону.

Собственная настройка внутри Postman держит адрес только для запросов клиента. Браузер при этом ходит своим путём, и это заметно упрощает сверку: открываю чужой API в браузере с адреса машины и вижу, что отдаёт он на обычное обращение, параллельно шлю тот же запрос из Postman через посредник и сравниваю ответы построчно.

Одновременно включать оба блока смысла нет. При двух включённых галочках Postman отдаёт приоритет системным параметрам, и собственные поля остаются заполненными без работы. Я видел, как из-за этого час искали причину того, что запросы упорно уходят со старого адреса.

Для ручной отладки я подключаю приватные адреса из закрытого пула: доступ к пулу открыт клиентам сервиса, посторонних обращений через ту же строку не идёт, и рейт-лимит на стороне чужого API расходуется только моими запросами. Привязать к пакету можно 2 адреса, менять привязку разрешено без ограничений, так что домашняя машина и рабочий сервер живут в одном пакете.

4. Сертификаты и ошибка проверки

Запрос по HTTPS через посредник строится в два этапа. Сначала клиент открывает туннель методом CONNECT до адреса посредника, потом внутри туннеля поднимает TLS-сессию до конечного узла. Сертификат проверяется на втором этапе, и проверяет его клиент собственными силами по своему списку корневых центров.

Отсюда простое следствие: посредник в проверку сертификата не вмешивается и подменить его не может. Когда всплывает unable to verify the first certificate или self signed certificate in certificate chain, причина лежит в цепочке сертификатов конечного узла либо в списке корневых центров у клиента.

Разбираю по порядку. Первое: сервер отдаёт сертификат без промежуточного звена цепочки. Браузер такой случай вытягивает сам, докачивая недостающее звено по ссылке внутри сертификата, а Postman этого не делает и честно отдаёт ошибку. Правится на стороне сервера, склейкой полной цепочки в один файл.

Второе: узел подписан внутренним центром компании. Корневой сертификат такого центра надо добавить в клиент: Settings, вкладка Certificates, блок CA Certificates, переключатель и путь к файлу PEM. После добавления клиент перезапускается.

Третье: сервер требует клиентский сертификат. Он вносится в блоке Client Certificates той же вкладки: поле Host с доменом и портом, дальше пара файлов CRT и KEY либо один файл PFX и поле Passphrase. Хост пишется без схемы, порт указывается отдельным полем.

Host:        api.example.net
Port:        443
CRT file:    C:\certs\client.crt
KEY file:    C:\certs\client.key
Passphrase:  (пусто, если ключ без пароля)

Быстрый обход на время отладки: Settings, вкладка General, переключатель SSL certificate verification в положение Off. Я включаю его обратно сразу после того, как разобрался с причиной, потому что выключенная проверка прячет и настоящие проблемы с цепочкой на боевом узле.

Для newman тот же набор задаётся ключами командной строки, их разберу ниже. Дополнительный корневой центр умеет подхватывать и сам Node.js, через переменную NODE_EXTRA_CA_CERTS с путём к файлу.

5. Консоль Postman и чтение реального запроса

Консоль открывается через меню View, пункт Show Postman Console, либо сочетанием Ctrl+Alt+C. Это единственное место, где виден запрос ровно в том виде, в каком он ушёл в сеть, вместе с подставленными переменными, добавленными заголовками и параметрами соединения.

Смотрю я на четыре блока каждой записи.

Блок Request Headers показывает итоговый набор заголовков. Здесь видно, что подставилось из переменных окружения, что добавил сам клиент и что пришло из скрипта предзапроса.

Блок Network показывает параметры соединения: адрес узла, к которому подключился клиент, версию TLS и шифр. Когда посредник работает, в этом блоке отражается его адрес. Когда поля заполнены, а галочка снята, здесь стоит адрес конечного узла напрямую, и вопрос закрывается за секунду.

Блок ответа показывает код, заголовки и тело. Заголовки ответа полезны при разборе рейт-лимита: счётчики оставшихся обращений чужие API отдают именно там.

Блок предупреждений подсвечивает подмену заголовков и отключённую проверку сертификата. Строка о выключенной проверке висит на каждом запросе, пока переключатель стоит в нижнем положении.

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

GET https://postman-echo.com/ip

Ответ содержит адрес, с которого пришло обращение. Совпал с адресом из кабинета: маршрут собран верно. Совпал с адресом рабочей машины: посредник не подключился. Заодно я смотрю на набор заголовков через https://postman-echo.com/headers и проверяю, что в них нет служебных полей с адресом источника. Для работы с чужими интерфейсами я держу анонимные адреса без пометок посредника отдельным набором: заголовки уходят такими же, как при обращении напрямую.

6. Insomnia: те же адреса, другие названия полей

Insomnia закрывает ту же задачу и настраивается быстрее, потому что поле посредника там одно. Открывается через Preferences, вкладка General, блок с сетевыми параметрами.

Строка пишется целиком, включая логин и пароль:

HTTP Proxy:   203.0.113.5:8000
HTTPS Proxy:  u8134:h2Kq7Rm4@203.0.113.5:8000
No Proxy for: localhost,127.0.0.1

Галочка Enable proxy включает оба поля разом. Пустое поле означает прямое соединение для соответствующей схемы, поэтому при работе только с TLS-эндпоинтами достаточно заполнить нижнюю строку.

Главное отличие сидит внутри. Insomnia собрана поверх libcurl, поэтому строка со схемой socks5://203.0.113.5:1080 в поле посредника отрабатывает без переходников. Postman работает по HTTP и HTTPS, и для протокола SOCKS адрес поднимается локальным переходником, который слушает порт на машине и уводит соединение дальше. Когда прогоны идут через SOCKS, я вношу адреса по протоколу SOCKS5 прямо в поле Insomnia и получаю тот же маршрут без лишнего звена.

Вкладка Timeline заменяет консоль. Вывод там оформлен как подробный лог libcurl: строки соединения, рукопожатие TLS, отправленные заголовки, полученные заголовки. Строка вида Connected to 203.0.113.5 port 8000 подтверждает работу посредника, дальше по логу видно CONNECT api.example.net:443 и код ответа туннеля.

7. Запуск коллекции через newman с посредником

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

Windows, PowerShell:

$env:HTTPS_PROXY = "http://u8134:h2Kq7Rm4@203.0.113.5:8000"
$env:HTTP_PROXY  = "http://u8134:h2Kq7Rm4@203.0.113.5:8000"
$env:NO_PROXY    = "localhost,127.0.0.1"
newman run api.postman_collection.json -e stage.postman_environment.json

Linux и macOS:

export HTTPS_PROXY="http://u8134:h2Kq7Rm4@203.0.113.5:8000"
export NO_PROXY="localhost,127.0.0.1"
newman run api.postman_collection.json -e stage.postman_environment.json --reporters cli,json --reporter-json-export run.json

Одноразовый запуск без правки окружения терминала пишется одной строкой:

HTTPS_PROXY="http://u8134:h2Kq7Rm4@203.0.113.5:8000" newman run api.postman_collection.json -e stage.postman_environment.json

Сертификаты в newman задаются ключами. Дополнительный корневой центр подключается через --ssl-extra-ca-certs, клиентская пара через --ssl-client-cert и --ssl-client-key, а --insecure снимает проверку целиком на время разбора:

newman run api.postman_collection.json -e stage.postman_environment.json --ssl-extra-ca-certs ca-internal.pem --ssl-client-cert client.crt --ssl-client-key client.key

Темп прогона держат два ключа. --delay-request ставит паузу между запросами в миллисекундах, --timeout-request ограничивает ожидание ответа. На коллекции из 40 запросов с пятью повторами я ставлю паузу 400 миллисекунд и таймаут 20 секунд:

newman run api.postman_collection.json -e stage.postman_environment.json --iteration-count 5 --delay-request 400 --timeout-request 20000

Потоков на обычном пакете доступно 1000, на корпоративном до 3000, трафик безлимитный на всех вариантах. Для newman запас огромный: прогон упирается в паузы и в рейт-лимит чужого интерфейса задолго до того, как закончатся потоки. При двух привязанных адресах общий лимит делится пополам, и на обычном пакете это 500 потоков на машину. Когда коллекция ходит по чужому API сотнями обращений подряд, я подключаю адреса под массовые обращения к интерфейсу и раскладываю прогон по нескольким строкам через файл с данными итераций.

Передача переменных окружения

Переменные попадают в прогон тремя путями, и они складываются по приоритету.

Файл окружения подключается ключом -e или --environment и содержит пары ключ-значение из экспорта Postman. Ключ -g подключает глобальные переменные из отдельного файла.

Точечная подстановка делается ключом --env-var, он повторяется столько раз, сколько нужно значений, и перекрывает файл:

newman run api.postman_collection.json -e stage.postman_environment.json --env-var "baseUrl=https://api.example.net" --env-var "token=$API_TOKEN" --env-var "proxyHost=203.0.113.5"

Файл с данными итераций подключается ключом -d, формат CSV или JSON. Каждая строка файла даёт свой набор значений, и коллекция прогоняется по одному разу на строку:

newman run api.postman_collection.json -e stage.postman_environment.json -d accounts.csv

Итоговое окружение после прогона выгружается ключом --export-environment. Это удобно, когда коллекция получает токен первым запросом и складывает его в переменную: следующий прогон стартует с готовым токеном.

newman run auth.postman_collection.json -e stage.postman_environment.json --export-environment stage.updated.json

Секреты в файл окружения я не кладу. Токен и пароль передаю через --env-var со ссылкой на переменную операционной системы, тогда файл коллекции спокойно живёт в общем репозитории. Строку подключения к посреднику держу там же, в переменных окружения машины, чтобы список адресов с поддержкой HTTPS обновлялся из кабинета одним файлом без правки команд запуска.

8. Проверка после настройки

Перед прогоном боевой коллекции я делаю четыре проверки подряд, они занимают минут пять и снимают почти все вопросы.

Первая проверка: адрес источника. Запрос GET https://postman-echo.com/ip из Postman должен вернуть адрес из кабинета. Тот же запрос из Insomnia отвечает так же. Расхождение между клиентами означает, что в одном из них галочка посредника снята.

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

curl -x http://203.0.113.5:8000 -U u8134:h2Kq7Rm4 -s https://api.ipify.org

Ответ с адресом посредника подтверждает рабочую строку и проходящую авторизацию. Ответ с адресом машины означает, что ключ -x не применился.

Третья проверка: туннель по TLS открывается. Обычный GET по http:// может проходить через посредник в момент, когда CONNECT для https:// упирается в отказ. Проверяю отдельной командой с подробным выводом:

curl -x http://203.0.113.5:8000 -U u8134:h2Kq7Rm4 -v https://api.example.net/v1/ping

Строка Established connection to proxy вместе с кодом 200 от туннеля закрывает вопрос.

Четвёртая проверка: newman видит те же параметры, что и клиент. Гоняю коллекцию из одного запроса к эхо-сервису и сверяю адрес в отчёте с тем, что показала консоль Postman.

newman run echo-ip.postman_collection.json --reporters cli

Совпали адреса: окружение прогона собрано верно. Разошлись: переменная задана в другом терминале либо потеряна схема http:// в её значении.

9. Разбор ошибок

Ниже сообщения, которые встречались мне в обоих клиентах и в newman чаще прочих, с причиной и порядком действий.

Две ситуации разберу подробнее, потому что видно их плохо.

Запросы проходят из клиента и падают из newman. Причина почти всегда в окружении: клиент читает собственную вкладку Proxy, а newman читает переменные процесса. Терминал открыт заново после установки переменных, значение потеряно. Перед каждым прогоном по расписанию я вывожу значение переменной командой echo в том же окне терминала, откуда стартует newman.

Часть запросов коллекции уходит через посредник, часть напрямую. Смотрю список исключений: в Proxy Bypass или No Proxy for попал домен, который совпадает по хвосту с адресом целевого API. Правило сравнения работает по окончанию имени, поэтому запись example.net уводит напрямую и api.example.net, и stage.example.net.

Соседние страницы справочника закрывают смежные случаи: маршрутизация приложений в Proxifier пригодится, когда программа полей посредника не имеет вовсе и трафик надо перехватывать снаружи, сбор выдачи в KeyAssort разбирает работу со списком адресов пачкой, загрузка данных в Excel и Power Query показывает, как свести ответы интерфейса в книгу для отчёта. Для прогонов коллекции внутри образа смотрите настройку посредника в Docker: там разобрана передача переменных окружения в контейнер и в docker-compose.