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。

配置分为两部分，api 和 web。要在 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

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 是系统在本地没有可用包时，从远程注册表中获取软件包的功能。

如果不指定，就会报错；

使用

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 度量单位
  • http://nginx.org/en/docs/syntax.html

Packages

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

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

如果你使用不同的插件，行为可能会有所不同。 默认插件自己并不处理 allow_access 和 allow_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 publish 和 npm 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_access，allow_publish 或 allow_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 界面用于管理私有包

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 像素。