reproxy

default: # the same as * (catch-all) server
  - { route: "^/api/svc1/(.*)", dest: "http://127.0.0.1:8080/blah1/$1" }
  - {
      route: "/api/svc3/xyz",
      dest: "http://127.0.0.3:8080/blah3/xyz",
      ping: "http://127.0.0.3:8080/ping",
      remote: "192.168.1.0/24, 127.0.0.1", # optional, restrict access to the route
      forward-health-checks: true # optional, forward /ping and /health to backend
    }
  - {
      route: "^/admin/(.*)",
      dest: "http://127.0.0.4:8080/$1",
      auth: "admin:$2y$05$..." # optional, per-route basic auth (htpasswd bcrypt format)
    }
  - {
      route: "^/upload/(.*)",
      dest: "http://127.0.0.5:8080/$1",
      timeout: 5m # optional, per-route request timeout (Go duration). 0 or omitted inherits --timeout.write
    }
  - {
      route: "^/login",
      dest: "http://127.0.0.6:8080/login",
      throttle: 2 # optional, per-route req/sec per user. 0 or omitted inherits --throttle.user
    }
srv.example.com:
  - { route: "^/api/svc2/(.*)", dest: "http://127.0.0.2:8080/blah2/$1/abc" }
  - { route: "/web/", dest: "/var/www", "assets": true }
"*.files.example.com":
  - { route: "^/files/(.*)", dest: "http://123.123.200.200:8080/$host/$1" }
```
이것은 동적 제공자이며 파일 변경이 자동으로 적용됩니다.

**여러 도메인의 여러 정적 사이트**를 `assets: true`와 함께 서버 이름을 키로 사용하여 제공할 수 있습니다:```yaml
site-en.example.com:
  - { route: "/", dest: "/var/www/en", "assets": true }
site-ru.example.com:
  - { route: "/", dest: "/var/www/ru", "assets": true }
```
**중요:** 에셋 규칙의 `route` 필드는 경로 접두사(예: `/`, `/web/`)여야 하며, 정규식이 아니어야 합니다. `^/(.*)`와 같은 정규식 패턴은 `assets: true`에서 작동하지 않습니다. 정적 에셋 매칭은 정규식이 아닌 경로 접두사 비교를 사용하기 때문입니다.

### Docker 제공자

Docker 제공자는 추가 구성 없이 완전 자동 검색(`--docker.auto`)을 지원합니다. 기본적으로 모든 요청 `http://<url>/<컨테이너 이름>/(.*)`을 해당 컨테이너의 내부 IP와 노출된 포트로 리디렉션합니다. 활성(실행 중인) 컨테이너만 감지됩니다.

기본 동작은 라벨을 통해 변경할 수 있습니다:

- `reproxy.server` - 일치시킬 서버(호스트 이름). 쉼표로 구분된 서버 목록도 가능합니다.
- `reproxy.route` - 소스 라우트(위치)
- `reproxy.dest` - 대상 경로. 참고: 전체 URL이 아니라 컨테이너의 ip:port에 추가될 경로입니다.
- `reproxy.port` - 발견된 컨테이너의 대상 포트
- `reproxy.ping` - 대상 컨테이너의 ping 경로.
- `reproxy.remote` - 쉼표로 구분된 서브넷 또는 IP 목록으로 라우트 접근 제한
- `reproxy.auth` - 쉼표로 구분된 `user:bcrypt_hash` 쌍(`htpasswd -nbB`로 생성)으로 라우트에 기본 인증 필요
- `reproxy.assets` - 에셋 매핑을 `web-root:location`으로 설정, 예: `reproxy.assets=/web:/var/www`
- `reproxy.keep-host` - 호스트 헤더를 그대로 유지(`yes`, `true`, `1`)하거나 대상 호스트로 대체(`no`, `false`, `0`)
- `reproxy.forward-health-checks` - reproxy가 처리하는 대신 `/ping` 및 `/health` 요청을 백엔드로 전달(`yes`, `true`, `1`). 백엔드에 애플리케이션별 응답이 있는 자체 상태 확인 엔드포인트가 있을 때 유용합니다.
- `reproxy.timeout` - 라우트별 요청 시간 제한(Go 기간 형식, 예: `5m`, `30s`). `0`이거나 설정되지 않으면 전역 `--timeout.write`를 상속합니다. 잘못된 값은 경고와 함께 무시됩니다.
- `reproxy.throttle` - 사용자별 라우트별 초당 요청 제한. `0`이거나 설정되지 않으면 `--throttle.user`를 상속합니다. 잘못된 값이나 음수 값은 경고와 함께 무시됩니다.
- `reproxy.enabled` - 컨테이너를 reproxy 대상에서 활성화(`yes`, `true`, `1`) 또는 비활성화(`no`, `false`, `0`)합니다.

참고: `--docker.auto` 없이 대상 컨테이너는 잠재적 대상으로 간주되려면 최소한 하나의 `reproxy.*` 라벨이 있어야 합니다.

`--docker.auto`를 사용하면 노출된 포트가 있는 모든 컨테이너가 라우팅 대상으로 간주됩니다. 이를 제한하는 방법은 세 가지입니다:

- `--docker.exclude`로 일부 컨테이너를 명시적으로 제외, 예: `--docker.exclude=c1 --docker.exclude=c2 ...`
- `--docker.network`로 특정 Docker 네트워크만 허용
- 라벨 `reproxy.enabled=false` 또는 `reproxy.enabled=no` 또는 `reproxy.enabled=0` 설정

`reproxy.route`가 정의되지 않은 경우 기본 라우트는 `^/<container_name>/(.*)`입니다. 모든 프록시 대상 소스가 동일한 접두사 패턴(예: `/api/(.*)`)을 가져야 하는 경우 사용자는 모든 컨테이너 기반 라우트에 공통 접두사(이 경우 `/api`)를 정의할 수 있습니다. 이는 `--docker.prefix` 매개변수로 할 수 있습니다.

Docker 제공자는 동일한 컨테이너에서 여러 개의 개별 라우트를 일치시키기 위해 `reproxy.N.something` 라벨의 여러 세트를 정의할 수도 있습니다. 이는 단일 컨테이너가 여러 엔드포인트(예: 공개 API와 관리 API)를 노출할 수 있는 경우에 유용합니다. 위의 모든 라벨은 "N-인덱스"와 함께 사용할 수 있습니다. 즉, `reproxy.1.server`, `reproxy.1.port` 등입니다. N은 0에서 9 사이의 범위여야 합니다.

이것은 동적 제공자이며 컨테이너 상태의 모든 변경 사항이 자동으로 적용됩니다.

### Consul Catalog 제공자

사용: `reproxy --consul-catalog.enabled`

Consul Catalog 제공자는 주기적으로(기본적으로 1초마다) Consul API를 호출하여 `reproxy.` 접두사가 있는 태그가 있는 서비스를 가져옵니다. 사용자는 `--consul-catalog.interval` 명령줄 플래그로 확인 간격을 재정의할 수 있으며, `--consul-catalog.address` 명령줄 옵션으로 Consul 주소를 재정의할 수 있습니다. 기본 주소는 `http://127.0.0.1:8500`입니다.

예:```
reproxy --consul-catalog.enabled --consul-catalog.address=http://192.168.1.100:8500 --consul-catalog.interval=10s  
```
기본적으로 프로바이더는 모든 서비스에 대해 다음 값을 설정합니다:
- enabled `false`
- server `*`
- route `^/(.*)`
- dest `http://<SERVICE_ADDRESS_FROM_CONSUL>/$1`
- ping `http://<SERVICE_ADDRESS_FROM_CONSUL>/ping`

이 기본값은 태그로 변경할 수 있습니다:

- `reproxy.server` - 일치시킬 서버(호스트명). 또한 쉼표로 구분된 서버 목록일 수 있습니다.
- `reproxy.route` - 소스 경로(위치)
- `reproxy.dest` - 대상 경로. 참고: 전체 URL이 아닌 서비스의 ip:port에 추가될 경로일 뿐입니다.
- `reproxy.port` - 검색된 서비스에 대한 대상 포트
- `reproxy.remote` - 쉼표로 구분된 서브넷 또는 IP 목록으로 해당 경로에 대한 접근을 제한합니다.
- `reproxy.auth` - 쉼표로 구분된 `user:bcrypt_hash` 쌍( `htpasswd -nbB` 로 생성)으로 해당 경로에 기본 인증을 요구합니다.
- `reproxy.ping` - 대상 서비스에 대한 핑 경로.
- `reproxy.forward-health-checks` - `/ping` 및 `/health` 요청을 백엔드로 전달합니다(`true`, `yes`, `1`).
- `reproxy.timeout` - Go 지속 시간 형식(예: `5m`, `30s`)의 경로별 요청 시간 제한. `0` 또는 설정되지 않으면 전역 `--timeout.write`를 상속합니다. 잘못된 값은 경고와 함께 무시됩니다.
- `reproxy.throttle` - 사용자별 경로별 초당 요청 제한. `0` 또는 설정되지 않으면 `--throttle.user`를 상속합니다. 잘못되거나 음수 값은 경고와 함께 무시됩니다.
- `reproxy.enabled` - 서비스를 reproxy 대상에서 활성화(`yes`, `true`, `1`) 또는 비활성화(`다른 값`)합니다.

### Compose-특정 세부 사항

규칙이 docker compose 환경의 일부로 설정된 경우, 정규식 그룹이 포함된 대상은 compose 구문과 충돌합니다. 예를 들어, compose 환경에서 `https://api.example.com/$1`를 사용하려고 하면 구문 오류로 실패합니다. 여기서 표준 해결책은 `$` 기호를 `$$`로 대체하여 "이스케이프"하는 것입니다 (예: `https://api.example.com/$$1`). 이 대체는 docker compose에서 지원되며 reproxy 자체와는 관련이 없습니다. 다른 방법은 reproxy 수준에서 지원되는 `$` 대신 `@`를 사용하는 것입니다 (예: `https://api.example.com/@1`).

## SSL 지원

SSL 모드(기본값 없음)는 `auto`(ACME/LE 인증서), `static`(기존 인증서) 또는 `none`으로 설정할 수 있습니다. `auto`로 설정하면 검색된 모든 서버 이름에 대해 SSL 인증서가 자동으로 발급됩니다. 사용자는 `--ssl.fqdn` 값을 설정하여 이를 재정의할 수 있습니다. `auto` 및 `static` SSL 모드에서 Reproxy는 자동으로 `X-Forwarded-Proto` 및 `X-Forwarded-Port` 헤더를 추가합니다. 이 헤더는 프록시 뒤에 있는 서비스가 클라이언트가 사용한 원래 프로토콜(http 또는 https)과 포트 번호를 알 수 있도록 하는 데 유용합니다.

검색 제공자(docker, file, consul)와 함께 ACME를 사용할 때, 새로 검색된 서버에 대해 SSL 인증서가 reproxy 재시작 없이 자동으로 획득됩니다.

### ACME 챌린지

Reproxy는 SSL 인증서 검증을 위해 두 가지 유형의 ACME 챌린지를 지원합니다:

1. **HTTP-01 챌린지**(기본값): 특정 HTTP URL에서 토큰을 제공하여 도메인 소유권을 확인합니다. 80번 포트가 공개적으로 접근 가능해야 합니다.

2. **DNS-01 챌린지**: DNS TXT 레코드를 생성하여 도메인 소유권을 확인합니다. 이 방법은:
   - 80번 포트가 접근 가능할 필요가 없음
   - 와일드카드 인증서와 작동
   - 지원되는 DNS 제공자 구성 필요

#### 챌린지 선택

Reproxy는 구성에 따라 사용할 챌린지 방법을 자동으로 결정합니다:

- **HTTP-01**(기본값): DNS 제공자가 구성되지 않은 경우 사용됨
- **DNS-01**: DNS 제공자가 구성된 경우 사용됨

챌린지 유형을 명시적으로 선택할 필요가 없습니다. DNS-01 챌린지를 사용하려면 DNS 제공자만 구성하면 됩니다.

#### 현재 지원되는 DNS 제공자

Reproxy는 현재 다음 DNS 제공자를 지원합니다:

- **Cloudflare**: `--ssl.dns.type=cloudflare --ssl.dns.cloudflare.api-token=TOKEN`
- **Route53 (AWS)**: `--ssl.dns.type=route53 --ssl.dns.route53.region=REGION --ssl.dns.route53.hosted-zone-id=ID`
- **Gandi**: `--ssl.dns.type=gandi --ssl.dns.gandi.bearer-token=TOKEN`
- **DigitalOcean**: `--ssl.dns.type=digitalocean --ssl.dns.digitalocean.api-token=TOKEN`
- **Hetzner**: `--ssl.dns.type=hetzner --ssl.dns.hetzner.api-token=TOKEN`
- **Linode**: `--ssl.dns.type=linode --ssl.dns.linode.api-token=TOKEN`
- **GoDaddy**: `--ssl.dns.type=godaddy --ssl.dns.godaddy.api-token=TOKEN`
- **Namecheap**: `--ssl.dns.type=namecheap --ssl.dns.namecheap.api-key=KEY --ssl.dns.namecheap.user=USER`
- **Scaleway**: `--ssl.dns.type=scaleway --ssl.dns.scaleway.secret-key=KEY --ssl.dns.scaleway.organization-id=ID`
- **Porkbun**: `--ssl.dns.type=porkbun --ssl.dns.porkbun.api-key=KEY --ssl.dns.porkbun.api-secret-key=SECRET`
- **DNSimple**: `--ssl.dns.type=dnsimple --ssl.dns.dnsimple.api-access-token=TOKEN --ssl.dns.dnsimple.account-id=ID`
- **DuckDNS**: `--ssl.dns.type=duckdns --ssl.dns.duckdns.api-token=TOKEN`

DNS 제공자로 Cloudflare를 사용한 예제:```
export CLOUDFLARE_API_TOKEN=your_api_token
reproxy --ssl.type=auto [email protected] --ssl.fqdn=example.com
```
The DNS-01 챌린지는 특히 다음 경우에 유용합니다:
- 서버에 포트 80이 공개적으로 노출되지 않은 경우
- 와일드카드 인증서(예: *.example.com)가 필요한 경우
- 제한적인 방화벽 뒤에 있는 경우

## 헤더

Reproxy는 `--drop-header` 매개변수(반복 가능)를 전달하여 수신 헤더를 정리(제거)할 수 있습니다. 이 매개변수는 서비스 내부에서 설정된 일부 헤더를 최종 사용자가 설정/위조할 수 없도록 하는 데 유용합니다. 예를 들어 인증을 담당하는 일부 서비스가 `X-Auth-User` 및 `X-Auth-Token`을 설정하는 경우, `--drop-header=X-Auth-User --drop-header=X-Auth-Token` 매개변수를 전달하거나 환경 변수 `DROP_HEADERS=X-Auth-User,X-Auth-Token`을 통해 수신 요청에서 해당 헤더를 제거하는 것이 합리적일 것입니다.

반대 기능인 발신 헤더 설정도 지원됩니다. 이는 여러 경우에 유용할 수 있습니다. 예를 들어 사용자 정의 CORS 규칙 적용, 보안 관련 헤더 등이 있습니다. 이는 `--header` 매개변수(반복 가능) 또는 환경 변수 `HEADER`를 통해 수행할 수 있습니다. 예를 들어 다음과 같이 docker compose에서 수행할 수 있습니다:```yaml
  environment:
      - HEADER=
          X-Frame-Options:SAMEORIGIN,
          X-XSS-Protection:1; mode=block;,
          Content-Security-Policy:default-src 'self'; style-src 'self' 'unsafe-inline';
```
## 로깅

기본적으로 요청 로그는 생성되지 않습니다. `--logger.enabled`를 설정하여 활성화할 수 있습니다. 로그(자동 회전)에는 [Apache Combined Log Format](http://httpd.apache.org/docs/2.2/logs.html#combined)이 사용됩니다.

사용자는 `--logger.stdout`을 사용하여 stdout 로그를 활성화할 수도 있습니다. 이는 위의 파일 로깅에 영향을 주지 않지만, 처리된 요청에 대한 최소한의 정보(예: 다음과 같은 형식)를 출력합니다:```
2021/04/16 01:17:25.601 [INFO]  GET - /echo/image.png - xxx.xxx.xxx.xxx - 200 (155400) - 371.661251ms
2021/04/16 01:18:18.959 [INFO]  GET - /api/v1/params - xxx.xxx.xxx.xxx - 200 (74) - 1.217669m
```
## Assets Server

사용자는 정적 파일을 제공하기 위해 자산 서버를 켤 수 있습니다(기본값은 꺼짐). `--assets.location`이 설정되어 있는 한, `assets.root` 아래의 모든 프록시되지 않은 요청을 정적 파일 요청으로 처리합니다. 자산 서버는 프록시 제공자 없이 사용할 수 있습니다. 이 모드에서 reproxy는 정적 콘텐츠에 대한 간단한 웹 서버 역할을 합니다. 자산 서버는 또한 `--assets.spa`를 사용한 "SPA 모드"를 지원하며, 여기서 찾을 수 없는 모든 요청은 `index.html`로 전달됩니다.

일반 자산 서버 외에도 여러 사용자 정의 자산 서버가 지원됩니다. 각 제공자는 이러한 정적 규칙을 정의하는 방법이 다르며, 일부 제공자는 전혀 지원하지 않을 수 있습니다. 예를 들어, 여러 자산 서버는 정적(명령줄 제공자), 파일 제공자에서 유용하고 Docker 제공자에서도 유용하지만, Consul 카탈로그 제공자에서는 거의 의미가 없습니다.

1. 정적 제공자 - 소스 요소에 `assets:` 또는 `spa:` 접두사가 있으면 파일 서버로 처리됩니다. 예를 들어 `*,assets:/web,/var/www,`는 `/var/www` 디렉토리를 기반으로 하는 파일 서버로 모든 `/web/*` 요청을 제공합니다.
2. 파일 제공자 - 선택적 필드 `assets: true` 또는 `spa: true`를 설정합니다. 참고: `route` 필드는 정규식 패턴이 아닌 경로 접두사(예: `/`, `/web/`)여야 합니다.
3. Docker 제공자 - `reproxy.assets=web-root:location`, 즉 `reproxy.assets=/web:/var/www`. SPA 모드로 전환하려면 `reproxy.spa`를 `yes` 또는 `true`로 설정합니다.

### Caching

자산 서버는 `--assets.cache=<duration>` 매개변수를 사용한 캐싱 제어를 지원합니다. `0s` 지속 시간(기본값)은 캐싱 제어를 끕니다. 지속 시간은 선택적 분수와 단위 접미사가 있는 십진수 시퀀스입니다(예: "300ms", "1.5h" 또는 "2h45m"). 유효한 시간 단위는 "ns", "us"(또는 "µs"), "ms", "s", "m", "h", "d"입니다.

캐시 지속 시간을 설정하는 두 가지 방법이 있습니다:

1. 모든 정적 자산에 대한 단일 값. `--assets.cache=48h`처럼 간단합니다.
2. 다른 MIME 유형에 대한 사용자 정의 지속 시간. 두 부분(기본값 및 mime:duration 쌍)을 포함해야 합니다. 명령줄에서는 여러 `--assets.cache` 옵션처럼 보입니다(예: `--assets.cache=48h --assets.cache=text/html:24h --assets.cache=image/png:2h`). 환경 변수 값은 쉼표로 구분되어야 합니다(예: `ASSETS_CACHE=48h,text/html:24h,image/png:2h`).

사용자 정의 404(찾을 수 없음) 페이지는 `--assets.not-found=<path>` 매개변수로 설정할 수 있습니다. 경로는 자산 루트를 기준으로 해야 합니다.

## Using reproxy as a base image

순수하게 정적 콘텐츠를 제공하는 것은 인기 있는 사용 사례 중 하나입니다. 일반적으로 이는 UI만 제공하는 별도의 프론트엔드 컨테이너에 사용됩니다. 자산 서버를 사용하면 이러한 컨테이너를 만드는 것이 거의 사소합니다. 이는 [reproxy.io](http://reproxy.io)를 제공하는 컨테이너의 예입니다.```docker
FROM node:22-alpine as build

WORKDIR /build
COPY site/ /build
COPY README.md /build/src/index.md

RUN yarn --frozen-lockfile
RUN yarn build
RUN	ls -la /build/public

FROM ghcr.io/umputun/reproxy
COPY --from=build /build/public /srv/site
EXPOSE 8080
USER app
ENTRYPOINT ["/srv/reproxy", "--assets.location=/srv/site"]
```
모든 필요한 것은 정적 자산을 특정 위치에 복사하고 그 위치를 `"--assets.location`으로 reproxy 시작점에 전달하는 것입니다.

## SPA 친화 모드

일부 SPA 애플리케이션은 프록시가 정적 자산의 404를 특별한 방식으로 처리하여 "/index.html"로 리디렉션하도록 합니다. 이는 nginx의 `try_files $uri $uri/ …` 지시문과 유사하며, 현대 웹 앱에서 이 기능이 다소 중요합니다.

이 모드는 기본적으로 꺼져 있으며, `--assets.spa` 설정 또는 `ASSETS_SPA=true` 환경 변수로 활성화할 수 있습니다.

## 리디렉션

기본적으로 reproxy는 대상 URL을 프록시 위치로 처리합니다. 즉, 내부적으로 HTTP 호출을 호출하고 응답을 클라이언트에 반환합니다. 그러나 대상 URL 앞에 `@code`를 붙이면 이 동작이 영구(상태 코드 301) 또는 임시(상태 코드 302) 리디렉션으로 변경될 수 있습니다. 즉, 대상이 `@301 https://example.com/something`로 설정되면 `Location: https://example.com/something`으로 영구 HTTP 리디렉션이 발생합니다.

지원되는 코드:

- `@301`, `@perm` - 영구 리디렉션
- `@302`, `@temp`, `@tmp` - 임시 리디렉션

## 추가 옵션

- `--gzip`   응답에 대한 gzip 압축을 활성화합니다.
- `--max=N`  요청의 최대 크기를 설정할 수 있습니다(기본값 64k). `0`으로 설정하면 크기 검사가 비활성화됩니다.
- `--timeout.*` 서버 및 프록시 전송에 대한 다양한 시간 제한. [모든 애플리케이션 옵션](#모든-애플리케이션-옵션)의 `timeout` 섹션을 참조하세요. 0 또는 음수 값은 시간 제한이 없음을 의미합니다.
- `--insecure` 대상 호스트의 SSL 검증을 비활성화합니다. 자체 서명된 인증서에 유용합니다.

## 기본 포트

사용자 정의 매개변수/환경을 전달할 필요성을 없애기 위해 기본 `--listen`은 동적이며 일반적인 경우에 합리적이고 도움이 되도록 설계되었습니다:

- 사용자가 `--listen`에 어떤 값을 설정하면 아래 로직은 무시되고 전달된 호스트:포트가 직접 사용됩니다.
- 사용자가 `--listen`에 아무것도 설정하지 않았고 reproxy가 도커 컨테이너 외부에서 실행되는 경우, 기본값은 http 모드(`ssl.type=none`)에서 `127.0.0.1:80`, ssl 모드(`ssl.type=auto` 또는 `ssl.type=static`)에서 `127.0.0.1:443`입니다.
- 사용자가 `--listen`에 아무것도 설정하지 않았고 reproxy가 도커 내부에서 실행되는 경우, 기본값은 http 모드에서 `0.0.0.0:8080`, ssl 모드에서 `0.0.0.0:8443`입니다.

또 다른 동적으로 설정되는 기본값은 `--ssl.http-port`입니다. 도커 컨테이너 내부에서 실행될 때는 `8080`으로, 그렇지 않을 때는 `80`으로 설정됩니다.

## 핑, 상태 확인 및 장애 조치

reproxy는 이 목적을 위해 두 개의 엔드포인트를 제공합니다:

- `/ping`은 `pong`으로 응답하며 reproxy가 실행 중임을 나타냅니다.
- `/health`는 모든 대상 서버가 핑 요청에 `200`으로 응답하면 `200 OK` 상태를 반환하고, 서버 중 하나라도 200이 아닌 코드로 응답하면 `417 Expectation Failed`를 반환합니다. 또한 통과/실패한 서비스에 대한 세부 정보가 포함된 JSON 본문을 반환합니다.

위 엔드포인트 외에도 reproxy는 선택적 실시간 상태 확인을 지원합니다. 이 경우(활성화된 경우) 각 대상은 주기적으로 핑 응답을 확인하고 실패한 대상 경로는 제외됩니다. 동일하거나 다양한 제공자로부터 여러 개의 동일한 대상을 반환할 수 있으며, 통과한 대상만 선택됩니다. 여러 일치 항목이 발견되고 통과한 경우 `lb-type` 전략(기본적으로 무작위 선택)에 따라 최종 대상이 선택됩니다.

실시간 상태 확인을 켜려면 사용자가 `--health-check.enabled` (또는 환경 변수 `HEALTH_CHECK_ENABLED=true`)를 설정해야 합니다. 확인 간격을 사용자 정의하려면 `--health-check.interval=`를 사용할 수 있습니다.

## 관리 API

선택 사항이며, `--mgmt.enabled`로 활성화할 수 있습니다. `mgmt.listen`(주소:포트)에 2개의 엔드포인트를 노출합니다:

- `GET /routes` - 발견된 모든 경로 목록
- `GET /metrics` - Prometheus 메트릭 반환 (`http_requests_total`, `response_status`, `http_response_time_seconds`)

기본적으로 `http_response_time_seconds`는 원시 요청 경로를 레이블로 사용하므로 동적 URL(예: `/api/users/123`, `/api/users/456`)에서 높은 카디널리티가 발생할 수 있습니다. `--mgmt.low-cardinality`를 사용하면 경로 패턴(예: `^/api/users/(.*)`)으로 전환하여 메트릭 카디널리티를 크게 줄일 수 있습니다.

_참고 [examples/metrics](https://github.com/umputun/reproxy/tree/master/examples/metrics)_

## 오류 보고

Reproxy는 요청이 제공된 경로나 자산과 일치하지 않을 경우 502(Bad Gateway) 오류를 반환합니다. 예상치 못한 내부 오류가 발생하면 500을 반환합니다. 기본적으로 reproxy는 가장 간단한 텍스트 버전의 오류인 "Server error"를 렌더링합니다. `--error.enabled`를 설정하면 기본 HTML 오류 메시지가 켜지고, `--error.template`으로 사용자는 오류 렌더링을 위한 사용자 정의 HTML 템플릿 파일을 설정할 수 있습니다. 템플릿에는 `{{.ErrCode}}`와 `{{.ErrMessage}}`의 두 가지 변수가 있습니다. 예를 들어, 이 템플릿 `oh my! {{.ErrCode}} - {{.ErrMessage}}`는 `oh my! 502 - Bad Gateway`로 렌더링됩니다.

## 조절

Reproxy를 사용하면 전체 시스템 활동 및 사용자별 최대 req/초 값을 정의할 수 있습니다. 0 값(기본값)은 무제한으로 처리됩니다.

사용자 활동은 일치하는 경로와 일치하지 않는 경로 모두에 대해 제한됩니다. 일치하지 않는 모든 경로는 "단일 대상 그룹"으로 간주되며 `rate*3`인 공통 제한기를 받습니다. 즉, `--throttle.user=10`으로 10(req/sec)가 정의되면 최종 사용자는 정적 자산 또는 일치하지 않는 경로에 대해 초당 최대 30개의 요청을 수행할 수 있습니다. 일치하는 경로의 경우 이 제한기는 대상(경로)별로 유지됩니다. 즉, s1.example.com/api로 프록시된 요청은 10 r/s를 허용하고 s2.example.com으로 프록시된 요청은 또 다른 10 r/s를 허용합니다.

### 경로별 시간 제한 및 조절

개별 경로는 제공자별 `timeout` 및 `throttle` 필드를 통해 전역 `--timeout.write` 및 `--throttle.user` 설정을 재정의할 수 있습니다. 이는 업로드, 보고서 생성 등과 같은 장기 실행 엔드포인트에 유용하며, 전역 쓰기 시간 제한보다 높은 데드라인이 필요하거나 다른 모든 것에 대해 전역 상한선을 높이지 않고 민감한 경로(예: 로그인)의 속도 제한을 강화할 때 유용합니다.

우선 순위는 "0은 전역 상속, 양수는 재정의"입니다. `timeout: 0`(또는 `timeout` 필드 없음)인 경로는 전역 `--timeout.write`를 유지하고, `timeout: 5m`인 경로는 일치하는 요청에 대해서만 재정의합니다. `throttle`에도 동일한 규칙이 적용됩니다.

경로별 시간 제한은 일치하는 요청에 대해 연결의 읽기 및 쓰기 데드라인을 재정의하므로 전역 `--timeout.write`(기본값 30s)를 초과할 수 있습니다. 경로별 시간 제한이 없는 경로는 여전히 전역 설정을 따릅니다.

**제한 사항 — 전송 수준 응답 헤더 시간 제한:** 경로별 `timeout`은 `--timeout.resp-header`(기본값 5s)를 재정의하지 않습니다. 해당 시간 제한은 공유 `http.Transport`에 설정되며 업스트림이 응답 헤더 전송을 시작하기 전에 적용됩니다. 업스트림이 응답을 시작하는 데 `--timeout.resp-header`보다 오래 걸리면(예: 느린 보고서 엔드포인트) 경로별 `timeout`과 관계없이 해당 경계에서 요청이 실패합니다. 이러한 경로를 지원하려면 느린 응답 경로에 필요한 최대값으로 전역 `--timeout.resp-header`를 높이십시오. 전송 수준 시간 제한의 경로별 재정의는 의도적으로 범위 밖입니다.

제공자 구문:
- **파일 제공자** (YAML): `timeout: 5m`, `throttle: 2`
- **정적 제공자** (CSV): 6번째 및 7번째 위치 필드, 예: `*,^/upload/(.*),http://up:8080/$1,,,5m,2`
- **Docker 제공자**: `reproxy.timeout=5m`, `reproxy.throttle=2` (또는 다중 경로 컨테이너의 경우 `reproxy.<n>.timeout` / `reproxy.<n>.throttle`)
- **Consul Catalog 제공자**: `reproxy.timeout=5m`, `reproxy.throttle=2`

## 업스트림 연결 제한

Reproxy를 사용하면 업스트림 연결 풀 설정을 구성하여 백엔드 서버에 유지되는 연결 수를 제어할 수 있습니다:

- `--upstream.max-idle-conns` - 모든 업스트림 호스트의 유휴 연결 최대 수. 기본값: 100.
- `--upstream.max-conns` - 업스트림 호스트당 최대 연결 수(0 = 무제한). 기본값: 0.

`--upstream.max-conns`를 설정하면 각 백엔드에 대한 동시 연결을 제한하여 업스트림 서버의 용량이 제한적이거나 연결 고갈을 방지하는 데 유용합니다.

## 기본 인증

Reproxy는 두 가지 모드(전역(모든 경로) 및 경로별)에서 기본 인증을 지원합니다.

### 전역 기본 인증

전역 기본 인증은 모든 경로를 보호합니다. 개발 및 테스트 중에 엔드포인트를 보호하는 데 유용합니다. 활성화하려면 `--basic-htpasswd=<파일 위치>` 또는 환경 변수 `BASIC_HTPASSWD=<파일 위치>`로 htpasswd 파일을 설정하십시오.

Reproxy는 htpasswd 파일이 다음 형식일 것으로 예상합니다:```
username1:bcrypt(password1)
username2:bcrypt(password2)
...
```
이것은 `htpasswd -nbB` 명령어로 생성할 수 있습니다. 예: `htpasswd -nbB test passwd`

### 경로별 기본 인증

경로별 인증은 각 경로에 대해 다른 자격 증명을 허용합니다. 경로에 경로별 인증이 설정되면 해당 경로에 대한 전역 인증이 우회됩니다. 경로별 인증은 공급자별 설정을 통해 구성됩니다:

- **파일 공급자**: YAML의 `auth` 필드, 예: `auth: "user1:$2y$..., user2:$2y$..."`
- **Docker 공급자**: `reproxy.auth` 레이블
- **Consul Catalog 공급자**: `reproxy.auth` 태그
- **정적 공급자**: 지원되지 않음 (경로별 인증을 위해 파일 공급자 사용)

형식은 쉼표로 구분된 `user:bcrypt_hash` 쌍 목록입니다 (동일한 htpasswd 형식). 동일한 경로에 여러 사용자를 지정할 수 있습니다.

docker-compose 예시:```yaml
services:
  admin-api:
    labels:
      - "reproxy.route=^/admin/(.*)"
      - "reproxy.dest=/$1"
      - "reproxy.auth=admin:$$2y$$05$$hashedpassword"
```
참고: docker-compose에서 `$`는 `$$`로 이스케이프되어야 합니다.

## IP 기반 접근 제어

Reproxy는 쉼표로 구분된 서브넷 또는 IP 목록으로 경로에 대한 접근을 제한할 수 있습니다. 이는 개발 및 테스트 시 유용하며, 무제한 접근을 허용하기 전에 사용할 수 있습니다. 또한 내부 서비스에 대한 접근을 제한하는 데 사용할 수도 있습니다. 기본적으로 모든 경로는 모든 클라이언트에 대해 열려 있습니다.

경로에 대한 접근을 제한하려면 사용자는 해당 경로에 적절한 키를 설정해야 합니다. 즉, docker 및 consul의 경우 `reproxy.remote`, 파일 제공자의 경우 `remote`입니다. 값은 쉼표로 구분된 서브넷 또는 IP 또는 서브넷 목록이어야 합니다. 예: `127.0.0.1, 192.168.1.0/24`. 자세한 내용은 [docker 제공자](#docker-provider) 및 [consul 카탈로그 제공자](#consul-catalog-provider) 섹션을 참조하세요.

기본적으로 reproxy는 클라이언트 요청의 원격 주소를 확인합니다. 그러나 다른 프록시 뒤에 있거나 docker 브리지 네트워크를 사용하는 경우 예상대로 작동하지 않을 수 있습니다. 이는 `--remote-lookup-headers` 매개변수를 통해 변경할 수 있으며, 이를 통해 `X-Real-IP` 또는 `X-Forwarded-For` 헤더의 값을 확인하고(이 순서로) 확인에 사용할 수 있습니다. 헤더가 설정되지 않은 경우 클라이언트의 원격 주소를 기준으로 확인이 수행됩니다. 이러한 헤더는 클라이언트에 의해 제공되며 쉽게 위조될 수 있으므로, 이 매개변수는 reproxy가 항상 이러한 헤더를 설정하고 덮어쓰는 신뢰할 수 있는 정방향 프록시 뒤에서 실행될 때만 활성화해야 합니다.

헤더 확인은 위조 가능성이 있으므로 주의해서 사용해야 합니다. `--remote-lookup-headers`가 활성화되면 IP 허용 목록은 전적으로 이 신뢰 가정에 의존합니다. 즉, 허용된 주소로 `X-Real-IP` 또는 `X-Forwarded-For`를 보내는 클라이언트는 그렇지 않으면 제한을 우회할 수 있습니다. 이 옵션은 reproxy가 이러한 헤더를 제어하는 신뢰할 수 있는 프록시 뒤에 있고 위조되지 않음을 보장할 수 있는 경우에만 활성화하세요.

## 플러그인 지원

reproxy의 핵심 기능은 외부 플러그인으로 확장할 수 있습니다. 각 플러그인은 [rpc 서버](https://golang.org/pkg/net/rpc/)를 구현하는 독립적인 프로세스/컨테이너입니다. 플러그인은 reproxy conductor에 등록되고 미들웨어 체인에 추가됩니다. 각 플러그인은 원래 URL, 헤더 및 일치하는 모든 경로 정보가 포함된 요청을 수신하고 헤더와 상태 코드로 응답합니다. 상태 코드가 400 이상이면 오류 응답으로 처리되고 프록시 오류와 함께 흐름이 즉시 종료됩니다. 플러그인이 설정할 수 있는 두 가지 유형의 헤더가 있습니다.

- `HeadersIn` - 들어오는 헤더. 프록시된 URL로 전송됩니다.
- `HeadersOut` - 나가는 헤더. 클라이언트로 다시 전송됩니다.

기본적으로 플러그인이 설정한 헤더는 원래 헤더와 혼합됩니다. 플러그인이 모든 헤더를 제어해야 하는 경우(예: 일부 헤더를 제거) 플러그인이 `OverrideHeaders*` 필드를 설정하여 코어 reproxy 프로세스에 헤더를 혼합하는 대신 덮어써야 함을 나타낼 수 있습니다.

- `OverrideHeadersIn` - 들어오는 모든 헤더에 대해 플러그인이 책임진다는 것을 나타냅니다.
- `OverrideHeadersOut` - 나가는 모든 헤더에 대해 플러그인이 책임진다는 것을 나타냅니다.

개발 프로세스를 단순화하기 위해 모든 구성 요소가 제공됩니다. 여기에는 등록, 수신 대기 및 호출 디스패치를 처리하는 `lib.Plugin`과 입력 및 출력을 정의하는 `lib.Request` 및 `lib.Response`가 포함됩니다. 플러그인 작성자는 `func(req lib.Request, res *lib.HandlerResponse) (err error)` 서명을 만족하는 구체적인 핸들러를 구현해야 합니다. 각 플러그인에는 이와 같은 여러 핸들러가 포함될 수 있습니다.

_자세한 내용은 [examples/plugin](https://github.com/umputun/reproxy/tree/master/examples/plugin)을 참조하세요_

## 컨테이너 보안

기본적으로 reproxy 컨테이너는 초기 설정을 단순화하고 docker 소켓에 액세스하기 위해 root 사용자로 실행됩니다. 이는 docker 제공자가 실행 중인 컨테이너를 검색할 수 있도록 하기 위해 필요합니다. 그러나 이러한 검색이 필요하지 않거나 docker 제공자를 사용하지 않는 경우 권한이 낮은 사용자로 변경하는 것이 좋습니다. 이는 docker-compose 수준과 docker의 `user` 옵션으로 수행할 수 있습니다. 자세한 내용은 아래 섹션을 참조하세요.

때로는 docker 내부 라우팅을 사용하더라도 docker 제공자를 비활성화하고 정적 또는 파일 제공자로 규칙을 설정하는 것이 합리적입니다. compose 내에서 실행되는 모든 컨테이너는 동일한 네트워크를 공유하고 로컬 DNS를 통해 접근 가능합니다. 사용자는 docker 검색을 피하기 위해 다음과 같은 규칙을 가질 수 있습니다: `- STATIC_RULES=*,/api/email/(.*),http://email-sender:8080/$$1`. 이 규칙은 동일한 compose 내에 정의된 `email-sender` 컨테이너를 예상합니다. 참고: 대상 서비스가 다른 compose 파일에 정의되어 있더라도 docker 네트워크를 사용하여 동일한 결과를 얻을 수 있습니다. 이렇게 하면 reproxy 구성을 실제 서비스와 분리하여 유지할 수 있습니다.

reproxy 컨테이너 내부에는 reproxy 바이너리 외에는 아무것도 없습니다. 빈(scratch) 이미지 위에 빌드되기 때문입니다.

### 비-root 사용자로 실행

UID `1001`(그룹 `1001` 및 `999`에 속함)을 가진 사용자가 컨테이너 내에 미리 생성되어 있으며, 비-root 사용자로 reproxy를 실행하는 데 사용할 수 있습니다:```yaml
services:
  reproxy:
    user: 1001
    image: umputun/reproxy:latest
# <...>
# see examples/ssl/docker-compose.yml for the full file example
```
Docker 제공자를 사용하려면 이 사용자가 호스트 시스템의 Docker 소켓에 접근할 권한이 있는지 확인해야 합니다. 이러한 권한을 설정하는 방법은 호스트 시스템 구성에 따라 다릅니다. Docker 소켓 권한 구성에 대한 자세한 내용은 [Docker 데몬 소켓 보안에 대한 Docker 문서](https://docs.docker.com/engine/security/protect-access/)를 참조하십시오.

## 옵션

각 옵션은 명령줄 또는 환경 키:값 쌍의 두 가지 형태로 제공될 수 있습니다. 일부 명령줄 옵션은 `-l localhost:8080`과 같은 짧은 형식을 가지며, 모든 옵션은 `--listen=localhost:8080`과 같은 긴 형식을 갖습니다. 각 옵션에 대한 환경 키(이름)는 접미사로 [나열](#all-application-options)되며, 예를 들어 `[$LISTEN]`과 같습니다.

모든 크기 옵션은 단위 접미사를 지원합니다. 예를 들어 10K(또는 10k)는 킬로바이트, 16M(또는 16m)는 메가바이트, 10G(또는 10g)는 기가바이트를 나타냅니다. 접미사가 없는 경우(예: 1024)는 바이트를 의미합니다.

일부 옵션은 반복 가능합니다. 이 경우 사용자는 명령줄에 여러 번 전달하거나 환경 변수에 쉼표로 구분하여 전달할 수 있습니다. 예를 들어 `--ssl.fqdn`은 그러한 옵션으로, `--ssl.fqdn=a1.example.com --ssl.fqdn=a2.example.com` 또는 환경 변수 `SSL_ACME_FQDN=a1.example.com,a2.example.com`으로 전달할 수 있습니다.

다음은 여러 요소를 지원하는 모든 옵션의 목록입니다: 

- `ssl.fqdn` (`SSL_ACME_FQDN`)
- `assets.cache` (`ASSETS_CACHE`)
- `docker.exclude` (`DOCKER_EXCLUDE`)
- `static.rule` (`$STATIC_RULES`)
- `header` (`$HEADER`)
- `drop-header` (`$DROP_HEADERS`)

## 모든 애플리케이션 옵션```
  -l, --listen=                     listen on host:port (default: 0.0.0.0:8080/8443 under docker, 127.0.0.1:80/443 without) [$LISTEN]
  -m, --max=                        max request size (default: 64K) [$MAX_SIZE]
  -g, --gzip                        enable gz compression [$GZIP]
  -x, --header=                     outgoing proxy headers to add [$HEADER]
      --drop-header=                incoming headers to drop [$DROP_HEADERS]
      --basic-htpasswd=             htpasswd file for basic auth [$BASIC_HTPASSWD]      
      --lb-type=[random|failover|roundrobin]   load balancer type (default: random) [$LB_TYPE]
      --signature                   enable reproxy signature headers [$SIGNATURE]
      --remote-lookup-headers       enable remote lookup headers, trust only behind a trusted proxy [$REMOTE_LOOKUP_HEADERS]
      --keep-host                   keep original Host header as default when proxying [$KEEP_HOST]
      --insecure                    skip SSL verification on destination host [$INSECURE]
      --dbg                         debug mode [$DEBUG]

ssl:
      --ssl.type=[none|static|auto] ssl (auto) support (default: none) [$SSL_TYPE]
      --ssl.cert=                   path to cert.pem file [$SSL_CERT]
      --ssl.key=                    path to key.pem file [$SSL_KEY]
      --ssl.acme-location=          dir where certificates will be stored by autocert manager (default: ./var/acme) [$SSL_ACME_LOCATION]
      --ssl.acme-email=             admin email for certificate notifications [$SSL_ACME_EMAIL]
      --ssl.http-port=              http port for redirect to https and acme challenge test (default: 8080 under docker, 80 without) [$SSL_HTTP_PORT]
      --ssl.fqdn=                   FQDN(s) for ACME certificates [$SSL_ACME_FQDN]

assets:
  -a, --assets.location=            assets location [$ASSETS_LOCATION]
      --assets.root=                assets web root (default: /) [$ASSETS_ROOT]
      --assets.spa                  spa treatment for assets [$ASSETS_SPA]
      --assets.cache=               cache duration for assets [$ASSETS_CACHE]
      --assets.not-found=           path to file to serve on 404, relative to location [$ASSETS_NOT_FOUND]

logger:
      --logger.stdout               enable stdout logging [$LOGGER_STDOUT]
      --logger.enabled              enable access and error rotated logs [$LOGGER_ENABLED]
      --logger.file=                location of access log (default: access.log) [$LOGGER_FILE]
      --logger.max-size=            maximum size before it gets rotated (default: 100M) [$LOGGER_MAX_SIZE]
      --logger.max-backups=         maximum number of old log files to retain (default: 10) [$LOGGER_MAX_BACKUPS]

docker:
      --docker.enabled              enable docker provider [$DOCKER_ENABLED]
      --docker.host=                docker host (default: unix:///var/run/docker.sock) [$DOCKER_HOST]
      --docker.network=             docker network [$DOCKER_NETWORK]
      --docker.exclude=             excluded containers [$DOCKER_EXCLUDE]
      --docker.auto                 enable automatic routing (without labels) [$DOCKER_AUTO]
      --docker.prefix=              prefix for docker source routes [$DOCKER_PREFIX]
      --docker.api-version=         docker API version (default: 1.24) [$DOCKER_API_VERSION]

consul-catalog:
      --consul-catalog.enabled      enable consul catalog provider [$CONSUL_CATALOG_ENABLED]
      --consul-catalog.address=     consul address (default: http://127.0.0.1:8500) [$CONSUL_CATALOG_ADDRESS]
      --consul-catalog.interval=    consul catalog check interval (default: 1s) [$CONSUL_CATALOG_INTERVAL]

file:
      --file.enabled                enable file provider [$FILE_ENABLED]
      --file.name=                  file name (default: reproxy.yml) [$FILE_NAME]
      --file.interval=              file check interval (default: 3s) [$FILE_INTERVAL]
      --file.delay=                 reload only after the file has been unchanged for this long (default: 500ms) [$FILE_DELAY]

static:
      --static.enabled              enable static provider [$STATIC_ENABLED]
      --static.rule=                routing rules [$STATIC_RULES]

timeout:
      --timeout.read-header=        read header server timeout (default: 5s) [$TIMEOUT_READ_HEADER]
      --timeout.write=              write server timeout (default: 30s) [$TIMEOUT_WRITE]
      --timeout.idle=               idle server timeout (default: 30s) [$TIMEOUT_IDLE]
      --timeout.dial=               dial transport timeout (default: 30s) [$TIMEOUT_DIAL]
      --timeout.keep-alive=         keep-alive transport timeout (default: 30s) [$TIMEOUT_KEEP_ALIVE]
      --timeout.resp-header=        response header transport timeout (default: 5s) [$TIMEOUT_RESP_HEADER]
      --timeout.idle-conn=          idle connection transport timeout (default: 90s) [$TIMEOUT_IDLE_CONN]
      --timeout.tls=                TLS hanshake transport timeout (default: 10s) [$TIMEOUT_TLS]
      --timeout.continue=           expect continue transport timeout (default: 1s) [$TIMEOUT_CONTINUE]

mgmt:
      --mgmt.enabled                enable management API [$MGMT_ENABLED]
      --mgmt.listen=                listen on host:port (default: 0.0.0.0:8081) [$MGMT_LISTEN]
      --mgmt.low-cardinality        use route patterns instead of raw paths for metrics labels [$MGMT_LOW_CARDINALITY]

error:
      --error.enabled               enable html errors reporting [$ERROR_ENABLED]
      --error.template=             error message template file [$ERROR_TEMPLATE]

health-check:
      --health-check.enabled        enable automatic health-check [$HEALTH_CHECK_ENABLED]
      --health-check.interval=      automatic health-check interval (default: 300s) [$HEALTH_CHECK_INTERVAL]

throttle:
      --throttle.system=            throttle overall activity' (default: 0) [$THROTTLE_SYSTEM]
      --throttle.user=              limit req/sec per user and per proxy destination (default: 0) [$THROTTLE_USER]

upstream:
      --upstream.max-idle-conns=    max idle connections total (default: 100) [$UPSTREAM_MAX_IDLE_CONNS]
      --upstream.max-conns=         max connections per upstream host (0=unlimited) (default: 0) [$UPSTREAM_MAX_CONNS]

plugin:
      --plugin.enabled              enable plugin support [$PLUGIN_ENABLED]
      --plugin.listen=              registration listen on host:port (default: 127.0.0.1:8081) [$PLUGIN_LISTEN]

Help Options:
  -h, --help                        Show this help message

```
## 상태

이 프로젝트는 활발히 개발 중이며 `v1`이 출시될 때까지 호환성을 깨는 변경이 있을 수 있습니다. 하지만 좋은 이유가 없는 한 변경을 최소화하기 위해 최선을 다하고 있습니다. 0.4.x 버전 기준으로 reproxy는 실제 사용에 충분히 적합한 것으로 간주되며, 많은 환경에서 프로덕션 용도로 사용되고 있습니다.