上游管理接口

上游 DNS 服务器和策略相关的 API 接口。

上游 DNS 管理

获取上游列表

获取所有上游 DNS 服务器的列表。

GET /api/upstream/list?page=1&pageSize=20
Authorization: Bearer {token}

查询参数：

参数	类型	必填	说明
page	int	❌	页码，默认 1
pageSize	int	❌	每页数量，默认 20

响应：

{
  "code": 200,
  "data": {
    "list": [
      {
        "id": 1,
        "name": "阿里云 DNS",
        "server": "223.5.5.5",
        "port": 53,
        "protocol": "udp",
        "weight": 100,
        "description": "阿里云公共 DNS",
        "health_status": "healthy",
        "created_at": "2025-01-15T10:30:00Z"
      }
    ],
    "total": 5
  }
}

创建上游

添加新的上游 DNS 服务器。

POST /api/upstream/create
Authorization: Bearer {token}
Content-Type: application/json

请求体：

{
  "name": "腾讯云 DNS",
  "server": "119.29.29.29",
  "port": 53,
  "protocol": "udp",
  "weight": 100,
  "description": "腾讯云公共 DNS"
}

参数说明：

参数	类型	必填	说明
name	string	✅	上游名称
server	string	✅	DNS 服务器 IP 地址
port	int	❌	端口，默认 53
protocol	string	❌	协议：udp/tcp，默认 udp
weight	int	❌	权重，默认 100
description	string	❌	描述

响应：

{
  "code": 200,
  "message": "创建成功",
  "data": {
    "id": 2,
    "name": "腾讯云 DNS",
    "server": "119.29.29.29",
    "port": 53,
    "protocol": "udp",
    "weight": 100,
    "description": "腾讯云公共 DNS",
    "health_status": "unknown"
  }
}

更新上游

更新上游 DNS 服务器配置。

PUT /api/upstream/update/:id
Authorization: Bearer {token}
Content-Type: application/json

请求体：

{
  "name": "阿里云 DNS",
  "server": "223.5.5.5",
  "weight": 150
}

删除上游

删除上游 DNS 服务器。

DELETE /api/upstream/delete/:id
Authorization: Bearer {token}

响应：

{
  "code": 200,
  "message": "删除成功"
}

健康检查

获取上游健康状态

获取所有上游 DNS 的健康状态。

GET /api/upstream/list/health
Authorization: Bearer {token}

响应：

{
  "code": 200,
  "data": {
    "list": [
      {
        "id": 1,
        "upstream_id": 1,
        "upstream_name": "阿里云 DNS",
        "status": "healthy",
        "last_check": "2025-01-15T10:30:00Z",
        "response_time": 23,
        "success_count": 150,
        "fail_count": 2
      }
    ]
  }
}

执行健康检查

手动触发对所有上游的健康检查。

POST /api/UpstreamHealthCheck/check
Authorization: Bearer {token}

响应：

{
  "code": 200,
  "message": "健康检查已触发"
}

获取健康检查配置

获取健康检查的配置信息。

GET /api/UpstreamHealthCheck/domain
Authorization: Bearer {token}

响应：

{
  "code": 200,
  "data": {
    "domain": "www.baidu.com",
    "type": "A",
    "interval": 30,
    "timeout": 5
  }
}

更新健康检查配置

更新健康检查的配置。

PUT /api/UpstreamHealthCheck/domain
Authorization: Bearer {token}
Content-Type: application/json

请求体：

{
  "domain": "www.baidu.com",
  "type": "A",
  "interval": 30,
  "timeout": 5
}

使用示例

cURL 示例

TOKEN="your_jwt_token"

# 获取上游列表
curl -s "http://localhost:8085/api/upstream/list" \
  -H "Authorization: Bearer $TOKEN" | jq

# 创建上游
curl -s -X POST "http://localhost:8085/api/upstream/create" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "114 DNS",
    "server": "114.114.114.114",
    "port": 53,
    "protocol": "udp",
    "weight": 50,
    "description": "114 公共 DNS"
  }' | jq

# 更新上游权重
curl -s -X PUT "http://localhost:8085/api/upstream/update/1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"weight": 200}' | jq

# 删除上游
curl -s -X DELETE "http://localhost:8085/api/upstream/delete/1" \
  -H "Authorization: Bearer $TOKEN" | jq

# 获取健康状态
curl -s "http://localhost:8085/api/upstream/list/health" \
  -H "Authorization: Bearer $TOKEN" | jq

# 执行健康检查
curl -s -X POST "http://localhost:8085/api/UpstreamHealthCheck/check" \
  -H "Authorization: Bearer $TOKEN" | jq

Python 示例

import requests

class DNSGoUpstreamAPI:
    def __init__(self, base_url, token):
        self.base_url = base_url
        self.headers = {'Authorization': f'Bearer {token}'}
    
    def list_upstreams(self, page=1, page_size=20):
        params = {'page': page, 'pageSize': page_size}
        response = requests.get(
            f'{self.base_url}/api/upstream/list',
            headers=self.headers,
            params=params
        )
        return response.json()
    
    def create_upstream(self, name, server, port=53, protocol='udp', 
                       weight=100, description=''):
        data = {
            'name': name,
            'server': server,
            'port': port,
            'protocol': protocol,
            'weight': weight,
            'description': description
        }
        response = requests.post(
            f'{self.base_url}/api/upstream/create',
            headers={**self.headers, 'Content-Type': 'application/json'},
            json=data
        )
        return response.json()
    
    def get_health_status(self):
        response = requests.get(
            f'{self.base_url}/api/upstream/list/health',
            headers=self.headers
        )
        return response.json()
    
    def check_health(self):
        response = requests.post(
            f'{self.base_url}/api/UpstreamHealthCheck/check',
            headers=self.headers
        )
        return response.json()

# 使用示例
api = DNSGoUpstreamAPI('http://localhost:8085', 'your_token')

# 添加上游
result = api.create_upstream(
    name='Google DNS',
    server='8.8.8.8',
    weight=100,
    description='Google 公共 DNS'
)
print(result)

# 查看健康状态
health = api.get_health_status()
print(health)

相关文档

• 上游策略 - 了解上游管理功能
• 健康检查 - 了解健康检查机制