VictoriaMetrics 中文教程（02）安装

VictoriaMetrics

在国内 IT 监控领域，上规模的公司很大概率会选型 VictoriaMetrics 作为时序存储。但 VictoriaMetrics 中文教程相对较少，我们希望通过这个系列文章，帮助大家更好地了解 VictoriaMetrics。

本文是 VictoriaMetrics 中文教程第 02 篇，讲解 VictoriaMetrics 的安装。历史文章：

VictoriaMetrics 中文教程（01）简介

核心摘要

VictoriaMetrics 支持二进制、Docker 镜像、Kubernetes operator、Helm chart、Ansible playbook 等多种安装方式。
初学者建议先用单机二进制版本体验，安装和启动都很简单。
单节点 VictoriaMetrics 默认监听 8428 端口，浏览器可访问 Web 界面。
启动时最重要的参数包括 -storageDataPath 和 -retentionPeriod。
VictoriaMetrics 支持在命令行参数和配置文件中引用环境变量，也可以通过 -envflag.enable 使用环境变量设置参数。

VictoriaMetrics 安装部署

VictoriaMetrics 支持多种安装方式：二进制安装、Docker 镜像安装，社区还提供 Kubernetes operator、Helm chart、Ansible playbook 等方式。对初学者来说，最建议从单机二进制版本开始，简单到令人发指。

VictoriaMetrics 的发布包可以到 GitHub releases 页面查找：

https://github.com/VictoriaMetrics/VictoriaMetrics/releases

写这篇文章时，最新版本是 v1.104.0，下面以这个版本为例。releases 页面下除了 VictoriaMetrics，还有 VictoriaLogs。我们要下载的是 VictoriaMetrics，注意别搞错。

VictoriaMetrics assets

发布包总共有 94 个，要选择适合自己平台的包。我的机器是 MacBook M1 芯片，所以选择 darwin-arm64，下载普通版即可，不需要 enterprise 版本。

一键启动示例：

ulric@ulric-flashcat tgz % ls -al victoria-metrics-darwin-arm64-v1.104.0.tar.gz
-rw-r--r--@ 1 ulric  staff  10854063 10 18 13:08 victoria-metrics-darwin-arm64-v1.104.0.tar.gz
ulric@ulric-flashcat tgz % mkdir victoria-metrics-darwin-arm64-v1.104.0
ulric@ulric-flashcat tgz % tar zxvf victoria-metrics-darwin-arm64-v1.104.0.tar.gz -C victoria-metrics-darwin-arm64-v1.104.0
x victoria-metrics-prod
ulric@ulric-flashcat tgz % cd victoria-metrics-darwin-arm64-v1.104.0
ulric@ulric-flashcat victoria-metrics-darwin-arm64-v1.104.0 % ls -al
total 41288
drwxr-xr-x    3 ulric  staff        96 10 18 13:09 .
drwxr-xr-x@ 101 ulric  staff      3232 10 18 13:09 ..
-rwxr-xr-x    1 ulric  staff  21137410 10  2 19:31 victoria-metrics-prod
ulric@ulric-flashcat victoria-metrics-darwin-arm64-v1.104.0 % ./victoria-metrics-prod
2024-10-18T05:10:14.101Z	info	VictoriaMetrics/lib/logger/flag.go:12	build version: victoria-metrics-20241002-113036-tags-v1.104.0-0-g0d4f4b8f7d
2024-10-18T05:10:14.101Z	info	VictoriaMetrics/lib/logger/flag.go:13	command-line flags
...
2024-10-18T05:10:14.220Z	info	VictoriaMetrics/lib/httpserver/httpserver.go:121	starting server at http://127.0.0.1:8428/
2024-10-18T05:10:14.220Z	info	VictoriaMetrics/lib/httpserver/httpserver.go:122	pprof handlers are exposed at http://127.0.0.1:8428/debug/pprof/

VictoriaMetrics 会在 8428 端口启动 HTTP 服务，可以通过浏览器访问 http://IP:8428 查看 VictoriaMetrics Web 界面。

vmui

上面示例是在前台启动。生产环境中可以把 VictoriaMetrics 作为后台服务启动，例如使用 nohup 或 systemd，这是 Linux 基础知识，这里不展开。

关键启动参数

命令行启动 VictoriaMetrics 时，可以传入很多参数。下面两个参数非常关键：

-storageDataPath：VictoriaMetrics 将所有数据存储在此目录中。默认路径是当前工作目录中的 victoria-metrics-data。
-retentionPeriod：数据保留时间。较旧的数据会被自动删除。默认保留期为 1 个月，也就是 31 天；最短保留期限为 24 小时或 1 天。很多人问“我的历史数据为什么没一直保存”，原因通常就是默认只保留 1 个月。如果要保存更久，需要通过这个参数设置。

更多参数可以通过下面命令查看：

./victoria-metrics-prod -help

VictoriaMetrics 使用环境变量

VictoriaMetrics 的各种配置基本都通过命令行参数设置。命令行参数支持引用环境变量，VictoriaMetrics 指定的一些配置文件里也支持引用环境变量。

引用环境变量的写法是 %{ENV_VAR}。例如：

-metricsAuthKey=%{METRICS_AUTH_KEY}

如果 VictoriaMetrics 启动时存在 METRICS_AUTH_KEY=top-secret 环境变量，就会自动扩展为：

-metricsAuthKey=top-secret

这个扩展由 VictoriaMetrics 本身执行。

VictoriaMetrics 启动时还会递归扩展环境变量中的 %{ENV_VAR} 引用。例如，如果 BAR=a%{BAZ} 且 BAZ=bc，则 FOO=%{BAR} 会扩展为 FOO=abc。

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

必须设置 -envflag.enable 标志。
命令行 flag 中的 . 要替换为 _，例如 -insert.maxQueueDuration <duration> 会翻译为 insert_maxQueueDuration=<duration>。
对于重复的 flag，可以使用逗号分隔的值列表。例如 -storageNode <nodeA> -storageNode <nodeB> 会转换为 storageNode=<nodeA>,<nodeB>。
环境变量前缀可以通过 -envflag.prefix 设置。例如，如果 -envflag.prefix=VM_，则环境变量必须以 VM_ 开头。

作为 Windows 服务运行

如果要把 VictoriaMetrics 作为 Windows 服务运行，需要为 WinSW 创建服务配置，然后按指南安装为服务。

1. 创建服务配置

<service>
  <id>VictoriaMetrics</id>
  <name>VictoriaMetrics</name>
  <description>VictoriaMetrics</description>
  <executable>%BASE%\victoria-metrics-windows-amd64-prod.exe</executable>

  <onfailure action="restart" delay="10 sec"/>
  <onfailure action="restart" delay="20 sec"/>

  <resetfailure>1 hour</resetfailure>

  <arguments>-envflag.enable</arguments>

  <priority>Normal</priority>

  <stoptimeout>15 sec</stoptimeout>

  <stopparentprocessfirst>true</stopparentprocessfirst>
    <startmode>Automatic</startmode>
    <waithint>15 sec</waithint>
    <sleeptime>1 sec</sleeptime>

  <logpath>%BASE%\logs</logpath>
  <log mode="roll">
    <sizeThreshold>10240</sizeThreshold>
    <keepFiles>8</keepFiles>
  </log>

  <env name="loggerFormat" value="json" />
  <env name="loggerOutput" value="stderr" />
  <env name="promscrape_config" value="C:\Program Files\victoria-metrics\promscrape.yml" />

</service>

2. 安装 WinSW

按照 WinSW 文档安装 WinSW。

3. 在 PowerShell 中安装并启动服务

winsw install VictoriaMetrics.xml
Get-Service VictoriaMetrics | Start-Service

更多细节可以参考这个 issue。

FAQ

初学者应该选择哪种安装方式？

建议先选择单机二进制安装。它没有外部依赖，下载、解压、启动即可，最适合快速理解 VictoriaMetrics 的基本行为。

为什么历史数据会被自动删除？

通常是因为没有显式设置 -retentionPeriod。VictoriaMetrics 默认保留 1 个月数据，如果想保存更长时间，需要调整这个参数。

能不能完全用环境变量管理启动参数？

可以。启用 -envflag.enable 后，可以按 VictoriaMetrics 的规则用环境变量设置参数；也可以通过 %{ENV_VAR} 在命令行参数或配置文件中引用环境变量。

总结

VictoriaMetrics 的安装门槛很低，尤其是单机二进制版本，非常适合入门和测试。真正需要重点关注的是启动参数：数据目录由 -storageDataPath 控制，数据保留时间由 -retentionPeriod 控制。把这两个参数搞清楚，再根据部署环境选择 systemd、Docker、Kubernetes 或 Windows 服务即可。