Pingap

Un proxy inverse et une passerelle applicative construits sur Cloudflare Pingora. Il se configure via des fichiers TOML ou une interface d'administration web intégrée au binaire, prend les modifications en compte sans redémarrage, et est livré avec plus de trente plugins.

中文说明 | Documentation · 中文文档 | Exemples | Plugins | Crates | Mise à niveau

Ce qui le distingue

• Une interface d'administration web intégrée au binaire. Chaque paramètre dispose d'un formulaire. Une modification est vérifiée de la même manière que pingap -t la vérifie avant d'être enregistrée, les versions antérieures peuvent être conservées et restaurées, et il existe des comptes en lecture seule et des jetons d'API. Sa page d'accueil affiche les graphiques du trafic des quinze dernières minutes - débit, statuts, latence, chaque amont - sans Prometheus.
• Des modifications sans interruption de service. Les amonts, les emplacements, les plugins et les certificats sont remplacés dans le processus en cours d'exécution (--autoreload). Ce qui nécessite de nouveaux écouteurs est appliqué par un redémarrage qui transfère les sockets (--autorestart, pour un démon sous Linux), et le processus en cours continue de servir si son remplaçant ne démarre pas.
• Plus de trente plugins, par emplacement et dans l'ordre où vous les listez : authentification (JWT, OIDC, clé, basic, HMAC, forward auth), règles d'accès (IP, referer, user agent, chemins bloqués), trafic (limites de débit et de bande passante, cache, mise en miroir, répartition du trafic), contenu (compression, substitution du corps, redirections, fichiers statiques, optimisation d'images) et opérations (mode maintenance, endpoint de santé, pages d'erreur). Tous les plugins
• Des certificats sans tâche cron. Let's Encrypt ou toute autre AC ACME, par HTTP-01 ou DNS-01 (Alibaba Cloud, Cloudflare, Tencent Cloud, Huawei Cloud), RSA et ECDSA côte à côte, OCSP stapling, et TLS mutuel envers les clients et envers les amonts.
• Une configuration vérifiée avant d'être exécutée. -t construit tout ce qu'un démarrage construirait, --strict refuse les clés qu'il ne connaît pas, --diff montre ce qu'une modification ferait. TOML, HCL ou KDL, dans des fichiers ou dans etcd, avec des secrets issus de l'environnement ou de fichiers.
• Conçu pour être surveillé. Métriques Prometheus (pull et push), traces OpenTelemetry, journaux d'accès en texte ou JSON avec plus de trente champs, et empreintes TLS JA4 des clients.

Le reste de ce que fait un proxy inverse est également présent : HTTP/1.1, HTTP/2, WebSocket et gRPC-web ; routage par hôte, chemin et expression régulière ; round robin, least connections, hachage cohérent et sessions persistantes, avec contrôles de santé, tentatives et disjoncteur ; backends issus du DNS (A/AAAA, SRV) ou des labels Docker ; le protocole PROXY sur les écouteurs et vers les amonts ; OpenSSL ou rustls.

Les métriques, le traçage et l'optimisation d'images sont dans les builds -full.

🚀 Démarrage

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'interface d'administration se trouve à l'adresse http://localhost/pingap. Les images sont étiquetées latest, full et rustls-full, ainsi que <version>, <version>-full, <version>-rustls-full pour une version publiée. Chacune possède également une variante -distroless sans shell, où command doit commencer par pingap comme ci-dessus.

Binaire

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

installe la dernière version dans /usr/local/bin/pingap sous Linux et macOS (x86_64 et arm64). Les variables placées devant sh déterminent ce qui est installé :

Variable	Effet
PINGAP_FULL=1	La build -full, avec toutes les fonctionnalités optionnelles
PINGAP_TLS=rustls	Linux : la build -rustls-full, sans OpenSSL (voir TLS backend)
PINGAP_LIBC=gnu	Linux : la build glibc à la place de celle statique musl
PINGAP_SERVICE=1	Linux avec systemd : également le service pingap et une configuration de démarrage dans /etc/pingap/conf ; il n'est ni activé ni démarré
PINGAP_VERSION=0.15.0	Cette version à la place de la dernière

Tous les assets sont sur la page des releases.

Une seule commande, aucun fichier de configuration

# 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

• Sans --cert, le certificat est commandé via HTTP-01 : le domaine doit résoudre vers cet hôte, avec le port 80 accessible. Il est conservé dans ~/.pingap/acme/<domains>.toml et réutilisé au démarrage suivant. Ne le supprimez pas, l'émission est soumise à des limites de débit.
• --cert est le certificat ou le répertoire dans lequel il se trouve (fullchain.pem / privkey.pem, cert.pem / key.pem et tls.crt / tls.key sont détectés ; --key désigne tout autre nom). --upstream et --domain prennent des listes séparées par des virgules, --addr l'adresse d'écoute.
• La configuration est recréée à chaque démarrage, l'administrateur ne peut donc pas la modifier. Pour plus d'un serveur, utilisez --conf, avec lequel ces options ne peuvent pas être combinées.

📝 Configuration

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

La même chose peut être écrite en HCL ou en KDL. Chaque clé est décrite dans la référence de configuration.