hyperswitch 中的 Decision Engine 安装指南：从一条 Docker Compose 命令到 Compose、源码构建与 Helm 的完整矩阵

本文基于 hyperswitch 仓库中 Decision Engine 官方文档集的 Installation 指南 展开，覆盖从“一条 docker compose up 命令跑通服务”到 Compose profile 矩阵、PostgreSQL/MySQL 双数据库选择、源码构建与 Helm 部署的完整本地安装路径。读完本文，你可以独立拉起 Decision Engine 的 API、Dashboard 与监控栈，掌握健康检查验证方式，并能按场景选择合适的安装轨道（预构建镜像或本地源码构建）。

Decision Engine 是什么：安装前的背景认知

在开始安装前，先明确你要装的是什么。按照文档集 Introduction 的定义，Decision Engine 是一个 Rust 服务，部署在你的编排器（orchestrator）与支付网关之间：每笔支付到来时，它从合格网关列表中挑选最优网关——可以按规则、按实时成功率、按成本，或三者混合——并记录结果，让后续决策持续改进。它以独立 HTTP 服务形式运行，不强制依赖任何特定编排器。

其核心能力包括（摘自 Introduction，安装后你会逐一用到）：

• 路由策略：POST /decide-gateway 支持规则路由（Euclid 规则引擎）、成功率路由（SR_BASED_ROUTING）、借记/卡组织路由（NTW_BASED_ROUTING）、网络+成功率混合路由（NTW_SR_HYBRID_ROUTING），以及在成功率路由之上叠加的多目标成本感知路由；
• 成本数据摄入：从结算报告和发票中学习每个连接器的真实费率；
• A/B 测试：在控制组与变体路由策略之间按可配置比例分流，内置双样本 z 检验；
• Autopilot 自动校准：后台任务自动调整成功率评分的 hedging 比例与桶大小；
• 分析与审计：ClickHouse 支撑的网关评分趋势、决策量、成本节省与单笔支付审计视图；
• Dashboard：React 运营面板，可直接配置路由、跑 A/B 实验、查看分析。

主要 API 面按端点分组组织（Health / Auth / Decisions / Feedback / Merchant accounts / Routing / Cost ingestion / Analytics），其中 Health 组包含 GET /health、GET /health/ready、GET /health/diagnostics 三个端点——安装后第一件事就是验证 GET /health。

需要说明一点：本文所述的安装步骤与文件均以 Decision Engine 官方仓库为准（文档在 Installation 页面明确给出了 juspay/decision-engine 仓库的克隆地址），而 hyperswitch 仓库承载的正是这套 Decision Engine 的 API 文档集（位于 api-reference/decision-engine-api-reference/ 目录），包括 安装指南、本地部署指南、PostgreSQL 指南、MySQL 指南、配置参考 与 Dashboard 指南。

环境要求（Prerequisites）

Installation 文档明确：Quick Start 路径从 GHCR（GitHub Container Registry）拉取预构建镜像，因此你不需要 Rust 工具链、make 或本地数据库。你只需要：

依赖	要求
Docker Engine	20+
Docker Compose	v2+，即 docker compose 子命令，不是旧版 docker-compose 独立二进制
仓库	Decision Engine 仓库克隆到本地——compose 命令要读取 docker-compose.yaml，所以必须在仓库根目录执行
网络与磁盘	可访问 ghcr.io/juspay/... 拉取镜像，并预留数 GB 磁盘空间（首次运行会拉取应用、PostgreSQL、Redis、Kafka、ClickHouse、Mailpit 等镜像）

源码运行轨道（见后文 Local Setup）则额外需要：Rust 1.85+、PostgreSQL 或 MySQL、Redis，以及 just 命令（PostgreSQL 源码运行需 just migrate-pg；MySQL 可直接使用 diesel migration run）。

快速开始：两条命令拉起服务

docker-compose.yaml 中的每个服务都挂在 profile 之后，因此必须传 profile——不存在无 profile 的默认启动方式。这是 Decision Engine 本地部署最关键的约定。

最快路径（仅 API）：

docker compose --profile postgres-ghcr up -d
curl http://localhost:8080/health

预期响应：

{ "message": "Health is good" }

若希望 API、Dashboard、文档一起拉起，把 profile 换成 --profile dashboard-postgres-ghcr，详见 Dashboard 指南。

Compose Profile 全矩阵

Local Setup 指南 把 profile 分为三类，必须至少指定一个。文档中使用的默认镜像标签为：

• DECISION_ENGINE_TAG=v1.4
• GROOVY_RUNNER_TAG=v1.4

核心运行时 Profile

Profile	数据库	包含内容
postgres-ghcr	PostgreSQL	API + PostgreSQL + Redis + Kafka + ClickHouse + PG 迁移任务
postgres-local	PostgreSQL	同上，但 API 镜像从本地源码构建
mysql-ghcr	MySQL	API + MySQL + Redis + Kafka + ClickHouse + MySQL 迁移任务 + routing-config
mysql-local	MySQL	同上，镜像从本地源码构建

注意 MySQL 轨道比 PostgreSQL 轨道多一个 routing-config 初始化服务，从表格结构上可以看出两条轨道并非完全对称。

Dashboard Profile

Profile	数据库	包含内容
dashboard-postgres-ghcr	PostgreSQL	核心 PG 栈 + Dashboard + Mintlify 文档
dashboard-postgres-local	PostgreSQL	核心 PG 栈（本地构建）+ Dashboard + 文档
dashboard-mysql-ghcr	MySQL	核心 MySQL 栈 + Dashboard + 文档
dashboard-mysql-local	MySQL	核心 MySQL 栈（本地构建）+ Dashboard + 文档

可选 Profile

Profile	额外内容
monitoring	Prometheus + Grafana
groovy-ghcr	Groovy 运行器镜像
groovy-local	从本地源码构建的 Groovy 运行器
analytics-clickhouse	仅 Kafka topic 初始化 + ClickHouse 分析引导

两条运行轨道：预构建镜像 vs 本地构建

Local Setup 文档把安装分为两条轨道，选择逻辑是：

1. Published-image 轨道（*-ghcr profile）——拉取 GHCR 上的现成镜像，验证产品行为最快，无需 Rust 环境；
2. Local-build 轨道（*-local profile）——从当前源码树构建镜像或二进制，用于开发验证。

本地构建轨道的 Compose 命令（以 PostgreSQL 为例，摘自 PostgreSQL Setup）：

COMPOSE_PROFILES= docker compose --profile postgres-local up -d --build
# 带 Dashboard + 文档：
COMPOSE_PROFILES= docker compose --profile dashboard-postgres-local up -d --build

GHCR 轨道：

export DECISION_ENGINE_TAG=v1.4
COMPOSE_PROFILES= docker compose --profile postgres-ghcr up -d

数据库选择：PostgreSQL 或 MySQL

Installation 文档的核心观点：PostgreSQL 与 MySQL 是 Decision Engine 中可互换的后端（这一能力也在 Introduction 的 Platform 一节中被列为核心平台特性——"Multi-DB — MySQL and PostgreSQL as interchangeable backends"）。选定其一后跟对应的专门指南走；若想要包含 Dashboard、监控、源码构建在内的完整 profile 矩阵，直接看 Local Setup。

Makefile 提供了一组常用封装（注意这些目标定义在 Decision Engine 官方仓库的 Makefile 中）：

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

分场景启动命令

不同使用场景对应不同的 profile 组合：

仅 API：

docker compose --profile postgres-ghcr up -d

API + Dashboard + 文档：

docker compose --profile dashboard-postgres-ghcr up -d

带监控（两个 profile 可叠加）：

docker compose --profile postgres-ghcr --profile monitoring up -d

一键本地开发：oneclick.sh

面向本地源码开发（含完整 PostgreSQL 分析栈），Local Setup 文档给出单命令入口：

./oneclick.sh

该流程会：用 Docker Compose 拉起 PostgreSQL、Redis、Kafka、ClickHouse 与分析初始化任务；等待基础设施健康；执行 PostgreSQL 迁移；以 cargo run --no-default-features --features postgres 在本地启动 API；以 Vite 在 http://localhost:5173/ 启动 Dashboard。默认按 Ctrl+C 会停止本地 API/Dashboard 进程以及由 oneclick.sh 自行拉起的基础设施服务；若希望退出后保留基础设施，使用：

ONECLICK_KEEP_INFRA=1 ./oneclick.sh

端到端回归门禁

Cypress 分支拥有完整的端到端回归门禁，一条命令跑两种模式：

npm run test:e2e

它会依次执行：oneclick.sh 的源码运行验证、通过 dashboard-postgres-local 的 Compose 验证、针对两种模式的完整 Cypress API/UI/文档冒烟契约。也可按模式单独触发：

npm run test:e2e:source
npm run test:e2e:docker

分析栈（Kafka → ClickHouse）的自动引导

Installation 与 Local Setup 文档都强调：Kafka 到 ClickHouse 的分析链路是自动引导的：

• Kafka topic 由 kafka-init 服务创建；
• ClickHouse 首次启动时加载 clickhouse/scripts/ 目录下的分析 SQL；
• 分析数据存储在命名卷 clickhouse-data 中，常规重启不丢失分析历史；
• 需要干净重建时使用：

make reset-analytics-clickhouse

该命令会删除 ClickHouse 分析卷并重建 Kafka + ClickHouse 分析栈。这也解释了 Quick Start 为什么要求数 GB 磁盘——ClickHouse 与 Kafka 都在栈内。

源码构建与运行

不经过 Docker 镜像、直接以二进制方式运行时：

PostgreSQL：

cargo build --release --no-default-features --features middleware,kms-aws,postgres
just migrate-pg
RUSTFLAGS="-Awarnings" cargo run --no-default-features --features postgres

MySQL：

cargo build --release --features release
RUSTFLAGS="-Awarnings" cargo run --features release

从这两组命令的结构可以看出两个实现事实：其一，PostgreSQL 是 cargo 的非默认 feature（--no-default-features --features postgres），说明 MySQL 侧的 release feature 才是默认构建路径之一；其二，PostgreSQL 轨道依赖 just migrate-pg 这一 justfile 任务执行数据库迁移，而 MySQL 轨道可以跳过 just、直接用 diesel migration run，与 Prerequisites 一节的前置说明相互印证。

无 Compose 的 Docker 构建

若只想构建镜像而不走 Compose 编排：

docker build --platform=linux/amd64 -t decision-engine-mysql:local -f Dockerfile .
docker build --platform=linux/amd64 -t decision-engine-pg:local -f Dockerfile.postgres .

注意两个数据库对应两个不同的 Dockerfile（Dockerfile 用于 MySQL，Dockerfile.postgres 用于 PostgreSQL），从源码结构看这是双后端在构建层面的直接体现。示例容器运行（把本地配置挂载进容器）：

docker run --platform=linux/amd64 \
  -v $(pwd)/config/docker-configuration.toml:/local/config/development.toml \
  -p 8080:8080 \
  decision-engine-pg:local

这里挂载的 config/docker-configuration.toml 是容器内 API 的实际配置来源，服务启动后若参数不符预期，应首先检查该文件（其字段参考 Configuration 文档）。

Helm 部署

Chart 位于官方仓库的 helm-charts/ 目录：

cd helm-charts
helm dependency update
helm install my-release .

Local Setup 文档在此特别强调了一个易踩的坑：必须使用 helm dependency update，而不是 helm dependency build。原因是提交的 Chart.lock 摘要可能与 Chart.yaml 漂移失步，build 在失步时会硬失败并报错 Error: the lock file (Chart.lock) is out of sync with the dependencies file；而 update 会无条件重新解析并重新从 Bitnami 仓库拉取 postgresql、mysql、redis 三个子 chart。

覆盖镜像时使用 image.repository、image.version、image.pullPolicy 三个 values，并建议先 helm install --dry-run 或 helm template 渲染校验后再应用到集群。

验证安装

健康检查是所有轨道的统一验证手段：

curl http://localhost:8080/health

预期响应：

{"message":"Health is good"}

Dashboard profile 额外暴露三个地址：

• 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

故障排查

Local Setup 文档给出四类排障入口：

1. 带干净卷重建 profile（数据状态异常时最直接的恢复手段）：

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

2. 检查数据库迁移任务日志（注意 PG 与 MySQL 的迁移服务名不同）：

docker compose logs db-migrator-postgres   # PostgreSQL
docker compose logs db-migrator            # MySQL

3. 检查分析基础设施：

docker compose logs kafka-init
docker compose logs clickhouse

并可直接向 ClickHouse 的 HTTP 接口查询 schema 验证分析表是否建成：

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

4. 关键排查文件清单（位于 Decision Engine 官方仓库）：docker-compose.yaml、config/docker-configuration.toml、src/config.rs、src/app.rs。前者定义服务拓扑与 profile，后两者定义配置的解析与应用入口——安装问题大多落在这四个文件之一。

一个容易混淆的点值得提醒：本文所在 hyperswitch 仓库根目录的 docker-compose.yml 是 Hyperswitch 路由服务自身的编排（其 profile 为 full_setup、scheduler、full_kv 等，服务包括 hyperswitch-server 等），与 Decision Engine 文档中描述的 postgres-ghcr/dashboard-postgres-ghcr 等 profile 不是同一个文件。执行 Decision Engine 安装步骤前，请确认你处于 juspay/decision-engine 官方仓库根目录，而不是 hyperswitch 仓库根目录。

下一步

• API Guide —— 服务跑通后，逐族路由的复制粘贴式 curl 示例（成本摄入、A/B 测试、Autopilot 等）；
• API Reference（OpenAPI 端点页） —— 精确的请求/响应 schema；
• Configuration —— 服务跑起后的配置文件字段参考与环境变量覆盖；
• Dashboard —— React 运营面板的路由级使用指南；
• PostgreSQL Setup / MySQL Setup —— 数据库专属的命令子集与验证方法。