Pingap

Un proxy inverso y gateway de aplicaciones construido sobre Cloudflare Pingora. Se configura mediante archivos TOML o a través de un panel de administración web que forma parte del binario, aplica los cambios sin reiniciar y viene con más de treinta plugins.

Las solicitudes de internet pasan por Pingap, que las enruta por host y ruta a grupos de servidores upstream

Qué lo distingue

Un panel de administración web en el binario. Cada ajuste tiene un formulario. Un cambio se valida de la misma forma en que pingap -t lo comprueba antes de almacenarse, las versiones anteriores pueden conservarse y restaurarse, y existen cuentas de solo lectura y tokens de API. Su página de inicio muestra gráficas del tráfico de los últimos quince minutos: tasa, estado, latencia, cada upstream, sin Prometheus.
Cambios sin tiempo de inactividad. Los upstreams, las ubicaciones, los plugins y los certificados se reemplazan en el proceso en ejecución (--autoreload). Lo que requiere nuevos listeners se aplica mediante un reinicio que transfiere los sockets (--autorestart, para un daemon en Linux), y el proceso en ejecución sigue sirviendo si su reemplazo no arranca.
Más de treinta plugins, por ubicación y en el orden en que los enumeres: autenticación (JWT, OIDC, key, basic, HMAC, forward auth), reglas de acceso (IP, referer, user agent, rutas bloqueadas), tráfico (límites de tasa y ancho de banda, caché, mirroring, división de tráfico), contenido (compresión, sustitución de cuerpo, redirecciones, archivos estáticos, optimización de imágenes) y operaciones (modo mantenimiento, endpoint de salud, páginas de error). Todos los plugins
Certificados sin cron job. Let's Encrypt o cualquier otra CA ACME, mediante HTTP-01 o DNS-01 (Alibaba Cloud, Cloudflare, Tencent Cloud, Huawei Cloud), RSA y ECDSA en paralelo, OCSP stapling, y TLS mutuo hacia los clientes y hacia los upstreams.
Configuración que se comprueba antes de ejecutarse. -t construye todo lo que construiría un arranque, --strict rechaza las claves que no conoce, --diff muestra qué haría un cambio. TOML, HCL o KDL, en archivos o en etcd, con secretos tomados del entorno o de archivos.
Diseñado para ser observado. Métricas de Prometheus (pull y push), trazas de OpenTelemetry, logs de acceso en texto o JSON con más de treinta campos, y huellas TLS JA4 de los clientes.

El resto de lo que hace un proxy inverso también está presente: HTTP/1.1, HTTP/2, WebSocket y gRPC-web; enrutamiento por host, ruta y expresión regular; round robin, least connections, consistent hashing y sesiones persistentes, con health checks, reintentos y un circuit breaker; backends desde DNS (A/AAAA, SRV) o etiquetas de Docker; el protocolo PROXY en los listeners y hacia los upstreams; OpenSSL o rustls.

Las métricas, el tracing y la optimización de imágenes están en las compilaciones -full.

🚀 Primeros pasos

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

El administrador está en http://localhost/pingap. Las imágenes están etiquetadas como latest, full y rustls-full, y <version>, <version>-full, <version>-rustls-full para una versión. Cada una también tiene una variante -distroless sin shell, donde command debe comenzar con pingap como se muestra arriba.

Binario

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

instala la última versión en /usr/local/bin/pingap en Linux y macOS (x86_64 y arm64). Las variables delante de sh eligen qué se instala:

Variable	Efecto
`PINGAP_FULL=1`	La compilación `-full`, con todas las características opcionales
`PINGAP_TLS=rustls`	Linux: la compilación `-rustls-full`, sin OpenSSL (ver TLS backend)
`PINGAP_LIBC=gnu`	Linux: la compilación glibc en lugar de la estática musl
`PINGAP_SERVICE=1`	Linux con systemd: también el servicio `pingap` y una configuración inicial en `/etc/pingap/conf`; no se habilita ni se inicia
`PINGAP_VERSION=0.15.0`	Esa versión en lugar de la última

Todos los recursos están en la página de releases.

Un comando, sin archivo de configuración

# 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

Sin --cert, el certificado se solicita mediante HTTP-01: el dominio debe resolverse a este host, con el puerto 80 accesible. Se guarda en ~/.pingap/acme/<domains>.toml y se reutiliza en el siguiente arranque. No lo elimine, la emisión está limitada por tasa.
--cert es el certificado o el directorio en el que se encuentra (se buscan fullchain.pem / privkey.pem, cert.pem / key.pem y tls.crt / tls.key; --key nombra cualquier otro). --upstream y --domain aceptan listas separadas por comas, --addr la dirección en la que escuchar.
La configuración se crea de nuevo en cada arranque, por lo que el administrador no puede editarla. Para más de un servidor use --conf, que no se puede combinar con estas flags.

📝 Configuración

[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 mismo puede escribirse en HCL o KDL. Cada clave se describe en la referencia de configuración.

pingap v0.13.8