Hyperswitch 生态 Decision Engine 的 MySQL 部署指南：Docker Compose、Make 目标与健康验证全解析

Hyperswitch 生态 Decision Engine 的 MySQL 部署指南Docker Compose、Make 目标与健康验证全解析【免费下载链接】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本文以 Decision EngineJuspay 开源的智能路由/决策引擎随 Hyperswitch 项目一并维护与发布的 MySQL 部署文档为主线完整讲解用 Docker Compose 把 Decision Engine 拉起在 MySQL 之上的两条轨道GHCR 预构建镜像轨与本地源码构建轨、对应的make封装目标、/health健康验证方式并结合同仓库的 完整本地部署指南 与 配置参考 深入 MySQL 数据源、Redis 缓存与 Kafka/ClickHouse 分析栈的配置细节。读完本文你可以独立在本机或私有环境完成 Decision Engine MySQL 的端到端部署并能看懂每个 profile 背后启动了哪些服务。一、MySQL 作为 Decision Engine 的受支持数据库后端Decision Engine 支持 PostgreSQL 与 MySQL 两种可互换的数据库后端。选型文档Installation Guide的表述是两者地位对等选定其一后按照对应数据库的专属指南操作即可MySQL 对应 MySQL Setup即本文主体PostgreSQL 对应 PostgreSQL Setup。一个关键差异点来自 Local Setup Guide 的前置条件说明PostgreSQL 源码运行需要just工具用于just migrate-pg执行迁移MySQL 源码运行可以直接使用diesel migration run不需要just。这解释了为什么本文的验证与构建路径更短MySQL 轨把迁移步骤直接放进了 Compose profile 里见下节。二、运行环境与版本前提按 Local Setup Guide 的 Prerequisites 章节MySQL 部署涉及以下工具链组件版本要求说明Docker Engine20运行容器化服务Docker Composev2必须是docker compose子命令而非旧版docker-compose二进制Git2拉取仓库Rust1.85仅本地源码构建轨需要另外注意文档中明确的两点默认约定本仓库decision-engine 分支使用的默认镜像 tag 为DECISION_ENGINE_TAGv1.4配套GROOVY_RUNNER_TAGv1.4。GHCR 轨的启动命令需要显式export这个变量。所有docker-compose.yaml中的服务都被 profile 门控没有默认/无 profile 的启动方式——必须至少传一个 profile。这也是为什么 GHCR 轨命令中显式设置了COMPOSE_PROFILES清空环境继承的 profile 变量再追加--profile。三、MySQL 相关 Compose Profile启动了哪些服务Local Setup Guide 的 Docker Compose Profiles 小节给出了完整 profile 矩阵。与 MySQL 相关的四个核心 profile 及其包含内容如下原表逐项继承Profile数据库包含的服务mysql-ghcrMySQLAPI MySQL Redis Kafka ClickHouse MySQL 迁移 routing-configmysql-localMySQLAPI MySQL Redis Kafka ClickHouse MySQL 迁移 routing-configdashboard-mysql-ghcrMySQLMySQL 核心栈 Dashboard Mintlify 文档站dashboard-mysql-localMySQLMySQL 核心栈 Dashboard Mintlify 文档站两个维度的区分数据源MySQL本文主题。镜像来源-ghcr轨从 GHCR 拉取预构建镜像无需本地 Rust 工具链-local轨从当前源码树构建镜像或二进制适合在改动源码后验证。此外还可以按需叠加可选 profile同表继承Profile额外内容monitoringPrometheus Grafanagroovy-ghcrGroovy 规则执行器预构建镜像groovy-local从本地源码构建的 Groovy 执行器analytics-clickhouse仅做 Kafka topic 初始化 ClickHouse 分析栈引导从服务构成可以推断mysql-ghcr/mysql-local相比 PostgreSQL 轨多挂了routing-config配置服务且迁移由 profile 内置的 migrator 容器执行排查时对应docker compose logs db-migrator。Kafka ClickHouse 分析栈属于两个数据库轨共有的基础设施决策结果发布到 Kafka、消费落盘到 ClickHouse分析数据存于命名卷clickhouse-data常规重启不会丢失分析历史。四、GHCR 预构建镜像轨启动 MySQL 栈以下命令完整继承自 MySQL Setup 原文是最小可用的 API 启动方式export DECISION_ENGINE_TAGv1.4 COMPOSE_PROFILES docker compose --profile mysql-ghcr up -d需要同时拉起 Dashboard 与文档站Mintlify docs时COMPOSE_PROFILES docker compose --profile dashboard-mysql-ghcr up -d要点说明export DECISION_ENGINE_TAGv1.4指定要拉取的 GHCR 镜像 tag与仓库默认 tag 保持一致COMPOSE_PROFILES显式清空环境中可能继承的 profile确保最终激活的 profile 只来自--profile参数命令需要在 decision-engine 仓库根目录执行compose 文件为docker-compose.yamlInstallation Guide 明确要求从 repo root 运行。首次运行会拉取 API、MySQL、Redis、Kafka、ClickHouse 等镜像并占用数 GB 磁盘。五、本地源码构建轨启动 MySQL 栈在源码有改动、或希望镜像完全由当前工作树构建时使用该轨道命令同样继承自 MySQL SetupCOMPOSE_PROFILES docker compose --profile mysql-local up -d --build带 Dashboard 文档站的版本COMPOSE_PROFILES docker compose --profile dashboard-mysql-local up -d --build与 GHCR 轨相比唯一区别是多了--build即由 Compose 触发基于本地Dockerfile的镜像构建。六、Make 封装目标除了裸 Compose 命令仓库提供了一层make封装MySQL Setup 原文make init-mysql-ghcr make init-mysql-localinit-mysql-ghcr等价于 GHCR 轨的一次性初始化拉起并准备 MySQL 核心栈init-mysql-local等价于本地构建轨的一次性初始化。Local Setup Guide 的 Make Targets 小节列出了同一层的完整常用封装供对照make init-pg-ghcr make init-pg-local make init-mysql-ghcr make init-mysql-local make run-pg-ghcr make run-mysql-local make reset-analytics-clickhouse make stop其中与 MySQL 运维直接相关的run-mysql-local本地构建轨运行、stop停止栈、reset-analytics-clickhouse删除 ClickHouse 分析卷并重建 Kafka ClickHouse 分析栈用于需要干净的分析数据的场景。七、验证部署/health 端点栈起来后用健康检查确认 API 进程与 MySQL/Redis 依赖均已就绪继承自 MySQL Setup 的 Verify 小节curl http://localhost:8080/health预期响应{message:Health is good}端口 8080 来自配置文件中[server] host 0.0.0.0 / port 8080的默认值见 Configuration Guide。若 Dashboard profile 也在运行还可以访问Local Setup Guide 的 Verification 小节Dashboardhttp://localhost:8081/dashboard/文档站http://localhost:8081/introductionAPI 示例http://localhost:8081/api-refs/api-ref若叠加了monitoringprofile另有 Prometheushttp://localhost:9090与 Grafanahttp://localhost:3000API 自身的 Prometheus 指标端点位于9094/metrics[metrics]段默认值。八、MySQL 部署涉及的核心配置项Compose profile 里 API 容器使用的数据库连接串已在config/docker-configuration.toml中以服务名预置理解下面的配置段有助于排障与迁移到裸机部署。以下各段完整继承自 Configuration Guide。8.1 MySQL 数据源[database] username db_user password db_pass host localhost port 3306 dbname decision_engine_db注意与 PostgreSQL 的配置段是分开的PG 用[pg_database]pg_*前缀字段。文档特别指出Docker Compose 运行时config/docker-configuration.toml里这些 host 已经写成 Compose 服务名不需要再手工改。8.2 其他强相关依赖Redis必需用于缓存 routing config 与 service configDocker 场景下 host 填 Compose 服务名[redis] host 127.0.0.1 port 6379Kafka ClickHouse 分析栈两者都必须enabled true否则即使连接信息配好了分析功能也是关闭的[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_engine多租户 Schema 映射与x-tenant-id头[tenant_secrets] public { schema public }部分路由GET /health/diagnostics、所有GET /analytics/*、POST /gateway-score/reset从x-tenant-id请求头解析租户缺失会直接拒绝错误码TE_03。本地验证这些路由时记得带上x-tenant-id: public详见 API Guide。8.3 三个主配置文件的选择Configuration Guide 明确了配置文件与运行方式的对应关系config/development.toml宿主机/源码运行config/docker-configuration.tomlDocker 与 Compose 运行本文的mysql-*profile 走的就是它helm-charts/config/development.tomlKubernetes chart 模板配置。文档的实操建议是直接编辑与运行方式匹配的那一份不要从不完整的config.example.toml拷贝。九、绕过 Compose 的两种运行方式如果不想用 Compose 编排Local Setup Guide 还给出两条 MySQL 路径。9.1 源码构建MySQLcargo build --release --features release RUSTFLAGS-Awarnings cargo run --features release这里 MySQL 是默认特性集的一部分无需像 PostgreSQL 轨那样传--no-default-features --features postgres。迁移可在数据库就绪后直接执行diesel migration run这是 MySQL 轨相对 PG 轨省掉just依赖的原因。9.2 直接构建 Docker 镜像docker build --platformlinux/amd64 -t decision-engine-mysql:local -f Dockerfile .示例容器运行以 PG 镜像为例MySQL 镜像同理把镜像名换成decision-engine-mysql:local、挂载对应的 toml 即可docker run --platformlinux/amd64 \ -v $(pwd)/config/docker-configuration.toml:/local/config/development.toml \ -p 8080:8080 \ decision-engine-pg:local该方式下容器把挂载进来的 toml 当作/local/config/development.toml读取因此数据库、Redis 地址必须能解析到宿主机网络。十、排障清单以下命令继承自 Local Setup Guide 的 Troubleshooting 小节针对 MySQL 轨做对应替换MySQL 迁移日志容器名为db-migrator以干净卷重建 profile数据/状态脏了最直接的恢复手段docker compose --profile mysql-ghcr down -v docker compose --profile mysql-ghcr up -d检查迁移作业日志docker compose logs db-migrator # MySQL 轨 docker compose logs db-migrator-postgres # PG 轨对照检查分析基础设施docker compose logs kafka-init docker compose logs clickhouse直接查看 ClickHouse 建好的分析表curl --user decision_engine:decision_engine \ http://localhost:8123/?querySHOW%20TABLES%20FROM%20default若需要彻底重建分析栈删卷重建make reset-analytics-clickhouse。文档同时提示了排障时应优先查看的文件清单docker-compose.yaml、config/docker-configuration.toml、src/config.rs、src/app.rs这些路径相对于 decision-engine 仓库根目录。十一、MySQL 轨与 PostgreSQL 轨速查对比维度MySQL 轨本文PostgreSQL 轨Compose profileAPImysql-ghcr/mysql-localpostgres-ghcr/postgres-localCompose profile含 Dashboarddashboard-mysql-ghcr/dashboard-mysql-localdashboard-postgres-ghcr/dashboard-postgres-localprofile 附加内容 routing-config 服务无此项make 目标make init-mysql-ghcr、make init-mysql-localmake init-pg-ghcr、make init-pg-local迁移日志容器db-migratordb-migrator-postgres源码运行构建cargo build --release --features releasecargo build --release --no-default-features --features middleware,kms-aws,postgres迁移工具直接diesel migration run需要just migrate-pg依赖just配置段[database]username/host/dbname…[pg_database]pg_ 前缀字段健康验证完全相同curl http://localhost:8080/health→{message:Health is good}同左十一补充、延伸阅读Installation Guide从零到运行实例的总入口Quick Start 与仓库准备Local Setup Guide本文多次引用的完整 profile 矩阵、源码构建、Helm 部署helm-charts/目录与排障PostgreSQL Setup同一套流程的 PostgreSQL 版本便于对照Configuration Guide[database]、[redis]、[analytics.*]等全部配置段详解与环境变量覆盖API Guide服务起来之后的可复制curl示例含x-tenant-id环境设置说明。最后提醒适用前提本文所有 profile 名称、make 目标与默认 tagv1.4均以当前仓库api-reference/decision-engine-api-reference/目录下的文档为准升级镜像 tag 或更换分支后建议先核对 Local Setup Guide 的 profile 表是否变更。【免费下载链接】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），仅供参考