pingap

# Pingap

Обратный прокси и шлюз приложений, построенный на [Cloudflare Pingora](https://github.com/cloudflare/pingora). Настраивается через файлы TOML или веб-админку, встроенную в бинарник, принимает изменения без перезапуска и поставляется с более чем тридцатью плагинами.

[中文说明](https://github.com/vicanso/pingap/blob/main/README_zh.md) | [Документация](https://pingap.io/) · [中文文档](https://pingap.io/zh/) | [Примеры](https://github.com/vicanso/pingap/blob/main/examples/README.md) | [Плагины](https://github.com/vicanso/pingap/blob/main/pingap-plugin/README.md) | [Crates](https://github.com/vicanso/pingap/blob/main/docs/README.md) | [Обновление](https://pingap.io/guide/upgrading)

![Запросы из интернета проходят через Pingap, который маршрутизирует их по хосту и пути к группам вышестоящих серверов](https://raw.githubusercontent.com/vicanso/pingap/main/asset/pingap-flow.svg)

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

- **Веб-админка в бинарнике.** Для каждой настройки есть форма. Изменение проверяется так же, как его проверяет `pingap -t`, прежде чем сохраниться, предыдущие версии можно хранить и восстанавливать, есть аккаунты только для чтения и API-токены. На главной странице отображаются графики трафика за последние пятнадцать минут — частота, статусы, задержка, каждый вышестоящий сервер — без Prometheus.
- **Изменения без простоя.** Вышестоящие серверы, локации, плагины и сертификаты заменяются в работающем процессе (`--autoreload`). То, что требует новых слушателей, применяется перезапуском с передачей сокетов (`--autorestart`, для демона в Linux), и работающий процесс продолжает обслуживать запросы, если его замена не запускается.
- **Более тридцати плагинов**, для каждой локации и в указанном вами порядке: аутентификация (JWT, OIDC, key, basic, HMAC, forward auth), правила доступа (IP, referer, user agent, заблокированные пути), трафик (ограничения частоты и пропускной способности, кэш, зеркалирование, разделение трафика), контент (сжатие, подстановка тела, перенаправления, статические файлы, оптимизация изображений) и операции (режим обслуживания, эндпоинт здоровья, страницы ошибок). [Все плагины](https://github.com/vicanso/pingap/blob/main/pingap-plugin/README.md)
- **Сертификаты без 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

```yaml
# 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
```

```bash
mkdir pingap_data
docker compose up -d
```

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

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

```bash
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](#tls-backend)) |
| `PINGAP_LIBC=gnu` | Linux: сборка с glibc вместо статической musl |
| `PINGAP_SERVICE=1` | Linux с systemd: также служба `pingap` и стартовая конфигурация в `/etc/pingap/conf`; она не включается и не запускается |
| `PINGAP_VERSION=0.15.0` | Этот релиз вместо последнего |

Все ресурсы находятся на [странице релизов](https://github.com/vicanso/pingap/releases).

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

```bash
# 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`, с которым эти флаги нельзя комбинировать.

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

```toml
[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. Каждый ключ описан в [справочнике по конфигурации](https://pingap.io/crates/config).

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

## 🔄 Как обрабатывается запрос

![Запрос проходит через сервер, location и его плагины запроса к upstream; ответ возвращается через плагины ответа и логируется](https://raw.githubusercontent.com/vicanso/pingap/main/asset/pingap-steps.svg)

1. **Сервер** принимает соединение и выбирает **location**, чьи хост и путь совпадают лучше всего. Запрос, не совпавший ни с одним, получает ответ `404`.
2. **Плагины** location выполняются в порядке их перечисления, каждый на своём шаге: на входе или на обратном пути. Плагин может сам ответить на запрос — попадание в кэш, неудачная аутентификация, перенаправление, статический файл — и тогда upstream не запрашивается вовсе.
3. В противном случае **upstream** location выбирает работоспособный бэкенд, и запрос пересылается. При `max_retries` соединение, которое не удаётся установить, пробуется на другом бэкенде; при `fallback_upstream` запрос, который upstream не может принять, направляется во второй upstream.
4. Ответ возвращается через плагины ответа клиенту, а запрос **логируется**: журнал доступа, метрики и трассировки.

## 📊 Производительность

Около 147 000 запросов в секунду для `/ping` на одном потоке M4 Pro при 99-м процентиле 116µs (`wrk`, 10 соединений, без журнала доступа).

<details>
<summary>Запуск</summary>

```
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
```

</details>

## 🔧 Разработка

```bash
make dev         # needs bacon: cargo install bacon
make build-web   # after a change under web/, needs Node.js
make fmt && make lint && make test
```

`make dev` собирает с функциями `full`, запускает Pingap с конфигурацией в `~/tmp/pingap` с `--autoreload`, обслуживает админ-панель на `127.0.0.1:3018` (`pingap` / `123123`) и пересобирает при изменении исходников. Админ-панель встраивается в бинарный файл из `dist/`, который заполняется командой `make build-web`. Минимальная поддерживаемая версия Rust — 1.96.

### TLS-бэкенд

Сборка по умолчанию использует OpenSSL, скомпилированный из исходников. Для rustls:

```bash
cargo build --release --no-default-features --features tls-rustls,full
```

Сборка с rustls всегда предлагает TLS 1.2 и 1.3 с собственными наборами шифров rustls, поэтому при проверке конфигурации параметры `tls_min_version`, `tls_max_version`, `tls_cipher_list` и `tls_ciphersuites` для каждого сервера отклоняются. Всё остальное работает так же; различия перечислены вместе с [certificate crate](https://pingap.io/crates/certificate). Команда `pingap --version` сообщает, какой бэкенд использует бинарный файл.

## 🤝 Участие в разработке

Pull requests приветствуются.

- Для новой функции сначала откройте issue, чтобы её можно было обсудить до написания кода.
- Пожалуйста, не открывайте pull request только для исправления опечатки или форматирования комментария; такие правки вносятся пакетами.
- Перед отправкой выполните `make fmt`, `make lint` и `make test`. CI запускает те же проверки для каждого pull request.
- Вклад вносится в соответствии с [Contributor License Agreement](https://github.com/vicanso/pingap/blob/main/CLA.md), который принимается путём отметки соответствующего пункта в шаблоне pull request: работа остаётся вашей и лицензируется проекту на условиях его лицензии.

## 📄 Лицензия

[Apache License, Version 2.0](https://github.com/vicanso/pingap/blob/main/LICENSE).