pingap

Antes que a versão do pingap esteja estável, nenhum pull request será aceito. Se você tiver alguma dúvida, crie uma nova issue primeiro.

Visão Geral

O Pingap é um proxy reverso de alto desempenho alimentado pelo Cloudflare Pingora . Ele simplifica o gerenciamento operacional ao permitir recarga a quente de configuração dinâmica, sem tempo de inatividade, por meio de arquivos TOML concisos e uma interface de administração web intuitiva.

Sua principal força está em um poderoso sistema de plugins, que oferece mais de vinte recursos prontos para uso para Autenticação (JWT, Key Auth), Segurança (CSRF, Restrições de IP/Referer/UA), Controle de Tráfego (Limitação de Taxa, Cache), Modificação de Conteúdo (Redirecionamentos, Substituição de Conteúdo) e Observabilidade (Request ID). Isso torna o Pingap não apenas um proxy, mas um gateway de aplicação flexível e extensível, projetado para lidar facilmente com cenários complexos, desde proteção de APIs até implantações modernas de aplicações web.

中文说明 | Documentação · 中文文档 | Exemplos | 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"]

Principais Recursos

• 🚀 Alto Desempenho e Confiabilidade

  • Construído em Rust para segurança de memória e desempenho de primeira linha.
  • Alimentado por Cloudflare Pingora, uma biblioteca de rede assíncrona comprovada em produção.
  • Suporta proxy HTTP/1.1, HTTP/2 e gRPC-web.

• 🔧 Dinâmico e Fácil de Usar

  • Alterações de configuração sem tempo de inatividade com recarga a quente.
  • Arquivos de configuração TOML simples e legíveis.
  • Interface Web completa para gerenciamento intuitivo em tempo real.
  • Suporta arquivo e etcd como backends de configuração.
  • Suporta registro de histórico de configuração, permitindo restaurar para a versão histórica com um clique.

• 🧩 Poderosa Extensibilidade

  • Um sistema de plugins rico para lidar com tarefas comuns de gateway.
  • Roteamento avançado com correspondência por host, caminho e regex.
  • Descoberta de serviços integrada por meio de listas estáticas, DNS ou rótulos Docker.
  • HTTPS automatizado com Let's Encrypt (suportando desafios HTTP-01 e DNS-01).

• 📊 Observabilidade Moderna

  • Métricas nativas do Prometheus para monitoramento (modos pull e push).
  • Suporte integrado ao OpenTelemetry para rastreamento distribuído.
  • Logs de acesso altamente personalizáveis com mais de 30 variáveis.
  • Métricas de desempenho detalhadas, incluindo tempo de conexão com o upstream, tempo de processamento e mais.

🚀 Começando

A maneira mais fácil de começar a usar o Pingap é utilizando o Docker Compose.

1. Crie um arquivo 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. Crie um diretório de dados e execute:

mkdir pingap_data
docker-compose up -d

3. Acesse a interface de administração:

Sua instância do Pingap está agora em execução! Você pode acessar a interface de administração web em http://localhost/pingap com as credenciais que você definiu.

Instalar o binário via curl

Para Linux e macOS, você pode instalar o último binário pré-compilado em /usr/local/bin/pingap com um único comando:

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

Variáveis de ambiente opcionais:

• PINGAP_FULL=1 — instala a build -full (todos os recursos opcionais habilitados)
• PINGAP_LIBC=gnu — no Linux, use a build glibc em vez da build estática musl padrão

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

Alvos suportados: Linux x86_64/arm64, Darwin x86_64/arm64. Consulte a página de releases para todos os ativos disponíveis.

Para instruções mais detalhadas, incluindo execução a partir de um binário, consulte nossa Documentação.

Iniciar um proxy sem arquivo de configuração

Um único comando é suficiente para servir um domínio via https e encaminhá-lo para um 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

Sem --cert, o Pingap solicita um certificado ao Let's Encrypt por meio do desafio HTTP-01, portanto, pingap.io deve resolver para este host e a porta 80 deve estar acessível pela internet. O certificado emitido é armazenado em ~/.pingap/acme/<domains>.toml e reutilizado na reinicialização — a emissão é limitada por taxa, portanto, não o exclua. Todo o restante ainda vem da linha de comando: alterar --upstream tem efeito na próxima inicialização sem tocar no certificado.

--cert aceita o próprio certificado ou o diretório que o contém — os layouts comuns fullchain.pem / privkey.pem, cert.pem / key.pem e tls.crt / tls.key são detectados automaticamente; use --key para qualquer outra coisa. O listener padrão é 0.0.0.0:443 quando há um certificado e 0.0.0.0:80 quando não há nem certificado nem domínio, e --addr o substitui. --upstream aceita uma lista de backends separada por vírgulas; --domain aceita uma lista de hosts separada por vírgulas (omita para servir todos os hosts via http simples).

A configuração é gerada a cada inicialização, portanto, não pode ser editada pela interface de administração: para qualquer coisa além de um único servidor, use --conf, que não pode ser combinado com essas flags.

Configuração Dinâmica

O Pingap foi projetado para se adaptar a alterações de configuração sem tempo de inatividade.

Recarga a Quente (--autoreload): Para a maioria das alterações — como atualizar upstreams, locations ou plugins — o Pingap aplica a nova configuração em até 10 segundos sem reinicialização. Este é o modo recomendado para ambientes containerizados.

Reinicialização Graciosa (-a ou --autorestart): Para alterações fundamentais (como modificar as portas de escuta do servidor), este modo realiza uma reinicialização completa, sem tempo de inatividade, garantindo que nenhuma solicitação seja descartada.

🔧 Desenvolvimento

make dev

Se você precisar de uma administração web, instale o nodejs e compile os assets web.

# generate admin web asset
cd web
npm i 
cd ..
make build-web

📝 Configuração

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

Você pode encontrar as instruções relevantes aqui: https://pingap.io/crates/config.

🔄 Etapas do Proxy

graph TD;
  server["HTTP Server"];
  locationA["Location A"];
  locationB["Location B"];
  locationPluginListA["Proxy Plugin List A"];
  locationPluginListB["Proxy Plugin List B"];
  upstreamA1["Upstream A1"];
  upstreamA2["Upstream A2"];
  upstreamB1["Upstream B1"];
  upstreamB2["Upstream B2"];
  locationResponsePluginListA["Response Plugin List A"];
  locationResponsePluginListB["Response Plugin List B"];

  start("New Request") --> server

  server -- "host:HostA, Path:/api/*" --> locationA

  server -- "Path:/rest/*"--> locationB

  locationA -- "Exec Proxy Plugins" --> locationPluginListA

  locationB -- "Exec Proxy Plugins" --> locationPluginListB

  locationPluginListA -- "proxy pass: 10.0.0.1:8001" --> upstreamA1

  locationPluginListA -- "proxy pass: 10.0.0.2:8001" --> upstreamA2

  locationPluginListA -- "done" --> response

  locationPluginListB -- "proxy pass: 10.0.0.1:8002" --> upstreamB1

  locationPluginListB -- "proxy pass: 10.0.0.2:8002" --> upstreamB2

  locationPluginListB -- "done" --> response

  upstreamA1 -- "Exec Response Plugins" --> locationResponsePluginListA
  upstreamA2 -- "Exec Response Plugins" --> locationResponsePluginListA

  upstreamB1 -- "Exec Response Plugins" --> locationResponsePluginListB
  upstreamB2 -- "Exec Response Plugins" --> locationResponsePluginListB

  locationResponsePluginListA --> response
  locationResponsePluginListB --> response

  response["HTTP Response"] --> stop("Logging");

📊 Desempenho

CPU: M4 Pro, Thread: 1

Ping sem log de acesso

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

📦 Versão do Rust

Nosso MSRV atual é 1.88

📄 Licença

Este projeto é licenciado sob a Apache License, Version 2.0.