Hyperswitch Decision Engine 配置指南Toml 配置项全解与生产环境调优实践【免费下载链接】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本文聚焦 Hyperswitch 仓库中 Decision Engine智能路由决策引擎的部署配置体系完整讲解官方配置指南configuration.md覆盖的 Server、日志、限流、多租户、鉴权、Analytics 与 Secrets 管理等全部配置段并结合 本地部署文档 中的 Compose Profile 矩阵说明每个配置项在实际运行时的作用与取值建议帮助你在本地、Docker 与 K8s 环境下正确、安全地配置并调优 Decision Engine。需要先说明一个适用前提Hyperswitch 仓库中的 api-reference/decision-engine-api-reference/ 目录存放的是 Decision Engine 组件的完整 API 参考文档含 OpenAPI 规范 decision_engine_openapi-specs.json而 Decision Engine 本身是一个独立运行的决策引擎服务据 安装文档其源码仓库为 juspay/decision-engine。因此下文中提到的config/development.toml、config/docker-configuration.toml、helm-charts/config/development.toml等路径均指Decision Engine 项目内的配置文件而非本仓库根目录下的同名 router 配置。一、主配置文件按运行环境选对文件Decision Engine 提供三份预置了全部必需配置段的配置文件分别对应三种运行方式配置文件适用场景config/development.toml从源码运行host/source runsconfig/docker-configuration.tomlDocker / Docker Compose 运行helm-charts/config/development.tomlKubernetes Helm Chart 模板配置官方配置指南给出的关键建议是直接编辑与你运行时匹配的那份文件而不是从config.example.toml复制——示例配置是不完整的incomplete缺段会导致启动失败或行为异常。结合 本地部署文档Docker 方式启动时必须显式传入 Compose Profile没有无 Profile 的默认启动常用组合包括# 最小 API 栈PostgreSQL docker compose --profile postgres-ghcr up -d # API Dashboard 文档站 docker compose --profile dashboard-postgres-ghcr up -d # 附加监控栈Prometheus Grafana docker compose --profile monitoring up -d也就是说选择哪份配置文件与选择哪个 Compose Profile 是配套关系源码运行读development.tomlCompose 运行读docker-configuration.toml且 Compose 文件中已通过服务名service name预接线了各依赖。二、基础服务配置段[server] 监听地址[server] host 0.0.0.0 port 8080host是绑定地址Docker/部署环境用0.0.0.0对外可达仅本机调试用127.0.0.1。安装文档的 Quick Start 以curl http://localhost:8080/health验证服务存活预期返回{message: Health is good}即默认端口为 8080。[log.console] 日志[log.console] enabled true level DEBUG log_format defaultlog_format取default人类可读或json结构化。生产环境建议使用json格式便于日志采集管道如 Loki/Vector 类组件按字段解析。[metrics] Prometheus 指标[metrics] host 0.0.0.0 port 9094Prometheus 指标暴露在host:port/metrics路径上。该配置与 本地部署文档 中的monitoringProfile 直接对应Prometheus 抓取 9094 端口的/metricsGrafana 面板运行在 3000 端口。若你启用了--profile monitoring请务必保证此段配置与 Prometheus scrape 目标一致否则监控栈会空转。[limit] 删除类 API 限流[limit] request_count 1 duration 60该段专门控制删除类deleteAPI 的速率request_count个请求 /duration秒。默认值 1 请求/60 秒是非常保守的保护性设置意在防止批量误删如批量删除商户、路由规则、成本数据等破坏性操作属于删除接口的熔断阀而非全局 QPS 限制。[cache_config] Redis 缓存键配置[cache_config] service_config_redis_prefix DE_service_config_ service_config_ttl 300 # Redis TTL for service config entries, in seconds控制服务配置条目写入 Redis 的键前缀与存活时间TTL单位秒。前缀避免与其他组件的缓存键冲突TTL 决定了配置变更在缓存层的最大传播延迟默认 300 秒内生效。[redis] 连接[redis] host 127.0.0.1 port 6379Redis 是 Decision Engine 的必需依赖——它用于缓存路由配置routing config与服务配置service config不是可选优化项。Docker 运行时应将host改为 Compose 中的服务名而非 127.0.0.1因为容器网络中回环地址无法跨容器访问。三、数据库配置MySQL 与 PostgreSQL 双后端Decision Engine 支持 MySQL 和 PostgreSQL 两种可互换的数据库后端二者使用互相独立的配置段MySQL 后端[database] username db_user password db_pass host localhost port 3306 dbname decision_engine_dbPostgreSQL 后端[pg_database] pg_username db_user pg_password db_pass pg_host localhost pg_port 5432 pg_dbname decision_engine_db注意两个段的键名风格不同MySQL 段使用无缀键username/hostPostgreSQL 段使用pg_前缀键pg_username/pg_host混写会导致解析不到连接参数。Docker Compose 运行时config/docker-configuration.toml已经通过服务名预接线了两者pre-wired via service names。从 本地部署文档 的 Profile 矩阵可以看到核心 Profilepostgres-ghcr、mysql-ghcr等都已包含对应数据库的迁移migrations任务因此换库时 Profile 与配置文件要同步切换避免配置文件指向 MySQL、Profile 拉起 PostgreSQL 迁移的不一致。四、多租户 Schema 与 x-tenant-id 头[tenant_secrets] public { schema public }tenant_secrets段把租户标识符映射到数据库 schema实现租户级数据隔离。随仓库分发的配置文件config/development.toml、config/docker-configuration.toml只定义了public一个租户——如果要支持额外租户需要自行在此段增加条目。配置指南特别强调了一个容易踩坑的运行时行为部分路由不是从已认证商户推导租户而是直接解析请求头x-tenant-id缺失时直接拒绝请求并返回TE_03错误码。以下路由必须携带x-tenant-id: publicGET /health/diagnostics所有GET /analytics/*路由POST /gateway-score/reset这一行为在 API 参考文档 的环境设置章节有对应说明。配置多租户后调用上述接口时务必在 curl 示例中加入-H x-tenant-id: public否则会被TE_03拦截。五、鉴权相关配置段Decision Engine 的鉴权体系由三个配置段/标志位共同决定理解它们之间的组合语义比逐个记住参数更重要[user_auth] JWT 配置[user_auth] jwt_secret change_me_in_production_use_32chars!! jwt_expiry_seconds 86400 email_verification_enabled falsejwt_secret签名密钥生产环境必须替换为强随机值官方建议 32 字符以上jwt_expiry_secondsJWT 有效期默认 86400 秒 1 天email_verification_enabled仅在接入了邮件服务商后才可置true。[admin_secret] 管理员引导密钥[admin_secret] secret test_admin用于认证POST /merchant-account/create端点管理员引导/bootstrap 入口见 createMerchant API 文档。生产环境必须更换此默认值。api_key_auth_enabled 顶层标志——最易被误解的一项api_key_auth_enabled true这是一个顶层配置项不属于任何段。官方指南对它做了强烈的风险提示语义是非对称的true受保护路由在 JWT Bearer Token 之外额外接受x-api-key请求头false鉴权中间件会放行所有请求不做任何认证——即等价于对所有受保护路由关闭鉴权。因此该标志的真实含义是是否启用 API Key 通道而不是关闭 API Key 就只走 JWT。任何需要强制鉴权的环境包括内网测试环境都不应将其设为false。六、Analytics 链路Kafka ClickHouse分析功能的数据流为决策结果 → Kafka 发布 → 消费写入 ClickHouse供分析与审计看板使用。两段配置都必须显式enabled true——即使连接详情配置齐全缺少enabled true时 Analytics 整体仍是禁用状态[analytics.kafka] enabled true brokers localhost:9092 api_topic api domain_topic domain [analytics.clickhouse] enabled true url http://localhost:8123 user decision_engine password decision_engineapi_topic与domain_topic是 Kafka 上两个主题分别承载 API 层与领域层的分析事件。Docker 运行时这些连接在 Compose 中已预配置并启用对应analytics-clickhouse等 Profile。若你本地调用了GET /analytics/*却拿不到数据排查顺序应为两个enabled开关 → Kafka brokers 可达性 → ClickHouse URL/凭据 → 请求头x-tenant-id。七、TLS 与出站 API 客户端[tls] 应用层 TLS[tls] certificate cert.pem private_key key.pemPEM 格式证书与私钥的路径。仅在你在应用层而非反向代理层终结 TLS 时才需要配置若前置 Nginx/Envoy 已处理 TLS此段可留空。[api_client] 出站 HTTP 客户端[api_client] client_idle_timeout 90 pool_max_idle_per_host 10 identity 控制 Decision Engine 发起上游调用upstream calls所用的出站 HTTP 客户端空闲超时 90 秒、每主机最大空闲连接 10。identity默认为空字符串如需与上游做 mTLS双向 TLS将其设为身份证书 PEM 路径。八、Secrets Management从明文到 KMS/Vault默认情况下配置中的密钥以明文存储在配置文件中。生产部署官方支持两种后端分别由 Cargo feature 开关控制编译能力AWS KMS需kms-awsfeature包含在releasefeature 集合中[secrets_management] secrets_manager aws_kms [secrets_management.aws_kms] key_id your-kms-key-id region us-east-1HashiCorp Vault需kms-hashicorp-vaultfeature[secrets_management] secrets_manager hashi_corp_vault [secrets_management.hashi_corp_vault] url http://127.0.0.1:8200 token hvs.your_token配置了 Secrets Manager 后database.password、user_auth.jwt_secret等敏感字段将从 Vault 解析而非读取配置文件明文——配置文件中只保留指向 Vault 的参数。选型建议AWS 环境优先 KMS随releasefeature 开箱即用自建/混合云环境用 Vault。九、环境变量覆盖与延伸阅读配置指南指出选定值可以在运行时通过环境变量覆盖这在 Helm 部署中通过extraEnvVars注入尤其有用避免把敏感值固化进 ConfigMap。完整的环境变量到配置项的映射以 Decision Engine 项目中的src/config.rs为准该源码文件位于 decision-engine 仓库不在本 Hyperswitch 仓库内。配置完成后的验证与下一步健康检查curl http://localhost:8080/health预期{message: Health is good}诊断端点注意携带租户头curl -H x-tenant-id: public http://localhost:8080/health/diagnostics完整部署矩阵Compose Profile、源码构建、Helm见 Local Setup 指南数据库专项的 make 目标与验证步骤见 PostgreSQL 设置 与 MySQL 设置可复制的 curl 示例见 API 指南 与 API Reference 索引。生产配置自检清单jwt_secret已随机化admin_secret已更换api_key_auth_enabled true未被误置为false日志为json格式敏感连接串走 KMS/Vault 而非明文[limit]段保留删除接口限流多租户路由调用携带x-tenant-id。逐项核对后配置层面的安全基线即已达到官方指南的要求。【免费下载链接】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），仅供参考