Pingap

Cloudflare Pingora 기반으로 구축된 리버스 프록시 및 애플리케이션 게이트웨이입니다. TOML 파일 또는 바이너리에 포함된 웹 관리자를 통해 구성되며, 재시작 없이 변경 사항을 적용하고 30개 이상의 플러그인을 제공합니다.

인터넷에서 들어온 요청이 Pingap을 통과하며, 호스트와 경로에 따라 업스트림 서버 그룹으로 라우팅됩니다

차별점

바이너리에 내장된 웹 관리자. 모든 설정에는 폼이 있습니다. 변경 사항은 저장되기 전에 pingap -t가 검사하는 방식으로 검증되며, 이전 버전을 보관하고 복원할 수 있고, 읽기 전용 계정과 API 토큰도 있습니다. 홈 페이지에서는 Prometheus 없이 지난 15분간의 트래픽(속도, 상태, 지연 시간, 각 업스트림)을 차트로 보여줍니다.
다운타임 없는 변경. 업스트림, 위치, 플러그인, 인증서는 실행 중인 프로세스에서 교체됩니다(--autoreload). 새로운 리스너가 필요한 사항은 소켓을 넘겨주는 재시작으로 적용되며(--autorestart, Linux의 데몬용), 대체 프로세스가 올라오지 않으면 실행 중인 프로세스가 계속 서비스를 제공합니다.
30개 이상의 플러그인, 위치별로 나열한 순서대로 적용됩니다: 인증(JWT, OIDC, key, basic, HMAC, forward auth), 접근 규칙(IP, referer, user agent, 차단 경로), 트래픽(속도 및 대역폭 제한, 캐시, 미러링, 트래픽 분할), 콘텐츠(압축, 본문 치환, 리다이렉트, 정적 파일, 이미지 최적화), 운영(유지보수 모드, 상태 엔드포인트, 오류 페이지). 모든 플러그인
cron 작업 없는 인증서. Let's Encrypt 또는 기타 ACME CA, HTTP-01 또는 DNS-01(Alibaba Cloud, Cloudflare, Tencent Cloud, Huawei Cloud) 방식, RSA와 ECDSA 병행, OCSP 스테이플링, 클라이언트 및 업스트림 방향의 상호 TLS를 지원합니다.
실행 전에 검사되는 구성. -t는 시작 시 생성될 모든 것을 빌드하고, --strict는 알 수 없는 키를 거부하며, --diff는 변경 사항이 미칠 영향을 보여줍니다. TOML, HCL 또는 KDL을 파일이나 etcd에 저장하며, 시크릿은 환경 변수나 파일에서 가져옵니다.
모니터링을 염두에 두고 설계됨. Prometheus 메트릭(pull 및 push), OpenTelemetry 트레이스, 30개 이상의 필드를 갖춘 텍스트 또는 JSON 형식 액세스 로그, 클라이언트의 JA4 TLS 지문을 제공합니다.

리버스 프록시의 나머지 기능도 모두 갖추고 있습니다: HTTP/1.1, HTTP/2, WebSocket 및 gRPC-web; 호스트, 경로 및 정규식 기반 라우팅; 라운드 로빈, 최소 연결, 일관된 해싱 및 스티키 세션, 상태 확인, 재시도 및 서킷 브레이커; DNS(A/AAAA, SRV) 또는 Docker 레이블 기반 백엔드; 리스너 및 업스트림 방향의 PROXY 프로토콜; OpenSSL 또는 rustls.

메트릭, 트레이싱 및 이미지 최적화는 -full 빌드에 포함되어 있습니다.

🚀 시작하기

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

관리자 페이지는 http://localhost/pingap 에 있습니다. 이미지는 latest, full, rustls-full 태그가 붙어 있으며, 릴리스의 경우 <version>, <version>-full, <version>-rustls-full 태그가 있습니다. 각 이미지에는 셸이 없는 -distroless 쌍둥이 이미지도 있으며, 이 경우 위에서처럼 command가 pingap으로 시작해야 합니다.

바이너리

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

Linux와 macOS(x86_64 및 arm64)에서 최신 릴리스를 /usr/local/bin/pingap에 설치합니다. sh 앞의 변수로 설치할 항목을 선택합니다:

변수	효과
`PINGAP_FULL=1`	모든 선택적 기능이 포함된 `-full` 빌드
`PINGAP_TLS=rustls`	Linux: OpenSSL 없이 `-rustls-full` 빌드 (TLS 백엔드 참조)
`PINGAP_LIBC=gnu`	Linux: 정적 musl 빌드 대신 glibc 빌드
`PINGAP_SERVICE=1`	systemd가 있는 Linux: `pingap` 서비스와 `/etc/pingap/conf`의 시작 구성도 함께 설치되며, 활성화되거나 시작되지는 않음
`PINGAP_VERSION=0.15.0`	최신 릴리스 대신 해당 릴리스

모든 에셋은 릴리스 페이지에 있습니다.

명령 하나, 구성 파일 없이

# 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

--cert가 없으면 인증서는 HTTP-01 방식으로 발급됩니다. 도메인이 이 호스트로 확인되어야 하며, 포트 80에 접근할 수 있어야 합니다. 인증서는 ~/.pingap/acme/<domains>.toml에 보관되며 다음 시작 시 다시 사용됩니다. 삭제하지 마세요. 발급에는 속도 제한이 있습니다.
--cert는 인증서 또는 인증서가 있는 디렉터리입니다(fullchain.pem / privkey.pem, cert.pem / key.pem, tls.crt / tls.key를 찾습니다. 그 외의 이름은 --key로 지정합니다). --upstream과 --domain은 쉼표로 구분된 목록을 받고, --addr은 수신할 주소를 받습니다.
구성은 매번 시작 시 새로 만들어지므로 관리자가 편집할 수 없습니다. 서버가 두 개 이상이면 --conf를 사용하세요. 이 플래그들과 함께 사용할 수 없습니다.

📝 구성

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

HCL 또는 KDL로도 작성할 수 있습니다. 모든 키는 구성 참조에 설명되어 있습니다.


`--autoreload`	재시작 없이 변경 사항이 적용됩니다. 파일에서는 10초 이내에, etcd에서는 즉시 적용됩니다. 재시작이 필요한 사항은 보고되며 재시작을 기다립니다. 컨테이너용 모드입니다
`-a`, `--autorestart`	위와 동일하며, 리로드로 변경할 수 없는 사항(예: 수신 주소)에 대해 요청을 드롭하지 않는 재시작을 수행합니다. Linux에서 데몬(`-d`)용이며, 그 외 환경에서는 리로드하고 대기 중인 사항을 보고합니다
`-t`	시작할 때처럼 모든 업스트림, 로케이션, 플러그인, 인증서, 서버를 빌드하며 아무것도 바인딩하지 않습니다
`--strict`	Pingap이 알지 못하는 키나 이 빌드에 해당 기능이 없는 키를 경고 대신 오류로 처리합니다. CI에서 `-t`와 함께 사용합니다
`--diff <other>`	`<other>`가 구성 대신 사용될 경우 무엇이 변경되는지 출력하며, 자격 증명은 체크섬으로 표시됩니다
`$ENV:NAME`, `$FILE:/path`	전체 값으로서, 구성이 로드될 때 변수나 파일로 대체됩니다

🔄 요청 처리 방식

요청은 서버, 로케이션 및 해당 요청 플러그인을 거쳐 업스트림으로 전달되며, 응답은 응답 플러그인을 거쳐 돌아오고 로깅됩니다

서버가 연결을 수락하고 호스트와 경로가 가장 잘 일치하는 로케이션을 선택합니다. 어느 것과도 일치하지 않는 요청에는 404로 응답합니다.
로케이션의 플러그인은 나열된 순서대로 각자의 단계(진입 시 또는 반환 시)에서 실행됩니다. 플러그인은 요청 자체에 응답할 수 있으며(캐시 적중, 인증 실패, 리다이렉트, 정적 파일), 이 경우 업스트림에는 요청이 전달되지 않습니다.
그렇지 않으면 로케이션의 업스트림이 정상 백엔드를 선택하고 요청이 전달됩니다. max_retries를 사용하면 연결할 수 없는 경우 다른 백엔드에서 시도하며, fallback_upstream을 사용하면 업스트림이 처리할 수 없는 요청이 두 번째 업스트림으로 전달됩니다.
응답은 응답 플러그인을 거쳐 클라이언트로 반환되며, 요청은 로깅됩니다: 액세스 로그, 메트릭, 트레이스.

📊 성능

M4 Pro의 단일 스레드에서 /ping에 대해 초당 약 147,000건의 요청을 처리하며, 99번째 백분위수는 116µs입니다(wrk, 연결 10개, 액세스 로그 없음).

실행 결과

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

🔧 개발

make dev         # needs bacon: cargo install bacon
make build-web   # after a change under web/, needs Node.js
make fmt && make lint && make test

make dev는 full 기능으로 빌드하고, --autoreload와 함께 ~/tmp/pingap의 구성으로 Pingap을 실행하며, 127.0.0.1:3018에서 관리자(pingap / 123123)를 제공하고 소스가 변경되면 다시 빌드합니다. 관리자는 make build-web이 채우는 dist/에서 바이너리에 임베드됩니다. 지원되는 최소 Rust 버전은 1.96입니다.

TLS 백엔드

기본 빌드는 소스에서 컴파일된 OpenSSL을 사용합니다. rustls의 경우:

cargo build --release --no-default-features --features tls-rustls,full

rustls 빌드는 항상 rustls 자체의 암호화 스위트와 함께 TLS 1.2 및 1.3을 제공하므로, 구성이 검사될 때 서버별 tls_min_version, tls_max_version, tls_cipher_list 및 tls_ciphersuites는 거부됩니다. 그 외의 모든 동작은 동일하며, 차이점은 certificate crate에 나열되어 있습니다. pingap --version은 바이너리가 어떤 백엔드를 사용하는지 알려줍니다.

🤝 기여하기

풀 리퀘스트를 환영합니다.

pingap

인기