switchboardlabs/gateway

Switchboard On Demand Oracle - Gateway Docker镜像文档

1. 镜像概述和主要用途

Switchboard On Demand Oracle - Gateway Docker镜像是Switchboard去中心化预言机网络的核心组件，用于实现链下数据源与链上智能合约的双向通信。该镜像封装了按需数据请求处理、数据源集成、数据验证及***交互逻辑，提供标准化接口供智能合约调用，支持外部数据的按需获取、验证与上链，是连接Web2数据源与Web3智能合约的关键中间件。

2. 核心功能和特性

2.1 核心功能

• 按需数据请求处理：接收并处理来自智能合约的实时数据请求，支持单次/批量请求模式
• 多数据源集成：兼容HTTP/HTTPS API、WebSocket、数据库等多种数据源类型，支持自定义数据源配置
• 数据验证与签名：通过链下预言机节点私钥对数据进行加密签名，确保数据完整性与可信度
• 网络适配：支持EVM、、等主流网络，可通过配置切换目标链
• 请求队列管理：内置任务队列机制，处理高并发数据请求，避免系统过载

2.2 关键特性

• 低延迟响应：优化数据传输与处理流程，平均响应时间<500ms（取决于数据源延迟）
• 高可用性设计：支持多实例部署与负载均衡，故障自动恢复
• 配置灵活性：通过环境变量或配置文件自定义数据源、验证规则、网络参数
• 安全加固：内置请求频率限制、数据源白名单、私钥加密存储机制
• 可观测性：暴露Prometheus监控指标，支持日志分级输出（DEBUG/INFO/WARN/ERROR）

3. 使用场景和适用范围

3.1 典型应用场景

• DeFi协议：实时获取加密货币价格、流动性数据、借贷利率等市场信息
• NFT平台：监控NFT集合地板价、交易量、持有人分布等链下数据
• 企业级*应用**：对接ERP、CRM系统，将链下业务数据（如物流信息、供应链状态）上链存证
• 物联网（IoT）：接收传感器数据（如温度、位置信息）并触发智能合约执行（如保险赔付）
• 合规审计：从监管机构API获取合规数据，自动生成链上审计报告

3.2 适用范围

• 需按需触发数据获取的智能合约（非持续喂价场景）
• 对数据实时性要求高的Web3应用（响应时间<1s）
• 需要多数据源交叉验证的高安全性场景（如***交易、资产结算）
• 需自定义数据源逻辑的复杂业务场景（如多API聚合、数据清洗规则）

4. 使用方法和配置说明

4.1 镜像获取

bash
# 拉取最新稳定版镜像
docker pull switchboardlabs/on-demand-oracle-gateway:latest

# 拉取指定版本（推荐生产环境使用固定版本）
docker pull switchboardlabs/on-demand-oracle-gateway:v1.2.0

4.2 基础运行示例（docker run）

bash
docker run -d \
  --name oracle-gateway \
  -p 8080:8080 \
  -e ORACLE_PRIVATE_KEY="0x1234567890abcdef..." \  # 预言机节点私钥（用于数据签名）
  -e BLOCKCHAIN_NETWORK="ethereum-mainnet" \        # 目标区块链网络
  -e DATA_SOURCE_WHITELIST="https://api.coingecko.com,https://api.binance.com" \  # 数据源白名单
  -e LOG_LEVEL="INFO" \                             # 日志级别
  -v /host/path/config:/app/config \                # 挂载自定义配置文件（可选）
  switchboardlabs/on-demand-oracle-gateway:latest

4.3 Docker Compose配置示例

yaml
version: '3.8'
services:
  oracle-gateway:
    image: switchboardlabs/on-demand-oracle-gateway:v1.2.0
    container_name: oracle-gateway
    restart: always
    ports:
      - "8080:8080"  # 数据请求接口端口
      - "9090:9090"  # Prometheus监控端口
    environment:
      - ORACLE_PRIVATE_KEY=${ORACLE_PRIVATE_KEY}  # 从宿主机环境变量注入，避免硬编码
      - BLOCKCHAIN_NETWORK="solana-mainnet"
      - DATA_SOURCE_CONFIG_PATH="/app/config/datasources.yaml"
      - REQUEST_QUEUE_SIZE=1000
      - LOG_LEVEL="INFO"
      - CACHE_TTL=30  # 重复请求缓存时间（秒）
    volumes:
      - ./config:/app/config  # 挂载本地配置目录（包含数据源定义、验证规则）
      - ./logs:/app/logs      # 挂载日志目录（持久化存储）
    networks:
      - oracle-network

networks:
  oracle-network:
    driver: bridge

4.4 环境变量配置说明

4.5 配置文件说明

数据源及验证规则需通过YAML配置文件定义（默认路径/app/default-config.yaml，可通过DATA_SOURCE_CONFIG_PATH自定义）。示例配置如下：

yaml
# datasources.yaml示例
datasources:
  - name: "coingecko-price"  # 数据源名称（唯一标识）
    type: "http"             # 类型：http/websocket/postgres
    url: "https://api.coingecko.com/api/v3/simple/price"
    method: "GET"
    timeout: 3000            # 超时时间（毫秒）
    headers:                 # 自定义请求头
      - key: "Accept"
        value: "application/json"
    params:                  # 默认请求参数
      ids: "bitcoin,ethereum"
      vs_currencies: "usd"
    validation:              # 数据验证规则
      type: "json_schema"    # 支持json_schema/script（自定义脚本）
      schema:                # JSON Schema验证规则
        type: "object"
        properties:
          bitcoin:
            type: "object"
            properties:
              usd: {type: "number", minimum: 0}
        required: ["bitcoin"]

blockchain:
  rpc_url: "https://api.mainnet-beta.solana.com"  # 区块链节点RPC地址（优先于默认网络）
  confirmations: 2                               # 数据上链所需确认数

4.6 端口与网络配置

网络要求：容器需访问以下外部服务：

• 目标节点RPC接口（如 JSON-RPC、*** RPC）
• 配置文件中定义的数据源API
• （可选）Prometheus服务器（若需远程监控）

5. 运维与故障排除

5.1 日志查看

bash
# 实时查看日志
docker logs -f oracle-gateway

# 查看ERROR级别日志
docker logs oracle-gateway | grep "ERROR"

5.2 常见问题解决

5.3 性能优化建议

• 高并发场景：部署多个容器实例，前置负载均衡器（如Nginx）
• 低延迟需求：将容器部署在靠近数据源与***节点的网络环境（如同区域云服务器）
• 数据可靠性：配置多个同源数据源（如主备API），启用自动故障切换

6. 版本更新与维护

• 镜像版本遵循语义化版本（MAJOR.MINOR.PATCH）
• 生产环境建议使用固定版本标签（如v1.2.0），避免直接使用latest
• 更新方法：拉取新版本镜像后，停止旧容器并重新部署（需确保配置文件兼容）