利用双网卡服务器搭建 Verdaccio 中转，解决内网 npm 依赖下载问题

- 一、场景与痛点
- 二、整体思路
- [三、在双网卡服务器上安装与配置 Verdaccio](#三、在双网卡服务器上安装与配置 Verdaccio)
- - [3.1 基础环境](#3.1 基础环境)
  - [3.2 配置 Verdaccio 监听内网地址](#3.2 配置 Verdaccio 监听内网地址)
  - [3.3 配置上游代理（uplinks）](#3.3 配置上游代理（uplinks）)
  - [3.4 配置存储路径与权限](#3.4 配置存储路径与权限)
  - [3.5 启动 Verdaccio](#3.5 启动 Verdaccio)
- 四、内网开发机配置
- - [4.1 全局配置（推荐）](#4.1 全局配置（推荐）)
  - [4.2 项目级配置（`.npmrc`）](#4.2 项目级配置（.npmrc）)
  - [4.3 仅对特定作用域生效](#4.3 仅对特定作用域生效)
  - [4.4 登录与发布](#4.4 登录与发布)
- 五、缓存预热（可选）
- - [5.1 手动执行 `npm install`](#5.1 手动执行 npm install)
  - [5.2 使用自动化脚本批量预热](#5.2 使用自动化脚本批量预热)
- 六、进阶配置与优化
- - [6.1 缓存过期策略](#6.1 缓存过期策略)
  - [6.2 限流与并发控制](#6.2 限流与并发控制)
  - [6.3 使用 Nginx 反代加一层安全](#6.3 使用 Nginx 反代加一层安全)
  - [6.4 磁盘空间管理](#6.4 磁盘空间管理)
- 七、常见问题与排查
- - [7.1 内网开发机无法访问 Verdaccio](#7.1 内网开发机无法访问 Verdaccio)
  - [7.2 安装包时 404 或超时](#7.2 安装包时 404 或超时)
  - [7.3 缓存包版本过旧](#7.3 缓存包版本过旧)
  - [7.4 安全考量](#7.4 安全考量)

一、场景与痛点

在内网开发环境中，我们常遇到这样的困境：

开发机只能访问内网，无法直接连接外网 npm registry；
每次新增依赖都需要手动下载包，再通过 U 盘或跳板机传入，效率极低；
依赖的传递依赖更是让手动处理变得几乎不可能。

但现实中，很多企业网络架构中会有一台双网卡服务器------它同时连接内网和外网，充当网关或跳板机。如果能把这台服务器利用起来，部署一个 npm 代理服务，内网开发机就能通过它间接访问外网 registry，从而彻底告别手动搬运依赖的麻烦。

Verdaccio 正是最适合这个场景的工具。它轻量、易配置，支持透明代理和缓存，部署在双网卡服务器上即可成为内网的 npm 镜像源。

二、整体思路

工作流程：

内网开发机将 npm registry 配置为双网卡服务器的内网 IP 和端口（如 http://192.168.1.100:4873）。
当开发机执行 npm install 时，请求会发往 Verdaccio。
Verdaccio 首先检查本地缓存中是否有该包：
- 如果有，直接返回缓存；
- 如果没有，则通过外网网卡向 registry.npmjs.org 请求下载，下载后缓存到本地，并返回给客户端。
后续所有内网开发机请求同一个包时，均直接从缓存读取，不再消耗外网带宽。

三、在双网卡服务器上安装与配置 Verdaccio

3.1 基础环境

服务器需安装 Node.js（v18+）和 npm。若服务器本身无法直接安装，可先通过外网下载安装包再传入，但通常双网卡服务器能访问外网，直接在线安装即可。

bash 复制代码

# 安装 Verdaccio（全局）
npm install -g verdaccio

3.2 配置 Verdaccio 监听内网地址

Verdaccio 默认监听 localhost:4873，只有本机能访问。我们需要让它监听内网 IP，以便内网其他机器访问。

编辑配置文件（默认位于 ~/.config/verdaccio/config.yaml），修改 listen 字段：

yaml 复制代码

# 监听所有网络接口（0.0.0.0），或指定具体内网 IP
listen: 0.0.0.0:4873

如果服务器有多个内网 IP，也可以指定具体 IP，如 listen: 192.168.1.100:4873。

3.3 配置上游代理（uplinks）

保持默认配置即可，指向公共 npm registry：

yaml 复制代码

uplinks:
  npmjs:
    url: https://registry.npmjs.org/

3.4 配置存储路径与权限

storage 目录用于缓存所有下载的包，建议放在大容量磁盘分区。权限控制可根据需要调整：

yaml 复制代码

storage: /var/verdaccio/storage   # 可修改为较大磁盘路径

packages:
  '**':
    access: $all          # 允许内网所有用户访问（可改为 $authenticated 加强安全）
    publish: $authenticated
    proxy: npmjs          # 允许从外网上游拉取

3.5 启动 Verdaccio

bash 复制代码

verdaccio --config /path/to/config.yaml

建议使用 PM2 或 systemd 管理进程，确保长期运行。生产环境可采用 PM2：

bash 复制代码

pm2 start verdaccio --name "verdaccio"
pm2 save
pm2 startup

四、内网开发机配置

每台内网开发机只需将 npm registry 指向服务器的内网地址即可。

4.1 全局配置（推荐）

bash 复制代码

npm set registry http://192.168.1.100:4873/

4.2 项目级配置（`.npmrc`）

在项目根目录创建 .npmrc 文件：

复制代码

registry=http://192.168.1.100:4873

4.3 仅对特定作用域生效

如果只想让 @mycompany 作用域的包走内网，其他包仍走公共源（但内网机无法访问外网，所以通常全部代理）：

复制代码

@mycompany:registry=http://192.168.1.100:4873

4.4 登录与发布

若需要发布私有包，先在内网开发机上登录：

bash 复制代码

npm login --registry=http://192.168.1.100:4873

然后发布：

bash 复制代码

npm publish --registry=http://192.168.1.100:4873

Verdaccio 会存储这些私有包，并仅在内网可见。

五、缓存预热（可选）

虽然 Verdaccio 会在首次请求时自动下载并缓存，但若内网有大量开发者同时首次使用，可能会造成瞬时外网流量高峰和等待延迟。推荐提前在服务器上"预热"常用依赖。

5.1 手动执行 `npm install`

将项目的 package.json 和 package-lock.json 复制到服务器上（或直接在服务器上 git clone），设置 registry 为本机地址：

bash 复制代码

npm set registry http://localhost:4873/
npm install

此时 Verdaccio 会自动下载所有依赖并缓存到 storage 目录。之后内网开发机再请求时，全部命中缓存。

5.2 使用自动化脚本批量预热

如果项目众多，可编写简单脚本遍历多个项目目录，执行 npm install，一次性完成缓存填充。

六、进阶配置与优化

6.1 缓存过期策略

Verdaccio 默认缓存时间较长，若希望定期更新包（获取最新补丁版本），可配置 ttl（Time To Live）：

yaml 复制代码

uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    cache: false              # 禁用缓存 metadata，强制每次查询上游
    max_age: 600              # 缓存元数据 10 分钟（单位秒）

但通常内网环境更看重稳定性，保留默认缓存即可。

6.2 限流与并发控制

防止大量并发请求打满外网带宽，可在配置中限制并发数：

yaml 复制代码

uplinks:
  npmjs:
    url: https://registry.npmjs.org/
    max_fails: 10
    timeout: 30s
    max_sockets: 10          # 最大并发连接数

6.3 使用 Nginx 反代加一层安全

生产环境建议在 Verdaccio 前加 Nginx，实现 HTTPS 加密、访问控制、负载均衡等：

nginx 复制代码

server {
    listen 80;
    server_name npm.internal.company.com;

    location / {
        proxy_pass http://127.0.0.1:4873;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

内网开发机即可使用域名访问，更规范。

6.4 磁盘空间管理

缓存目录会随着时间增长，需定期清理或设置自动清理策略。Verdaccio 提供了 storage 插件的 --clean 命令，或可手动删除过期包。

七、常见问题与排查

7.1 内网开发机无法访问 Verdaccio

检查服务器防火墙是否开放 4873 端口（或自定义端口）。
确认 listen 配置为 0.0.0.0 或正确的内网 IP。
确认内网路由可达，可用 telnet 192.168.1.100 4873 测试连通性。

7.2 安装包时 404 或超时

检查服务器外网连通性（ping registry.npmjs.org 或 curl）。
若上游有网络限制，可改用淘宝镜像源作为上游：url: https://registry.npmmirror.com/。
查看 Verdaccio 日志，确认是否成功从上游拉取。

7.3 缓存包版本过旧

若需要强制刷新缓存，可删除 storage 下对应包的文件夹，重启 Verdaccio，下次请求会重新拉取。

7.4 安全考量

内网环境相对安全，但若担心未授权访问，可将 packages['**'].access 设为 $authenticated，要求所有用户登录。
使用 htpasswd 限制注册（max_users: -1），避免无关人员注册。
启用 HTTPS 加密传输（若通过 Nginx 代理，可配置 SSL 证书）。

参考资源：

Verdaccio 官网：https://verdaccio.org/
GitHub 仓库：https://github.com/verdaccio/verdaccio
官方配置文档：https://verdaccio.org/docs/configuration
PM2 进程管理：https://pm2.keymetrics.io/

利用双网卡服务器搭建 Verdaccio 中转，解决内网 npm 依赖下载问题

利用双网卡服务器搭建 Verdaccio 中转，解决内网 npm 依赖下载问题

一、场景与痛点

二、整体思路

三、在双网卡服务器上安装与配置 Verdaccio

3.1 基础环境

3.2 配置 Verdaccio 监听内网地址

3.3 配置上游代理（uplinks）

3.4 配置存储路径与权限

3.5 启动 Verdaccio

四、内网开发机配置

4.1 全局配置（推荐）

4.2 项目级配置（.npmrc）

4.3 仅对特定作用域生效

4.4 登录与发布

五、缓存预热（可选）

5.1 手动执行 npm install

5.2 使用自动化脚本批量预热

六、进阶配置与优化

6.1 缓存过期策略

6.2 限流与并发控制

6.3 使用 Nginx 反代加一层安全

6.4 磁盘空间管理

七、常见问题与排查

7.1 内网开发机无法访问 Verdaccio

7.2 安装包时 404 或超时

7.3 缓存包版本过旧

7.4 安全考量

4.2 项目级配置（`.npmrc`）

5.1 手动执行 `npm install`