VictoriaMetrics 完全指南 / 02 - 安装部署

02 · 安装部署

本章目标

掌握 VictoriaMetrics 单节点的多种安装方式
了解集群版的部署流程
使用 Docker 快速搭建开发环境
配置 systemd 管理服务
验证安装是否成功

2.1 版本选择指南

在开始安装前，先确定你需要哪个版本：

版本	适用场景	资源要求	下载文件
单节点版 (victoria-metrics)	中小规模监控、开发测试	最低 1 CPU / 1 GB RAM	`victoria-metrics-*-amd64-v1.106.0.tar.gz`
集群版 (vminsert + vmselect + vmstorage)	大规模、多租户	每组件最低 2 CPU / 4 GB RAM	三个独立二进制

决策流程图

你的监控数据规模？
│
├── < 100 万活跃时间序列
│   └── 单节点版 ✅（简单、高效）
│
├── 100 万 - 1000 万活跃时间序列
│   └── 单节点版（高配） 或 集群版 ✅
│
└── > 1000 万活跃时间序列
    └── 集群版 ✅（水平扩展）

2.2 单节点版安装

2.2.1 二进制安装（推荐）

# 1. 下载最新版本（以 v1.106.0 为例，请替换为实际版本）
VM_VERSION="v1.106.0"
cd /tmp

curl -LO "https://github.com/VictoriaMetrics/VictoriaMetrics/releases/download/${VM_VERSION}/victoria-metrics-linux-amd64-${VM_VERSION}.tar.gz"

# 2. 解压
tar xzf "victoria-metrics-linux-amd64-${VM_VERSION}.tar.gz"

# 3. 安装到 /usr/local/bin/
sudo mv victia-metrics-prod /usr/local/bin/victoria-metrics
sudo chmod +x /usr/local/bin/victoria-metrics

# 4. 验证
victoria-metrics --version

输出示例：

victoria-metrics-20250114-113803-tags-v1.106.0-0-g0b97eed387

2.2.2 创建系统用户和目录

# 创建专用用户
sudo useradd --system --shell /bin/false --home-dir /var/lib/victoria-metrics victoriametrics

# 创建数据目录
sudo mkdir -p /var/lib/victoria-metrics/data
sudo mkdir -p /etc/victoria-metrics
sudo mkdir -p /var/log/victoria-metrics

# 设置权限
sudo chown -R victoriametrics:victoriametrics /var/lib/victoria-metrics
sudo chown -R victoriametrics:victoriametrics /var/log/victoria-metrics

2.2.3 配置文件

创建 /etc/victoria-metrics/victoria-metrics.conf：

# ===========================
# VictoriaMetrics 单节点配置
# ===========================

# 数据存储路径
-storageDataPath=/var/lib/victoria-metrics/data

# HTTP 监听端口
-httpListenAddr=:8428

# 数据保留期（天数），默认 1 个月
-retentionPeriod=90d

# 内存限制（建议为物理内存的 60-70%）
-memory.allowedPercent=60

# 插入数据时的最大时间偏差容忍
-search.maxStalenessInterval=5m

# 日志级别 (INFO, WARN, ERROR, FATAL)
-loggerLevel=INFO

# 启用按日期分区（提升大保留期场景下的删除性能）
-disablePerDayIndex=false

# PromQL 兼容模式
-promscrape.config=/etc/victoria-metrics/prometheus.yml

2.2.4 systemd 服务单元

创建 /etc/systemd/system/victoria-metrics.service：

[Unit]
Description=VictoriaMetrics Monitor
Documentation=https://docs.victoriametrics.com/
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=victoriametrics
Group=victoriametrics
ExecStart=/usr/local/bin/victoria-metrics \
    -storageDataPath=/var/lib/victoria-metrics/data \
    -httpListenAddr=:8428 \
    -retentionPeriod=90d \
    -memory.allowedPercent=60 \
    -loggerLevel=INFO \
    -envflag.enable=true \
    -envflag.prefix=VM_
ExecStop=/bin/kill -SIGTERM $MAINPID
Restart=on-failure
RestartSec=10
LimitNOFILE=65536
LimitNPROC=32768

# 安全加固
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/lib/victoria-metrics /var/log/victoria-metrics

[Install]
WantedBy=multi-user.target

注意：-envflag.enable=true 允许通过环境变量传递配置（前缀 VM_），例如 VM_STORAGE_DATA_PATH=/data 等价于 -storageDataPath=/data。

# 启动服务
sudo systemctl daemon-reload
sudo systemctl enable victoria-metrics
sudo systemctl start victoria-metrics

# 检查状态
sudo systemctl status victoria-metrics

2.2.5 验证安装

# 健康检查
curl -s http://localhost:8428/health
# 预期输出: {"status":"ok"}

# 写入测试数据
curl -d 'test_metric{label="hello"} 42' 'http://localhost:8428/api/v1/import/prometheus'

# 查询测试数据
curl -s 'http://localhost:8428/api/v1/query?query=test_metric'

预期返回：

{
  "status": "success",
  "data": {
    "resultType": "vector",
    "result": [
      {
        "metric": {"__name__": "test_metric", "label": "hello"},
        "value": [1699000000, "42"]
      }
    ]
  }
}

2.3 Docker 安装

2.3.1 单容器快速启动

# 最简单的启动方式
docker run -d \
    --name victoria-metrics \
    -p 8428:8428 \
    -v vm-data:/victoria-metrics-data \
    victoriametrics/victoria-metrics:latest \
    -storageDataPath=/victoria-metrics-data \
    -retentionPeriod=90d

# 验证
curl http://localhost:8428/health

2.3.2 Docker Compose 完整环境

创建 docker-compose.yml：

version: '3.8'

services:
  # VictoriaMetrics 单节点
  victoria-metrics:
    image: victoriametrics/victoria-metrics:v1.106.0
    container_name: victoria-metrics
    restart: unless-stopped
    ports:
      - "8428:8428"
    volumes:
      - vm-data:/victoria-metrics-data
      - ./victoria-metrics.conf:/etc/victoria-metrics/victoria-metrics.conf
    command:
      - '-storageDataPath=/victoria-metrics-data'
      - '-retentionPeriod=90d'
      - '-httpListenAddr=:8428'
      - '-memory.allowedPercent=60'
      - '-promscrape.config=/etc/victoria-metrics/prometheus.yml'
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: '2'
    healthcheck:
      test: ["CMD", "/usr/bin/wget", "--spider", "-q", "http://localhost:8428/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 10s

  # vmagent - 轻量级数据采集器
  vmagent:
    image: victoriametrics/vmagent:v1.106.0
    container_name: vmagent
    restart: unless-stopped
    ports:
      - "8429:8429"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - vmagent-data:/vmagent-remotewrite-data
    command:
      - '-promscrape.config=/etc/prometheus/prometheus.yml'
      - '-remoteWrite.url=http://victoria-metrics:8428/api/v1/write'
      - '-remoteWrite.tmpDataPath=/vmagent-remotewrite-data'
    depends_on:
      victoria-metrics:
        condition: service_healthy

  # Grafana - 可视化面板
  grafana:
    image: grafana/grafana:11.0.0
    container_name: grafana
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - grafana-data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin123
      - GF_INSTALL_PLUGINS=victoriametrics-metrics-datasource
    depends_on:
      victoria-metrics:
        condition: service_healthy

volumes:
  vm-data:
    driver: local
  vmagent-data:
    driver: local
  grafana-data:
    driver: local

配套 prometheus.yml（Prometheus 采集配置）：

global:
  scrape_interval: 15s
  evaluation_interval: 15s

scrape_configs:
  # 采集 VictoriaMetrics 自身指标
  - job_name: 'victoria-metrics'
    static_configs:
      - targets: ['victoria-metrics:8428']

  # 采集 Node Exporter（如果有）
  - job_name: 'node-exporter'
    static_configs:
      - targets: ['node-exporter:9100']

  # 采集 vmagent 自身
  - job_name: 'vmagent'
    static_configs:
      - targets: ['vmagent:8429']

启动整个环境：

# 启动
docker compose up -d

# 查看状态
docker compose ps

# 查看日志
docker compose logs -f victoria-metrics

# 停止
docker compose down

# 停止并删除数据
docker compose down -v

2.4 集群版安装

集群版由三个组件组成：

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   vmstorage  │◀────│   vminsert   │     │   vmselect   │
│  数据存储层   │     │   写入层     │     │   查询层     │
└──────┬───────┘     └──────────────┘     └──────┬───────┘
       │                                         │
       └─────────────────────────────────────────┘
                    vmstorage API

2.4.1 下载集群组件

VM_VERSION="v1.106.0"

# 下载三个组件
for component in vminsert vmselect vmstorage; do
    curl -LO "https://github.com/VictoriaMetrics/VictoriaMetrics/releases/download/${VM_VERSION}/${component}-linux-amd64-${VM_VERSION}.tar.gz"
    tar xzf "${component}-linux-amd64-${VM_VERSION}.tar.gz"
    sudo mv "${component}-prod" "/usr/local/bin/${component}"
    sudo chmod +x "/usr/local/bin/${component}"
done

# 验证
vminsert --version
vmselect --version
vmstorage --version

2.4.2 启动集群组件

# 启动 vmstorage（存储层）
/usr/local/bin/vmstorage \
    -storageDataPath=/var/lib/victoria-metrics/vmstorage-data \
    -httpListenAddr=:8482 \
    -vminsertAddr=:8400 \
    -vmselectAddr=:8401 \
    -retentionPeriod=90d &

# 等待 vmstorage 启动
sleep 5

# 启动 vminsert（写入层）
/usr/local/bin/vminsert \
    -httpListenAddr=:8480 \
    -storageNode=localhost:8400 &

# 启动 vmselect（查询层）
/usr/local/bin/vmselect \
    -httpListenAddr=:8481 \
    -storageNode=localhost:8401 &

2.4.3 多节点集群部署示例

生产环境通常部署多个实例以实现高可用：

# vmstorage 节点 1
vmstorage -storageDataPath=/data/vmstorage1 \
    -httpListenAddr=:8482 -vminsertAddr=:8400 -vmselectAddr=:8401

# vmstorage 节点 2
vmstorage -storageDataPath=/data/vmstorage2 \
    -httpListenAddr=:8483 -vminsertAddr=:8402 -vmselectAddr=:8403

# vmstorage 节点 3
vmstorage -storageDataPath=/data/vmstorage3 \
    -httpListenAddr=:8484 -vminsertAddr=:8404 -vmselectAddr=:8405

# vminsert（连接所有 vmstorage）
vminsert -httpListenAddr=:8480 \
    -storageNode=localhost:8400,localhost:8402,localhost:8404

# vmselect（连接所有 vmstorage）
vmselect -httpListenAddr=:8481 \
    -storageNode=localhost:8401,localhost:8403,localhost:8405

2.5 包管理器安装

Ubuntu / Debian（APT）

# 下载 deb 包
VM_VERSION="v1.106.0"
curl -LO "https://github.com/VictoriaMetrics/VictoriaMetrics/releases/download/${VM_VERSION}/victoria-metrics-amd64-${VM_VERSION}.tar.gz"
tar xzf "victoria-metrics-amd64-${VM_VERSION}.tar.gz"

# 安装（deb 包目前社区提供）
sudo dpkg -i victoria-metrics_*.deb

RHEL / CentOS（RPM）

sudo rpm -ivh victoria-metrics-*.rpm

提示：官方也提供 Ansible Playbook 用于自动化部署。

2.6 ARM 架构安装

VictoriaMetrics 支持 ARM64 架构，适合在 AWS Graviton、Apple Silicon 等平台运行：

# ARM64 下载
VM_VERSION="v1.106.0"
curl -LO "https://github.com/VictoriaMetrics/VictoriaMetrics/releases/download/${VM_VERSION}/victoria-metrics-linux-arm64-${VM_VERSION}.tar.gz"
tar xzf "victoria-metrics-linux-arm64-${VM_VERSION}.tar.gz"
sudo mv victoria-metrics-prod /usr/local/bin/victoria-metrics

Docker 使用 ARM64 镜像：

docker pull victoriametrics/victoria-metrics:v1.106.0-arm64

2.7 验证清单

安装完成后，按以下清单逐项检查：

#	检查项	命令	预期结果
1	服务运行	`curl http://localhost:8428/health`	`{"status":"ok"}`
2	版本确认	`curl http://localhost:8428/api/v1/status/buildinfo`	返回版本号
3	写入测试	`curl -d 'test 1' http://localhost:8428/api/v1/import/prometheus`	204
4	查询测试	`curl 'http://localhost:8428/api/v1/query?query=test'`	有结果
5	UI 访问	浏览器打开 `http://localhost:8428/vmui`	看到 VMUI
6	指标暴露	`curl http://localhost:8428/metrics`	Prometheus 格式指标
7	日志正常	`journalctl -u victoria-metrics -n 50`	无 ERROR

2.8 常见安装问题

端口被占用

# 查看 8428 端口占用
sudo lsof -i :8428
# 或
sudo ss -tlnp | grep 8428

权限问题

# 确保数据目录权限正确
ls -la /var/lib/victoria-metrics/
# 应为 victoriametrics:victoriametrics

# SELinux 环境可能需要
sudo setsebool -P httpd_can_network_connect on

systemd 启动失败

# 查看详细日志
journalctl -u victoria-metrics -n 100 --no-pager

# 常见原因：
# 1. 配置参数拼写错误
# 2. 数据目录不存在或权限不足
# 3. 端口已被占用

本章小结

安装方式	适用场景	复杂度	生产可用
二进制 + systemd	生产环境	中	✅
Docker	开发测试	低	⚠️ 需配置持久化
Docker Compose	完整监控栈	低	✅
集群二进制	大规模生产	高	✅
包管理器	快速体验	低	⚠️ 可能版本滞后