flomesh/pipy

Pipy Docker镜像文档

镜像概述和主要用途

Pipy是一款轻量级、高性能的可编程代理，专为云、边缘计算和物联网（IoT）环境设计。它提供灵活的编程接口，允许用户根据特定需求定制代理逻辑，实现数据转发、过滤、转换和处理等功能。作为通用代理解决方案，Pipy能够适应从云端大规模部署到边缘设备资源受限环境的各种场景，为网络流量管理提供高度定制化能力。

核心功能和特性

• 可编程性：支持通过类JavaScript脚本语言定义代理行为，实现复杂流量处理逻辑（如请求/响应转换、动态路由、数据过滤等）。
• 多环境适配：针对云、边缘和物联网环境深度优化，可在服务器、嵌入式设备及资源受限场景中高效运行。
• 高性能：采用异步I/O模型和轻量级架构，高并发场景下保持低延迟和低资源占用。
• 轻量级设计：镜像体积小、启动速度快，适合容器化部署和边缘设备集成。
• 模块化架构：内置HTTP、TCP、TLS、WebSocket等丰富功能模块，支持按需组合扩展。
• 动态配置：支持运行时更新代理规则和配置，无需重启服务即可应用变更。

使用场景和适用范围

• 云服务代理：作为微服务间流量代理，实现服务发现、负载均衡、熔断限流等功能。
• 边缘计算数据处理：在边缘节点部署，对IoT设备原始数据进行本地过滤、聚合和预处理，减少云端传输压力。
• 物联网设备通信：为IoT设备提供安全通信隧道，支持MQTT、CoAP等物联网协议的代理与转换。
• API网关：管理客户端API请求，实现认证授权、请求限流、日志记录等功能。
• 网络流量监控：捕获分析网络流量，支持实时监控、日志收集和异常检测。
• 协议转换：在HTTP与WebSocket、TCP与UDP等不同协议间进行转换，实现异构系统通信。

使用方法和配置说明

基本部署（Docker Run）

拉取并运行Pipy基础镜像：

bash
docker run -d --name pipy-proxy -p 8080:8080 flomesh/pipy

• -d：后台运行容器
• --name pipy-proxy：指定容器名称
• -p 8080:8080：映射容器8080端口到主机（默认代理端口）
• flomesh/pipy：Pipy官方Docker镜像

自定义配置示例

通过挂载脚本文件定义代理逻辑：

1. 创建本地脚本proxy.js（示例：HTTP请求转发到example.com）：

javascript
pipy()
  .listen(8080)
  .serveHTTP(() =>
    $=>$.pipe(
      new HTTPProxy('example.com:80')
    )
  )

2. 挂载脚本运行容器：

bash
docker run -d --name pipy-custom -p 8080:8080 -v $(pwd)/proxy.js:/pipy/proxy.js flomesh/pipy /pipy/proxy.js

• -v $(pwd)/proxy.js:/pipy/proxy.js：挂载本地脚本到容器
• 最后的/pipy/proxy.js：指定启动执行的脚本路径

Docker Compose配置

创建docker-compose.yml：

yaml
version: '3'
services:
  pipy:
    image: flomesh/pipy
    container_name: pipy-proxy
    ports:
      - "8080:8080"  # HTTP代理端口
      - "8443:8443"  # HTTPS代理端口（如需）
    volumes:
      - ./proxy.js:/pipy/proxy.js  # 挂载自定义脚本
      - ./certs:/pipy/certs        # 挂载TLS证书（如需）
    restart: unless-stopped
    command: /pipy/proxy.js  # 执行自定义脚本

启动服务：

bash
docker-compose up -d

配置参数说明

环境变量

• PIPY_LOG_LEVEL：日志级别（debug/info/warn/error，默认info）
• PIPY_WORKERS：工作进程数（默认按CPU核心数自动调整）
• PIPY_CONFIG_PATH：默认配置脚本路径（默认/pipy/default.js）

核心API示例

• listen(port)：指定监听端口
• serveHTTP(handler)：配置HTTP代理处理逻辑
• connectTCP(handler)：配置TCP代理处理逻辑
• HTTPProxy(target)：创建HTTP代理目标
• TLSTermination(cert, key)：配置TLS终止（HTTPS）

高级代理逻辑示例

实现基于路径的HTTP路由和响应头修改：

javascript
pipy({
  _routes: {
    '/api/users': 'http://user-service:8080',
    '/api/orders': 'http://order-service:8080',
    '/': 'http://webapp:8080'
  }
})
  .listen(8080)
  .serveHTTP(
    $=>$.matchPath(_ => _routes[_.path] || 'http://default-service:8080')
      .pipe(
        new HTTPProxy(r => _routes[r])
      )
      .replaceMessage(
        msg => msg.setHeader('X-Proxy', 'Pipy')
      )
  )

功能说明：

• 根据请求路径路由到不同后端服务
• 为所有响应添加X-Proxy: Pipy头