存储后端（S3 / R2）

pnpr 保存两种数据：

🌐 pnpr keeps two kinds of data:

• Hosted — the source of truth: packages published to this server plus anything served in static mode. Lives under storage.

• Cache — the disposable mirror of upstream registries plus the resolver cache, lockfile-verdict cache, and S3 upload staging scratch. Lives under cache (defaults to <storage>/.pnpr-cache).

默认情况下，两者都是本地目录。添加一个 s3: 块会将托管的存储移入兼容 S3 的对象存储，因此持久数据由提供商进行复制，并且可以被多个无状态的 pnpr 副本共享。缓存始终保持在本地磁盘上 —— 只有托管的软件包存储是插件化的。

🌐 By default both are local directories. Adding an s3: block moves the hosted store into an S3-compatible object store, so the durable data is replicated by the provider and can be shared by several stateless pnpr replicas. The cache always stays on local disk — only the hosted package store is pluggable.

因为任何兼容 S3 的端点都可以使用，这也包括 Cloudflare R2、MinIO、Backblaze B2、Wasabi 等 — 将 endpoint 指向正确的主机。

🌐 Because any S3-compatible endpoint works, this also covers Cloudflare R2, MinIO, Backblaze B2, Wasabi, etc. — point endpoint at the right host.

storage: ./storage
# cache: ./cache     # local proxy cache + resolver cache + S3 upload staging

s3:
  bucket: my-pnpr-packages
  region: auto
  # Omit `endpoint` for AWS S3. For R2 use the account endpoint:
  endpoint: https://<account-id>.r2.cloudflarestorage.com
  # Optional key prefix, so one bucket can hold more than the hosted store:
  prefix: packages
  # Credentials. Omit these to fall back to the standard
  # AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY environment variables.
  accessKeyId: ${PNPR_S3_ACCESS_KEY_ID}
  secretAccessKey: ${PNPR_S3_SECRET_ACCESS_KEY}

选项

🌐 Options

键	必填	描述
bucket	是	存储托管软件包的桶。
region	否	AWS S3 需要一个真实的区域（例如 us-east-1）；Cloudflare R2 使用 auto。
endpoint	否	S3 兼容提供商的自定义端点。AWS S3 可省略；R2 为 https://<account-id>.r2.cloudflarestorage.com；MinIO 例如 http://127.0.0.1:9000。
prefix	否	每个对象存储的键前缀。
accessKeyId	否	访问密钥。未设置时回退到 AWS_ACCESS_KEY_ID。
secretAccessKey	否	私密密钥。未设置时回退到 AWS_SECRET_ACCESS_KEY。
forcePathStyle	否	使用路径式寻址（endpoint/bucket/key）而不是虚拟主机式（bucket.endpoint/key）。MinIO 通常需要 true；AWS 和 R2 使用默认值。
allowHttp	否	允许明文 HTTP 端点 — 需要用于本地 MinIO 通过 http://。默认为仅 HTTPS。

一个完整的 Cloudflare R2 示例

🌐 A complete Cloudflare R2 example

# pnpr.yaml
storage: ./storage

s3:
  bucket: my-pnpr-packages
  region: auto
  endpoint: https://abc123def456.r2.cloudflarestorage.com

registries:
  local:
    type: hosted
    packages:
      '@mycompany/*':
        publish: $authenticated

  npmjs:
    type: upstream
    url: https://registry.npmjs.org/
    public: true

  main:
    type: router
    sources: [local, npmjs]

defaultRegistry: main

export AWS_ACCESS_KEY_ID="<r2-access-key-id>"
export AWS_SECRET_ACCESS_KEY="<r2-secret-access-key>"
pnpr -c ./pnpr.yaml --listen 0.0.0.0:7677 --public-url https://registry.example.com

--public-url 会重写提供的包清单中的 dist.tarball URL，因此客户端通过该服务器而不是上游获取 tar 包。

一个通过普通 HTTP 的本地 MinIO

🌐 A local MinIO over plain HTTP

在 http:// 上的 MinIO 需要 forcePathStyle 和 allowHttp：

🌐 MinIO over http:// needs forcePathStyle and allowHttp:

s3:
  bucket: pnpr
  region: us-east-1
  endpoint: http://127.0.0.1:9000
  forcePathStyle: true
  allowHttp: true
  accessKeyId: minioadmin
  secretAccessKey: minioadmin