IP黑名单系统 API接口开发手册

目录

• 概述
• 基本信息
• API端点
• 认证API
• 错误处理
• 示例代码
• 开发指南

概述

IP黑名单系统提供一组API，允许外部应用程序查询和管理IP黑名单。本手册详细介绍了可用的API端点、请求方法、参数和响应格式。

基本信息

• 基础URL: https://您的域名
• 认证方式:
  • JWT认证:
    • 推荐方式: 通过请求体的token字段传递JWT令牌
    • 兼容方式: 通过Authorization: Bearer <token>头传递令牌
  • API密钥:
    • 推荐方式: 通过请求体的key字段传递API密钥
    • 兼容方式: 通过URL参数key传递API密钥
• 安全策略: 所有API都必须进行认证，无法直接匿名访问
• 响应格式: 所有API返回JSON格式
• 跨域支持: 所有API支持CORS跨域请求

API端点

1. 检查IP黑名单状态

请求

GET /api/blacklist/check-api

参数:

参数	类型	必须	描述
ip	string	否	要检查的IP地址，如不提供则使用访问者当前IP
key	string	是	API密钥，用于认证请求（必须具有读取权限）

响应

{
  "ip": "192.168.1.1",
  "blocked": false,
  "message": "IP 192.168.1.1 不在黑名单中"
}

字段说明:

字段	类型	描述
ip	string	被查询的IP地址
blocked	boolean	是否在黑名单中
message	string	状态描述信息

状态码

• 200 OK: 请求成功
• 400 Bad Request: 请求参数错误
• 401 Unauthorized: API密钥缺失、无效或权限不足
• 500 Internal Server Error: 服务器内部错误

2. 检查系统连接状态

请求

GET /api/blacklist/check

请求头: (兼容方式)

参数	类型	必须	描述
Authorization	string	是	JWT认证令牌，格式为: Bearer <token>

或者 (推荐方式)

POST /api/blacklist/check
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

响应

{
  "connected": true,
  "message": "KV连接正常"
}

字段说明:

字段	类型	描述
connected	boolean	KV存储是否连接正常
message	string	连接状态描述信息

状态码

• 200 OK: 请求成功
• 401 Unauthorized: JWT认证失败或令牌无效
• 500 Internal Server Error: 服务器内部错误

认证API

1. 用户登录

请求

POST /api/auth/login

请求体:

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

响应

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "username": "admin",
    "role": "admin"
  }
}

状态码

• 200 OK: 登录成功
• 401 Unauthorized: 登录失败
• 500 Internal Server Error: 服务器内部错误

2. 验证令牌

请求

GET /api/auth/verify

请求头: (兼容方式)

参数	类型	必须	描述
Authorization	string	是	JWT认证令牌，格式为: Bearer <token>

或者 (推荐方式)

POST /api/auth/verify
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

响应

{
  "valid": true,
  "message": "认证令牌有效",
  "user": {
    "username": "admin",
    "role": "admin"
  }
}

状态码

• 200 OK: 令牌有效
• 401 Unauthorized: 令牌无效或已过期
• 500 Internal Server Error: 服务器内部错误

错误处理

IP黑名单管理API

1. 获取黑名单列表

请求

GET /api/blacklist/get

请求头: (兼容方式)

参数	类型	必须	描述
Authorization	string	是	JWT认证令牌，格式为: Bearer <token>

或者 (推荐方式)

POST /api/blacklist/get
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

响应

[
  "192.168.1.1",
  "10.0.0.1",
  "172.16.0.1"
]

状态码

• 200 OK: 请求成功
• 401 Unauthorized: JWT认证失败或令牌无效
• 500 Internal Server Error: 服务器内部错误

2. 添加IP到黑名单

请求

POST /api/blacklist/add

请求头: (兼容方式)

参数	类型	必须	描述
Authorization	string	是	JWT认证令牌，格式为: Bearer <token>
Content-Type	string	是	application/json

请求体: (兼容方式)

{
  "ip": "192.168.1.1"
}

或者 (推荐方式)

POST /api/blacklist/add
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "ip": "192.168.1.1"
}

响应

{
  "success": true
}

状态码

• 200 OK: 请求成功
• 400 Bad Request: 缺少必要参数
• 401 Unauthorized: JWT认证失败或令牌无效
• 500 Internal Server Error: 服务器内部错误

3. 从黑名单删除IP

请求

POST /api/blacklist/remove

请求头: (兼容方式)

参数	类型	必须	描述
Authorization	string	是	JWT认证令牌，格式为: Bearer <token>
Content-Type	string	是	application/json

请求体: (兼容方式)

{
  "ip": "192.168.1.1"
}

或者 (推荐方式)

POST /api/blacklist/remove
Content-Type: application/json

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "ip": "192.168.1.1"
}

响应

{
  "success": true
}

状态码

• 200 OK: 请求成功
• 400 Bad Request: 缺少必要参数
• 401 Unauthorized: JWT认证失败或令牌无效
• 500 Internal Server Error: 服务器内部错误