端口连通性检测

接口标识: portcheck 价格: 0.005 元/次同步响应

接口介绍
接口文档
在线测试

接口简介

端口连通性检测接口通过真实 TCP 连接探测目标域名或公网 IP 的指定端口是否开放，逐端口返回开放状态与连接延迟毫秒数。支持单端口或最多 20 个端口批量并发探测，总耗时约等于单端口超时而非累加，超时不超过 5 秒、默认 3 秒。私有内网、回环、保留网段一律拒绝探测，域名先解析并校验全部 IP 为公网。适合远程服务可用性监控、防火墙策略核查、上线前端口自检等场景。

详细介绍

![端口连通性检测接口封面](https://fujian.phpwc.com/pyapi/uploads/site/20261111/apiops_portcheck__1794363277_c3141e9f8c52.png)

服务器端口到底通不通？与其反复猜测，不如直接探测：传入域名和端口，开放状态与连接延迟一次看清。

## 接口概述
面向运维与监控场景中需要快速确认远程端口状态的需求，接口通过建立真实 TCP 连接探测目标域名或公网 IP，同步返回每个端口的开放状态与连接耗时毫秒数。支持单端口探测，也支持一次最多 20 个端口批量并发，单端口超时可自定义。探测结果可接入监控告警、上线检查清单与防火墙策略核查流程，替代人工逐个试连，让服务可达性结论以结构化数据的形式留存。

## 核心能力
1. **TCP 真实探测**：以真实连接判定端口开放状态，结论贴近实际访问效果。
2. **批量并发**：一次最多探测 20 个端口，并发执行且自动去重，总耗时约等于单端口超时。
3. **延迟量化**：每个端口都返回连接耗时毫秒数，未开放的端口也给出超时或拒绝等原因。
4. **公网护栏**：私有内网、回环、保留网段一律拒绝，域名先解析并校验全部 IP 为公网。

## 产品优势
1. **接入简单**：标准 POST 同步调用，传域名与端口即可拿到结果。
2. **响应迅速**：批量端口并发探测，快速返回全部结论。
3. **结论明确**：每个端口明确返回开放与否、延迟多少、为何不通，无需猜测。
4. **合规安全**：内置公网校验，接口不会被用成内网扫描通道。
5. **降本增效**：一个接口替代自建探测脚本与探测节点维护。

## 效果展示
一句话理解：它就像替你去敲一栋楼里各个房间的门，看哪些房间有人应答，还记录下每次敲门等了多久。

以一次真实调用为例，你要传的参数：

| 参数 | 本次示例值 | 说明 |
|------|-----------|------|
| host | example.com | 目标域名或公网 IP，不带协议前缀与路径 |
| ports | 443,22 | 批量端口逗号分隔，最多 20 个；也可用 port 传单个端口 |
| timeout | 3 | 单端口连接超时秒数，不超过 5 秒，默认 3 |

你会拿到的结果：

| 返回内容 | 本次示例值 | 对应字段 |
|---------|-----------|---------|
| 探测目标 | `"example.com"` | `host` |
| 探测端口总数 | 2 | `total` |
| 开放端口数 | 1 | `open_count` |
| 各端口结果 | 443 开放（46 毫秒）、22 被拒绝 | `results`，每项含 `port`、`open`、`latency_ms`，未开放时含 `reason` |

API请求示例：

```
POST /api/portcheck
host=example.com&ports=443,22&timeout=3
```

API响应示例：

```json
{
  "code": 0,
  "desc": "成功",
  "data": {
    "host": "example.com",
    "total": 2,
    "open_count": 1,
    "results": [
      {
        "port": 443,
        "open": true,
        "latency_ms": 46
      },
      {
        "port": 22,
        "open": false,
        "latency_ms": 47,
        "reason": "ConnectionRefusedError"
      }
    ]
  },
  "request_id": "7a1c9e2f4b6d48a0b3c5d7e9f1a2b4c6"
}
```

443 端口 open=true 并给出连接耗时；22 端口被拒绝，reason 返回 ConnectionRefusedError，开放的端口不携带该字段。

## 应用场景
- **服务监控**：周期性探测业务端口，端口不通即时告警。
- **上线自检**：新服务部署后确认对外所需端口已经开放。
- **防火墙核查**：安全策略调整后，从外部视角验证放行效果。
- **故障排查**：快速区分「服务没起来」还是「端口没放开」。

## 应用案例
**游戏服务器运维**：新服开服前要确认多个对外端口可访问，此前靠工程师逐个远程试连，速度慢且无记录。现在上线脚本调用本接口批量探测，开放状态与延迟一张表返回，异常端口当场定位，开服检查从半小时缩短到几分钟。

**监控平台开发者**：自研监控产品需要为客户提供端口拨测能力，直接接入本接口完成周期探测，延迟毫秒值用于绘制趋势图，结合 reason 字段区分超时与拒绝，告警信息更有依据，客户工单量明显下降。

常见问题

Q：为什么不能探测内网地址？

A：为防止被滥用为内网扫描工具，私有、回环、链路本地、保留网段地址一律拒绝；域名会先解析并校验全部 IP 均为公网。

Q：批量探测多个端口要多久？

A：最多 20 个端口并发探测，总耗时约等于单端口超时时间，默认 3 秒、最大可设 5 秒，而不是逐端口累加。

Q：端口未开放时返回什么？

A：open=false，并以 reason 给出原因（timeout 为超时、ConnectionRefusedError 为拒绝连接等），latency_ms 为本次探测耗时。

端口检测网络诊断运维监控服务器

接口地址： https://www.phpwc.cn/api/portcheck

请求方式： POST

业务请求参数

参数名	类型	必填	默认值	说明
`host`	string	必填	-	目标域名或公网 IP，禁止私有内网回环地址
`port`	int	选填	-	单个端口，范围 1~65535，与 ports 二选一
`ports`	string	选填	-	批量端口，逗号分隔，最多 20 个，如 80,443,22，与 port 二选一
`timeout`	float	选填	`3`	单端口连接超时秒数，范围 0.1~5，默认 3

查看签名算法查看调用示例

响应参数

字段名	类型	说明
`code`	int	状态码，0=成功
`desc`	string	状态描述
`data`−	object	业务数据（成功时返回）
`host`	string	探测目标
`total`	int	探测端口总数
`open_count`	int	开放端口数量
`results`−	array	各端口探测结果数组
`port`	int	端口号
`open`	boolean	端口是否开放
`latency_ms`	int	连接耗时（毫秒）
`reason`	string	未开放时的原因（timeout 超时、ConnectionRefusedError 拒绝等），open=true 时无此字段
`request_id`	string	请求追踪ID

JSON 示例：

调用成功：

{
  "code": 0,
  "desc": "success",
  "data": { ... },
  "request_id": "abc123..."
}

调用失败：

{
  "code": 999,
  "desc": "错误描述",
  "request_id": "abc123..."
}

请先登录后使用在线测试