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

Hyperswitch 部署配置实战config/deployments 下 Router、Scheduler 与 Drainer 配置生成及 Docker Compose 部署【免费下载链接】hyperswitchOpen 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/hyperswitchHyperswitch 作为可组合的支付平台自托管部署时需要同时跑通 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/routerdrainer独立的流处理组件负责消费 Redis 流对应crates/drainerscheduler定时任务组件又细分为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.tomlproduction 中则替换为线上地址如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.tomlproduction.toml[dummy_connector].enabledtrue启用模拟处理器false[user].force_two_factor_authfalsetrue[user].base_urlhttps://app.hyperswitch.iohttps://live.hyperswitch.io[frm].enabled欺诈检测truefalse[platform].allow_connected_merchantstruefalse[network_tokenization_supported_connectors]adyen,cybersource,peachpayments,trustpaycybersource,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即可复制env_specific.toml并改名为环境名_config.tomlcp config/deployments/env_specific.toml config/deployments/sandbox_config.toml编辑该文件填入 sandbox 环境的真实值vi config/deployments/sandbox_config.toml用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.tomlDrainer独立组件直接编辑 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中按官方片段启动服务注意将命令中的配置路径替换为你生成的对应环境文件Routerhyperswitch-serverhyperswitch-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/configProducerhyperswitch-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_FLOWproducerConsumerhyperswitch-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_FLOWconsumerDrainerhyperswitch-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小结一份配置从仓库到生产的路径整个流程可以归纳为四步在config/deployments/env_specific.toml基础上派生环境名_config.toml填写数据库、Redis、KMS、密钥等真实值变量含义对照 config.example.toml用cat将环境名.toml环境内建默认值如 sandbox.toml与用户值文件合并为环境名_release.toml作为 Router 的最终配置再以cat将 scheduler/consumer.toml 或 scheduler/producer.toml 叠加到 release 配置上派生 consumer/producer 配置直接编辑 drainer.toml 替换占位值然后按上述 Docker Compose 片段启动四个服务并用curl http://localhost:8080/health验证。这条“内建默认值 环境敏感值 角色参数”的三层拼装方式保证了同一套仓库配置可以无歧义地服务于 integration_test、sandbox 与 production 三套环境也是 Hyperswitch 自托管Self-host部署时推荐的做法。【免费下载链接】hyperswitchOpen 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考