jauderho/toxiproxy Docker镜像文档

镜像概述和主要用途

jauderho/toxiproxy 是基于 Toxiproxy 的 Docker 镜像。Toxiproxy 是一个网络条件模拟框架，旨在帮助开发和测试人员模拟各类网络异常场景，如延迟、丢包、带宽限制等，以验证应用在不稳定网络环境下的表现。该镜像由社区维护，提供多平台支持，确保与上游 Toxiproxy 版本同步，上游发布后 1 小时内构建更新，并每周至少重建一次以保持镜像时效性。

核心功能与特性

• 多类型网络条件模拟：支持延迟、带宽限制、数据包丢失、连接中断、网络抖动等多种异常场景
• 轻量级代理：基于 TCP/UDP 协议，资源占用低，可快速集成到测试环境
• 动态配置：通过配置文件或 HTTP API 实时调整代理规则，无需重启服务
• 多平台支持：提供 Linux/amd64、Linux/arm64 等架构镜像，适配不同硬件环境
• 自动更新机制：上游 Toxiproxy 发布新版本后 1 小时内自动构建镜像，每周定期重建确保依赖安全性

使用场景和适用范围

• 应用弱网测试：开发人员验证应用在高延迟、低带宽网络下的响应能力（如移动应用、IoT 设备）
• 容错机制验证：QA 团队测试服务在网络中断、数据包丢失时的重试逻辑和数据一致性
• CI/CD 集成：在自动化测试流程中注入网络异常，确保发布前覆盖边缘网络场景
• 分布式系统测试：模拟跨区域服务间的网络延迟，验证分布式协议（如共识算法）的稳定性
• 教学与演示：直观展示网络问题对系统的影响，辅助理解网络依赖关系

使用方法和配置说明

基础启动命令

通过 docker run 快速启动 Toxiproxy，默认监听 0.0.0.0:8474 并提供 HTTP API：

bash
docker run -d -p 8474:8474 --name toxiproxy jauderho/toxiproxy

环境变量配置

通过环境变量调整 Toxiproxy 基础运行参数：

配置文件使用

Toxiproxy 通过 JSON 配置文件定义代理规则，格式如下（示例文件 toxiproxy.json）：

json
{
  "proxies": [
    {
      "name": "web_service_proxy",       // 代理名称（唯一标识）
      "upstream": "[***]", // 上游服务地址（目标服务）
      "listen": "0.0.0.0:8080",         // 代理监听地址（容器内）
      "middleware": [                    // 网络异常规则配置
        {
          "name": "latency",             // 延迟中间件
          "attrs": {
            "latency": "500ms",          // 固定延迟
            "jitter": "100ms"            // 延迟抖动范围
          }
        },
        {
          "name": "loss",                // 丢包中间件
          "attrs": {
            "loss": 10,                  // 丢包率（百分比）
            "correlation": 50            // 丢包相关性（0-100）
          }
        }
      ]
    }
  ]
}

启动时挂载配置文件：

bash
docker run -d \
  -p 8474:8474 \
  -p 8080:8080 \  # 映射代理监听端口（对应配置文件中的 listen 端口）
  -v $(pwd)/toxiproxy.json:/toxiproxy.json \
  -e TOXIPROXY_CONFIG_FILE=/toxiproxy.json \
  --name toxiproxy jauderho/toxiproxy

Docker Compose 配置示例

创建 docker-compose.yml 集成 Toxiproxy 与测试服务：

yaml
version: "3.8"
services:
  toxiproxy:
    image: jauderho/toxiproxy
    ports:
      - "8474:8474"   # Toxiproxy API 端口
      - "8080:8080"   # 代理监听端口（对应配置文件中的 web_service_proxy）
    volumes:
      - ./toxiproxy.json:/toxiproxy.json
    environment:
      - TOXIPROXY_LOG_LEVEL=debug
      - TOXIPROXY_CONFIG_FILE=/toxiproxy.json
    depends_on:
      - web-service  # 依赖的上游服务

  web-service:
    image: nginx:alpine  # 示例上游服务（可替换为实际服务）
    ports:
      - "80:80"

部署方案示例

示例 1：模拟 HTTP 服务延迟与丢包

1. 创建配置文件 toxiproxy.json：

json
{
  "proxies": [
    {
      "name": "nginx_proxy",
      "upstream": "[***]",
      "listen": "0.0.0.0:8080",
      "middleware": [
        {
          "name": "latency",
          "attrs": { "latency": "1s", "jitter": "200ms" }
        },
        {
          "name": "loss",
          "attrs": { "loss": 15, "correlation": 30 }
        }
      ]
    }
  ]
}

2. 启动服务栈：

bash
docker-compose up -d

3. 测试代理效果（通过代理访问上游 Nginx）：

bash
curl http://localhost:8080  # 应感受到约 1 秒延迟，且部分请求失败（15% 丢包率）

示例 2：动态调整代理规则（HTTP API）

Toxiproxy 提供 HTTP API 动态管理代理（默认地址 http://localhost:8474）：

• 创建代理（添加带宽限制）：

  bash
  curl -X POST http://localhost:8474/proxies \
    -H "Content-Type: application/json" \
    -d '{
      "name": "bandwidth_proxy",
      "upstream": "tcp://db-service:3306",
      "listen": "0.0.0.0:3307",
      "middleware": [{"name": "bandwidth", "attrs": {"rate": "100kbit"}}]
    }'
  

• 查看代理列表：

  bash
  curl http://localhost:8474/proxies
  

• 删除代理：

  bash
  curl -X DELETE http://localhost:8474/proxies/bandwidth_proxy
  

注意事项

• 配置文件权限：挂载配置文件时确保容器内路径可读写（建议设置文件权限为 644）
• 端口映射：需将配置文件中 listen 定义的代理端口与宿主机端口映射（如示例中的 8080:8080）
• 上游服务可达性：确保 Toxiproxy 容器能访问配置中的 upstream 地址（可通过 Docker 网络连接服务）
• API 安全：生产环境建议通过防火墙限制 Toxiproxy API 端口（8474）访问，避免未授权配置修改