pingap

Bevor die pingap-Version stabil ist, werden keine Pull Requests akzeptiert. Bei Fragen erstelle bitte zuerst ein neues Issue.

Überblick

Pingap ist ein hochperformanter Reverse-Proxy, angetrieben von Cloudflare Pingora. Er vereinfacht das Betriebsmanagement durch dynamisches, unterbrechungsfreies Hot-Reloading der Konfiguration über prägnante TOML-Dateien und eine intuitive Web-Admin-Oberfläche.

Seine Kernstärke liegt in einem leistungsstarken Plugin-System, das über zwanzig sofort einsatzbereite Funktionen für Authentifizierung (JWT, Key Auth), Sicherheit (CSRF, IP/Referer/UA-Einschränkungen), Verkehrssteuerung (Rate Limiting, Caching), Inhaltsänderung (Redirects, Content Substitution) und Observability (Request ID) bietet. Dadurch ist Pingap nicht nur ein Proxy, sondern ein flexibles und erweiterbares Application Gateway, das entwickelt wurde, um komplexe Szenarien von API-Schutz bis hin zu modernen Webanwendungs-Deployments mühelos zu bewältigen.

中文说明 | 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"]

Hauptmerkmale

• 🚀 Hohe Leistung & Zuverlässigkeit

  • Mit Rust entwickelt für Speichersicherheit und erstklassige Performance.
  • Angetrieben von Cloudflare Pingora, einer bewährten asynchronen Netzwerkbibliothek.
  • Unterstützt HTTP/1.1, HTTP/2 und gRPC-web-Proxying.

• 🔧 Dynamisch & einfach zu bedienen

  • Unterbrechungsfreie Konfigurationsänderungen mit Hot-Reloading.
  • Einfache, menschenlesbare TOML-Konfigurationsdateien.
  • Voll ausgestattete Web-UI für intuitive Echtzeitverwaltung.
  • Unterstützt sowohl Dateien als auch etcd als Konfigurations-Backends.
  • Unterstützt Konfigurationsverlauf, kann mit einem Klick auf die historische Version zurückgesetzt werden.

• 🧩 Leistungsstarke Erweiterbarkeit

  • Ein reichhaltiges Plugin-System für gängige Gateway-Aufgaben.
  • Fortgeschrittenes Routing mit Host-, Pfad- und Regex-Matching.
  • Integrierte Service-Discovery über statische Listen, DNS oder Docker-Labels.
  • Automatisiertes HTTPS mit Let's Encrypt (unterstützt sowohl HTTP-01- als auch DNS-01-Challenges).

• 📊 Moderne Observability

  • Native Prometheus-Metriken zur Überwachung (Pull- & Push-Modus).
  • Integrierte OpenTelemetry-Unterstützung für verteiltes Tracing.
  • Hochgradig anpassbare Access-Logs mit über 30 Variablen.
  • JA4-TLS-Client-Fingerprints ({:ja4} in Access-Logs, $ja4 in Upstream-Headern), um Clients anhand ihres TLS-Stacks zu unterscheiden, sowohl bei OpenSSL- als auch bei rustls-Builds.
  • Detaillierte Performance-Metriken, einschließlich Upstream-Verbindungszeit, Verarbeitungszeit und mehr.

🚀 Erste Schritte

Der einfachste Weg, mit Pingap zu beginnen, ist die Verwendung von Docker Compose.

1. Erstelle eine docker-compose.yml-Datei:

# 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. Erstelle ein Datenverzeichnis und starte:

mkdir pingap_data
docker-compose up -d

3. Greife auf die Admin-UI zu:

Deine Pingap-Instanz läuft jetzt! Du kannst auf die Web-Admin-Oberfläche unter http://localhost/pingap mit den von dir festgelegten Anmeldedaten zugreifen.

Installation der Binärdatei über curl

Für Linux und macOS kannst du die neueste vorgefertigte Binärdatei mit einem Befehl nach /usr/local/bin/pingap installieren:

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

Optionale Umgebungsvariablen:

• PINGAP_FULL=1 — installiert den -full-Build (alle optionalen Features aktiviert)
• PINGAP_LIBC=gnu — unter Linux den glibc-Build anstelle des standardmäßigen musl-Static-Builds verwenden
• PINGAP_TLS=rustls — unter Linux den -rustls-full-Build installieren (rustls-TLS-Backend, alle optionalen Features, kein OpenSSL); siehe TLS-Backend

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

Unterstützte Ziele: Linux x86_64/arm64, Darwin x86_64/arm64. Siehe die Releases-Seite für alle verfügbaren Assets.

Für detailliertere Anweisungen, einschließlich der Ausführung aus einer Binärdatei, schaue in unsere Dokumentation.

Starte einen Proxy ohne Konfigurationsdatei

Ein einziger Befehl genügt, um eine Domain über https bereitzustellen und sie an ein Backend weiterzuleiten:

# 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

Ohne --cert fragt Pingap Let's Encrypt über die HTTP-01-Challenge nach einem Zertifikat, daher muss pingap.io auf diesen Host auflösen und Port 80 aus dem Internet erreichbar sein. Das ausgestellte Zertifikat wird in ~/.pingap/acme/<domains>.toml aufbewahrt und beim Neustart wiederverwendet — die Ausstellung ist ratenbegrenzt, lösche es also nicht. Alles andere kommt weiterhin von der Kommandozeile: Eine Änderung von --upstream wird beim nächsten Start wirksam, ohne das Zertifikat anzufassen.

--cert akzeptiert das Zertifikat selbst oder das Verzeichnis, das es enthält — die gängigen Layouts fullchain.pem / privkey.pem, cert.pem / key.pem und tls.crt / tls.key werden automatisch erkannt, verwende --key für alles andere. Der Listener ist standardmäßig 0.0.0.0:443, wenn ein Zertifikat vorhanden ist, und 0.0.0.0:80, wenn weder ein Zertifikat noch eine Domain vorhanden ist, und --addr überschreibt dies. --upstream nimmt eine kommagetrennte Liste von Backends, --domain eine kommagetrennte Liste von Hosts (weglassen, um jeden Host über einfaches http bereitzustellen). Anfragen für einen Host, der nicht aufgeführt ist, werden mit 404 beantwortet.

Die Konfiguration wird bei jedem Start generiert, kann also nicht über die Admin-UI bearbeitet werden: Für alles jenseits eines einzelnen Servers verwende --conf, was nicht mit diesen Flags kombiniert werden kann.

Dynamische Konfiguration

Pingap ist darauf ausgelegt, sich an Konfigurationsänderungen ohne Ausfallzeiten anzupassen.

Hot Reload (--autoreload): Für die meisten Änderungen — wie das Aktualisieren von Upstreams, Locations oder Plugins — wendet Pingap die neue Konfiguration innerhalb von 10 Sekunden ohne Neustart an. Dies ist der empfohlene Modus für containerisierte Umgebungen.