API 调用

概述

JXWAF 云 WAF 管理控制台提供 Admin API（/admin_api/），用于自动化运维与二次开发，包括子账号（业务部门）批量开通、网站接入配置管理、域名接入、全局名单维护、业务数据查询等。

用户控制台对接接口（/user/ API）详见 用户控制台定制开发指南。

一、启用与认证

1.1 启用配置

• 管理控制台出厂 docker-compose.yml 默认已设 ADMIN_API_ENABLE: "false"，生产环境如需调用请改为 "true"
• 白名单项可为 IP 或域名；域名会被解析为 IP 后匹配，解析结果缓存 300 秒

1.2 认证方式

通过 HTTP 请求头 jxwaf-waf-auth 携带主账号 waf_auth：

jxwaf-waf-auth: <waf_auth_token>

waf_auth 可在管理控制台 系统管理 → 基础配置 查看。请求头名称使用连字符（下划线请求头会被丢弃）。

1.3 请求与响应格式

• Method：POST（约定使用 POST）
• Content-Type：application/json
• Body：JSON 格式，参数通过 JSON Body 传递

请求示例：

curl -X POST http://<host>/admin_api/get_sub_account_list \
  -H "jxwaf-waf-auth: <your_waf_auth>" \
  -H "Content-Type: application/json" \
  -d '{"page": 1}'

响应格式（统一 HTTP 200，通过 result 判断成败）：

通用错误响应：

二、接口清单

以下接口路径前需加 /admin_api 前缀。除特别说明外，所有接口均需 jxwaf-waf-auth 认证。

子账号管理

网站接入配置管理

域名管理

防护配置（子账号维度）

自定义配置（子账号维度）：/get_sub_account_custom_request_header_*、/get_sub_account_custom_response_header_*、/get_sub_account_custom_response_content_*、/get_sub_account_custom_upstream_address_*（每类含 list/get/create/edit/delete/edit_status/exchange_priority）

SSL 证书：/get_sub_account_ssl_manage_list、/create_sub_account_ssl_manage、/request_wildcard_cert、/retry_sub_account_ssl_cert、/edit_sub_account_ssl_cert_config 等

缓存管理：/get_sub_account_cache_policy_*、/get_sub_account_no_cache_policy_*、/get_sub_account_cache_bypass_policy_*、/create_cache_warmup_task、/get_cache_warmup_list、/create_cache_refresh_task、/get_cache_refresh_list 等

全局名单与防护组件

系统配置：/get_sys_log_conf / /edit_sys_log_conf（日志传输）、/get_sys_report_conf_conf / /edit_sys_report_conf_conf / /test_sys_report_conf_conf（日志查询）、/get_sys_custom_page_conf / /edit_sys_custom_page_conf（拦截页面）、/get_sys_webtds_check_conf / /edit_sys_webtds_check_conf（WebTDS）、/waf_conf_backup / /waf_conf_load（配置备份/加载）

SOC 安全运营：/get_soc_usage_stat_*、/get_soc_web_attack_*、/get_soc_flow_attack_*、/get_soc_attack_event_list、/get_soc_log_query_list、/get_soc_network_ip_* 等

节点监控：/get_node_monitor_list、/delete_node_monitor

三、关键接口详解

3.1 创建子账号

接口地址：POST /admin_api/create_sub_account

请求参数：

请求示例：

curl -X POST http://<host>/admin_api/create_sub_account \
  -H "jxwaf-waf-auth: <your_waf_auth>" \
  -H "Content-Type: application/json" \
  -d '{
    "sub_user_name": "client01",
    "user_password": "password123",
    "sub_otp_auth": "false",
    "website_access_conf": "default_conf"
  }'

返回示例：

{
  "result": true,
  "message": "create success"
}

当 sub_otp_auth 为 "true" 时，返回额外包含 OTP 绑定信息：

{
  "result": true,
  "message": "create success",
  "otp_secret_key": "<base32密钥>",
  "otp_auth_url": "otpauth://totp/..."
}

错误示例：

3.2 获取子账号列表

接口地址：POST /admin_api/get_sub_account_list

请求参数：

返回参数：

返回示例：

{
  "result": true,
  "records": [
    {
      "sub_user_name": "client01",
      "waf_auth": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "sub_otp_auth": "false",
      "website_access_conf": "default_conf",
      "domain_count": 3,
      "ssl_cert_count": 2,
      "web_engine_status": "true",
      "flow_engine_status": "false"
    }
  ],
  "page": 1,
  "total_pages": 1,
  "total_records": 1
}

如需一次性获取全部子账号（无分页），可调用 /admin_api/api_get_sub_account_list（无需 page 参数），返回 records 含 user_name, sub_user_name, sub_otp_auth, waf_auth, website_access_conf。

3.3 重置子账号 waf_auth

接口地址：POST /admin_api/edit_sub_account_waf_auth

请求参数：

返回示例：

{
  "result": true,
  "message": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

新 waf_auth 通过 message 字段返回。重置后，原 waf_auth 立即失效，使用该子账号的用户控制台会话需重新登录。

3.4 创建网站接入配置

接口地址：POST /admin_api/create_website_access_conf

请求参数：

返回示例：

{
  "result": true,
  "message": "create success"
}

创建接入配置后可调用 /admin_api/website_access_conf_connect_test（参数同上）验证 DNS 凭据是否有效。

3.5 创建域名

接口地址：POST /admin_api/create_domain

请求参数：

返回示例：

{
  "result": true,
  "message": "create success"
}

创建域名时，系统自动完成 WAF 侧 DNS 配置并生成 CNAME 接入值。子账号必须已绑定接入配置。

错误示例：

3.6 获取域名列表

接口地址：POST /admin_api/get_domain_list

请求参数：

返回 records 字段：

3.7 全局名单管理

创建全局名单

接口地址：POST /admin_api/create_global_name_list

请求参数：

返回示例：

{
  "result": true,
  "message": "create success"
}

添加名单条目

接口地址：POST /admin_api/create_global_name_list_item

请求参数：

返回示例：

新增成功：

{"result": true, "message": "create_success"}

条目已存在（刷新过期时间）：

{"result": true, "message": "edit_success"}

错误示例：

{"result": false, "message": "name_list_name 不存在"}

获取名单条目列表

接口地址：POST /admin_api/get_name_list_item_list_list

请求参数：

返回参数：

返回示例：

{
  "result": true,
  "records": [
    {
      "name_list_name": "blacklist",
      "name_list_item": "192.168.1.100",
      "name_list_expire": "86400",
      "name_list_item_expire_time": 1735776000
    }
  ],
  "page": 1,
  "total_pages": 1,
  "total_records": 1
}

删除名单条目

接口地址：POST /admin_api/delete_global_name_list_item

请求参数：

返回示例：

{"result": true, "message": "删除成功"}

3.8 业务数据统计概览

接口地址：POST /admin_api/get_soc_usage_stat_overview

请求参数：

返回参数：

返回示例：

{
  "result": true,
  "overview": {
    "total_request": 125000,
    "traffic_in": 5242880,
    "traffic_out": 10485760,
    "status_2xx": 120000,
    "status_3xx": 2000,
    "status_4xx": 2500,
    "status_5xx": 500,
    "request_latency_avg": 35,
    "upstream_latency_avg": 120
  },
  "status_detail": {
    "200": 118000,
    "301": 2000,
    "404": 2400,
    "500": 500
  },
  "from_time": "2026-08-01 00:00:00",
  "to_time": "2026-08-01 23:59:59"
}

3.9 节点状态列表

接口地址：POST /admin_api/get_node_monitor_list

请求参数：无（仅需 jxwaf-waf-auth 认证）

返回参数：

返回示例：

{
  "result": true,
  "message": [
    {
      "node_uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "node_hostname": "node-01",
      "node_ip": "1.1.1.1",
      "node_status": "true",
      "node_status_update_time": 1722470400,
      "waf_conf_update_time": 1722470300
    }
  ]
}

四、使用场景

场景1：批量开通部门

IT 运维团队通过 API 自动化开通部门：先创建接入配置，再创建子账号并绑定。

# 1. 创建网站接入配置
curl -X POST http://<host>/admin_api/create_website_access_conf \
  -H "jxwaf-waf-auth: <your_waf_auth>" \
  -H "Content-Type: application/json" \
  -d '{
    "website_access_conf_name": "default_conf",
    "website_access_conf_detail": "默认接入配置",
    "website_access_conf_type": "aliyun",
    "website_access_conf_api_key": "<AccessKey ID>",
    "website_access_conf_api_secret": "<AccessKey Secret>",
    "website_access_conf_domain": "acc.jxwaf.com",
    "website_access_conf_ip_list": "[\"1.1.1.1\",\"2.2.2.2\"]",
    "website_access_conf_ttl": "600",
    "resource_quota_enable": "false"
  }'

# 2. 创建子账号并绑定接入配置
curl -X POST http://<host>/admin_api/create_sub_account \
  -H "jxwaf-waf-auth: <your_waf_auth>" \
  -H "Content-Type: application/json" \
  -d '{
    "sub_user_name": "client01",
    "user_password": "password123",
    "sub_otp_auth": "false",
    "website_access_conf": "default_conf"
  }'

场景2：通过外部系统自动封禁攻击 IP

当安全设备检测到攻击行为时，调用名单条目接口自动将攻击 IP 加入黑名单：

# 添加攻击 IP 到黑名单（已存在则刷新过期时间）
curl -X POST http://<host>/admin_api/create_global_name_list_item \
  -H "jxwaf-waf-auth: <your_waf_auth>" \
  -H "Content-Type: application/json" \
  -d '{
    "name_list_name": "auto_blacklist",
    "name_list_item": "203.0.113.50"
  }'

解封特定 IP：

curl -X POST http://<host>/admin_api/delete_global_name_list_item \
  -H "jxwaf-waf-auth: <your_waf_auth>" \
  -H "Content-Type: application/json" \
  -d '{
    "name_list_name": "auto_blacklist",
    "name_list_item": "203.0.113.50"
  }'

场景3：域名接入自动化

通过 Admin API 为子账号创建域名：

curl -X POST http://<host>/admin_api/create_domain \
  -H "jxwaf-waf-auth: <your_waf_auth>" \
  -H "Content-Type: application/json" \
  -d '{
    "sub_user_name": "client01",
    "domain": "demo.jxwaf.com",
    "http": "true",
    "https": "true",
    "ssl_domain": "demo.jxwaf.com",
    "source_ip": "[\"1.2.3.4\"]",
    "source_http_port": "80",
    "source_https_port": "443",
    "origin_protocol": "http",
    "balance_type": "round_robin",
    "pre_proxy": "false",
    "real_ip_conf": "X-Real-IP",
    "connect_timeout": "5",
    "send_timeout": "60",
    "read_timeout": "60",
    "detail": "演示站点"
  }'

创建后调用 /admin_api/get_domain_list 获取 cname 值。部门在用户控制台配置 DNS 自动接入后，系统自动完成 CNAME 解析。

场景4：查询业务运行数据

查询指定部门某时间段的业务统计概览：

curl -X POST http://<host>/admin_api/get_soc_usage_stat_overview \
  -H "jxwaf-waf-auth: <your_waf_auth>" \
  -H "Content-Type: application/json" \
  -d '{
    "from_time": "2026-08-01 00:00:00",
    "to_time": "2026-08-01 23:59:59",
    "sub_user_name": "client01"
  }'