Hyperswitch Decision Engine 的 PostgreSQL 部署：Compose Profile、Make 目标与源码级配置详解

Hyperswitch 生态中的 Decision Engine 是一个独立的智能路由控制面服务，负责为每笔交易选择最优支付网关，可独立于支付编排器运行（见 README.md 中对该服务的描述）。本篇聚焦 Decision Engine 的 PostgreSQL 部署路径：如何仅用数条命令通过 Docker Compose 拉起完整的 PostgreSQL 技术栈、使用哪些 Make 目标、以及如何验证服务健康。读完后你可以独立完成 Decision Engine 的 Postgres 本地部署、源码构建运行，并能从配置文件中定位数据库参数。

1. 背景：为什么需要单独的 PostgreSQL 部署指南

Decision Engine 支持 PostgreSQL 与 MySQL 两种可互换的数据库后端，官方文档为此拆分为两套数据库专属的部署手册：

• PostgreSQL Setup —— 本文主题；
• MySQL Setup —— MySQL 对等版本；
• Local Setup Guide —— 完整的 CLI / Docker / Compose / Helm 矩阵权威指南；
• Installation —— 端到端安装入口。

PostgreSQL 手册本身只收录 Postgres 专属命令，完整的 profile 语义、源码构建与排障内容以 Local Setup 为准。理解这一文档分工，有助于按数据库维度快速定位部署命令。

2. 前提条件

来自 Local Setup Guide 的前置要求（PostgreSQL 手册的 Compose 命令依赖这些条件）：

• Docker 20+、Docker Compose v2+（docker compose 子命令，而非旧版 docker-compose 二进制）；
• Git 2+；
• 源码运行场景额外需要：Rust 1.85+、PostgreSQL 或 MySQL、Redis，以及 just 命令运行器（PostgreSQL 源码运行必须通过 just migrate-pg 执行数据库迁移；MySQL 则可直接使用 diesel migration run）。

注意 Quick Start 拉取的是预构建镜像（GHCR track），因此容器化路径不需要本地安装 Rust、make 或数据库；但源码运行路径（见第 6 节）需要完整工具链。

3. Docker Compose 启动（PostgreSQL）

PostgreSQL 手册提供了三条核心启动路径，全部基于 compose profile 机制——docker-compose.yaml 中每个服务都挂在某个 profile 之后，因此必须显式传入至少一个 profile，不存在无 profile 的默认启动。

3.1 发布镜像轨道（GHCR track）

拉取官方发布镜像，指定默认版本标签后启动：

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

该 profile 包含的核心栈为：API + PostgreSQL + Redis + Kafka + ClickHouse + PostgreSQL 迁移作业。

带 Dashboard 与 Mintlify 文档服务时改用 dashboard-postgres-ghcr：

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

按 Local Setup 的 profile 矩阵，dashboard-postgres-ghcr = 核心 PG 栈 + dashboard + Mintlify docs。启动后除 API 外还暴露：

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

默认版本标签约定（用于 GHCR 轨道）：

• DECISION_ENGINE_TAG=v1.4 —— Decision Engine 应用镜像；
• GROOVY_RUNNER_TAG=v1.4 —— Groovy 规则运行器镜像（配合可选 profile groovy-ghcr 使用）。

3.2 本地构建轨道（Local build track）

从当前源码树构建镜像，适用于修改了源码后的验证：

COMPOSE_PROFILES= docker compose --profile postgres-local up -d --build

带 Dashboard + docs 的对应命令：

COMPOSE_PROFILES= docker compose --profile dashboard-postgres-local up -d --build

两条轨道的核心差异仅在于应用镜像来源：postgres-ghcr 拉取 GHCR 上的既有镜像，postgres-local 通过 --build 从源码构建；PostgreSQL、Redis、Kafka、ClickHouse 等基础设施栈一致。

3.3 Make 目标快捷方式

不想手写 profile 命令时，仓库提供等价 make 包装：

make init-pg-ghcr    # 等价于 postgres-ghcr profile 启动
make init-pg-local   # 等价于 postgres-local profile 启动

Local Setup 中还列出了相关常用目标，可作为操作面参照：

make run-pg-ghcr
make stop
make reset-analytics-clickhouse   # 删除 ClickHouse 分析卷并重建 Kafka + ClickHouse 分析栈

4. 验证：健康检查

启动完成后，用手册给定的 curl 命令验证 API 存活：

curl http://localhost:8080/health

预期响应：

{"message":"Health is good"}

端口 8080 与 Configuration 中 [server] 节一致：

[server]
host = "0.0.0.0"
port = 8080

host 为绑定地址：容器化部署用 0.0.0.0，仅本机访问可用 127.0.0.1。此外还有两个配套健康端点可供更细粒度检查（见 healthCheck 与 healthDiagnostics）：GET /health/ready 用于就绪检查，GET /health/diagnostics 用于深度诊断——后者属于按租户路由的接口，需要携带 x-tenant-id: public 请求头，缺失会直接被拒绝（错误码 TE_03）。

5. 结合仓库：PostgreSQL 栈到底包含什么

从 Local Setup 的 profile 矩阵和 Analytics Bootstrap 章节可以还原 postgres-ghcr / postgres-local 的组成：

组件	作用	说明
Decision Engine API	路由控制面主服务	监听 8080
PostgreSQL	主数据库	由 db-migrator-postgres 迁移作业初始化
Redis	缓存	缓存路由配置与服务配置，[cache_config] 中 service_config_ttl 默认 300 秒
Kafka + ClickHouse	分析链路	kafka-init 创建 Kafka topic；ClickHouse 首次启动时加载 clickhouse/scripts/ 下的分析 SQL
PG migrations	数据库迁移	以一次性 job 形式运行，日志可用 docker compose logs db-migrator-postgres 查看

分析数据落在命名 Docker 卷 clickhouse-data 中，普通重启会保留分析历史；需要彻底重建时使用 make reset-analytics-clickhouse。

数据库连接参数在 Configuration 中有完整定义。PostgreSQL 使用独立的 [pg_database] 配置节（与 MySQL 的 [database] 节分开）：

[pg_database]
pg_username = "db_user"
pg_password = "db_pass"
pg_host = "localhost"
pg_port = 5432
pg_dbname = "decision_engine_db"

对于 Docker Compose 运行，两个节都已通过 config/docker-configuration.toml 中的服务名预接线，无需手改——这也是手册中 Postgres 命令不需要额外配置环境变量即可工作的前提。多租户场景下，[tenant_secrets] 节把租户标识映射到数据库 schema，出厂配置仅定义 public 租户。

6. 源码构建运行（PostgreSQL 轨道）

Local Setup 给出了 PostgreSQL 源码运行的三条命令，这是 postgres-local 容器轨道之外的第二种本地运行方式：

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

关键点：

1. postgres feature 门控数据库后端——构建与运行都必须显式传 --features postgres，否则不会启用 PostgreSQL 支持；just migrate-pg 负责执行 PostgreSQL 迁移（这也是文档要求源码运行安装 just 的原因）。

2. 一键脚本 ./oneclick.sh 会走完整的本地开发流程：Compose 拉起 PostgreSQL、Redis、Kafka、ClickHouse 与分析初始化作业 → 等待基础设施健康 → 执行 PostgreSQL 迁移 → 用 cargo run --no-default-features --features postgres 启动本地 API → Vite 启动 Dashboard（http://localhost:5173/）。默认 Ctrl+C 会一并停止由 oneclick.sh 自行拉起的基础设施；要保留基础设施可用 ONECLICK_KEEP_INFRA=1 ./oneclick.sh。

3. 不经 Compose 直接构建 Docker 镜像时，PostgreSQL 有独立 Dockerfile：

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

   容器运行示例把仓库配置文件挂载为容器内配置：

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

7. 排障要点（PostgreSQL 场景）

来自 Local Setup Troubleshooting 章节，针对 PG 栈最有用的几条：

以干净卷重建 profile（怀疑脏数据/迁移卡住时）：

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

检查迁移作业：

docker compose logs db-migrator-postgres

检查分析基础设施：

docker compose logs kafka-init
docker compose logs clickhouse

直接查询 ClickHouse 模式确认分析表是否已创建：

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

排障时值得优先查看的文件（手册原文列出的“Common Next Files To Inspect”）：docker-compose.yaml、config/docker-configuration.toml、src/config.rs、src/app.rs——其中 config/docker-configuration.toml 即第 5 节所述的服务名预接线配置。

8. 与 Hyperswitch 主仓库的关系

需要说明的适用前提：本文所述 Decision Engine 的 Compose/镜像/Helm 文件位于其独立服务仓库（juspay/decision-engine）中，本 hyperswitch 仓库内收录的是该服务的完整 API 参考与部署文档（api-reference/decision-engine-api-reference/ 目录）。两者在本仓库中的交汇点体现在 Hyperswitch 的路由层：

• crates/router/src/core/routing.rs 等文件包含 Hyperswitch 与 Decision Engine 的对接逻辑（路由配置、评分端点、健康检查等），例如 core/routing/helpers.rs、core/payments/routing/utils.rs；
• CHANGELOG.md 记录了多条决策引擎集成演进：x-admin-secret 鉴权（#13539）、决策引擎 HTTP 请求指标（#13457）、无活跃路由算法时跳过评估（#13702）等；
• healthCheck 对应的 /health 端点即本文第 4 节验证命令的 API 定义。

从源码结构看，Hyperswitch 在主链路中以 HTTP 客户端身份调用 Decision Engine 完成动态路由决策，Decision Engine 则作为可独立部署的控制面运行——这正是本篇 PostgreSQL 部署指南的实际使用场景。

9. 命令速查

场景	命令
GHCR 镜像启动（API 栈）	COMPOSE_PROFILES= docker compose --profile postgres-ghcr up -d
GHCR 镜像启动（+Dashboard+Docs）	COMPOSE_PROFILES= docker compose --profile dashboard-postgres-ghcr up -d
源码构建镜像启动	COMPOSE_PROFILES= docker compose --profile postgres-local up -d --build
Make 快捷	make init-pg-ghcr / make init-pg-local
健康检查	curl http://localhost:8080/health → {"message":"Health is good"}
干净重建	docker compose --profile postgres-ghcr down -v && docker compose --profile postgres-ghcr up -d
查看迁移日志	docker compose logs db-migrator-postgres
源码运行	cargo run --no-default-features --features postgres（迁移用 just migrate-pg）

相关文档：Installation、Local Setup Guide、MySQL Setup、Configuration。