Pingap

Un reverse proxy e application gateway basato su Cloudflare Pingora. Si configura tramite file TOML o un'interfaccia web di amministrazione integrata nel binario, applica le modifiche senza riavvio e viene fornito con più di trenta plugin.

中文说明 | Documentazione · Documentazione in cinese | Esempi | Plugin | Crates | Aggiornamento

Cosa lo distingue

• Un'interfaccia web di amministrazione nel binario. Ogni impostazione ha un modulo. Una modifica viene verificata come farebbe pingap -t prima di essere salvata, le versioni precedenti possono essere conservate e ripristinate, e sono disponibili account in sola lettura e token API. La sua pagina iniziale mostra grafici del traffico degli ultimi quindici minuti - frequenza, stato, latenza, ogni upstream - senza Prometheus.
• Modifiche senza downtime. Upstream, location, plugin e certificati vengono sostituiti nel processo in esecuzione (--autoreload). Ciò che richiede nuovi listener viene applicato tramite un riavvio che passa i socket al nuovo processo (--autorestart, per un demone su Linux), e il processo in esecuzione continua a servire se il suo sostituto non si avvia.
• Oltre trenta plugin, per location e nell'ordine in cui li elenchi: autenticazione (JWT, OIDC, key, basic, HMAC, forward auth), regole di accesso (IP, referer, user agent, percorsi bloccati), traffico (limiti di frequenza e larghezza di banda, cache, mirroring, suddivisione del traffico), contenuto (compressione, sostituzione del body, redirect, file statici, ottimizzazione delle immagini) e operazioni (modalità manutenzione, endpoint di health, pagine di errore). Tutti i plugin
• Certificati senza cron job. Let's Encrypt o qualsiasi altra CA ACME, tramite HTTP-01 o DNS-01 (Alibaba Cloud, Cloudflare, Tencent Cloud, Huawei Cloud), RSA ed ECDSA affiancati, OCSP stapling e mutual TLS verso i client e verso gli upstream.
• Configurazione verificata prima dell'esecuzione. -t costruisce tutto ciò che farebbe un avvio, --strict rifiuta le chiavi che non conosce, --diff mostra cosa farebbe una modifica. TOML, HCL o KDL, in file o in etcd, con segreti presi dall'ambiente o da file.
• Progettato per essere monitorato. Metriche Prometheus (pull e push), tracce OpenTelemetry, log di accesso in testo o JSON con più di trenta campi e impronte TLS JA4 dei client.

C'è anche tutto il resto di ciò che fa un reverse proxy: HTTP/1.1, HTTP/2, WebSocket e gRPC-web; routing per host, percorso ed espressione regolare; round robin, least connections, consistent hashing e sticky sessions, con health check, retry e circuit breaker; backend da DNS (A/AAAA, SRV) o etichette Docker; il protocollo PROXY sui listener e verso gli upstream; OpenSSL o rustls.

Metriche, tracing e ottimizzazione delle immagini sono nelle build -full.

🚀 Per iniziare

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

L'amministratore si trova su http://localhost/pingap. Le immagini sono taggate latest, full e rustls-full, e <version>, <version>-full, <version>-rustls-full per una release. Ognuna ha anche una gemella -distroless senza shell, dove command deve iniziare con pingap come sopra.

Binario

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

installa l'ultima release in /usr/local/bin/pingap su Linux e macOS (x86_64 e arm64). Le variabili anteposte a sh scelgono cosa viene installato:

Variabile	Effetto
PINGAP_FULL=1	La build -full, con tutte le funzionalità opzionali
PINGAP_TLS=rustls	Linux: la build -rustls-full, senza OpenSSL (vedi TLS backend)
PINGAP_LIBC=gnu	Linux: la build glibc al posto di quella statica musl
PINGAP_SERVICE=1	Linux con systemd: anche il servizio pingap e una configurazione iniziale in /etc/pingap/conf; non viene abilitato né avviato
PINGAP_VERSION=0.15.0	Quella release al posto dell'ultima

Tutti gli asset sono nella pagina delle release.

Un solo comando, nessun file di configurazione

# 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

• Senza --cert il certificato viene richiesto tramite HTTP-01: il dominio deve risolvere verso questo host, con la porta 80 raggiungibile. Viene conservato in ~/.pingap/acme/<domains>.toml e riutilizzato al successivo avvio. Non eliminarlo, l'emissione è soggetta a limiti di frequenza.
• --cert è il certificato o la directory in cui si trova (fullchain.pem / privkey.pem, cert.pem / key.pem e tls.crt / tls.key vengono trovati; --key indica qualsiasi altro nome). --upstream e --domain accettano elenchi separati da virgole, --addr l'indirizzo su cui ascoltare.
• La configurazione viene creata ex novo a ogni avvio, quindi l'amministratore non può modificarla. Per più di un server usare --conf, che non può essere combinato con questi flag.

📝 Configurazione

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

Lo stesso può essere scritto in HCL o KDL. Ogni chiave è descritta nella riferimento di configurazione.