跳到主要内容

配置接口

配置 API 可读取、保存、检查和校验 YAML。生产变更应先校验、备份原配置，再 reload 并检查状态。

配置检查接口​

GET /api/config​

作用：

  • 读取当前启动参数指向的配置文件原文。
  • 返回 YAML 文本、配置路径、内容版本和文件更新时间。
  • 不展开环境变量占位符；响应中的 content 与磁盘文件保持一致。

返回示例：

{
  "ok": true,
  "path": "/etc/oxidns/config.yaml",
  "format": "yaml",
  "content": "plugins:\n  - tag: forward\n    type: forward\n",
  "version": "sha256-hex",
  "updated_at_ms": 1760000000000
}

PUT /api/config​

作用：

  • 保存完整 YAML 配置文件。
  • 保存前默认执行与 POST /api/config/validate 相同的校验。
  • 可在保存成功后触发一次应用级 reload。
  • 保存时写入请求中的原始文本，不会把 ${VAR} 展开后的值落盘。

请求体：

{
  "format": "yaml",
  "content": "plugins:\n  - tag: debug_main\n    type: debug_print\n",
  "base_version": "sha256-hex",
  "validate": true,
  "reload": false
}

返回：

  • 200 OK
    • 配置已保存，返回新版本、插件数量和初始化顺序。
  • 400 Bad Request
    • YAML 无法解析、配置校验失败，或 format 不是 yaml。
  • 409 Conflict
    • base_version 与当前文件版本不一致，或保存后请求 reload 时已有 reload 正在进行。

GET /api/config/check​

作用：

  • 校验当前配置文件路径对应的配置文件。
  • 校验时会在内存中展开环境变量占位符，但不会修改磁盘文件。

适用场景：

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

POST /api/config/validate​

作用：

  • 直接校验请求体中的 YAML 配置文本。
  • 同时支持 PUT /api/config 使用的 JSON 包装格式。
  • 校验时会在内存中展开环境变量占位符，但不会返回或保存展开后的配置。

请求体要求：

  • UTF-8 YAML 文本且非空；或
  • JSON：{"format":"yaml","content":"...yaml..."}

适用场景：

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