跳到主要内容

管理 API

ForgeDNS 的管理 API 是独立控制平面，负责：

  • 进程与启动健康检查
  • 配置检查与配置文本校验
  • 重载与关闭控制
  • 插件扩展 API
  • Prometheus 指标导出

本章介绍当前提供的管理 API。

启用方式​

简写​

api:
  http: "127.0.0.1:9088"

详写​

api:
  http:
    listen: "127.0.0.1:9443"
    ssl:
      cert: "/etc/forgedns/api.crt"
      key: "/etc/forgedns/api.key"
      client_ca: "/etc/forgedns/client-ca.crt"
      require_client_cert: true
    auth:
      type: basic
      username: "admin"
      password: "secret"

认证与传输​

TLS​

当 ssl.cert 与 ssl.key 同时配置时，API 使用 HTTPS。

可选增强：

  • client_ca
    • 配置客户端 CA。
  • require_client_cert
    • 强制双向认证。

Basic Auth​

auth:
  type: basic
  username: "admin"
  password: "secret"

开启后，所有 API 请求都需要通过 Basic Auth。

请求头格式如下：

Authorization: Basic YWRtaW46c2VjcmV0

编码规则如下：

  • 先按 username:password 拼接原始字符串。
  • 再对整个字符串做 Base64 编码。
  • 请求头前缀必须为 Basic 。

以上示例中，admin:secret 对应的 Base64 结果为 YWRtaW46c2VjcmV0。

注意事项：

  • 这里使用的是标准 Base64，不是 URL-safe Base64。
  • 不需要分别对 username 和 password 单独编码。
  • 不使用百分号编码，也不应先做 URL encode。
  • 服务端按解码后的完整结果与 username:password 做直接比较。

示例：

curl -u admin:secret http://127.0.0.1:9088/healthz

或：

curl -H 'Authorization: Basic YWRtaW46c2VjcmV0' \
  http://127.0.0.1:9088/healthz

路由组织​

API 路由分成三类：

  • 全局路由
    • 例如 /healthz、/control
  • 插件路由
    • 统一格式：/plugins/<plugin_tag>/<subpath>
  • 观测路由
    • 例如 /metrics

内置健康检查接口​

GET /healthz​

作用：

  • 只检查 API 监听是否已建立。

返回：

  • 200 OK：ok
  • 503 Service Unavailable：not_listening

GET /readyz​

作用：

  • 检查插件初始化和 server 启动是否已完成。

返回：

  • 200 OK：ready
  • 503 Service Unavailable：not_ready

GET /health​

作用：

  • 返回 JSON 形式的健康详情。

示例结构：

{
  "status": "ok",
  "version": "x.y.z",
  "uptime_ms": 12345,
  "checks": {
    "api": "ok",
    "plugin_init": "ok",
    "server_startup": "ok"
  },
  "plugins": {
    "total": 12,
    "servers": 4
  }
}

内置控制接口​

GET /control​

作用：

  • 返回当前进程控制面状态。

返回内容包括：

  • 运行状态
  • 运行时长
  • 当前配置路径
  • 是否请求过 shutdown
  • reload 状态快照

POST /shutdown​

作用：

  • 请求优雅关闭。

返回：

  • 202 Accepted

POST /reload​

作用：

  • 请求重载配置，重新加载所有插件。

返回：

  • 202 Accepted
    • 已受理。
  • 409 Conflict
    • 已有 reload 在 pending / in_progress。

GET /reload/status​

作用：

  • 查询最近一次重载状态。

返回字段包括：

  • status
    • idle
    • pending
    • in_progress
    • ok
    • failed
  • pending
  • in_progress
  • last_started_ms
  • last_completed_ms
  • last_success_ms
  • last_error

配置检查接口​

GET /config/check​

作用：

  • 校验当前配置文件路径对应的配置文件。

适用场景：

  • 检查磁盘上现有配置是否能成功解析与通过插件依赖校验。

POST /config/validate​

作用：

  • 直接校验请求体中的 YAML 配置文本。

请求体要求：

  • UTF-8 文本
  • 非空

适用场景：

  • 控制平面先验校验配置，再决定是否落盘。

插件扩展 API​

统一格式​

/plugins/<plugin_tag>/<route>

说明：

  • 也有少量插件会把主资源绑定到前缀路由下，例如 query_recorder 的 /plugins/<tag>/records/<id>。

cache​

GET /plugins/<cache_tag>/flush​

清空缓存。

provider​

POST /plugins/<provider_tag>/reload​

作用：

  • 使用 provider 启动时的同一份配置，定向刷新该 provider 的内部数据快照。
  • 不会重建其它插件，也不会修改 provider tag、依赖关系或配置拓扑。

返回：

  • 200 OK
    • provider 已成功 reload。
  • 400 Bad Request
    • provider 不存在、不是运行中的 provider，或 reload 过程中返回错误。

适用场景：

  • 规则文件下载完成后，只刷新受影响的 domain_set、ip_set、geosite、geoip、adguard_rule provider。
  • 需要避免应用级全量 POST /reload 对其它插件造成重建影响。

注意：

  • 如果变更涉及 config.yaml、provider 依赖拓扑、插件列表或其它非 provider 结构，仍然需要使用 POST /reload。

GET /plugins/<cache_tag>/dump​

导出缓存 dump。

POST /plugins/<cache_tag>/load_dump​

导入缓存 dump。

reverse_lookup​

GET /plugins/<tag>?ip=<ip_addr>​

按 IP 查询缓存中的域名。

示例：

GET /plugins/reverse_lookup_main?ip=8.8.8.8

返回：

  • 命中：域名文本，通常为 fully-qualified domain name。
  • 未命中：空响应体。
  • 参数错误：400 Bad Request。

query_recorder​

GET /plugins/<tag>/records​

按 created_at_ms 倒序返回 recorder 主表中的记录列表，不包含 steps。

查询参数：

  • cursor=<created_at_ms>:<id>
    • 用于继续向后翻页。
  • limit=<n>
    • 默认 100，最大 500。
  • since_ms=<unix_ms>
    • 仅返回大于等于该时间的记录。
  • until_ms=<unix_ms>
    • 仅返回小于等于该时间的记录。

返回：

  • 200 OK
    • JSON，形如：
{
  "ok": true,
  "next_cursor": "1713510000123:42",
  "records": [
    {
      "id": 42,
      "created_at_ms": 1713510000123,
      "elapsed_ms": 12,
      "request_id": 1234,
      "client_ip": "192.0.2.10",
      "questions_json": [
        { "name": "www.example.com.", "qtype": "A", "qclass": "IN" }
      ],
      "req_rd": true,
      "req_cd": false,
      "req_ad": false,
      "req_opcode": "Query",
      "req_edns_json": null,
      "error": null,
      "has_response": true,
      "rcode": "NoError",
      "resp_aa": false,
      "resp_tc": false,
      "resp_ra": true,
      "resp_ad": false,
      "resp_cd": false,
      "answer_count": 1,
      "authority_count": 0,
      "additional_count": 0,
      "answers_json": [
        {
          "name": "www.example.com.",
          "class": "IN",
          "ttl": 300,
          "rr_type": "A",
          "payload_kind": "A",
          "payload_text": "192.0.2.1",
          "payload": { "ip": "192.0.2.1" }
        }
      ],
      "authorities_json": [],
      "additionals_json": [],
      "signature_json": [],
      "resp_edns_json": null
    }
  ]
}

GET /plugins/<tag>/records/<id>​

返回单条完整记录，并附带 steps 路径事件数组。

返回：

  • 200 OK
    • JSON，包含 record 对象；其中 record.record 为主表字段，record.steps 为路径事件。
  • 404 Not Found
    • 记录不存在。

GET /plugins/<tag>/stats/overview​

返回 recorder 概览统计。

查询参数：

  • since_ms=<unix_ms>
  • until_ms=<unix_ms>

返回字段：

  • query_total
  • error_total
  • dropped_total
  • avg_elapsed_ms

GET /plugins/<tag>/stats/plugins​

按路径事件聚合插件命中情况。

查询参数：

  • since_ms=<unix_ms>
  • until_ms=<unix_ms>
  • kind=matcher|executor|builtin|all

返回字段：

  • kind
  • tag
  • evaluated
  • matched
  • executed
  • query_total
  • query_share

GET /plugins/<tag>/stream​

通过 SSE 推送新写入的完整记录。

查询参数：

  • tail=<n>
    • 先回放最近 n 条内存 tail，再持续推送新记录。

说明：

  • event: record 的 data 为完整 RecordDetail JSON。
  • 会定期发送 heartbeat 注释帧以保持长连接。

Prometheus 指标​

GET /metrics​

当配置了至少一个 metrics_collector 且 API 已启用时，会注册该接口。

当前导出的指标包括：

  • forgedns_query_total
  • forgedns_query_error_total
  • forgedns_query_inflight
  • forgedns_query_latency_count
  • forgedns_query_latency_sum_ms

这些指标带有插件级标签信息，可用于区分不同流水线观测点。

配置参考​

最小可用管理面​

api:
  http: "127.0.0.1:9088"

适用场景：

  • 本机运维
  • 进程自检
  • 指标抓取

受保护控制面​

api:
  http:
    listen: "0.0.0.0:9443"
    ssl:
      cert: "/etc/forgedns/api.crt"
      key: "/etc/forgedns/api.key"
    auth:
      type: basic
      username: "admin"
      password: "secret"

适用场景：

  • 远程控制
  • 与上层运维平台集成

双向认证控制面​

api:
  http:
    listen: "0.0.0.0:9443"
    ssl:
      cert: "/etc/forgedns/api.crt"
      key: "/etc/forgedns/api.key"
      client_ca: "/etc/forgedns/client-ca.crt"
      require_client_cert: true

适用场景：

  • 严格受控的自动化系统
  • 多租户或高敏感运维环境