juspaydotin/hyperswitch-router

开源***交换机镜像文档

镜像概述与主要用途

本镜像提供一款开源***交换机，作为支付处理的核心组件，旨在解决支付系统中的协议转换、交易路由和流程自动化问题。其核心价值在于通过开源架构降低支付系统构建门槛，同时确保交易处理的开放性、实时性、安全性和可靠性，适用于各类需要对接多支付渠道或构建自定义支付流程的场景。

核心功能与特性

核心功能

• 多协议支持：兼容主流支付协议（如ISO 8583、REST API、WebSocket等），实现不同支付系统间的协议转换
• 智能交易路由：基于预设规则（如成本、成功率、地域）动态路由交易请求至最优支付渠道
• 实时交易处理：毫秒级交易响应能力，支持高并发场景下的稳定处理
• 完整交易生命周期管理：包含请求验证、处理、响应、异常重试及对账流程

关键特性

• 开源可定制：源代码完全开放，支持根据业务需求修改核心逻辑或扩展功能模块
• 安全合规：内置数据加密（TLS 1.3）、敏感信息脱敏及PCI DSS合规相关配置
• 高可用性：支持集群部署与自动故障转移，保障交易系统持续运行
• 轻量化设计：基于微服务架构，可按需部署独立功能模块，降低资源占用

使用场景与适用范围

适用场景

• 支付网关构建：作为多渠道支付统一接入层，整合银行、第三方支付平台接口
• 跨境支付处理：处理多币种转换、国际支付协议适配及合规申报流程
• ***机构系统集成：银行、信用社等机构内部支付系统升级或新旧系统衔接
• 电商平台支付中台：支持平台内多商家、多支付方式的统一管理

目标用户

• ***科技公司（FinTech）
• 支付服务提供商（PSP）
• 电子商务平台技术团队
• 中小型银行及信用合作社

使用方法与配置说明

基本部署（Docker Run）

bash
docker run -d \
  --name financial-switch \
  --restart always \
  -p 8080:8080 \  # 交易API端口
  -p 8081:8081 \  # 管理后台端口
  -e SWITCH_ENV=production \  # 运行环境（development/production）
  -e DB_CONN_STR="postgresql://user:password@db-host:5432/financial_switch" \  # 数据库连接串
  -e API_KEY=your-secure-api-key \  # 管理API访问密钥
  -v /host/path/config:/app/config \  # 挂载自定义配置文件
  -v /host/path/logs:/app/logs \  # 挂载日志目录
  financial-switch:latest

Docker Compose配置示例

yaml
version: '3.8'
services:
  financial-switch:
    image: financial-switch:latest
    container_name: financial-switch
    restart: always
    ports:
      - "8080:8080"
      - "8081:8081"
    environment:
      - SWITCH_ENV=production
      - DB_CONN_STR="postgresql://user:password@db:5432/financial_switch"
      - API_KEY=your-secure-api-key
      - LOG_LEVEL=INFO
    volumes:
      - ./config:/app/config
      - ./logs:/app/logs
    depends_on:
      - db

  db:
    image: postgres:14-alpine
    container_name: financial-switch-db
    restart: always
    environment:
      - POSTGRES_USER=user
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=financial_switch
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

核心配置参数说明

环境变量

配置文件挂载

通过-v ./config:/app/config挂载自定义配置目录，支持以下配置文件：

• routes.yaml：交易路由规则配置
• channels.json：支付渠道连接参数
• security.yaml：加密算法及密钥配置

注意事项

• 生产环境需确保API_KEY复杂度（建议16位以上包含大小写字母、数字及特殊字符）
• 数据库需独立部署并定期备份，避免容器内数据丢失
• 高并发场景下建议配置MAX_CONCURRENT_TX参数并部署集群模式
• 首次启动需执行初始化脚本：docker exec -it financial-switch /app/init-db.sh