VictoriaMetrics 中文手册
运维指南
安装部署

安装部署

单机版

安装

要快速尝试 VictoriaMetrics，只需下载 VictoriaMetrics 可执行文件或 Docker 镜像，并使用所需的运行参数启动它。还可以参考快速开始指南获取更多信息。

此外，也可以通过以下方法来安装VictoriaMetrics：

运行

下面的几个运行参数是最常用的：

  • -storageDataPath：VictoriaMetrics 把所有的数据都保存在这个目录。默认的路径是当前工作目录中的victoria-metrics-data子目录。
  • -retentionPeriod：数据的保留时间。历史的数据会被自动清理删除。默认的保留时间是 1 个月。最小的保留时间是 1 天（即 24 小时）。点击了解更多详情。

其他的运行参数，建议使用默认值就可以了，只有在有特殊需求的时候再调整他们。用-help参数看下所有可用参数及他们描述和默认值。

正因 VictoriaMetrics 的配置参数都是通过命令行传递的，所以它不支持动态修改配置。如果要修改配置就只能用新的命令行对 VictoriaMetrics 进行重启。步骤如下：

  • 向 VictoriaMetrics 进程发送SIGINT信号，让其优雅退出。请参阅如何向进程发送信号。
  • 等待进程退出。可能需要几秒钟时间。
  • 用新的命令行参数启动 VictoriaMetrics。

使用 docker-compose

Docker-compose 能帮助我们用一条命令加速启动 VictoriaMetrics, vmagent 和 Grafana。更多详细信息请查阅这里。

Systemd Service

参考这里将 VictoriaMetrics 设置为一个 Systemd Service。 我们提供了 Snap 包 可在 Ubuntu 上直接使用。

下面的几个文档，对初始化 VictoriaMetrics 服务可能会有些帮助：

VictoriaMetrics 默认使用 8428 端口处理 Prometheus 查询请求。建议为 VictoriaMetrics 搭建监控。

环境变量

所有的 VictoriaMetrics 组件都支持在启动参数中使用语法%{ENV_VAR}引用环境变量。比如，

在 VictoriaMetrics 启动时，如果环境变量中存在METRICS_AUTH_KEY=top-secret，那么-metricsAuthKey=%{METRICS_AUTH_KEY}就会自动转换成metricsAuthKey=top-secret。这个转换是 VictoriaMetrics 自动做的。

VictoriaMetrics 会递归的转换环境变量。比如我们有 2 个环境变量BAR=a%{BAZ}和BAZ=bc。那对于FOO=%{BAR}就会自动被转换成FOO=abc。

此外，所有的 VictoriaMetrics 组件都允许根据以下规则用环境变量设置启动参数：

  • 必须开启-envflag.enable启动参数。
  • 参数名中的每一个.字符都会被用_替代（比如-insert.maxQueueDuration <duration>对应的环境变了是insert_maxQueueDuration=<duration>）。
  • 对于数组类参数，替代方式是用逗号,把多个参数值链接起来（比如-storageNode <nodeA> -storageNode <nodeB>对应的环境变量是storageNode=<nodeA>,<nodeB>）。
  • 环境变量的前缀可以通过参数-envflag.prefix设定. 比如，如果-envflag.prefix=VM_, 那么所有环境变量名都要以VM_开头。

升级

除非发布日志里特别声明了，否则升级 VictoriaMetrics 到最新版本都是安全的。 跨多个版本升级也是安全的，除非发布日志里有特别声明。建议定期升级到最新版本，因为最新版可能包含重要的 bugfix、性能优化或新功能。

除非发布日志另有说明，降级到旧版本也是安全的。

在升级/降级过程中必须执行以下步骤：

  • 向 VictoriaMetrics 进程发送SIGINT信号让它优雅退出。请参阅如何向进程发送信号。
  • 等待进程退出。这可能需要几秒钟时间。
  • 启动新版本的 VictoriaMetrics。

Prometheus 重启不会导致 remote write 丢失数据。详细信息请参阅本文。对于 vmagent 也一样。

构建

我们建议使用官方发布的二进制 或者 Docker 镜像，不建议使用源代码进行构建。
构建源代码一般是在你要开发一些定制化需求或者测试 BUG 修复时候才需要。

构建开发环境

  1. 安装 Go。 要求最低版本是 Go 1.19。
  2. 在仓库的根目录运行命令make victoria-metrics。该命令会构建victoria-metrics二进制然后把它放到bin目录中。

构建生产环境

  1. 安装 docker。
  2. 在仓库的跟目录执行命令make victoria-metrics-prod。 命令会构建victoria-metrics-prod二进制，并把它放到bin目录中.

ARM 构建

ARM 的构建可以在树莓派或 energy-efficient ARM servers上执行。

开发环境 ARM 构建

  1. 安装 Go. 要求最低版本是 Go 1.19。
  2. 在这个仓库根目录执行make victoria-metrics-linux-arm或make victoria-metrics-linux-arm64. 该命令可以构建出victoria-metrics-linux-arm或victoria-metrics-linux-arm64二进制，并把它放到bin目录中。

生产环境 ARM 构建

  1. 安装 docker.
  2. 在这个仓库根目录执行make victoria-metrics-linux-arm-prod或make victoria-metrics-linux-arm64-prod. 它构建出victoria-metrics-linux-arm-prod或victoria-metrics-linux-arm64-prod二进制，并把它放到bin目录中。

纯 Go 构建 (CGO_ENABLED=0)

纯Go模式构建就是只构建没有 cgo 的依赖的 Go 代码。

  1. 安装 Go。 要求最低版本是 Go 1.19。
  2. 在仓库的根目录执行命令make victoria-metrics-pure，命令会构建出二进制victoria-metrics-pure，并把它放到bin目录中。

构建 Docker 镜像

执行命令make package-victoria-metrics。该命令会在本地构建victoriametrics/victoria-metrics:<PKG_TAG>的镜像。<PKG_TAG>是使用仓库的源代码自动生成的镜像 Tag。<PKG_TAG>可以通过环境变量指定，比如执行命令PKG_TAG=foobar make package-victoria-metrics。

基础镜像用的是 alpine，但是可以使用<ROOT_IMAGE>环境变量指定使用其他基础镜像。 比如，下面的命令就是使用 scratch 作为我们的基础镜像:

ROOT_IMAGE=scratch make package-victoria-metrics

集群版

一个集群至少包含下面几项：

  • 一个vmstorage节点，需要指定-retentionPeriod和-storageDataPath参数
  • 一个vminsert节点，需要指定-storageNode=<vmstorage_host>
  • 一个vmselect节点，需要指定-storageNode=<vmstorage_host>

建议每个服务至少运行两个实例，来保证高可用。在这种情况下，当一个实例暂时不可用时，集群仍可继续工作，其余节点可以处理增加的工作量。

最好运行许多小型 vmstorage 节点而非少量大型 vmstorage 节点，因为当某些 vmstorage 节点不可用时，这可以减少剩余 vmstorage 实例的压力增加。

必须在 vminsert 和 vmselect 节点前放置一个 http 负载均衡器，例如 vmauth 或 nginx。它必须根据 url 格式包含以下路由配置：

  • 带有/insert前缀的请求必须被路由到 vminsert 实例的 8480 端口数。
  • 带有/select前缀的请求必须被路由到 vmselect 实例的 8481 端口数。

端口可以通过-httpListenAddr参数来设定。

建议为集群配置上监控。

下面的工具可以简化集群部署：

可以在单个主机上手动设置一个玩具集群。在这种情况下，每个集群组件 - vminsert、vmselect 和 vmstorage - 必须使用-httpListenAddr启动参数指定不同的端口。此参数指定用于接受监控和 Profiling 的 http 请求的地址。vmstorage实例必须对下面你的参数设定不同地址参数，以避免端口冲突：

  • -storageDataPath- 每个vmstorage实例都不行有一个专用的数据存储路径。
  • -vminsertAddr- 每个vmstorage实例必须监听一个 tcp 地址，用来接受 vminsert 发送过来的数据。
  • -vmselectAddr- 每个vmstorage实例必须监听一个 tcp 地址，用来处理 vmselect 发送过来的查询请求。

二进制

集群版本的二进制文件可在发布页面的 assets 部分中找到。

集群版本的 Docker 镜像可在此处找到：

构建

集群版本的源代码可在 cluster 分支中获取。

生产环境构建

无需在系统上安装 Go，因为二进制文件是在 Go 的官方 docker 容器内构建的。因此，安装 docker 并运行以下命令：

make vminsert-prod vmselect-prod vmstorage-prod

产生的二进制文件被放入带有-prod后缀的bin文件夹中：

$ make vminsert-prod vmselect-prod vmstorage-prod
$ ls -1 bin
vminsert-prod
vmselect-prod
vmstorage-prod

开发环境构建

  1. 安装Go，最低支持版本是 Go1.18。
  2. 从仓库根目录运行make。它应该构建vmstorage、vmselect和vminsert二进制文件并将它们放入bin文件夹中。

构建 docker 镜像

执行make package命令，会在本地构建下面几个 docker 镜像：

  • victoriametrics/vminsert:<PKG_TAG>
  • victoriametrics/vmselect:<PKG_TAG>
  • victoriametrics/vmstorage:<PKG_TAG>

<PKG_TAG>是根据仓库中的源码自动生成的 image tag。<PKG_TAG>可以使用环境变量来指定，比如：PKG_TAG=foobar make package.

默认情况下，为了提高可调试性，镜像是在 alpine image 之上构建的。可以通过ROOT_IMAGE环境变量设置在其他基础镜像之上构建镜像。例如，以下命令在临时镜像之上构建镜像：

ROOT_IMAGE=scratch make package

vmstorage 自动发现

只有企业版支持vminsert和vmselect对vmstorage实例自动服务发现，开源版的话需要进行二次开发。

VictoriaMetrics 的代码质量很高，所以二次开发也比较简单。只需要参考netstorage.Init实现即可，仅有 2 行代码。这里给出一个代码实现参考：

netstorage.go
// ResetStorageNodes initializing new storageNodes by using new addrs, and replace the old global storageNodes
func ResetStorageNodes(addrs []string, hashSeed uint64) {
	if len(addrs) == 0 {
		return
	}
	prevSnb := getStorageNodesBucket()
	snb := initStorageNodes(addrs, hashSeed)
	setStorageNodesBucket(snb)
	if prevSnb != nil {
		go func() {
			logger.Infof("Storage nodes updated, stopping previous storage nodes")
			mustStopStorageNodes(prevSnb)
			logger.Infof("Previous storage nodes already stopped")
		}()
	}
}

将上面的函数放到netstorage.go中，自己再实现发现实例列表的方法，在方法里面调用该ResetStorageNodes方法即可。

Helm

Helm Chart 简化了在 Kubernetes 中管理 VictoriaMetrics 集群版本的过程。它可在 helm-charts 仓库中获得。

Kubernetes operator

K8s operator 简化了在 Kubernetes 中管理 VictoriaMetrics 组件的过程。

单机版本