renminghui/punchnet-android
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
punchnet-android/API.md
stavid d116d2cbcd fix some warning
2026-06-20 13:28:22 +08:00

12 KiB
Raw Permalink Blame History

HTTP API 接口列表

域名 https://root.punchsky.com/api

1.密钥登录接口

URL：/auth/token
Method：POST

请求参数

参数名 类型 必填 说明
client_id string ✅ 客户端唯一标识符
token string ✅ 密钥
mac string MAC地址
system string 系统信息(window11/macos 15.8)
version string 软件版本
hostname string 主机名

响应参数

字段 类型 说明
code int 0 成功，其他失败
message string 说明
data object
access_token string
username string 用户名
user_type string token密钥登录、account账号登录
audit int 0 未审核，1审核通过
network_id int 网络ID
network_name string 网络名称
network_domain string 网络域名
domain string 主域名
my_network_list array 我的网络列表

示例响应

{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "MjZ8NDB8MGZhMWE3OGI2NzVkZDEwOWIyYjg2MmI4ZDQ5MTY1MmV8ZTg4MzgzMThhZDBhMjU5MDI5MzQ4ZGQ5ZTc3ZWExZDVhYmQ2YjQwM2M3NDE1YmE4MWQ5YzEzZTEzOTM3MzYzMQ",
    "username": "测试clinet_id_123456",
    "user_type": "token",
    "audit": 1,
    "network_id": 3,
    "network_name": "test的网络",
    "network_domain": "punchsky8.com",
    "domain": "punchsky.com",
    "my_network_list": []
  }
}

错误

{
  "code": 400,
  "message": "密钥已失效",
  "data": null
}

2.账号登录接口

URL：/auth/login
Method：POST

请求参数

参数名 类型 必填 说明
client_id string ✅ 客户端唯一标识符
username string ✅ 用户名
password string ✅ 密码
mac string MAC地址
system string 系统信息(window11/macos 15.8)
version string 软件版本
hostname string 主机名

响应参数 - 跟auth/token一致 ，多了一个我的网络列表

{
    "code": 0,
    "message": "success",
    "data": {
        "access_token": "MzF8NDV8MzM2MzMyMTQ1MTc3YjlkMjYyZGU3OTNkMWFhYjQ4OTB8YmE3ODRiZDE1MmFlMjQ3MDk2NzIyZTRiY2EyOWQzMGZmNWMyMWRhMmJkYzM3Zjk1N2NkNjg2NGRlNjQ1ZDc1MQ",
        "username": "test3",
        "user_type": "account",
        "audit": 1,
        "network_id": 3,
        "network_name": "test\u7684\u7f51\u7edc",
        "network_domain": "lfn1.punchlink.cn",
        "my_network_list": [
            {
                "network_id": 3,
                "network_name": "test\u7684\u7f51\u7edc"
            }
        ]
    }
}

3.连接网络

URL：/connect
Method：POST

请求参数

参数名 类型 必填 说明
client_id string ✅ 客户端唯一标识符
access_token string ✅
version string 软件版本

响应参数

字段 类型 说明
code int 0 成功，其他失败
message string 说明
data object
ip string IP地址
mask_len int mask
hostname string hostname
identity_id int 目前返回单个数字，多组概念稍后解决
resource_list array 资源列表
node_list string 节点列表
acl array 访问规则
exit_node array 出口节点列表 (可为空)

示例响应

{
  "code": 0,
  "message": "success",
  "data": {
    "ip": "10.10.2.3",
    "mask_len": 24,
    "hostname": "lfmw",
    "identity_id": 26,
    "resource_list": [
      {
        "id": 0,
        "name": "文档中心",
        "url": "http://10.10.2.6:88",
        "connection_status": "connected"
      },
      {
        "id": 1,
        "name": "文档中心",
        "url": "http://10.10.2.6:80",
        "connection_status": "connected"
      },
      {
        "id": 2,
        "name": "数据中心",
        "url": "http://10.10.2.6:88",
        "connection_status": "connected"
      },
      {
        "id": 3,
        "name": "数据中心",
        "url": "http://10.10.2.6:80",
        "connection_status": "connected"
      },
      {
        "id": 4,
        "name": "数据中心",
        "url": "http://10.10.2.6:3306",
        "connection_status": "connected"
      }
    ],
    "node_list": [
      {
        "id": 13,
        "name": "key_MTE1",
        "ip": "10.10.2.3",
        "system": "Macos 1.0.0",
        "connection_status": "connected"
      },
      {
        "id": 14,
        "name": "test3",
        "ip": "10.10.2.4",
        "system": "Window 1.0.0",
        "connection_status": "connected"
      },
      {
        "id": 23,
        "name": "alc",
        "ip": "10.10.2.6",
        "system": "",
        "connection_status": "connected"
      },
      {
        "id": 25,
        "name": "maliu-window",
        "ip": "10.10.2.7",
        "system": "OS: Windows, Host name: DESKTOP-VLMVV81",
        "connection_status": "connected"
      },
      {
        "id": 26,
        "name": "key_MTE4",
        "ip": "10.10.2.8",
        "system": "OS: Windows, Host name: DESKTOP-VLMVV81",
        "connection_status": "connected"
      },
      {
        "id": 27,
        "name": "company-window",
        "ip": "10.10.2.9",
        "system": "OS: Windows, Host name: DESKTOP-VLMVV81",
        "connection_status": "disconnected"
      },
      {
        "id": 28,
        "name": "maliu-macos",
        "ip": "10.10.2.10",
        "system": "",
        "connection_status": "connected"
      },
      {
        "id": 29,
        "name": "key_MTE4",
        "ip": "10.10.2.5",
        "system": "linux",
        "connection_status": "connected"
      },
      {
        "id": 39,
        "name": "maliu-ubuntu",
        "ip": "10.10.2.12",
        "system": "linux",
        "connection_status": "disconnected"
      },
      {
        "id": 40,
        "name": "测试clinet_id_123456",
        "ip": "10.10.2.3",
        "system": "Macos 1.0.0",
        "connection_status": "connected"
      },
      {
        "id": 41,
        "name": "test3",
        "ip": "10.10.2.5",
        "system": "linux",
        "connection_status": "connected"
      },
      {
        "id": 42,
        "name": "test3",
        "ip": "10.10.2.6",
        "system": "",
        "connection_status": "connected"
      },
      {
        "id": 43,
        "name": "user_MTQw",
        "ip": "10.10.2.13",
        "system": "linux",
        "connection_status": "connected"
      },
      {
        "id": 45,
        "name": "test3",
        "ip": "10.10.2.3",
        "system": "Macos 1.0.0",
        "connection_status": "connected"
      },
      {
        "id": 47,
        "name": "compay-usa",
        "ip": "10.10.2.14",
        "system": "linux",
        "connection_status": "connected"
      },
      {
        "id": 48,
        "name": "test3",
        "ip": "10.10.2.10",
        "system": "",
        "connection_status": "disconnected"
      },
      {
        "id": 49,
        "name": "test3",
        "ip": "10.10.2.7",
        "system": "OS: Windows, Host name: DESKTOP-VLMVV81",
        "connection_status": "connected"
      },
      {
        "id": 50,
        "name": "test3",
        "ip": "10.10.2.9",
        "system": "OS: Windows, Host name: DESKTOP-VLMVV81",
        "connection_status": "disconnected"
      },
      {
        "id": 51,
        "name": "test3",
        "ip": "10.10.2.15",
        "system": "OS: Windows, Host name: MALIU3CA0",
        "connection_status": "disconnected"
      },
      {
        "id": 52,
        "name": "test3",
        "ip": "10.10.2.16",
        "system": "OS: Ubuntu, Host name: alex-ubuntu",
        "connection_status": "disconnected"
      }
    ],
    "acl": [],
    "exit_node": [
      {
        "node_id": 41,
        "node_name": "test3",
        "gateway": "10.10.2.5",
        "target_network": "0.0.0.0/24"
      }
    ]
  }
}

错误

{
  "code": 400,
  "message": "操作失败",
  "data": null
}

4.断开网络

URL：/disconnect
Method：POST

请求参数

参数名 类型 必填 说明
client_id string ✅ 客户端唯一标识符
access_token string ✅

响应参数

字段 类型 说明
code int 0 成功，其他失败
message string 说明
data

示例响应

{
  "code": 0,
  "message": "success",
  "data": null
}

错误

{
  "code": 400,
  "message": "操作失败",
  "data": null
}

5.设备详情

URL：/get_node_resources
Method：POST

请求参数

参数名 类型 必填 说明
client_id string ✅ 客户端唯一标识符
access_token string ✅
id int ✅ 设备id

响应参数

字段 类型 说明
code int 0 成功，其他失败
message string 说明
data

示例响应

{
  "code": 0,
  "message": "success",
  "data": {
    "id": 15,
    "name": "key_MTE1",
    "ip": "10.10.2.5",
    "system": "Macos 1.0.0",
    "connection_status": "connected",
    "resource_list": [
      {
        "id": 15,
        "name": "数据中心",
        "url": "http://10.10.2.5:8080",
        "connection_status": "connected"
      },
      {
        "id": 15,
        "name": "数据中心",
        "url": "http://10.10.2.5:90",
        "connection_status": "connected"
      },
      {
        "id": 15,
        "name": "数据中心",
        "url": "http://10.10.2.5:10",
        "connection_status": "connected"
      }
    ]
  }
}

6.验证access_token 服务端使用

URL：auth/access_token
Method：POST

请求参数

参数名 类型 必填 说明
client_id string ✅ 客户端唯一标识符
access_token string ✅
ip string ✅
mask_len int ✅
hostname string ✅
mac string ✅
network_id int ✅

响应参数

示例响应

{
  "result": "ok"
}

错误

{
  "error": {
    "code": 1,
    "message": "缺少必填参数：client_id"
  }
}

7.set_node_status 服务端使用

URL：set_node_status
Method：POST

请求参数

参数名 类型 必填 说明
client_id string ✅ 客户端唯一标识符
access_token string ✅
status int ✅
network_id int ✅

响应参数

示例响应

{
  "result": "ok"
}

错误

{
  "error": {
    "code": 1,
    "message": "缺少必填参数：client_id"
  }
}

8.获取节点开放端口

URL：/acl
Method：POST

请求参数

参数名 类型 必填 说明
client_id string ✅ 客户端唯一标识符
access_token string ✅
network_id int 网络ID

响应参数

字段 类型 说明
code int 0 成功，其他失败
message string 说明
data object

示例响应

{
  "code": 0,
  "message": "success",
  "data": {
    "tcp": [
      80
    ],
    "udp": []
  }
}