pingap

Avant que la version de pingap ne soit stable, aucune pull request ne sera acceptée. Si vous avez des questions, veuillez d'abord créer une nouvelle issue.

Aperçu

Pingap est un reverse proxy haute performance propulsé par Cloudflare Pingora. Il simplifie la gestion opérationnelle en permettant le rechargement à chaud dynamique de la configuration sans interruption de service, via des fichiers TOML concis et une interface d'administration web intuitive.

Sa force principale réside dans un puissant système de plugins, offrant plus de vingt fonctionnalités prêtes à l'emploi pour l'authentification (JWT, Key Auth), la sécurité (CSRF, restrictions IP/Referer/UA), le contrôle du trafic (limitation de débit, mise en cache), la modification de contenu (redirections, substitution de contenu) et l'observabilité (Request ID). Cela fait de Pingap non pas un simple proxy, mais une passerelle applicative flexible et extensible, conçue pour gérer sans effort des scénarios complexes, de la protection d'API au déploiement d'applications web modernes.

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

Fonctionnalités clés

• 🚀 Haute performance et fiabilité

  • Développé en Rust pour la sécurité mémoire et des performances de premier ordre.
  • Propulsé par Cloudflare Pingora, une bibliothèque réseau asynchrone éprouvée.
  • Prend en charge le proxy HTTP/1.1, HTTP/2 et gRPC-web.

• 🔧 Dynamique et facile à utiliser

  • Modifications de configuration sans interruption de service grâce au rechargement à chaud.
  • Fichiers de configuration TOML simples et lisibles par l'humain.
  • Interface web complète pour une gestion intuitive et en temps réel.
  • Prend en charge les fichiers et etcd comme backends de configuration.
  • Prend en charge l'historique des configurations, avec restauration en un clic vers une version antérieure.

• 🧩 Extensibilité puissante

  • Un riche système de plugins pour gérer les tâches courantes de passerelle.
  • Routage avancé avec correspondance par hôte, chemin et expression régulière.
  • Découverte de services intégrée via des listes statiques, DNS ou labels Docker.
  • HTTPS automatisé avec Let's Encrypt (prise en charge des défis HTTP-01 et DNS-01).

• 📊 Observabilité moderne

  • Métriques Prometheus natives pour la supervision (modes pull et push).
  • Prise en charge intégrée d'OpenTelemetry pour le tracing distribué.
  • Journaux d'accès hautement personnalisables avec plus de 30 variables.
  • Empreintes TLS client JA4 ({:ja4} dans les journaux d'accès, $ja4 dans les en-têtes upstream) pour distinguer les clients par leur pile TLS, aussi bien sur les builds OpenSSL que rustls.
  • Métriques de performance détaillées, incluant le temps de connexion upstream, le temps de traitement, et plus encore.

🚀 Démarrage

La façon la plus simple de démarrer avec Pingap est d'utiliser Docker Compose.

1. Créez un fichier 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. Créez un répertoire de données et lancez :

mkdir pingap_data
docker-compose up -d

3. Accédez à l'interface d'administration :

Votre instance Pingap est maintenant en cours d'exécution ! Vous pouvez accéder à l'interface d'administration web à l'adresse http://localhost/pingap avec les identifiants que vous avez définis.

Installer le binaire via curl

Pour Linux et macOS, vous pouvez installer le dernier binaire précompilé dans /usr/local/bin/pingap avec une seule commande :

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

Variables d'environnement optionnelles :

• PINGAP_FULL=1 — installe le build -full (toutes les fonctionnalités optionnelles activées)
• PINGAP_LIBC=gnu — sous Linux, utilise le build glibc au lieu du build statique musl par défaut
• PINGAP_TLS=rustls — sous Linux, installe le build -rustls-full (backend TLS rustls, toutes les fonctionnalités optionnelles, sans OpenSSL) ; voir Backend TLS

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

Cibles prises en charge : Linux x86_64/arm64, Darwin x86_64/arm64. Consultez la page des releases pour tous les assets disponibles.

Pour des instructions plus détaillées, notamment pour exécuter depuis un binaire, consultez notre Documentation.

Démarrer un proxy sans fichier de configuration

Une seule commande suffit pour servir un domaine en https et le rediriger vers 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

Sans --cert, Pingap demande un certificat à Let's Encrypt via le défi HTTP-01, donc pingap.io doit résoudre vers cet hôte et le port 80 doit être accessible depuis Internet. Le certificat émis est conservé dans ~/.pingap/acme/<domains>.toml et réutilisé au redémarrage — l'émission est limitée en débit, donc ne le supprimez pas. Tout le reste provient toujours de la ligne de commande : modifier --upstream prend effet au prochain démarrage sans toucher au certificat.

--cert accepte le certificat lui-même ou le répertoire qui le contient — les dispositions courantes fullchain.pem / privkey.pem, cert.pem / key.pem et tls.crt / tls.key sont détectées automatiquement, utilisez --key pour tout autre cas. L'écouteur utilise par défaut 0.0.0.0:443 lorsqu'il y a un certificat et 0.0.0.0:80 lorsqu'il n'y a ni certificat ni domaine, et --addr le remplace. --upstream accepte une liste de backends séparés par des virgules, --domain une liste d'hôtes séparés par des virgules (omettez-le pour servir tous les hôtes en http simple). Les requêtes pour un hôte non listé reçoivent une réponse 404.

La configuration est générée à chaque démarrage, elle ne peut donc pas être modifiée via l'interface d'administration : pour tout ce qui dépasse un seul serveur, utilisez --conf, qui ne peut pas être combiné avec ces options.

Configuration dynamique

Pingap est conçu pour s'adapter aux changements de configuration sans interruption de service.