📊 监控

在用户发现问题之前，先知道哪里坏了。

OPL 数据空间提供健康检查和模型接口，足够让你很容易接上可用性监控、模型连通性检查以及端到端响应验证。无论你是单实例还是多节点部署，这些检查都能帮你确认服务在线、模型可达、推理真实可用。

---

为什么要监控？

更快发现故障

如果每 60 秒做一次健康检查，你最多一分钟就能知道服务不可用，而不是等用户来报错。

验证模型侧连通性

OPL 数据空间进程存活，不代表上游模型服务也正常。检查 /api/models 可以及时发现“前端活着、模型挂了”的空档。

端到端确认

最深的一层检查会发出真实 prompt 并校验返回值。只要这一层通过，就能说明 API、后端、模型提供方和推理链路整体都在工作。

---

核心能力

✅ 健康检查端点	无认证 /health，服务可用时返回 200
🔗 模型连接检查	有认证 /api/models，确认模型提供方可达
🤖 深度健康检查	发送真实 chat completion 并验证结果
🐻 Uptime Kuma 配方	针对不同监控层级的现成配置思路

---

Level 1：基础健康检查

/health 公开可访问，不需要认证。服务运行正常时会返回 200 OK。

curl http://your-open-webui-instance:8080/health

它能验证 Web 服务可用、应用初始化完成，以及基础数据库连通性正常。

Uptime Kuma 配置

1. 新建 HTTP(s) monitor
2. URL: http://your-open-webui-instance:8080/health
3. Interval: 60 seconds
4. Retries: 3

---

Level 2：模型连通性检查

/api/models 需要认证，用于确认 OPL 数据空间能否连接模型提供方并列出可用模型。

curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://your-open-webui-instance:8080/api/models

你需要先准备一个 API 密钥。配置方式见 API 密钥。

专用监控账号

建议创建一个非管理员用户，例如 monitoring-bot，专门生成 API 密钥给监控系统使用。这样即使 key 泄漏，影响范围也更小。

Uptime Kuma 配置

1. Monitor Type: HTTP(s) - JSON Query
2. URL: http://your-open-webui-instance:8080/api/models
3. Method: GET
4. Header: Authorization: Bearer YOUR_API_KEY
5. JSON Query: $count(data[*])>0
6. Expected Value: true
7. Interval: 300 seconds

进阶 JSONata 查询

目标	查询
至少存在一个 Ollama 模型	$count(data[owned_by='ollama'])>0
某个模型必须存在	$exists(data[id='gpt-4o'])
多个模型同时存在	$count(data[id in ['gpt-4o', 'gpt-4o-mini']]) = 2

可在 jsonata.org 用实际返回结果调试这些表达式。

---

Level 3：深度健康检查

发送一次真实 chat completion，验证整条推理链路。

curl -X POST http://your-open-webui-instance:8080/api/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Respond with the word HEALTHY"}],
    "model": "llama3.1",
    "temperature": 0
  }'

理想结果是返回 200 OK，并且响应里包含 HEALTHY。这一层能抓到模型未加载、后端处理异常、上游模型服务异常等 Level 1 / 2 不会暴露的问题。

信息

在 Uptime Kuma 里做 Level 3 时，需要使用 HTTP(s) monitor，并配置 POST body、认证头和 JSON 查询条件。具体写法见 Uptime Kuma 文档。

---

下一步

• OpenTelemetry - Trace、metrics 与 logs 接入 Grafana、Prometheus、Jaeger 等系统
• API 密钥 - API 密钥的完整开启与发放方式