端点参考

KernelHost API

所有端点均返回 application/json。错误遵循 RFC 7807(Problem+JSON)。每个响应都携带 X-Request-Id 响应头,便于与服务器端审计日志进行关联。

MethodPath权限范围用途
GET/v1/healthpublic无需身份验证的健康检查。
GET/v1/meany自身账户信息与密钥元数据。
GET/v1/productsread:products所有公开销售产品的列表与价格。
GET/v1/products/{id}read:products产品详情,包含配置选项。
POST/v1/orderswrite:orders提交订单。必须携带 Idempotency-Key。
GET/v1/orders/{id}read:orders自身订单的状态。
GET/v1/servicesread:services自身服务列表(支持分页)。
GET/v1/services/{id}read:services自身某项服务的详情。
GET/v1/services/{id}/credentialsread:credentials服务凭据(独立权限范围,全程审计)。
POST/v1/services/{id}/actionswrite:services服务操作:start、stop、reboot、cancel(于计费周期结束时生效)、cancel_revoke。
GET/v1/services/{id}/metricsread:services自有服务的服务器指标(CPU、内存、网络)。
GET/v1/services/{id}/ddos/profilesread:ddos可用的 Advanced DDoS Protection 防护配置。
GET/v1/services/{id}/ddos/rulesread:ddos已分配防护 IP 的当前规则。
POST/v1/services/{id}/ddos/ruleswrite:ddos添加一条防护规则,必须提供 Idempotency-Key。
DELETE/v1/services/{id}/ddos/rules/{rule_id}write:ddos删除一条自有规则,必须提供 Idempotency-Key。
GET/v1/services/{id}/ddos/attacksread:ddos受保护 IP 上检测到的攻击(Remote DDoS Protection)。
GET/v1/services/{id}/ddos/attacks/{attack_id}read:ddos单次攻击详情:流量与分项统计。
GET/v1/billing/balanceread:billing账户余额。
GET/v1/billing/invoicesread:billing您的发票列表(支持分页)。
GET/v1/billing/invoices/{id}/pdfread:billing发票 PDF。
GET/v1/webhooksread:webhooks当前 Webhook URL。
PUT/v1/webhookswrite:webhooks设置或取消 Webhook URL。

Advanced DDoS Protection 规则

这些接口要求使用属于当前账户的 Advanced DDoS Protection 服务。状态为 active 或 suspended 时均可读取,只有 active 状态允许修改。请在 API 密钥上明确启用用于读取的 read:ddos 和用于修改的 write:ddos。现有密钥不会自动获得新权限。不提供隧道或白名单管理功能。

从配置目录中选择 app_code。port 必须是 1 到 65535 的整数;icmp 可省略 port 或传入 0。可选的 extra_ports 对象使用与目录完全一致的名称指定整数端口;省略的项使用配置默认值。协议由服务器确定,请勿提交 protocol。未知字段或名称返回 HTTP 400。

GET /v1/services/{id}/ddos/profiles

{
  "data": [{
    "app_code": "rust",
    "name": "Rust",
    "default_port": 28015,
    "protocol": "UDP",
    "extra_ports": [
      {"name": "Query", "port": 28016, "protocol": "UDP"},
      {"name": "RCON", "port": 28016, "protocol": "TCP"},
      {"name": "RustPlus", "port": 28082, "protocol": "TCP"}
    ]
  }],
  "meta": {"service_id": 1234, "protection_ip": "192.0.2.10", "max_rules": 1000}
}

POST /v1/services/{id}/ddos/rules

{
  "app_code": "rust",
  "port": 28015,
  "extra_ports": {"Query": 28016, "RCON": 28016, "RustPlus": 28082}
}

POST 返回 HTTP 201,data 中包含创建的规则。GET 返回规则列表,以及含有 service_id、protection_ip 和 max_rules 的 meta。DELETE 请求体须为空,返回结果为下方所示的 HTTP 200。POST 和 DELETE 均必须提供 Idempotency-Key。

GET /v1/services/{id}/ddos/rules

{
  "data": [{
    "id": "example-rule-id",
    "app_code": "rust",
    "port": 28015,
    "protocol": "UDP",
    "extra_ports": [
      {"name": "Query", "port": 28016, "protocol": "UDP"},
      {"name": "RCON", "port": 28016, "protocol": "TCP"},
      {"name": "RustPlus", "port": 28082, "protocol": "TCP"}
    ]
  }],
  "meta": {"service_id": 1234, "protection_ip": "192.0.2.10", "max_rules": 1000}
}

DELETE /v1/services/{id}/ddos/rules/{rule_id}

{"data": {"id": "example-rule-id", "deleted": true}}

面板与 API 共用固定 UTC 时间窗口:每账户每分钟 10 次写入尝试,每防护 IP 每分钟 5 次,每账户每 UTC 日 200 次。通过限流检查后无效或失败的尝试也计数;成功的幂等重放不计数。DDoS API 读取接口共用每账户每分钟 30 次请求的限制。每个防护 IP 最多 1000 条规则。

HTTP 404:服务未知或不属于您,或者规则非本人所有、缺失或为系统规则。HTTP 409:服务不是 Advanced DDoS Protection(not_supported_for_product)、服务非 active 状态、端口冲突或并发修改。HTTP 429:已达限制,请遵守 Retry-After。HTTP 502:防护服务无法完成请求。系统规则 block 不显示且无法删除。HTTP 503:请求限额检查暂时不可用,请遵守 Retry-After。

DDoS 攻击报告

这些接口要求使用属于当前账户、状态为 active 或 suspended 的 Remote DDoS Protection 服务,并需要明确启用的 read:ddos 权限。列表按从新到旧的顺序显示在该服务受保护 IP 地址上检测到的 DDoS 攻击。

查询参数:from 和 to 可使用日期(YYYY-MM-DD)或带时区的 ISO 8601 日期时间(默认:最近 30 天);limit 为 1 到 100(默认 25);offset 为 0 到 9999(默认 0)。查询时间范围最多回溯 90 天,且不会早于该受保护 IP 地址分配给此服务的时间;meta.from 和 meta.to 显示实际使用的时间范围。

GET /v1/services/{id}/ddos/attacks?from=2026-10-10

{
  "data": [{
    "id": "3f6c1a2e-9b47-4d8a-b5e2-7c0d9e4a1f63",
    "type": "ddos_attack",
    "started_at": "2026-11-07T18:34:06Z",
    "ended_at": null,
    "detected_bps": 20938227712,
    "detected_pps": 1998848,
    "source_ip_count": 341,
    "target_ip": "203.0.113.111",
    "details_available": true
  }],
  "paging": {"limit": 25, "offset": 0, "total": 1, "truncated": false},
  "meta": {"service_id": 5678, "protected_ip": "203.0.113.111", "from": "2026-10-10T00:00:00Z", "to": "2026-11-09T11:10:16Z", "retention_days": 90}
}

每条攻击记录包含 id(UUID)、type(ddos_attack;若目标 IP 曾被临时黑洞路由,则为 blackhole)、started_at、ended_at(可能为 null)、detected_bps、detected_pps、source_ip_count、target_ip 和 details_available。detected_bps 和 detected_pps 是检测到攻击时的速率;此时过滤已经开始,因此可能低于详情中的峰值。paging 包含 limit、offset、total 和 truncated(时间范围内攻击超过 500 次时为 true),meta 包含 service_id、protected_ip、from、to 和 retention_days(90)。列表缓存 60 秒。

GET /v1/services/{id}/ddos/attacks/{attack_id}

{
  "data": {
    "id": "3f6c1a2e-9b47-4d8a-b5e2-7c0d9e4a1f63",
    "type": "ddos_attack",
    "started_at": "2026-11-07T18:34:06Z",
    "ended_at": null,
    "detected_bps": 20938227712,
    "detected_pps": 1998848,
    "source_ip_count": 341,
    "target_ip": "203.0.113.111",
    "details_available": true,
    "peak_bps": 20938227712,
    "peak_pps": 1998848,
    "total_bytes": 104809201664,
    "total_packets": 81887232,
    "interval_seconds": 1,
    "traffic": [{"time": "2026-11-07T18:34:06Z", "bps": 20938227712, "pps": 1998848}],
    "protocols": [{"protocol": "UDP", "avg_bps": 695618765, "avg_pps": 65645, "bytes": 104342814720, "packets": 78774272, "bps_percent": 99.56, "pps_percent": 96.2}],
    "destination_ports": [{"port": 58675, "protocol": "UDP", "avg_bps": 695556506, "avg_pps": 65481, "bps_percent": 99.55, "pps_percent": 95.96}],
    "source_ports": [{"port": 53, "protocol": "UDP", "avg_bps": 41896312, "avg_pps": 3511, "bps_percent": 5.996, "pps_percent": 5.15}],
    "source_countries": [{"country": "MX", "avg_bps": 96051528, "avg_pps": 8656}],
    "source_ips": [{"ip": "198.51.100.7", "avg_bps": 46162248, "avg_pps": 4151, "bps_percent": 6.61, "pps_percent": 6.08}],
    "packet_sizes": [{"range": "1400-1499", "avg_bps": 374806938, "percent": 54.076}]
  },
  "meta": {"service_id": 5678, "cached": false}
}

详情包含列表中的全部字段,另有 peak_bps、peak_pps、total_bytes、total_packets 和 interval_seconds。traffic 按时间间隔列出过滤网络所观测到的入站攻击流量({time, bps, pps}),范围约为检测前 10 分钟至检测后 10 分钟。protocols、destination_ports、source_ports、source_countries、source_ips 和 packet_sizes 等分项统计通常包含排名前 5 的条目:avg_bps 和 avg_pps 为整个测量窗口内的平均值,bps_percent 和 pps_percent 为占比。protocols 另含 bytes 和 packets,packet_sizes 含 range、avg_bps 和 percent。详情最多缓存 15 分钟。

HTTP 400 validation_failed:值无效或查询参数未知。HTTP 404:服务未知或不属于您,攻击 ID 未知,或攻击针对的是其他 IP 地址。HTTP 409 not_supported_for_product:该服务不是 Remote DDoS Protection 服务(例如 Advanced DDoS Protection 或服务器)。HTTP 409 service_not_active:服务既不是 active 也不是 suspended 状态。HTTP 409 protection_not_ready:防护仍在配置中。

服务器指标

此接口要求使用属于当前账户的活动服务,并需要 read:services 权限。Edge Unlimited Traffic VPS 提供 CPU、内存以及入站和出站网络数据(bit/s 和包/s),另提供每日及本月至今的出站流量。位于欧洲、德国、法国、加拿大东部、英国和波兰站点的常规 Unlimited Traffic VPS 仅提供以 bit/s 计的入站和出站网络数据。

查询参数 range:1h、6h、24h、7d 或 14d(默认 1h)。数据点之间的间隔取决于时间范围:Edge Unlimited Traffic VPS 约为 15 秒(1h)、20 秒(6h)、2 分钟(24h)、10 分钟(7d)和 20 分钟(14d);常规 Unlimited Traffic VPS 在 24h 及以内为 5 分钟,7d 为 30 分钟,14d 为 2 小时。step_seconds 显示响应中的实际间隔。

GET /v1/services/{id}/metrics?range=24h

{
  "data": {
    "service_id": 1234,
    "range": "24h",
    "step_seconds": 120,
    "available": ["cpu_percent", "memory_percent", "network_in_bps", "network_out_bps", "network_in_pps", "network_out_pps"],
    "summary": {
      "cpu_percent": {"avg": 3.1, "max": 41.7, "last": 2.9},
      "network_in_bps": {"avg": 64012.5, "max": 912345.0, "last": 60026.2}
    },
    "points": [
      {"time": "2026-11-08T11:12:00Z", "cpu_percent": 3.254, "memory_percent": 43.001, "network_in_bps": 68515.425, "network_out_bps": 650.767, "network_in_pps": 119.992, "network_out_pps": 0.775},
      {"time": "2026-11-08T11:14:00Z", "cpu_percent": 3.118, "memory_percent": 43.004, "network_in_bps": 66120.871, "network_out_bps": 702.134, "network_in_pps": 115.317, "network_out_pps": 0.825}
    ],
    "traffic": {
      "month_to_date_out_bytes": 111844510,
      "daily": [{"date": "2026-11-09", "out_bytes": 10485760, "final": false}],
      "as_of": "2026-11-09T11:00:01Z",
      "unit": "bytes",
      "direction": "outbound"
    }
  },
  "meta": {"generated_at": "2026-11-09T11:12:30Z", "cached": false, "measured_at": "server_network_interface"}
}

数值在服务器的网络接口上测得,因此反映的是实际到达服务器的流量。内存数据需要服务器内运行客户机代理(guest agent)。无法测得的数值为 null;available 列出有测量值的指标,summary 为每项指标给出 avg、max 和 last。traffic 包含每日及本月至今的出站流量(单位为字节,当天统计完成后 final 为 true),对于没有流量计数器的产品则为 null。响应缓存时间为 30 秒(1h)至 10 分钟(14d);meta.cached 表示响应是否来自缓存。

HTTP 400 validation_failed:range 取值不受支持或查询参数未知。HTTP 404:服务未知或不属于您。HTTP 409 not_supported_for_product:此服务没有可用指标(其他产品和站点)。HTTP 409 service_not_active:服务未处于活动状态。

服务器指标和攻击报告适用通用速率限制。此外,无法由缓存响应的数据获取请求在这三个接口合计每账户每分钟最多 20 次;超出后将返回带 Retry-After 的 HTTP 429。HTTP 502 monitoring_unavailable 或 reports_unavailable:数据源暂时不可用,请稍后重试。HTTP 503 temporarily_unavailable(带 Retry-After):另一个并行请求正在准备相同的数据。

以下内容无法通过 API 获取:Advanced DDoS Protection 以及 Edge Unlimited Traffic VPS 等服务器的攻击报告;按受保护 IP 统计的清洁流量或丢弃流量;常规 Unlimited Traffic VPS 的 CPU 和内存数据;webhook 推送和 CSV 导出。

幂等性

POST /v1/orders 与 POST /v1/services/{id}/actions 必须携带 Idempotency-Key 请求头(1 至 80 个字符,取自 [A-Za-z0-9_.-])。该 Key 与请求方法、路径及请求体绑定。在一小时内使用同一个 Key 重复发送相同的请求,将返回已保存的响应;超过一小时后将返回 410(reason 为 replay_stale),此时请发送新的 Key。若同一个 Key 搭配不同的请求体或用于其他端点,请求将以 409 idempotency_conflict 被拒绝。

速率限制

默认限制为:每个密钥每分钟 60 次请求(另允许 20 次突发)、每天 5,000 次;每个账户在所有密钥之间合计每分钟 120 次;每个来源 IP 每分钟 600 次。超出限制时,将返回 HTTP 429 并附带 Retry-After 响应头。响应头 X-RateLimit-Remaining 与 X-RateLimit-Reset 显示该密钥限额的当前状态。