1 / 4概念
Private Registry
私有仓库是团队自己的包与制品的解析入口:它托管内部包,代理上游公共源,并用认证和分组规则决定一次构建能拿到什么。判断标准不是“能不能装包”,而是解析是否可复现、来源是否可审计。
1 概念
1.1 一句话定义
私有仓库是一个带存储与代理能力的包索引服务。客户端按 scope 或格式把请求发给它,它从 hosted 仓库返回内部包,或从 proxy 仓库回源上游并缓存,group 仓库把多个来源聚合成一个逻辑源。
1.2 它解决什么问题
- 内部包不能发到公共源:需要私有命名空间和访问控制。
- 上游公共源不稳定或延迟高:需要缓存与代理,减少外网依赖。
- 多个团队/环境需要不同可见性:需要 hosted、proxy、group 的组合。
没有私有仓库,内部包靠文件拷贝,上游依赖靠每个开发者直连,来源和权限都无法统一。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 包管理器、lockfile 与 workspace | JavaScript / TypeScript Toolchain |
| 流水线中的认证与发布阶段 | CI/CD |
| SBOM、签名与漏洞扫描 | Supply Chain Security |
| 容器镜像仓库与编排 | Containers & Cloud Native |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| hosted | 仓库自己存储包 | 不是代理缓存 |
| proxy | 回源上游并缓存 | 不是 hosted 的副本 |
| group | 把多个仓库聚合成一个逻辑源 | 不是复制数据 |
| scope | npm 包名前的 @team 命名空间 | 不是权限组 |
| upstream | 被代理的公共源 | 不是内部发布源 |
| dist-tag | 指向某个版本的标签,如 latest | 不是语义化版本 |
| tarball | 包的实际压缩内容 | 不是元数据 JSON |
2 机制
2.1 心智模型
把仓库想成一个带缓存的解析链:客户端问“这个包的这个版本在哪”,仓库按 group 顺序查 hosted 与 proxy;proxy 命中缓存就直接返回,未命中才回源。发布只写 hosted,读取可以经过 group。
2.2 机制拆解
- 认证:客户端带 token 或 basic auth 请求;仓库校验 scope 与读写权限。
- 解析:group 依次查询成员仓库;hosted 命中返回,proxy 命中缓存返回。
- 回源:proxy 未命中时请求上游,校验完整性后写入缓存并返回。
- 发布:客户端
publish写 hosted;仓库校验版本、tarball 和权限。 - 失效:TTL、手动清理或上游变更触发缓存更新;负缓存避免重复回源。
- 审计:记录谁在何时发布/下载了哪个版本,供追溯。
2.3 完整枚举
| 仓库类型 | 写入 | 读取 | 数据来源 | 典型用途 |
|---|---|---|---|---|
| hosted | 允许 | 允许 | 本仓库存储 | 内部包、快照、发布版 |
| proxy | 禁止 | 允许 | 上游公共源 | 缓存 npm/Maven/PyPI |
| group | 禁止 | 允许 | 多个成员仓库 | 统一解析入口 |
| virtual | 视实现 | 允许 | 多个格式/仓库 | 迁移期聚合 |
常见格式与工具:
| 格式 | 客户端 | 仓库产品 | 关键元数据 |
|---|---|---|---|
| npm | npm/pnpm/yarn | Verdaccio、Nexus | package.json、dist-tags |
| Maven | Maven/Gradle | Nexus、Artifactory | POM、GAV 坐标 |
| PyPI | pip/uv | Nexus、Devpi | wheel/sdist、requires |
| Docker | docker/containerd | Nexus、Harbor | manifest、digest |
| 通用文件 | curl/CI | Nexus、Artifactory | 路径、校验和 |
2.4 关键数字与量级
| 指标 | 常见取值 | 说明 |
|---|---|---|
| 缓存 TTL | 分钟到天 | 越短越新,回源越多 |
| 包大小上限 | 10–500 MB | 按产品和格式配置 |
| token 有效期 | 小时到月 | CI 用短期 token |
| 并发下载 | 数十到数千 | 受磁盘与上游限制 |
| 保留版本 | 全部 / 仅发布版 | 快照要设清理策略 |
| 负缓存 TTL | 分钟级 | 防止重复查不存在的包 |
3 实践
3.1 最小示例
# .npmrc:scope 走私有仓库,公共包仍可回源
@acme:registry=https://registry.acme.internal/repository/npm-group/
registry=https://registry.acme.internal/repository/npm-group/
//registry.acme.internal/repository/npm-group/:_authToken=${NPM_TOKEN}
always-auth=true
# Verdaccio 最小配置:本地发布 + 上游代理
storage: /var/lib/verdaccio/storage
uplinks: {npmjs: {url: 'https://registry.npmjs.org/'}}
packages:
'@acme/*': {access: $authenticated, publish: $authenticated}
'**': {access: $all, proxy: npmjs}
# 发布内部包:先确认 scope、版本和 dist-tag
npm publish --registry https://registry.acme.internal/repository/npm-hosted/ --tag next
npm view @acme/ui versions --registry https://registry.acme.internal/repository/npm-group/
3.2 常用操作与参数
| 操作 | 命令 / 配置 | 说明 |
|---|---|---|
| 登录 | npm login --registry <url> | token 写入用户配置 |
| 发布 | npm publish --tag next | 版本不可覆盖 |
| 弃用 | npm deprecate @acme/ui@1.0.0 "reason" | 不删除历史 |
| 查看来源 | npm view <pkg> dist.tarball | 确认实际下载地址 |
| 清理缓存 | 仓库管理 UI / API | 按包或按 TTL |
| 校验完整性 | npm pack + sha512 | 对比仓库记录 |
| 代理状态 | 仓库健康页 / 日志 | 看回源失败与命中率 |
3.3 标准流程
- 规划 scope:内部包统一
@org/*,公共包仍走 group。 - 建 hosted 存内部包,proxy 指向上游,group 作为唯一入口。
- CI 用只读 token 拉包,发布用最小写权限的独立 token。
- 发布前跑测试与打包,确认版本号、files 字段和 dist-tag。
- 发布后从 group 重新解析一次,验证 tarball 与校验和。
- 配 TTL、负缓存和磁盘告警;定期清理未使用的快照。
- 把仓库地址、证书和 token 注入方式写进团队文档。
3.4 与相邻技术的组合
- 工具链:
.npmrc的 registry/scope 决定 pnpm 的解析路径。 - 供应链安全:私有仓库是依赖入口,需配合签名、SBOM 和漏洞扫描。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 格式 | npm / Maven / 多格式 | 决定产品能力 |
| 规模 | 小团队 / 企业 | 决定高可用与权限模型 |
| 托管 | SaaS / 自建 | 维护成本与网络边界 |
| 代理需求 | 强 / 弱 | 决定缓存与回源策略 |
| 合规 | 需要审计 / 不需要 | 决定日志与留存 |
3.6 决策规则
- 只做 npm、团队小:Verdaccio,部署轻、配置少。
- 多格式、需要统一权限与高可用:Nexus 或 Artifactory。
- 代码已在 GitHub/GitLab:可先用平台自带的包 registry,减少运维。
- 外网不稳定:所有公共依赖走 proxy,CI 不直连公网。
- 内部包必须不可变:hosted 禁止覆盖版本,发布走新版本。
- 迁移期:用 group/virtual 聚合旧新仓库,避免一次性切换。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| Verdaccio | 轻量、npm 友好、易自建 | 多格式与高可用较弱 | 小团队、npm |
| Nexus | 多格式、权限与代理成熟 | 运维重、UI 较老 | 企业多格式 |
| Artifactory | 功能全、生态广 | 商业成本高 | 大型企业 |
| GitHub/GitLab Packages | 与代码平台一体 | 格式与代理能力有限 | 已用该平台 |
| 公共 npm + 私有 scope | 零运维 | 内部包无法托管 | 仅开源项目 |
3.8 何时不该用
- 只有一两个内部包:平台自带 registry 足够,不必自建。
- 没有备份与磁盘容量:缓存会把磁盘打满,必须先规划。
- 把 token 写进仓库:任何 registry 都救不了泄露。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 安装返回 401/403 | token 过期、scope 不匹配或权限不足 | 重新登录,检查 scope 与 ACL |
| 内部包 404 | 发布到了错误 repository 或 group 未包含 | 检查 publishConfig 与 group 成员 |
| 上游新版本看不到 | proxy 缓存 TTL 未到 | 清缓存或等 TTL,确认上游 |
| tarball 校验失败 | 缓存损坏或传输截断 | 清缓存重拉,校验 sha512 |
| 发布被拒 | 版本已存在或账号无写权限 | 升版本,检查 publish 权限 |
| CI 拉包慢 | 未走 proxy 或缓存未命中 | 统一 registry,预热缓存 |
| 磁盘写满 | 缓存/快照无保留策略 | 设 TTL、清理与容量告警 |
| 依赖来源不明 | 客户端绕过私有仓库直连公网 | 强制 registry + 网络策略 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
| 覆盖已发布版本 | 下游不可复现 | 发新版本,弃用旧版本 |
token 提交到 .npmrc | 凭据泄露 | 环境变量/密钥管理 |
| 所有包都发布到 public | 内部代码外泄 | scope + hosted 仓库 |
| 关闭完整性校验 | 供应链攻击面扩大 | 保留 lockfile 与校验和 |
| 只配 proxy 不配 group | 内部包与公共包两套地址 | group 统一入口 |
4.3 可观测信号
下载/发布成功率、401/403 比例、回源延迟、缓存命中率、磁盘使用、包版本增长、异常下载来源。审计日志要能回答“谁在何时发布了哪个 tarball”。
4.4 安全 / 性能 / 一致性边界
- 安全:registry 是依赖入口;token 最小权限、短期有效,发布需审批。
- 性能:缓存命中决定 CI 速度;TTL 太短会放大回源,太长会看不到修复。
- 一致性:已发布版本不可变;lockfile + 校验和保证下游拿到同一份。
- 可用性:私有仓库故障会阻断所有构建,需备份、只读镜像或降级方案。