vicanso/pingapnginx와 같은 리버스 프록시로, pingora를 기반으로 구축되었으며, 간단하고 효율적입니다.
pingap 버전이 안정화되기 전까지는 풀 리퀘스트를 받지 않습니다. 질문이 있으시면 먼저 새 이슈를 생성해 주세요.
Pingap은 Cloudflare Pingora 기반의 고성능 리버스 프록시입니다. 간결한 TOML 파일과 직관적인 웹 관리 인터페이스를 통해 동적이고 무중단 구성 핫 리로딩을 지원하여 운영 관리를 단순화합니다.
핵심 강점은 강력한 플러그인 시스템에 있으며, 인증(JWT, Key Auth), 보안(CSRF, IP/Referer/UA 제한), 트래픽 제어(속도 제한, 캐싱), 콘텐츠 수정(리다이렉트, 콘텐츠 대체), 관측성(Request ID)을 위한 20개 이상의 즉시 사용 가능한 기능을 제공합니다. 이를 통해 Pingap은 단순한 프록시가 아니라 API 보호부터 최신 웹 애플리케이션 배포까지 복잡한 시나리오를 손쉽게 처리하도록 설계된 유연하고 확장 가능한 애플리케이션 게이트웨이입니다.
中文说明 | 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"]
🚀 고성능 및 안정성
🔧 동적이고 사용하기 쉬움
🧩 강력한 확장성
📊 현대적인 관측성
{:ja4}, 업스트림 헤더의 $ja4)으로 OpenSSL 및 rustls 빌드 모두에서 TLS 스택별로 클라이언트를 구분할 수 있습니다.Pingap을 시작하는 가장 쉬운 방법은 Docker Compose를 사용하는 것입니다.
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
mkdir pingap_data
docker-compose up -d
이제 Pingap 인스턴스가 실행 중입니다! 설정한 자격 증명으로 http://localhost/pingap 에서 웹 관리 인터페이스에 접속할 수 있습니다.
Linux와 macOS의 경우, 다음 한 명령으로 최신 사전 빌드된 바이너리를 /usr/local/bin/pingap에 설치할 수 있습니다:
curl -sSL https://raw.githubusercontent.com/vicanso/pingap/main/install.sh | sh
선택적 환경 변수:
PINGAP_FULL=1 — -full 빌드 설치(모든 선택적 기능 활성화)PINGAP_LIBC=gnu — Linux에서 기본 musl 정적 빌드 대신 glibc 빌드 사용PINGAP_TLS=rustls — Linux에서 -rustls-full 빌드 설치(rustls TLS 백엔드, 모든 선택적 기능, OpenSSL 없음); TLS 백엔드 참조# Full-featured build
curl -sSL https://raw.githubusercontent.com/vicanso/pingap/main/install.sh | PINGAP_FULL=1 sh
지원 대상: Linux x86_64/arm64, Darwin x86_64/arm64. 사용 가능한 모든 에셋은 릴리스 페이지를 참조하세요.
바이너리에서 실행하는 방법을 포함한 더 자세한 지침은 문서를 확인하세요.
단일 명령으로 도메인을 https로 서비스하고 백엔드로 전달할 수 있습니다:
# 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
--cert 없이 Pingap은 HTTP-01 챌린지를 통해 Let's Encrypt에 인증서를 요청하므로, pingap.io가 이 호스트로 확인되어야 하고 포트 80이 인터넷에서 접근 가능해야 합니다. 발급된 인증서는 ~/.pingap/acme/<domains>.toml에 보관되고 재시작 시 재사용됩니다 — 발급에는 속도 제한이 있으므로 삭제하지 마세요. 나머지는 모두 명령줄에서 옵니다: --upstream을 변경하면 인증서를 건드리지 않고 다음 시작 시 적용됩니다.
--cert는 인증서 자체 또는 인증서가 있는 디렉터리를 받습니다 — 일반적인 fullchain.pem / privkey.pem, cert.pem / key.pem, tls.crt / tls.key 레이아웃이 자동으로 감지되며, 그 외의 경우 --key를 사용하세요. 리스너는 인증서가 있으면 0.0.0.0:443, 인증서도 도메인도 없으면 0.0.0.0:80이 기본값이며, --addr로 재정의할 수 있습니다. --upstream은 쉼표로 구분된 백엔드 목록을, --domain은 쉼표로 구분된 호스트 목록을 받습니다(생략하면 모든 호스트를 일반 http로 서비스). 목록에 없는 호스트에 대한 요청은 404로 응답됩니다.
구성은 매 시작 시 생성되므로 관리 UI를 통해 편집할 수 없습니다: 단일 서버 이상의 용도로는 --conf를 사용하세요. 이는 이러한 플래그와 함께 사용할 수 없습니다.
Pingap은 다운타임 없이 구성 변경에 적응하도록 설계되었습니다.
핫 리로드(--autoreload): 업스트림, 위치 또는 플러그인 업데이트와 같은 대부분의 변경 사항에 대해 Pingap은 재시작 없이 10초 이내에 새 구성을 적용합니다. 이는 컨테이너화된 환경에 권장되는 모드입니다.
그레이스풀 재시작(-a 또는 --autorestart): 서버 리스닝 포트 수정과 같은 근본적인 변경의 경우, 이 모드는 요청이 유실되지 않도록 완전한 무중단 재시작을 수행합니다.
핸드오버는 시간 기반이 아니라 준비 상태 기반입니다: 대체 프로세스는 -d -u로 시작되고, 리스너를 인계받을 준비가 되는 순간 업그레이드 소켓 옆의 유닉스 소켓을 통해 보고하며, 그제서야 실행 중인 프로세스가 자신에게 SIGQUIT을 보냅니다. 대체 프로세스가 종료되거나, 그 데몬이 죽거나, basic.restart_ready_timeout(기본 1분)이 먼저 지나면 재시작이 중단되고 실행 중인 프로세스가 계속 서비스합니다.
make dev
웹 관리자가 필요하다면 nodejs를 설치하고 웹 에셋을 빌드해야 합니다.
# generate admin web asset
cd web
npm i
cd ..
make build-web
기본 빌드는 openssl 크레이트가 소스에서 컴파일한 OpenSSL로 TLS를 종료합니다. 대신 rustls로 빌드하려면 OpenSSL 소스 빌드가 제거됩니다(C 컴파일러는 여전히 필요합니다: rustls의 암호화 제공자인 ring과 aws-lc-rs는 C와 어셈블리를 포함합니다):
cargo build --release --no-default-features --features tls-rustls
# with the optional features as well
cargo build --release --no-default-features --features tls-rustls,full
rustls 빌드는 구성 검증(시작, --test, 자동 재시작) 시 서버별 tls_min_version, tls_max_version, tls_cipher_list, tls_ciphersuites 설정을 거부합니다: 항상 rustls의 기본 암호 제품군으로 TLS 1.2와 1.3을 제공합니다. 관리 UI는 실행 중인 바이너리가 rustls 빌드일 때 해당 필드를 비활성화합니다. 동적 SNI 인증서, 자체 서명 CA 발급, ACME, 업스트림 ca 옵션을 포함한 나머지는 모두 동일하게 동작합니다. 사전 빌드된 이미지도 동일한 변형을 제공합니다: vicanso/pingap:rustls-full(릴리스의 경우 :<version>-rustls-full), 그리고 :latest와 :full. 업스트림 검증 시 알아야 할 한 가지 차이점: rustls(webpki)는 CA:TRUE를 가진 서버 인증서를 거부하는데, OpenSSL은 이를 허용합니다. 따라서 빠른 openssl req -x509 자체 서명 인증서를 사용하는 백엔드는 업스트림 ca 옵션이 신뢰하기 전에 CA가 서명한 적절한 리프 인증서(또는 CA 플래그가 없는 자체 서명 리프 인증서)가 필요합니다. --version(긴 형식), 시작 로그, 관리 홈 페이지 모두 바이너리가 어떤 백엔드로 빌드되었는지 보고합니다.
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"]
관련 지침은 여기에서 확인할 수 있습니다: https://pingap.io/crates/config.