跳到主要内容
版本号:5.x

配置文件

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

首次运行 Verdaccio 时会自动生成默认的配置文件 config.yaml

默认配置

默认配置支持 私有(scoped) 包,并允许所有用户 访问 所有包,但只有已登陆用户才能 发布

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

章节

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

存储

是默认的存储方式。 Verdaccio 默认使用内置本地文件模式存储

storage: ./storage

V5.6.0 发布:环境变量 VERDACCIO_STORAGE_PATH 可用于替换存储的位置(仅适用于默认存储,不适用于插件,除非它独立实现)。

.verdaccio-db 数据库

微型数据库用于存储用户发布的私有包。 该数据库基于 JSON 文件,其中包含已发布的私有包列表以及用于令牌签名的秘密令牌。 首次启动应用程序时会自动创建。

数据库的位置基于 config.yaml 文件夹位置,例如:

如果 config.yaml 位于 /some_local_path/config.yaml,则数据库将在 /some_local_path/storage/.verdaccio-db 中创建。

信息

对于长期使用 Verdaccio 且 .verdaccio-db 文件已经存在的用户,密钥长度可为 64 个字符。 但是,对于较新的安装,长度将生成为 32 个字符长。

如果密钥长度为64 个字符

  • 对于在 Node.js 22 或更高版本上运行 Verdaccio 5.x 的用户,如果密钥长度不是 32 个字符长的,应用程序将无法启动
  • 对于在 Node.js 21 或更低版本上运行 Verdaccio 5.x 的用户,应用程序可以启动,但会在控制台显示弃用警告。

如何升级存储中的令牌密钥?

⚠️ 如果更新密钥将使所有先前生成的令牌失效。

选项 1:手动

转至存储位置并手动将密钥修改为 32 个字符长。

选项 2:自动(自 v5.31.0 起)

如果长度为 64 个字符,则 migrateToSecureLegacySignature 属性用于生成新的密钥令牌。

security:
api:
migrateToSecureLegacySignature: true

令牌将自动更新为 32 个字符,应用程序将顺利启动。 该属性不会对应用程序产生任何其他影响,并且可以在更新密钥后删除。

.verdaccio-db文件数据库只有在用户不使用自定义存储时可用,默认情况下,verdaccio 使用一个小型数据库来存储私有软件包,storage属性定义在 config.yaml 文件中。 根据操作系统的不同,位置可能会有所变化。 阅读 CLI 部分 以获取有关文件位置的更多详细信息。

数据库的结构基于 JSON 文件,例如:

{
"list": ["package1", "@scope/pkg2"],
"secret": "secret_token_32_characters_long"
}
  • list: 是一个数组,包含已发布的私有包的列表,这个列表上的任何项目都被认为是由用户发布的。
  • secret:secret 字段用于令牌签名和验证,适用于 JWT 或 legacy 令牌签名。

插件

插件目录的位置。 对于基于 Docker/Kubernetes 的部署很有用。

plugins: ./plugins

认证

在这里进行身份验证设置。 默认认证基于 htpasswd,并且是内置的。 你可以通过插件来修改这一行为。 有关此部分的更多信息,请阅读授权页面

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

安全

安全配置允许使用两个选项自定义令牌签名。 配置分为两个部分:apiweb。 在使用 JWT 时,api 必须定义;否则,将使用 Legacy 令牌签名(aes192)。

token 是如何生成的?

令牌签名需要由创建 .verdaccio-db 数据库的自定义插件生成的秘密令牌,或者在使用自定义存储的情况下,秘密令牌是从插件实现本身获取的。 无论如何,启动应用程序都需要秘密令牌

Legacy 令牌签名

legacy 属性用于启用旧令牌签名。 默认情况下启用。 Legacy 功能仅应用于 API,Web UI 默认使用 JWT。

信息

在使用 Node.js 21 或更低版本的 5.x 版本中,将会看到警告 [DEP0106] DeprecationWarning: crypto.createDecipher is deprecated。 打印在终端中。 此警告表明 Node.js 已弃用 legacy 签名所使用的函数。

如果 verdaccio 在 Node.js 22 或更高版本上运行,您将不会看到此警告,因为已经实现了新的 Legacy 签名。

migrateToSecureLegacySignature 属性仅适用于高于 5.31.0 的版本,并且默认为 false

security:
api:
legacy: true # 默认情况下为 true,即使此部分未定义
migrateToSecureLegacySignature: true # 如果长度为 64 个字符,将生成一个新的加密令牌

JWT 令牌签名

要启用新的 JWT(JSON Web令牌) 签名,需要将 jwt 块添加到 api 部分; web 中默认使用 jwt

通过使用 JWT 签名,还可以使用自己的属性来自定义签名和令牌验证

security:
api:
legacy: true
migrateToSecureLegacySignature: true # will generate a new secret token if the length is 64 characters
jwt:
sign:
expiresIn: 29d
verify:
someProp: [value]
web:
sign:
expiresIn: 1h # 1 hour by default
verify:
someProp: [value]

服务器

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

您可以为传入连接指定 HTTP/1.1 服务器保 Keep-Alive 超时(以秒为单位)。 值 0 使 http 服务器的行为与 8.0.0 之前的 Node.js 版本类似,后者没有 Keep-Alive 超时时间。 解决方法:通过给定的配置,您可以解决以下问题 https://github.com/verdaccio/verdaccio/issues/301。 如果 60 不够,则设置为 0。

server:
keepAliveTimeout: 60

Web UI

此属性允许您修改 Web UI 的外观。 有关本节的更多信息,请阅读 web UI 页面

web:
enable: true
title: Verdaccio
logo: logo.png
scope:

当这些包在本地不可用时,上行链路增加了从远程注册表获取包的功能。 有关本节的更多信息,请阅读上行链接页面

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

软件包

本部分允许您控制软件包的访问方式。 有关本部分的更多信息,请阅读 软件包页面

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

高级设置

离线发布

默认情况下,verdaccio 不允许你在客户端离线时发布软件包。 可以通过将该值设置为 true 来覆盖此设置。

publish:
allow_offline: false
Since: verdaccio@2.3.6 due #223

URL 前缀

该前缀用于服务器在代理之后运行时使用,如果在没有反向代理的情况下使用,则无法正常工作,请查看 反向代理设置 页面了解更多详细信息。

内部逻辑正确构建了公共 URL,验证了 host 标头和错误的 url_prefix

例如:url_prefix: /verdaccio, url_prefix: verdaccio/, url_prefix: verdaccio 将转换为 /verdaccio/

url_prefix: /verdaccio/

新的 VERDACCIO_PUBLIC_URL 用于代理后,该变量将用于:

  • 用作提供 UI 资源(js、favicon 等)的基本路径
  • 用于返回元数据 dist 基本路径
  • 忽略 hostX-Forwarded-Proto 请求头
  • 如果设置了url_prefix则将其追加到环境变量(env) 中。

环境变量页面阅读更多关于 VERDACCIO_PUBLIC_URL 的信息。

User Agent

自 verdaccio@5.4.0`

默认情况下,用户代理是禁用的,作为交换,用户代理客户端信息(包管理器、浏览器等)被直接透传到远程服务器。 要启用以前的行为,请使用布尔值。

user_agent: true
user_agent: false
user_agent: 'custom user agent'

用户速率限制

自: `verdaccio@5.4.0` [#](https://github.com/verdaccio/verdaccio/releases/tag/v5.4.0)

为用户端 npm tokennpm profilenpm login/adduser 和登录网站设置默认请求速率限制,以每 15 分钟限制 100 个请求为例,可通过以下方式定制:

userRateLimit:
windowMs: 50000
max: 1000

还可以通过中间件文档进行其他配置(仅限功能标志)。

最大请求体大小

默认情况下,JSON 文档的最大请求体大小为 10mb,如果遇到提示"request entity too large"的错误,你可以增加该值的大小。

max_body_size: 10mb

监听端口

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:// 协议来设置 listen 标志。 如需了解更多信息,请阅读文档中的 SSL 部分

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

代理

代理是特殊用途的 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

通知

通过 webhook 启用对第三方工具的通知相当容易。 有关此部分的更多信息,请阅读通知页面

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"}'

如需了解更详细的配置设置,请查看源代码

日志

风险

自 v5.22.0 以来,logger 属性被重新命名为 logs,但 log 仍然兼容,但显示一个警告

支持两种记录器类型,您可以只选择其中一种:

控制台输出 (默认)

log: { type: stdout, format: pretty, level: http }

文件输出

log: { type: file, path: verdaccio.log, level: info }

有关完整信息-请参阅此处:Features/logger

Audit

自 verdaccio@3.0.0`

npm audit 是随 npm 6.x 发布的一项新命令。 Verdaccio 包含一个内置中间件插件来处理此命令。

使用新的安装方式会默认包含这个中间件,否则你需要添加下面这些属性到你的配置文件中

middlewares:
audit:
enabled: true

实验性

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

我们希望能够在不影响生产环境的情况下发布新特性。 此标志允许我们添加新功能并从决定使用它们的社区获得反馈。

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

以下是一个例子:

experiments:
changePassword: false

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

配置生成器 API

v5.23.1版本之后,新的高级配置构建器 API 可用。 该 API 是一种灵活的方式,可以使用构建器模式以 JSON 或 YAML 形式以编程方式生成配置输出,例如:

import { ConfigBuilder } from 'verdaccio';

const config = ConfigBuilder.build();
config
.addUplink('upstream', { url: 'https://registry.upstream.local' })
.addUplink('upstream2', { url: 'https://registry.upstream2.local' })
.addPackageAccess('upstream/*', {
access: 'public',
publish: 'foo, bar',
unpublish: 'foo, bar',
proxy: 'some',
})
.addLogger({ level: 'info', type: 'stdout', format: 'json' })
.addStorage('/tmp/verdaccio')
.addSecurity({ api: { legacy: true } });

// generate JSON object as output
config.getConfig();

// generate output as yaml
config.getAsYaml();