健康检查
这是什么 / 何时用
Health 服务面向服务端监控探针、SRE 巡检脚本与平台运维自动化,提供实例及各核心子系统的实时健康探活与队列水位查询:包括 HTTP 网关存活、OceanBase 数据库连接池、Redis 缓存与 Pub/Sub 通道、对象存储与本地挂载卷、ClamAV 病毒扫描引擎、TLS 证书有效期、NTP 时钟偏移,以及后台异步 Worker 队列(构建、数据库、邮件、消息、Webhook、迁移、用量聚合等)的待处理积压(size)与失败作业数。
前置
- 客户端初始化与认证:
- 仅服务端与 Console 侧可用:需使用 Server SDK
Client(setEndpoint、setProject、setKey,API Key 需具备health.readscope)或 Console SDK(管理面 Session / 短期 JWT)。 - Client / Web SDK 不可用:为防止暴露底层基础设施拓扑与内部队列水位,浏览器端 Web SDK 不提供
Health服务。
- 仅服务端与 Console 侧可用:需使用 Server SDK
使用骨架
- **初始化客户端与
Health服务**:在巡检进程或发布流水线中装载APPBASE_ENDPOINT、APPBASE_PROJECT_ID与具备health.readscope 的APPBASE_API_KEY。 - 执行网关与基础组件探活:调用
health.get()检查 HTTP 服务总览,调用getDB()、getCache()、getPubSub()、getStorage()、getStorageLocal()验证核心存储与消息总线连通性及ping延迟(毫秒)。 - 检查安全与环境状态:按需调用
getTime()校验服务器时钟与互联网 NTP 时间偏移(防止 JWT/OAuth 签名因时钟漂移失效),调用getCertificate({ domain })检查站点或自定义域名的 TLS 证书剩余有效期。 - 监控异步队列积压与失败任务:调用
getQueue*({ threshold })(如getQueueWebhooks、getQueueBuilds、getQueueDatabases)监控待消费队列长度,并调用getFailedJobs({ name, threshold })监控各队列死信/失败作业水位。
关键参数与返回
子系统与环境检查方法清单
| SDK 方法(Node / Java) | Python 方法 | Go 方法 | REST 端点 | 参数 | 返回模型 | 说明 |
|---|---|---|---|---|---|---|
get() | get() | Get() | GET /v1/health | 无 | HealthStatus | 检查 HTTP 服务总览状态(name、ping、status:pass / fail)。 |
getDB() | get_db() | GetDB() | GET /v1/health/db | 无 | HealthStatusList | 检查底层数据库实例连通性与延迟(total + statuses[])。 |
getCache() | get_cache() | GetCache() | GET /v1/health/cache | 无 | HealthStatusList | 检查缓存层(Redis)连通性与响应延迟。 |
getPubSub() | get_pub_sub() | GetPubSub() | GET /v1/health/pubsub | 无 | HealthStatusList | 检查实时订阅与内部事件 Pub/Sub 通道状态。 |
getStorage() | get_storage() | GetStorage() | GET /v1/health/storage | 无 | HealthStatus | 检查当前配置的主存储设备读写状态。 |
getStorageLocal() | get_storage_local() | GetStorageLocal() | GET /v1/health/storage/local | 无 | HealthStatus | 检查本地文件系统存储卷可写性与状态。 |
getAntivirus() | get_antivirus() | GetAntivirus() | GET /v1/health/anti-virus | 无 | HealthAntivirus | 检查防病毒引擎版本(version)与在线状态(status)。 |
getCertificate({ domain? }) | get_certificate(domain=...) | GetCertificate(...) | GET /v1/health/certificate | domain?: string | HealthCertificate | 检查指定域名(或主端点域名)的 TLS 证书颁发者、主题与过期时间戳。 |
getTime() | get_time() | GetTime() | GET /v1/health/time | 无 | HealthTime | 返回远端 NTP 时间(remoteTime)、本机时间(localTime)与秒级差值(diff)。 |
异步队列积压与失败任务检查方法清单
| SDK 方法(Node / Java) | Python 方法 | REST 端点 | 可选参数 | 返回模型 |
|---|---|---|---|---|
getQueueBuilds({ threshold? }) | get_queue_builds(threshold=...) | GET /v1/health/queue/builds | threshold?: number(积压告警阈值) | HealthQueue({ size: number }) |
getQueueCertificates({ threshold? }) | get_queue_certificates(threshold=...) | GET /v1/health/queue/certificates | threshold?: number | HealthQueue |
getQueueDatabases({ name?, threshold? }) | get_queue_databases(...) | GET /v1/health/queue/databases | name?: string, threshold?: number | HealthQueue |
getQueueDeletes({ threshold? }) | get_queue_deletes(threshold=...) | GET /v1/health/queue/deletes | threshold?: number | HealthQueue |
getQueueFunctions({ threshold? }) | get_queue_functions(threshold=...) | GET /v1/health/queue/functions | threshold?: number | HealthQueue |
getQueueLogs({ threshold? }) | get_queue_logs(threshold=...) | GET /v1/health/queue/logs | threshold?: number | HealthQueue |
getQueueMails({ threshold? }) | get_queue_mails(threshold=...) | GET /v1/health/queue/mails | threshold?: number | HealthQueue |
getQueueMessaging({ threshold? }) | get_queue_messaging(threshold=...) | GET /v1/health/queue/messaging | threshold?: number | HealthQueue |
getQueueMigrations({ threshold? }) | get_queue_migrations(threshold=...) | GET /v1/health/queue/migrations | threshold?: number | HealthQueue |
getQueueStatsResources({ threshold? }) | get_queue_stats_resources(...) | GET /v1/health/queue/stats-resources | threshold?: number | HealthQueue |
getQueueUsage({ threshold? }) | get_queue_usage(threshold=...) | GET /v1/health/queue/usage | threshold?: number | HealthQueue |
getQueueUsageDump({ threshold? }) | get_queue_usage_dump(threshold=...) | GET /v1/health/queue/usage-dump | threshold?: number | HealthQueue |
getQueueWebhooks({ threshold? }) | get_queue_webhooks(threshold=...) | GET /v1/health/queue/webhooks | threshold?: number | HealthQueue |
getFailedJobs({ name, threshold? }) | get_failed_jobs(name, threshold=...) | GET /v1/health/queue/failed/{name} | name(必填队列枚举), threshold?: number | HealthQueue |
错误与边界
- 单子系统异常不阻塞全局可用性:例如未开启 ClamAV 时
getAntivirus()可能返回disabled/offline或异常,但这不影响 TablesDB、知识库或模型网关正常服务;生产巡检脚本应按业务实际依赖的子系统设置告警分级。 - **队列阈值(
threshold)超限语义**:调用getQueue*({ threshold: 500 })或getFailedJobs({ name: 'webhooks', threshold: 10 })时,若当前队列size超过所传threshold,服务端会返回错误状态码(便于对接基于 HTTP 状态码的外部监控探针);若仅需采集数值指标写入 Prometheus,建议不传threshold(或传null)直接读取返回的size字段。 - 权限隔离:若 API Key 缺少
health.readscope,所有/v1/health/*接口将返回401 general_unauthorized_scope。
SDK 类别差异
| SDK 类别 | 支持范围 | 鉴权方式 | 典型场景 |
|---|---|---|---|
| Server SDK(Node.js / Java / Python / Go) | 全量子系统健康检查与队列监控 | 项目 API Key(health.read) | 后端就绪探针、Worker 积压巡检、发布前环境自检 |
| Console SDK(Node.js / Java / Python / Go) | 全量 + getConsolePausing 等管理面扩展 | 管理面 Session / 短期 JWT | 平台运维控制台健康面板 |
| Client / Web SDK(Web) | **无 Health 服务** | — | 浏览器不可调用健康检查 |
各语言调用示例
服务端 / Console 侧视角(无 Web 页签);单子系统失败不代表整体不可用。
- Node.js(Server)
- Java
- Python
- Go
- REST(curl)
import { Client, Health, AgentbaseException } from 'agentbase-node-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT ?? 'https://appbuild-sit.oceanbase.com/v1')
.setProject(process.env.APPBASE_PROJECT_ID ?? 'enterprise-ai-hub-210')
.setKey(process.env.APPBASE_API_KEY!);
const health = new Health(client);
try {
// 1. 总览与核心存储/缓存探活
const httpStatus = await health.get();
const dbStatus = await health.getDB();
const cacheStatus = await health.getCache();
const storageStatus = await health.getStorage();
console.log('HTTP:', httpStatus.status, 'DB count:', dbStatus.total, 'Cache count:', cacheStatus.total, 'Storage:', storageStatus.status);
// 2. 时钟偏移与队列积压监控
const clock = await health.getTime();
const webhookQueue = await health.getQueueWebhooks({ threshold: 1000 });
const buildQueue = await health.getQueueBuilds({ threshold: 200 });
console.log(`NTP diff=${clock.diff}s, webhookQueue=${webhookQueue.size}, buildQueue=${buildQueue.size}`);
} catch (err) {
if (err instanceof AgentbaseException) {
console.error(`健康检查告警 [${err.code} ${err.type}]: ${err.message}`);
}
throw err;
}import io.agentbase.Client;
import io.agentbase.services.Health;
import io.agentbase.exceptions.AppBaseException;
Client client = new Client()
.setEndpoint("https://appbuild-sit.oceanbase.com/v1")
.setProject("enterprise-ai-hub-210")
.setKey(System.getenv("APPBASE_API_KEY"));
Health health = new Health(client);
try {
var overall = health.get(); // 总览
var db = health.getDB(); // 子系统:getCache / getPubSub / getStorage / getStorageLocal / getAntivirus / getCertificate / getTime
var cache = health.getCache();
var whQueue = health.getQueueWebhooks(1000L); // 队列积压:getQueue* 系列(builds / mails / messaging / webhooks / usage / migrations 等)
System.out.println("Status=" + overall.getStatus() + ", db=" + db.getTotal() + ", cache=" + cache.getTotal() + ", whQueue=" + whQueue.getSize());
} catch (AppBaseException e) {
System.err.println("Health check alert: HTTP " + e.getCode() + " type=" + e.getType());
}import os
from agentbase.client import Client
from agentbase.services.health import Health
from agentbase.exception import AgentbaseException
client = (
Client()
.set_endpoint(os.environ.get('APPBASE_ENDPOINT', 'https://appbuild-sit.oceanbase.com/v1'))
.set_project(os.environ.get('APPBASE_PROJECT_ID', 'enterprise-ai-hub-210'))
.set_key(os.environ['APPBASE_API_KEY'])
)
health = Health(client)
try:
overall = health.get()
db = health.get_db()
cache = health.get_cache()
clock = health.get_time()
wh_queue = health.get_queue_webhooks(threshold=1000)
print(overall.status, db.total, cache.total, clock.diff, wh_queue.size)
except AgentbaseException as exc:
print(f"Health check error {exc.code} ({exc.type}): {exc.message}")package main
import (
"fmt"
"os"
"agentbase-go-sdk/agentbase"
)
func main() {
cl := agentbase.NewClient(
agentbase.WithEndpoint("https://appbuild-sit.oceanbase.com/v1"),
agentbase.WithProject("enterprise-ai-hub-210"),
agentbase.WithKey(os.Getenv("APPBASE_API_KEY")),
)
health := agentbase.NewHealth(cl)
status, _ := health.Get() // 总览
db, _ := health.GetDB() // 子系统:GetCache / GetPubSub / GetStorage / GetStorageLocal / GetAntivirus / GetCertificate / GetTime / GetFailedJobs
whQueue, _ := health.GetQueueWebhooks(health.WithGetQueueWebhooksThreshold(1000))
fmt.Println(status.Status, db.Total, whQueue.Size)
}# 1. HTTP 网关、数据库、缓存与存储健康检查
curl -sS "$APPBASE_ENDPOINT/health" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY"
curl -sS "$APPBASE_ENDPOINT/health/db" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY"
curl -sS "$APPBASE_ENDPOINT/health/cache" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY"
# 2. 队列积压与失败任务水位检查(builds / mails / webhooks / migrations / databases 等)
curl -sS "$APPBASE_ENDPOINT/health/queue/webhooks?threshold=1000" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY"
curl -sS "$APPBASE_ENDPOINT/health/queue/failed/webhooks?threshold=50" \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY"示例指引
- JavaScript / TypeScript 全量示例:../examples/javascript.md
- Python 全量示例:../examples/python.md
- Java 全量示例:../examples/java.md
- Go 全量示例:../examples/go.md
事实源
skills/ob-agentbase/references/server-sdks/java.md(模块总览)skills/ob-agentbase/references/server-sdks/nodejs.md(模块表)apis/zh-CN/misc/health.md(REST 端点清单与响应模型)- appbase
release-2.10.2/v2.10.0(0a5d23f9349028496286572fd43117aa6f8fce0a) - agentbase-sdks v2.10.0 specs(
packages/sdks/server-nodejs/src/services/health.ts方法面)