搭建私有npm仓库之verdaccio

Posted on Edited on Views:

一、目录结构

verdaccio-docker/
├── docker-compose.yml
├── verdaccio/
│   ├── config.yaml
│   └── storage/          # 自动创建，存放下载的 npm 包
│   ├── htpasswd          # 认证账户密码

二、配置文件

1. verdaccio/config.yaml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
storage: /verdaccio/storage

uplinks:
  npmjs:
    url: https://registry.npmmirror.com/  # 上游仓库

packages:
  '@*/*':
    access: $all
    publish: $authenticated
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

auth:
  htpasswd:
    file: /verdaccio/htpasswd
    max_users: 100

# 允许外部访问
listen: 0.0.0.0:4873

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

# 插件配置（可选）
web:
  title: Verdaccio Private npm registry
  gravatar: true
  favicon: https://verdaccio.org/docs/assets/favicon.ico

# 安全配置
security:
  api:
    jwt:
      sign:
        expiresIn: 30d
      verify:
        someSecret: 'P8VlF5PmcJc'
  web:
    sign:
      expiresIn: 30d
    verify:
      someSecret: 'P8VlF5PmcJc'

2. docker-compose.yml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
services:
  verdaccio:
    image: verdaccio/verdaccio:latest
    container_name: verdaccio
    restart: always
    ports:
      - "4873:4873"
    volumes:
      - ./verdaccio/config.yaml:/verdaccio/conf/config.yaml
      - ./verdaccio/storage:/verdaccio/storage
      - ./verdaccio/htpasswd:/verdaccio/htpasswd
    environment:
      - VERDACCIO_PORT=4873
    networks:
      - verdaccio-net

networks:
  verdaccio-net:
    driver: bridge

三、启动步骤

1. 初始化目录

1
mkdir -p verdaccio-docker/verdaccio/  && touch verdaccio-docker/verdaccio/htpasswd

2. 创建配置文件

将上述两个文件分别保存为：

  • verdaccio-docker/docker-compose.yml
  • verdaccio-docker/verdaccio/config.yaml

3.初始化htpasswd

# admin/admin@321
docker run --rm httpd:latest htpasswd -nb admin admin@321
...
admin:$apr1$FKx4Htf0$Ao1NhIyrwTlyLZ9U6gzha.

tee >verdaccio/htpasswd <<EOF
admin:$apr1$FKx4Htf0$Ao1NhIyrwTlyLZ9U6gzha.
EOF

4. 启动服务

1
2
cd verdaccio-docker
docker-compose up -d

5. 验证运行状态

1
2
3
4
5
6
7
8
# 查看容器状态
docker-compose ps

# 查看日志
docker-compose logs -f verdaccio

# 测试访问
curl http://localhost:4873

a817a5bfb0777bbb889085568832df5e.png

四、使用 Verdaccio

1.发布仓库

No Package Published Yet.
To publish your first package just:
1. Create user
npm adduser --registry http://127.0.0.1:4873/

2. Publish
npm publish --registry http://127.0.0.1:4873/

3. Refresh this page

2. 客户端配置

方式一：使用 npm config（推荐）

1
2
3
4
5
6
7
8
9
10
11
12
# 设置私有仓库地址
npm config set registry http://<服务器 IP>:4873/

# 登录
npm login
# Username: admin
# Password: admin_password
# Email: admin@example.com

# 发布包
cd your-project
npm publish

方式二：使用 .npmrc 文件

在项目根目录创建 .npmrc：

1
2
registry=http://<服务器 IP>:4873/
//<服务器 IP>:4873/:_authToken=admin_password

方式三：使用 nrm 管理多个仓库

1
2
3
4
5
6
7
8
# 添加私有仓库
nrm add verdaccio http://<服务器 IP>:4873

# 切换到私有仓库
nrm use verdaccio

# 切换回官方源
nrm use npm

3. 测试上传与下载

1
2
3
4
5
6
7
8
9
10
# 创建测试包
mkdir -p test-verdaccio && cd test-verdaccio
npm init -y
npm install lodash

# 发布到私有仓库
npm publish --access public

# 从私有仓库安装（验证缓存代理）
npm install lodash  # 第二次安装会非常快，因为从本地缓存读取

五、进阶配置

1. 配置反向代理（Nginx + HTTPS）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
server {
    listen 80;
    server_name npm.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name npm.yourdomain.com;

    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    location / {
        proxy_pass http://127.0.0.1:4873;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 支持
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

2. 配置 LDAP 认证

1
2
3
4
5
6
7
8
9
10
11
12
auth:
  htpasswd:
    file: /verdaccio/htpasswd
    max_users: 100
  ldap:
    type: ldapjs
    search:
      base: dc=example,dc=com
      user: cn=admin,dc=example,dc=com
      password: admin_password
      filter: (&(objectClass=inetOrgPerson)(uid=%s))
    # ... 其他 LDAP 配置

3. 配置邮件通知

1
2
3
4
5
6
7
8
9
10
11
12
13
14
web:
  gravatar: true
  title: Verdaccio Private npm registry

mail:
  to: admin@example.com
  from: no-reply@example.com
  smtp:
    host: smtp.example.com
    port: 465
    secure: true
    auth:
      user: admin@example.com
      pass: password

六、常用命令速查

操作 命令
启动 docker-compose up -d
停止 docker-compose down
查看日志 docker-compose logs -f verdaccio
重启 docker-compose restart verdaccio
添加用户 docker exec -it verdaccio htpasswd -b /verdaccio/htpasswd user pass
查看容器状态 docker-compose ps
更新镜像 docker-compose pull && docker-compose up -d

七、注意事项

要点 说明
存储路径 /verdaccio/storage 持久化，删除会丢失缓存
认证文件 /verdaccio/htpasswd 持久化，用户信息不会丢失
内存限制 生产环境建议设置 deploy.resources.limits
端口冲突 确保 4873 端口未被占用
网络隔离 可通过 Docker Compose networks 限制访问
备份策略 定期备份 verdaccio/storage 和 verdaccio/htpasswd

八、备份与恢复

1
2
3
4
5
6
# 备份
tar -czf verdaccio-backup-$(date +%Y%m%d).tar.gz verdaccio/

# 恢复
tar -xzf verdaccio-backup-20260625.tar.gz -C /path/to/verdaccio-docker/
docker-compose restart verdaccio