agentbase-docs

健康检查 API

实例与各子系统健康探测:HTTP 服务总览、组件状态、存储状态、队列积压与平台时钟(服务端/运维视角)。

资源与基础路径

认证与权限

认证与请求头约定见 通用约定。

端点清单

方法 + 路径用途
GET /healthHTTP 服务状态
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}失败队列阈值检查

请求与响应

以下按端点给出完整规格:输入(path / query / body 字段级表格)、输出(返回模型与关键字段)、调用示例(可复制的 curl)与响应示例。标注「泛化 schema any」的端点,响应体为对应资源的 JSON 文档,具体字段以 Server SDK 类型定义与实际资源为准。

Health

GET /v1/health

探测 HTTP 服务入口是否存活:最基础的健康检查,适合负载均衡与存活探针。

输入:无 path/query/body 参数。

输出:返回 healthStatus:

字段类型说明
namestring服务名
pinginteger健康检查耗时(毫秒)
statusstringpass / 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:

字段类型说明
versionstring防病毒服务版本
statusstringdisabled / 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 证书有效性:返回证书主体、签发者与有效期。

输入:

参数位置类型必填默认/枚举说明
domainquerystring否—要校验的域名;缺省用平台自身域名。

输出:返回 healthCertificate:

字段类型说明
namestring证书名称(如 /CN=www.google.com)
subjectSNstring主体 SN
issuerOrganisationstring签发机构
validFromstring生效时间(Unix 秒)
validTostring失效时间(Unix 秒)
signatureTypeSNstring签名算法(如 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:

字段类型说明
namestring服务名
pinginteger健康检查耗时(毫秒)
statusstringpass / 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:

字段类型说明
namestring服务名
pinginteger健康检查耗时(毫秒)
statusstringpass / 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:

字段类型说明
remoteTimeinteger可信远程服务器当前 Unix 时间戳(秒)
localTimeinteger平台本地服务器 Unix 时间戳(秒)
diffinteger远程与本地时间差(毫秒)

调用示例:

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

查询审计日志队列积压数:等待处理的审计日志条数。

输入:

参数位置类型必填默认/枚举说明
thresholdqueryinteger否默认 5000队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。

输出:返回 healthQueue:

字段类型说明
sizeinteger队列中等待处理的任务数

调用示例:

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

查询构建队列积压数:等待处理的构建任务条数。

输入:

参数位置类型必填默认/枚举说明
thresholdqueryinteger否默认 5000队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。

输出:返回 healthQueue:

字段类型说明
sizeinteger队列中等待处理的任务数

调用示例:

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 申请的证书数。

输入:

参数位置类型必填默认/枚举说明
thresholdqueryinteger否默认 5000队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。

输出:返回 healthQueue:

字段类型说明
sizeinteger队列中等待处理的任务数

调用示例:

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

查询数据库变更队列积压数:等待处理的数据库变更条数。

输入:

参数位置类型必填默认/枚举说明
namequerystring否默认 "database_db_main"要检查的数据库队列名,默认 database_db_main。
thresholdqueryinteger否默认 5000队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。

输出:返回 healthQueue:

字段类型说明
sizeinteger队列中等待处理的任务数

调用示例:

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

查询后台删除队列积压数:等待执行的破坏性变更条数。

输入:

参数位置类型必填默认/枚举说明
thresholdqueryinteger否默认 5000队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。

输出:返回 healthQueue:

字段类型说明
sizeinteger队列中等待处理的任务数

调用示例:

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

查询函数执行队列积压数:等待执行的函数调用条数。

输入:

参数位置类型必填默认/枚举说明
thresholdqueryinteger否默认 5000队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。

输出:返回 healthQueue:

字段类型说明
sizeinteger队列中等待处理的任务数

调用示例:

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

查询日志队列积压数:等待写入的日志条数。

输入:

参数位置类型必填默认/枚举说明
thresholdqueryinteger否默认 5000队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。

输出:返回 healthQueue:

字段类型说明
sizeinteger队列中等待处理的任务数

调用示例:

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

查询邮件队列积压数:等待发送的邮件条数。

输入:

参数位置类型必填默认/枚举说明
thresholdqueryinteger否默认 5000队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。

输出:返回 healthQueue:

字段类型说明
sizeinteger队列中等待处理的任务数

调用示例:

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

查询消息队列积压数:等待投递的消息条数。

输入:

参数位置类型必填默认/枚举说明
thresholdqueryinteger否默认 5000队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。

输出:返回 healthQueue:

字段类型说明
sizeinteger队列中等待处理的任务数

调用示例:

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

查询迁移队列积压数:等待执行的迁移任务条数。

输入:

参数位置类型必填默认/枚举说明
thresholdqueryinteger否默认 5000队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。

输出:返回 healthQueue:

字段类型说明
sizeinteger队列中等待处理的任务数

调用示例:

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

查询资源统计队列积压数:等待处理的资源指标条数。

输入:

参数位置类型必填默认/枚举说明
thresholdqueryinteger否默认 5000队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。

输出:返回 healthQueue:

字段类型说明
sizeinteger队列中等待处理的任务数

调用示例:

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

查询用量统计队列积压数:等待处理的使用量指标条数。

输入:

参数位置类型必填默认/枚举说明
thresholdqueryinteger否默认 5000队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。

输出:返回 healthQueue:

字段类型说明
sizeinteger队列中等待处理的任务数

调用示例:

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 投递队列积压数:等待投递的回调条数。

输入:

参数位置类型必填默认/枚举说明
thresholdqueryinteger否默认 5000队列大小阈值;达到(≥)时返回服务错误用于告警,默认 5000。

输出:返回 healthQueue:

字段类型说明
sizeinteger队列中等待处理的任务数

调用示例:

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 可用作失败堆积告警。

输入:

参数位置类型必填默认/枚举说明
namepathstring是枚举 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。
thresholdqueryinteger否默认 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
}

错误与边界

与 Server SDK 的对应

service.method端点
Health.get / getAntivirus / getCache / getCertificate / getDB / getPubSub / getStorage / getStorageLocal / getQueue* / getFailedQueue/health*

事实源