健康检查 API
实例与各子系统健康探测:HTTP 服务总览、组件状态、存储状态、队列积压与平台时钟(服务端/运维视角)。
服务与资源边界
健康检查(Health)API 为平台运维与自动化巡检系统提供只读的实例级与组件级探针接口,覆盖 HTTP 入口存活、底层 OceanBase 数据库连通性、内存缓存、Pub/Sub、对象存储、ClamAV 防病毒、域名 TLS 证书有效期、系统时钟漂移以及 14 类后台异步工作队列的积压与失败任务阈值监控。
资源与基础路径
Base URL:
https://<your-endpoint>/v1。路径前缀
/health;无状态端点,返回healthStatus*模型。
认证与权限
认证与请求头约定见 通用约定。
scope:
health.read;项目 API Key 即可访问。
端点总览
本模块端点按探测目标分为四组:核心组件探针(/health、/health/db、/health/cache、/health/pubsub、/health/storage*、/health/anti-virus)、安全与时钟探针(/health/certificate、/health/time)、工作队列待处理积压探针(/health/queue/{name})以及死信/失败任务阈值探针(/health/queue/failed/{name})。
端点清单
| 方法 + 路径 | 用途 |
|---|---|
GET /health | HTTP 服务状态 |
GET /health/anti-virus / cache / certificate / db / pubsub | 组件状态 |
GET /health/storage / GET /health/storage/local | 存储状态 |
GET /health/queue/{name} 系列(audits / builds / certificates / databases / deletes / functions / logs / mails / messaging / migrations / stats-resources / stats-usage / webhooks) | 队列积压状态 |
GET /health/time | 平台时钟(Unix 秒,用于时钟漂移检测) |
GET /health/queue/failed/{name} | 失败队列阈值检查 |
端点详解
队列监控端点(/health/queue/* 與 /health/queue/failed/*)均支持可选的 threshold 查询参数(默认 5000):当队列当前积压或失败条数 size 低于阈值时返回 200 OK,达到或超过阈值时触发告警状态,便于直接对接 Prometheus Blackbox Exporter 或外部告警网关。
请求与响应
以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。
Health
GET /v1/health
探测 HTTP 服务入口是否存活:最基础的健康检查,适合负载均衡与存活探针。
输入:无 path/query/body 参数。
输出:返回 healthStatus:
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 服务名 |
ping | integer | 健康检查耗时(毫秒) |
status | string | pass / fail |
调用示例:
curl "https://<your-endpoint>/v1/health" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"name": "database",
"ping": 128,
"status": "pass"
}GET /v1/health/anti-virus
探测防病毒服务连通性与版本。
输入:无 path/query/body 参数。
输出:返回 healthAntivirus:
| 字段 | 类型 | 说明 |
|---|---|---|
version | string | 防病毒服务版本 |
status | string | disabled / offline / online |
调用示例:
curl "https://<your-endpoint>/v1/health/anti-virus" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"version": "1.0.0",
"status": "online"
}GET /v1/health/cache
探测内存缓存服务状态(多节点返回列表)。
输入:无 path/query/body 参数。
输出:返回 healthStatusList(total + statuses[],元素为 healthStatus:name / ping / status(pass / fail))。
调用示例:
curl "https://<your-endpoint>/v1/health/cache" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 2,
"statuses": [
{
"name": "cache-1",
"ping": 2,
"status": "pass"
},
{
"name": "cache-2",
"ping": 3,
"status": "pass"
}
]
}GET /v1/health/certificate
校验指定域名的 TLS 证书有效性:返回证书主体、签发者与有效期。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
domain | query | string | 否 | — | 要校验的域名;缺省用平台自身域名。 |
输出:返回 healthCertificate:
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 证书名称(如 /CN=www.google.com) |
subjectSN | string | 主体 SN |
issuerOrganisation | string | 签发机构 |
validFrom | string | 生效时间(Unix 秒) |
validTo | string | 失效时间(Unix 秒) |
signatureTypeSN | string | 签名算法(如 RSA-SHA256) |
调用示例:
curl "https://<your-endpoint>/v1/health/certificate?domain=www.example.com" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"name": "/CN=www.example.com",
"subjectSN": "",
"issuerOrganisation": "Let's Encrypt",
"validFrom": "1704200998",
"validTo": "1711458597",
"signatureTypeSN": "RSA-SHA256"
}GET /v1/health/db
探测数据库服务状态(多节点返回列表)。
输入:无 path/query/body 参数。
输出:返回 healthStatusList(total + statuses[],元素为 healthStatus:name / ping / status(pass / fail))。
调用示例:
curl "https://<your-endpoint>/v1/health/db" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 1,
"statuses": [
{
"name": "database",
"ping": 128,
"status": "pass"
}
]
}GET /v1/health/pubsub
探测发布订阅(pub-sub)服务状态(多节点返回列表)。
输入:无 path/query/body 参数。
输出:返回 healthStatusList(total + statuses[],元素为 healthStatus:name / ping / status(pass / fail))。
调用示例:
curl "https://<your-endpoint>/v1/health/pubsub" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"total": 1,
"statuses": [
{
"name": "pubsub",
"ping": 5,
"status": "pass"
}
]
}GET /v1/health/storage
探测存储设备状态。
输入:无 path/query/body 参数。
输出:返回 healthStatus:
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 服务名 |
ping | integer | 健康检查耗时(毫秒) |
status | string | pass / fail |
调用示例:
curl "https://<your-endpoint>/v1/health/storage" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"name": "storage",
"ping": 12,
"status": "pass"
}GET /v1/health/storage/local
探测本地存储设备状态。
输入:无 path/query/body 参数。
输出:返回 healthStatus:
| 字段 | 类型 | 说明 |
|---|---|---|
name | string | 服务名 |
ping | integer | 健康检查耗时(毫秒) |
status | string | pass / fail |
调用示例:
curl "https://<your-endpoint>/v1/health/storage/local" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"name": "storage-local",
"ping": 1,
"status": "pass"
}GET /v1/health/time
返回平台本地时钟与远程 NTP 时间的对照:用于客户端时钟漂移检测(签名请求前校时)。
输入:无 path/query/body 参数。
输出:返回 healthTime:
| 字段 | 类型 | 说明 |
|---|---|---|
remoteTime | integer | 可信远程服务器当前 Unix 时间戳(秒) |
localTime | integer | 平台本地服务器 Unix 时间戳(秒) |
diff | integer | 远程与本地时间差(毫秒) |
调用示例:
curl "https://<your-endpoint>/v1/health/time" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"remoteTime": 1757812200,
"localTime": 1757812293,
"diff": 93
}GET /v1/health/queue/audits
查询审计日志队列积压数:等待处理的审计日志条数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
threshold | query | integer | 否 | 默认 5000 | 队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue:
| 字段 | 类型 | 说明 |
|---|---|---|
size | integer | 队列中等待处理的任务数 |
调用示例:
curl "https://<your-endpoint>/v1/health/queue/audits" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}GET /v1/health/queue/builds
查询构建队列积压数:等待处理的构建任务条数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
threshold | query | integer | 否 | 默认 5000 | 队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue:
| 字段 | 类型 | 说明 |
|---|---|---|
size | integer | 队列中等待处理的任务数 |
调用示例:
curl "https://<your-endpoint>/v1/health/queue/builds" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}GET /v1/health/queue/certificates
查询证书队列积压数:等待向 Let’s Encrypt 申请的证书数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
threshold | query | integer | 否 | 默认 5000 | 队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue:
| 字段 | 类型 | 说明 |
|---|---|---|
size | integer | 队列中等待处理的任务数 |
调用示例:
curl "https://<your-endpoint>/v1/health/queue/certificates" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}GET /v1/health/queue/databases
查询数据库变更队列积压数:等待处理的数据库变更条数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | query | string | 否 | 默认 "database_db_main" | 要检查的数据库队列名,默认 database_db_main。 |
threshold | query | integer | 否 | 默认 5000 | 队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue:
| 字段 | 类型 | 说明 |
|---|---|---|
size | integer | 队列中等待处理的任务数 |
调用示例:
curl "https://<your-endpoint>/v1/health/queue/databases" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}GET /v1/health/queue/deletes
查询后台删除队列积压数:等待执行的破坏性变更条数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
threshold | query | integer | 否 | 默认 5000 | 队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue:
| 字段 | 类型 | 说明 |
|---|---|---|
size | integer | 队列中等待处理的任务数 |
调用示例:
curl "https://<your-endpoint>/v1/health/queue/deletes" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}GET /v1/health/queue/functions
查询函数执行队列积压数:等待执行的函数调用条数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
threshold | query | integer | 否 | 默认 5000 | 队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue:
| 字段 | 类型 | 说明 |
|---|---|---|
size | integer | 队列中等待处理的任务数 |
调用示例:
curl "https://<your-endpoint>/v1/health/queue/functions" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}GET /v1/health/queue/logs
查询日志队列积压数:等待写入的日志条数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
threshold | query | integer | 否 | 默认 5000 | 队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue:
| 字段 | 类型 | 说明 |
|---|---|---|
size | integer | 队列中等待处理的任务数 |
调用示例:
curl "https://<your-endpoint>/v1/health/queue/logs" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}GET /v1/health/queue/mails
查询邮件队列积压数:等待发送的邮件条数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
threshold | query | integer | 否 | 默认 5000 | 队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue:
| 字段 | 类型 | 说明 |
|---|---|---|
size | integer | 队列中等待处理的任务数 |
调用示例:
curl "https://<your-endpoint>/v1/health/queue/mails" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}GET /v1/health/queue/messaging
查询消息队列积压数:等待投递的消息条数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
threshold | query | integer | 否 | 默认 5000 | 队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue:
| 字段 | 类型 | 说明 |
|---|---|---|
size | integer | 队列中等待处理的任务数 |
调用示例:
curl "https://<your-endpoint>/v1/health/queue/messaging" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}GET /v1/health/queue/migrations
查询迁移队列积压数:等待执行的迁移任务条数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
threshold | query | integer | 否 | 默认 5000 | 队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue:
| 字段 | 类型 | 说明 |
|---|---|---|
size | integer | 队列中等待处理的任务数 |
调用示例:
curl "https://<your-endpoint>/v1/health/queue/migrations" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}GET /v1/health/queue/stats-resources
查询资源统计队列积压数:等待处理的资源指标条数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
threshold | query | integer | 否 | 默认 5000 | 队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue:
| 字段 | 类型 | 说明 |
|---|---|---|
size | integer | 队列中等待处理的任务数 |
调用示例:
curl "https://<your-endpoint>/v1/health/queue/stats-resources" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}GET /v1/health/queue/stats-usage
查询用量统计队列积压数:等待处理的使用量指标条数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
threshold | query | integer | 否 | 默认 5000 | 队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue:
| 字段 | 类型 | 说明 |
|---|---|---|
size | integer | 队列中等待处理的任务数 |
调用示例:
curl "https://<your-endpoint>/v1/health/queue/stats-usage" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}GET /v1/health/queue/webhooks
查询 Webhook 投递队列积压数:等待投递的回调条数。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
threshold | query | integer | 否 | 默认 5000 | 队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue:
| 字段 | 类型 | 说明 |
|---|---|---|
size | integer | 队列中等待处理的任务数 |
调用示例:
curl "https://<your-endpoint>/v1/health/queue/webhooks" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}GET /v1/health/queue/failed/{name}
查询指定队列中失败任务的数量:结合 threshold 可用作失败堆积告警。
输入:
| 参数 | 位置 | 类型 | 必填 | 默认/枚举 | 说明 |
|---|---|---|---|---|---|
name | path | string | 是 | 枚举 v1-database, v1-deletes, v1-audits, v1-mails, v1-functions, v1-stats-resources, v1-stats-usage, v1-webhooks … | 队列名,枚举:v1-database、v1-deletes、v1-audits、v1-mails、v1-functions、v1-stats-resources、v1-stats-usage、v1-webhooks、v1-certificates、v1-builds、v1-screenshots、v1-messaging、v1-migrations、v1-schema-migrations。 |
threshold | query | integer | 否 | 默认 5000 | 阈值;达到(≥)时返回服务错误用于告警,默认 5000。 |
输出:返回 healthQueue(size:失败任务数)。
调用示例:
curl "https://<your-endpoint>/v1/health/queue/failed/v1-database" \
-H "X-Appwrite-Project: <YOUR_PROJECT_ID>" \
-H "X-Appwrite-Key: <YOUR_API_KEY>"响应示例:
{
"size": 8
}错误与边界
Health 端点用于监控探测:组件异常时返回降级状态而非 5xx(除网关自身不可达)。
与 Server SDK 的对应
| service.method | 端点 |
|---|---|
Health.get / getAntivirus / getCache / getCertificate / getDB / getPubSub / getStorage / getStorageLocal / getQueue* / getFailedQueue | /health* |