Kuvasz 监控系统安装与部署指南

前言

Kuvasz 是一款基于 Docker 的现代化监控系统，采用 PostgreSQL 作为数据存储后端。本文将详细介绍 Kuvasz 的安装部署流程，帮助您快速搭建自己的监控平台。

系统要求

在开始安装前，请确保您已满足以下基本要求：

1. Docker 环境：Kuvasz 以 Docker 镜像方式分发，需要 Docker 运行环境
2. PostgreSQL 数据库：最低支持版本为 12，Alpine 发行版也可支持
3. YAML 配置文件：用于配置监控项和集成功能

数据库准备

Kuvasz 需要 PostgreSQL 数据库支持，您有两种选择：

1. 使用现有 PostgreSQL 实例：确保版本不低于 12
2. 使用 Docker Compose 新建实例：推荐初次使用者采用此方式

配置文件准备

Kuvasz 的核心配置通过 YAML 文件实现，建议在部署前创建基础配置文件：

# 初始可为空文件，后续逐步添加配置项

Docker Compose 部署方案

方案一：包含 PostgreSQL 的完整部署

version: '3'

services:
  kuvasz-db:
    image: postgres:17-alpine
    container_name: kuvaszdb
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: your_secure_password
      TZ: 'Asia/Shanghai'  # 建议设置为本地时区
    ports:
      - "5432:5432"
    volumes:
      - ./pgdata:/var/lib/postgresql/data

  kuvasz:
    image: kuvaszmonitoring/kuvasz:latest
    container_name: kuvasz
    mem_limit: 384M  # 最小内存限制
    ports:
      - "8080:8080"
    environment:
      TZ: 'Asia/Shanghai'
      DATABASE_HOST: kuvaszdb
      DATABASE_USER: postgres
      DATABASE_PASSWORD: your_secure_password
      ADMIN_USER: admin  # 自定义管理员用户名
      ADMIN_PASSWORD: secure_password  # 自定义管理员密码
      ADMIN_API_KEY: your_api_key  # 自定义API密钥
    volumes:
      - ./kuvasz.yml:/config/kuvasz.yml
    depends_on:
      - kuvasz-db

方案二：使用现有 PostgreSQL 的部署

version: '3'

services:
  kuvasz:
    image: kuvaszmonitoring/kuvasz:latest
    container_name: kuvasz
    mem_limit: 384M
    ports:
      - "8080:8080"
    environment:
      TZ: 'Asia/Shanghai'
      DATABASE_HOST: your_db_host
      DATABASE_PORT: 5432
      DATABASE_NAME: your_db_name
      DATABASE_USER: your_db_user
      DATABASE_PASSWORD: your_db_password
      ADMIN_USER: admin
      ADMIN_PASSWORD: secure_password
      ADMIN_API_KEY: your_api_key
    volumes:
      - ./kuvasz.yml:/config/kuvasz.yml

禁用认证（开发环境适用）

如需禁用认证功能，可添加环境变量：

ENABLE_AUTH: 'false'

部署后操作

1. 访问 Web 界面：部署成功后，通过 http://服务器IP:8080 访问
2. 登录系统：使用配置的管理员凭据登录
3. 健康检查：通过 /api/v1/health 端点验证服务状态

监控项配置

Kuvasz 提供三种监控项管理方式：

1. Web 界面：可视化操作，适合手动管理
2. REST API：适合自动化场景
3. YAML 配置：适合基础设施即代码(IaC)实践

示例：配置 Slack 通知

integrations:
  slack:
    - name: production-alerts
      webhook-url: 'https://hooks.slack.com/services/...'
      global: true  # 设为全局默认通知渠道

高级部署场景

对于 Kubernetes 或 Swarm 等容器编排系统，部署时需注意：

1. 正确设置环境变量
2. 挂载配置文件卷
3. 配置健康检查探针

版本升级注意事项

从 v1 升级到 v2 时需注意：

1. 不再提供 GraalVM 原生镜像
2. PostgreSQL 最低版本要求提升至 12
3. REST API 进行了版本化调整
4. 集成配置方式改为纯 YAML
5. 认证机制简化

建议升级前备份数据库，并参考官方升级文档进行迁移。

最佳实践建议

1. 生产环境务必使用强密码
2. 定期备份 PostgreSQL 数据
3. 为不同环境使用不同的配置文件
4. 监控系统本身设置告警规则
5. 合理设置内存限制防止OOM

通过以上步骤，您应该已经成功部署了 Kuvasz 监控系统。如需进一步了解具体配置细节，可参考官方配置文档。