OneUptime 手动监控器（Manual Monitor）完全指南：用 API 与状态页驱动的纯人工监控方案

OneUptime 手动监控器（Manual Monitor）完全指南：用 API 与状态页驱动的纯人工监控方案

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime

手动监控器（Manual Monitor）是 OneUptime 中唯一一种完全不做自动化检查的监控器类型：它没有探针（Probe）、没有监控间隔、没有自动判定的告警条件，监控器的状态完全由你在仪表盘或通过 API 手动设定。本文以 OneUptime 官方文档（法文版原文）为核心脉络，并结合仓库源码深入讲解手动监控器的类型定义、创建步骤、状态更新方式、事件与告警联动，以及它与其它监控器类型在底层实现上的本质差异。读完本文，你将掌握如何在 OneUptime 中用最少的配置接入外部监控工具、托管无法自动探测的服务，并在状态页上对外呈现受控的状态信息。

概述：手动监控器是什么

OneUptime 官方文档对手动监控器的定义非常明确：手动监控允许你创建状态完全由人工或通过 API 管理的监控器，OneUptime 不执行任何自动化检查——你直接控制监控器的状态。

在源码层面，这一设计由 MonitorType 枚举 落地：Manual = "Manual"是枚举中的一个独立值，与Website、API、Ping、Host等类型平级，但在整个平台的调度、探测、评估体系中它都被特殊对待。MonitorTypeHelper中提供了一系列类型能力判断函数，手动监控器在每一条判断路径上都返回"否"或"无"，这正是文档所说"不进行任何自动化检查"的代码级印证（详见下文"与其他监控器的底层差异"一节）。

简单来说，手动监控器就是一个由你亲手维护的占位符（placeholder）。官方文档列出了它最典型的四类用途：

• 与外部监控工具集成，由外部工具通过 OneUptime API 回写状态；
• 追踪无法被自动化监控的服务或系统；
• 为没有自动化健康检查的组件管理事件（Incident）；
• 代表你以人工方式跟踪状态的第三方依赖。

在源码中的定位：从枚举到类型能力

要理解手动监控器，先看它在代码里的"身份"。在 MonitorType.ts 中，MonitorTypeHelper把全部监控器类型按用途分类展示（getMonitorTypeCategories），MonitorType.Manual被单独归入"Other"（其他）分类：

{ label: "Other", monitorTypes: [MonitorType.Manual], },

同文件还给出了Manual类型在监控器创建选择器中的展示信息：

• 标题：Manual
• 描述："No automatic checks. You set the status yourself, or from an external tool."（无自动检查。你自己或由外部工具设定状态。）
• 图标：IconProp.EmptyCircle（空心圆）
• 搜索关键词：static、external、integration、placeholder、no check、third party

这些关键词意味着用户在创建监控器时，即使只记得"external"、"placeholder"这类描述性词汇，也能在类型选择器中检索到手动监控器。这与文档"第三方依赖""外部工具"的定位完全一致。

在数据模型层面，监控器的类型与当前状态分别存储于 Monitor 数据库模型：monitorType字段（L877）记录监控器类型，currentMonitorStatusId与currentMonitorStatus（L908-L925、L970）记录当前状态。手动监控器的monitorType固定为Manual，其currentMonitorStatus只会在你主动更新时改变。

创建手动监控器

在 OneUptime 仪表盘中创建手动监控器非常简单，官方文档给出了四步操作：

1. 进入 OneUptime 仪表盘的监控器（Monitors）页面；
2. 点击创建监控器（Create Monitor）；
3. 在监控器类型中选择手动（Manual）；
4. 为监控器输入名称和描述。

由于手动监控器没有探测步骤（probe step）与判定条件（criteria），创建流程到此即告完成——不需要配置监控间隔、不需要选择探针、不需要编写任何检查规则。这是它与其它所有监控器类型在创建体验上最显著的差异。

工作原理：没有间隔、没有探针、没有自动评估

官方文档用一句话概括了手动监控器的工作方式：

手动监控器没有监控间隔、没有探针、也没有自动化的条件评估。监控器的状态会一直保持为你设定的值，直到你再次修改它。

这一点在源码中有非常直接的印证。MonitorTypeHelper提供了以下能力判断方法（MonitorType.ts）：

也就是说，从调度器、探针分发到告警评估、图表渲染，手动监控器在所有自动化路径上都被显式排除。它唯一的"数据源"就是人工或 API 写入的状态值。这正是它适合作为占位符的根本原因：平台不会用任何自动化任务去干扰你设定的状态。

更新状态：仪表盘与 API 双通道

手动监控器没有自动状态流转，因此"更新状态"是使用它的核心操作。官方文档明确给出了两种方式：

• 仪表盘（Dashboard）——直接在 OneUptime 仪表盘中修改监控器的状态；
• API——通过 OneUptime API 以编程方式更新监控器状态。

仪表盘方式适合人工值守场景：当你在状态页上要对外展示某个组件的状态时，直接点击修改即可。API 方式则适合自动化场景：外部监控工具、脚本或 CI/CD 流水线可以在检测到问题时调用 OneUptime API 回写状态。结合源码中的 ApiKey / ApiKeyPermission 模型 可以推断，平台提供了基于 API Key 的鉴权机制供外部系统调用，实际使用时请以当前 OneUptime 实例的 API 文档为准获取具体的端点与参数。

无论是哪种方式，最终落地的都是对 Monitor 模型 中currentMonitorStatus字段的写入，状态一旦更新便会立即反映在监控器列表与关联的状态页组件上。

事件与告警：手动监控器同样参与

"没有自动检查"并不等于"不能产生告警"。官方文档强调：你可以像对待其它任何监控器类型一样，对手动监控器创建事件（Incident）和告警（Alert）。这带来了三个典型能力：

• 跟踪外部监控服务的停机时间——外部工具通过 API 把状态置为异常，你再针对该监控器创建事件；
• 在问题被人工上报时手动创建事件——例如业务侧反馈某个流程不可用；
• 在状态页（Status Page）上使用手动监控器向用户传达状态——这是它作为"状态页占位符"的核心用法。

从数据模型看，事件（Incident）与监控器之间存在标准的关联关系，监控器可以触发或挂载事件与告警，这一机制对手动监控器同样生效，因此你完全可以把状态页上的"第三方依赖""线下业务流程"等组件建模为手动监控器，并为其配置事件与告警流程，而不需要这些组件真的具备可探测的端点。

适用场景一览

官方文档用一张表格总结了手动监控器最典型的五类使用场景：

这张表也呼应了前文源码中的描述与关键词：external、integration、placeholder、third party——手动监控器正是为"我无法自动探测，但需要在平台上统一呈现和告警"的场景而设计。

手动监控器与其他监控器类型的底层差异

为了更清楚地理解"手动"到底意味着什么，可以把MonitorTypeHelper中的类型能力判断汇总成一张对比表。以最常见的Website（网站）监控器为参照：

由此可见，手动监控器在平台内部是被"完整剥离"了自动化能力的监控器：它不参与探针调度、不评估告警条件、不生成监控曲线，只保留监控器的身份、状态字段、事件告警关联与状态页展示能力。它像是一个"空壳"监控器，把状态的判定权完全交还给你。

计费与配额：手动监控器免费且不限量

对于关心成本与配额的用户，源码中还透露了一个重要信息。在 MonitorType.ts 中，isBilledAsActiveMonitor()方法的注释明确指出：

该方法镜像了服务端实际的计费逻辑——ActiveMonitoringMeteredPlan只统计类型不是 Manual 的监控器。手动监控器免费且不限量。

public static isBilledAsActiveMonitor(monitorType: MonitorType): boolean { return !this.isManualMonitor(monitorType); }

也就是说，无论你在状态页上挂多少个手动占位符组件，都不会计入活跃监控（Active Monitoring）的计费额度，也不会触发免费套餐的用量告警。对于需要大量在状态页上呈现外部依赖、线下设施组件的团队来说，这是一个非常实用的特性。

小结

手动监控器是 OneUptime 监控体系中的一个"特例存在"：它没有探针、没有间隔、没有条件评估，状态完全由人工或 API 驱动，同时保留事件、告警与状态页集成能力，并且免费、不限量。从源码角度看，MonitorType 枚举与 MonitorTypeHelper 通过一系列能力判断方法把 Manual 从自动化链路中完整剥离，只留下"状态容器"的职责；从使用角度看，它最适合作为外部依赖、物理设施、业务流程与状态页占位符的建模载体。

如果你正在接入外部监控工具，或在状态页上需要呈现平台之外管理的组件，不妨从创建一个手动监控器开始——它没有自动检查带来的噪音，只有你想要的确定性。

【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime