Toxiproxy：网络故障模拟 TCP 代理

项目简介

Toxiproxy 是一个用于模拟网络条件的框架，专门为测试、CI 和开发环境设计。它支持对连接进行确定性的篡改，也支持随机化的混沌测试与自定义配置。项目的目标是帮助开发者用测试证明：自己的应用不存在单点故障。Toxiproxy 由两部分组成：用 Go 编写的 TCP 代理（即本仓库），以及通过 HTTP 与代理通信的客户端。你只需让应用的所有测试连接都经过 Toxiproxy，之后就可以通过 HTTP 操控这些连接的健康状态。自 2014 年 10 月起，Shopify 一直在其所有开发和测试环境中使用它。

主要功能

• TCP 代理 + HTTP API：可在测试运行时动态创建、启用、禁用代理，并注入故障。
• 多种 toxic（故障注入项）：latency、down、bandwidth、slow_close、timeout、reset_peer、slicer、limit_data、packet_loss。
• 多语言客户端：提供 Ruby、Go、Python、.NET、PHP、Node、Java、Haskell、Rust、Elixir 等客户端库。
• 命令行工具 toxiproxy-cli：无需写代码即可创建代理、添加 toxic、查看列表。
• 配置文件：可通过 -config 选项把 JSON 配置文件传给服务端。
• 日志级别可调：支持 panic、fatal、error、warn/warning、info、debug、trace，通过环境变量 LOG_LEVEL 设置。

安装与使用

Ubuntu

$ wget -O toxiproxy-2.13.0.deb https://github.com/Shopify/toxiproxy/releases/download/v2.13.0/toxiproxy_2.13.0_linux_amd64.deb
$ sudo dpkg -i toxiproxy-2.13.0.deb
$ sudo service toxiproxy start

macOS（Homebrew / MacPorts）

$ brew tap shopify/shopify
$ brew install toxiproxy

$ port install toxiproxy

Docker

$ docker pull ghcr.io/shopify/toxiproxy
$ docker run --rm -it ghcr.io/shopify/toxiproxy

源码编译

$ make build
$ ./dist/toxiproxy-server

填充代理：应用启动时（早于任何连接建立）需要告知 Toxiproxy 把哪些监听地址代理到哪里。可用客户端库的 populate 辅助方法：

Toxiproxy.populate([
  {
    name: "shopify_test_redis_master",
    listen: "127.0.0.1:22220",
    upstream: "127.0.0.1:6379"
  },
  {
    name: "shopify_test_mysql_master",
    listen: "127.0.0.1:24220",
    upstream: "127.0.0.1:3306"
  }
])

也可以用 CLI 创建代理：

toxiproxy-cli create -l localhost:26379 -u localhost:6379 shopify_test_redis_master

注入故障：把应用的连接地址改为 Toxiproxy 的监听端口后，即可在测试中操控：

redis = Redis.new(port: 22220)

Toxiproxy[:shopify_test_redis_master].downstream(:latency, latency: 1000).apply do
  redis.get("test") # will take 1s
end

或通过 CLI：

toxiproxy-cli toxic add -t latency -a latency=1000 shopify_test_redis_master

大型应用建议把配置写在单独的 config/toxiproxy.json，通过 -config 传给服务端，或用 populate 加载：

[
  {
    "name": "web_dev_frontend_1",
    "listen": "[::]:18080",
    "upstream": "webapp.domain:8080",
    "enabled": true
  },
  {
    "name": "web_dev_mysql_1",
    "listen": "[::]:13306",
    "upstream": "database.domain:3306",
    "enabled": true
  }
]

注意事项

• Toxiproxy 2.0 对 API 做了不兼容 1.x 的改动，使用 2.x 服务端时需确保客户端库版本匹配，可通过 /version 端点查看服务端版本。
• 监听端口建议避开临时端口范围，避免随机端口冲突；Linux 默认范围是 32768 到 61000，见 /proc/sys/net/ipv4/ip_local_port_range。
• 代理命名建议采用 <app>_<env>_<data store>_<shard>，避免多个应用共用同一个 Toxiproxy 时发生冲突。
• 以宿主机方式（--net=host）使用 Docker 镜像时，API 绑定在 0.0.0.0，可从各主机接口访问；若其他机器能访问该主机，请通过 -e TOXIPROXY_AUTH_TOKEN=<token> 设置认证令牌。

---

本作品整理自 GitHub 开源项目 Shopify/toxiproxy，原作者 @Shopify，许可证 MIT。中文介绍由 AI 根据项目 README 整理，以原仓库为准。