pingap

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

Visão Geral

Pingap é um proxy reverso de alto desempenho alimentado pelo Cloudflare Pingora. Ele simplifica o gerenciamento operacional ao permitir recarregamento dinâmico de configuração sem downtime através de arquivos TOML concisos e uma interface web de administração intuitiva.

Sua força principal está em um poderoso sistema de plugins, oferecendo mais de vinte recursos prontos para uso em Autenticação (JWT, Key Auth), Segurança (CSRF, Restrições de IP/Referer/UA), Controle de Tráfego (Rate Limiting, Caching), 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 sem esforço com cenários complexos, desde proteção de API até implantações de aplicações 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"]

Principais Recursos

• 🚀 Alto Desempenho e Confiabilidade

  • Construído com Rust para segurança de memória e desempenho de alto nível.
  • Alimentado pelo Cloudflare Pingora, uma biblioteca de rede assíncrona testada em batalha.
  • Suporta proxy HTTP/1.1, HTTP/2 e gRPC-web.

• 🔧 Dinâmico e Fácil de Usar

  • Alterações de configuração sem downtime com hot-reloading.
  • Arquivos de configuração TOML simples e legíveis por humanos.
  • Interface Web completa para gerenciamento intuitivo em tempo real.
  • Suporta tanto arquivo quanto etcd como backends de configuração.
  • Suporta histórico de configuração, permitindo restaurar para uma versão anterior com um clique.

• 🧩 Extensibilidade Poderosa

  • Um rico sistema de plugins para lidar com tarefas comuns de gateway.
  • Roteamento avançado com correspondência de host, path e regex.
  • Descoberta de serviços integrada via listas estáticas, DNS ou labels do 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.
  • Fingerprints JA4 de clientes TLS ({:ja4} nos logs de acesso, $ja4 nos headers de upstream) para distinguir clientes por sua stack TLS, tanto em builds OpenSSL quanto rustls.
  • Métricas de desempenho detalhadas, incluindo tempo de conexão com upstream, tempo de processamento e mais.

🚀 Primeiros Passos

A maneira mais fácil de começar com o Pingap é usando 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á rodando! Você pode acessar a interface web de administração em http://localhost/pingap com as credenciais que você definiu.

Instalar o binário via curl

Para Linux e macOS, você pode instalar o binário pré-compilado mais recente 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 o build -full (todos os recursos opcionais habilitados)
• PINGAP_LIBC=gnu — no Linux, usa o build glibc em vez do build estático musl padrão
• PINGAP_TLS=rustls — no Linux, instala o build -rustls-full (backend TLS rustls, todos os recursos opcionais, sem OpenSSL); veja TLS backend

# 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. Veja a página de releases para todos os assets 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 através do desafio HTTP-01, então pingap.io deve resolver para este host e a porta 80 deve estar acessível pela internet. O certificado emitido é mantido em ~/.pingap/acme/<domains>.toml e reutilizado na reinicialização — a emissão tem limite de taxa, então não o exclua. Todo o resto 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 outro. O listener tem como padrão 0.0.0.0:443 quando há um certificado e 0.0.0.0:80 quando não há certificado nem domínio, e --addr sobrescreve isso. --upstream aceita uma lista de backends separada por vírgulas, --domain uma lista de hosts separada por vírgulas (omita para servir todos os hosts via http simples). Requisições para um host que não está listado são respondidas com 404.

A configuração é gerada a cada inicialização, então não pode ser editada através da 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

Pingap é projetado para se adaptar a mudanças de configuração sem downtime.

Hot Reload (--autoreload): Para a maioria das mudanças—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 conteinerizados.

Graceful Restart (-a ou --autorestart): Para mudanças fundamentais (como modificar portas de escuta do servidor), este modo realiza uma reinicialização completa sem downtime, garantindo que nenhuma requisição seja perdida.