Pingap

Ein Reverse-Proxy und Application Gateway, aufgebaut auf Cloudflare Pingora. Er wird über TOML-Dateien oder eine Web-Administration konfiguriert, die Teil der Binärdatei ist, übernimmt Änderungen ohne Neustart und bringt mehr als dreißig Plugins mit.

中文说明 | Dokumentation · 中文文档 | Beispiele | Plugins | Crates | Upgrading

Was ihn auszeichnet

• Eine Web-Administration in der Binärdatei. Jede Einstellung hat ein Formular. Eine Änderung wird so geprüft, wie pingap -t sie prüft, bevor sie gespeichert wird, frühere Versionen können aufbewahrt und wiederhergestellt werden, und es gibt schreibgeschützte Konten und API-Tokens. Die Startseite stellt den Datenverkehr der letzten fünfzehn Minuten grafisch dar – Rate, Status, Latenz, jeder Upstream – ohne Prometheus.
• Änderungen ohne Ausfallzeit. Upstreams, Locations, Plugins und Zertifikate werden im laufenden Prozess ersetzt (--autoreload). Was neue Listener erfordert, wird durch einen Neustart angewendet, der die Sockets übergibt (--autorestart, für einen Daemon unter Linux), und der laufende Prozess bedient weiter, falls sein Nachfolger nicht hochkommt.
• Über dreißig Plugins, pro Location und in der Reihenfolge, in der du sie auflistest: Authentifizierung (JWT, OIDC, Key, Basic, HMAC, Forward Auth), Zugriffsregeln (IP, Referer, User Agent, blockierte Pfade), Datenverkehr (Raten- und Bandbreitenbegrenzungen, Cache, Mirroring, Traffic-Splitting), Inhalte (Komprimierung, Body-Ersetzung, Weiterleitungen, statische Dateien, Bildoptimierung) und Betrieb (Wartungsmodus, Health-Endpunkt, Fehlerseiten). Alle Plugins
• Zertifikate ohne Cron-Job. Let's Encrypt oder jede andere ACME-CA, per HTTP-01 oder DNS-01 (Alibaba Cloud, Cloudflare, Tencent Cloud, Huawei Cloud), RSA und ECDSA nebeneinander, OCSP-Stapling sowie gegenseitiges TLS gegenüber Clients und gegenüber Upstreams.
• Konfiguration, die vor der Ausführung geprüft wird. -t baut alles auf, was ein Start aufbauen würde, --strict lehnt Schlüssel ab, die es nicht kennt, --diff zeigt, was eine Änderung bewirken würde. TOML, HCL oder KDL, in Dateien oder in etcd, mit Secrets aus der Umgebung oder aus Dateien.
• Zum Beobachten gemacht. Prometheus-Metriken (Pull und Push), OpenTelemetry-Traces, Zugriffslogs als Text oder JSON mit mehr als dreißig Feldern und JA4-TLS-Fingerabdrücke der Clients.

Der Rest dessen, was ein Reverse-Proxy tut, ist ebenfalls vorhanden: HTTP/1.1, HTTP/2, WebSocket und gRPC-web; Routing nach Host, Pfad und regulärem Ausdruck; Round Robin, Least Connections, Consistent Hashing und Sticky Sessions, mit Health Checks, Retries und einem Circuit Breaker; Backends aus DNS (A/AAAA, SRV) oder Docker-Labels; das PROXY-Protokoll auf Listenern und gegenüber Upstreams; OpenSSL oder rustls.

Metriken, Tracing und Bildoptimierung sind in den -full-Builds enthalten.

🚀 Erste Schritte

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

Der Admin ist unter http://localhost/pingap erreichbar. Images sind mit latest, full und rustls-full sowie <version>, <version>-full, <version>-rustls-full für ein Release getaggt. Jedes hat außerdem einen -distroless-Zwilling ohne Shell, bei dem command wie oben mit pingap beginnen muss.

Binary

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

installiert die neueste Version nach /usr/local/bin/pingap unter Linux und macOS (x86_64 und arm64). Variablen vor sh legen fest, was installiert wird:

Variable	Wirkung
PINGAP_FULL=1	Der -full-Build mit allen optionalen Funktionen
PINGAP_TLS=rustls	Linux: der -rustls-full-Build ohne OpenSSL (siehe TLS-Backend)
PINGAP_LIBC=gnu	Linux: der glibc-Build anstelle des statischen musl-Builds
PINGAP_SERVICE=1	Linux mit systemd: zusätzlich der pingap-Dienst und eine Startkonfiguration in /etc/pingap/conf; er wird nicht aktiviert oder gestartet
PINGAP_VERSION=0.15.0	Diese Version anstelle der neuesten

Alle Assets befinden sich auf der Releases-Seite.

Ein Befehl, keine Konfigurationsdatei

# 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

• Ohne --cert wird das Zertifikat per HTTP-01 bestellt: Die Domain muss auf diesen Host auflösen, wobei Port 80 erreichbar sein muss. Es wird in ~/.pingap/acme/<domains>.toml gespeichert und beim nächsten Start erneut verwendet. Löschen Sie es nicht, die Ausstellung ist rate-limitiert.
• --cert ist das Zertifikat oder das Verzeichnis, in dem es liegt (fullchain.pem / privkey.pem, cert.pem / key.pem und tls.crt / tls.key werden gefunden; --key benennt alles andere). --upstream und --domain nehmen durch Kommas getrennte Listen entgegen, --addr die Adresse, auf der gelauscht werden soll.
• Die Konfiguration wird bei jedem Start neu erstellt, sodass der Administrator sie nicht bearbeiten kann. Für mehr als einen Server verwenden Sie --conf, womit diese Flags nicht kombiniert werden können.

📝 Konfiguration

[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"]

Dasselbe kann in HCL oder KDL geschrieben werden. Jeder Schlüssel ist in der Konfigurationsreferenz beschrieben.