npm 仓库 — 概览

一句话总结

Pier 内置了一个完整的 npm 兼容仓库，它就运行在驱动你容器的同一个 Rust 二进制文件里。不需要 Verdaccio 容器，也不需要额外的数据库 —— 打开 https://your-pier-host/registry/npm/，在面板中签发一个令牌，把三行内容写入 .npmrc，你就拥有了一个供整个团队使用的私有 + 代理仓库。

它端到端地实现了 npm 仓库 HTTP 协议，因此 npm、yarn（1 以及 2/3/4）、pnpm 和 bun 无需任何定制客户端代码即可直接使用它。

它能做什么

私有发布。 npm publish（带 scope 和不带 scope）、npm dist-tag、npm deprecate、npm unpublish。涵盖全套标准变更操作。
上游代理模式。 镜像 registry.npmjs.org（或任意兼容的上游）—— packument 永久缓存，tarball 在首次安装时惰性拉取，LRU GC 将磁盘缓存控制在可配置的上限以内。
Web 登录流程。 npm login --auth-type=web 会打开浏览器，针对 Pier 面板进行认证（含 2FA），并把一个长期有效的 pier_npm_… 令牌写入 .npmrc —— 无需手动复制粘贴。
流式下载。 tarball 通过 axum::Body::from_stream 提供 —— Pier 不会把一个 200 MiB 的 tarball 整个缓冲在内存里。
按路由限流。 公共读取、管理变更和 npm publish 各自拥有独立的按 IP 配额。

它适合谁

如果你属于以下情况，Pier 的仓库就很适合你：

想要一个 Verdaccio 的自托管替代方案，又不想多维护一个容器和一个数据库。
团队规模较小，希望私有包和公共依赖都用同一个 .npmrc URL。
需要在 npmjs.org 宕机时安装仍然可用。
想要审计可见性 —— 了解团队实际使用了哪些公共包。
已经在用 Pier 跑容器，不想再额外运维第二个守护进程。

v1 中尚未包含的内容

npm search —— 暂无 /-/v1/search 端点。发现包请通过 Pier UI 进行。
npm owner / RBAC —— 目前采用单一所有者模型：某个版本的发布者控制该版本的 deprecate / unpublish，管理员可覆盖。多维护者所有权将在后续推出。
npm audit —— 合理的实现方式是在上游代理工作完成之后再推出，这样 audit 载荷就能透传给 npmjs.org。两者都在路线图上跟踪。
npm star/unstar —— 明确不计划支持。UI 在 Mirror 标签页提供了”置顶”开关，能更好地解决同样的问题。

标准 npm CLI 的其余所有功能在今天都已能对 Pier 正常工作。

架构一览

npm install left-pad ─┬─► GET /registry/npm/left-pad
                       │      (packument, ETag-cached)
                       │
                       └─► GET /registry/npm/left-pad/-/left-pad-1.3.0.tgz
                              ↓ first time: upstream fetch + cache
                              ↓ next time: stream from local FS

packument 元数据存储在 SQLite 中（npm_packages 存放原始 JSON blob，npm_versions 存放已下载的版本）。
tarball 存储在本地文件系统的 data/registry/{package}/{file}.tgz。可选地镜像到任意 S3 兼容的冷存储层（Packages → S3 configure）。
通过 If-None-Match 进行 ETag 重新校验 → 命中即 304 短路返回。基于 TTL 的刷新会自动唤醒过期的条目。

后续步骤

启用仓库并配置你的第一个客户端 —— 5 分钟。
开启上游代理模式，让团队镜像 npmjs.org。
选择你的客户端指南：npm · yarn 1.x · yarn 2/3/4 · pnpm · bun。