Hyperswitch 本地部署完全指南Docker Compose、Nix 与 Rust 源码环境搭建及 API 实战【免费下载链接】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 是一个开源、可组合的支付网关可通过统一的 API 连接多家支付、收款、风控与 Token 化服务提供商。本文基于仓库中的 docs/try_local_system.md 编写系统讲解在本地运行 Hyperswitch 的三条主流路径Docker Compose 一键运行、Docker Compose 开发环境、Nix 开发环境以及从源码自建 Rust 运行环境、初始化数据库、配置并启动应用最后借助 Postman 集合完成“创建商户 → 创建 API Key → 配置支付连接器 → 发起支付与退款”的端到端联调。读完本文你将具备把 Hyperswitch 跑在本机并开始调用其支付 API 的完整实战能力。本地运行 Hyperswitch 的三条路径Hyperswitch 的本地运行方式取决于你的目标官方文档给出的建议如下场景推荐方式特点只想快速试用、体验支付 API使用 Docker Compose 拉取 Docker Hub 镜像运行无需安装 Rust 工具链最省事需要修改源码、调试代码使用 Docker Compose 搭建开发环境源码挂载进容器cargo run热编译运行首次编译耗时长开发者、贡献者、希望环境可复现使用 Nix 开发环境依赖被 Nix 统一管理跨 MacOS / Linux / WSL2深度定制、脱离容器运行在宿主机安装 Rust 与各依赖灵活度最高需自行管理 PostgreSQL、Redis、Superposition 等服务下面逐一展开各部分独立可读可依据自己的需求跳到对应小节。方式一用 Docker Compose 一键运行 Hyperswitch这是官方推荐的最简单方式不需要在宿主机安装 Rust、数据库脚本会自动拉取最新镜像并编排好所有服务。1. 安装容器编排工具先安装 Docker Compose 或 Podman Compose二者任选其一即可。2. 克隆仓库并进入项目目录git clone --depth 1 --branch latest https://gitcode.com/GitHub_Trending/hy/hyperswitch cd hyperswitch使用--depth 1做浅克隆可以显著减少下载体积--branch latest拉取最新发布分支。如果打算参与开发或修改代码则可以去掉--depth做完整克隆下文“开发环境”一节有说明。3. 可选按需修改配置仓库自带的 config/docker_compose.toml 已经可以直接运行。该文件与容器编排文件 docker-compose.yml 是一一对应的涉及的关键配置有顶部application_source main用于标识当前运行的实例来源[master_database]、[replica_database]、[accounts_database]、[global_database]四个数据库连接块默认均为db_user / db_pass pg:5432 / hyperswitch_db其中pg是 docker-compose.yml 中 PostgreSQL 服务的名称容器网络内可直接解析[redis]中host redis-standalone、port 6379对应编排文件里的redis-standalone服务[secrets]中的admin_api_key test_admin这是后续用 Postman 创建商户时需要填入的管理员 API Key务必留意这个值[server]中port 8080、host 0.0.0.0与request_body_limitPost 请求体默认限 16 KB。如果你改了docker_compose.toml中的数据库口令、端口等必须同步修改 docker-compose.yml 里对应环境变量否则服务间将无法互通。4. 执行一键安装脚本scripts/setup.sh运行后脚本会以交互方式让你选择安装模式。结合 scripts/setup.sh 源码可以梳理出脚本的完整执行流程环境检测自动检测宿主机是 Docker 还是 Podman并验证compose插件与curl是否可用端口预检检查8080 / 8081 / 9000 / 9050 / 5432 / 6379 / 9060等端口是否被占用若有冲突会给出警告对应脚本check_prerequisites函数生成.oneclick-setup.env写入ONE_CLICK_SETUPtrue供编排文件中的 prestart 钩子等逻辑读取交互选择 Setup 模式随后按所选 profile 启动容器健康检查依次请求http://localhost:8080/health与http://localhost:8080/health/ready全部通过后打印访问信息与默认账号。脚本支持三种 Setup 模式对应select_profile与start_services函数模式适用场景启动的服务1) Standard Setup推荐快速试用大多数体验场景App Server应用服务器、Control Center控制台、PostgreSQL、Redis2) Full Stack Setup完整的端到端支付测试Standard 的全部内容外加 Scheduler调度器、Monitoring监控、OLAP分析等 profile3) Standalone App Server仅做 API 集成测试App Server、PostgreSQL、Redis、Superposition5. 验证服务并访问脚本完成后会打印各服务的访问地址Control Center运营后台http://localhost:9000App Server支付 APIhttp://localhost:8080Superposition配置管理服务http://localhost:8081MonitoringGrafana仅 Full 模式http://localhost:3000默认登录账号邮箱demohyperswitch.com密码Hyperswitch123停止服务时依据所选模式执行对应命令即可例如 Standard/Standalone 模式为docker compose downFull 模式需带上各 profiledocker compose --profile scheduler --profile monitoring --profile olap --profile full_setup down6. 运行附加服务docker-compose.yml 中除了默认启动的核心依赖还通过 Compose profile 管理了一批可选服务可按需单独拉起Schedulerproducer/consumer位于schedulerprofile负责轮询并异步处理 webhook、重试等任务Drainer位于full_kvprofile负责把 Redis KV 中的流式数据批量回写数据库Monitoring 全家桶位于monitoringprofile包括 Grafana、Prometheus、Loki、Promtail、Tempo 与 OTel Collector配置样例如 config/prometheus.yaml、config/grafana-datasource.yaml、config/tempo.yamlClustered Redis位于clustered_redisprofile用于以集群模式运行 Redis默认 3 个节点可通过REDIS_CLUSTER_COUNT调整hyperswitch-web-sdk前端 SDK 的本地开发服务端口9050hyperswitch-control-center控制台服务端口9000其配置来自 config/dashboard.toml。需要说明的是基础体验并不需要这些附加服务它们主要面向需要验证调度、监控或 KV 场景的高级用户。方式二用 Docker Compose 搭建可改码的开发环境如果你的目标是“改 Hyperswitch 源码并运行”官方建议使用 docker-compose-development.yml 提供的开发编排。1. 安装 Docker Compose 并克隆仓库git clone https://gitcode.com/GitHub_Trending/hy/hyperswitch cd hyperswitch2.可选修改配置同样通过 config/docker_compose.toml 配置应用改配置时记得同步 docker-compose.yml开发编排中也会复用此配置。3. 启动开发环境docker compose --file docker-compose-development.yml up -d与“一键运行”模式最大的区别在于这里没有预先构建好的镜像而是将当前仓库源码挂载进容器后执行cargo run --bin router -- -f ./config/docker_compose.toml直接编译并启动支付路由router即 Hyperswitch 的核心组件。因此首次编译时间较长视机器配置可能约 30 分钟。该编排同时会拉起 PostgreSQL、Redis、migration_runner自动执行just migrate跑数据库迁移、superposition 及其初始化容器superposition-init。4. 验证服务是否就绪curl --head --request GET http://localhost:8080/health如果返回200 OK说明 App Server 已正常启动可以进入文末的「体验支付 API」环节。5.可选追加调度器与监控开发环境中如需 Scheduler 或监控可参考「运行附加服务」一节用--profile scheduler --profile monitoring等方式叠加启动。方式三使用 Nix 开发环境Nix 开发环境可为 MacOS、Linux 与 WSL2 用户统一安装所有项目依赖保证可复现的开发体验相关定义位于仓库根目录的 flake.nix。1. 安装 Nix官方建议使用 DetSys 的 nix-installer 安装它会自动启用 flakes 支持。若你还希望用 Nix 管理 dotfiles 与本机软件包可以进一步配置 nixos-unified-template。2. 通过 Nix 启动外部服务在 hyperswitch 目录执行nix run .#ext-services该命令会通过process-compose一键启动本地开发所需的全部外部服务PostgreSQL自动创建应用所需的数据库与用户RedisSuperposition配置管理服务使用自包含的 demo 镜像。3. 进入 Nix 开发 ShellHyperswitch 提供三个面向不同活动的 Nix shellShell命令用途默认 Shellhyperswitch-shellnix develop最小环境用于编译并运行服务端可在其中执行 DB 迁移、编译与运行各组件使用项目定义的 Rust MSRV开发 Shellhyperswitch-dev-shellnix develop .#dev在默认 Shell 基础上增加活跃开发所需工具可在其中运行 clippy 检查、校验 OpenAPI 规范使用提交时最新的 RustQA Shellhyperswitch-qa-shellnix develop .#qa在默认 Shell 基础上增加执行 Cypress 测试所需的工具同样使用项目定义的 MSRV提示仓库中的 CI/质量检查命令大多可通过 justfile 的 recipe 触发例如just check、just clippy对应scripts/ci-checks.sh中执行的just ci_hack等流程在 dev shell 内使用非常顺手。方式四从源码自建 Rust 环境并手动运行如果你不使用 Nix也完全可以在宿主机上手动安装依赖、编译并运行。官方文档按 Ubuntu / WindowsWSL2/ Windows原生/ MacOS 分别给出了步骤。由于每一步命令都涉及系统级依赖下面分平台展开。Ubuntu 系系统通过rustup安装 stable Rust 工具链选择defaultprofilecurl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh可选验证安装是否成功rustc --version从网络下载并执行 shell 脚本请自行注意安全官方仅在 Ubuntu 软件源没有rustup包的前提下推荐该方式。安装并启动 PostgreSQLsudo apt update sudo apt install postgresql postgresql-contrib libpq-dev systemctl start postgresql.service安装并启动 Redissudo apt install redis-server systemctl start redis.service安装diesel_cli数据库迁移工具仅启用 postgres 特性cargo install diesel_cli --no-default-features --features postgres安装编译 Rust 项目所需的pkg-config与 OpenSSLsudo apt install pkg-config libssl-devWindowsUbuntu on WSL2安装 Ubuntu 子系统并进入 WSL 环境wsl --install -d Ubuntu注意WSL 内存不足时编译部分 crate 可能触发SIGKILL错误。必要时可通过 Windows 用户目录下的.wslconfig将内存放宽至约 24GB或在 WSL 内创建 swap 文件具体见 WSL 配置文档。在 WSL 内安装 stable Rust 工具链curl --proto https --tlsv1.2 -sSf https://sh.rustup.rs | sh安装并启动 PostgreSQLsudo apt update sudo apt install postgresql postgresql-contrib libpq-dev sudo service postgresql start安装并启动 Redissudo apt install redis-server sudo service redis-server start安装 Rust 编译所需的构建工具链sudo apt install build-essential安装diesel_clicargo install diesel_cli --no-default-features --features postgres安装pkg-config与 OpenSSLsudo apt install pkg-config libssl-devWindows原生本节以winget为例也可换用你习惯的包管理器按官方安装指引安装 PostgreSQL按官方安装指引安装 Redis安装 Rustwinget install -e --id Rustlang.Rust.GNU安装diesel_clicargo install diesel_cli --no-default-features --features postgres安装 OpenSSLwinget install opensslMacOS本节以 Homebrew 为例安装 stable Rust 工具链brew install rustup rustup default stable安装并启动 PostgreSQL 14brew install postgresql14 brew services start postgresql14如果系统中不存在postgres数据库用户需要手动创建createuser -s postgres安装并启动 Redisbrew install redis brew services start redis安装diesel_cli。若链接失败并出现类似cannot find -lpq的错误说明缺少libpq可先安装再重装brew install libpq export PQ_LIB_DIR$(brew --prefix libpq)/lib cargo install diesel_cli --no-default-features --features postgres可以将PQ_LIB_DIR持久化到 shell 启动文件中echo PQ_LIB_DIR$(brew --prefix libpq)/lib ~/.zshrc安装命令运行器just官方用它简化迁移等命令的执行cargo install just以上各平台依赖装完后都进入下一节“设置数据库”。初始化数据库与执行迁移1. 创建数据库与用户先用环境变量指定库名与账号密码export DB_USERdb_user export DB_PASSdb_pass export DB_NAMEhyperswitch_dbUbuntu 系同样适用于 Ubuntu on WSL2执行sudo -u postgres psql -e -c \ CREATE USER $DB_USER WITH PASSWORD $DB_PASS SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN; sudo -u postgres psql -e -c \ CREATE DATABASE $DB_NAME;MacOS 执行psql -e -U postgres -c \ CREATE USER $DB_USER WITH PASSWORD $DB_PASS SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN; psql -e -U postgres -c \ CREATE DATABASE $DB_NAME2. 克隆仓库git clone https://gitcode.com/GitHub_Trending/hy/hyperswitch cd hyperswitch3. 执行数据库迁移先导出DATABASE_URL环境变量export DATABASE_URLpostgres://$DB_USER:$DB_PASSlocalhost:5432/$DB_NAME然后运行迁移两种方式等价使用just推荐装好just后即可用just migrate直接使用 diesel CLIdiesel migration run从 justfile 中的migraterecipe 可以看到它本质上是对 diesel CLI 的封装把DATABASE_URL或回退到postgresql://db_user:db_passlocalhost:5432/hyperswitch_db和迁移目录 migrationsv1 迁移默认目录传给diesel migration run。仓库中已有数以百计的历史迁移脚本覆盖从最早的建表到近期新增列的全部 schema 演进因此首次迁移会执行较长时间属正常现象。如果你需要运行 v2 兼容或纯 v2 的迁移可分别使用just migrate_v2_compatible与just migrate_v2。配置应用所有应用配置文件都放在仓库的 config 目录下。配置文件随运行环境不同而切换Development开发config/development.tomlSandbox沙箱对应config/sandbox.tomlProduction生产对应config/production.tomlDocker Composeconfig/docker_compose.tomlconfig/config.example.toml 是全部可用配置项的权威参考config/development.toml 则给出本地开发推荐的默认值。若需要修改全局日志级别、数据库连接池等均可基于前者覆盖。对本机源码运行而言需要特别关注 config/development.toml 中如下几处[master_database]/[replica_database]/[accounts_database]/[global_database]默认均为localhost:5432上的hyperswitch_db用户名db_user、密码db_pass如果前面建库时改了凭据必须同步修改此文件[redis]默认指向127.0.0.1:6379[secrets]admin_api_key test_admin是管理端 API Key后续调用创建商户接口时要填入master_enc_key与jwt_secret在当前配置中为本地示例值[locker]mock_locker true、locker_enabled true本地开发使用模拟 Locker 即可完成卡信息 Token 化流程无需部署真实 Locker 服务。运行应用1. 启动并初始化 SuperpositionSuperposition 是 Hyperswitch 的配置管理服务负责按维度下发动态配置。官方提供了 4 个just命令just superposition-up在 Docker 中启动 Superpositionjust superposition-down停止 Superpositionjust superposition-seed向 Superposition 写入默认配置如果你倾向在本地而非 Docker运行 Superposition可参考 Superposition 官方的 setup 指引。执行just superposition-up just superposition-seedsuperposition-seed会读取 config/superposition_seed.toml 并调用 scripts/seed_superposition.sh对应的 Docker 化自动初始化逻辑见 docker-compose-development.yml 中的superposition-init服务。它会默认写入以下内容维度dimensionsorganization_id、merchant_id、profile_id、connector默认配置configsrequires_cvv是否强制要求 CVV、implicit_customer_update、payout_tracker_mapping等。2. 编译并运行应用使用 cargo开发模式适合直接改代码cargo run也可以显式指定配置cargo run --bin router -- -f ./config/development.toml如果你在使用 Nix可改为nix run首次编译会拉取并编译整个 workspace包含 crates/router、crates/analytics 等大量 crate耗时取决于机器性能。3. 健康检查curl --head --request GET http://localhost:8080/health返回200 OK即表示服务已就绪。从源码看/health路由实现于 crates/router/src/routes/health.rs会直接返回200 OK与文本health is good同时累加健康检查指标。setup 脚本在启动完成后还会请求更深度的/health/ready接口同文件中的deep_health_check该接口会逐一校验Database、Redis、LockerVault、Analytics、OpenSearch、Outgoing Request、Unified Connector Service等下游组件的连通性并返回 JSON 详情是排查“表面 200 但服务不可用”问题的最直接手段。体验 Hyperswitch 支付 API服务跑起来之后官方推荐使用 Postman 集合完成首笔支付。仓库中同样提供了完整的 OpenAPI 规格如 api-reference/context7.json 与 api-reference 目录下的 v1/v2 接口文档可配合 Postman 集合对照学习。前置配置 Postman 变量注册 / 登录 Postman打开 Hyperswitch 的 Postman collection切到Variables标签页把baseUrl变量的 current value 改为本地服务地址默认http://localhost:8080继续在 Variables 页找到admin_api_key变量填入应用配置里的管理端 API Key使用 Docker Compose 运行时在 config/docker_compose.toml 中搜索admin_api_key默认test_admin源码本地运行时在 config/development.toml 中搜索admin_api_key。1. 创建商户账户Merchant Account打开 collection 中 “Quick Start” 文件夹下的Merchant Account - Create请求在 Body 中按需调整参数若不想使用默认的支付连接器可修改routing_algorithm字段中的data内容例如换成你想联调的连接器点击 Send 创建商户账户若未 fork 到自己的工作区Postman 会提示先 fork collection。成功后会返回与请求体大体一致、并附带若干服务端生成字段的响应。保存响应中的 merchant ID 与 publishable key后续接口会用到。2. 创建 API Key打开API Key - Create请求按需修改 Body 后点击 Send。响应中会包含明文 API Key请妥善保管服务端只保存其哈希明文仅此一次返回参见仓库中api_keys.hash_key相关设计。3. 配置支付连接器账户Payment Connector Account到目标支付连接器如 Stripe、Adyen 等的商户后台注册安全保存连接器 API Key 及其他必要密钥打开Payment Connector - Create请求重点修改connector_name与connector_account_details字段——不同连接器需要填的细节字段可参考仓库中的连接器文档与 config/docker_compose.toml 中[connectors]与[connectors.supported]对可用连接器的声明其中已内置 stripe、adyen、checkout、paypal、braintree 等大量连接器的测试环境 base_url 与支持的支付方式清单回到 Postman 的 Variables 页把connector_api_key变量设为你的连接器 API Key点击 Send 创建连接器账户。如需接入更多支付渠道重复以上步骤即可。4. 创建一笔支付Payment创建支付前请确保已完成「创建商户账户」与「配置至少一个支付连接器账户」。打开Payments - Create请求按需修改 Body 后点击 Send若一切正常且连接器凭据正确响应中status字段应为succeeded若返回的status是requires_confirmation则把请求体中的confirm置为true后重新发送打开Payments - Retrieve请求不做任何修改直接 Send即可按payment_id查询刚才创建的支付对象。5. 发起一笔退款Refund打开 Quick Start 文件夹下的Refunds - Create请求按需调整退款金额后点击 Send会针对该客户最近的一笔支付创建退款观察响应的status字段确认退款未失败打开Refunds - Retrieve请求切到 Params 页把上一步响应中的refund_id填入 Path Variables 的id即可查询退款对象详情。至此你已经完整走通了“商户 → API Key → 连接器 → 支付 → 查询 → 退款”的本地闭环。剩余更多接口订阅、争议、路由策略、收款等都可以在同一 Postman 集合的其他文件夹中继续探索希望深入理解系统整体架构的读者可继续阅读仓库中的 docs/architecture.md。常见问题与排障速查健康检查 200 但支付报错优先查看/health/ready返回 JSON 中各项组件状态确认 DB/Redis/Superposition 是否真正可达Superposition 未 seed 时会导致requires_cvv等动态配置缺失。首次编译极慢 / WSL 下 SIGKILL源码编译属正常现象约 30 分钟量级WSL 用户请按前文增大内存或增加 swap。改了 docker_compose.toml 后连接失败数据库口令、端口等改动必须同步到 docker-compose.yml 的环境变量中二者是配套使用的。改端口后 Postman 连不上确认baseUrl变量与[server]的port一致。以上所有操作路径都可在仓库当前版本中逐一复现如需构建自有镜像或在云上部署可进一步参考 docs/building_docker_images.md。【免费下载链接】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），仅供参考