定制speedtest-cli：实现指定服务器精准网络测速与性能评估

1. 项目缘起：为什么需要定制你的测速工具？

如果你经常和服务器打交道，无论是管理自己的云主机、评估机房线路质量，还是为应用选择最佳的网络节点，speedtest-cli绝对是你工具箱里的老朋友。这个由 Ookla 官方提供的命令行测速工具，以其简单直接和相对准确的结果，成为了无数运维、开发乃至普通用户的首选。但用久了，你肯定会遇到一个让人挠头的问题：默认的测速服务器列表，真的能代表你的真实网络环境吗？

想象一下这个场景：你的业务服务器部署在某个特定的云服务商机房，用户主要来自某个地区。你用speedtest-cli跑了一下，结果显示带宽很高，延迟很低，一切看起来都很美好。但实际用户访问时，体验却差强人意。问题出在哪？很可能，speedtest-cli自动选择的“最优”服务器，与你业务服务器或目标用户所在的网络路径完全不同。它可能连接到了一个与你服务器同运营商但物理距离很远的节点，或者是一个虽然近但与你服务器之间网络质量不佳的节点。这种“测不准”的情况，对于需要精准评估特定两点间（例如：你的办公室到你托管在阿里云上海节点的服务器）网络质量的场景来说，是致命的。

网络上相关的讨论也印证了这一点。无论是新手在问“如何让 speedtest-cli 只测某个服务器”，还是老手在分享“修改源码指定 ID”的片段，核心诉求都是一致的：我们需要将网络性能测试的主动权掌握在自己手里，让测试结果服务于真实的业务场景，而不是被一个黑盒算法所左右。这就是本次项目的核心价值——通过修改speedtest-cli，使其能够稳定、可靠地连接到你指定的测速服务器，从而获得最具参考价值的网络性能数据。

2. 核心思路拆解：从“自动选择”到“精准指定”

标准的speedtest-cli工作流程可以概括为三步：获取服务器列表 -> 根据延迟和负载自动排序 -> 选择“最佳”服务器进行带宽测试。我们要做的修改，本质上是绕过第二步的自动排序逻辑，强制在第一步获取的列表中，锁定我们预先知道的一个或多个目标服务器。

2.1 理解speedtest-cli的服务器选择机制

要修改它，必须先理解它。speedtest-cli的核心是一个 Python 脚本。当你运行它时，它会首先向 Ookla 的配置服务器发起请求，获取一个包含全球数千个测速服务器信息的 JSON 列表。这个列表里的每个服务器都有唯一的id、host（域名或IP）、sponsor（运营商名称）、name（城市名）等属性。

默认情况下，脚本会使用speedtest模块中的Speedtest类。这个类有一个get_best_server方法，其内部逻辑大致是：

1. 对列表中的每个服务器（默认取前10个延迟较低的候选）发送一个小的 HTTP GET 请求（通常是获取一个latency.txt文件）。
2. 测量每个请求的往返延迟（Ping 值）。
3. 综合考虑延迟和服务器报告的当前负载，计算出一个分数。
4. 选择分数最高的服务器作为“最佳服务器”。

我们的目标，就是让这个过程不再“计算分数”，而是直接根据我们提供的条件（如服务器ID、主机名或赞助商名称）进行匹配和锁定。

2.2 修改方案的权衡与选型

实现“指定服务器”这个目标，通常有几种路径：

1. 命令行参数暴力覆盖：这是最直观的想法，比如增加一个--server-id 12345的参数。但这需要修改参数解析逻辑，并深入修改Speedtest类的内部方法，使其在接收到此参数时，跳过get_best_server，直接使用get_servers获取列表并从中查找目标。这种方式最干净，但修改点较多，需要对源码结构有较深理解。
2. 环境变量引导：通过设置环境变量来影响服务器列表的获取或选择逻辑。但这通常需要源码本身支持，原版speedtest-cli并不原生支持，因此实现起来和第一种方法类似，只是注入配置的方式不同。
3. 修改配置文件或列表缓存：speedtest-cli会缓存服务器列表。我们可以尝试修改这个缓存文件，只保留我们想要的服务器。这种方法有点“旁门左道”，且每次列表更新都可能失效，不够稳定。
4. 源码层硬编码：直接找到get_best_server方法，将其逻辑替换为根据固定ID返回服务器。这种方法最简单粗暴，但牺牲了灵活性，每次换服务器都要改代码，仅适用于单一固定场景的调试。

对于一个希望兼具灵活性和稳定性的解决方案，方案一（增强命令行参数）是最优选择。它保持了工具原有的使用习惯，只是增加了一个功能开关，既满足了指定测试的需求，又不影响原有的自动测试功能。接下来，我们就将按照这个思路进行实操。

注意：修改开源工具代码时，务必注意其许可证（speedtest-cli通常使用 Apache 2.0 许可证）。我们的修改仅供个人学习和使用参考。如果修改幅度较大，考虑向其上游项目提交功能请求或 Pull Request 是更开源的做法。

3. 实操准备：定位关键代码与理解结构

在动手之前，我们需要准备好“手术刀”和“解剖图”。

3.1 获取与查看源码

首先，确保你安装了原版的speedtest-cli。通常可以通过系统包管理器（如apt、yum）或 Python 的pip安装。但为了修改，我们更需要其源码位置。

对于通过pip安装的情况，可以使用以下命令找到其安装路径：

pip show speedtest-cli | grep Location

进入该Location目录，找到speedtest.py或类似的主文件。更推荐的做法是直接从其官方 Git 仓库（如 GitHub 上的sivel/speedtest-cli）克隆或下载一份源码副本，在一个独立的目录中进行修改，这样不会影响系统已安装的版本。

3.2 分析源码入口与服务器选择流程

用你喜欢的文本编辑器（如 VSCode, Vim, Sublime Text）打开speedtest.py。我们主要关注以下几个部分：

1. 参数解析部分：通常位于文件底部main()函数中，或使用argparse模块定义的地方。这里定义了--help,--share,--simple等现有参数。我们需要在这里添加新的参数，例如--server。
2. Speedtest类初始化：在main()函数中，会实例化一个Speedtest对象。我们需要将新参数传递给这个对象。
3. Speedtest类的get_best_server方法：这是核心中的核心。我们需要查看这个方法是如何实现的，并计划如何修改它，使其在接收到特定参数时，执行不同的逻辑。

让我们模拟一下代码的关键结构（以下为示意，非完整源码）：

# 在 speedtest.py 中可能存在的结构 def main(): parser = argparse.ArgumentParser(description='...') parser.add_argument('--server', help='Specify a server ID to test against.') # ... 其他已有参数 args = parser.parse_args() speedtest = Speedtest() # 我们需要将 args.server 传递给 speedtest 对象 speedtest.run(args) # 或者类似的调用 class Speedtest: def __init__(self): self.servers = [] self.best_server = {} # 可能需要一个属性来存储用户指定的 server_id self.user_specified_server_id = None def run(self, args): if args.server: self.user_specified_server_id = args.server self.get_servers() self.get_best_server() # 这个方法需要被改造 self.download() self.upload()

通过这样的分析，我们明确了修改的切入点：增强argparse以接收新参数，并修改Speedtest.get_best_server()方法的行为。

4. 核心修改步骤详解

现在，我们进入具体的代码修改环节。请务必在修改前备份原文件。

4.1 第一步：增强命令行参数解析

找到argparse.ArgumentParser相关的代码段。添加一个--server参数，用于接收服务器 ID。同时，可以考虑添加一个--server-host参数，用于直接指定主机名或IP，提供另一种指定方式。

# 在 speedtest.py 中找到类似下面的代码块进行修改 parser = argparse.ArgumentParser( description='Command line interface for testing internet bandwidth using speedtest.net.\n' '------------------------------------------------------------' '-----------------------------------------------------------') parser.add_argument('--server', '-s', type=int, help='Specify a server ID to test against. Overrides automatic selection.') parser.add_argument('--server-host', help='Specify a server host (domain or IP) to test against. Useful if server ID is unknown.') # 保持其他已有的 add_argument 行不变

这里，type=int确保了--server参数的值会被解析为整数，与服务器列表中的id字段类型匹配。--server-host则处理字符串类型的主机信息。

4.2 第二步：修改 Speedtest 类以接收参数

我们需要将命令行参数传递到Speedtest类的实例中。查看main()函数中Speedtest对象是如何被创建和使用的。通常，修改后的调用方式如下：

def main(): # ... 参数解析代码 ... args = parser.parse_args() # 实例化 Speedtest 对象 speedtest = Speedtest() # 将指定的服务器信息传递给对象 if args.server: speedtest.user_specified_server = {'id': args.server} elif args.server_host: # 注意：此时我们还不知道id，先存下host，后续在服务器列表中匹配 speedtest.user_specified_server = {'host': args.server_host} else: speedtest.user_specified_server = None try: # 运行测速，这里可能需要调整 run() 方法的签名以接收 args speedtest.run() except Exception as e: # ... 异常处理 ...

你可能需要修改Speedtest类的__init__方法，增加一个实例变量（如self.user_specified_server）来存储这些信息。

4.3 第三步：重写get_best_server方法逻辑

这是最关键的一步。找到Speedtest类中的get_best_server方法。我们需要用新的逻辑替换或扩展它。

新逻辑的核心思路：

1. 如果self.user_specified_server不为空，则执行“指定服务器”逻辑。
2. 否则，执行原有的自动选择逻辑。

“指定服务器”逻辑的详细步骤：

1. 确保服务器列表已加载：调用self.get_servers()（如果尚未调用）。
2. 在服务器列表中查找目标：
   • 如果指定了id，则遍历self.servers（这可能是一个嵌套字典），找到id匹配的服务器。
   • 如果指定了host，则遍历查找host属性部分匹配或完全匹配的服务器。这里需要处理host可能是域名或IP的情况，匹配逻辑可以稍宽松（如in判断）。
3. 验证服务器可用性：找到候选服务器后，不能直接使用。必须模仿原有逻辑，对该服务器执行一次延迟测试（Ping），以确保它当前是可响应的。如果无法连接或超时，应抛出明确错误，提示用户服务器不可用。
4. 赋值：将找到并验证通过的服务器字典赋值给self.best_server。

以下是修改后的get_best_server方法的一个简化示例：

def get_best_server(self, servers=None): """Select the best server based on automatic logic or user specification.""" if servers is None: servers = self.servers # 情况一：用户指定了服务器 if self.user_specified_server: specified = self.user_specified_server candidate = None # 扁平化服务器列表以便遍历（原数据结构可能是按国家/地区嵌套的） flat_servers = [] for country in servers.values(): for server in country: flat_servers.append(server) # 根据 ID 或 Host 查找 if 'id' in specified: for server in flat_servers: if server['id'] == specified['id']: candidate = server break elif 'host' in specified: target_host = specified['host'] for server in flat_servers: # 简单匹配：检查目标host是否出现在服务器的host字段中 if target_host in server['host']: candidate = server break # 找到第一个匹配的 if not candidate: raise ValueError('Could not find the specified server in the list.') # 验证服务器延迟（即是否可达） print('Testing latency to the specified server (%s) ...' % candidate['host']) candidate['latency'] = self.test_latency(candidate) # 假设有一个 test_latency 方法 if candidate['latency'] is None or candidate['latency'] > 10000: # 10秒超时 raise RuntimeError('The specified server (%s) is not responding.' % candidate['host']) self.best_server = candidate print('Selected server: %(name)s [%(id)s] (latency: %(latency).2f ms)' % self.best_server) return [self.best_server] # 情况二：原有自动选择逻辑 else: # 这里是原有的 get_best_server 代码，通常包括对多个服务器测延迟、排序等 # ... (保留原有代码) ... return best_servers

你需要根据实际的源码，找到原有的延迟测试函数（可能叫_test_latency,test_latency,_ping等）并调用它。同时，注意处理servers参数的数据结构，原版代码可能为了效率只测试前10个延迟最低的，但在指定模式下，我们需要遍历整个列表来查找。

4.4 第四步：调整run方法流程

确保run方法（或main函数中调用测速的流程）能够适应新的逻辑。通常run方法会依次调用get_servers(),get_best_server(),download(),upload()。我们的修改已经让get_best_server()行为发生了变化，因此run方法本身可能不需要大改，只需确保user_specified_server被正确传递和初始化。

5. 测试与验证你的修改

修改完成后，绝不能直接用于生产环境。必须进行充分的测试。

5.1 功能测试

1. 测试--server参数：

   # 首先，运行原版命令获取一个你附近的服务器的ID python speedtest.py --list | head -20 # 假设你看到一行：1234) Some ISP (City, Country) [10.0 km] # 那么 1234 就是服务器ID python speedtest.py --server 1234

   观察输出。它应该直接连接到 ID 为 1234 的服务器，并显示该服务器的名称和延迟，然后开始下载/上传测试。不会再出现“Selecting best server based on ping...”或列出多个服务器延迟的过程。

2. 测试--server-host参数：

   # 使用上面找到的服务器的 host 部分（例如：speedtest.example.com） python speedtest.py --server-host speedtest.example.com

   同样，它应该直接匹配并连接到该主机。

3. 测试错误处理：

   # 使用一个不存在的ID python speedtest.py --server 999999 # 或一个无效的主机 python speedtest.py --server-host nonexistent.example.com

   程序应该给出清晰的错误信息，如“Could not find the specified server...”或“The specified server is not responding.”，而不是崩溃或继续执行自动选择。

4. 测试回退功能：不添加任何--server或--server-host参数，运行程序。它应该完美地执行原有的自动选择服务器流程，确保我们的修改没有破坏原有功能。

5.2 兼容性测试

在不同的网络环境下测试，比如家庭网络、公司网络、不同的云服务器上。确保在各种情况下，指定服务器的功能都工作正常。特别要注意某些服务器可能不支持speedtest.net的测试协议或已下线，你的错误处理机制要足够健壮。

6. 进阶技巧与深度定制

基础功能实现后，我们可以考虑一些增强功能，让这个工具更加强大和易用。

6.1 实现服务器列表的过滤与搜索

--list命令会输出海量服务器，难以阅读。我们可以增强它：

• --list-country CN：只列出中国的服务器。
• --list-sponsor “China Telecom”：只列出中国电信赞助的服务器。
• --list-name “Shanghai”：只列出城市名包含“上海”的服务器。

这需要修改--list参数的处理逻辑，在打印列表前进行过滤。这能极大提升在大量服务器中寻找目标 ID 的效率。

6.2 允许多服务器指定与轮询测试

有时我们想对比同一个运营商在不同地区的服务器，或者对比不同运营商到本地的质量。可以扩展--server参数，使其接受一个逗号分隔的 ID 列表。

python speedtest.py --server 1234,5678,9012

修改后的逻辑可以依次对每个指定服务器进行完整的下载/上传测试，并输出对比表格。这需要重构测试循环，并妥善管理每个测试之间的状态（如重置计数器）。

6.3 结果输出定制化

默认的输出格式可能不适合自动化脚本处理。可以增加参数：

• --json：以 JSON 格式输出结果，便于被jq或其他编程语言解析。
• --csv：输出为 CSV 格式，方便导入电子表格。
• --simple --unit Mbps：以最简化的格式，并强制以 Mbps 为单位输出。

这需要修改结果打印部分的代码，根据参数选择不同的格式化函数。

6.4 集成到监控系统

将修改后的speedtest-cli封装成一个脚本，定期（如每15分钟）执行，测试到几个关键业务服务器的网络质量（延迟、丢包、带宽），并将结果推送到监控系统（如 Prometheus, Zabbix）或时间序列数据库（如 InfluxDB）。这样，你就能获得一个持续性的、针对特定路径的网络质量仪表盘，对于 SLA 监控和故障排查有巨大价值。

7. 常见问题与排查实录

在修改和使用过程中，你可能会遇到以下问题：

7.1 修改后运行报语法错误或导入错误

• 问题：执行python speedtest.py立刻报SyntaxError或ImportError。
• 排查：
  1. 检查语法：仔细检查你修改的代码行，特别是添加的冒号、括号、引号是否匹配。Python 对缩进极其敏感，确保新增代码块的缩进正确。
  2. 检查导入：如果你在修改中引用了新的模块（通常不需要），确保它们已安装。
  3. 回滚测试：用备份的原版文件替换回去，如果错误消失，说明问题肯定出在你的修改上。使用diff工具对比原文件和修改文件，定位差异点。

7.2 指定服务器 ID 后，程序依然执行自动选择

• 问题：使用了--server 1234，但程序还是打印出“Selecting best server based on ping...”。
• 排查：
  1. 参数传递检查：在main()函数中，打印一下args.server的值，确认它被正确解析。
  2. 实例变量检查：在Speedtest类的get_best_server方法开头，打印self.user_specified_server的值，确认它已从main函数正确传递过来。
  3. 逻辑分支检查：确认if self.user_specified_server:这一判断条件为True。注意，如果self.user_specified_server被初始化为空字典{}，它在 Python 中也是True。更好的做法是初始化为None，并判断if self.user_specified_server is not None:。

7.3 找到服务器但延迟测试失败

• 问题：程序找到了指定的服务器，但在测试延迟时卡住或返回超时。
• 排查：
  1. 网络连通性：手动ping或curl一下该服务器的host，看是否通。可能是服务器临时下线，或者你的网络到该服务器有防火墙限制。
  2. 协议与端口：speedtest测试使用的不是简单的 ICMP ping，而是 HTTP/HTTPS。检查服务器host的 80/8080/443 端口是否可达。有些服务器可能部署在非标准端口。
  3. 延迟测试方法：检查你调用的test_latency方法是否适用于所有服务器。原版方法可能对某些服务器响应处理不够健壮。可以尝试增加超时时间，或添加更详细的异常捕获和日志。

7.4 批量测试时结果不稳定或脚本中断

• 问题：当实现多服务器轮询测试时，跑到某个服务器后脚本报错停止。
• 排查：
  1. 异常隔离：在每个服务器的测试循环外，使用try...except包裹。即使一个服务器测试失败，也应记录错误并继续测试下一个。
  2. 资源清理：确保每次测试后，网络连接、临时文件等资源被正确释放，避免影响后续测试。
  3. 速率限制：过于频繁地向 Ookla 服务器列表接口或测速服务器发起请求，可能会被暂时限制。在循环中增加time.sleep(1)等间隔。

修改speedtest-cli来指定服务器，本质上是一个经典的“工具定制化”过程。它要求你不仅会使用工具，还要能深入其内部，理解其数据流和控制逻辑，并安全地进行手术式改造。这个过程带来的价值远不止于一个定制版的测速工具，它更锻炼了你阅读他人代码、设计功能扩展和解决实际问题的能力。当你下次再遇到一个“差不多好用”但“差点意思”的开源工具时，你会有足够的信心拿起编辑器，把它改造成完全适合自己工作流的利器。