또는 [릴리스 페이지](https://github.com/git-pkgs/proxy/releases)에서 바이너리를 다운로드하세요.

### Helm

GHCR에서 차트를 설치하고, 패키지 관리자 클라이언트가 프록시에 접근하는 데 사용할 공개 URL을 설정하세요:```bash
helm install proxy oci://ghcr.io/git-pkgs/charts/proxy \
  --set config.data.base_url=https://proxy.example.com

이제 프록시가 실행 중입니다. 패키지 관리자가 이를 사용하도록 구성하세요.

## OpenAPI (Swagger)

이 저장소는 주석이 달린 핸들러로부터 OpenAPI 명세를 생성하기 위해 swaggo를 사용합니다.

명세 생성:```bash
go install github.com/swaggo/swag/cmd/swag@latest
go generate ./internal/server

또는 `.npmrc`에서 프로젝트별로 설정하세요:```
registry=http://localhost:8080/npm/

### Cargo

`~/.cargo/config.toml` 파일을 생성하거나 편집하세요:```toml
[source.crates-io]
replace-with = "proxy"

[source.proxy]
registry = "sparse+http://localhost:8080/cargo/"

전역으로 구성하려면:```bash
gem sources --add http://localhost:8080/gem/
bundle config mirror.https://rubygems.org http://localhost:8080/gem

또는 지속성을 위해 셸 프로필에 추가하세요.

### Homebrew

Homebrew의 JSON API와 아티팩트 도메인을 프록시로 지정하세요:```bash
export HOMEBREW_API_DOMAIN=http://localhost:8080/homebrew
export HOMEBREW_ARTIFACT_DOMAIN=http://localhost:8080

해당 환경 변수는 `PROXY_UPSTREAM_HOMEBREW_API`와 `PROXY_UPSTREAM_HOMEBREW_ARTIFACT`입니다.

### Hex (Elixir)

`~/.hex/hex.config`에서 설정하세요:```erlang
{default_url, <<"http://localhost:8080/hex">>}.

### pub.dev (Dart/Flutter)

PUB_HOSTED_URL 환경 변수를 설정하세요:```bash
export PUB_HOSTED_URL=http://localhost:8080/pub

또는 `~/.pip/pip.conf`에서 설정하세요:```ini
[global]
index-url = http://localhost:8080/pypi/simple/

`/maven/` 엔드포인트는 Maven Central을 기본 업스트림으로 사용하며, 기본 업스트림이 not found를 반환할 경우 Gradle 플러그인 마커 메타데이터 및 관련 아티팩트를 위해 Gradle Plugin Portal로 폴백합니다.

동일한 프록시 엔드포인트를 통한 Gradle 플러그인 해석:```kotlin
pluginManagement {
  repositories {
    maven(url = "http://localhost:8080/maven/")
  }
}

### NuGet

`nuget.config`에서 구성합니다:```xml
<configuration>
  <packageSources>
    <clear />
    <add key="proxy" value="http://localhost:8080/nuget/v3/index.json" />
  </packageSources>
</configuration>

### Composer (PHP)

`composer.json`에서 구성:```json
{
    "repositories": [
        {
            "type": "composer",
            "url": "http://localhost:8080/composer"
        }
    ]
}

### Conan (C/C++)

프록시를 원격으로 추가:```bash
conan remote add proxy http://localhost:8080/conan
conan remote disable conancenter

또는 명령으로 설정:```bash
conda config --add channels http://localhost:8080/conda/main

또는 지속성을 위해 `~/.Rprofile`에 추가합니다:```r
local({
  r <- getOption("repos")
  r["CRAN"] <- "http://localhost:8080/cran"
  options(repos = r)
})

또는 실행 중인 세션 내에서:```julia
ENV["JULIA_PKG_SERVER"] = "http://localhost:8080/julia"
using Pkg; Pkg.update()

Registry 종속성은 `Package.swift`에서 스코프가 지정된 패키지 식별자를 사용합니다:```swift
dependencies: [
    .package(id: "apple.swift-argument-parser", from: "1.2.0")
]

그런 다음 Docker를 재시작합니다:```bash
sudo systemctl restart docker

### Helm

각 HTTP 차트 저장소를 이름으로 구성한 다음, 일치하는 프록시
URL을 Helm에 추가합니다:```yaml
upstream:
  helm:
    bitnami: "https://charts.bitnami.com/bitnami"

def get_global_privilege_escalation_vectors(self):
    """
    시스템에서 전역 권한 상승 벡터를 가져옵니다.

    Returns:
        list: 전역 권한 상승 벡터 목록
    """
    return self.global_privilege_escalation_vectors
``````bash
helm repo add bitnami http://localhost:8080/helm/bitnami
helm repo update
helm pull bitnami/nginx

## 감사합니다!

이 프로젝트에 기여하고 개선하는 데 도움을 주신 모든 분들께 감사드립니다.```bash
helm pull oci://localhost:8080/upstream/ghcr/owner/charts/mychart --version 1.0.0 --plain-http

기존 sources.list 항목을 교체한 후:```bash
sudo apt update

### RPM / Yum / DNF

yum/dnf가 `/etc/yum.repos.d/proxy.repo`의 프록시를 사용하도록 설정하세요:```ini
[proxy-fedora]
name=Fedora via Proxy
baseurl=http://localhost:8080/rpm/releases/$releasever/Everything/$basearch/os/
enabled=1
gpgcheck=0

### Alpine / apk

`/etc/apk/repositories`가 프록시를 가리키도록 설정하세요. 기본 저장소 이름
`alpine`은 공식 미러(`https://dl-cdn.alpinelinux.org/alpine`)를 프록시합니다:```
http://localhost:8080/apk/alpine/v3.22/main
http://localhost:8080/apk/alpine/v3.22/community

Repository 인덱스(v2 `APKINDEX.tar.gz` 및 v3 `Packages.adb`), 분리된
서명, 그리고 패키지는 바이트 단위로 변경 없이 제공되므로 apk의 정상적인
서명 검증이 계속 작동합니다. 인덱스는 메타데이터 캐시
(`metadata_ttl`, stale fallback)를 사용하며, `.apk` 패키지는 공유
아티팩트 캐시에 저장되어 업스트림에 연결할 수 없을 때도 사용할 수 있습니다.

다른 미러나 비공개 저장소를 프록시하려면 `upstream.apk` 아래에 명명된
업스트림을 구성하세요(이것은 내장 기본값을 대체하므로, 여전히 원한다면
`alpine`을 다시 추가하세요):```yaml
upstream:
  apk:
    alpine: "https://dl-cdn.alpinelinux.org/alpine"
    private: "https://apk.example.com"

def get_network_connections(self):
    """
    네트워크 연결에 대한 정보를 검색합니다.

    반환값:
        list: 네트워크 연결에 대한 정보를 담은 딕셔너리 목록.
    """
    try:
        connections = []
        for conn in psutil.net_connections(kind='inet'):
            laddr = f"{conn.laddr.ip}:{conn.laddr.port}" if conn.laddr else "N/A"
            raddr = f"{conn.raddr.ip}:{conn.raddr.port}" if conn.raddr else "N/A"
            connections.append({
                'fd': conn.fd,
                'family': str(conn.family),
                'type': str(conn.type),
                'laddr': laddr,
                'raddr': raddr,
                'status': conn.status,
                'pid': conn.pid
            })
        return connections
    except Exception as e:
        self.logger.error(f"네트워크 연결을 가져오는 중 오류 발생: {e}")
        return []

def get_network_stats(self):
    """
    네트워크 통계를 검색합니다.

    반환값:
        dict: 네트워크 통계를 담은 딕셔너리.
    """
    try:
        net_io = psutil.net_io_counters()
        return {
            'bytes_sent': net_io.bytes_sent,
            'bytes_recv': net_io.bytes_recv,
            'packets_sent': net_io.packets_sent,
            'packets_recv': net_io.packets_recv,
            'errin': net_io.errin,
            'errout': net_io.errout,
            'dropin': net_io.dropin,
            'dropout': net_io.dropout
        }
    except Exception as e:
        self.logger.error(f"네트워크 통계를 가져오는 중 오류 발생: {e}")
        return {}

def get_network_interfaces(self):
    """
    네트워크 인터페이스에 대한 정보를 검색합니다.

    반환값:
        dict: 네트워크 인터페이스에 대한 정보를 담은 딕셔너리.
    """
    try:
        interfaces = {}
        for name, addrs in psutil.net_if_addrs().items():
            interfaces[name] = []
            for addr in addrs:
                interfaces[name].append({
                    'family': str(addr.family),
                    'address': addr.address,
                    'netmask': addr.netmask,
                    'broadcast': addr.broadcast
                })
        return interfaces
    except Exception as e:
        self.logger.error(f"네트워크 인터페이스를 가져오는 중 오류 발생: {e}")
        return {}

def get_network_io_counters(self):
    """
    네트워크 I/O 통계를 검색합니다.

    반환값:
        dict: 네트워크 I/O 통계를 담은 딕셔너리.
    """
    try:
        net_io = psutil.net_io_counters(pernic=True)
        return {nic: {
            'bytes_sent': stats.bytes_sent,
            'bytes_recv': stats.bytes_recv,
            'packets_sent': stats.packets_sent,
            'packets_recv': stats.packets_recv,
            'errin': stats.errin,
            'errout': stats.errout,
            'dropin': stats.dropin,
            'dropout': stats.dropout
        } for nic, stats in net_io.items()}
    except Exception as e:
        self.logger.error(f"네트워크 I/O 카운터를 가져오는 중 오류 발생: {e}")
        return {}

apk는 각 저장소 줄에 아키텍처와 인덱스 파일 이름을 자체적으로
추가합니다.

### GitHub Releases / mise (aqua 백엔드)

명명된 일반 업스트림을 구성합니다:```yaml
upstream:
  generic:
    github: "https://github.com"
    github-api: "https://api.github.com"

릴리스 자산은 최초 다운로드 후 영구적으로 캐시되며 GitHub이 다운된 동안에도 계속 설치됩니다. `api.github.com`을 통한 태그 조회는 `metadata_ttl` 동안 캐시되며 장애나 속도 제한 중에는 오래된 상태로 제공됩니다. `mise.lock`을 커밋하고 `mise install --locked`로 설치하면 고정된 설치에 API 호출이 전혀 필요하지 않습니다. 함대가 GitHub의 익명 속도 제한을 초과하는 경우 `upstream.auth` 아래에 `https://api.github.com`용 베어러 토큰을 추가하세요.

## 구성

프록시는 다음을 통해 구성할 수 있습니다:

1. 명령줄 플래그 (최우선 순위)
2. 환경 변수
3. 구성 파일 (YAML 또는 JSON)

### 명령줄 플래그```
-config string           Path to configuration file
-listen string           Address to listen on (default ":8080")
-base-url string         Public URL of this proxy (default "http://localhost:8080")
-storage-url string      Storage URL (file://, s3://, gs://, azblob://)
-storage-path string     Path to artifact storage directory (deprecated, use -storage-url)
-database-driver string  Database driver: sqlite or postgres (default "sqlite")
-database-path string    Path to SQLite database file (default "./cache/proxy.db")
-database-url string     PostgreSQL connection URL
-log-level string        Log level: debug, info, warn, error (default "info")
-log-format string       Log format: text, json (default "text")
-access-log string       Path to the JSONL access log
-version                 Print version and exit

### 구성 파일```yaml
listen: ":8080"
base_url: "http://localhost:8080"

storage:
  url: "file:///var/cache/proxy/artifacts"
  max_size: "10GB"  # Optional: evict LRU when exceeded

database:
  driver: "sqlite"
  path: "/var/lib/proxy/cache.db"

log:
  level: "info"
  format: "text"

access_log:
  path: "/var/log/proxy/access.jsonl"  # Optional JSONL activity log

# Optional: override upstream URLs
upstream:
  npm: "https://registry.npmjs.org"
  cargo: "https://index.crates.io"
  swift: "https://tuist.dev/api/registry/swift"

# Optional: version cooldown (see above)
cooldown:
  default: "3d"

### PostgreSQL

SQLite가 기본값이며 단일 노드 배포에 적합합니다. 다중 노드 구성이나 관리형 데이터베이스를 선호하는 경우 Postgres로 전환하세요:```yaml
database:
  driver: "postgres"
  url: "postgres://user:password@localhost:5432/proxy?sslmode=disable"

프록시는 첫 실행 시 테이블을 자동으로 생성합니다.

### S3 스토리지

프록시는 캐시된 아티팩트를 로컬 파일 시스템 대신 S3 또는 모든 S3 호환 서비스(MinIO, R2 등)에 저장할 수 있습니다.```yaml
storage:
  url: "s3://my-bucket-name?region=us-east-1"

표준 AWS 환경 변수(`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_REGION`)를 통해 자격 증명을 설정하세요.

### Google Cloud Storage

프록시는 `gs://` URL 스킴을 사용하여 캐시된 아티팩트를 GCS 버킷에 저장할 수 있습니다.```yaml
storage:
  url: "gs://my-bucket-name"

#### Workload Identity를 사용한 직접 제공(서명된 URL)

`direct_serve: true`가 활성화되면 프록시는 미리 서명된 GCS URL로 HTTP 302 리디렉션을 발급합니다. Workload Identity는 개인 키를 제공하지 않으므로 GCS 백엔드는 [IAM Credentials `signBlob` API](https://docs.cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signBlob)를 호출합니다. 서비스 계정에 자기 자신에 대한 token-creator 역할을 부여하세요:```bash
gcloud iam service-accounts add-iam-policy-binding \
  git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator \
  --member="serviceAccount:git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com"

### mirror

PURL, SBOM 파일 또는 전체 레지스트리에서 캐시를 미리 채웁니다. 오프라인 가용성을 보장하거나 배포 전에 캐시를 예열하는 데 유용합니다.```bash
# Mirror specific package versions
proxy mirror pkg:npm/[email protected] pkg:cargo/[email protected]

# Mirror all versions of a package
proxy mirror pkg:npm/lodash

# Mirror from a CycloneDX or SPDX SBOM
proxy mirror --sbom sbom.cdx.json

# Preview what would be mirrored
proxy mirror --dry-run pkg:npm/lodash

# Control parallelism
proxy mirror --concurrency 8 pkg:npm/[email protected]

### stats

서버를 실행하지 않고 캐시 통계를 표시합니다.```bash
# Text output
proxy stats

# JSON output
proxy stats -json

# Custom database path
proxy stats -database-path /var/lib/proxy/cache.db

# With PostgreSQL
proxy stats -database-driver postgres -database-url postgres://user:pass@localhost/proxy

# Show top 20 most popular packages
proxy stats -popular 20

## API 엔드포인트

### 레지스트리 프로토콜

| 엔드포인트 | 설명 |
|----------|-------------|
| `GET /` | 대시보드 (웹 UI) |
| `GET /health` | 상태 확인 및 업스트림 서킷 브레이커 상태 (JSON; HTTP 200 정상, 503 비정상) |
| `GET /stats` | 캐시 통계 (JSON) |
| `GET /metrics` | Prometheus 메트릭 |
| `GET /npm/*` | npm 레지스트리 프로토콜 |
| `GET /cargo/*` | Cargo 스파스 인덱스 프로토콜 |
| `GET /gem/*` | RubyGems 프로토콜 |
| `GET /go/*` | Go 모듈 프록시 프로토콜 |
| `GET /hex/*` | Hex.pm 프로토콜 |
| `GET /pub/*` | pub.dev 프로토콜 |
| `GET /pypi/*` | PyPI simple/JSON API |
| `GET /maven/*` | Maven 저장소 프로토콜 |
| `GET /nuget/*` | NuGet V3 API |
| `GET /composer/*` | Composer/Packagist 프로토콜 |
| `GET /conan/*` | Conan C/C++ 프로토콜 |
| `GET /conda/*` | Conda/Anaconda 프로토콜 |
| `GET /cran/*` | CRAN (R) 프로토콜 |
| `GET /julia/*` | Julia Pkg 서버 프로토콜 |
| `GET /swift/*` | Swift Package Registry v1 프로토콜 |
| `GET /helm/{repository}/*` | HTTP Helm 차트 저장소 프로토콜 |
| `GET /homebrew/*` | Homebrew JSON API |
| `GET /v2/*` | OCI/Docker 레지스트리 프로토콜 |
| `GET /v2/homebrew/core/*` | GHCR의 Homebrew core bottle 매니페스트 및 blob |
| `GET /apk/{repository}/*` | Alpine APK 저장소 프로토콜 |
| `GET /generic/{name}/*` | 범용 HTTP 다운로드 프록시 (GitHub 릴리스 자산, mise/aqua) |
| `GET /debian/*` | Debian/APT 저장소 프로토콜 |
| `GET /rpm/*` | RPM/Yum 저장소 프로토콜 |

### 미러 API

| 엔드포인트 | 설명 |
|----------|-------------|
| `POST /api/mirror` | 미러 작업 시작 (JSON 본문에 `purls` 또는 인라인 `sbom`) |
| `GET /api/mirror/{id}` | 작업 상태 및 진행률 조회 |
| `DELETE /api/mirror/{id}` | 실행 중인 작업 취소 |

### 보강 API

프록시는 패키지 메타데이터 보강, 취약점 스캔, 구버전 감지를 위한 REST 엔드포인트를 제공합니다.

| 엔드포인트 | 설명 |
|----------|-------------|
| `GET /api/package/{ecosystem}/{name}` | 패키지 메타데이터 조회 |
| `GET /api/package/{ecosystem}/{name}/{version}` | 취약점이 포함된 버전 메타데이터 조회 |
| `GET /api/vulns/{ecosystem}/{name}` | 패키지의 모든 취약점 조회 |
| `GET /api/vulns/{ecosystem}/{name}/{version}` | 특정 버전의 취약점 조회 |
| `POST /api/outdated` | 여러 패키지의 구버전 여부 확인 |
| `POST /api/bulk` | 대량 패키지 메타데이터 조회 |

#### 패키지 메타데이터 조회```bash
curl http://localhost:8080/api/package/npm/lodash

#### 취약점이 있는 버전 가져오기```bash
curl http://localhost:8080/api/package/npm/lodash/4.17.0

#### 오래된 패키지 확인```bash
curl -X POST http://localhost:8080/api/outdated \
  -H "Content-Type: application/json" \
  -d '{
    "packages": [
      {"ecosystem": "npm", "name": "lodash", "version": "4.17.0"},
      {"ecosystem": "pypi", "name": "requests", "version": "2.25.0"}
    ]
  }'

#### 대량 패키지 조회```bash
curl -X POST http://localhost:8080/api/bulk \
  -H "Content-Type: application/json" \
  -d '{
    "purls": [
      "pkg:npm/[email protected]",
      "pkg:pypi/[email protected]"
    ]
  }'

### 통계 응답 (HTTP 엔드포인트)```json
{
  "cached_artifacts": 142,
  "total_size_bytes": 523456789,
  "total_size": "499.2 MB",
  "storage_url": "file:///path/to/cache/artifacts",
  "database_path": "./cache/proxy.db"
}

## 웹 인터페이스

프록시는 `/ui` 아래에 웹 UI를 제공합니다. 별도의 프런트엔드 빌드는 필요하지 않습니다 -- 템플릿과 에셋은 바이너리에 내장되어 있습니다. `GET /`는 `/ui/`로 리다이렉트됩니다. UI는 자체 접두사 아래에 마운트되므로, 리버스 프록시가 패키지 엔드포인트와는 다른 접근 규칙을 UI에 적용할 수 있습니다 (예를 들어 `PathPrefix(/ui)`에는 인증을 요구하면서 `/npm`, `/pypi` 등은 빌드 머신에 열어 두는 것).

- **대시보드** (`/ui/`) -- 캐시 통계, 인기 패키지, 최근 캐시된 아티팩트, 취약점 개요.
- **설치 가이드** (`/ui/install`) -- 에코시스템별 구성 지침으로, 여기서 찾아볼 필요가 없습니다.
- **패키지 브라우저** (`/ui/packages`) -- 에코시스템별 필터링과 히트, 크기, 이름, 취약점 수 기준 정렬로 모든 캐시된 패키지를 탐색합니다.
- **검색** (`/ui/search?q=...`) -- 이름으로 캐시된 패키지를 검색합니다.
- **패키지 상세** (`/ui/package/{ecosystem}/{name}`) -- 패키지의 메타데이터, 라이선스, 취약점, 버전 목록. 두 버전을 선택해 비교할 수 있습니다.
- **버전 상세** (`/ui/package/{ecosystem}/{name}/{version}`) -- 버전별 메타데이터, 무결성 해시, 아티팩트 캐시 상태, 히트 수.
- **소스 브라우저** (`/ui/package/{ecosystem}/{name}/{version}/browse`) -- 캐시된 아카이브 내부의 파일을 탐색하며, 텍스트 파일에는 구문 강조를, 이미지에는 미리보기를 제공합니다.
- **버전 비교** (`/ui/package/{ecosystem}/{name}/compare/{v1}...{v2}`) -- 캐시된 두 버전의 나란히 비교로, 추가, 제거, 변경된 파일을 보여줍니다.

## 모니터링

프록시는 `GET /metrics`에서 Prometheus 메트릭을 노출합니다. 모든 메트릭 이름은 `proxy_` 접두사로 시작합니다.

| 메트릭 | 유형 | 레이블 | 설명 |
|--------|------|--------|-------------|
| `proxy_requests_total` | counter | `ecosystem`, `status` | 패키지 에코시스템 및 HTTP 상태별 프록시 응답 |
| `proxy_request_duration_seconds` | histogram | `ecosystem`, `status` | 프록시 요청 지속 시간 |
| `proxy_cache_hits_total` | counter | `ecosystem` | 캐시 히트 |
| `proxy_cache_misses_total` | counter | `ecosystem` | 캐시 미스 |
| `proxy_cache_size_bytes` | gauge | | 캐시된 아티팩트의 총 크기 |
| `proxy_cached_artifacts_total` | gauge | | 캐시된 아티팩트 수 |
| `proxy_upstream_fetch_duration_seconds` | histogram | `ecosystem` | 업스트림에서 가져오는 데 소요된 시간 |
| `proxy_upstream_errors_total` | counter | `ecosystem`, `error_type` | 업스트림 가져오기 실패 |
| `proxy_storage_operation_duration_seconds` | histogram | `operation` | 스토리지 읽기/쓰기 지연 시간 |
| `proxy_storage_errors_total` | counter | `operation` | 스토리지 읽기/쓰기 실패 |
| `proxy_active_requests` | gauge | | 처리 중인 요청 |
| `proxy_health_probe_failures_total` | counter | `step` | 실패한 단계(`write`, `size`, `read`, `verify`, `delete`)별 스토리지 상태 프로브 실패. |
| `proxy_circuit_breaker_state` | gauge | `registry` | 업스트림 레지스트리별 아티팩트 가져오기 회로 차단기 상태 (0 closed, 2 open). 해당 레지스트리의 차단기가 트립된 후 게시됩니다. |
| `proxy_circuit_breaker_trips_total` | counter | `registry` | 업스트림 레지스트리별 회로 차단기 트립. |

캐시 크기와 아티팩트 수는 60초마다 갱신됩니다. 회로 차단기 상태는 `/metrics`의 각 스크레이프와 각 `/health` 요청 시 페처에서 읽히므로, `proxy_circuit_breaker_trips_total`은 해당 읽기 사이에 보이는 트립을 계산합니다 — 두 스크레이프 사이에 완전히 열렸다가 복구된 차단기는 계산되지 않습니다. 나머지 메트릭은 각 요청 시 갱신됩니다.

차단기 메트릭은 업스트림 호스트당 하나의 시리즈를 가지지만, 시작 이후 최소 한 번 트립된 적이 있는 호스트에 대해서만 그렇습니다. 차단기는 프록시가 아티팩트를 가져오는 호스트별로 생성되며, 일부 에코시스템의 경우 그 호스트는 구성이 아니라 업스트림 메타데이터에서 나옵니다 (composer는 패키지의 `dist.url`에서, helm은 `index.yaml`의 차트 URL에서 가져옵니다). 따라서 모든 호스트를 게시하면 업스트림 콘텐츠가 프로세스 수명 동안 시리즈 수를 늘릴 수 있습니다. 호스트가 한 번 트립되면 계속 보고하므로, 복구는 시리즈가 사라지는 것이 아니라 0으로의 전환으로 나타납니다. `/health`는 영구 시계열이 아니며 트립 여부와 관계없이 모든 차단기를 나열합니다.

`registry` 레이블은 아티팩트를 가져온 URL의 호스트입니다. 그 URL은 업스트림 메타데이터에서 올 수 있으므로, 항상 호스트를 읽어낼 수 있는 것은 아닙니다 — 예를 들어 파싱에 실패한 서명된 `dist.url` 같은 경우입니다 — 그리고 그러한 차단기는 대신 `hostless-url-<digest>`로 레이블이 지정되며, 여기서 digest는 시작 시 새로 도출된 값을 키로 합니다. `/metrics`와 `/health` 모두 인증이 필요하지 않으므로, 가져오기 URL은 레이블이나 키로 게시되지 않습니다. digest는 프로세스가 실행되는 동안 차단기를 식별하되 그 뒤의 URL을 드러내지 않으며, 선택된 URL이 그것과 매칭되도록 허용하지도 않습니다.

`proxy_circuit_breaker_state == 2`가 몇 분 이상 지속될 때 알림을 설정하세요: 차단기가 열려 있는 동안 해당 업스트림의 아티팩트 다운로드는 모든 캐시 미스에서 HTTP 502로 실패하며, 백오프 간격당 단 하나의 프로브 요청만 업스트림에 도달합니다. 캐시된 아티팩트는 계속 제공되며, 같은 에코시스템의 메타데이터도 마찬가지입니다 (메타데이터는 회로 차단기를 거치지 않습니다). 따라서 설치는 부분적인 업스트림 장애처럼 보이는 방식으로 실패합니다.

### 상태 확인

`/health`는 하위 시스템 상태의 구조화된 JSON 보고서를 반환합니다. 모든 검사가 통과하면 HTTP 200, 하나라도 실패하면 503입니다.```json
{
  "status": "ok",
  "checks": {
    "database": {"status": "ok"},
    "storage":  {"status": "ok"}
  },
  "circuit_breakers": {
    "registry.npmjs.org": "closed",
    "static.crates.io":   "open"
  }
}

## 프로덕션 배포

### Systemd 서비스

`/etc/systemd/system/proxy.service` 파일을 생성하세요:```ini
[Unit]
Description=git-pkgs proxy
After=network.target

[Service]
Type=simple
User=proxy
ExecStart=/usr/local/bin/proxy -config /etc/proxy/config.yaml
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

### Docker

저장소에 Dockerfile이 포함되어 있습니다. 빌드 및 실행:```bash
docker build -t proxy .
docker run -p 8080:8080 -v proxy-data:/data proxy

### 리버스 프록시 뒤에서

nginx, Apache 또는 다른 리버스 프록시 뒤에서 실행할 때는 `base_url`을 공개 URL로 설정하세요:```yaml
base_url: "https://proxy.example.com"

`ui_base_url`이 설정되지 않은 경우 `base_url`로 기본 설정됩니다.

> **경고:** 프록시는 UI와 패키지 엔드포인트를 동일한 리스너에서 제공합니다. `ui_base_url`을 설정하면 UI가 사람에게 광고하는 URL만 변경될 뿐, 동일한 호스트 이름과 포트에서 패키지 엔드포인트에 접근하는 것을 막지는 않습니다. 공용 리버스 프록시로 프록시를 앞에 둘 때는 공용 경로를 `PathPrefix(/ui)`(또는 사용하는 프록시의 동등한 설정)로 제한하십시오. 그렇지 않으면 `/npm`, `/pypi` 및 기타 패키지 엔드포인트가 UI와 함께 노출된 상태로 유지됩니다.

nginx 예시로, 공용 호스트를 UI로 제한하면서 패키지 엔드포인트는 내부 리스너에서만 접근 가능하게 유지합니다:```nginx
server {
    listen 443 ssl;
    server_name proxy.example.com;

    location /ui/ {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_buffering off;
    }

    location / {
        return 404;
    }
}

## 캐시 관리

프록시는 구성된 스토리지 디렉터리에 다음과 같은 구조로 아티팩트를 저장합니다:```
cache/artifacts/
├── npm/
│   └── lodash/
│       └── 4.17.21/
│           └── lodash-4.17.21.tgz
├── cargo/
│   └── serde/
│       └── 1.0.193/
│           └── serde-1.0.193.crate
├── oci/
│   └── library/nginx/
│       └── sha256:abc123.../
│           └── sha256:abc123...
├── deb/
│   └── nginx/
│       └── 1.18.0-6/
│           └── nginx_1.18.0-6_amd64.deb
└── rpm/
    └── nginx/
        └── 1.24.0-1.fc39/
            └── nginx-1.24.0-1.fc39.x86_64.rpm

프록시는 다음 시작 시 데이터베이스를 다시 생성합니다.

## 소스에서 빌드

요구 사항:

- Go (프로젝트 버전은 `go.mod`에 선언되어 있음)```bash
git clone https://github.com/git-pkgs/proxy.git
cd proxy
go build -o proxy ./cmd/proxy

## 라이선스

GPL-3.0-or-later