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 Engine（Juspay 开源的智能路由/决策引擎，随 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 Engine	20+	运行容器化服务
Docker Compose	v2+	必须是`docker compose`子命令，而非旧版`docker-compose`二进制
Git	2+	拉取仓库
Rust	1.85+	仅本地源码构建轨需要

另外注意文档中明确的两点默认约定：

本仓库（decision-engine 分支）使用的默认镜像 tag 为DECISION_ENGINE_TAG=v1.4（配套GROOVY_RUNNER_TAG=v1.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-ghcr`	MySQL	API + MySQL + Redis + Kafka + ClickHouse + MySQL 迁移 + routing-config
`mysql-local`	MySQL	API + MySQL + Redis + Kafka + ClickHouse + MySQL 迁移 + routing-config
`dashboard-mysql-ghcr`	MySQL	MySQL 核心栈 + Dashboard + Mintlify 文档站
`dashboard-mysql-local`	MySQL	MySQL 核心栈 + Dashboard + Mintlify 文档站

两个维度的区分：

数据源：MySQL（本文主题）。
镜像来源：-ghcr轨从 GHCR 拉取预构建镜像，无需本地 Rust 工具链；-local轨从当前源码树构建镜像（或二进制），适合在改动源码后验证。

此外，还可以按需叠加可选 profile（同表继承）：

Profile	额外内容
`monitoring`	Prometheus + Grafana
`groovy-ghcr`	Groovy 规则执行器（预构建镜像）
`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_TAG=v1.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_TAG=v1.4：指定要拉取的 GHCR 镜像 tag，与仓库默认 tag 保持一致；
COMPOSE_PROFILES=：显式清空环境中可能继承的 profile，确保最终激活的 profile 只来自--profile参数；
命令需要在 decision-engine 仓库根目录执行（compose 文件为docker-compose.yaml，Installation Guide 明确要求从 repo root 运行）。首次运行会拉取 API、MySQL、Redis、Kafka、ClickHouse 等镜像并占用数 GB 磁盘。

五、本地源码构建轨启动 MySQL 栈

在源码有改动、或希望镜像完全由当前工作树构建时使用该轨道（命令同样继承自 MySQL Setup）：

COMPOSE_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-local

init-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 小节）：

Dashboard：http://localhost:8081/dashboard/
文档站：http://localhost:8081/introduction
API 示例：http://localhost:8081/api-refs/api-ref

若叠加了monitoringprofile，另有 Prometheus（http://localhost:9090）与 Grafana（http://localhost:3000）；API 自身的 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 config；Docker 场景下 host 填 Compose 服务名：
```
[redis] host = "127.0.0.1" port = 6379
```

Kafka + 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.toml：Docker 与 Compose 运行（本文的mysql-*profile 走的就是它）；
helm-charts/config/development.toml：Kubernetes chart 模板配置。

文档的实操建议是：直接编辑与运行方式匹配的那一份，不要从不完整的config.example.toml拷贝。

九、绕过 Compose 的两种运行方式

如果不想用 Compose 编排，Local Setup Guide 还给出两条 MySQL 路径。

9.1 源码构建（MySQL）

cargo 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 --platform=linux/amd64 -t decision-engine-mysql:local -f Dockerfile .

示例容器运行（以 PG 镜像为例，MySQL 镜像同理，把镜像名换成decision-engine-mysql:local、挂载对应的 toml 即可）：

docker run --platform=linux/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/?query=SHOW%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 profile（API）	`mysql-ghcr`/`mysql-local`	`postgres-ghcr`/`postgres-local`
Compose profile（含 Dashboard）	`dashboard-mysql-ghcr`/`dashboard-mysql-local`	`dashboard-postgres-ghcr`/`dashboard-postgres-local`
profile 附加内容	+ routing-config 服务	无此项
make 目标	`make init-mysql-ghcr`、`make init-mysql-local`	`make init-pg-ghcr`、`make init-pg-local`
迁移日志容器	`db-migrator`	`db-migrator-postgres`
源码运行构建	`cargo build --release --features release`	`cargo 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 目标与默认 tag（v1.4）均以当前仓库api-reference/decision-engine-api-reference/目录下的文档为准；升级镜像 tag 或更换分支后，建议先核对 Local Setup Guide 的 profile 表是否变更。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考