elixircloud/prowes

GA4GH WES中间件注入代理服务镜像文档

镜像概述与主要用途

本镜像是一个轻量级代理服务，专为全球基因组与健康联盟(GA4GH)工作流执行服务(WES)设计，核心功能是在WES请求的处理流程中注入自定义中间件。通过该代理，用户可灵活扩展GA4GH WES服务的功能，如添加认证授权、请求日志记录、数据转换、流量控制等自定义逻辑，而无需修改后端WES服务本身。适用于需要定制化WES请求处理流程的科研机构、生物信息平台及***健康数据处理系统。

核心功能与特性

1. 中间件注入机制

• 支持在WES请求生命周期的关键阶段（请求接收、处理前、响应返回前）插入中间件
• 支持链式执行多个中间件，按配置顺序依次处理请求

2. GA4GH WES协议兼容

• 完全兼容GA4GH WES API规范（v1.0及以上）
• 支持标准WES端点代理，包括/service-info、/runs、/runs/{run_id}等

3. 灵活配置能力

• 通过YAML配置文件定义中间件类型、参数及执行顺序
• 支持动态调整中间件链，无需重启代理服务

4. 轻量级与高可用

• 基于轻量级Web框架构建，资源占用低（内存<100MB，CPU占用率<5%）
• 支持健康检查接口，便于容器编排平台实现自动恢复

5. 可扩展性

• 提供中间件开发SDK，支持自定义中间件实现（Python/Go语言）
• 内置常用中间件模板：认证中间件（JWT/OAuth2）、日志中间件、请求验证中间件

使用场景与适用范围

典型使用场景

• WES服务功能扩展：为现有GA4GH WES服务添加审计日志、权限控制等功能
• 多租户WES管理：为不同租户请求应用差异化中间件策略（如资源配额限制）
• 科研数据安全增强：注入数据脱敏中间件，确保WES请求中的敏感信息合规处理
• 请求调试与监控：通过日志中间件记录完整请求/响应数据，辅助问题排查

适用范围

• 部署GA4GH WES服务的基因组学研究机构
• 生物信息学工作流管理平台
• ***健康数据处理中心
• 需要定制化工作流执行流程的科研团队

使用方法与配置说明

前提条件

• Docker Engine 20.10+ 或 Docker Desktop 4.0+
• 可访问的GA4GH WES后端服务实例
• 中间件配置文件（如使用自定义中间件）

获取镜像

bash
docker pull [镜像仓库地址]/ga4gh-wes-proxy:latest
# 示例：docker pull ghcr.io/example/ga4gh-wes-proxy:v1.2.0

基本使用示例（Docker Run）

bash
docker run -d \
  --name wes-proxy \
  -p 8080:8080 \  # 代理服务端口
  -e WES_BACKEND_URL="http://wes-backend:8000" \  # 后端WES服务地址
  -e LOG_LEVEL="info" \  # 日志级别（debug/info/warn/error）
  -v ./middleware-config.yaml:/app/config/middleware.yaml \  # 挂载中间件配置文件
  [镜像仓库地址]/ga4gh-wes-proxy:latest

Docker Compose配置示例

yaml
version: '3.8'
services:
  wes-proxy:
    image: [镜像仓库地址]/ga4gh-wes-proxy:latest
    container_name: wes-proxy
    ports:
      - "8080:8080"
    environment:
      - WES_BACKEND_URL=http://wes-backend:8000
      - PROXY_PORT=8080
      - LOG_LEVEL=info
      - HEALTH_CHECK_INTERVAL=30s  # 健康检查间隔
    volumes:
      - ./middleware-config.yaml:/app/config/middleware.yaml
      - ./logs:/app/logs  # 挂载日志目录
    depends_on:
      - wes-backend
    restart: unless-stopped

  wes-backend:
    image: ga4gh/wes-ga4gh:latest  # 示例后端WES服务
    ports:
      - "8000:8000"

配置参数说明

环境变量

中间件配置文件格式（YAML）

yaml
# middleware-config.yaml示例
middlewares:
  - name: "logging"  # 内置日志中间件
    type: "logging"
    config:
      log_path: "/app/logs/wes-proxy.log"
      log_format: "json"  # text/json
      include_request_body: true  # 是否记录请求体
      include_response_body: false  # 是否记录响应体

  - name: "jwt-auth"  # JWT认证中间件
    type: "auth.jwt"
    config:
      jwks_url: "https://auth.example.com/.well-known/jwks.json"
      required_claims:  # 必须包含的JWT声明
        - "scope:wes.execute"
      exclude_paths:  # 排除认证的路径
        - "/service-info"

  - name: "request-validator"  # 请求验证中间件
    type: "validation"
    config:
      schema_path: "/app/schemas/wes-request.schema.json"  # 自定义请求JSON Schema

验证服务运行

1. 启动代理服务后，访问健康检查接口：

   bash
   curl http://localhost:8080/health
   # 预期响应：{"status": "healthy", "backend_connected": true}
   

2. 验证WES服务代理：

   bash
   curl http://localhost:8080/service-info
   # 应返回后端WES服务的service-info响应，并包含X-Proxy: ga4gh-wes-proxy头
   

自定义中间件开发指南

如需开发自定义中间件，请参考官方GitHub仓库的https://github.com/%5B%E7%BB%84%E7%BB%87%E5%90%8D%5D/ga4gh-wes-proxy/blob/main/docs/middleware-dev-guide.md%EF%BC%8C%E6%94%AF%E6%8C%81Python%EF%BC%88%E9%80%9A%E8%BF%87Flask%E4%B8%AD%E9%97%B4%E4%BB%B6%E6%8E%A5%E5%8F%A3%EF%BC%89%E5%92%8CGo%EF%BC%88%E9%80%9A%E8%BF%87HTTP Handler接口）两种开发方式。