Verdaccio 特性

🌙
手机阅读
本文目录结构

配置文件

此文件是 Verdaccio 的重要部分,您可以在其中修改默认行为,启用插件并扩展功能。

首次运行 verdaccio 时会创建一个默认配置文件config.yaml

默认配置

默认配置允许任何用户访问所有包,但只有经过身份验证的用户才能发布。

storage: ./storage
auth:
  htpasswd:
    file: ./htpasswd
uplinks:
  npmjs:
    url: https://registry.npmjs.org/
packages:
  '@*/*':
    access: $all
    publish: $authenticated
    proxy: npmjs
  '**':
    proxy: npmjs
logs:
  - {type: stdout, format: pretty, level: http}

配置详细解说

以下各章节解释了每个属性的含义以及不同的选项。

storage

storage: ./storage

是默认存储的位置。

Verdaccio 默认情况下基于本地文件系统。

plugins

plugins: ./plugins

是插件目录的位置。

对于基于 Docker / Kubernetes 的部署很有用

auth

auth:
  htpasswd:
    file: ./htpasswd
    max_users: 1000

认证设置在这里完成,默认的授权是基于 htpasswd 并且是内置的。

您可以通过 plugins 来修改此行为。

security

verdaccio@4.0.0开始支持

https://github.com/verdaccio/verdaccio/issues/168

security:
  api:
    legacy: true
    jwt:
      sign:
        expiresIn: 29d
      verify:
        someProp: [value]
   web:
     sign:
       expiresIn: 7d # 7 days by default
     verify:
        someProp: [value]

该安全块允许您自定义令牌签名。要启用 JWT(JSON Web 令牌)新签名,您需要将 jwt 块添加到 api 部分,Web 默认使用 jwt。

配置分为两部分,apiweb。要在 api 上使用 JWT,必须先对其进行定义,否则将使用旧式令牌签名(aes192)。对于 JWT,您可以使用自己的属性自定义签名和令牌验证。

强烈建议您迁移到 JWT,因为旧版签名(aes192)已过时,并且在以后的版本中将消失。

server

一组属性,用于修改服务器应用程序的行为,特别是 API(Express.js)

server:
  keepAliveTimeout: 60

您可以指定 HTTP/1.1 服务器保持活动超时(以秒为单位)以进行连接。 值为 0 会使 http 服务器的行为类似于 8.0.0 之前的 Node.js 版本,后者没有保持活动超时。

解决方法:通过给定的配置,您可以解决以下问题 https://github.com/verdaccio/verdaccio/issues/301。 如果 60 不够,请设置为 0。

web

此属性使您可以修改 Web UI 的外观。有关此部分的更多信息,请阅读 Web UI 页面。

web:
  enable: true
  title: Verdaccio
  logo: logo.png
  scope:
uplinks:
  npmjs:
    url: https://registry.npmjs.org/

uplinks 是系统在本地没有可用包时,从远程注册表中获取软件包的功能。

如果不指定,就会报错;

packages

包允许用户控制如何访问包

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

高级设置

离线发布

默认情况下,verdaccio 不允许客户端脱机时发布,可以通过将其设置为 true 来覆盖该行为

publish:
  allow_offline: false

verdaccio@2.3.6 开始支持

URL Prefix

url_prefix: /verdaccio/

我们建议使用子目录 /verdaccio/ 代替 URI。

Max Body Size

默认情况下,JSON 文档的最大正文大小为 10mb,如果由于"request entity too large"而出错,则可以增加此值

max_body_size: 10mb

Listen Port

verdaccio 默认在端口 4873 中运行。

可以通过 cli 或在配置文件中更改端口,以下选项有效。

listen:
# - localhost:4873            # default value
# - http://localhost:4873     # same thing
# - 0.0.0.0:4873              # listen on all addresses (INADDR_ANY)
# - https://example.org:4873  # if you want to use https
# - "[::1]:4873"                # ipv6
# - unix:/tmp/verdaccio.sock    # unix socket

HTTPS

要在 verdaccio 中启用 https,只需使用协议 https:// 设置监听标志就足够了。

有关此部分的更多信息,请阅读 ssl 页面。

https:
    key: ./path/verdaccio-key.pem
    cert: ./path/verdaccio-cert.pem
    ca: ./path/verdaccio-csr.pem

Proxy

代理是专用于 HTTP 服务器,旨在将数据从远程服务器传输到本地客户端。

http_proxy 和 https_proxy

如果您的网络中有代理,则可以使用以下属性设置 X-Forwarded-For 标头。

http_proxy: http://something.local/
https_proxy: https://something.local/

no_proxy

此变量应包含逗号分隔的域扩展列表,不应将其用于代理。

no_proxy: localhost,127.0.0.1

notify

通过 Web 钩子,启用向第三方工具的通知非常容易

notify:
  method: POST
  headers: [{'Content-Type': 'application/json'}]
  endpoint: https://usagge.hipchat.com/v2/room/3729485/notification?auth_token=mySecretToken
  content: '{"color":"green","message":"New package published: * {{ name }}*","notify":true,"message_format":"text"}'

Audit

npm audit 是随 npm 6.x 发布的新命令。

Verdaccio 包含一个内置的中间件插件来处理此命令。

middlewares:
  audit:
    enabled: true

Experiments

此版本包含一个名为 experiments 的新属性,可以将其放置在 config.yaml 中,并且是完全可选的。

我们希望能够运送新产品而不影响生产环境。该标志使我们可以添加新功能,并从想要使用它们的社区中获得反馈。

此标志下的功能可能不稳定,或者在将来的版本中可能会删除。

experiments:
  token: false

要在控制台中禁用实验警告,您必须注释掉整个实验部分。

uplinks 是系统在本地没有可用包时,从远程注册表中获取软件包的功能。

如果不指定,就会报错;

使用

uplinks:
  npmjs:
   url: https://registry.npmjs.org/
  server2:
    url: http://mirror.local.net/
    timeout: 100ms
  server3:
    url: http://mirror2.local.net:9000/
  baduplink:
    url: http://localhost:55666/

配置

您可以定义多个 uplinks(上行链路),并且每个上行链路都必须具有唯一的名称(key/ 键)。它们可以具有以下属性:

属性 类型 必填 示例 支持 描述 默认值
url 字符串 https://registry.npmjs.org/ 任意路径 外部注册服务器 URL npmjs
ca 字符串 ~./ssl/client.crt' 任意路径 SSL 证书文件路径 无默认值
timeout 字符串 100ms 任意路径 为请求设置新的超时时间 30s
maxage 字符串 10m 任意路径 the time threshold to the cache is valid 2m
fail_timeout 字符串 10m 任意路径 请求在连续失败超过指定次数后的最长等待重试时间 5m
max_fails 数字 2 任意路径 请求连续失败的最大次数限制 2
cache boolean [true,false] >= 2.1 缓存下载的远程 tarball 文件到本地 true
auth list 见下文 >= 2.5 指定“授权 authorization”请求头的内容 详情见 禁用
headers list authorization: “Bearer SecretJWToken==” 任意路径 上行链路请求的请求头 header 列表 禁用
strict_ssl boolean [true,false] >= 3.0 为 true 时,会检测 SSL 证书的有效性 true
agent_options object maxSockets: 10 >= 4.0.2 HTTP 或 HTTPS 代理的用于管理上行链路连接持久性和重用的选项更多信息 无默认值

Auth 属性

auth 属性允许您在上行链路中使用 auth 令牌。使用默认环境变量:

uplinks:
  private:
    url: https://private-registry.domain.com/registry
    auth:
      type: bearer
      token_env: true # defaults to `process.env['NPM_TOKEN']`

或者使用一个指定的环境变量

uplinks:
  private:
    url: https://private-registry.domain.com/registry
    auth:
      type: bearer
      token_env: FOO_TOKEN

token_env: FOO_TOKEN 内部将使用 process.env['FOO_TOKEN']

或者直接指定令牌:

uplinks:
  private:
    url: https://private-registry.domain.com/registry
    auth:
      type: bearer
      token: "token"

注意:token 的优先级高于 token_env

须知

  • 上行链路必须是与 npm 端点兼容的注册表。
    • 例如:verdaccio,sinopia@1.4.0,npmjs 注册表,yarn 注册表,JFrog 等。
  • 设置 cache 为 false 将有助于节省硬盘空间。这将避免存储,tarballs 但会将元数据保留在文件夹中。
  • 超过多个上行链路可能会减慢您的软件包的查找速度,这是由于 npm 客户端对每个请求所做的,verdaccio 对每个​​上行链路都会进行 1 个呼叫。
  • timeout,maxage 和 fail_timeout 格式遵循 NGINX 度量单位

Packages

这是一系列的约束,它基于特定条件允许或限制对本地存储的访问。

安全约束构建于被使用的插件上,在默认情况下,verdaccio 使用 htpasswd 插件。

如果你使用不同的插件,行为可能会有所不同。 默认插件自己并不处理 allow_accessallow_publish,它使用内部回退功能以防止插件尚未就绪。

使用

packages:
  # scoped packages
  '@scope/*':
    access: $all
    publish: $all
    proxy: server2

  'private-*':
    access: $all
    publish: $all
    proxy: uplink1

  '**':
    # allow all users (including non-authenticated users) to read and
    # publish all packages
    access: $all
    publish: $all
    proxy: uplink2

如果未进行任何设置,默认值则会被保留

packages:
  '**':
    access: $all
    publish: $authenticated

verdaccio 处理的列表内部组是:

'$all', '$anonymous', '@all', '@anonymous', 'all', 'undefined', 'anonymous'

如果 htpasswd 返回用户名为组,所有用户,不管匿名与否,都会分别接到该组的权限以及插件提供的组。

例如,如果你以 npmUser 身份登录,组列表为。

// groups without '$' are going to be deprecated eventually
'$all', '$anonymous', '@all', '@anonymous', 'all', 'undefined', 'anonymous', 'npmUser'

如果你想要保护你所在组的特定包,你需要做如下工作。 我们来使用一个包含所有前缀为 npmuser- 的包的 Regex。

我们建议您为软件包使用前缀,这样可以更轻松地保护它们

packages:
  'npmuser-*':
    access: npmuser
    publish: npmuser

重启 verdaccio 并在命令行中尝试安装 npmuser-core

$ npm install npmuser-core
npm install npmuser-core
npm ERR! code E403
npm ERR! 403 Forbidden: npmuser-core@latest

npm ERR! A complete log of this run can be found in:
npm ERR!     /Users/user/.npm/_logs/2017-07-02T12_20_14_834Z-debug.log

你可以使用不同的插件认证来更改现有行为。 verdaccio 只是检查试图访问或发布特定包的用户是否属于正确的组。

设置多个组

定义多个访问组非常简单,只需要在它们之间加入一个空格。

  'company-*':
    access: admin internal
    publish: admin
    proxy: server1
  'supersecret-*':
    access: secret super-secret-area ultra-secret-area
    publish: secret ultra-secret-area
    proxy: server1

阻止对一组包的访问

如果要阻止访问 / 发布到特定的软件包组。只是不定义访问和发布。

packages:
  'old-*':
  '**':
    access: $all
    publish: $authenticated

阻止代理一组特定包

您可能希望阻止一个或几个程序包从远程存储库中获取。但是,同时,允许其他程序包访问不同的上行链路

packages:
  'jquery':
    access: $all
    publish: $all
  'my-company-*':
    access: $all
    publish: $authenticated
  '@my-local-scope/*':
    access: $all
    publish: $authenticated
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

让我们描述一下在上面的示例中我们想要做什么:

  • 我想要自己的服务器上放置 jquery 依赖库但需要避免代理它。
  • 我想要所有和 my-company-*匹配的依赖库但我需要避免代理它们。
  • 我想要在 my-local-scope 范围内的所有依赖库但我需要避免代理它们。
  • 我想要代理所有剩余的依赖库。

请注意,包定义的顺序很重要,请始终使用双通配符,因为如果你没有包含它,verdaccio 会帮你来包含它,这样你的依赖库解析会受到影响。

取消发布包

该属性的发布处理权限为 npm publishnpm unpublish

但是,如果您想更具体一点,可以在包访问部分中使用 unpublish 属性,例如:

packages:
  'jquery':
    access: $all
    publish: $all
    unpublish: root
  'my-company-*':
    access: $all
    publish: $authenticated
    unpublish:
  '@my-local-scope/*':
    access: $all
    publish: $authenticated
    # unpublish: property commented out
  '**':
    access: $all
    publish: $authenticated
    proxy: npmjs

在前面的示例中,将描述行为:

  • 所有用户都可以发布 jquery 包,但是只有用户 root 才能取消发布任何版本。

  • 只有经过身份验证的用户才能发布 my-company- *程序包,但不允许任何人取消发布它们。

  • 如果取消注释了 unpublish,则发布定义将授予或拒绝访问。

配置

您可以定义多个包,并且每个包都必须具有唯一的 Regex。语法基于 minimatch glob 表达式。

属性 类型 必填 示例 支持 描述
access 字符串 $all 任意路径 定义允许访问包的组
publish 字符串 $authenticated 任意路径 定义允许发布的组
proxy 字符串 npmjs 任意路径 针对特定的 uplink 限制查找
storage 字符串 字符串 /some-folder 它在每个文件夹访问的存储文件夹中创建一个子文件夹

我们建议不要再使用 allow_access/allow_publish 和 proxy_access,它们已被弃用,不久将被删除,请使用其中每个的简短版本(access / publish / proxy)。

auth / 认证方式

身份验证与您正在使用的 auth 插件相关。 包限制也由“包访问”处理。

客户端身份验证由 npm 客户端本身处理。 登录到应用程序后:

npm adduser --registry http://localhost:4873

npm 会将 Verdaccio 返回的 Token 保存在配置文件中,它存放于您的用户主目录下。 如需了解更多有关于 npm 配置 (.npmrc) 相关的内容,请查阅 官方文档。

cat .npmrc
registry=http://localhost:5555/
//localhost:5555/:_authToken="secretVerdaccioToken"
//registry.npmjs.org/:_authToken=secretNpmjsToken

匿名发布包

verdaccio 允许启用匿名发布,要使用这个功能,必须设置正确的 程序包访问权限。

  'my-company-*':
    access: $anonymous
    publish: $anonymous
    proxy: npmjs

所有次要发行版都不允许您在没有令牌的情况下进行发布。

https://github.com/verdaccio/verdaccio/issues/212#issuecomment-308578500

组织

$all$anonymous 的含义

如您所知,Verdaccio 默认使用 htpasswd。

该插件未实现 allow_access,allow_publish 和 allow_unpublish 方法。因此,Verdaccio 将通过以下方式进行处理:

  • 如果您尚未登录(您是匿名用户),则 $all$anonymous 的含义完全相同。
  • 如果您已登录,则 $anonymous 将不属于您的组,并且 $all 将与任何登录的用户匹配。新的 $authenticated 组将添加到列表中。

总而言之,$all 将匹配所有用户,无论是否登录。

先前的行为仅适用于默认身份验证插件。 如果您使用的是自定义插件,并且此类插件实现了 allow_accessallow_publishallow_unpublish,则访问的分辨率取决于插件本身。 Verdaccio 将仅设置默认组。

  • logged: $all, $authenticated, + groups added by the plugin
  • anonymous (logged out): $all and $anonymous.

默认 htpasswd

为了简化安装,verdaccio 使用 htpasswd 基础上的插件。

从 v3.0.x 版本开始,默认使用 verdaccio-htpasswd 插件。

auth:
  htpasswd:
    file: ./htpasswd
    # Maximum amount of users allowed to register, defaults to "+inf".
    # You can set this to -1 to disable registration.
    #max_users: 1000
属性 类型 必填 示例 支持 描述
文件 字符串 ./htpasswd 任意路径 存储了加密认证信息的 htpasswd 文件
max_users 数字 1000 任意路径 最大的用户数量

如果需要禁止新用户注册,可将配置修改为 max_users: -1.

notify/ 通知事项

通知主要是为了与 Slack 的传入 Webhooks 一起使用而构建的,但也将向任何端点提供简单的有效负载。 当前仅对 npm publish 命令有效。

使用

带有 HipChat,Stride 和 Google Hangouts 聊天钩子的示例

Verdaccio 支持任何 API,请随时添加更多示例。

单个通知

notify:
  method: POST
  headers: [{'Content-Type': 'application/json'}]
  endpoint: https://usagge.hipchat.com/v2/room/3729485/notification?auth_token=mySecretToken
  content: '{"color":"green","message":"New package published: * {{ name }}*","notify":true,"message_format":"text"}'

多通知

notify:
  'example-google-chat':
    method: POST
    headers: [{'Content-Type': 'application/json'}]
    endpoint: https://chat.googleapis.com/v1/spaces/AAAAB_TcJYs/messages?key=myKey&token=myToken
    content: '{"text":"New package published: `{{ name }}{{#each versions}} v{{version}}{{/each}}`"}'
  'example-hipchat':
     method: POST
     headers: [{'Content-Type': 'application/json'}]
     endpoint: https://usagge.hipchat.com/v2/room/3729485/notification?auth_token=mySecretToken
     content: '{"color":"green","message":"New package published: * {{ name }}*","notify":true,"message_format":"text"}'
  'example-stride':
     method: POST
     headers: [{'Content-Type': 'application/json'}, {'authorization': 'Bearer secretToken'}]
     endpoint: https://api.atlassian.com/site/{cloudId}/conversation/{conversationId}/message
     content: '{"body": {"version": 1,"type": "doc","content": [{"type": "paragraph","content": [{"type": "text","text": "New package published: * {{ name }}* Publisher name: * {{ publisher.name }}"}]}]}}'

模板

用 Handlebars 作为主要模板引擎。https://handlebarsjs.com/

格式范例

# iterate all versions
{{ name }}{{#each versions}} v{{version}}{{/each}}

# publisher and `dist-tag` package published
{{ publisher.name }} has published {{ publishedPackage }}

属性

通过模板进入的属性列表

  • 元数据
  • 发表者(在发表的人)
  • 已发布的包(包 @1.0.0)

元数据

模板可以访问的包元数据

{
    "_id": "@test/pkg1",
    "name": "@test/pkg1",
    "description": "",
    "dist-tags": {
        "beta": "1.0.54"
    },
    "versions": {
        "1.0.54": {
            "name": "@test/pkg1",
            "version": "1.0.54",
            "description": "some description",
            "main": "index.js",
            "scripts": {
                "test": "echo \"Error: no test specified\" && exit 1"
            },
            "keywords": [],
            "author": {
                "name": "Author Name",
                "email": "author@domain.com"
            },
            "license": "MIT",
            "dependencies": {
                "webpack": "4.12.0"
            },
            "readmeFilename": "README.md",
            "_id": "@ test/pkg1@1.0.54",
            "_npmVersion": "6.1.0",
            "_nodeVersion": "9.9.0",
            "_npmUser": {},
            "dist": {
                "integrity": "sha512-JlXWpLtMUBAqvVZBvH7UVLhXkGE1ctmXbDjbH/l0zMuG7wVzQ7GshTYvD/b5C+G2vOL2oiIS1RtayA/kKkTwKw==",
                "shasum": "29c55c52c1e76e966e706165e5b9f22e32aa9f22",
                "tarball": "http://localhost:4873/@test/pkg1/-/@test/pkg1-1.0.54.tgz"
            }
        }
    },
    "readme": "# test",
    "_attachments": {
        "@test/pkg1-1.0.54.tgz": {
            "content_type": "application/octet-stream",
            "data": "H4sIAAAAAAAAE+y9Z5PjyJIgOJ ...",
            "length": 33112
        }
    },
    "time": {}
}

发表人

您可以用 publisher object(对象)在 webhook 的 content 里访问包发表人信息。

请参阅以下 publisher object(对象)类别:

{
  name: string,
  groups: string[],
  real_groups: string[]
}

范例:

notify:
  method: POST
  headers: [{'Content-Type': 'application/json'}]
  endpoint: https://usagge.hipchat.com/v2/room/3729485/notification?auth_token=mySecretToken
  content: '{"color":"green","message":"New package published: * {{ name }}*. Publisher name: * {{ publisher.name }} *.","notify":true,"message_format":"text"}'

注意:如果 package.json 文件已经具有 Publisher 属性,则无法获取发布者信息。

已发布包

您可以使用关键字{{publishedPackage}}访问正在发布的包,如下所示。

{{ publisher.name }} has published {{ publishedPackage }}

配置

属性 类型 必填 支持路径 描述
method 字符串 任意路径 HTTP verb
packagePattern 字符串 任意路径 仅当包名字和正规表达式匹配时才运行此通知
packagePatternFlags 字符串 任意路径 任何与正规表达式一起使用的标记
headers array/object 任意路径 如果此端点需要特定的标头,请把它们设置为键数组:value objects(值对象)。
endpoint 字符串 任意路径 设置此调用的 URL 端点
content 字符串 任意路径 任何 Handlebar 表达式

Logger/ 日志

与任何 Web 应用程序一样,verdaccio 具有可自定义的内置记录器。 您可以定义多种类型的输出。

logs:
  # console output
  - {type: stdout, format: pretty, level: http}
  # file output
  - {type: file, path: verdaccio.log, level: info}
  # Rotating log stream. Options are passed directly to bunyan.
  # See: https://github.com/trentm/node-bunyan#stream-type-rotating-file
  - {type: rotating-file, format: json, path: /path/to/log.jsonl, level: http, options: {period: 1d}}

使用 SIGUSR2 通知应用程序,日志文件已轮换,需要重新打开它。 注意:在集群模式下不支持循环日志流。 看这里 : https://github.com/trentm/node-bunyan#stream-type-rotating-file

配置

属性 类型 必填 示例 支持 描述
type 字符串 [stdout, file] 任意路径 定义输出
path 字符串 verdaccio.log 任意路径 如果类型为文件,请定义该文件的位置
format 字符串 [pretty, pretty-timestamped] 任意路径 输出格式
level 字符串 [fatal, error, warn, http, info, debug, trace] 任意路径 详细级别

用户界面

Verdaccio 有可定制的 Web 界面用于管理私有包

https://a.axihe.com/npm/verdaccio/webui.png

web:
  enable: true
  title: Verdaccio
  logo: logo.png
  primary_color: "#4b5e40"
  gravatar: true | false
  scope: "@scope"
  sort_packages: asc | desc

所有访问限制设置可以参考 保护包 页面,这些规则也将应用于 Web 界面。

国际化

Since v4.5.0, there are translations available

i18n:
  web: en-US

Only️仅此列表中的语言可用,请随时贡献更多。 默认值是 es-US

配置

属性 类型 必填 示例 支持 描述
enable boolean true/false 任意路径 允许显示网页界面
title 字符串 Verdaccio 任意路径 HTML 页眉标题说明
gravatar boolean true >v4 如果启用此属性,将在引擎盖下生成图像
sort_packages [asc,desc] asc >v4 默认情况下,私有包按升序排序
logo 字符串 /local/path/to/my/logo.png
http://my.logo.domain/logo.png
任意路径 logo 所在的 URI 路径(顶部 logo)
primary_color 字符串 “#4b5e40” >4 在整个 UI 中使用的主要颜色(标题等)
scope 字符串 @myscope >v3.x 如果您将此注册表用于特定的模块范围,请在 webui 指令标题中指定该范围以进行设置

建议 logo 尺寸为 40x40 像素。


AXIHE / 精选资源

浏览全部教程

面试题

学习网站

前端培训
自己甄别

前端书籍

关于朱安邦

我叫 朱安邦,阿西河的站长,在杭州。

以前是一名平面设计师,后来开始接接触前端开发,主要研究前端技术中的JS方向。

业余时间我喜欢分享和交流自己的技术,欢迎大家关注我的 Bilibili

关注我: Github / 知乎

目前重心已经放在研究区块链上面了

我叫朱安邦,阿西河的站长

目前在杭州从事区块链周边的开发工作,机械专业,以前从事平面设计工作。

2014年底脱产在老家自学6个月的前端技术,自学期间几乎从未出过家门,最终找到了满意的前端工作。更多>