鸭梨公共文档

主题

使用 Verdaccio 搭建私有 npm 仓库 ​

Verdaccio 是一个开源的 NPM 私有仓库软件，可用于代理 npmjs.org 的包，以及发布自己的私有包。

本机使用：

bash
pnpm add -g verdaccio
verdaccio

可通过在项目下使用 .npmrc 来指定私有仓库地址：

bash
registry=http://localhost:4873/

package.json 中的 publishConfig 字段：

json
{
  "publishConfig": {
    "registry": "http://localhost:4873/"
  }
}

Docker 安装并测试：

bash
docker run -it --rm --name verdaccio -p 4873:4873 verdaccio/verdaccio

建议自定义私有包的前缀，如 local-* 或者 @my-company/*，通过这种方法可以清楚地把公有包和私有包分开。

Docker Compose 部署 ​

下面是提供包含 SSL 和 htpasswd 认证的 Docker Compose 配置示例：

yaml
services:
  verdaccio:
    image: verdaccio/verdaccio
    container_name: verdaccio
    environment:
      - VERDACCIO_PORT=4873
    ports:
      - "4873:4873"
    volumes:
      - ./conf:/verdaccio/conf
      - ./storage:/verdaccio/storage
      - ./plugins:/verdaccio/plugins
    networks:
      - verdaccio-net

networks:
  verdaccio-net:
    driver: bridge

需要配合以下配置文件 conf/config.yaml：

yaml
# 基础配置
storage: /verdaccio/storage
plugins: /verdaccio/plugins

# 网络设置
listen:
  - 0.0.0.0:4873

# HTTPS 配置
https:
  key: /verdaccio/conf/cert.key
  cert: /verdaccio/conf/cert.pem
  ca: /verdaccio/conf/ca.pem

# 认证配置
auth:
  htpasswd:
    file: /verdaccio/conf/htpasswd
    max_users: -1  # 禁用 npm adduser 注册，设置为正数可限制用户数量

# 上游镜像配置
uplinks:
  npmjs:
    url: https://registry.npmjs.org/

# 包访问权限配置
packages:
  '@*/*':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs

  '**':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs

# 日志配置
logs:
  - {type: stdout, format: pretty, level: http}

使用前需要执行以下步骤：

  1. 准备 SSL 证书（假设证书文件已存在）：

    • 将证书文件重命名并放入 conf 目录：
      • cert.pem（域名证书）
      • cert.key（私钥）
      • ca.pem（CA 证书，可选）

  2. 创建初始用户：

    bash
    # 安装 htpasswd 工具（如果尚未安装）
sudo apt-get install apache2-utils

# 创建 htpasswd 文件（将 username 替换为你的用户名）
htpasswd -c conf/htpasswd username

  3. 目录结构：

    text
    ├── docker-compose.yml
├── conf/
│   ├── config.yaml
│   ├── cert.pem
│   ├── cert.key
│   └── htpasswd
├── storage/
└── plugins/

  4. 启动服务：

    bash
    docker-compose up -d

验证配置：

bash
curl -k https://example.com:4873
npm login --registry=https://example.com:4873

注意事项：

  1. 证书需要包含完整的证书链，建议使用 Let's Encrypt 的免费证书
  2. 如果使用自签名证书，客户端需要添加 --strict-ssl=false 参数
  3. 生产环境建议将 max_users 设置为正数以限制注册
  4. 可以使用 docker exec -it verdaccio htpasswd /verdaccio/conf/htpasswd username 添加新用户
  5. 如果不需要 CA 证书，可以删除配置文件中的 ca 配置项

如果需要自动生成自签名证书（仅限测试环境），可以使用以下命令：

bash
openssl req -x509 -newkey rsa:4096 -keyout conf/cert.key -out conf/cert.pem -days 365 -nodes -subj "/CN=example.com"