API 文档

DNS-Go 提供完整的 RESTful API，支持域名管理、解析记录、上游配置等所有功能。

基础信息

• 基础 URL: http://localhost:8085/api/v1
• 认证方式: JWT Token
• 请求格式: JSON
• 响应格式: JSON

认证

所有 API 请求（除登录外）都需要在请求头中携带 JWT Token：

Authorization: Bearer <your-jwt-token>

获取 Token

curl -X POST http://localhost:8085/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "admin123",
    "captcha_id": "",
    "captcha_code": ""
  }'

响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_at": "2025-01-01T12:00:00Z"
  }
}

响应格式

成功响应

{
  "code": 200,
  "message": "success",
  "data": { }
}

错误响应

{
  "code": 400,
  "message": "请求参数错误",
  "data": null
}

状态码

状态码	说明
200	成功
400	请求参数错误
401	未授权
403	禁止访问
404	资源不存在
500	服务器内部错误

API 列表

认证相关

方法	路径	说明
POST	/auth/login	用户登录
POST	/auth/logout	用户登出
POST	/auth/refresh	刷新 Token
GET	/auth/captcha	获取验证码

域名管理

方法	路径	说明
GET	/domains	获取域名列表
POST	/domains	创建域名
GET	/domains/:id	获取域名详情
PUT	/domains/:id	更新域名
DELETE	/domains/:id	删除域名
POST	/domains/import	批量导入
GET	/domains/export	批量导出

解析记录

方法	路径	说明
GET	/domains/:id/records	获取记录列表
POST	/domains/:id/records	创建记录
GET	/records/:id	获取记录详情
PUT	/records/:id	更新记录
DELETE	/records/:id	删除记录

上游管理

方法	路径	说明
GET	/upstreams	获取上游列表
POST	/upstreams	创建上游
GET	/upstreams/:id	获取上游详情
PUT	/upstreams/:id	更新上游
DELETE	/upstreams/:id	删除上游

策略管理

方法	路径	说明
GET	/strategies	获取策略列表
POST	/strategies	创建策略
GET	/strategies/:id	获取策略详情
PUT	/strategies/:id	更新策略
DELETE	/strategies/:id	删除策略

查询日志

方法	路径	说明
GET	/logs/query	获取查询日志
GET	/logs/stats	获取统计信息
DELETE	/logs/clear	清理日志

系统监控

方法	路径	说明
GET	/monitor/system	系统资源
GET	/monitor/dns	DNS 统计
GET	/monitor/cache	缓存统计

用户管理

方法	路径	说明
GET	/users	获取用户列表
POST	/users	创建用户
GET	/users/:id	获取用户详情
PUT	/users/:id	更新用户
DELETE	/users/:id	删除用户
PUT	/users/:id/password	修改密码

分页参数

列表接口支持分页：

参数	类型	说明	默认值
page	int	页码	1
page_size	int	每页数量	20
keyword	string	搜索关键词	-

响应包含分页信息：

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [],
    "total": 100,
    "page": 1,
    "page_size": 20
  }
}

示例代码

Python

import requests

BASE_URL = "http://localhost:8085/api/v1"

# 登录
response = requests.post(f"{BASE_URL}/auth/login", json={
    "username": "admin",
    "password": "admin123"
})
token = response.json()["data"]["token"]

headers = {"Authorization": f"Bearer {token}"}

# 获取域名列表
response = requests.get(f"{BASE_URL}/domains", headers=headers)
domains = response.json()["data"]["list"]

# 创建域名
response = requests.post(f"{BASE_URL}/domains", headers=headers, json={
    "name": "example.com",
    "description": "示例域名"
})

JavaScript

const BASE_URL = 'http://localhost:8085/api/v1';

// 登录
const login = async () => {
  const response = await fetch(`${BASE_URL}/auth/login`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      username: 'admin',
      password: 'admin123'
    })
  });
  const data = await response.json();
  return data.data.token;
};

// 使用 Token 请求
const getDomains = async (token) => {
  const response = await fetch(`${BASE_URL}/domains`, {
    headers: { 'Authorization': `Bearer ${token}` }
  });
  return await response.json();
};

Swagger 文档

启动服务后，可以访问 Swagger UI 查看完整 API 文档：

http://localhost:8085/swagger/index.html