# API 域名测速

TokenFlows 提供多个 API 接入域名：`https://api-new.tokenflows.org` 和 `https://api-us.tokenflows.org`。两个域名在不同网络运营商、不同地区下的延迟差异可能很明显，与其凭感觉猜，不如直接测一遍。

本文介绍的 `api-speed-test.sh` 会依次测试两个域名的 DNS 解析、网络延迟和 HTTPS 连接各阶段耗时，最后给出推荐结果。

## 脚本做了什么

1. **DNS 解析**：列出两个域名解析出的 IP，方便判断是否指向同一入口。
2. **ICMP Ping**：平均延迟与丢包率，作为链路质量的参考值。
3. **HTTPS 连接测试**：每轮请求拆解为 `DNS` `TCP 握手` `TLS 握手` `TTFB` `总计` 五段耗时，并记录 HTTP 状态码。
4. **汇总对比**：计算平均值、最小/最大值与 TTFB 中位数，自动判定哪个域名更快（差异小于 10% 时视为网络抖动，不强行下结论）。

## 一键运行

无需下载，直接执行：

```bash
curl -fsSL https://tokenflows.org/api-speed-test.sh | sh
```

> ⚠️ **安全提示**：这类命令会直接执行远端脚本。执行前建议先在浏览器打开 [https://tokenflows.org/api-speed-test.sh](https://tokenflows.org/api-speed-test.sh) 查看脚本内容。

脚本支持 macOS 与 Linux，仅依赖系统自带的 `curl`、`ping`、`dig`/`nslookup`，无需安装额外依赖。

## 输出示例

默认每个域名测试 5 轮，输出如下：

```text
============================================================
 TokenFlows API 域名连通性与速度测试
============================================================
 请求路径 : /
 测试轮数 : 5 轮/域名
 单次超时 : 10s
 测试时间 : 2026-09-21 14:40:38
 出口 IP  : 1.2.3.4

[1/4] DNS 解析
  api-new.tokenflows.org             172.67.188.54 104.21.64.247
  api-us.tokenflows.org              170.106.50.245

[3/4] HTTPS 连接测试 (DNS / TCP / TLS / TTFB)
  https://api-new.tokenflows.org/
    第 1/5 次  HTTP 401  DNS 2ms  TCP 1ms  TLS 315ms  TTFB 594ms  总计 914ms

============================================================
 汇总结果
============================================================
 域名                           成功 HTTP       DNS       TCP       TLS       TTFB      总计    最快    最慢
 api-new.tokenflows.org           5/5    401x5      2.8ms     3.6ms     325.6ms   505.2ms   837.8ms   665.7ms   933.1ms
 api-us.tokenflows.org            5/5    401x5      2.9ms     1.5ms     843.8ms   546.6ms   1395.4ms  1360.8ms  1420.6ms

结论
  平均总耗时 : api-new.tokenflows.org 838ms  vs  api-us.tokenflows.org 1395ms
  推荐: api-new.tokenflows.org  (快 40.0%)
```

## 参数

| 参数 | 说明 | 默认值 |
| --- | --- | --- |
| `-n, --rounds N` | 每个域名的测试轮数，网络波动大时可加大 | `5` |
| `-p, --path PATH` | 请求路径，可改为真实业务路径 | `/` |
| `-t, --timeout SEC` | 单次请求超时秒数 | `10` |
| `--no-ping` | 跳过 ICMP Ping（部分网络屏蔽 ICMP） | 不跳过 |
| `-h, --help` | 查看帮助 | - |

## 输出解读

| 指标 | 含义 | 说明 |
| --- | --- | --- |
| DNS | 域名解析耗时 | 超过 200ms 说明本地 DNS 解析较慢，可尝试更换 DNS |
| TCP | TCP 握手耗时 | 反映到接入点的网络往返延迟 |
| TLS | TLS 握手耗时 | HTTPS 证书协商，跨地区访问时通常最耗时 |
| TTFB | 首字节耗时 | 服务端处理 + 网络回程，最能反映接口真实体验 |
| 总计 | 单次请求总耗时 | 该域名一次完整请求的耗时 |

终端中会用颜色标注：绿色为正常，黄色为偏慢，红色为明显偏慢。

**关于 HTTP 状态码**：脚本不携带 API Key，因此返回 `401` 属于正常现象，只代表服务可达。只有 curl 报错（`000`）才算连通性失败。

## 退出码

| 退出码 | 含义 |
| --- | --- |
| `0` | 两个域名均连通并完成对比 |
| `1` | 存在无法连通的域名 |
| `2` | 参数错误或缺少依赖 |

可用在 CI 或监控脚本中判断网络健康度：

```bash
curl -fsSL https://tokenflows.org/api-speed-test.sh | sh >/dev/null 2>&1 \
  || echo "API 域名连通性异常"
```

## 常见问题

**Q：提示 `Permission denied`？**

说明是下载到本地后执行的，先运行 `chmod +x api-speed-test.sh` 再执行；也可以直接用上面的 `curl ... | sh` 方式运行。

**Q：一行命令会执行远端脚本，安全吗？**

脚本是纯 shell 实现、不含任何上传或写文件逻辑，可先访问 [https://tokenflows.org/api-speed-test.sh](https://tokenflows.org/api-speed-test.sh) 查看全部内容，也可以先下载到本地再执行。

**Q：Ping 显示无响应，但请求正常？**

部分网络（公司网络、部分云主机）会屏蔽 ICMP，这不代表域名不通。加 `--no-ping` 跳过即可。

**Q：TLS 耗时特别高（几百毫秒以上）？**

通常是跨地区访问导致，属于正常现象，优先选择 TLS 与 TTFB 更低的域名。

**Q：结果每次都不一样？**

网络本身存在抖动。增大轮数（`-n 20`）并关注平均值与中位数，不要只看单次结果。

**Q：想测试其他域名或路径？**

路径用 `-p` 指定；域名可在脚本顶部的 `DOMAIN_NEW`、`DOMAIN_US` 两个变量中修改。

## 相关文档

- [API 参考](/docs/api-reference)：查看各协议对应的 Base URL 与请求示例。
- [产品与排错](/docs/faq)：排查 API Key、额度与调用报错。