pingap

Antes de que la versión de pingap sea estable, no se aceptará ningún pull request. Si tienes alguna pregunta, por favor crea primero un nuevo issue.

Pingap Logo

Descripción general

Pingap es un proxy inverso de alto rendimiento impulsado por Cloudflare Pingora. Simplifica la gestión operativa al permitir la recarga en caliente de la configuración de forma dinámica y sin tiempo de inactividad mediante archivos TOML concisos y una interfaz web de administración intuitiva.

Su fortaleza principal radica en un potente sistema de plugins, que ofrece más de veinte funcionalidades listas para usar para Autenticación (JWT, Key Auth), Seguridad (CSRF, Restricciones de IP/Referer/UA), Control de Tráfico (Rate Limiting, Caching), Modificación de Contenido (Redirecciones, Sustitución de Contenido) y Observabilidad (Request ID). Esto hace que Pingap no sea solo un proxy, sino una puerta de enlace de aplicaciones flexible y extensible, diseñada para manejar sin esfuerzo escenarios complejos, desde la protección de API hasta despliegues de aplicaciones web modernas.

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

Características principales

🚀 Alto Rendimiento y Fiabilidad
- Construido con Rust para seguridad de memoria y rendimiento de primer nivel.
- Impulsado por Cloudflare Pingora, una biblioteca de redes asíncronas probada en batalla.
- Soporta proxy HTTP/1.1, HTTP/2 y gRPC-web.
🔧 Dinámico y Fácil de Usar
- Cambios de configuración sin tiempo de inactividad con recarga en caliente.
- Archivos de configuración TOML simples y legibles por humanos.
- Interfaz Web completa para una gestión intuitiva y en tiempo real.
- Soporta tanto archivos como etcd como backends de configuración.
- Soporta registro de historial de configuración, permite restaurar a la versión histórica con un solo clic.
🧩 Potente Extensibilidad
- Un rico sistema de plugins para manejar tareas comunes de puerta de enlace.
- Enrutamiento avanzado con coincidencia de host, ruta y regex.
- Descubrimiento de servicios integrado mediante listas estáticas, DNS o etiquetas de Docker.
- HTTPS automatizado con Let's Encrypt (soportando desafíos HTTP-01 y DNS-01).
📊 Observabilidad Moderna
- Métricas nativas de Prometheus para monitoreo (modos pull y push).
- Soporte integrado de OpenTelemetry para trazabilidad distribuida.
- Logs de acceso altamente personalizables con más de 30 variables.
- Huellas digitales de cliente TLS JA4 ({:ja4} en los logs de acceso, $ja4 en las cabeceras upstream) para distinguir clientes por su stack TLS, tanto en compilaciones OpenSSL como rustls.
- Métricas de rendimiento detalladas, incluyendo tiempo de conexión upstream, tiempo de procesamiento y más.

🚀 Primeros pasos

La forma más sencilla de empezar con Pingap es usando Docker Compose.

Crea un archivo 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

Crea un directorio de datos y ejecuta:

mkdir pingap_data
docker-compose up -d

Accede a la Interfaz de Administración:

¡Tu instancia de Pingap ya está en ejecución! Puedes acceder a la interfaz web de administración en http://localhost/pingap con las credenciales que configuraste.

Instalar el binario mediante curl

Para Linux y macOS, puedes instalar el último binario precompilado en /usr/local/bin/pingap con un solo comando:

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

Variables de entorno opcionales:

PINGAP_FULL=1 — instala la compilación -full (todas las características opcionales habilitadas)
PINGAP_LIBC=gnu — en Linux, usa la compilación glibc en lugar de la compilación estática musl predeterminada
PINGAP_TLS=rustls — en Linux, instala la compilación -rustls-full (backend TLS rustls, todas las características opcionales, sin OpenSSL); consulta TLS backend

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

Objetivos soportados: Linux x86_64/arm64, Darwin x86_64/arm64. Consulta la página de releases para todos los recursos disponibles.

Para instrucciones más detalladas, incluyendo la ejecución desde un binario, consulta nuestra Documentación.

Iniciar un proxy sin un archivo de configuración

Un solo comando es suficiente para servir un dominio sobre https y reenviarlo 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

Sin --cert, Pingap solicita un certificado a Let's Encrypt mediante el desafío HTTP-01, por lo que pingap.io debe resolverse a este host y el puerto 80 debe ser accesible desde internet. El certificado emitido se guarda en ~/.pingap/acme/<domains>.toml y se reutiliza al reiniciar — la emisión tiene límite de tasa, así que no lo elimines. Todo lo demás sigue viniendo de la línea de comandos: cambiar --upstream surte efecto en el siguiente inicio sin tocar el certificado.

--cert acepta el propio certificado o el directorio que lo contiene — los diseños comunes fullchain.pem / privkey.pem, cert.pem / key.pem y tls.crt / tls.key se detectan automáticamente, usa --key para cualquier otro. El listener por defecto es 0.0.0.0:443 cuando hay un certificado y 0.0.0.0:80 cuando no hay ni certificado ni dominio, y --addr lo sobrescribe. --upstream acepta una lista de backends separados por comas, --domain una lista de hosts separados por comas (omítelo para servir todos los hosts sobre http simple). Las solicitudes para un host que no está en la lista se responden con 404.

La configuración se genera en cada inicio, por lo que no se puede editar a través de la interfaz de administración: para cualquier cosa más allá de un solo servidor usa --conf, que no se puede combinar con estos flags.

Configuración Dinámica

Pingap está diseñado para adaptarse a los cambios de configuración sin tiempo de inactividad.

Hot Reload (--autoreload): Para la mayoría de los cambios —como actualizar upstreams, locations o plugins— Pingap aplica la nueva configuración en 10 segundos sin reiniciar. Este es el modo recomendado para entornos contenerizados.

pingap v0.13.7