白名单管理API文档

概述

本API系统提供白名单IP地址的管理功能，支持添加、删除、查询操作。所有接口都支持GET和POST两种请求方式，并使用时间戳+MD5签名进行身份验证。

api接口地址 https://byjsgateway.vpsnb.net

认证机制

签名算法

sign = MD5(orderId + timestamp + api_key)

认证参数

• orderId: 用户名
• timestamp: 当前时间戳（秒）
• sign: MD5签名
• 时间戳有效期：5分钟

API接口

1. 添加白名单IP

接口地址： /api/whitelist/add
请求方式： GET / POST
功能说明： 添加单个IP地址到白名单

GET请求参数

GET /api/whitelist/add?orderId=用户名&timestamp=时间戳&sign=签名&ip=IP地址

POST请求参数

{
    "orderId": "用户名",
    "timestamp": 1234567890,
    "sign": "md5签名",
    "ip": "192.168.1.100"
}

参数说明

• ip: 要添加的IP地址（必填，只支持单个IPv4地址）

响应示例

{
    "code": 0,
    "msg": "白名单添加成功，1分钟后生效",
    "data": {
        "ip": "192.168.1.100"
    }
}

失败响应示例

{
    "code": 400,
    "msg": "IP地址 192.168.1.100 已存在于白名单中"
}

或

{
    "code": 400,
    "msg": "无效的IP格式，只支持单个IP地址（如：192.168.1.100）"
}

2. 删除白名单IP

接口地址： /api/whitelist/remove
请求方式： GET / POST
处理方式： 异步处理，接口立即返回，网关配置在后台更新，约1分钟后生效

GET请求参数

GET /api/whitelist/remove?orderId=用户名&timestamp=时间戳&sign=签名&ip=IP地址

POST请求参数

{
    "orderId": "用户名",
    "timestamp": 1234567890,
    "sign": "md5签名",
    "ip": "192.168.1.100"
}

参数说明

• ip: 要删除的IP地址（必填，只支持单个IPv4地址）

失败响应示例

{
    "code": 400,
    "msg": "IP地址 192.168.1.100 不存在于白名单记录中"
}

或

{
    "code": 400,
    "msg": "IP地址 192.168.1.100 已经是禁用状态"
}

3. 查询白名单

接口地址： /api/whitelist/query
请求方式： GET / POST
功能说明： 查询用户当前启用的白名单IP列表（简化版，只返回启用的IP）

GET请求参数

GET /api/whitelist/query?orderId=用户名&timestamp=时间戳&sign=签名

POST请求参数

{
    "orderId": "用户名",
    "timestamp": 1234567890,
    "sign": "md5签名"
}

成功响应示例

{
    "code": 0,
    "msg": "查询成功",
    "data": {
        "active_whitelist": ["192.168.1.101", "192.168.1.102", "192.168.1.103"],
        "active_count": 3
    }
}

字段说明：

• active_whitelist：启用的白名单IP列表（数组）
• active_count：启用的白名单数量（整数）

说明：

• 只返回当前启用状态的白名单IP列表
• 已禁用的白名单不会在结果中显示
• 返回数据简洁，适合大量白名单的场景
• 如果没有启用的白名单，active_whitelist 将是空数组 []，active_count 为 0

失败响应示例

{
    "code": 500,
    "msg": "查询白名单失败: 具体错误信息"
}

重要特性

1. 异步自动同步机制

• 当添加或删除白名单IP时，系统会在后台异步同步到用户的所有活跃端口
• 接口立即返回成功响应，不会等待网关配置完成
• 网关配置更新在后台线程中执行，约1分钟后生效

2. IP格式限制

• 只支持单个IPv4地址格式（如：192.168.1.100）
• 不支持网段格式（如：192.168.1.0/24）
• 不支持域名或其他格式

4. 请求方式灵活性

• 所有接口都支持GET和POST两种请求方式
• GET请求参数通过URL查询字符串传递
• POST请求支持JSON格式和表单格式

错误码说明

使用示例

Python示例

import requests
import time
import hashlib

def generate_sign(orderId, timestamp, key):
    sign_str = f"{orderId}{timestamp}{key}"
    return hashlib.md5(sign_str.encode()).hexdigest()

# POST请求示例
def add_whitelist_post(ip):
    timestamp = int(time.time())
    sign = generate_sign("username", timestamp, "api_key")

    data = {
        "orderId": "username",
        "timestamp": timestamp,
        "sign": sign,
        "ip": ip
    }

    response = requests.post("http://localhost:5001/api/whitelist/add", json=data)
    return response.json()

# GET请求示例
def add_whitelist_get(ip):
    timestamp = int(time.time())
    sign = generate_sign("username", timestamp, "api_key")

    params = {
        "orderId": "username",
        "timestamp": timestamp,
        "sign": sign,
        "ip": ip
    }

    response = requests.get("http://localhost:5001/api/whitelist/add", params=params)
    return response.json()

# 使用示例
result = add_whitelist_post("192.168.1.100")
print(result)

cURL示例

POST请求

curl -X POST http://localhost:5001/api/whitelist/add \
  -H "Content-Type: application/json" \
  -d '{
    "orderId": "username",
    "timestamp": 1234567890,
    "sign": "your_md5_sign",
    "ip": "192.168.1.100"
  }'

GET请求

curl "http://localhost:5001/api/whitelist/add?orderId=username&timestamp=1234567890&sign=your_md5_sign&ip=192.168.1.100"

注意事项

1. 时间戳验证：请确保客户端时间与服务器时间差不超过5分钟
2. 签名生成：签名字符串的拼接顺序为：orderId + timestamp + api_key
3. IP格式：严格验证IP地址格式，只接受标准的IPv4地址
4. 批量操作：如需添加多个IP，请逐个调用添加接口，每个请求都会立即返回
5. 异步生效：添加/删除操作立即返回成功，但网关配置需要约1分钟后生效