EasyTier 节点管理系统

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: 服务器错误

EdgeOne 云函数检测 API

以下 API 用于通过 EdgeOne 云函数检测节点在线状态，支持两种部署模式：独立云函数部署或一体化部署（Hono 内置路由）。如配置了 API Key，需在请求头中携带 X-API-Key 进行鉴权。

GET/api/edgeone/check单节点在线检测▼

查询参数

server（必填）：节点连接地址，格式如 tcp://IP:PORT、ws://IP:PORT、wss://IP:PORT
network_name（必填）：EasyTier 网络名称
network_secret（必填）：EasyTier 网络密码

请求头

X-API-Key（可选）：API 鉴权密钥（如已配置）

在线响应

{
  "is_online": true,
  "connection_count": 5,
  "latency_ms": 120,
  "check_time": "2026-05-08T09:00:00.000Z"
}

离线响应

{
  "is_online": false,
  "connection_count": 0,
  "latency_ms": -1,
  "check_time": "2026-05-08T09:00:00.000Z",
  "error": "连接超时"
}

状态码

200: 检测完成（无论节点在线或离线）
400: 缺少必填参数
401: API Key 验证失败
500: 服务器内部错误

POST/api/edgeone/batch-check批量节点在线检测▼

请求头

X-API-Key（可选）：API 鉴权密钥（如已配置）

请求体

{
  "nodes": [
    {
      "server": "tcp://1.2.3.4:11010",
      "network_name": "MyNetwork",
      "network_secret": "MyPassword"
    },
    {
      "server": "ws://5.6.7.8:11011",
      "network_name": "TestNetwork",
      "network_secret": "TestPassword"
    }
  ]
}

响应

{
  "results": [
    {
      "is_online": true,
      "connection_count": 5,
      "latency_ms": 120,
      "check_time": "2026-05-08T09:00:00.000Z"
    },
    {
      "is_online": false,
      "connection_count": 0,
      "latency_ms": -1,
      "check_time": "2026-05-08T09:00:00.000Z",
      "error": "连接超时"
    }
  ]
}

状态码

200: 批量检测完成
400: 请求参数错误（节点列表为空/超过20个/缺少必填字段）
401: API Key 验证失败
500: 服务器内部错误

GET/api/edgeone/health云函数健康状态▼

请求头

X-API-Key（可选）：API 鉴权密钥（如已配置）

响应

{
  "status": "ok",
  "service": "edgeone-check",
  "mode": "remote",
  "timestamp": "2026-05-08T09:00:00.000Z"
}

mode 字段说明：

remote：配置了 EDGEONE_CHECK_API，使用远程 EdgeOne 云函数检测
local：未配置远程 API，使用本地 TCP 直连检测

状态码

200: 服务正常
401: API Key 验证失败

系统管理 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"
  }'