API 文档

EasyTier 节点管理系统 API 接口详细说明

基础信息

Base URL: https://your-domain.workers.dev

认证方式: Bearer Token (JWT)

Content-Type: application/json

认证 API

POST/api/auth/register用户注册▼

请求体

{
  "email": "user@example.com",
  "password": "password123"
}

响应

{
  "message": "注册成功，请查收验证邮件",
  "verification_token": "token_string"
}

状态码

  • 201: 注册成功
  • 400: 请求参数错误
  • 500: 服务器错误
POST/api/auth/login用户登录▼

请求体

{
                              "email": "user@example.com",
                              "password": "password123"
                            }

响应

{
                                  "token": "jwt_token_string",
                                  "user": {
                                    "email": "user@example.com",
                                    "is_admin": false
                                  }
                                }

状态码

  • 200: 登录成功
  • 401: 邮箱或密码错误
  • 403: 邮箱未验证
  • 500: 服务器错误
GET/api/auth/verify?token=<verification_token>验证邮箱▼

查询参数

  • token: 验证令牌（从注册邮件中获取）

响应

{
  "message": "邮箱验证成功"
}

状态码

  • 200: 验证成功
  • 400: 验证令牌无效
  • 500: 服务器错误

节点管理 API

所有节点管理 API 都需要在请求头中包含 JWT token: Authorization: Bearer <your_jwt_token>

GET/api/nodes/my获取我的节点列表▼

响应

{
  "nodes": [
    {
      "id": 1,
      "node_name": "节点1",
      "region_type": "domestic",
      "region_detail": "北京",
      "connections": [
        {
          "type": "TCP",
          "ip": "1.2.3.4",
          "port": 8080
        }
      ],
      "current_bandwidth": 50.5,
      "tier_bandwidth": 100,
      "max_bandwidth": 1000,
      "used_traffic": 50.2,
      "max_traffic": 1000,
      "connection_count": 5,
      "max_connections": 100,
      "tags": "高速,稳定",
      "status": "online"
    }
  ]
}

状态码

  • 200: 成功
  • 401: 未授权
  • 500: 服务器错误
POST/api/nodes/创建节点▼

请求体

{
  "node_name": "节点1",
  "region_type": "domestic",
  "region_detail": "北京",
  "connections": [
    {
      "type": "TCP",
      "ip": "1.2.3.4",
      "port": 8080
    }
  ],
  "tier_bandwidth": 100,
  "max_bandwidth": 1000,
  "max_traffic": 1000,
  "reset_cycle": 30,
  "max_connections": 100,
  "tags": "高速,稳定",
  "valid_until": "2026-11-04",
  "allow_relay": 1
}

响应

{
  "message": "节点创建成功",
  "node_id": 1
}

状态码

  • 201: 创建成功
  • 400: 请求参数错误
  • 401: 未授权
  • 500: 服务器错误
PUT/api/nodes/<id>更新节点▼

路径参数

  • id: 节点 ID

请求体

同创建节点，所有字段都是可选的

响应

{
  "message": "节点更新成功"
}

状态码

  • 200: 更新成功
  • 400: 请求参数错误
  • 401: 未授权
  • 403: 无权修改此节点
  • 404: 节点不存在
  • 500: 服务器错误
DELETE/api/nodes/<id>删除节点▼

路径参数

  • id: 节点 ID

响应

{
  "message": "节点删除成功"
}

状态码

  • 200: 删除成功
  • 401: 未授权
  • 403: 无权删除此节点
  • 404: 节点不存在
  • 500: 服务器错误

公开 API

以下 API 不需要认证

POST/api/report节点上报▼

请求体

{
  "node_name": "my-node",
  "email": "user@example.com",
  "token": "your-report-token",
  "current_bandwidth": 50.5,
  "reported_traffic": 0.5,
  "connection_count": 5,
  "status": "online"
}

响应

{
  "message": "上报成功",
  "used_traffic": 50.7,
  "max_traffic": 1000,
  "reset_date": "2025-12-04T00:00:00.000Z"
}

状态码

  • 200: 上报成功
  • 400: 请求参数错误
  • 403: Token验证失败或节点已过期
  • 404: 节点不存在
  • 500: 服务器错误
POST/api/query查询节点（智能负载均衡）▼

请求体

{
  "region": "domestic",
  "priority": "traffic",
  "relay_only": false
}

响应

{
  "nodes": [
    {
      "id": 1,
      "node_name": "节点1",
      "region_type": "domestic",
      "region_detail": "北京",
      "connections": [
        {
          "type": "TCP",
          "ip": "1.2.3.4",
          "port": 8080
        }
      ],
      "current_bandwidth": 50.5,
      "tier_bandwidth": 100,
      "connection_count": 5,
      "max_connections": 100,
      "used_traffic": 50.2,
      "max_traffic": 1000,
      "tags": "高速,稳定",
      "allow_relay": 1
    }
  ]
}

状态码

  • 200: 查询成功
  • 500: 服务器错误
GET/api/public获取公开节点列表▼

响应

{
  "nodes": [
    {
      "id": 1,
      "node_name": "节点1",
      "region_type": "domestic",
      "region_detail": "北京",
      "current_bandwidth": 50.5,
      "tier_bandwidth": 100,
      "max_bandwidth": 1000,
      "used_traffic": 50.2,
      "max_traffic": 1000,
      "connection_count": 5,
      "max_connections": 100,
      "tags": "高速,稳定",
      "status": "online",
      "allow_relay": 1
    }
  ]
}

状态码

  • 200: 成功
  • 500: 服务器错误
GET/api/stats获取统计信息▼

响应

{
  "total_nodes": 100,
  "online_nodes": 80,
  "domestic_nodes": 60,
  "overseas_nodes": 40,
  "total_bandwidth": 10000.5
}

状态码

  • 200: 成功
  • 500: 服务器错误

系统管理 API

需要管理员权限

GET/api/system/check-init检查系统初始化状态▼

响应

{
  "initialized": true
}

状态码

  • 200: 成功
POST/api/system/initialize初始化系统▼

请求体

{
  "jwt_secret": "your-jwt-secret",
  "email": "admin@example.com",
  "password": "admin123456"
}

响应

{
  "message": "系统初始化成功",
  "admin_email": "admin@example.com"
}

状态码

  • 201: 初始化成功
  • 400: 系统已初始化或参数错误
  • 401: JWT 密钥验证失败
  • 500: 服务器错误

错误响应格式

所有错误响应都遵循以下格式：

{
  "error": "错误描述信息"
}

使用示例

示例 1: 用户注册和登录

# 1. 注册
curl -X POST https://your-domain.workers.dev/api/auth/register   -H "Content-Type: application/json"   -d '{"email":"user@example.com","password":"password123"}'

# 2. 验证邮箱（使用邮件中的 token）
curl https://your-domain.workers.dev/api/auth/verify?token=verification_token

# 3. 登录
curl -X POST https://your-domain.workers.dev/api/auth/login   -H "Content-Type: application/json"   -d '{"email":"user@example.com","password":"password123"}'

示例 2: 创建和管理节点

# 1. 创建节点
curl -X POST https://your-domain.workers.dev/api/nodes/   -H "Authorization: Bearer your_jwt_token"   -H "Content-Type: application/json"   -d '{
    "node_name": "测试节点",
    "region_type": "domestic",
    "region_detail": "北京",
    "connections": [{"type":"TCP","ip":"1.2.3.4","port":8080}],
    "tier_bandwidth": 100,
    "max_bandwidth": 1000,
    "max_traffic": 1000,
    "reset_cycle": 30,
    "max_connections": 100,
    "valid_until": "2026-11-04",
    "allow_relay": 1
  }'

# 2. 获取我的节点
curl https://your-domain.workers.dev/api/nodes/my   -H "Authorization: Bearer your_jwt_token"

# 3. 更新节点
curl -X PUT https://your-domain.workers.dev/api/nodes/1   -H "Authorization: Bearer your_jwt_token"   -H "Content-Type: application/json"   -d '{"tier_bandwidth": 200}'

# 4. 删除节点
curl -X DELETE https://your-domain.workers.dev/api/nodes/1   -H "Authorization: Bearer your_jwt_token"

示例 3: 节点上报

# 使用节点名称、邮箱和Token进行上报
curl -X POST https://your-domain.workers.dev/api/report   -H "Content-Type: application/json"   -d '{
    "node_name": "my-node",
    "email": "user@example.com",
    "token": "your-report-token-here",
    "current_bandwidth": 50.5,
    "reported_traffic": 0.5,
    "connection_count": 5,
    "status": "online"
  }'