pingap v0.13.10
Обратный прокси-сервер, подобный nginx, построенный на pingora, простой и эффективный.
pingap
До стабилизации версии pingap пул-реквесты приниматься не будут. Если у вас есть вопросы, сначала создайте новый issue.
Обзор
Pingap — это высокопроизводительный обратный прокси на основе Cloudflare Pingora. Он упрощает эксплуатационное управление благодаря динамической перезагрузке конфигурации без простоев через лаконичные TOML-файлы и интуитивно понятный веб-интерфейс администратора.
Его ключевая особенность — мощная система плагинов, предлагающая более двадцати готовых функций для аутентификации (JWT, Key Auth), безопасности (CSRF, ограничения по IP/Referer/UA), управления трафиком (ограничение скорости, кэширование), модификации контента (редиректы, подстановка контента) и наблюдаемости (Request ID). Это делает Pingap не просто прокси, а гибким и расширяемым шлюзом приложений, способным без усилий справляться со сложными сценариями — от защиты API до развертывания современных веб-приложений.
中文说明 | Документация · 中文文档 | Примеры | Плагины | 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.
-
🔧 Динамичность и простота использования
- Изменение конфигурации без простоев благодаря hot-reload.
- Простые и читаемые TOML-файлы конфигурации.
- Полнофункциональный веб-интерфейс для интуитивного управления в реальном времени.
- Поддержка файлов и etcd в качестве бэкенда конфигурации.
- Поддержка истории изменений конфигурации с возможностью отката к предыдущей версии в один клик.
-
🧩 Мощная расширяемость
- Богатая система плагинов для решения типовых задач шлюза.
- Продвинутая маршрутизация с сопоставлением по хосту, пути и регулярным выражениям.
- Встроенное обнаружение сервисов через статические списки, DNS или Docker-метки.
- Автоматический HTTPS с Let's Encrypt (поддержка проверок HTTP-01 и DNS-01).
-
📊 Современная наблюдаемость
- Нативные метрики Prometheus для мониторинга (режимы pull и push).
- Встроенная поддержка OpenTelemetry для распределенной трассировки.
- Высоконастраиваемые журналы доступа с более чем 30 переменными.
- Детальные метрики производительности, включая время подключения к апстриму, время обработки и другое.
🚀 Начало работы
Самый простой способ начать работу с Pingap — использовать Docker Compose.
- Создайте файл
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
- Создайте каталог данных и запустите:
mkdir pingap_data
docker-compose up -d
- Откройте админ-интерфейс:
Ваш экземпляр 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 по умолчанию
# Полнофункциональная сборка
curl -sSL https://raw.githubusercontent.com/vicanso/pingap/main/install.sh | PINGAP_FULL=1 sh
Поддерживаемые платформы: Linux x86_64/arm64, Darwin x86_64/arm64. Все доступные артефакты см. на странице релизов.
Более подробные инструкции, включая запуск из бинарного файла, см. в нашей Документации.
Запуск прокси без файла конфигурации
Одной команды достаточно, чтобы обслуживать домен по https и перенаправлять трафик на бэкенд:
# сертификат запрашивается у Let's Encrypt
pingap --domain=pingap.io --upstream=192.168.1.1:3000
# или укажите собственный сертификат
pingap --domain=pingap.io --upstream=192.168.1.1:3000 --cert=/etc/ssl/pingap.io
Без --cert Pingap запрашивает сертификат у Let's Encrypt через проверку HTTP-01, поэтому 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).
Конфигурация генерируется при каждом запуске, поэтому ее нельзя редактировать через админ-интерфейс: для чего-либо, кроме одного сервера, используйте --conf, который нельзя комбинировать с этими флагами.
Динамическая конфигурация
Pingap спроектирован так, чтобы адаптироваться к изменениям конфигурации без простоев.
Hot Reload (--autoreload): для большинства изменений — например, обновления апстримов, локаций или плагинов — Pingap применяет новую конфигурацию в течение 10 секунд без перезапуска. Это рекомендуемый режим для контейнерных сред.
Graceful Restart (-a или --autorestart): для фундаментальных изменений (например, изменение прослушивающих портов сервера) этот режим выполняет полный перезапуск без простоев, гарантируя, что ни один запрос не будет потерян.
🔧 Разработка
make dev
Если вам нужен веб-админ, установите nodejs и соберите веб-ресурсы.
# генерация ресурсов админ-панели
cd web
npm i
cd ..
make build-web
📝 Конфигурация
server "test" {
addr = "127.0.0.1:6118"
location "github-api" {
path = "/api"
proxy_set_headers = ["Host:api.github.com"]
rewrite = "^/api/(?<path>.+)$ /$1"
upstream "api" {
addrs = ["api.github.com:443"]
discovery = "dns"
sni = "api.github.com"
}
}
location "static" {
plugin "staticServe" {
category = "directory"
path = "~/Downloads"
step = "request"
}
}
}
[upstreams.api]
addrs = ["api.github.com:443"]
discovery = "dns"
sni = "api.github.com"
[plugins.staticServe]
category = "directory"
path = "~/Downloads"
step = "request"
[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"]
Соответствующие инструкции можно найти здесь: https://pingap.io/crates/config.
🔄 Шаги проксирования
graph TD;
server["HTTP Server"];
locationA["Location A"];
locationB["Location B"];
locationPluginListA["Proxy Plugin List A"];
locationPluginListB["Proxy Plugin List B"];
upstreamA1["Upstream A1"];
upstreamA2["Upstream A2"];
upstreamB1["Upstream B1"];
upstreamB2["Upstream B2"];
locationResponsePluginListA["Response Plugin List A"];
locationResponsePluginListB["Response Plugin List B"];
start("New Request") --> server
server -- "host:HostA, Path:/api/*" --> locationA
server -- "Path:/rest/*"--> locationB
locationA -- "Exec Proxy Plugins" --> locationPluginListA
locationB -- "Exec Proxy Plugins" --> locationPluginListB
locationPluginListA -- "proxy pass: 10.0.0.1:8001" --> upstreamA1
locationPluginListA -- "proxy pass: 10.0.0.2:8001" --> upstreamA2
locationPluginListA -- "done" --> response
locationPluginListB -- "proxy pass: 10.0.0.1:8002" --> upstreamB1
locationPluginListB -- "proxy pass: 10.0.0.2:8002" --> upstreamB2
locationPluginListB -- "done" --> response
upstreamA1 -- "Exec Response Plugins" --> locationResponsePluginListA
upstreamA2 -- "Exec Response Plugins" --> locationResponsePluginListA
upstreamB1 -- "Exec Response Plugins" --> locationResponsePluginListB
upstreamB2 -- "Exec Response Plugins" --> locationResponsePluginListB
locationResponsePluginListA --> response
locationResponsePluginListB --> response
response["HTTP Response"] --> stop("Logging");
📊 Производительность
CPU: M4 Pro, Thread: 1
Ping без журнала доступа
wrk 'http://127.0.0.1:6118/ping' --latency
Running 10s test @ http://127.0.0.1:6118/ping
2 threads and 10 connections
Thread Stats Avg Stdev Max +/- Stdev
Latency 66.41us 23.67us 1.11ms 76.54%
Req/Sec 73.99k 2.88k 79.77k 68.81%
Latency Distribution
50% 67.00us
75% 80.00us
90% 91.00us
99% 116.00us
1487330 requests in 10.10s, 194.32MB read
Requests/sec: 147260.15
Transfer/sec: 19.24MB
📦 Версия Rust
Наша текущая MSRV — 1.88
📄 Лицензия
Этот проект лицензирован в соответствии с Apache License, Version 2.0.