Hyperswitch 自托管:五个 Rust 服务、三个 profile,和一份要自己扛的运维清单
Hyperswitch 是 Juspay 开源的支付平台,仓库在 juspay/hyperswitch,文档在 docs.hyperswitch.io。用 Rust 写,Apache-2.0,2022 年 10 月创建,README 快照时约 45,859 stars,最近一次 push 记录在 2026-11-21,仍在活跃提交。
它的定位是「可组合的支付平台」:既能自托管,也能直接用 SaaS。连接 120+ 支付处理方(README 里两处口径分别是 100+ connectors 和 120+ processors),包括 Stripe、Adyen、Braintree、Worldpay、Checkout.com、Cybersource、Global Payments、PayPal、Bank of America 等。
下面只谈一件事:把 Hyperswitch 部署到自己的基础设施上,你会得到什么,又要付出什么。
先说不适用的情况
如果业务只接一家 PSP,比如只用 Stripe,或者只用 Stripe Connect、Braintree,那么这套东西带来的是净负担。多一层 app server、多一个数据库、多一套要跟版本的 vault,换来的路由能力你用不上。
Hyperswitch 值得自托管的前提通常是下面几条里至少中一条:
- 同时接了两家以上 PSP,需要在它们之间按授权率分流;
- 需要对失败交易做重试,并且要控制重试预算,不能无限重试把收单行风控惹毛;
- 需要 2-way / 3-way 对账,能回溯日期、错峰调度、自定义输出格式;
- 想把支付平台重构成多处理方架构,但现有的 VGS / TokenEx vault 不想动,卡不能重新 token 化。
模块边界:哪些能拆开单用
README 把能力拆成六块,每块都可以单独接:
- Cost Observability:审计、监控、优化支付成本,发现隐藏费用、降级和罚金;
- Revenue Recovery:按卡 BIN、地区、支付方式调优重试,并控制重试预算;
- Vault:PCI 合规的卡 / token / 钱包 / 银行凭证存储,支持 bring-your-own-vault,可以直接接 VGS、TokenEx 而不重新 token 化;
- Intelligent Routing:在多个 PSP 之间按预测授权率选路;
- Reconciliation:2-way / 3-way 对账,支持回溯日期、错峰调度、自定义输出;
- Alternate Payment Methods:PayPal、Apple Pay、Google Pay、Samsung Pay、Pay by Bank、Klarna 等 drop-in 组件。
真正决定部署形态的是仓库矩阵,服务边界比功能列表更清楚:
| 仓库 | 语言 | 职责 | 能否单独用 |
|---|---|---|---|
| hyperswitch | Rust | app server:路由、重试、vault 调用、可观测性 | 依赖 card-vault 与 encryption-service |
| hyperswitch-card-vault | Rust | PCI 合规卡存储 | 依赖 encryption-service |
| hyperswitch-encryption-service | Rust | 加解密与 KMS | 可独立部署 |
| hyperswitch-prism | Rust | 统一 connector 库 | 可以不跑整套 switch,直接对接处理方 |
| decision-engine | Rust | 独立路由控制平面,按规则与成功率选网关 | 可与任何 orchestrator 配合 |
| control-center | ReScript | 商户后台 | 配合 app server |
| control-center-embedded | TypeScript | 嵌入式组件 | 配合 app server |
| hyperswitch-web | ReScript React | 前端 SDK(npm) | 是 |
| hyperswitch-client-core | — | 共享核心 | 是 |
| react-hyper-js、sdk-utils | — | 前端相关工具 | 是 |
| Android | Kotlin / Maven | 移动端 SDK | 是 |
| iOS | Swift / CocoaPods | 移动端 SDK,SPM 进行中 | 是 |
| react-native-hyperswitch | — | React Native 绑定(npm) | 是 |
| flutter_hyperswitch | — | Flutter 绑定(pub.dev) | 是 |
| hyperswitch-suite | Terraform | 把 core、vault、control-center、web 串起来的 umbrella | 部署用 |
| hyperswitch-helm | Helm | K8s 部署 | 部署用 |
旧的 hyperswitch-sdk-react-native 已经从 npm 移除,新项目不要再用。
这张表里最该注意的是后两行之外的三个:prism 是一套统一的 connector 库,你可以只拿它去对接处理方,不跑整套 switch;decision-engine 是独立的控制平面,按规则和成功率选网关,理论上能配任何 orchestrator;card-vault + encryption-service 也可以单独作为卡存储层存在。也就是说,不一定非得「全量上 Hyperswitch」,可以只切一块进来。
三种启动方式
本地一键启动走脚本:
git clone --depth 1 --branch latest https://github.com/juspay/hyperswitch
cd hyperswitch
scripts/setup.sh
脚本会检测 Docker / Podman,提供三个 profile:
- Standard:app server + Control Center;
- Full:在 Standard 基础上加监控与调度器;
- Minimal:只有 app server。
跑完之后脚本会打印访问链接。想先看界面而不部署,可以用托管 sandbox:app.hyperswitch.io,不用部署就能配 connector、看日志 / 路由规则 / 重试策略、发起测试支付。
生产侧是 Helm charts,支持 AWS / GCP / Azure 或任意 K8s,部署文档在 deploy-on-kubernetes-using-helm;另有 hyperswitch-suite 这个 Terraform umbrella 仓库,把 core、vault、control-center、web 串起来一次性拉起。
自托管的实际代价
这一节是成本清单,不是劝退。
数据面组件要自己配齐。 app server 需要 Postgres 存配置和路由规则,需要 Redis 做缓存与限流,encryption-service 要接到你自己的 KMS(AWS KMS 之类)。具体版本要求和最小规格,我没有实测,按官方 Helm chart 的默认值来比较稳妥。
密钥和凭证在自己手里,风险也在自己手里。 每个 connector 的 API key、签名密钥都要自己保管和轮换;vault 里卡数据的加密密钥放在 KMS,一旦密钥丢失或被误删,卡数据就解不开——这不是「重启一下」能恢复的故障。Vault 的 bring-your-own-vault 模式可以接 VGS / TokenEx,好处是卡不重新 token 化,代价是两套系统的凭证都要维护。
升级不是单点动作。 服务是分开的,app server 依赖 card-vault 和 encryption-service,升级顺序和兼容性要自己确认。CHANGELOG.md 记录版本变更,数据库迁移的具体行为我没实测,上生产前建议先在 staging 完整走一遍升级路径。
PCI 范围没有消失,只是挪了位置。 card-vault 承担 PCI 合规的卡存储,app server 应当尽量不落卡号。自托管意味着合规审计、渗透测试、日志脱敏、访问控制仍然由你自己负责,托管 SaaS 时由对方承担的那部分责任,现在回到你这边。这部分工作量常常被低估。
监控和调度器在 Full profile 里才齐。 如果选 Minimal,只拿到 app server,可观测性和定时任务(对账的错峰调度就属于这类)要另外解决。
README 给出的三个起点
官方列出的典型迁移场景有三个,基本对应上面说的适用条件:
- 从单一 Stripe / Stripe Connect / Braintree 迁到多 PSP 路由;
- 商户用直连收单行(TSYS、JP Morgan Payments)替换掉原来的网关;
- 重构支付平台,但保留现有 VGS / TokenEx vault。
这三个场景的共同点是:已经有了支付复杂度,缺的是统一调度层。如果没有这层复杂度,Hyperswitch 帮不上忙。
社区与贡献
Slack 邀请链接:inviter.co/hyperswitch-slack,另有 GitHub Discussions 和 issue 模板。版本变更看仓库里的 CHANGELOG.md。
如果你正在做多 PSP 路由、重试或对账,值得花半天用 Minimal profile 或 sandbox 跑一遍;如果只是接一家 PSP,把这半天省下来。