pingap v0.13.10
Un proxy inverso como nginx, construido sobre pingora, simple y eficiente.
pingap
Antes de que la versión de pingap sea estable, no se aceptarán pull requests. Si tienes alguna pregunta, crea un nuevo issue primero.
Resumen
Pingap es un proxy inverso de alto rendimiento impulsado por Cloudflare Pingora. Simplifica la gestión operativa al permitir la recarga en caliente dinámica y sin tiempo de inactividad de la configuración a través de archivos TOML concisos y una interfaz de administración web intuitiva.
Su fortaleza principal reside en un potente sistema de plugins, que ofrece más de veinte funciones listas para usar para Autenticación (JWT, Key Auth), Seguridad (CSRF, Restricciones de IP/Referer/UA), Control de Tráfico (Limitación de Tasa, Caching), Modificación de Contenido (Redirecciones, Sustitución de Contenido) y Observabilidad (ID de Solicitud). Esto hace de Pingap no 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 implementaciones modernas de aplicaciones web.
English Description | Documentación · Documentación en chino | Ejemplos | Plugins | Crates
flowchart LR
internet("Internet") -- solicitud --> 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 Clave
-
🚀 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íncrona 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.
- Interfaz web completa para gestión intuitiva en tiempo real.
- Soporta tanto archivos como etcd como backend de configuración.
- Soporta registro histórico de configuraciones, pudiendo restaurar a una versión histórica con un clic.
-
🧩 Extensibilidad Poderosa
- Un rico sistema de plugins para manejar tareas comunes de puerta de enlace.
- Enrutamiento avanzado con coincidencia de host, ruta y expresiones regulares.
- Descubrimiento de servicios integrado a través de listas estáticas, DNS o etiquetas Docker.
- HTTPS automatizado con Let's Encrypt (soporta desafíos HTTP-01 y DNS-01).
-
📊 Observabilidad Moderna
- Métricas Prometheus nativas para monitoreo (modos pull y push).
- Soporte integrado de OpenTelemetry para trazado distribuido.
- Registros de acceso altamente personalizables con más de 30 variables.
- Métricas de rendimiento detalladas, incluyendo tiempo de conexión ascendente, tiempo de procesamiento y más.
🚀 Primeros Pasos
La forma más fácil de comenzar con Pingap es usando Docker Compose.
- Crea un archivo
docker-compose.yml:
# docker-compose.yml
version: '3.8'
services:
pingap:
image: vicanso/pingap:latest # Para producción, usa una versión específica como vicanso/pingap:0.12.1-full
container_name: pingap-instance
restart: always
ports:
- "80:80"
- "443:443"
volumes:
# Monta un directorio local para persistir todas las configuraciones y datos
- ./pingap_data:/opt/pingap
environment:
# Configurar usando variables de entorno
- PINGAP_CONF=/opt/pingap/conf
- PINGAP_ADMIN_ADDR=0.0.0.0:80/pingap
- PINGAP_ADMIN_USER=pingap
- PINGAP_ADMIN_PASSWORD=<TuContraseñaSegura> # ¡Cambia esto!
command:
# Inicia pingap y habilita la recarga en caliente
- 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á funcionando! Puedes acceder a la interfaz web de administración en http://localhost/pingap con las credenciales que estableciste.
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 funciones opcionales habilitadas)PINGAP_LIBC=gnu— en Linux, usa la compilación glibc en lugar de la compilación estática musl predeterminada
# Compilación con todas las funciones
curl -sSL https://raw.githubusercontent.com/vicanso/pingap/main/install.sh | PINGAP_FULL=1 sh
Destinos compatibles: Linux x86_64/arm64, Darwin x86_64/arm64. Consulta la página de versiones para todos los activos disponibles.
Para instrucciones más detalladas, incluyendo la ejecución desde un binario, consulta nuestra Documentación.
Iniciar un proxy sin archivo de configuración
Un solo comando es suficiente para servir un dominio a través de https y reenviarlo a un backend:
# certificado solicitado a let's encrypt
pingap --domain=pingap.io --upstream=192.168.1.1:3000
# o usa tu propio certificado
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 a través del
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 proviene de la línea de comandos: cambiar
--upstream surte efecto en el próximo inicio sin tocar el certificado.
--cert acepta el certificado en sí 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 caso. El listener
predeterminado 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 anula. --upstream
toma una lista separada por comas de backends, --domain una lista separada por comas de
hosts (omítelo para servir a todos los hosts a través de http simple).
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 algo más que un solo servidor usa --conf, que no se puede
combinar con estos indicadores.
Configuración Dinámica
Pingap está diseñado para adaptarse a los cambios de configuración sin tiempo de inactividad.
Recarga en Caliente (--autoreload): Para la mayoría de los cambios, como actualizar upstreams, ubicaciones o plugins, Pingap aplica la nueva configuración en 10 segundos sin reiniciar. Este es el modo recomendado para entornos contenedorizados.
Reinicio Gradual (-a o --autorestart): Para cambios fundamentales (como modificar los puertos de escucha del servidor), este modo realiza un reinicio completo sin tiempo de inactividad, asegurando que no se pierdan solicitudes.
🔧 Desarrollo
make dev
Si necesitas una interfaz de administración web, debes instalar nodejs y construir los assets web.
# generar asset de administración web
cd web
npm i
cd ..
make build-web
📝 Configuración
server "test" {
addr = "127.0.0.1:6118"
location "github-api" {
path = "/api"
proxy_set_headers = ["Host:api.github.com"]
rewrite = "^/api/(?<path>.+)$ /$1"
upstream "api" {
addrs = ["api.github.com:443"]
discovery = "dns"
sni = "api.github.com"
}
}
location "static" {
plugin "staticServe" {
category = "directory"
path = "~/Downloads"
step = "request"
}
}
}
[upstreams.api]
addrs = ["api.github.com:443"]
discovery = "dns"
sni = "api.github.com"
[plugins.staticServe]
category = "directory"
path = "~/Downloads"
step = "request"
[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"]
Puedes encontrar las instrucciones relevantes aquí: https://pingap.io/crates/config.
🔄 Paso de Proxy
graph TD;
server["Servidor HTTP"];
locationA["Ubicación A"];
locationB["Ubicación B"];
locationPluginListA["Lista de Plugins Proxy A"];
locationPluginListB["Lista de Plugins Proxy B"];
upstreamA1["Upstream A1"];
upstreamA2["Upstream A2"];
upstreamB1["Upstream B1"];
upstreamB2["Upstream B2"];
locationResponsePluginListA["Lista de Plugins de Respuesta A"];
locationResponsePluginListB["Lista de Plugins de Respuesta B"];
start("Nueva Solicitud") --> server
server -- "host:HostA, Path:/api/*" --> locationA
server -- "Path:/rest/*"--> locationB
locationA -- "Ejecutar Plugins Proxy" --> locationPluginListA
locationB -- "Ejecutar Plugins Proxy" --> locationPluginListB
locationPluginListA -- "proxy pass: 10.0.0.1:8001" --> upstreamA1
locationPluginListA -- "proxy pass: 10.0.0.2:8001" --> upstreamA2
locationPluginListA -- "hecho" --> response
locationPluginListB -- "proxy pass: 10.0.0.1:8002" --> upstreamB1
locationPluginListB -- "proxy pass: 10.0.0.2:8002" --> upstreamB2
locationPluginListB -- "hecho" --> response
upstreamA1 -- "Ejecutar Plugins de Respuesta" --> locationResponsePluginListA
upstreamA2 -- "Ejecutar Plugins de Respuesta" --> locationResponsePluginListA
upstreamB1 -- "Ejecutar Plugins de Respuesta" --> locationResponsePluginListB
upstreamB2 -- "Ejecutar Plugins de Respuesta" --> locationResponsePluginListB
locationResponsePluginListA --> response
locationResponsePluginListB --> response
response["Respuesta HTTP"] --> stop("Registro");
📊 Rendimiento
CPU: M4 Pro, Hilo: 1
Ping sin registro de acceso
wrk 'http://127.0.0.1:6118/ping' --latency
Running 10s test @ http://127.0.0.1:6118/ping
2 threads and 10 connections
Thread Stats Avg Stdev Max +/- Stdev
Latency 66.41us 23.67us 1.11ms 76.54%
Req/Sec 73.99k 2.88k 79.77k 68.81%
Latency Distribution
50% 67.00us
75% 80.00us
90% 91.00us
99% 116.00us
1487330 requests in 10.10s, 194.32MB read
Requests/sec: 147260.15
Transfer/sec: 19.24MB
📦 Versión de Rust
Nuestro MSRV actual es 1.88
📄 Licencia
Este proyecto está licenciado bajo Apache License, Version 2.0.