DNS-Go

主题

API 密钥管理 ​

API Key 接口用于管理 API 密钥的增删改查和状态切换。API Key 认证通过 X-API-Key 请求头传递，适用于第三方系统对接。

获取 API Key 列表 ​

请求 ​

http
GET /api/apikey/list?page=1&page_size=20&keyword=
Authorization: Bearer {token}

查询参数：

参数类型必填默认值说明
pageint❌1页码
page_sizeint❌20每页数量（最大 100）
keywordstring❌-搜索关键词（名称/前缀）

响应 ​

成功响应（200）：

json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "total": 10,
    "items": [
      {
        "id": 1,
        "name": "第三方系统对接",
        "key_prefix": "dnsgo_a1b2c3d4...",
        "description": "用于第三方 DNS 管理系统的 API 对接",
        "allowed_ips": "",
        "status": "active",
        "created_by": 1,
        "last_used_at": 1705300000,
        "created_at": 1705300000,
        "updated_at": 1705300000
      }
    ]
  }
}

字段说明：

字段类型说明
idint密钥 ID
namestring密钥名称
key_prefixstring密钥前缀（仅前 10 位）
descriptionstring密钥描述
allowed_ipsstringIP 白名单，逗号分隔
statusstring状态: active 启用, disabled 禁用
created_byint创建者用户 ID
last_used_atint最后使用时间戳（秒），0 表示从未使用
created_atint创建时间戳（秒）
updated_atint更新时间戳（秒）

获取 API Key 详情 ​

请求 ​

http
GET /api/apikey/{id}
Authorization: Bearer {token}

响应 ​

成功响应（200）：

json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "name": "第三方系统对接",
    "key_prefix": "dnsgo_a1b2c3d4...",
    "description": "用于第三方 DNS 管理系统的 API 对接",
    "allowed_ips": "",
    "status": "active",
    "created_by": 1,
    "last_used_at": 1705300000,
    "created_at": 1705300000,
    "updated_at": 1705300000
  }
}

创建 API Key ​

请求 ​

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

请求体：

json
{
  "name": "第三方系统对接",
  "description": "用于第三方 DNS 管理系统的 API 对接（可选）",
  "allowed_ips": "192.168.1.100,10.0.0.0/8"
}

参数说明：

参数类型必填说明
namestring✅密钥名称（最大 128 字符）
descriptionstring❌密钥描述（最大 512 字符）
allowed_ipsstring❌IP 白名单，逗号分隔，留空则不限制

响应 ​

成功响应（200）：

json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "name": "第三方系统对接",
    "key_prefix": "dnsgo_a1b2c3d4...",
    "key": "dnsgo_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6",
    "description": "用于第三方 DNS 管理系统的 API 对接",
    "allowed_ips": "192.168.1.100,10.0.0.0/8",
    "status": "active",
    "created_by": 1,
    "last_used_at": 0,
    "created_at": 1705300000,
    "updated_at": 1705300000
  }
}

⚠️ 注意：key 字段仅在创建时返回，且只展示一次。请立即保存。

更新 API Key ​

请求 ​

http
PUT /api/apikey/{id}
Authorization: Bearer {token}
Content-Type: application/json

请求体（全部可选，只传需要修改的字段）：

json
{
  "name": "新名称",
  "description": "新描述",
  "allowed_ips": "10.0.0.0/8",
  "status": "disabled"
}

参数说明：

参数类型必填可取值说明
namestring❌-密钥名称
descriptionstring❌-密钥描述
allowed_ipsstring❌-IP 白名单，传空字符串清除白名单
statusstring❌active, disabled密钥状态

响应 ​

成功响应（200）：

json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1
  }
}

切换 API Key 状态 ​

请求 ​

http
PUT /api/apikey/{id}/toggle
Authorization: Bearer {token}
Content-Type: application/json

请求体：

json
{
  "status": "disabled"
}

参数说明：

参数类型必填可取值
statusstring✅active, disabled

响应 ​

成功响应（200）：

json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1,
    "status": "disabled"
  }
}

删除 API Key ​

请求 ​

http
DELETE /api/apikey/{id}
Authorization: Bearer {token}

响应 ​

成功响应（200）：

json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": 1
  }
}

使用示例 ​

API Key 认证方式 ​

API Key 通过 X-API-Key 请求头传递，与 JWT Token 认证并存：

bash
# 使用 API Key 调用接口
curl http://localhost:8085/api/system/info \
  -H "X-API-Key: dnsgo_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

# 也可以查询域名列表
curl "http://localhost:8085/api/domain/list?page=1&page_size=20" \
  -H "X-API-Key: dnsgo_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6"

JavaScript 示例 ​

javascript
// 使用 API Key 调用接口
const API_KEY = 'dnsgo_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6';
const BASE_URL = 'http://localhost:8085';

const apiCall = async (path) => {
  const response = await fetch(`${BASE_URL}${path}`, {
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    }
  });
  return response.json();
};

// 获取系统信息
console.log(await apiCall('/api/system/info'));

// 查询域名列表
console.log(await apiCall('/api/domain/list?page=1&page_size=20'));

Python 示例 ​

python
import requests

class DNSGoClient:
    def __init__(self, base_url='http://localhost:8085', api_key=None):
        self.base_url = base_url
        self.headers = {'X-API-Key': api_key} if api_key else {}
    
    def get(self, path):
        response = requests.get(
            f'{self.base_url}{path}',
            headers={**self.headers, 'Content-Type': 'application/json'}
        )
        return response.json()
    
    def post(self, path, data=None):
        response = requests.post(
            f'{self.base_url}{path}',
            headers={**self.headers, 'Content-Type': 'application/json'},
            json=data
        )
        return response.json()

# 使用 API Key 认证（无需登录）
client = DNSGoClient(api_key='dnsgo_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6')

# 获取系统信息
info = client.get('/api/system/info')
print(info)

# 获取域名列表
domains = client.get('/api/domain/list?page=1&page_size=20')
print(domains)

# 创建域名记录（需要有写权限）
result = client.post('/api/domain/create', {
    'domain': 'example.com',
    'type': 'A',
    'value': '1.2.3.4'
})
print(result)

错误码说明 ​

错误码说明处理建议
400请求参数错误检查必填字段和格式
401API Key 无效或已禁用检查密钥是否正确，是否被禁用
403客户端 IP 不在白名单中检查密钥的 IP 白名单配置
404API Key 不存在检查密钥 ID 是否正确
500服务器内部错误查看服务器日志

相关文档 ​

基于 MIT 许可发布

Copyright © 2025 坐公交也用券