Pingap

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

Запросы из интернета проходят через Pingap, который маршрутизирует их по хосту и пути к группам вышестоящих серверов

Что отличает его

Веб-админка в бинарнике. Для каждой настройки есть форма. Изменение проверяется так же, как его проверяет pingap -t, прежде чем сохраниться, предыдущие версии можно хранить и восстанавливать, есть аккаунты только для чтения и API-токены. На главной странице отображаются графики трафика за последние пятнадцать минут — частота, статусы, задержка, каждый вышестоящий сервер — без Prometheus.
Изменения без простоя. Вышестоящие серверы, локации, плагины и сертификаты заменяются в работающем процессе (--autoreload). То, что требует новых слушателей, применяется перезапуском с передачей сокетов (--autorestart, для демона в Linux), и работающий процесс продолжает обслуживать запросы, если его замена не запускается.
Более тридцати плагинов, для каждой локации и в указанном вами порядке: аутентификация (JWT, OIDC, key, basic, HMAC, forward auth), правила доступа (IP, referer, user agent, заблокированные пути), трафик (ограничения частоты и пропускной способности, кэш, зеркалирование, разделение трафика), контент (сжатие, подстановка тела, перенаправления, статические файлы, оптимизация изображений) и операции (режим обслуживания, эндпоинт здоровья, страницы ошибок). Все плагины
Сертификаты без cron-задачи. Let's Encrypt или любой другой ACME CA, через HTTP-01 или DNS-01 (Alibaba Cloud, Cloudflare, Tencent Cloud, Huawei Cloud), RSA и ECDSA бок о бок, OCSP stapling и взаимный TLS по отношению к клиентам и к вышестоящим серверам.
Конфигурация, проверяемая перед запуском. -t собирает всё, что собрал бы запуск, --strict отклоняет неизвестные ключи, --diff показывает, что сделает изменение. TOML, HCL или KDL, в файлах или в etcd, с секретами из окружения или из файлов.
Создан для мониторинга. Метрики Prometheus (pull и push), трейсы OpenTelemetry, логи доступа в виде текста или JSON с более чем тридцатью полями и JA4 TLS-отпечатки клиентов.

Всё остальное, что делает обратный прокси, тоже присутствует: HTTP/1.1, HTTP/2, WebSocket и gRPC-web; маршрутизация по хосту, пути и регулярному выражению; round robin, наименьшее число соединений, согласованное хеширование и липкие сессии, с проверками здоровья, повторами и размыкателем цепи; бэкенды из DNS (A/AAAA, SRV) или меток Docker; протокол PROXY на слушателях и по отношению к вышестоящим серверам; OpenSSL или rustls.

Метрики, трейсинг и оптимизация изображений присутствуют в сборках -full.

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

Docker Compose

# docker-compose.yml
services:
  pingap:
    image: vicanso/pingap:latest # for production, pin a release: vicanso/pingap:<version>-full
    container_name: pingap-instance
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      # everything Pingap keeps: configuration, certificates, cache
      - ./pingap_data:/opt/pingap
    environment:
      - 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:
      - pingap
      - --autoreload

mkdir pingap_data
docker compose up -d

Административный интерфейс доступен по адресу http://localhost/pingap. Образы имеют теги latest, full и rustls-full, а также <version>, <version>-full, <version>-rustls-full для релиза. У каждого также есть -distroless-двойник без оболочки, где command должен начинаться с pingap, как показано выше.

Бинарный файл

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

устанавливает последний релиз в /usr/local/bin/pingap на Linux и macOS (x86_64 и arm64). Переменные перед sh определяют, что устанавливается:

Переменная	Эффект
`PINGAP_FULL=1`	Сборка `-full` со всеми опциональными функциями
`PINGAP_TLS=rustls`	Linux: сборка `-rustls-full`, без OpenSSL (см. TLS backend)
`PINGAP_LIBC=gnu`	Linux: сборка с glibc вместо статической musl
`PINGAP_SERVICE=1`	Linux с systemd: также служба `pingap` и стартовая конфигурация в `/etc/pingap/conf`; она не включается и не запускается
`PINGAP_VERSION=0.15.0`	Этот релиз вместо последнего

Все ресурсы находятся на странице релизов.

Одна команда, без файла конфигурации

# the certificate comes from Let's Encrypt
pingap --domain=pingap.io --upstream=192.168.1.1:3000

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

Без --cert сертификат заказывается по HTTP-01: домен должен разрешаться в этот хост, а порт 80 должен быть доступен. Он хранится в ~/.pingap/acme/<domains>.toml и используется снова при следующем запуске. Не удаляйте его, выпуск ограничен по частоте.
--cert — это сертификат или каталог, в котором он находится (находятся fullchain.pem / privkey.pem, cert.pem / key.pem и tls.crt / tls.key; --key задаёт имя для всего остального). --upstream и --domain принимают списки, разделённые запятыми, --addr — адрес для прослушивания.
Конфигурация создаётся заново при каждом запуске, поэтому администратор не может её редактировать. Для более чем одного сервера используйте --conf, с которым эти флаги нельзя комбинировать.

📝 Конфигурация

[upstreams.api]
addrs = ["api.github.com:443"]
discovery = "dns"
sni = "api.github.com"

[plugins.staticServe]
category = "directory"
path = "~/Downloads"

[locations.github-api]
upstream = "api"
path = "/api"
proxy_set_headers = ["Host:api.github.com"]
rewrite = "^/api/(?<path>.+)$ /$1"

[locations.static]
plugins = ["staticServe"]

[servers.test]
addr = "127.0.0.1:6118"
locations = ["github-api", "static"]

То же самое можно записать на HCL или KDL. Каждый ключ описан в справочнике по конфигурации.


`--autoreload`	Изменение применяется без перезапуска: в течение десяти секунд из файлов, сразу из etcd. То, что требует перезапуска, сообщается и ожидает его. Режим для контейнеров
`-a`, `--autorestart`	То же самое, плюс перезапуск, при котором не теряется ни один запрос для того, что не может изменить перезагрузка, — например, адреса прослушивания. Для демона (`-d`) в Linux; в любом другом месте выполняется перезагрузка с сообщением о том, что ожидает
`-t`	Собирает каждый upstream, location, плагин, сертификат и сервер так же, как при запуске, и ничего не привязывает
`--strict`	Ключ, неизвестный Pingap, или ключ, для которого в этой сборке нет функции, считается ошибкой, тогда как иначе это предупреждение. Для `-t` в CI
`--diff <other>`	Выводит, что изменилось бы, если бы `<other>` занял место конфигурации; учётные данные показываются в виде контрольных сумм
`$ENV:NAME`, `$FILE:/path`	Как целое значение: заменяется переменной или файлом при загрузке конфигурации

pingap

Популярное