跳到主要内容

TCP 扫描 API

TCP 扫描 API 可以扫描指定 IPv4 地址范围内的 TCP 连通性，并自动通过 ADB 连接到局域网内可达的 Android 设备。无需手动执行 adb connect 命令，即可快速发现并连接无线 Android 设备。

接口地址​

POST /api/v1/device/tcp-scan

要求​

许可证要求

此 API 需要 Pro、Team 或 Business 计划。 Starter 计划无权访问。

请求体​

所有字段均为可选。省略时，应用将使用在设置中配置的 IP 范围和端口。

字段类型是否必填描述
start_ipstring否起始 IPv4 地址（例如 "192.168.1.2"）。默认使用应用存储的设置。
end_ipstring否结束 IPv4 地址（例如 "192.168.1.254"）。默认使用应用存储的设置。
portinteger否要扫描的 TCP 端口（例如 5555）。默认使用应用存储的 scan_port（默认值：5555）。
子网限制

扫描范围限于单个 /24 子网。若 start_ip 和 end_ip 属于不同的 /24 子网，范围将自动截断至 start_ip.x.x.255。

示例​

使用应用设置（推荐）​

发送空请求体，使用应用中已配置的 IP 范围和端口：

curl -X POST http://localhost:50809/api/v1/device/tcp-scan \
  -H "Content-Type: application/json" \
  -d '{}'

自定义 IP 范围​

curl -X POST http://localhost:50809/api/v1/device/tcp-scan \
  -H "Content-Type: application/json" \
  -d '{
    "start_ip": "192.168.1.2",
    "end_ip": "192.168.1.254",
    "port": 5555
  }'

响应​

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 3,
    "success": 2,
    "failed": 1,
    "details": [
      {
        "ip": "192.168.1.100",
        "success": true,
        "message": "already connected to 192.168.1.100:5555"
      },
      {
        "ip": "192.168.1.101",
        "success": true,
        "message": "connected to 192.168.1.101:5555"
      },
      {
        "ip": "192.168.1.102",
        "success": false,
        "message": "failed to connect to 192.168.1.102:5555"
      }
    ]
  }
}

响应字段说明​

字段类型描述
data.totalintegerTCP 端口可达的 IP 总数
data.successinteger成功通过 ADB 连接的 IP 数量
data.failedintegerADB 连接失败的 IP 数量
data.detailsarray每个 IP 的连接结果列表
data.details[].ipstring扫描的 IP 地址
data.details[].successbooleanADB 连接是否成功（true 表示成功）
data.details[].messagestringADB 输出信息或错误信息

错误响应​

HTTP 状态码Code描述
403403API 访问需要 Pro+ 计划

工作原理​

  1. TCP 探测 — 并发地对范围内每个 IP 进行 TCP 连接测试，超时时间为 1 秒。
  2. ADB 连接 — 对每个可达的 IP 执行 adb connect <ip>:<port>（最多重试 2 次）。
  3. 结果汇总 — 收集所有 IP 的连接结果并返回。

扫描成功后，已连接的设备将自动出现在 TikMatrix 设备列表中。