API参考

详细了解绮梦DNS的API接口

API目录

1. 认证API

认证API用于用户登录、登出和密码修改，采用基于会话的认证机制。

用户登录

POST
/api/login

请求体：

{"username": "admin", "password": "admin"}

响应示例：

{"status": "success", "message": "登录成功"}

用户登出

POST
/api/logout

响应示例：

{"status": "success", "message": "注销成功"}

修改密码

POST
/api/change-password

请求体：

{"currentPassword": "oldpass", "newPassword": "newpass"}

响应示例：

{"status": "success", "message": "密码修改成功"}

2. 屏蔽规则API

获取Shield配置和统计

GET
/api/shield

查询参数：

参数名 类型 必填 描述
all boolean 否 是否返回完整规则列表

响应示例：

{"updateInterval": 3600, "blockMethod": "NXDOMAIN", "blacklistCount": 4, "domainRulesCount": 1000, "domainExceptionsCount": 50, "regexRulesCount": 100, "regexExceptionsCount": 10, "hostsRulesCount": 20}

获取本地规则

GET
/api/shield/localrules

响应示例：

["example.com", ".*\\.test\\.com"]

获取远程规则

GET
/api/shield/remoterules

响应示例：

["ads.example.com", "tracking.example.com"]

Hosts规则管理

GET/POST/DELETE
/api/shield/hosts

获取Hosts规则：

{"hosts": [{"domain": "localhost", "ip": "127.0.0.1"}], "hostsCount": 1}

添加Hosts规则：

{"ip": "192.168.1.1", "domain": "router.local"}

删除Hosts规则：

{"domain": "router.local"}

黑名单管理

GET/POST/PUT/DELETE
/api/shield/blacklists

获取黑名单列表：

[{"name": "AdGuard DNS filter", "url": "https://example.com/filter.txt", "enabled": true, "lastUpdateTime": "2025-12-16T10:00:00Z"}]

添加黑名单：

{"name": "New Blacklist", "url": "https://example.com/new-filter.txt"}

3. DNS查询API

DNS查询

GET
/api/query?domain=example.com

查询参数：

参数名 类型 必填 描述
domain string 是 要查询的域名

响应示例：

{"domain": "example.com", "blocked": false, "reason": "", "timestamp": "2025-12-16T10:00:00Z"}

4. 系统状态API

获取系统状态

GET
/api/status

响应示例：

{"status": "running", "queries": 1000, "blocked": 200, "allowed": 800, "errors": 5, "lastQuery": "2025-12-16T10:00:00Z", "avgResponseTime": 15.5, "activeIPs": 10, "startTime": "2025-12-16T00:00:00Z", "uptime": 3600000, "cpuUsage": 5.2, "timestamp": "2025-12-16T10:00:00Z"}

获取配置信息

GET
/api/config

响应示例：

{"shield": {"blockMethod": "NXDOMAIN", "customBlockIP": "", "blacklists": [{"name": "AdGuard DNS filter", "url": "https://example.com/filter.txt", "enabled": true}], "updateInterval": 3600}}

重启服务

POST
/api/config/restart

响应示例：

{"status": "success", "message": "服务已重启"}

6. 查询日志API

获取日志统计

GET
/api/logs/stats

响应示例：

{"total": 1000, "allowed": 800, "blocked": 200, "errors": 5, "today": 100}

获取查询日志

GET
/api/logs/query

查询参数：

参数名 类型 必填 描述
limit int 否 返回记录数，默认100
offset int 否 偏移量，默认0
sort string 否 排序字段，默认time
direction string 否 排序方向，asc或desc，默认desc
result string 否 结果过滤：allowed, blocked, error
search string 否 搜索关键词

响应示例：

[{"id": 1, "time": "2025-12-16T10:00:00Z", "domain": "example.com", "type": "A", "result": "allowed", "clientIP": "192.168.1.2", "responseTime": 15.5}, {"id": 2, "time": "2025-12-16T09:59:00Z", "domain": "ads.example.com", "type": "A", "result": "blocked", "clientIP": "192.168.1.3", "responseTime": 10.2}]

获取日志计数

GET
/api/logs/count

响应示例：

{"count": 1000}

5. 统计数据API

获取实时统计

GET
/api/stats

响应示例：

{"dns": {"Queries": 1000, "Blocked": 200, "Allowed": 800, "Errors": 5, "LastQuery": "2025-12-16T10:00:00Z", "AvgResponseTime": 15.5, "TotalResponseTime": 15500, "QueryTypes": {"A": 600, "AAAA": 200, "CNAME": 100, "MX": 50, "NS": 50}, "SourceIPs": ["192.168.1.2", "192.168.1.3"], "CpuUsage": 5.2, "DNSSECQueries": 500, "DNSSECSuccess": 450, "DNSSECFailed": 50, "DNSSECEnabled": true}, "shield": {"domainRules": 1000, "domainExceptions": 50, "regexRules": 100, "regexExceptions": 10, "hostsRules": 20}, "topQueryType": "A", "activeIPs": 10, "avgResponseTime": 15.5, "cpuUsage": 5.2, "dnssecEnabled": true, "dnssecQueries": 500, "dnssecSuccess": 450, "dnssecFailed": 50, "dnssecUsage": 50.0, "time": "2025-12-16T10:00:00Z"}}

获取最常屏蔽域名

GET
/api/top-blocked

响应示例：

[{"domain": "ads.example.com", "count": 100}, {"domain": "tracking.example.com", "count": 80}]

获取最常解析域名

GET
/api/top-resolved

响应示例：

[{"domain": "example.com", "count": 200}, {"domain": "google.com", "count": 150}]

获取最活跃客户端

GET
/api/top-clients

响应示例：

[{"ip": "192.168.1.2", "count": 500, "lastSeen": "2025-12-16T10:00:00Z"}, {"ip": "192.168.1.3", "count": 300, "lastSeen": "2025-12-16T09:59:00Z"}]

获取最常查询域名

GET
/api/top-domains

响应示例：

[{"domain": "example.com", "count": 300, "dnssec": true}, {"domain": "google.com", "count": 250, "dnssec": true}]

获取最近屏蔽域名

GET
/api/recent-blocked

响应示例：

[{"domain": "ads.example.com", "time": "10:00:00"}, {"domain": "tracking.example.com", "time": "09:59:00"}]

获取24小时统计

GET
/api/hourly-stats

响应示例：

{"labels": ["00:00", "01:00", ..., "23:00"], "data": [10, 15, ..., 25]}

获取每日统计

GET
/api/daily-stats

响应示例：

{"labels": ["12-01", "12-02", ..., "12-07"], "data": [100, 150, ..., 300]}

获取每月统计

GET
/api/monthly-stats

响应示例：

{"labels": ["11-17", "11-18", ..., "12-16"], "data": [50, 80, ..., 300]}

获取查询类型统计

GET
/api/query/type

响应示例：

[{"type": "A", "count": 600}, {"type": "AAAA", "count": 200}, {"type": "CNAME", "count": 100}]

7. WebSocket API

实时统计推送

WebSocket连接用于实时推送统计数据和系统状态。

ws://localhost:8080/ws/stats

消息格式：

{"type": "stats_update", "data": {"dns": {"Queries": 1000, "Blocked": 200}, "shield": {"domainRules": 1000}}, "time": "2025-12-16T10:00:00Z"}

消息类型：

  • initial_data：初始数据推送
  • stats_update：实时统计数据更新

8. Swagger UI

系统提供了Swagger UI用于更直观地浏览和测试API。

http://localhost:8080/api/index.html

Swagger UI提供了以下功能：

  • 完整的API文档浏览
  • 在线API测试
  • 请求和响应格式示例
  • API版本管理

注意：访问Swagger UI需要先登录系统。