OneUptime Server / VM 监控实战指南：从 Infrastructure Agent 安装到资源阈值告警

OneUptime Server / VM 监控实战指南从 Infrastructure Agent 安装到资源阈值告警【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime本篇指南以 OneUptime 的 Server / VM 监控功能为主体讲解如何通过一个轻量的 Go 基础设施代理Infrastructure Agent采集服务器 CPU、内存、磁盘、负载与进程数据并将其上报给 OneUptime 平台进行在线判定与阈值告警。读完本文你将掌握在 Linux、macOS、Windows 上安装与配置代理的完整流程、代理支持的 CLI 命令与底层上报机制以及如何配置「在线 / 降级 / 离线」的监控条件含时间窗口聚合与无数据处理策略并结合仓库源码理解每一个判定背后的实现原理。概览Server / VM 监控的架构与能力Server 和 VM 监控允许你通过在被监控主机上安装一个轻量代理Infrastructure Agent来监控服务器、虚拟机及其他基础设施的健康状况与性能。该代理会把系统指标上报给 OneUptime从而让你能够监控服务器的在线状态uptime与可用性跟踪 CPU、内存和磁盘的使用情况监控正在运行的进程基于资源利用率阈值设置告警在问题影响业务服务之前发现基础设施隐患从源码结构看这条数据链路分为两段采集端是 InfrastructureAgentGo 编写的守护进程它按固定周期每 30 秒采集指标并通过 HTTP 推送到平台判定端是 OneUptime 服务端的监控条件评估器ServerMonitorCriteria.ts它把上报的数据与用户配置的阈值条件做比较决定监控对象处于哪种状态。创建 Server Monitor在开始安装代理之前需要先在 OneUptime Dashboard 中创建一个 Server 类型的监控器进入 OneUptime Dashboard 的Monitors监控页面点击Create Monitor创建监控选择Server / VM作为监控类型系统会为该监控器生成一个Secret Key密钥——后续配置代理时需要用到它按照安装说明在被监控服务器上部署代理这个 Secret Key 是代理与平台之间唯一的身份凭证在代理启动时会先被校验。参见 agent.go 中checkIfSecretKeyIsValid的实现代理启动后会向/server-monitor/secret-key/verify/{secretKey}发起一次 GET 请求校验失败会直接退出os.Exit(1)并提示检查网络、OneUptime URL 与代理地址。安装 Infrastructure AgentOneUptime Infrastructure Agent 是一个轻量、开源的 Go 守护进程它采集系统指标并每 30 秒上报一次给 OneUptime。这个采集周期定义在 agent.go 中——通过gocron.DurationJob(30*time.Second)创建定时任务并且在服务启动时立即执行一次mainJob.RunNow()因此配置完成后无需等待 30 秒即可看到第一批数据。它支持 Linux、macOS 和 Windows。Linux / macOS# 安装代理 curl -sSL https://oneuptime.com/docs/static/scripts/infrastructure-agent/install.sh | sudo bash # 配置代理 sudo oneuptime-infrastructure-agent configure --secret-keyYOUR_SECRET_KEY --oneuptime-urlhttps://oneuptime.com # 启动代理 sudo oneuptime-infrastructure-agent start将YOUR_SECRET_KEY替换为监控器设置页面中显示的密钥如果是自托管 OneUptime将https://oneuptime.com替换为你自己的实例 URL。仓库中保存有对应的安装脚本 install.sh它会自动检测操作系统与 CPU 架构x86_64→amd64、aarch64/arm64→arm64、arm*→arm从发布产物下载对应平台的二进制并解压到$HOME/bin同时把二进制目录写入.bashrc、.zshrc、.profile等 shell 配置。脚本还支持-b参数自定义安装目录、-d参数开启调试输出。Windows从发布页面下载最新代理oneuptime-infrastructure-agent_windows_amd64.zipx64 系统oneuptime-infrastructure-agent_windows_arm64.zipARM64 系统解压 zip 文件以管理员身份打开命令提示符并运行# 配置代理 oneuptime-infrastructure-agent configure --secret-keyYOUR_SECRET_KEY --oneuptime-urlhttps://oneuptime.com # 启动代理 oneuptime-infrastructure-agent startWindows 安装包同样提供了 MSI 构建脚本见 InfrastructureAgent/build-msi.sh 与 windows/ 下的 WiX 模板。代理配置文件的落盘位置configure命令会把配置写入 JSON 文件。从 config.go 的configPath()实现可以看到完整的路径解析逻辑若设置了环境变量ONEUPTIME_AGENT_CONFIG_PATH则优先使用该路径Unix 系统默认写入/etc/oneuptime-infrastructure-agent/config.jsonWindows 默认写入%PROGRAMDATA%\oneuptime-infrastructure-agent\config.jsonPROGRAMDATA为空时回退到C:\ProgramData当系统目录不可用或不可写时例如非特权用户本地测试回退到$HOME/.oneuptime-infrastructure-agent/。配置文件内容为 JSON 格式字段定义在 config.go 的ConfigFile结构体中secret_key、oneuptime_url、proxy_url、proxy_port、proxy_username、proxy_password。因此除了命令行参数你同样可以手动编辑该 JSON 文件后再执行start。代理支持Proxy如果服务器通过代理访问互联网可以在配置代理时指定代理地址sudo oneuptime-infrastructure-agent configure --secret-keyYOUR_SECRET_KEY --oneuptime-urlhttps://oneuptime.com --proxy-urlhttp://proxy.example.com:8080代理配置在运行时会被实际使用从 agent.go 可以看到当proxyUrl非空时HTTP 客户端会使用http.Transport{Proxy: http.ProxyURL(...)}构造校验密钥与上报指标的请求都会走该代理。Agent 命令详解Infrastructure Agent 支持以下命令命令入口见 main.go命令说明configure用密钥和 OneUptime URL 配置代理并注册为系统服务start启动代理服务stop停止代理服务restart重启代理服务status显示当前服务运行状态logs查看代理日志-n指定行数-f实时跟踪uninstall卸载代理服务同时删除配置文件help显示全部命令帮助其中logs命令的参数细节可以从源码确认默认显示最近 100 行-n默认值-f实现类似tail -f的实时输出见 main.go。日志文件路径由utils.GetLogPath()决定日志中还包含安全处理——密钥绝不会以明文出现在日志中MaskSecret只会输出[REDACTED] (N characters)这样的占位描述且上报出错时的 URL 错误信息也会通过RedactSecret把密钥路径段替换为[REDACTED]参见 redact.go。采集的指标代理每 30 秒采集一次完整指标集打包成ServerMonitorReport见 server_monitor_report.go通过POST /server-monitor/response/ingest/{secretKey}上报见 agent.go。上报内容包含basicInfrastructureMetrics基础指标、processes进程列表、hostname主机名与requestReceivedAt本次上报时间。CPU来自 cpu_metrics.go 与 utils/cpu.goCPU Usage Percent—— 整体 CPU 利用率百分比所有核心平均CPU Cores—— CPU 核心数另有每个核心的单独使用率perCorePercent以及 user / system / idle / iowait / steal / nice / irq / softirq 等 CPU 时间占比内存来自 memory_metrics.go 与 utils/memory.go基于 gopsutil 的mem.VirtualMemory()Total Memory—— 总内存Used Memory—— 已用内存Free Memory—— 空闲内存Memory Usage Percent—— 内存利用率百分比附带 available可用、buffers、cached以及 swap 的 total / used / free / swapPercentUsed磁盘来自 disk_metrics.go 与 utils/disk.go针对每个挂载磁盘/卷Total Disk Space—— 磁盘总容量Used Disk Space—— 已用空间Free Disk Space—— 可用空间Disk Usage Percent—— 磁盘利用率百分比Disk Path—— 磁盘挂载路径附带 device设备名、fstype文件系统类型以及读写字节数、读写次数、I/O 时间等计数器从 utils/disk.go 的实现可以看到磁盘采集对异常情况做了较完善的兜底分区枚举带 20 秒超时防止 Windows 上无响应的网络驱动器阻塞整个采集任务单个盘读不了如 BitLocker 锁定的卷、RAW 分区、不可达的网络盘不会拖垮整批采集而是记录警告后继续上报其余可读分区磁盘 I/O 计数器在不支持的平台如无 cgo 的 macOS 构建会降级为空字段而不是报错。进程来自 server_process.go 与 utils/procs.goProcess Name—— 运行中的进程名Process ID (PID)—— 进程标识符Process Command—— 启动进程的完整命令行附带每个进程的 CPU 百分比、内存占用字节与百分比、状态、线程数、创建时间与用户名其他指标除文档列出的四类指标外源码中代理还会采集见 infrastructure_metrics.goLoad Metricsload_metrics.go1 / 5 / 15 分钟负载均值Network Metricsnetwork_metrics.go每个网卡的收发字节数、包数、错误与丢包数以及总收发量与 TCP 连接数established / listen / totalHost Metricshost_metrics.go操作系统平台与版本、内核版本与架构、主机运行时长uptime、启动时间、虚拟化类型与角色、进程总数等监控条件Criteria配置你可以配置监控条件来决定服务器何时被判定为「在线 / 降级 / 离线」。判定逻辑集中在服务端 ServerMonitorCriteria.ts而所有可用条件类型与比较运算符统一定义在 CriteriaFilter.ts 的CheckOn与FilterType枚举中。可用条件类型条件类型说明Is Online服务器代理是否在正常上报基于心跳CPU Usage (in %)当前 CPU 利用率百分比Memory Usage (in %)当前内存利用率百分比Disk Usage (in %)当前磁盘利用率百分比针对指定磁盘路径Swap Usage (in %)当前 swap 利用率百分比CPU IO Wait (in %)CPU 等待 I/O 的时间占比Load Average (1 minute)最近 1 分钟系统负载均值Load Average (5 minute)最近 5 分钟系统负载均值Load Average (15 minute)最近 15 分钟系统负载均值Server Process Name检查是否存在指定名称的进程Server Process Command检查是否存在指定命令的进程Server Process PID检查是否存在指定 PID 的进程数值型条件的比较运算符对于数值型指标CPU、内存、磁盘、swap、CPU IO wait、负载均值Greater Than—— 数值超过阈值Less Than—— 数值低于阈值Greater Than or Equal To—— 数值大于等于阈值Less Than or Equal To—— 数值小于等于阈值时间窗口聚合Evaluate over a period of timeEvaluate this criteria over a period of time是条件表单上的一个独立复选框而不是比较运算符。开启后将不再用「最新一次检查的瞬时值」做比较而是对时间窗口内For the last (in minutes)设定可选 2、3、5、10、15、20、30、45、60 分钟见 CriteriaFilter.ts 的EvaluateOverTimeMinutes的数据做聚合聚合方式在Evaluate下选择Average平均值、Sum求和、Maximum Value最大值、Minimum Value最小值、All Values所有值、Any Value任意值。这里有两个值得注意的行为细节源码注释中已有明确说明见 CriteriaFilter.tsAll Values只有在窗口真正被数据完整覆盖后才会匹配。一个刚创建的监控器或者上报被中断的监控器还没有足够的历史数据来对最近 N 分钟下结论此时条件会等待而不是拿仅有的一个读数去匹配。Any Value则是任一单次检查突破阈值就立刻告警的设置仍然会立即触发。布尔型序列如 Is Online在开启时间窗口聚合时仪表盘只会提供 All Values 与 Any Value 两种聚合方式因为 0/1 序列的平均值、求和等结果没有语义意义见 CriteriaFilter.ts。无数据处理If No DataIf No Data控制当时间窗口无法支撑该条件时窗口内没有数据或监控器运行时间还不够覆盖整个窗口如何处理Ignore默认—— 条件不匹配。适用于常规阈值告警。Trigger—— 把缺失数据本身当作问题。适用于心跳型检查——「沉默」本身就是故障。Treat As Zero—— 把整个窗口当作一个 0 参与比较。适用于计数器类指标——「没有事件」确实就意味着零。这三种策略对应 CriteriaFilter.ts 中的NoDataPolicy枚举。需要特别说明的是Is Online例外服务端判定中时间窗口无数据时 Is Online 条件不会被 NoDataPolicy 拦截而是直接基于代理最后一次上报的时间差来判断——因为对服务器监控而言数据缺失本身就是离线信号见 ServerMonitorCriteria.ts。进程类条件的比较运算符对于进程检查Is Executing—— 进程当前正在运行Is Not Executing—— 进程当前未运行示例条件配置代理停止上报时标记服务器离线Filter Type: Is OnlineFilter Condition: False从实现看服务端会计算上次上报时间与当前时间的分钟差当差值达到offlineIfNotCheckedInMinutes默认 3 分钟若开启了时间窗口聚合则取窗口时长时该条件才会判定为离线否则视为在线见 ServerMonitorCriteria.ts。因此代理每 30 秒上报一次、默认 3 分钟未上报即离线的判定节奏天然可以容忍个别的网络抖动。CPU 使用率超过 90% 时告警Filter Type: CPU Usage (in %)Filter Condition: Greater ThanValue: 90磁盘使用率超过 85% 时告警Filter Type: Disk Usage (in %)Disk Path:/Filter Condition: Greater ThanValue: 85磁盘路径在判定时会做归一化处理统一小写、把\归一为/、去掉末尾/根路径/保持原样并在上报的磁盘列表中精确匹配该路径见 ServerMonitorCriteria.ts。此外若 Disk Path 填写*则表示所有磁盘只要任意一个磁盘突破阈值即告警并且每个完整挂载点会分别触发各自的告警见 ServerMonitorCriteria.ts。内存使用率超过 80% 时告警Filter Type: Memory Usage (in %)Filter Condition: Greater ThanValue: 80关键进程停止运行时告警Filter Type: Server Process NameFilter Condition: Is Not ExecutingValue:nginx进程名匹配是不区分大小写的精确匹配两端去空格后转小写比对进程命令与 PID 的检查同理见 ServerMonitorCriteria.ts。故障排查代理不上报确认代理正在运行sudo oneuptime-infrastructure-agent status查看代理日志sudo oneuptime-infrastructure-agent logs -n 50确认 Secret Key 正确无误可在监控器设置页找到确认服务器可以访问你的 OneUptime 实例 URL检查防火墙是否放行出站 HTTPS 连接注意代理启动时就会做一次密钥校验校验失败会直接退出——所以如果status显示服务未运行可以先检查日志中是否有Secret key is invalid之类的错误代理资源占用过高代理被设计为轻量级。如果发现资源占用偏高重启代理sudo oneuptime-infrastructure-agent restart检查代理日志中的错误信息代理配置问题确认代理 URL 和端口正确确认代理允许连接到你的 OneUptime 实例使用以下命令重新配置sudo oneuptime-infrastructure-agent configure --proxy-urlhttp://proxy:port --secret-keyYOUR_KEY --oneuptime-urlYOUR_URL最佳实践设置有意义的阈值—— 降级与离线的判定条件应匹配服务器正常运行时的波动范围避免把正常的短期波动误判为故障监控关键进程—— 使用进程监控确保 Web 服务器、数据库等核心服务始终在运行主动监控磁盘使用率—— 磁盘写满会引发连锁的应用故障应在磁盘接近写满之前就设置告警开启时间窗口聚合—— 对 CPU 这类可能瞬时飙高的指标建议勾选Evaluate this criteria over a period of time并使用基于时间窗口的聚合避免误报保持代理更新—— 定期升级 Infrastructure Agent以获得最新的功能改进与问题修复相关资源监控条件类型与运算符定义CriteriaFilter.ts服务端判定实现ServerMonitorCriteria.ts上报数据结构ServerMonitorResponse.ts代理主逻辑与上报周期agent.go代理配置与存储config.go代理命令入口main.go代理安装脚本install.sh【免费下载链接】oneuptimeComplete open-source monitoring and observability platform.项目地址: https://gitcode.com/GitHub_Trending/on/oneuptime创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考