adqproxy — мой обратный прокси на Rust, построенный на Cloudflare Pingora. Команда для работы с ним — adqp. Мне хотелось совместить программируемую обработку запросов с привычным устройством сервера: конфигурацией сайтов, проверкой настроек и службой systemd.
Когда я вернулся к проекту, обнаружилась неприятная граница между этими частями: пакет устанавливался, проверка конфигурации проходила, а процесс завершался ещё до первого HTTP-запроса. Пока исправлял установку и маршрутизацию, отдельно проверил весь путь от установки пакета до работающего сервиса.
Чтобы объяснить устройство adqproxy, сначала разберу его основу: что такое Pingora, где она работает у Cloudflare и почему её сравнивают с NGINX.
Что такое reverse proxy и где здесь Pingora
Обратный прокси принимает запрос от клиента и обращается к приложению от его имени. Приложение может работать на другом порту, сервере или в контейнере. Прокси выбирает, куда направить запрос, и возвращает ответ клиенту.
Клиент → reverse proxy → приложение или группа бэкендов
Например, один домен может отправлять /api/ в API-сервис, а остальные запросы — во фронтенд. На этом же уровне можно завершать TLS и распределять запросы между экземплярами приложения.
Pingora — асинхронный многопоточный Rust-фреймворк для построения сетевых сервисов, включая HTTP-прокси. Cloudflare открыла его исходный код в феврале 2024 года. Разработчик подключает библиотеки и пишет приложение со своей логикой обработки трафика. Анонс открытия Pingora
В проекте есть поддержка HTTP/1.1, HTTP/2, TLS, переиспользования соединений, балансировки и проверок доступности бэкендов. Какие возможности попадут в конкретный сервис и как ими управлять, определяет приложение поверх фреймворка. Репозиторий Pingora
Для чего Cloudflare использует Pingora
В описанной Cloudflare архитектуре Pingora обслуживает обращения из сети Cloudflare к origin-серверам — серверам, на которых работает сайт или приложение клиента.
В статье 2022 года компания объясняла ограничения своей прежней системы на NGINX: пулы соединений были привязаны к отдельным worker-процессам. Запрос не всегда мог использовать соединение, уже открытое другим процессом. Архитектура Pingora позволила разделять соединения между потоками и реже выполнять TCP/TLS-рукопожатия. Как Cloudflare построила Pingora
Почему Pingora сравнивают с NGINX
Они пересекаются в задачах reverse proxy: принять HTTP-запрос, выбрать бэкенд, установить соединение и вернуть ответ. На этом участке приложение на Pingora может конкурировать с NGINX.
При этом NGINX предоставляет готовый веб-сервер с конфигурацией, модулями, отдачей статических файлов, проксированием и балансировкой. Pingora предоставляет основу для разработки собственного сетевого сервиса. Поэтому при выборе стоит сравнивать возможности и эксплуатацию конкретных приложений. Возможности NGINX · Назначение Pingora
| Вопрос | NGINX | Pingora и приложение поверх неё |
|---|---|---|
| С чего начинается работа | Запуск готового сервера и настройка конфигурации | Разработка или выбор готового приложения на фреймворке |
| Где задаётся поведение | Конфигурация, модули, расширения | Rust-код и интерфейс настроек конкретного приложения |
| Кто определяет формат сайтов | NGINX | Автор приложения |
| Что нужно проверить при внедрении | Конфигурацию и необходимые модули | Возможности приложения, конфигурацию, установку и обновления |
Возможность перенести собственную логику в Rust-код — одна из причин моего интереса к Pingora. Если прокси должен принимать решения по данным приложения, выбирать особую стратегию маршрутизации или интегрироваться с внутренними сервисами, полезно иметь явные точки расширения.
Для обычного проксирования нескольких сайтов NGINX остаётся практичным вариантом. В своём проекте я оцениваю Pingora прежде всего как основу для программируемого прокси. Отдельного сравнения производительности adqproxy и NGINX на одинаковой нагрузке в этой работе не было.
Как в Pingora обрабатывается запрос
Интерфейс ProxyHttp позволяет включаться в отдельные этапы запроса:
request_filter— проверить запрос или сформировать ответ до обращения к бэкенду.upstream_peer— выбрать сервер и параметры соединения с ним.upstream_request_filter— изменить запрос перед отправкой бэкенду.response_filterиlogging— обработать ответ и записать результат.
Это удобно, когда логика выбора бэкенда сложнее фиксированного соответствия пути и адреса. Например, решение может зависеть от контекста запроса. Последовательность этапов и условия повторных попыток описаны в руководстве по жизненному циклу запроса.
Как устроен adqproxy
В adqproxy я добавляю поверх Pingora формат конфигурации сайтов и рабочий процесс управления ими: sites-available, sites-enabled, проверку конфигурации и запуск через systemd. Это та часть, с которой взаимодействует администратор сервера.
В рамках этой доработки я обновил Pingora с 0.6.0 до 0.9.1, адаптировал код кэша и метрик и зафиксировал зависимости в Cargo.lock. Дальше проверял конкретное поведение adqproxy: запуск без upstream, выбор бэкенда, TLS и обновление поверх изменённых настроек. Релиз Pingora 0.9.1
Почему чистая установка падала
Установщик включал сайт default с простым правилом return 200 "OK\n"; для /health. Такой ответ можно отдать прямо из прокси. Но бинарник при запуске безусловно брал первый балансировщик из списка upstream, а у штатного сайта список был пуст. Обе части по отдельности казались разумными, пока их не запускали вместе.
Теперь прокси может стартовать без upstream. После установки на Linux с systemd он включает штатный сайт и отвечает на http://127.0.0.1:8080/health. При обновлении установщик сохраняет proxy.yaml, файлы сайтов и их симлинки. Если администратор отключил сайт по умолчанию, обновление его обратно не включает. Изменения установщика
Что я взял из рабочего процесса NGINX
Сайт хранится в /etc/adq-pingora/sites-available/, а adq-ensite создаёт ссылку в sites-enabled/. Например, в файле /etc/adq-pingora/sites-available/demo путь можно связать с конкретной группой бэкендов.
server {
listen 8080;
server_name demo.example;
location /api/ {
proxy_pass demo_api;
}
}
upstream demo_api {
server 127.0.0.1:3000;
}
С этим конфигом запрос на /api/ с заголовком Host: demo.example уходит в demo_api. До правки два маршрута с разными proxy_pass могли попадать в один бэкенд. Я поднял два локальных HTTP-сервера и проверил по телам ответов, какой из них действительно обработал каждый запрос. Для HTTPS директива listen … ssl теперь создаёт TLS-слушатель на указанном порту и использует сертификат из конфига.
Проверку имеет смысл запускать от пользователя службы. Так сразу видно, может ли процесс прочитать файлы конфига и TLS-ключ. Применение изменений пока требует перезапуска systemd, поэтому возможен перерыв в обслуживании.
sudo adq-ensite demo
sudo -u adq-pingora adqp -t && sudo systemctl restart adq-pingora
Похожий подход к проверке конфигурации и работающего сервиса я описал в статье о проверке и обновлении NGINX после шести CVE: сначала сверил настройки и установленный пакет, затем проверил обработку запросов после обновления.

Что я теперь проверяю перед релизом
CI собирает бинарник из зафиксированных зависимостей, ставит его на Ubuntu, запускает установленную службу через systemd и ждёт OK от штатного /health. Отдельные тесты проверяют обновление поверх изменённого конфига, неправильный синтаксис, отсутствующий upstream, два независимых бэкенда, HTTPS и счётчик запросов на /metrics. Так я проверяю установку, которую получит пользователь, вместе с поведением самого прокси. Прогон GitHub Actions


Код и инструкция по сборке уже в основной ветке. Публикация пакета adqproxy в npm пока впереди. Репозиторий проекта