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

本文以 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 文档站

两个维度的区分：

1. 数据源：MySQL（本文主题）。
2. 镜像来源：-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

若叠加了 monitoring profile，另有 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）：

1. 以干净卷重建 profile（数据/状态脏了最直接的恢复手段）：

   docker compose --profile mysql-ghcr down -v
   docker compose --profile mysql-ghcr up -d
   

2. 检查迁移作业日志：

   docker compose logs db-migrator            # MySQL 轨
   docker compose logs db-migrator-postgres   # PG 轨（对照）
   

3. 检查分析基础设施：

   docker compose logs kafka-init
   docker compose logs clickhouse
   

4. 直接查看 ClickHouse 建好的分析表：

   curl --user decision_engine:decision_engine \
     "http://localhost:8123/?query=SHOW%20TABLES%20FROM%20default"
   

5. 若需要彻底重建分析栈（删卷重建）：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 表是否变更。