3 天冷却期意味着当 `lodash` 发布 `4.18.0` 版本时，你的构建会继续使用 `4.17.21`，直到 3 天过去。如果新版本被证明遭到入侵，你从未暴露于风险之中。

解析顺序：包覆盖，然后是生态系统覆盖，最后是全局默认值。这让你可以设置一个保守的默认值，并为需要更快更新的包划定例外。完整配置参考请见 [docs/configuration.md](https://github.com/git-pkgs/proxy/blob/main/docs/configuration.md)。

## 制品扫描

冷却期只查看版本的发布时间戳——它从不检查实际的字节内容。制品扫描填补了这一空白：启用后，每个制品都会被暂存到存储中，并由一个或多个外部服务（trivy、ClamAV、Wiz，或任何遵循小型 HTTP/JSON 契约的服务）扫描，然后才会提交到缓存并提供给客户端。```yaml
scanning:
  enabled: true
  signing_key: ${PROXY_SCANNING_SIGNING_KEY}
  scanners:
    - name: clamav
      url: http://clamav-adapter:8080/scan
      mode: block             # a block verdict deletes the artifact and returns 403
    - name: trivy
      url: http://trivy-adapter:8081/scan
      mode: monitor            # findings are logged, never gate caching
      ecosystems: [npm, pypi]

或者从[发布页面](https://github.com/git-pkgs/proxy/releases)下载二进制文件。

### Helm

从 GHCR 安装 chart，并设置包管理器客户端用于访问代理的公共 URL：```bash
helm install proxy oci://ghcr.io/git-pkgs/charts/proxy \
  --set config.data.base_url=https://proxy.example.com

代理现已运行。配置你的包管理器以使用它。

## OpenAPI (Swagger)

本仓库使用 swaggo 从带注释的处理器生成 OpenAPI 规范。

生成规范：```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

或在你的 shell 配置文件中设置以实现持久化。

### 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 作为主要上游，当主要上游返回未找到时，回退到 Gradle Plugin Portal 以获取 Gradle 插件标记元数据及相关构件。

通过同一代理端点进行 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 chart 仓库配置一个名称，然后将匹配的代理 URL 添加到 Helm：```yaml
upstream:
  helm:
    bitnami: "https://charts.bitnami.com/bitnami"

python3 exploit.py -t http://target.com -u admin -p password

代理使用常规的元数据缓存设置缓存 `index.yaml`，并在根据索引验证 chart 归档的 SHA-256 摘要后对其进行缓存。

对于存储在 OCI registry 中的 chart，请配置一个命名的 OCI 上游，并将保留的 `upstream/{name}` 前缀添加到 chart 引用中：```yaml
upstream:
  oci:
    ghcr: "https://ghcr.io"

### Debian / APT

在 `/etc/apt/sources.list.d/proxy.list` 中配置 APT 以使用代理：```
deb http://localhost:8080/debian stable main contrib

上游默认使用 `http://deb.debian.org/debian`。要代理其他 APT 仓库（例如 Ubuntu），请在配置文件中设置 `upstream.debian`，或在环境变量中设置 `PROXY_UPSTREAM_DEBIAN`：```yaml
upstream:
  debian: "http://archive.ubuntu.com/ubuntu"

然后：```bash
sudo dnf clean all
sudo dnf update

然后：```bash
apk update

## 使用示例

### 基本用法

```bash
# 扫描单个目标
python3 cve_2025_55182.py -t https://target.example.com

# 扫描多个目标
python3 cve_2025_55182.py -f targets.txt

# 使用自定义超时时间扫描
python3 cve_2025_55182.py -t https://target.example.com --timeout 15

# 使用代理扫描
python3 cve_2025_55182.py -t https://target.example.com --proxy http://127.0.0.1:8080

# 使用自定义线程数扫描
python3 cve_2025_55182.py -f targets.txt --threads 20

# 详细输出
python3 cve_2025_55182.py -t https://target.example.com -v

# 将结果保存到文件
python3 cve_2025_55182.py -f targets.txt -o results.txt

# 使用自定义载荷扫描
python3 cve_2025_55182.py -t https://target.example.com --payload "custom_payload"

# 使用自定义 User-Agent 扫描
python3 cve_2025_55182.py -t https://target.example.com --user-agent "Mozilla/5.0"

# 使用自定义请求头扫描
python3 cve_2025_55182.py -t https://target.example.com --headers "X-Custom: value"

# 使用自定义 Cookie 扫描
python3 cve_2025_55182.py -t https://target.example.com --cookie "session=abc123"

# 使用自定义方法扫描
python3 cve_2025_55182.py -t https://target.example.com --method POST

# 使用自定义数据扫描
python3 cve_2025_55182.py -t https://target.example.com --data "param=value"

# 使用自定义路径扫描
python3 cve_2025_55182.py -t https://target.example.com --path "/custom/path"

# 使用自定义端口扫描
python3 cve_2025_55182.py -t https://target.example.com --port 8443

# 使用自定义协议扫描
python3 cve_2025_55182.py -t https://target.example.com --scheme https

# 使用自定义 SSL 验证扫描
python3 cve_2025_55182.py -t https://target.example.com --no-verify-ssl

# 使用自定义重定向扫描
python3 cve_2025_55182.py -t https://target.example.com --no-redirect

# 使用自定义重试次数扫描
python3 cve_2025_55182.py -t https://target.example.com --retries 3

# 使用自定义延迟扫描
python3 cve_2025_55182.py -t https://target.example.com --delay 1

# 使用自定义随机延迟扫描
python3 cve_2025_55182.py -t https://target.example.com --random-delay

# 使用自定义随机 User-Agent 扫描
python3 cve_2025_55182.py -t https://target.example.com --random-user-agent

# 使用自定义随机请求头扫描
python3 cve_2025_55182.py -t https://target.example.com --random-headers

# 使用自定义随机 Cookie 扫描
python3 cve_2025_55182.py -t https://target.example.com --random-cookie

# 使用自定义随机方法扫描
python3 cve_2025_55182.py -t https://target.example.com --random-method

# 使用自定义随机数据扫描
python3 cve_2025_55182.py -t https://target.example.com --random-data

# 使用自定义随机路径扫描
python3 cve_2025_55182.py -t https://target.example.com --random-path

# 使用自定义随机端口扫描
python3 cve_2025_55182.py -t https://target.example.com --random-port

# 使用自定义随机协议扫描
python3 cve_2025_55182.py -t https://target.example.com --random-scheme

# 使用自定义随机 SSL 验证扫描
python3 cve_2025_55182.py -t https://target.example.com --random-no-verify-ssl

# 使用自定义随机重定向扫描
python3 cve_2025_55182.py -t https://target.example.com --random-no-redirect

# 使用自定义随机重试次数扫描
python3 cve_2025_55182.py -t https://target.example.com --random-retries

# 使用自定义随机延迟扫描
python3 cve_2025_55182.py -t https://target.example.com --random-delay

# 使用自定义随机随机延迟扫描
python3 cve_2025_55182.py -t https://target.example.com --random-random-delay

# 使用自定义随机随机 User-Agent 扫描
python3 cve_2025_55182.py -t https://target.example.com --random-random-user-agent

# 使用自定义随机随机请求头扫描
python3 cve_2025_55182.py -t https://target.example.com --random-random-headers

# 使用自定义随机随机 Cookie 扫描
python3 cve_2025_55182.py -t https://target.example.com --random-random-cookie

# 使用自定义随机随机方法扫描
python3 cve_2025_55182.py -t https://target.example.com --random-random-method

# 使用自定义随机随机数据扫描
python3 cve_2025_55182.py -t https://target.example.com --random-random-data

# 使用自定义随机随机路径扫描
python3 cve_2025_55182.py -t https://target.example.com --random-random-path

# 使用自定义随机随机端口扫描
python3 cve_2025_55182.py -t https://target.example.com --random-random-port

# 使用自定义随机随机协议扫描
python3 cve_2025_55182.py -t https://target.example.com --random-random-scheme

# 使用自定义随机随机 SSL 验证扫描
python3 cve_2025_55182.py -t https://target.example.com --random-random-no-verify-ssl

# 使用自定义随机随机重定向扫描
python3 cve_2025_55182.py -t https://target.example.com --random-random-no-redirect

# 使用自定义随机随机重试次数扫描
python3 cve_2025_55182.py -t https://target.example.com --random-random-retries

# 使用自定义随机随机延迟扫描
python3 cve_2025_55182.py -t https://target.example.com --random-random-delay```
http://localhost:8080/apk/private

然后重写 mise 设置中的 GitHub URL（`~/.config/mise/config.toml`，mise ≥ 2025.9.3）：```toml
[settings.url_replacements]
"regex:^https://github\\.com/([^/]+)/([^/]+)/releases/download/(.+)" = "http://localhost:8080/generic/github/$1/$2/releases/download/$3"
"regex:^https://api\\.github\\.com/(.*)" = "http://localhost:8080/generic/github-api/$1"

### 环境变量```bash
PROXY_LISTEN=:8080
PROXY_BASE_URL=http://localhost:8080
PROXY_UI_URL=http://localhost:8080  # Optional; defaults to PROXY_BASE_URL
PROXY_STORAGE_URL=file:///var/cache/proxy/artifacts
PROXY_DATABASE_DRIVER=sqlite
PROXY_DATABASE_PATH=./cache/proxy.db
PROXY_DATABASE_URL=postgres://user:pass@localhost/proxy?sslmode=disable
PROXY_LOG_LEVEL=info
PROXY_LOG_FORMAT=text
PROXY_ACCESS_LOG_PATH=/var/log/proxy/access.jsonl
PROXY_UPSTREAM_SWIFT=https://tuist.dev/api/registry/swift

请参阅[配置参考](https://github.com/git-pkgs/proxy/blob/main/docs/configuration.md#upstream-registries)，了解每个上游键、环境变量和默认 URL。

使用配置文件运行：```bash
./proxy -config /etc/proxy/config.yaml

或通过环境变量：```bash
PROXY_DATABASE_DRIVER=postgres
PROXY_DATABASE_URL=postgres://user:password@localhost:5432/proxy?sslmode=disable

对于像 MinIO 这样的 S3 兼容服务：```yaml
storage:
  url: "s3://my-bucket?endpoint=http://localhost:9000&disableSSL=true&s3ForcePathStyle=true"

身份验证使用 [Application Default Credentials](https://docs.cloud.google.com/docs/authentication/application-default-credentials)，这意味着无需在配置或环境中嵌入任何凭据。支持的来源按顺序如下：

- **GKE Workload Identity** — 将运行代理的 Kubernetes 服务账号绑定到在存储桶上具有 `roles/storage.objectAdmin` 权限的 Google 服务账号。代理将自动使用工作负载的令牌。
- GCE、Cloud Run、Cloud Functions 等上的**附加服务账号**。
- 指向服务账号 JSON 密钥文件的 **`GOOGLE_APPLICATION_CREDENTIALS`** 环境变量。
- 用于本地开发的 **`gcloud auth application-default login`**。

#### GKE Workload Identity 设置```bash
# 1. Create a Google service account
gcloud iam service-accounts create git-pkgs-proxy \
  --project=PROJECT_ID

# 2. Grant it access to the bucket
gsutil iam ch \
  serviceAccount:git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com:objectAdmin \
  gs://my-bucket-name

# 3. Bind the Kubernetes service account to it
gcloud iam service-accounts add-iam-policy-binding \
  git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.workloadIdentityUser \
  --member="serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"

# 4. Annotate the Kubernetes service account
kubectl annotate serviceaccount KSA_NAME \
  --namespace=NAMESPACE \
  iam.gke.io/gcp-service-account=git-pkgs-proxy@PROJECT_ID.iam.gserviceaccount.com

## CLI 命令

### serve（默认）

启动代理服务器。如果未指定命令，这是默认命令。```bash
proxy serve [flags]
proxy [flags]  # same as 'proxy serve'

镜像命令接受与 `serve` 相同的存储和数据库标志。已缓存的构件会被跳过。

服务器运行时，还可以使用镜像 API：```bash
# Start a mirror job
curl -X POST http://localhost:8080/api/mirror \
  -H "Content-Type: application/json" \
  -d '{"purls": ["pkg:npm/[email protected]"]}'

# Start a mirror job from an inline CycloneDX or SPDX JSON SBOM
curl -X POST http://localhost:8080/api/mirror \
  -H "Content-Type: application/json" \
  -d '{"sbom":{"bomFormat":"CycloneDX","components":[{"purl":"pkg:npm/[email protected]"}]}}'

# Check job status
curl http://localhost:8080/api/mirror/mirror-1

# Cancel a running job
curl -X DELETE http://localhost:8080/api/mirror/mirror-1

示例输出：```
Cache Statistics
================

Packages:   45
Versions:   128
Artifacts:  128
Total size: 892.4 MB
Total hits: 1547

Packages by ecosystem:
  npm        32
  cargo      13

Most popular packages:
   1. npm/lodash (342 hits, 24.7 KB)
   2. npm/react (198 hits, 89.3 KB)
   3. cargo/serde (156 hits, 234.1 KB)

Recently cached:
  npm/[email protected] (2024-01-15 14:32, 54.2 KB)
  cargo/[email protected] (2024-01-15 14:28, 412.8 KB)

Response:```json
{
  "ecosystem": "npm",
  "name": "lodash",
  "latest_version": "4.17.21",
  "license": "MIT",
  "license_category": "permissive",
  "description": "Lodash modular utilities",
  "homepage": "https://lodash.com/",
  "repository": "https://github.com/lodash/lodash",
  "registry_url": "https://registry.npmjs.org"
}

(no input provided)```json
{
  "package": {
    "ecosystem": "npm",
    "name": "lodash",
    "latest_version": "4.17.21",
    "license": "MIT",
    "license_category": "permissive"
  },
  "version": {
    "ecosystem": "npm",
    "name": "lodash",
    "version": "4.17.0",
    "license": "MIT",
    "published_at": "2016-06-17T03:59:56Z",
    "yanked": false,
    "is_outdated": true
  },
  "vulnerabilities": [
    {
      "id": "GHSA-p6mc-m468-83gw",
      "summary": "Prototype Pollution in lodash",
      "severity": "HIGH",
      "cvss_score": 7.4,
      "fixed_version": "4.17.12"
    }
  ],
  "is_outdated": true,
  "license_category": "permissive"
}

Response:```json
{
  "results": [
    {
      "ecosystem": "npm",
      "name": "lodash",
      "version": "4.17.0",
      "latest_version": "4.17.21",
      "is_outdated": true
    },
    {
      "ecosystem": "pypi",
      "name": "requests",
      "version": "2.25.0",
      "latest_version": "2.31.0",
      "is_outdated": true
    }
  ]
}

Response:```json
{
  "packages": {
    "pkg:npm/lodash": {
      "ecosystem": "npm",
      "name": "lodash",
      "latest_version": "4.17.21",
      "license": "MIT",
      "license_category": "permissive"
    },
    "pkg:pypi/requests": {
      "ecosystem": "pypi",
      "name": "requests",
      "latest_version": "2.31.0",
      "license": "Apache-2.0",
      "license_category": "permissive"
    }
  }
}

## 工作原理

1. 包管理器向代理请求包元数据
2. 代理从上游获取元数据，将制品 URL 重写为指向代理
3. 包管理器请求制品（tarball、crate 等）
4. 代理检查本地缓存：
   - **缓存命中**：从本地存储提供
   - **缓存未命中**：从上游获取，存储到本地，再提供给客户端
5. 对同一制品的后续请求将从缓存中提供```
┌─────────────┐     ┌─────────┐     ┌──────────┐
│   npm/cargo │────▶│  proxy  │────▶│ upstream │
│   client    │◀────│         │◀────│ registry │
└─────────────┘     └─────────┘     └──────────┘
                         │
                         ▼
                    ┌─────────┐
                    │  cache  │
                    │ storage │
                    └─────────┘

失败的检查会包含一个 `"error"` 字段。存储失败还会包含一个 `"step"` 字段，用于标识哪个探测步骤失败（`write`、`size`、`read`、`verify`、`delete`）。当数据库检查失败时，存储条目会报告 `{"status": "skipped"}`，因此响应始终携带相同的键集合。

`circuit_breakers` 报告每个上游的 artifact 获取熔断器的状态（`"open"` 或 `"closed"`），以上游主机为键——或者在获取 URL 没有可读取的主机时，使用 [Monitoring](#monitoring) 中描述的 `hostless-url-<digest>` 占位符作为键。在代理从至少一个上游获取过 artifact 之前，该键会被省略；并且只有当某个主机创建了熔断器后，该主机才会出现。熔断器在上游反复失败后跳闸，并在指数退避后重试上游。当某个熔断器处于打开状态时，该主机的 artifact 下载在缓存未命中时会返回 HTTP 502，且不会联系上游；已缓存的 artifact 仍会从存储中提供，因为缓存会在获取器之前被检查。熔断器在其整个退避期间都报告为 `"open"`，包括半开窗口——在该窗口中它允许一个探测请求以测试恢复情况。熔断器状态是按进程且保存在内存中的，因此重启会清除它，但恢复并不需要重启：只要熔断器处于打开状态，退避就会持续重试，因此一旦上游再次正常提供服务，它就会自行关闭。

打开的熔断器**不会**将 `status` 设置为 `"error"`，也不会更改 HTTP 状态码：它报告的是某个特定上游拒绝提供服务，而不是此代理不适合接收流量；并且因为一个不健康的上游而使就绪探测失败，会导致该 pod 对所有其他生态系统也被移出轮换。请使用 `proxy_circuit_breaker_state` 对其进行告警。

存储探测结果会缓存 `health.storage_probe_interval`（默认 30 秒），以限制探测远程后端的成本。一次探测最多持有内部互斥锁 10 秒（硬编码的每次探测超时），因此 `/health` 旨在作为 Kubernetes 的**就绪**探测，而不是存活探测——缓慢的 S3 往返应该将 pod 移出轮换，而不是重启它。

Prometheus 的抓取配置：```yaml
scrape_configs:
  - job_name: git-pkgs-proxy
    static_configs:
      - targets: ["localhost:8080"]

启用并启动：```bash
sudo systemctl enable proxy
sudo systemctl start proxy

使用 Postgres 和 S3：```bash
docker run -p 8080:8080 \
  -e PROXY_DATABASE_DRIVER=postgres \
  -e PROXY_DATABASE_URL=postgres://user:pass@db:5432/proxy \
  -e PROXY_STORAGE_URL=s3://my-bucket?region=us-east-1 \
  -e AWS_ACCESS_KEY_ID=... \
  -e AWS_SECRET_ACCESS_KEY=... \
  proxy

如果通过不同于软件包端点的主机名访问 UI——例如，UI 公开暴露在某个域名上，而构建机器访问的是 Docker 网络别名——则需单独设置 `ui_base_url`。`base_url` 是包管理器和元数据重写所使用的 URL；`ui_base_url` 是向访问 Web UI 的用户公布的 URL（canonical/`og:url` 标签以及安装指南横幅）：```yaml
base_url: "http://pkg-proxy:8080"        # internal alias for build machines
ui_base_url: "https://proxy.example.com/ui"  # public UI URL

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;
}

使用 `PathPrefix(/ui)` 的 Traefik 示例，使公共路由器仅匹配 UI 流量：```yaml
labels:
  traefik.enable: "true"
  traefik.http.services.pkg-proxy.loadbalancer.server.port: "8080"
  traefik.http.routers.pkg-proxy.rule: "Host(`proxy.example.com`) && PathPrefix(`/ui`)"
  traefik.http.routers.pkg-proxy.entrypoints: "websecure"

缓存元数据存储在 SQLite（默认）或 PostgreSQL 中。要清除本地缓存：```bash
rm -rf ./cache/artifacts/*
rm ./cache/proxy.db

运行测试：```bash
go test ./...