KuvaszUptime 介绍与选型指南

目标：面向准备自建网站/服务可用性监控（uptime monitoring）的读者，讲清 KuvaszUptime（项目名 Kuvasz，官网品牌 Kuvasz Uptime）是什么、能监控什么、不能做什么，并与 Uptime Kuma、Gatus 两个同类开源产品及商业托管服务 Uptime Robot 做量化对比，帮助你在 30 分钟内完成选型判断。本文为认知篇，所有版本、许可、特性、社区数据均溯源自官方渠道（来源与查询日期随文标注，查询日期统一为 2026-11-01），部署、配置与 API 的逐条实测见本系列其余三篇。

一、环境信息

本文是认知与选型篇，未做本地部署实验，以下为撰写时核实的信息来源与版本基线（查询日期：2026-11-01）：

• 软件名称：Kuvasz（官网品牌 Kuvasz Uptime，专栏与本文统一使用 KuvaszUptime 指代该实体；仓库 kuvasz-uptime/kuvasz，作者 Ádám Kobor / adamkobor）
• 最新稳定版：4.6.0（发布日期 2026-10-25；来源：官网 Changelog https://kuvasz-uptime.dev/changelog/，条目 "4.6.0 2026-10-25"）
• 开发语言与技术栈：Kotlin 2.4.0 + Micronaut 5 框架（来源：官网 Changelog 3.11.0 条目原文 "The project has been upgraded to use Micronaut 5 and Kotlin 2.4.0 under the hood"），Web UI 为现代单页前端
• 许可证：AGPL-3.0（来源：官网首页 "Kuvasz is licensed under AGPL-3.0, it's free and it always will be" 及仓库 LICENSE 链接 https://github.com/kuvasz-uptime/kuvasz/blob/main/LICENSE）
• 官网与文档站：https://kuvasz-uptime.dev；在线 Demo：https://demo.kuvasz-uptime.dev（演示账号 demo / secureDemoPassword，来源：Docker Hub 仓库页说明）；API 文档：https://api-docs.kuvasz-uptime.dev
• 分发形态：单一 Docker 镜像 kuvaszmonitoring/kuvasz（Docker Hub 官方仓库），另有官方 Helm Chart（GitHub OCI Registry）；不提供裸机二进制/系统软件包分发
• 外部依赖：PostgreSQL（官方最低实测版本 14，支持 alpine 发行版；来源：官网 Deployment 页 "The minimum, tested version of PostgreSQL is 14"）
• 对比对象（同为查询日期 2026-11-01）：Uptime Kuma（louislam/uptime-kuma，版本线 2.5.8，来源：Docker Hub 仓库页 Recent tags）、Gatus（TwiN/gatus，版本线 v5.37.0，来源：FreeBSD ports 更新记录与 pkg.go.dev 版本列表）、Uptime Robot（商业 SaaS，来源：官网对比表 https://kuvasz-uptime.dev/#kuvasz-vs-uptimerobot）

二、软件概述

Kuvasz 是一个开源、自托管的 uptime & SSL 监控服务，官方首页的定位原话是 "The developer- and cloud-friendly uptime monitor"（来源：kuvasz-uptime.dev 首页，查询日期 2026-11-01）。它回答的问题很朴素：我的一组网站、API、端口、证书、定时任务是否正常，异常时如何第一时间通知我，以及如何向我的用户/团队展示服务状态。

项目名字来自匈牙利古代护卫犬品种 Kuvasz（发音 [ˈkuvɒs]）——一只替你看家护院的狗，正好对应「替你盯住服务可用性」的产品角色（来源：官网首页 "Where does the name come from?" 小节）。

它有几个鲜明的产品特征，使其在同类中辨识度很高：

1. 面向开发者与云环境：配置完全声明式（YAML + 环境变量，两者可自由组合），监控器可以用一个 YAML 文件以 IaC（基础设施即代码）方式管理，支持 YAML 导入/恢复备份；同时提供完整 REST API 与 Web UI，三种管理面可混用。
2. 云原生发行形态：整站就是一个 Docker 镜像，外部只依赖一个 PostgreSQL 数据库；官方同时提供 Helm Chart 用于 Kubernetes 部署。4.6.0 版本官方基准结论是「1,000 个监控器以内默认配置无压力，5,000 个监控器 1.5 GB 内存绰绰有余」（来源：官网 Changelog 4.6.0 与 Sizing Guide）。
3. 监控类型覆盖面在开源同类中最宽之一：HTTP(S)、SSL 证书、Push 心跳（cron 监控）、ICMP Ping、TCP 端口、DNS 记录、Docker 容器七类，且全部纳入同一套事故（incident）、状态页、维护窗口、通知与指标导出体系。
4. 内置 MCP 服务器：可以把监控数据与管理操作作为工具暴露给 AI 助手（Claude、Cursor 等 MCP 客户端），用自然语言查询监控状态、查看事故、创建/启停监控器——这在同类开源监控产品中属于少见的前瞻特性。

💡 技术拓展：自托管监控服务的开源许可证常见三种——MIT/Apache-2.0（最宽松，可闭源商用衍生）、AGPL-3.0（网络服务条款：如果你修改它并对外提供网络服务，必须开源修改后的源码）、EPL/EUPL 等（弱 Copyleft）。对比参考：Uptime Kuma 为 MIT，Gatus 为 Apache-2.0，GoatCounter 为 EUPL-1.2 修改版。Kuvasz 选择 AGPL-3.0 意味着：直接自用、内部部署完全自由；但若对其源码做了修改并对外提供服务，需公开修改部分源码。本文/本系列按原样部署使用，不涉及修改义务。

三、核心架构

Kuvasz 是一个单体（monolithic）Web 应用 + 调度器的组合，架构简单清晰，这正是它「稳定高性能」的基础。以下结构依据官网文档（Deployment、Configuration reference、Sizing、Features 各页，查询日期 2026-11-01）整理：

┌─────────────────────────────────────────────────────────────┐
│                    kuvasz 容器（单镜像）                       │
│                                                             │
│  ┌───────────┐   ┌──────────────────────────────────────┐   │
│  │ 调度器     │──▶│ 检查器（按类型）                       │   │
│  │ (虚拟线程) │   │ HTTP / SSL / Push / ICMP / TCP /     │   │
│  └───────────┘   │ DNS / Docker                         │   │
│                  └──────────────┬───────────────────────┘   │
│        ▲                        │ 检查结果                    │
│        │ 计划窗口/连通性闸门       ▼                          │
│  ┌─────┴───────┐        ┌──────────────┐    ┌───────────┐   │
│  │ 维护窗口 +   │        │ PostgreSQL   │◀──│ REST API   │   │
│  │ 连通性检查   │        │ (外部依赖)    │    │ /api/v2|v3 │   │
│  └─────────────┘        └──────┬───────┘    └─────┬─────┘   │
│                                │ 事件/事故          │         │
│                  ┌─────────────▼───────┐   ┌──────▼──────┐  │
│                  │ 通知集成（Email/Slack │   │ Web UI /    │  │
│                  │ /Telegram/…/Webhook）│   │ 状态页 / MCP │  │
│                  └─────────────────────┘   └─────────────┘  │
│                                │                             │
│                  ┌─────────────▼──────────┐                  │
│                  │ 指标导出器 Prometheus /  │                  │
│                  │ OTLP                    │                  │
│                  └────────────────────────┘                  │
└─────────────────────────────────────────────────────────────┘

核心组件与数据流：

1. 调度与执行层：每个监控器按各自 uptimeCheckInterval（最短可到 5 秒）被调度执行；4.6.0 起定时检查固定运行在 JVM 虚拟线程上（原 USE_VIRTUAL_THREAD_SCHEDULING 开关已废弃并忽略，来源：Changelog 4.6.0 Improvements）。SSL 证书检查默认每日一次。
2. 事件与事故层：检查结果产生 uptime 事件与 SSL 事件；连续失败达到阈值（failureCountThreshold）形成事故（incident），事故带时间线、可加备注（Investigating/Identified/Resolved，4.5.0 引入），恢复时自动闭环。
3. 存储层：唯一的持久化依赖是 PostgreSQL。检查历史、响应时间、事件、事故、状态页配置全部存库；官方提供自定义数据保留（数据清理）能力。4.6.0 针对大历史量做了索引优化：官方测试 1,000 监控器 + 一个月历史时，监控详情页快约 4 倍（TCP/ICMP/DNS/Docker 类约 20 倍），状态页 30 天均值查询从最高 6 秒降到约 0.2 秒（来源：Changelog 4.6.0）。
4. 告警与集成层：通知渠道按「集成（integration）」配置，支持 Email、Slack（Webhook 与 Bot 两种）、Discord、Telegram、Microsoft Teams、Apprise、Pushover、PagerDuty 与自定义 Webhook；可全局生效或按监控器绑定，Webhook URL 支持模板变量（3.11.0 引入）。
5. 对外接口层：Web UI（含可品牌化公共/私有状态页）、REST API（/api/v2 全量接口 + 4.6.0 新增带分页/排序/搜索的 /api/v3，v2 全量列表接口标记废弃但继续工作）、Prometheus 与 OTLP 指标导出器、内置 MCP 服务器（独立 ADMIN_MCP_API_KEY 保护 /mcp 端点）。
6. 配置层：YAML 文件（容器内挂载于 /config/kuvasz.yml）与环境变量两种形态等价可组合；例外是集成、监控器、状态页、维护窗口等列表型结构只能写在 YAML 里。

部署拓扑上它就是「1 个应用容器 + 1 个 PostgreSQL」的最小两件套，官方 Compose 文件即此形态；Kubernetes 下用官方 Helm Chart（可自带或由 Chart 拉起 PostgreSQL）。没有开箱的分布式/多副本模式——多位置监控的官方做法是在多个位置各部署一套 Kuvasz（来源：官网对比表脚注 1）。

四、功能特性

以下特性清单逐项核对自官网 Features 各小节与 Docker Hub 仓库页（查询日期 2026-11-01）：

一句话总结：「检查什么」很全（七类），「查到之后怎么办」也很全（事故→通知→状态页→指标→AI），「怎么管理」三条路（UI/API/YAML）。

五、快速开始（最小可用示例）

本节为官方快速启动路径的溯源摘录（来源：官网 Deployment 页 "Quick start with Docker Compose"，查询日期 2026-11-01）；本系列 B 篇已在本机实测复现，逐条命令与真实回显见《KuvaszUptime 4.6.0 Docker Compose 部署指南》。

官方 TL;DR 共三步：

1. 准备 Docker 与 Docker Compose 环境，建目录并准备空的 kuvasz.yml 配置文件；
2. 下载官方示例 docker-compose.yml（官方源：https://raw.githubusercontent.com/kuvasz-uptime/kuvasz/refs/heads/main/docker-examples/docker-compose.yml），该文件内含两个服务：PostgreSQL（pgautoupgrade/pgautoupgrade:18-alpine）与 Kuvasz（kuvaszmonitoring/kuvasz），需把示例中的默认凭据（YourSuperSecretUsername / YourSuperSecretPassword / YourSuperSecretDbPassword）改成自己的；
3. docker compose up -d 启动，访问 http://<主机>:8080 用设置的凭据登录。

⚠️ 注意：官方要求 ADMIN_PASSWORD 至少 12 个字符且不得与 ADMIN_USER 相同；ADMIN_API_KEY（可选，启用 API Key 认证）至少 16 个字符。若想彻底免认证可设 ENABLE_AUTH=false。B 篇实测时曾用 8 位弱口令启动并复现了启动失败与报错回显，排障过程见该篇「常见问题」。

启动后的第一个健康检查入口是无需认证的 GET /api/v2/health，返回 {"status": "UP"}（HTTP 非 2xx 即不健康），可直接用作编排系统的就绪探针。登录后即可在 Web UI 创建第一个监控器，或按官方推荐走 API/YAML 管理。

六、适用场景与限制

适合用的场景（依据上文特性矩阵归纳）：

1. 个人/中小团队的「全栈可用性监控」：网站、API、证书、端口、cron、DNS、Docker 容器一个服务全覆盖，替代多个单一用途的小工具；
2. 需要对外/对内状态页：可品牌化、公共/私有分级、事故时间线自动同步；
3. 配置即代码的工作流：监控器随代码库管理，YAML 导入/恢复即备份，适配 GitOps 习惯；
4. 已有 Prometheus/OTLP 观测栈：把可用性指标并网而不是再开一个告警孤岛；
5. 中等偏大规模：官方基准 5,000 监控器 / 1.5 GB 内存可跑，分页与索引优化到位（4.6.0 专项）；
6. AI 运维场景尝鲜：MCP 服务器让助手直接操作监控系统。

限制与不适用（依据官方文档与对比表明确写明的内容）：

1. 必须接受 AGPL-3.0：二开并对外提供服务需开源修改；对许可证敏感的商业场景需法务评估；
2. 无开箱多位置监控：可多地部署多套，但没有内置「按位置区分视角」的能力；域名到期（domain expiration）监控官方对比表标注为不支持（Uptime Robot Solo 有）；
3. 单实例架构：无内置集群/高可用模式，监控服务自身是单点（可用数据库备份 + 快速重建缓解）；
4. 强依赖 PostgreSQL：不支持 SQLite/MySQL，不能「零依赖」跑起来（Uptime Kuma 默认 SQLite 可零外部依赖）；
5. 只发 Docker 镜像：无裸机二进制/系统包，离线内网环境需自备镜像与镜像仓库；
6. 性能测试参照官方基准：本系列未做大规模复测，Sizing Guide 数据为官方实验室结果。

七、同类选型对比

选型对比取三个可对齐的参照物：Uptime Kuma（最流行的开源自托管监控，Node.js）、Gatus（Go 编写的开发者向健康看板）、Uptime Robot（老牌商业 SaaS，作为托管基准线）。下表数据来源：Kuvasz 行来自官网与 Docker Hub 仓库页；Uptime Kuma 行来自其 Docker Hub 仓库页（版本 2.5.8，更新于 2026-10-30 前后）与 GitHub 仓库 README；Gatus 行来自其 Docker Hub 仓库页与 GitHub README、FreeBSD ports 版本记录；Uptime Robot 列来自官网对比表。全部查询日期为 2026-11-01，社区热度数据会随时间变化，引用时请注意时效。

表后解读（如何选型）：

• 如果你要「零外部依赖、五分钟跑起来」：选 Uptime Kuma。SQLite 默认存储让它不需要任何外部数据库，社区与生态最大（1 亿+ 拉取量），UI 最讨喜；代价是 JVM 之外的 Node 栈在大规模下的资源与性能需要自己评估，声明式/IaC 能力弱。
• 如果你要「极轻量、条件表达式的机器式健康检查」：选 Gatus。25 MB 镜像、Go 单文件、YAML 条件断言是它的灵魂，Kubernetes 场景常见；代价是没有成型的多类型监控矩阵（如 SSL 独立监控、Docker 容器监控、Push 心跳的组合深度不及 Kuvasz），状态页品牌化能力有限。
• 如果你要「七类监控全家桶 + 状态页 + IaC + 完整 API + 指标导出 + AI 接口」且规模在千级监控器：选 Kuvasz。它是三者中唯一把「监控类型覆盖、事故管理、品牌化状态页、声明式配置、REST API、Prometheus/OTLP、OIDC、MCP」做成一个自洽整体的；代价是必须养一个 PostgreSQL、接受 AGPL-3.0、镜像比 Gatus 大。
• 如果你完全不想运维：Uptime Robot 这类 SaaS 仍然合理，但免费档 5 分钟间隔/50 监控器/1 个状态页的约束，对认真做可用性的团队偏紧，且数据不出自己服务器这一条自托管方案天然占优。

与站内已发布的同类自托管服务对照：GoatCounter（arp242/goatcounter）属于「网站访问统计（web analytics）」而非可用性监控，两者经常被一起讨论但解决的问题不同——前者统计「谁在访问」，后者盯「服务还活着吗」，细节见 《GoatCounter 介绍与选型指南》。

八、参考链接

1. 官网首页（定位、特性总览、Uptime Robot 对比表）：https://kuvasz-uptime.dev/（查询日期 2026-11-01）
2. 官网 Changelog（4.6.0 / 4.5.0 版本线与特性依据）：https://kuvasz-uptime.dev/changelog/（查询日期 2026-11-01）
3. 官网 Deployment 部署文档（Compose 快启、健康探针、凭据要求）：https://kuvasz-uptime.dev/setup/installation/（查询日期 2026-11-01）
4. 官网 Configuration reference（YAML/ENV 双通道配置）：https://kuvasz-uptime.dev/setup/configuration/（查询日期 2026-11-01）
5. 官网 Sizing Guide（官方基准与资源建议）：https://kuvasz-uptime.dev/setup/sizing/（经 Changelog 4.6.0 引用）
6. 官方 API 文档（OpenAPI）：https://api-docs.kuvasz-uptime.dev/（查询日期 2026-11-01）
7. GitHub 仓库：https://github.com/kuvasz-uptime/kuvasz；Roadmap：https://github.com/orgs/kuvasz-uptime/projects/2/views/1（查询日期 2026-11-01）
8. Docker Hub 官方镜像仓库（拉取量/镜像体积/标签）：https://hub.docker.com/r/kuvaszmonitoring/kuvasz（查询日期 2026-11-01）
9. 在线 Demo（demo / secureDemoPassword）：https://demo.kuvasz-uptime.dev（来源：Docker Hub 仓库页，查询日期 2026-11-01）
10. 对比对象仓库与镜像页：Uptime Kuma https://github.com/louislam/uptime-kuma 与 https://hub.docker.com/r/louislam/uptime-kuma；Gatus https://github.com/TwiN/gatus 与 https://hub.docker.com/r/twinproduction/gatus、pkg.go.dev 版本页 https://pkg.go.dev/github.com/TwiN/gatus/v5（查询日期 2026-11-01）
11. 站内同类阅读：《GoatCounter 介绍与选型指南》