Docs
文档目录

健康检查

运行示例前,将 <APPBASE_ENDPOINT_WITH_V1> 替换为目标环境的 API 地址,并核对项目及凭据属于同一环境。

这是什么 / 何时用

Health 服务面向服务端监控探针、SRE 巡检脚本与平台运维自动化,提供实例及各核心子系统的实时健康探活与队列水位查询:包括 HTTP 网关存活、OceanBase 数据库连接池、Redis 缓存与 Pub/Sub 通道、对象存储与本地挂载卷、ClamAV 病毒扫描引擎、TLS 证书有效期、NTP 时钟偏移,以及后台异步 Worker 队列(构建、数据库、邮件、消息、Webhook、迁移、用量聚合等)的待处理积压(size)与失败作业数。

前置

使用骨架

  1. 初始化客户端与 Health 服务:在巡检进程或发布流水线中装载 APPBASE_ENDPOINT、APPBASE_PROJECT_ID 与具备 health.read scope 的 APPBASE_API_KEY。

  2. 执行网关与基础组件探活:调用 health.get() 检查 HTTP 服务总览,调用 getDB()、getCache()、getPubSub()、getStorage()、getStorageLocal() 验证核心存储与消息总线连通性及 ping 延迟(毫秒)。

  3. 检查安全与环境状态:按需调用 getTime() 校验服务器时钟与互联网 NTP 时间偏移(防止 JWT/OAuth 签名因时钟漂移失效),调用 getCertificate({ domain }) 检查站点或自定义域名的 TLS 证书剩余有效期。

  4. 监控异步队列积压与失败任务:调用 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 })(domain 可选)get_certificate(domain=...)GetCertificate(...)GET /v1/health/certificatedomain?: stringHealthCertificate检查指定域名(或主端点域名)的 TLS 证书颁发者、主题与过期时间戳。
getTime()get_time()GetTime()GET /v1/health/time无HealthTime返回远端 NTP 时间(remoteTime)、本机时间(localTime)与秒级差值(diff)。

异步队列积压与失败任务检查方法清单

SDK 方法(Node / Java)Python 方法REST 端点可选参数返回模型
getQueueBuilds({ threshold })(threshold 可选)get_queue_builds(threshold=...)GET /v1/health/queue/buildsthreshold?: number(积压告警阈值)HealthQueue({ size: number })
getQueueCertificates({ threshold })(threshold 可选)get_queue_certificates(threshold=...)GET /v1/health/queue/certificatesthreshold?: numberHealthQueue
getQueueDatabases({ name, threshold })(name、threshold 均可选)get_queue_databases(...)GET /v1/health/queue/databasesname?: string, threshold?: numberHealthQueue
getQueueDeletes({ threshold })(threshold 可选)get_queue_deletes(threshold=...)GET /v1/health/queue/deletesthreshold?: numberHealthQueue
getQueueFunctions({ threshold })(threshold 可选)get_queue_functions(threshold=...)GET /v1/health/queue/functionsthreshold?: numberHealthQueue
getQueueLogs({ threshold })(threshold 可选)get_queue_logs(threshold=...)GET /v1/health/queue/logsthreshold?: numberHealthQueue
getQueueMails({ threshold })(threshold 可选)get_queue_mails(threshold=...)GET /v1/health/queue/mailsthreshold?: numberHealthQueue
getQueueMessaging({ threshold })(threshold 可选)get_queue_messaging(threshold=...)GET /v1/health/queue/messagingthreshold?: numberHealthQueue
getQueueMigrations({ threshold })(threshold 可选)get_queue_migrations(threshold=...)GET /v1/health/queue/migrationsthreshold?: numberHealthQueue
getQueueStatsResources({ threshold })(threshold 可选)get_queue_stats_resources(...)GET /v1/health/queue/stats-resourcesthreshold?: numberHealthQueue
getQueueUsage({ threshold })(threshold 可选)get_queue_usage(threshold=...)GET /v1/health/queue/usagethreshold?: numberHealthQueue
getQueueUsageDump({ threshold })(threshold 可选)get_queue_usage_dump(threshold=...)GET /v1/health/queue/usage-dumpthreshold?: numberHealthQueue
getQueueWebhooks({ threshold })(threshold 可选)get_queue_webhooks(threshold=...)GET /v1/health/queue/webhooksthreshold?: numberHealthQueue
getFailedJobs({ name, threshold })(threshold 可选)get_failed_jobs(name, threshold=...)GET /v1/health/queue/failed/{name}name(必填队列枚举), threshold?: numberHealthQueue

错误与边界

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 页签);单子系统失败不代表整体不可用。

import { Client, Health, AgentbaseException } from 'agentbase-node-sdk';

const client = new Client()
    .setEndpoint(process.env.APPBASE_ENDPOINT ?? '<APPBASE_ENDPOINT_WITH_V1>')
    .setProject(process.env.APPBASE_PROJECT_ID ?? '<APPBASE_PROJECT_ID>')
    .setKey(process.env.APPBASE_API_KEY!);
{
  const prepareRequest = client.prepareRequest.bind(client);
  client.prepareRequest = (...args) => {
    const request = prepareRequest(...args);
    request.options.redirect = 'error';
    return request;
  };
}

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;
}

示例指引