首页
/ Hyperswitch 部署配置实战：config/deployments 下 Router、Scheduler 与 Drainer 配置生成及 Docker Compose 部署

Hyperswitch 部署配置实战：config/deployments 下 Router、Scheduler 与 Drainer 配置生成及 Docker Compose 部署

2026-09-05 21:39:56作者：郁楠烈Hubert
hyperswitch
Open source, composable payments platform | PCI compliant | SaaS and Self-host options | Enables connectivity to multiple payment, payout, fraud, vault and tokenization providers | Uplifts authorization with intelligent routing and revenue recovery | Reduce payment processing costs with cost observability | Reduces payment ops with reconciliation
项目地址：https://gitcode.com/GitHub_Trending/hy/hyperswitch

Hyperswitch 作为可组合的支付平台，自托管部署时需要同时跑通 router、drainer 和 scheduler 三个组件。本文以仓库内 config/deployments/README.md 为骨架，完整讲解三个环境的 Router 配置如何与 env_specific.toml 合并生成发布配置、Scheduler 的 consumer/producer 配置如何在其上派生、Drainer 如何独立配置，以及最终如何通过 Docker Compose 启动四个服务并验证健康检查。读完后你可以直接照做，为 sandbox / production / integration_test 任一环境产出一份可部署的配置文件。

三大部署组件与配置文件的一一对应关系

从 config/deployments/README.md 的定义看，Hyperswitch 有 3 个组件：

  • router：核心 API 服务，处理支付、退款、争议等请求，对应 crates/router；
  • drainer：独立的流处理组件，负责消费 Redis 流，对应 crates/drainer；
  • scheduler：定时任务组件，又细分为 consumer（消费端）和 producer（生产端）两个角色，对应 crates/scheduler。

关于这三个组件在整体架构中的职责划分，可参阅 docs/architecture.md。

config/deployments 目录为 router 组件维护了 3 套环境配置：integration_test（集成测试）、sandbox（沙箱）和 production（生产）。目录结构如下：

config/deployments            # 部署配置根目录
├── README.md                 # 说明文档
├── drainer.toml              # drainer 专属配置
├── env_specific.toml         # 环境敏感值（由用户按环境填写）
├── integration_test.toml     # integration_test 环境专属配置
├── production.toml           # production 环境专属配置
├── sandbox.toml              # sandbox 环境专属配置
└── scheduler                 # scheduler 配置目录
    ├── consumer.toml         # consumer 角色配置
    └── producer.toml         # producer 角色配置

这些文件与 crates/router、crates/scheduler、crates/drainer 各自加载的配置结构对应，是部署时唯一需要人工干预的配置层。

Router 配置：三套环境文件与环境名 1:1 映射

integration_test.toml、sandbox.toml、production.toml 分别对应同名环境，官方建议在整个流程中统一使用环境名作为文件名，避免歧义。这三份文件承载的是 Hyperswitch 推荐的环境内建默认值，它们的内容体量很大（各约 1100 行），主要包括：

  • [connectors]：全部支付连接器的 base_url。以 sandbox 为例，adyen.base_url = "https://checkout-test.adyen.com/" 等测试地址（见 sandbox.toml）；production 中则替换为线上地址，如 adyen.base_url = "https://{{merchant_endpoint_prefix}}-checkout-live.adyenpayments.com/checkout/"（见 production.toml）。文件内注释明确提示：这些属性不是可选的，无效或空值会导致 Hyperswitch 请求失败；
  • [pm_filters.<connector>] 与 [payout_method_filters.<connector>]：按连接器声明的支付方式国家/币种白名单，用于在列表支付方式（PML）等接口中过滤；
  • [mandates.supported_payment_methods]、[zero_mandates.supported_payment_methods]：各支付方式的 mandate 支持矩阵；
  • 其他行为开关，如 [webhooks]、[tokenization]、[merchant_advice_codes.*]（商家建议码到重试策略的映射）等。

通过对比 sandbox 与 production 两份文件，可以看到几处典型的环境差异（可直接作为部署核对参考）：

配置项 sandbox.toml production.toml
[dummy_connector].enabled true（启用模拟处理器） false
[user].force_two_factor_auth false true
[user].base_url https://app.hyperswitch.io https://live.hyperswitch.io
[frm].enabled（欺诈检测） true false
[platform].allow_connected_merchants true false
[network_tokenization_supported_connectors] adyen,cybersource,peachpayments,trustpay cybersource,peachpayments
连接器 base_url 沙箱/测试域名 线上域名

env_specific.toml：敏感值与环境专属参数的载体

env_specific.toml 单独存放 因部署环境而异、且通常涉及敏感信息 的值，因此与上面三份“环境内建值”文件分开维护，需要由部署者按实际环境填写。文件头部注释指明：每个配置项的含义以 config/config.example.toml 为权威说明。

结合 config.example.toml 的注释，env_specific.toml 中的关键段落可归为几类：

数据库连接（每个库段落结构一致，字段包括 username/password/host/port/dbname/max_pool_size/min_idle_pool_size/connection_timeout/queue_strategy/idle_timeout/max_lifetime）：

  • [master_database]：主 SQL 数据存储；
  • [replica_database]：只读副本，用于分担读流量；
  • [accounts_database]：账户 schema 库（merchant accounts、profiles、MCAs、key stores）；
  • [global_database]：全局租户库（users、roles）；
  • [analytics.sqlx]：分析库连接（source = "sqlx" 时使用），另支持 [analytics.clickhouse] 作为 ClickHouse 数据源。

缓存与队列：[redis] 段包含 host/port/pool_size/default_ttl 以及集群模式相关配置（cluster_enabled、cluster_urls）。scheduler 与 drainer 的流（stream）都建立在 Redis 之上，因此这里配置是否正确直接决定后台任务链路能否工作。

密钥与加解密：[secrets]（master_enc_key 为 32 字节主加密钥、admin_api_key、jwt_secret）、[jwekey]（与 Rust Locker 对应的公私钥对）、[secrets_management.aws_kms] 与 [encryption_management.aws_kms]（key_id、region，用于 KMS 托管的密钥解密）。

服务与网络：[server]（workers、port、host、shutdown_timeout、request_body_limit 等，另有 [server.tls] 提供 HTTPS 端口与证书路径）、[proxy]（HTTP/HTTPS 代理与绕过列表）、[log.console] / [log.file] / [log.telemetry]（日志级别与 OpenTelemetry 上报端点）。

外部服务：[events.kafka]（各类事件 topic）、[file_storage.aws_s3]、[email] / [email.aws_ses]、[locker]（卡片保险库主机与 mock_locker 开关）、[network_tokenization_service]、[grpc_client.*] 等。

部署时应逐段替换这些占位值（如 db_user、clickhouse_password、kms_key_id），这是整个配置生成流程中唯一必须人工编辑的文件。

生成 Router 最终配置：cat 合并三步法

以 sandbox 环境为例，官方文档给出的完整步骤如下（其他环境把 sandbox 换成 production 或 integration_test 即可）：

  1. 复制 env_specific.toml 并改名为 <环境名>_config.toml：

    cp config/deployments/env_specific.toml config/deployments/sandbox_config.toml

  2. 编辑该文件，填入 sandbox 环境的真实值：

    vi config/deployments/sandbox_config.toml

  3. 用 cat 将环境内建值文件与用户值文件合并为最终的发布配置：

    cat config/deployments/sandbox.toml config/deployments/sandbox_config.toml > config/deployments/sandbox_release.toml

合并产物 sandbox_release.toml 即为“可以部署到 sandbox 环境”的 Router 配置。README 特别提示：如需部署到其他环境，把命令中的 sandbox 替换为对应环境名（如 production、integration_test）即可复用同一套步骤。

Scheduler：在 Router 配置之上派生 consumer / producer 配置

Scheduler 的配置不是独立完整的配置，而是在 Router 的 *_release.toml 基础上叠加角色参数生成。两个角色文件的差异（来自 consumer.toml 与 producer.toml）：

公共部分 [scheduler]：

[scheduler]
consumer_group = "scheduler_group"
graceful_shutdown_interval = 60000 # 关停重试等待时间（毫秒）
loop_interval = 3000                # consumer 轮询间隔（毫秒）；producer 为 30000
stream = "scheduler_stream"         # Redis 流名称

consumer 专属 [scheduler.consumer]：

[scheduler.consumer]
consumer_group = "scheduler_group"
disabled = false  # 是否允许 consumer 实际消费任务

producer 专属 [scheduler.producer]：

[scheduler.producer]
batch_size = 50                      # 单条 Redis 队列条目中打包的任务数
lock_key = "producer_locking_key"    # Redis 中 producer 分布式锁的键
lock_ttl = 160                       # 锁的过期时间（秒）
lower_fetch_limit = 900              # 从队列拉取条目的下限（秒）
upper_fetch_limit = 0                # 上限（0 表示不设上限）

两者还有 [scheduler.server] 段落，用于暴露本地服务端口（默认 port = 3000、host = "127.0.0.1"、workers = 1）。

生成方式同样是 cat 合并，且角色文件在前、Router release 配置在后：

# sandbox 环境的 consumer
cat config/deployments/scheduler/consumer.toml config/deployments/sandbox_release.toml > config/deployments/consumer_sandbox_release.toml

# sandbox 环境的 producer
cat config/deployments/scheduler/producer.toml config/deployments/sandbox_release.toml > config/deployments/producer_sandbox_release.toml

Drainer：独立组件，直接编辑 drainer.toml 使用

与 Router/Scheduler 不同，drainer 不依赖其他配置文件，drainer.toml 可直接使用——前提是先把其中的占位值替换为本环境的真实值。其核心参数：

[drainer]
loop_interval = 500        # 轮询间隔（毫秒）
max_read_count = 100       # 单次最多读取条目数
num_partitions = 64        # 分区数
shutdown_interval = 1000   # 关停间隔（毫秒）
stream_name = "drainer_stream"

其余段落包括 [master_database]（连接串与 pool_size）、[redis]（cluster_enabled、max_failure_threshold_seconds 等）、[secrets_management.aws_kms] / [encryption_management.aws_kms] 以及 [log.*]。因为 drainer 会直连数据库和 Redis，部署前必须确保 master_database 与 redis 段与 Router 使用的基础设施一致。

Docker Compose 启动四个服务并验证

配置就绪后，可以在 docker-compose.yml 中按官方片段启动服务（注意将命令中的配置路径替换为你生成的对应环境文件）：

Router（hyperswitch-server）：

hyperswitch-server:
  image: docker.juspay.io/juspaydotin/hyperswitch-router:latest # 拉取 latest 镜像；如需不带附加特性（如 KMS）的裸版本可换成 standalone，但不建议用于生产
  command: /local/bin/router --config-path /local/config/deployments/sandbox_release.toml # 替换为实际生成的配置
  ports:
    - "8080:8080"
  volumes:
    - ./config:/local/config

Producer：

hyperswitch-producer:
  image: docker.juspay.io/juspaydotin/hyperswitch-producer:latest
  command: /local/bin/scheduler --config-path /local/config/deployments/producer_sandbox_release.toml
  volumes:
    - ./config:/local/config
  environment:
    - SCHEDULER_FLOW=producer

Consumer：

hyperswitch-consumer:
  image: docker.juspay.io/juspaydotin/hyperswitch-consumer:latest
  command: /local/bin/scheduler --config-path /local/config/deployments/consumer_sandbox_release.toml
  volumes:
    - ./config:/local/config
  environment:
    - SCHEDULER_FLOW=consumer

Drainer：

hyperswitch-drainer:
  image: docker.juspay.io/juspaydotin/hyperswitch-drainer:latest
  command: /local/bin/drainer --config-path /local/config/deployments/drainer.toml
  volumes:
    - ./config:/local/config

几点来自配置文件的实现佐证：

  • producer 与 consumer 共用同一个 scheduler 二进制，靠环境变量 SCHEDULER_FLOW 区分角色，因此两个服务段的 command 完全一致、仅环境变量不同；
  • 四个服务都把宿主机的 ./config 挂到容器内 /local/config，所以 --config-path 指向的是容器内路径 /local/config/deployments/...，与你本地 config/deployments 目录一一对应；
  • Router 暴露 8080 端口，与 env_specific.toml 中 [server].port = 8080 保持一致。

启动后，可用健康检查端点确认 Router 已就绪：

curl --head --request GET 'http://localhost:8080/health'

小结：一份配置从仓库到生产的路径

整个流程可以归纳为四步：

  1. 在 config/deployments/env_specific.toml 基础上派生 <环境名>_config.toml，填写数据库、Redis、KMS、密钥等真实值（变量含义对照 config.example.toml）；
  2. 用 cat 将 <环境名>.toml（环境内建默认值，如 sandbox.toml）与用户值文件合并为 <环境名>_release.toml，作为 Router 的最终配置；
  3. 再以 cat 将 scheduler/consumer.toml 或 scheduler/producer.toml 叠加到 release 配置上，派生 consumer/producer 配置；
  4. 直接编辑 drainer.toml 替换占位值，然后按上述 Docker Compose 片段启动四个服务，并用 curl http://localhost:8080/health 验证。

这条“内建默认值 + 环境敏感值 + 角色参数”的三层拼装方式，保证了同一套仓库配置可以无歧义地服务于 integration_test、sandbox 与 production 三套环境，也是 Hyperswitch 自托管（Self-host）部署时推荐的做法。

hyperswitch
Open source, composable payments platform | PCI compliant | SaaS and Self-host options | Enables connectivity to multiple payment, payout, fraud, vault and tokenization providers | Uplifts authorization with intelligent routing and revenue recovery | Reduce payment processing costs with cost observability | Reduces payment ops with reconciliation
项目地址：https://gitcode.com/GitHub_Trending/hy/hyperswitch
登录后查看全文

相关内容推荐

1 Hyperswitch config_importer 实战：将 TOML 配置文件一键转换为 Kubernetes 环境变量2 深入解析 Hyperswitch 的 router 主 crate：目录布局、双二进制架构与 Feature 切换机制3 Hyperswitch Decision Engine 的 PostgreSQL 部署：Compose Profile、Make 目标与源码级配置详解4 Hyperswitch Analytics 数据管道实战：Kafka + ClickHouse + OpenSearch（olap Profile）的部署与配置5 零到生产：Hyperswitch全场景部署指南（本地开发→云环境）6 Hyperswitch 生态 Decision Engine 的 MySQL 部署指南：Docker Compose、Make 目标与健康验证全解析7 Hyperswitch Decision Engine 配置指南：Toml 配置项全解与生产环境调优实践8 hyperswitch 中的 Decision Engine 安装指南：从一条 Docker Compose 命令到 Compose、源码构建与 Helm 的完整矩阵9 4个高效步骤实现OpenCloud企业级部署10 OpenCloud云平台实战部署：从环境搭建到服务验证的极简路径
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

qBittorrent WebAPI 变更日志详解：从 2.11 到 2.16 的 API 演进、破坏性变更与源码级实现剖析Godot Engine 的 thirdparty 目录：第三方库 Vendor 化、补丁管理与更新流程全解析fuels-rs Codec 详解：基于 ABIEncoder / ABIDecoder 的类型序列化与反序列化机制Scrapling MCP Server 详解：把三级 Web 抓取能力接入 AI Agent 的完整实践zx ProcessPromise 完全指南：Promise 语义下的进程控制、管道流与输出格式化Adobe 前端面试题全解：从 front-end-interview-handbook 看 JS 算法、UI 组件与系统设计考点Khoj 自定义 Agent 实现指南：从 Admin 创建、权限模型到 API 与知识绑定机制AutoGPT 前端实战：用 useLatest 稳定回调引用，解决 React Effect 重复执行与闭包过期问题Open Notebook 本地私有化部署实战：Docker Compose + Ollama 构建 100% 离线的 NotebookLM 式研究助手MinerU 壁仞（Biren）加速卡部署指南：从镜像加载到服务启动的完整实操

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
854
1.34 K
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.12 K
2.72 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
528
588
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
906
1.83 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.53 K
1.01 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
989
508
ops-mathops-math
本项目是CANN提供的数学类基础计算算子库，实现网络在NPU上加速计算。
C++
1.34 K
1.45 K
docsdocs
暂无描述
Markdown
892
5.79 K
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
213
313