上游代理模式

上游代理模式把 Pier 变成 registry.npmjs.org（或任意 npm 兼容上游）的透明镜像。整个团队使用一个 .npmrc URL，其余的交给 Pier 处理 —— packument 被缓存并重新校验，tarball 在首次安装时惰性拉取，GC 把磁盘占用控制在上限以内。

为什么要用它

一个 URL，无需按 scope 路由。 私有包和公共包都在同一个 https://your-pier-host/registry/npm/ 后面。不再需要 @org:registry=… 加上一个默认仓库 —— 一行搞定。
npmjs.org 宕机时安装仍可进行。 你之前安装过的内容都在缓存里。只有新的间接依赖在首次未命中时才会失败。
审计可见性。 Mirror 标签页列出团队通过 Pier 安装过的每一个公共包，并显示磁盘占用大小和最后拉取时间。
合规。 如果你需要审查哪些版本进入你的代码库，代理就是那个把关口。

它的工作原理

Client                Pier                       Upstream
  │                    │                            │
  │  GET /react        │                            │
  ├───────────────────►│  cache miss / TTL expired  │
  │                    ├───────────────────────────►│
  │                    │   200 packument            │
  │                    │◄───────────────────────────┤
  │   packument        │  cache + URL-rewrite       │
  │◄───────────────────┤  dist.tarball → /registry/ │
  │                    │                            │
  │  GET /react/-/.tgz │                            │
  ├───────────────────►│  cache miss                │
  │                    ├───────────────────────────►│
  │                    │   tarball bytes            │
  │                    │◄───────────────────────────┤
  │   tarball          │  write FS + DB row         │
  │◄───────────────────┤                            │

packument 缓存以每个包一个 JSON blob 的形式存储在 SQLite 中（npm_packages.upstream_packument_json）。每个包一行 —— 即便是 next（3769 个版本）也仍然只是一行。
tarball 缓存存储在磁盘的 data/registry/{package}/{file}.tgz。只有客户端实际安装过的版本才会落到这里。
TTL 重新校验 —— 当某个缓存的 packument 超过配置的 TTL 时，Pier 会向上游发送 If-None-Match: <stored-etag>。304 会在没有载荷的情况下短路返回；200 则替换该 blob。

配置

Packages → Upstream proxy 有四个设置项：

设置项	作用	合理取值
Enable upstream proxy	总开关	默认关闭；打开它
Upstream URL	从哪里拉取	`https://registry.npmjs.org`（默认）
Packument TTL (seconds)	多久重新校验一次元数据	默认 600（10 分钟）；想减少通信可设 3600
Max cache size (MiB)	tarball 存储的硬上限。`0` = 无限制	见下方容量规划

缓存容量规划

packument 缓存很小（每个包约 1–50 KB，全部在 SQLite 中 —— 计入 DB 文件，不计入磁盘上限）。占主导地位的是 tarball。

场景	推荐上限
单台开发机	500–1000 MiB
小团队（3–5 名开发者）	2–5 GiB
共享 CI 镜像	20+ GiB
磁盘充裕的服务器	`0`（无限制）

当超过上限时，后台 LRU GC（每 10 分钟运行一次）会丢弃最旧的 tarball，直到总量符合上限。被淘汰的 tarball 会在下次安装时静默重新拉取 —— 用户看不到任何错误，只是多了一次网络往返。

查看缓存内容

Packages 中的 Mirror 标签页列出每一个已缓存的公共包：

Versions cached —— 来自上游 packument 的版本计数
Tarballs on disk —— 实际已下载版本的总和
Last fetched —— packument 上次刷新的时间
★ —— 给你关心的包置顶，然后用 Pinned only 筛选

点击某一行打开包详情。已缓存的版本会显示其大小、完整性哈希，以及 Deprecate / Unpublish 按钮（运维级操作）。

预拉取某个版本

当一个代理包有元数据但磁盘上没有 tarball 时（GC 之后，或冷缓存），详情页会显示一个 Download latest (X.Y.Z) 按钮。点击它即可通过 Pier 主动拉取该版本的 tarball，而无需在本地运行 npm install —— 这对于预热缓存或冒烟测试一个新镜像很有用。

临时禁用

关闭 Enable upstream proxy 并保存。已缓存的包会保留在 DB 和磁盘上；对未缓存包的新请求会返回 404。重新开启即可恢复。禁用时缓存绝不会被自动清除。

故障处理

如果在 TTL 重新校验时上游不可达，Pier 会提供缓存副本并记录一条警告。代理在读取时绝不会因上游可用性而阻塞。

如果上游在刷新一个先前已缓存的包时返回 404，Pier 会继续提供缓存副本 —— 从你的仓库中显式 unpublish 是一项独立且更需谨慎的操作。