vicanso/pingapnginx와 같은 리버스 프록시로, pingora를 기반으로 구축되었으며, 간단하고 효율적입니다.
# Pingap
[Cloudflare Pingora](https://github.com/cloudflare/pingora) 기반으로 구축된 리버스 프록시 및 애플리케이션 게이트웨이입니다. TOML 파일 또는 바이너리에 포함된 웹 관리자를 통해 구성되며, 재시작 없이 변경 사항을 적용하고 30개 이상의 플러그인을 제공합니다.
[中文说明](https://github.com/vicanso/pingap/blob/main/README_zh.md) | [문서](https://pingap.io/) · [中文文档](https://pingap.io/zh/) | [예제](https://github.com/vicanso/pingap/blob/main/examples/README.md) | [플러그인](https://github.com/vicanso/pingap/blob/main/pingap-plugin/README.md) | [Crates](https://github.com/vicanso/pingap/blob/main/docs/README.md) | [업그레이드](https://pingap.io/guide/upgrading)
## 차별점
- **바이너리에 내장된 웹 관리자.** 모든 설정에는 폼이 있습니다. 변경 사항은 저장되기 전에 `pingap -t`가 검사하는 방식으로 검증되며, 이전 버전을 보관하고 복원할 수 있고, 읽기 전용 계정과 API 토큰도 있습니다. 홈 페이지에서는 Prometheus 없이 지난 15분간의 트래픽(속도, 상태, 지연 시간, 각 업스트림)을 차트로 보여줍니다.
- **다운타임 없는 변경.** 업스트림, 위치, 플러그인, 인증서는 실행 중인 프로세스에서 교체됩니다(`--autoreload`). 새로운 리스너가 필요한 사항은 소켓을 넘겨주는 재시작으로 적용되며(`--autorestart`, Linux의 데몬용), 대체 프로세스가 올라오지 않으면 실행 중인 프로세스가 계속 서비스를 제공합니다.
- **30개 이상의 플러그인**, 위치별로 나열한 순서대로 적용됩니다: 인증(JWT, OIDC, key, basic, HMAC, forward auth), 접근 규칙(IP, referer, user agent, 차단 경로), 트래픽(속도 및 대역폭 제한, 캐시, 미러링, 트래픽 분할), 콘텐츠(압축, 본문 치환, 리다이렉트, 정적 파일, 이미지 최적화), 운영(유지보수 모드, 상태 엔드포인트, 오류 페이지). [모든 플러그인](https://github.com/vicanso/pingap/blob/main/pingap-plugin/README.md)
- **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
```yaml
# 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
```
```bash
mkdir pingap_data
docker compose up -d
```
관리자 페이지는 http://localhost/pingap 에 있습니다. 이미지는 `latest`, `full`, `rustls-full` 태그가 붙어 있으며, 릴리스의 경우 `<version>`, `<version>-full`, `<version>-rustls-full` 태그가 있습니다. 각 이미지에는 셸이 없는 `-distroless` 쌍둥이 이미지도 있으며, 이 경우 위에서처럼 `command`가 `pingap`으로 시작해야 합니다.
### 바이너리
```bash
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 백엔드](#tls-backend) 참조) |
| `PINGAP_LIBC=gnu` | Linux: 정적 musl 빌드 대신 glibc 빌드 |
| `PINGAP_SERVICE=1` | systemd가 있는 Linux: `pingap` 서비스와 `/etc/pingap/conf`의 시작 구성도 함께 설치되며, 활성화되거나 시작되지는 않음 |
| `PINGAP_VERSION=0.15.0` | 최신 릴리스 대신 해당 릴리스 |
모든 에셋은 [릴리스 페이지](https://github.com/vicanso/pingap/releases)에 있습니다.
### 명령 하나, 구성 파일 없이
```bash
# 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`를 사용하세요. 이 플래그들과 함께 사용할 수 없습니다.
## 📝 구성
```toml
[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로도 작성할 수 있습니다. 모든 키는 [구성 참조](https://pingap.io/crates/config)에 설명되어 있습니다.
| | |
| --- | --- |
| `--autoreload` | 재시작 없이 변경 사항이 적용됩니다. 파일에서는 10초 이내에, etcd에서는 즉시 적용됩니다. 재시작이 필요한 사항은 보고되며 재시작을 기다립니다. 컨테이너용 모드입니다 |
| `-a`, `--autorestart` | 위와 동일하며, 리로드로 변경할 수 없는 사항(예: 수신 주소)에 대해 요청을 드롭하지 않는 재시작을 수행합니다. Linux에서 데몬(`-d`)용이며, 그 외 환경에서는 리로드하고 대기 중인 사항을 보고합니다 |
| `-t` | 시작할 때처럼 모든 업스트림, 로케이션, 플러그인, 인증서, 서버를 빌드하며 아무것도 바인딩하지 않습니다 |
| `--strict` | Pingap이 알지 못하는 키나 이 빌드에 해당 기능이 없는 키를 경고 대신 오류로 처리합니다. CI에서 `-t`와 함께 사용합니다 |
| `--diff <other>` | `<other>`가 구성 대신 사용될 경우 무엇이 변경되는지 출력하며, 자격 증명은 체크섬으로 표시됩니다 |
| `$ENV:NAME`, `$FILE:/path` | 전체 값으로서, 구성이 로드될 때 변수나 파일로 대체됩니다 |
## 🔄 요청 처리 방식
1. **서버**가 연결을 수락하고 호스트와 경로가 가장 잘 일치하는 **로케이션**을 선택합니다. 어느 것과도 일치하지 않는 요청에는 `404`로 응답합니다.
2. 로케이션의 **플러그인**은 나열된 순서대로 각자의 단계(진입 시 또는 반환 시)에서 실행됩니다. 플러그인은 요청 자체에 응답할 수 있으며(캐시 적중, 인증 실패, 리다이렉트, 정적 파일), 이 경우 업스트림에는 요청이 전달되지 않습니다.
3. 그렇지 않으면 로케이션의 **업스트림**이 정상 백엔드를 선택하고 요청이 전달됩니다. `max_retries`를 사용하면 연결할 수 없는 경우 다른 백엔드에서 시도하며, `fallback_upstream`을 사용하면 업스트림이 처리할 수 없는 요청이 두 번째 업스트림으로 전달됩니다.
4. 응답은 응답 플러그인을 거쳐 클라이언트로 반환되며, 요청은 **로깅**됩니다: 액세스 로그, 메트릭, 트레이스.
## 📊 성능
M4 Pro의 단일 스레드에서 `/ping`에 대해 초당 약 147,000건의 요청을 처리하며, 99번째 백분위수는 116µs입니다(`wrk`, 연결 10개, 액세스 로그 없음).
<details>
<summary>실행 결과</summary>
```
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
```
</details>
## 🔧 개발
```bash
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의 경우:
```bash
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](https://pingap.io/crates/certificate)에 나열되어 있습니다. `pingap --version`은 바이너리가 어떤 백엔드를 사용하는지 알려줍니다.
## 🤝 기여하기
풀 리퀘스트를 환영합니다.
- 새로운 기능의 경우, 코드를 작성하기 전에 논의할 수 있도록 먼저 이슈를 열어 주세요.
- 오타나 주석의 서식만 수정하기 위한 풀 리퀘스트는 열지 마세요. 이러한 수정은 일괄적으로 처리됩니다.
- 푸시하기 전에 `make fmt`, `make lint`, `make test`를 실행하세요. CI는 모든 풀 리퀘스트에서 동일한 검사를 실행합니다.
- 기여는 [기여자 라이선스 계약](https://github.com/vicanso/pingap/blob/main/CLA.md)에 따라 이루어지며, 풀 리퀘스트 템플릿의 해당 체크박스를 선택함으로써 동의하게 됩니다. 작업물의 소유권은 기여자에게 있으며, 프로젝트의 라이선스에 따라 프로젝트에 라이선스가 부여됩니다.
## 📄 라이선스
[Apache License, Version 2.0](https://github.com/vicanso/pingap/blob/main/LICENSE).