Pingap

Um proxy reverso e gateway de aplicações construído sobre o Cloudflare Pingora. É configurado através de ficheiros TOML ou de uma interface web de administração que faz parte do binário, aplica alterações sem reiniciar e vem com mais de trinta plugins.

中文说明 | Documentation · 中文文档 | Examples | Plugins | Crates | Upgrading

O que o distingue

• Uma interface web de administração no binário. Cada definição tem um formulário. Uma alteração é verificada da mesma forma que pingap -t a verifica antes de ser guardada, versões anteriores podem ser mantidas e restauradas, e existem contas só de leitura e tokens de API. A sua página inicial apresenta gráficos do tráfego dos últimos quinze minutos - taxa, estado, latência, cada upstream - sem Prometheus.
• Alterações sem tempo de inatividade. Upstreams, locations, plugins e certificados são substituídos no processo em execução (--autoreload). O que exige novos listeners é aplicado por um reinício que transfere os sockets (--autorestart, para um daemon no Linux), e o processo em execução continua a servir se o seu substituto não arrancar.
• Mais de trinta plugins, por location e pela ordem em que os listar: autenticação (JWT, OIDC, key, basic, HMAC, forward auth), regras de acesso (IP, referer, user agent, caminhos bloqueados), tráfego (limites de taxa e largura de banda, cache, mirroring, divisão de tráfego), conteúdo (compressão, substituição de corpo, redirecionamentos, ficheiros estáticos, otimização de imagens) e operações (modo de manutenção, endpoint de saúde, páginas de erro). Todos os plugins
• Certificados sem cron job. Let's Encrypt ou qualquer outra CA ACME, por HTTP-01 ou DNS-01 (Alibaba Cloud, Cloudflare, Tencent Cloud, Huawei Cloud), RSA e ECDSA lado a lado, OCSP stapling, e mutual TLS para com os clientes e para com os upstreams.
• Configuração verificada antes de ser executada. -t constrói tudo o que um arranque construiria, --strict recusa chaves que não conhece, --diff mostra o que uma alteração faria. TOML, HCL ou KDL, em ficheiros ou em etcd, com segredos obtidos do ambiente ou de ficheiros.
• Feito para ser observado. Métricas Prometheus (pull e push), traces OpenTelemetry, logs de acesso em texto ou JSON com mais de trinta campos, e impressões digitais TLS JA4 dos clientes.

O resto do que um proxy reverso faz também está presente: HTTP/1.1, HTTP/2, WebSocket e gRPC-web; encaminhamento por host, caminho e expressão regular; round robin, least connections, consistent hashing e sessões sticky, com verificações de saúde, retries e um circuit breaker; backends a partir de DNS (A/AAAA, SRV) ou de labels Docker; o protocolo PROXY nos listeners e para com os upstreams; OpenSSL ou rustls.

Métricas, tracing e otimização de imagens estão nas builds -full.

🚀 Começar

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

O admin está em http://localhost/pingap. As imagens são marcadas como latest, full e rustls-full, e <version>, <version>-full, <version>-rustls-full para uma versão. Cada uma também tem uma variante -distroless sem shell, onde command precisa começar com pingap como acima.

Binário

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

instala a versão mais recente em /usr/local/bin/pingap no Linux e macOS (x86_64 e arm64). As variáveis antes de sh escolhem o que é instalado:

Variável	Efeito
PINGAP_FULL=1	A build -full, com todos os recursos opcionais
PINGAP_TLS=rustls	Linux: a build -rustls-full, sem OpenSSL (veja TLS backend)
PINGAP_LIBC=gnu	Linux: a build glibc em vez da musl estática
PINGAP_SERVICE=1	Linux com systemd: também o serviço pingap e uma configuração inicial em /etc/pingap/conf; ele não é habilitado nem iniciado
PINGAP_VERSION=0.15.0	Essa versão em vez da mais recente

Todos os assets estão na página de releases.

Um comando, sem arquivo de configuração

# 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

• Sem --cert, o certificado é solicitado via HTTP-01: o domínio precisa resolver para este host, com a porta 80 acessível. Ele é mantido em ~/.pingap/acme/<domains>.toml e reutilizado na próxima inicialização. Não o exclua, a emissão é limitada por taxa.
• --cert é o certificado ou o diretório em que ele está (fullchain.pem / privkey.pem, cert.pem / key.pem e tls.crt / tls.key são encontrados; --key nomeia qualquer outro). --upstream e --domain recebem listas separadas por vírgulas, --addr o endereço no qual escutar.
• A configuração é criada novamente a cada inicialização, portanto o administrador não pode editá-la. Para mais de um servidor, use --conf, que não pode ser combinado com estas flags.

📝 Configuração

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

O mesmo pode ser escrito em HCL ou KDL. Cada chave está descrita na referência de configuração.

--autoreload	Uma alteração é aplicada sem reinício: em até dez segundos a partir de ficheiros, de imediato a partir do etcd. O que exige reinício é reportado e aguarda por ele. O modo para contentores
-a, --autorestart	O mesmo, e um reinício que não descarta nenhum pedido para o que um reload não consegue alterar, como um endereço de escuta. Para um daemon (-d) no Linux; em qualquer outro lugar faz reload e reporta o que aguarda
-t	Constrói cada upstream, location, plugin, certificado e servidor como um arranque faz, e não liga nada
--strict	Uma chave que o Pingap não conhece, ou uma para a qual esta build não tem funcionalidade, é um erro, onde de outra forma seria um aviso. Para -t em CI
--diff <other>	Imprime o que mudaria se <other> tomasse o lugar da configuração, com as credenciais mostradas como checksums
$ENV:NAME, $FILE:/path	Como valor completo: substituído pela variável ou pelo ficheiro quando a configuração é carregada

🔄 Como um pedido é tratado