pingap

Prima che la versione di pingap sia stabile, non verrà accettata alcuna pull request. Se hai domande, crea prima una nuova issue.

Panoramica

Pingap è un reverse proxy ad alte prestazioni basato su Cloudflare Pingora. Semplifica la gestione operativa consentendo il ricaricamento a caldo dinamico della configurazione senza downtime tramite concisi file TOML e un'interfaccia web di amministrazione intuitiva.

La sua forza principale risiede in un potente sistema di plugin, che offre oltre venti funzionalità pronte all'uso per Autenticazione (JWT, Key Auth), Sicurezza (CSRF, Restrizioni IP/Referer/UA), Controllo del Traffico (Rate Limiting, Caching), Modifica dei Contenuti (Redirect, Sostituzione dei Contenuti) e Osservabilità (Request ID). Questo rende Pingap non solo un proxy, ma un gateway applicativo flessibile ed estensibile, progettato per gestire senza sforzo scenari complessi, dalla protezione delle API al deployment di moderne applicazioni web.

中文说明 | Documentazione · 中文文档 | Esempi | Plugin | 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"]

Caratteristiche Principali

• 🚀 Alte Prestazioni e Affidabilità

  • Costruito con Rust per la sicurezza della memoria e prestazioni di primo livello.
  • Basato su Cloudflare Pingora, una libreria di networking asincrono collaudata.
  • Supporta il proxying HTTP/1.1, HTTP/2 e gRPC-web.

• 🔧 Dinamico e Facile da Usare

  • Modifiche di configurazione senza downtime con ricaricamento a caldo.
  • File di configurazione TOML semplici e leggibili dall'uomo.
  • Web UI completa per una gestione intuitiva e in tempo reale.
  • Supporta sia file che etcd come backend di configurazione.
  • Supporta la cronologia delle configurazioni, con ripristino alla versione storica con un solo clic.

• 🧩 Potente Estensibilità

  • Un ricco sistema di plugin per gestire le comuni attività di gateway.
  • Routing avanzato con corrispondenza di host, path e regex.
  • Service discovery integrato tramite liste statiche, DNS o label Docker.
  • HTTPS automatizzato con Let's Encrypt (supporta sia le challenge HTTP-01 che DNS-01).

• 📊 Osservabilità Moderna

  • Metriche Prometheus native per il monitoraggio (modalità pull e push).
  • Supporto OpenTelemetry integrato per il tracing distribuito.
  • Access log altamente personalizzabili con oltre 30 variabili.
  • Fingerprint TLS client JA4 ({:ja4} negli access log, $ja4 negli header upstream) per distinguere i client in base al loro stack TLS, sia nelle build OpenSSL che rustls.
  • Metriche di prestazioni dettagliate, inclusi tempo di connessione upstream, tempo di elaborazione e altro ancora.

🚀 Per Iniziare

Il modo più semplice per iniziare con Pingap è usare Docker Compose.

1. Crea un file 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

2. Crea una directory dati ed esegui:

mkdir pingap_data
docker-compose up -d

3. Accedi alla Admin UI:

La tua istanza Pingap è ora in esecuzione! Puoi accedere all'interfaccia web di amministrazione all'indirizzo http://localhost/pingap con le credenziali che hai impostato.

Installare il binario tramite curl

Per Linux e macOS, puoi installare l'ultimo binario precompilato in /usr/local/bin/pingap con un solo comando:

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

Variabili d'ambiente opzionali:

• PINGAP_FULL=1 — installa la build -full (tutte le funzionalità opzionali abilitate)
• PINGAP_LIBC=gnu — su Linux, usa la build glibc invece della build statica musl predefinita
• PINGAP_TLS=rustls — su Linux, installa la build -rustls-full (backend TLS rustls, tutte le funzionalità opzionali, senza OpenSSL); vedi Backend TLS

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

Target supportati: Linux x86_64/arm64, Darwin x86_64/arm64. Vedi la pagina delle release per tutti gli asset disponibili.

Per istruzioni più dettagliate, inclusa l'esecuzione da binario, consulta la nostra Documentazione.

Avviare un proxy senza file di configurazione

Un singolo comando è sufficiente per servire un dominio in https e inoltrarlo a un backend:

# 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

Senza --cert, Pingap richiede un certificato a Let's Encrypt tramite la challenge HTTP-01, quindi pingap.io deve risolvere verso questo host e la porta 80 deve essere raggiungibile da internet. Il certificato emesso viene conservato in ~/.pingap/acme/<domains>.toml e riutilizzato al riavvio — l'emissione è soggetta a rate limit, quindi non eliminarlo. Tutto il resto proviene ancora dalla riga di comando: modificare --upstream ha effetto al successivo avvio senza toccare il certificato.

--cert accetta il certificato stesso o la directory che lo contiene — i layout comuni fullchain.pem / privkey.pem, cert.pem / key.pem e tls.crt / tls.key vengono rilevati automaticamente, usa --key per qualsiasi altro caso. Il listener predefinito è 0.0.0.0:443 quando c'è un certificato e 0.0.0.0:80 quando non c'è né un certificato né un dominio, e --addr lo sovrascrive. --upstream accetta una lista di backend separati da virgole, --domain una lista di host separati da virgole (omittilo per servire ogni host su http semplice). Le richieste per un host che non è elencato ricevono una risposta 404.

La configurazione viene generata a ogni avvio, quindi non può essere modificata tramite la admin UI: per qualsiasi cosa oltre a un singolo server usa --conf, che non può essere combinato con questi flag.

Configurazione Dinamica

Pingap è progettato per adattarsi ai cambiamenti di configurazione senza downtime.

Hot Reload (--autoreload): Per la maggior parte delle modifiche—come l'aggiornamento di upstream, location o plugin—Pingap applica la nuova configurazione entro 10 secondi senza riavvio. Questa è la modalità consigliata per ambienti containerizzati.

Graceful Restart (-a o --autorestart): Per modifiche fondamentali (come la modifica delle porte di ascolto del server), questa modalità esegue un riavvio completo senza downtime, garantendo che nessuna richiesta venga persa.