pingap

До стабилизации версии pingap pull requests не принимаются. Если у вас есть вопросы, сначала создайте новый issue.

Обзор

Pingap — это высокопроизводительный обратный прокси на базе Cloudflare Pingora. Он упрощает операционное управление, обеспечивая динамическую горячую перезагрузку конфигурации без простоя через лаконичные TOML-файлы и интуитивный веб-интерфейс администратора.

Его ключевая сила — мощная система плагинов, предлагающая более двадцати готовых функций для аутентификации (JWT, Key Auth), безопасности (CSRF, ограничения по IP/Referer/UA), управления трафиком (ограничение скорости, кэширование), модификации контента (редиректы, подстановка контента) и наблюдаемости (Request ID). Это делает Pingap не просто прокси, а гибким и расширяемым шлюзом приложений, спроектированным для лёгкой обработки сложных сценариев — от защиты API до развёртывания современных веб-приложений.

中文说明 | Documentation · 中文文档 | Examples | Plugins | Crates

flowchart LR
  internet("Internet") -- request --> pingap["Pingap"]
  pingap -- proxy:pingap.io/api/* --> apiUpstream["10.1.1.1,10.1.1.2"]
  pingap -- proxy:cdn.pingap.io --> cdnUpstream["10.1.2.1,10.1.2.2"]
  pingap -- proxy:/* --> upstream["10.1.3.1,10.1.3.2"]

Ключевые возможности

• 🚀 Высокая производительность и надёжность

  • Написан на Rust для безопасности памяти и производительности высшего уровня.
  • Работает на Cloudflare Pingora — проверенной в бою асинхронной сетевой библиотеке.
  • Поддерживает проксирование HTTP/1.1, HTTP/2 и gRPC-web.

• 🔧 Динамичность и простота использования

  • Изменение конфигурации без простоя с горячей перезагрузкой.
  • Простые, удобочитаемые TOML-файлы конфигурации.
  • Полнофункциональный веб-интерфейс для интуитивного управления в реальном времени.
  • Поддерживает как файлы, так и etcd в качестве бэкендов конфигурации.
  • Поддерживает историю изменений конфигурации с возможностью восстановления до предыдущей версии в один клик.

• 🧩 Мощная расширяемость

  • Богатая система плагинов для решения типовых задач шлюза.
  • Продвинутая маршрутизация с сопоставлением по хосту, пути и регулярным выражениям.
  • Встроенное обнаружение сервисов через статические списки, DNS или метки Docker.
  • Автоматический HTTPS с Let's Encrypt (поддержка HTTP-01 и DNS-01 challenge).

• 📊 Современная наблюдаемость

  • Нативные метрики Prometheus для мониторинга (режимы pull и push).
  • Встроенная поддержка OpenTelemetry для распределённой трассировки.
  • Гибко настраиваемые журналы доступа с более чем 30 переменными.
  • Отпечатки TLS-клиентов JA4 ({:ja4} в журналах доступа, $ja4 в заголовках upstream) для различения клиентов по их TLS-стеку, как в сборках на OpenSSL, так и на rustls.
  • Детальные метрики производительности, включая время подключения к upstream, время обработки и другое.

🚀 Начало работы

Самый простой способ начать работу с Pingap — использовать Docker Compose.

1. Создайте файл docker-compose.yml:

# docker-compose.yml
version: '3.8'

services:
  pingap:
    image: vicanso/pingap:latest # For production, use a specific version like vicanso/pingap:0.12.1-full
    container_name: pingap-instance
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      # Mount a local directory to persist all configurations and data
      - ./pingap_data:/opt/pingap
    environment:
      # Configure using environment variables
      - PINGAP_CONF=/opt/pingap/conf
      - PINGAP_ADMIN_ADDR=0.0.0.0:80/pingap
      - PINGAP_ADMIN_USER=pingap
      - PINGAP_ADMIN_PASSWORD=<YourSecurePassword> # Change this!
    command:
      # Start pingap and enable hot-reloading
      - pingap
      - --autoreload

2. Создайте каталог данных и запустите:

mkdir pingap_data
docker-compose up -d

3. Откройте интерфейс администратора:

Ваш экземпляр Pingap теперь работает! Веб-интерфейс администратора доступен по адресу http://localhost/pingap с указанными вами учётными данными.

Установка бинарного файла через curl

Для Linux и macOS вы можете установить последний готовый бинарный файл в /usr/local/bin/pingap одной командой:

curl -sSL https://raw.githubusercontent.com/vicanso/pingap/main/install.sh | sh

Необязательные переменные окружения:

• PINGAP_FULL=1 — установить сборку -full (все опциональные функции включены)
• PINGAP_LIBC=gnu — в Linux использовать сборку с glibc вместо стандартной статической сборки с musl
• PINGAP_TLS=rustls — в Linux установить сборку -rustls-full (TLS-бэкенд rustls, все опциональные функции, без OpenSSL); см. TLS-бэкенд

# Full-featured build
curl -sSL https://raw.githubusercontent.com/vicanso/pingap/main/install.sh | PINGAP_FULL=1 sh

Поддерживаемые цели: Linux x86_64/arm64, Darwin x86_64/arm64. Все доступные артефакты см. на странице релизов.

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

Запуск прокси без файла конфигурации

Одной команды достаточно, чтобы обслуживать домен по https и перенаправлять его на бэкенд:

# certificate requested from let's encrypt
pingap --domain=pingap.io --upstream=192.168.1.1:3000

# or bring your own certificate
pingap --domain=pingap.io --upstream=192.168.1.1:3000 --cert=/etc/ssl/pingap.io

Без --cert Pingap запрашивает сертификат у Let's Encrypt через HTTP-01 challenge, поэтому pingap.io должен разрешаться в этот хост, а порт 80 должен быть доступен из интернета. Выданный сертификат хранится в ~/.pingap/acme/<domains>.toml и переиспользуется при перезапуске — выдача ограничена по частоте, поэтому не удаляйте его. Всё остальное по-прежнему задаётся из командной строки: изменение --upstream вступает в силу при следующем запуске без изменения сертификата.

--cert принимает как сам сертификат, так и каталог, содержащий его — распространённые раскладки fullchain.pem / privkey.pem, cert.pem / key.pem и tls.crt / tls.key определяются автоматически, для всего остального используйте --key. Слушатель по умолчанию использует 0.0.0.0:443, когда есть сертификат, и 0.0.0.0:80, когда нет ни сертификата, ни домена; --addr переопределяет это. --upstream принимает список бэкендов через запятую, --domain — список хостов через запятую (опустите его, чтобы обслуживать все хосты по обычному http). Запросы к хосту, который не указан, получают ответ 404.

Конфигурация генерируется при каждом запуске, поэтому её нельзя редактировать через веб-интерфейс администратора: для чего-либо сложнее одного сервера используйте --conf, который нельзя комбинировать с этими флагами.

Динамическая конфигурация

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

Горячая перезагрузка (--autoreload): для большинства изменений — например, обновления upstream, location или плагинов — Pingap применяет новую конфигурацию в течение 10 секунд без перезапуска. Это рекомендуемый режим для контейнерных окружений.

Плавный перезапуск (-a или --autorestart): для фундаментальных изменений (например, изменения портов прослушивания сервера) этот режим выполняет полный перезапуск без простоя, гарантируя, что ни один запрос не будет потерян.