Upright 快速上手教程：5 分钟创建并运行你的第一个 HTTP 健康检查探针

Upright 是一个开源的自托管合成监控引擎（Synthetic Monitoring），支持 HTTP 健康检查探针、SMTP、Traceroute 和 Playwright 浏览器探针，并可通过 Prometheus 输出指标、用 AlertManager 告警。这篇快速上手教程带你从零安装 Upright，创建并运行你的第一个 HTTP 健康检查探针，最终在面板上查看 UP/DOWN 状态与 30 天在线率。

Upright 是什么 🌐

简单来说，Upright 就是「部署在你自己服务器上的站点监控」：

• 多地域站点：把 Upright 部署到多个城市的 VPS 上，从不同地理位置探测你的服务，世界地图总览一目了然
• 5 种内置探针：HTTP、MCP、Playwright（浏览器）、SMTP、Traceroute，另支持自定义
• 可观测性：Prometheus 指标、OpenTelemetry 链路追踪、AlertManager 告警
• 自带 Web 面板：探针状态矩阵、30 天 Uptime 历史、公开状态页，无需额外前端

下图就是安装完成后的站点总览面板，地图上的每个标记点就是一个监控站点：

安装前置条件 ⚙️

资源	最低要求	建议
CPU	2 vCPU	2 vCPU
内存	2 GB	4 GB
磁盘	25 GB	50 GB

软件要求：Ubuntu 24.04+ / Debian 12+（任意支持 Docker 的 Linux）、Docker 24.0+、Ruby 3.4+、Rails 8.0+。

💡 本地开发只需 Ruby 环境，生产环境通过 Kamal 以 Docker 容器方式部署。

一键安装步骤 🚀

Upright 是一个 Rails 引擎，设计为运行在独立 Rails 应用中。安装只需 4 条命令：

rails new my-upright --database=sqlite3 --skip-test
cd my-upright
bundle add upright
bin/rails generate upright:install
bin/rails db:prepare

生成器会一次性创建你需要的全部配置文件，包括：

• probes/ 目录 —— 存放所有探针定义（本教程的主角）
• config/recurring.yml —— 探针调度任务
• config/initializers/upright.rb —— 引擎配置
• config/sites.yml —— 监控站点定义
• config/prometheus/prometheus.yml 与 config/alertmanager/alertmanager.yml —— 指标与告警

启动服务（记得设置管理密码）：

ADMIN_PASSWORD=upright bin/dev

浏览器访问 http://app.my-upright.localhost:3000，使用用户名 admin、密码 upright 登录。

📝 Upright 采用子域名路由：app 子域名是管理后台，而 nyc、lon 等站点子域名则展示对应位置探针的结果。

创建第一个 HTTP 探针 ✍️

HTTP 探针全部定义在 probes/http_probes.yml 中。安装后该文件已带有一个示例，打开它并改成你要监控的地址：

# probes/http_probes.yml
- name: Main Website
  url: https://example.com
  expected_status: 200

- name: API Health
  url: https://api.example.com/health
  expected_status: 200
  alert_severity: critical

字段说明（完整注释见 http_probes.yml 模板）：

字段	必填	说明
name	✅	探针唯一名称，会显示在面板中
url	✅	要探测的 URL
expected_status	❌	期望的状态码，默认接受 200–399
alert_severity	❌	失败时的告警级别：medium / high（默认）/ critical
basic_auth_credentials	❌	Basic Auth 凭据（存于 Rails credentials 的键名）
proxy	❌	代理设置（存于 Rails credentials 的键名）

实现逻辑非常直白：探针发起 GET 请求，只要响应状态码落在期望范围内即视为 UP，否则为 DOWN，源码在 http_probe.rb。每次探测还会把 curl 详细日志和响应体（≤1MB）保存为附件，方便事后排障。

理解探针调度 ⏱️

探针不是手动触发的，而是由 Solid Queue 的周期性任务驱动，定义在 config/recurring.yml：

development:
  http_probes:
    schedule: every minute
    command: "Upright::Probes::HTTPProbe.check_and_record_all_later"

production:
  http_probes:
    schedule: "*/30 * * * * *"   # 每 30 秒一轮
    command: "Upright::Probes::HTTPProbe.check_and_record_all_later"

开发环境每分钟探测一次，生产环境默认每 30 秒一次。修改调度后重启服务即可生效，无需其他配置。

查看探针结果 📊

等上一两个调度周期，回到面板顶部导航的 PROBE STATUS，就能看到你的探针在每个站点的实时状态——绿色 UP 表示健康，红色 DOWN 表示失败：

运行一段时间后再访问 UPTIME 页面，每个探针会生成过去 30 天的状态条和在线率百分比，绿色代表全天在线，红色代表整天不可用：

点击任意探针名称还能下钻到历史结果列表，查看每次探测的耗时、状态码和响应体附件。

下一步：接入 Prometheus 告警 🔔

Upright 通过 Puma 插件在 9394 端口暴露指标（upright_probe_up、upright_probe_duration_seconds、upright_http_response_status 等），Prometheus 抓取配置和 ProbeDown 告警规则已由生成器预置在 config/prometheus/prometheus.yml 和 config/prometheus/rules/upright.rules.yml 中：探针持续 5 分钟 DOWN 即触发告警，severity 由你配置探针时的 alert_severity 决定，最终由 AlertManager 负责通知你。

常见问题 FAQ ❓

Q：登录失败怎么办？ 必须设置 ADMIN_PASSWORD 环境变量，缺少时登录会直接失败（fail closed）。本地测试可用 ADMIN_PASSWORD=upright bin/dev。

Q：如何多地域监控？ 在 config/sites.yml 中定义多个站点（代码、城市、geohash），把 Upright 用 Kamal 部署到多台 VPS，每个站点通过 SITE_SUBDOMAIN 环境变量标识自己，并为每个站点配置子域名 DNS。

Q：只监控一个站点可以吗？ 完全可以，sites.yml 中保留一个站点即可，单机也能享受全部功能。

总结 🎉

回顾一下这条完整路径：安装 Upright → 编辑 probes/http_probes.yml → 启动服务 → 查看状态与 Uptime。你已经拥有了一个属于自己的、可多地域扩展的 HTTP 健康检查监控系统。接下来不妨再试试 SMTP 探针、Traceroute 探针，或用一条命令生成 Playwright 浏览器探针，监控真实的用户登录流程。