企业官网建设流程全解析

OneUptime 服务器 / VM 监控实战：基础设施 Agent 部署、指标采集与阈值告警全指南

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

服务器与虚拟机（VM）监控是保障基础设施健康的第一道防线。OneUptime 通过一个轻量级、基于 Go 编写的基础设施 Agent，将服务器上的系统指标持续上报到平台，帮助你实时掌握服务器的可用性、CPU / 内存 / 磁盘使用率、运行中的进程状态，并在资源阈值被突破前发出告警。本篇指南以官方文档（fr/monitor/server-monitor.md，英文版见 en/monitor/server-monitor.md）为主线，并结合仓库源码逐层拆解：读完你既能独立完成从创建监控、安装 Agent 到配置告警判定条件的完整闭环，也能理解 Agent 每 30 秒采集与上报的底层实现。

服务器 / VM 监控概述

服务器 / VM 监控通过在目标服务器上安装一个轻量级 Agent 来工作。该 Agent 负责采集系统指标并上报给 OneUptime，从而帮助你实现：

• 监控服务器的可用性与正常运行时间（uptime）；
• 跟踪 CPU、内存与磁盘的使用情况；
• 监控服务器上正在运行的进程；
• 基于资源使用率阈值设置告警；
• 在基础设施问题影响业务服务之前提前发现风险。

从架构上看，这是一套"探针外置"模型：Agent 主动采集、平台负责存储与判定。Agent 侧的核心实现在 agents/InfrastructureAgent 目录，服务端接收与在线状态判定的实现在packages/App/FeatureSet/Telemetry与packages/App/FeatureSet/Workers，后文会逐一对应。

创建服务器 / VM 监控

在 OneUptime Dashboard 中创建服务器监控的完整步骤如下：

1. 进入仪表盘中的监控（Monitors）页面；
2. 点击创建监控（Create Monitor）；
3. 选择服务器 / VM（Server / VM）作为监控类型；
4. 系统会为该监控生成一个密钥（Secret Key）——后续配置 Agent 时必须使用；
5. 按照安装指引在服务器上完成 Agent 的配置与启动。

其中第 4 步生成的密钥是 Agent 与平台之间的身份凭证。服务端通过它完成两件事：一是启动前的密钥校验，Agent 启动时调用GET /server-monitor/secret-key/verify/:secretkey验证密钥是否有效（对应源码 ServerMonitor.ts，校验逻辑见 agent.go）；二是指标上报时通过POST /server-monitor/response/ingest/:secretkey定位到具体监控（见 ServerMonitor.ts）。因此密钥一旦泄露，攻击者即可伪造该服务器的指标数据，务必妥善保管。

基础设施 Agent：基于 Go 的轻量守护进程

OneUptime 基础设施 Agent 是一个基于 Go 的轻量守护进程（daemon），每 30 秒采集一次系统指标并上报给 OneUptime，支持 Linux、macOS 与 Windows 三大平台。

从源码看，30 秒的采集周期由gocron调度器实现，启动时会立即执行一次采集任务，此后按固定周期循环：

// agents/InfrastructureAgent/agent.go job, err := scheduler.NewJob(gocron.DurationJob(30*time.Second), gocron.NewTask(collectMetricsJob, ag.SecretKey, ag.OneUptimeURL, ag.ProxyURL))

每次采集任务会依次获取内存、CPU、磁盘、网络、负载（load average）、主机与进程数据，并封装为ServerMonitorReport上报（见 agent.go 与 server_monitor_report.go）。上报数据中同时携带RequestReceivedAt时间戳，服务端正是依据该时间戳判断服务器是否"在线"（详见文末"在线状态判定"一节）。

Agent 的安装与配置还支持以下环境特性（来自 config.go）：

• 配置文件默认保存在系统目录：Unix 下为/etc/oneuptime-infrastructure-agent/config.json，Windows 下为%PROGRAMDATA%\oneuptime-infrastructure-agent\config.json；
• 若系统目录不可写（例如非特权用户），会自动回退到$HOME/.oneuptime-infrastructure-agent/；
• 可通过环境变量ONEUPTIME_AGENT_CONFIG_PATH显式指定配置文件路径，便于容器化等场景。

Linux / macOS 安装

官方安装脚本位于仓库 packages/App/FeatureSet/Docs/Static/scripts/infrastructure-agent/install.sh。该脚本会自动完成平台与架构检测（支持amd64、arm64、arm，覆盖 Linux / macOS / FreeBSD / OpenBSD 等系统），从发布源拉取最新版本并解压到指定目录（默认$HOME/bin，可用-b参数覆盖），随后将二进制加入 shell 的PATH。安装完成后再依次执行配置与启动：

# 安装 Agent（脚本会检测 OS 与架构并安装最新版本） sudo bash install.sh # 配置 Agent：填入监控密钥与 OneUptime 实例地址 sudo oneuptime-infrastructure-agent configure --secret-key=YOUR_SECRET_KEY --oneuptime-url=https://oneuptime.com # 启动 Agent sudo oneuptime-infrastructure-agent start

命令中的YOUR_SECRET_KEY需要替换为监控设置中显示的密钥；如果你自托管 OneUptime，请将https://oneuptime.com替换为你自己的实例 URL。configure命令在保存配置的同时还会把 Agent 注册为系统服务（service.New），源码见 main.go。

Windows 安装

Windows 上通过官方发布包安装：

1. 下载最新版 Agent（选择对应架构的 zip 包）：
   • oneuptime-infrastructure-agent_windows_amd64.zip—— 适用于 x64 系统；
   • oneuptime-infrastructure-agent_windows_arm64.zip—— 适用于 ARM64 系统；
2. 解压 zip 包；
3. 以管理员身份打开命令提示符，执行：

# 配置 Agent oneuptime-infrastructure-agent configure --secret-key=YOUR_SECRET_KEY --oneuptime-url=https://oneuptime.com # 启动 Agent oneuptime-infrastructure-agent start

代理（Proxy）支持

如果服务器需要通过 HTTP 代理访问外网，可以在configure时通过--proxy-url参数指定代理地址：

sudo oneuptime-infrastructure-agent configure --secret-key=YOUR_SECRET_KEY --oneuptime-url=https://oneuptime.com --proxy-url=http://proxy.example.com:8080

源码层面，代理会在发起请求前被解析并装配到 HTTP 客户端传输层上（http.Transport{Proxy: http.ProxyURL(proxyURL)}），密钥校验与指标上报两个请求都会使用该代理，见 agent.go。需要注意：代理配置是全局生效的，请确保代理本身允许访问你的 OneUptime 实例地址。

Agent 命令速查

Agent 提供以下管理命令（由 main.go 实现，run为服务内部命令）：

其中logs -n 50表示显示最近 50 行日志（默认 100 行），logs -f进入实时跟踪模式（见 main.go）。在排障时，logs -n 50也恰好覆盖约 25 分钟（每 30 秒一行）的日志窗口。

需要提醒的是：Agent 在日志与错误信息中会对密钥做脱敏处理（MaskSecret/RedactSecret），避免密钥随日志泄露，对应实现见 agent.go 与 utils/redact.go。

Agent 采集的指标详解

Agent 采集的指标分为四类，与文档中的列表一一对应，同时我补充了源码中可验证的实现细节：

CPU

• CPU 使用率（%）—— CPU 整体使用百分比；
• CPU 核心数—— CPU 逻辑核心数量。

实现上，采集逻辑会先获取每个核心的使用率再求平均（cpu.go），因此"使用率"代表所有核心的平均负载。除此之外，Agent 还会计算 CPU 时间分解（用户态、系统态、空闲、I/O 等待、Steal、Nice、IRQ、SoftIRQ 的百分比），其中的I/O 等待（iowait）正是监控判定标准中"CPU IO Wait"数据来源（cpu.go）。

内存

• 总内存（Total Memory）—— 可用内存总量；
• 已用内存（Used Memory）—— 当前已使用内存；
• 空闲内存（Free Memory）—— 当前空闲内存；
• 内存使用率（%）—— 内存使用百分比。

采集自 gopsutil 的VirtualMemory()，同时还会附带Available（可用内存）、Buffers、Cached等字段（memory.go）。此外 Agent 还会采集Swap 交换分区的总量、已用、空闲与使用率（memory.go），为"Swap 使用率"判定项提供数据。

磁盘

对每个已挂载的磁盘 / 卷：

• 磁盘总空间（Total Disk Space）—— 磁盘总容量；
• 已用空间（Used Disk Space）—— 当前已使用空间；
• 可用空间（Free Disk Space）—— 当前可用空间；
• 磁盘使用率（%）—— 磁盘使用百分比；
• 磁盘路径（Disk Path）—— 磁盘挂载路径。

磁盘采集按分区逐一进行（disk.go）。值得关注的两个工程细节：一是分区枚举设置了 20 秒超时（diskPartitionTimeout = 20 * time.Second），避免 Windows 上无响应的网络驱动器卡死整个采集任务（disk.go）；二是会同步采集每个分区的 I/O 计数器（读写字节数、读写次数、I/O 时间），以便按设备维度分析磁盘 I/O 压力（disk.go）。

进程

• 进程名（Process Name）—— 正在运行的进程名称；
• 进程 ID（PID）—— 进程标识符；
• 进程命令（Process Command）—— 启动该进程的完整命令行。

进程列表通过 gopsutil 的process.Processes()获取（procs.go），并对每个进程尽力补充 CPU 使用率、内存占用（RSS 字节数与百分比）、运行状态、线程数、创建时间与所属用户等附加字段——这些字段采集失败时自动回退为零值，不影响主流程。

补充：负载与网络

除了文档列出的四类指标，Agent 还会采集 1 / 5 / 15 分钟系统负载平均值（load.Avg()，见 load.go）以及网络指标（utils/network.go）。负载平均值对应判定标准中的"Load Average (1/5/15 minute)"检查项。

监控判定标准（Criteria）

你可以为服务器监控配置一组判定标准（criteria），用于确定服务器在何时被判定为在线（online）、降级（degraded）或离线（offline）。判定项的类型定义在 CriteriaFilter.ts 的CheckOn枚举中。

可用的检查类型

磁盘类检查需要额外指定diskPath（如/），对应数据结构中的ServerMonitorOptions.diskPath字段（见 CriteriaFilter.ts）。

过滤条件（Filter Conditions）

对于数值型指标（CPU、内存、磁盘、Swap、I/O 等待、负载均值）：

• 大于（Greater Than）—— 数值超过某阈值；
• 小于（Less Than）—— 数值低于某阈值；
• 大于等于（Greater Than or Equal To）—— 数值达到或超过某阈值；
• 小于等于（Less Than or Equal To）—— 数值处于或低于某阈值。

对于进程类检查：

• 正在运行（Is Executing）—— 进程当前正在运行；
• 未在运行（Is Not Executing）—— 进程当前未运行。

对应的比较操作符枚举定义见 CriteriaFilter.ts 的FilterType。

按时间段评估（Evaluate Over Time）

"在一段时间内评估此条件（Evaluate this criteria over a period of time）"是判定表单中的一个独立复选框，而非过滤条件。开启后，平台不再对比"最新一次检查的瞬时值"，而是对比一段时间窗口内的聚合值，聚合方式在Evaluate下拉框中选择：

• 平均值（Average）
• 总和（Sum）
• 最大值（Maximum Value）
• 最小值（Minimum Value）
• 所有值（All Values）
• 任意值（Any Value）

聚合窗口由"最近（分钟）"（For the last (in minutes)）设置，可选窗口从 2 分钟到 60 分钟（EvaluateOverTimeMinutes枚举，见 CriteriaFilter.ts）。

几个需要理解的语义细节（对应 CriteriaFilter.ts）：

• All Values只有在窗口内确实被数据完整覆盖时才会匹配。一个刚创建的监控、或检查记录已中断的监控，没有足够的历史数据来支撑"最近 N 分钟"的判定，此时该条件会等待，而不是用仅有的单次读数去匹配。
• Any Value用于"只要单次检查一越界就立刻告诉我"的场景，它会立即触发。
• If No Data（无数据时）控制窗口无法支撑判定时如何处理：
  • Ignore（忽略，默认）—— 该条件不匹配。适用于常规阈值告警；
  • Trigger（触发）—— 把数据缺失本身当作问题。适用于心跳型检查——"沉默本身就是故障"；
  • Treat As Zero（按零处理）—— 将整个窗口视为单个零值。适用于计数器类指标——"没有事件"确实意味着零。

需要说明的是，文档法语版中关于时间段评估的描述较为简略，上述 All Values / Any Value 语义与 If No Data 策略的完整说明以英文版文档 en/monitor/server-monitor.md 为准，并已在 CriteriaFilter.ts 的NoDataPolicy枚举中得到印证。

判定示例

以下示例覆盖了最常见的几种场景，可直接在判定表单中按字段逐项填写：

示例一：Agent 停止上报时标记服务器为离线

• 检查类型（Check On）：在线（Is Online）
• 过滤条件（Filter Condition）：False

示例二：CPU 使用率超过 90% 时告警

• 检查类型：CPU 使用率（%）
• 过滤条件：大于
• 数值：90

示例三：磁盘使用率超过 85% 时告警

• 检查类型：磁盘使用率（%）
• 磁盘路径：/
• 过滤条件：大于
• 数值：85

示例四：内存使用率超过 80% 时告警

• 检查类型：内存使用率（%）
• 过滤条件：大于
• 数值：80

示例五：关键进程停止时告警

• 检查类型：服务器进程名
• 过滤条件：未在运行（Is Not Executing）
• 数值：nginx

排障指南（Troubleshooting）

症状一：Agent 不上报数据

按以下顺序逐项排查：

• 确认 Agent 正在运行：sudo oneuptime-infrastructure-agent status；
• 查看 Agent 日志：sudo oneuptime-infrastructure-agent logs -n 50；
• 确认密钥（Secret Key）填写正确；
• 确认服务器能够访问你的 OneUptime 实例 URL；
• 检查防火墙规则是否放行了出站 HTTPS 连接。

症状二：Agent 资源占用过高

Agent 被设计为轻量级。如果观察到资源占用异常升高：

• 重启 Agent：sudo oneuptime-infrastructure-agent restart；
• 查看 Agent 日志，排查是否有持续报错（例如磁盘采集异常）。

值得一提的细节是：磁盘采集模块内置了"问题日志去重"机制（diskProblemLog），同一问题每 10 分钟最多重复记录一次，避免某个不可读分区让日志每 30 秒刷屏（见 disk.go）；而磁盘分区枚举的超时上限为 20 秒，低于 30 秒采集周期，因此单个无响应驱动器不会拖垮整个上报任务。

症状三：代理相关故障

• 确认代理 URL 与端口配置正确；
• 确保代理允许访问你的 OneUptime 实例；
• 重新配置代理：sudo oneuptime-infrastructure-agent configure --proxy-url=http://proxy:port --secret-key=YOUR_KEY --oneuptime-url=YOUR_URL。

服务端侧原理：数据接收与在线状态判定

理解了 Agent 侧之后，再看服务端如何协同（这部分是对文档内容由源码补充的深度延伸）：

1. 密钥校验：Agent 每次启动时调用GET /server-monitor/secret-key/verify/:secretkey，服务端查询匹配serverMonitorSecretKey且类型为 Server 的监控，若不存在则返回错误（ServerMonitor.ts）；
2. 指标接收：Agent 调用POST /server-monitor/response/ingest/:secretkey上报指标，服务端立即返回成功响应，并将数据投递到TelemetryQueueService异步队列处理（ServerMonitor.ts），后续由 ProcessServerMonitorIngest.ts 消费；
3. 在线状态判定：Worker 中的 CheckOnlineStatus.ts 每分钟执行一次"扫描"，凡是serverMonitorRequestReceivedAt距今超过 3 分钟仍未收到新上报的服务器监控，就会被判定为离线——这就是文档中"在线（Is Online）"心跳判定的服务端依据。

最佳实践

1. 设定有意义的阈值—— 降级与离线判定条件应贴合服务器正常工作区间，避免把偶发抖动误判为故障；
2. 监控关键进程—— 利用进程监控确保 Web 服务器、数据库等核心服务始终存活，进程异常停止时第一时间告警；
3. 主动监控磁盘使用率—— 磁盘空间耗尽往往引发应用级联故障，务必在磁盘将满之前就设置告警（例如使用示例三的 85% 阈值，或结合业务情况调低）；
4. 善用"按时间段评估"—— 对 CPU 这类可能瞬时尖峰的指标，开启时间段评估并使用聚合方式（如平均值、任意值），可有效避免误报；
5. 保持 Agent 更新—— 定期升级基础设施 Agent，及时获得性能改进与问题修复（仓库内可关注 agents/InfrastructureAgent 目录的变更）。

以上五条同时被官方文档作为推荐基线（见 fr/monitor/server-monitor.md）。将 Agent 部署、判定条件与上述实践结合使用，即可为服务器与虚拟机建立一套覆盖"可用性—资源—进程"三层的自动化监控体系。

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