Cadence 本地开发环境搭建：使用 Docker 安装并配置 PostgreSQL 持久化存储

• 后端
• 任务调度
• 工作流自动化
• 微服务

导读

本文基于 Cadence 仓库中的 docs/setup/POSTGRES_SETUP.md 编写，讲解如何在本地开发环境用 Docker 快速启动一个 PostgreSQL 实例，并把它配置为 Cadence 分布式工作流编排引擎的持久化存储。读完本文，你将掌握：拉取并运行 PostgreSQL 容器、通过psql客户端完成连通性验证、把development_postgres.yaml配置文件中的连接参数与容器端口映射对齐，以及用 docker-compose 一键拉起包含 PostgreSQL 的完整 Cadence 服务栈，为后续 schema 初始化与本地联调铺平道路。

为什么本地开发要用 PostgreSQL

Cadence 是一个分布式、可扩展、持久且高可用的编排引擎，用于以可扩展和弹性方式执行异步长时间运行的业务逻辑。在本地开发场景中，选择一款与生产环境一致的关系型数据库作为持久化存储，可以最大程度降低"本地跑得通、上线就出问题"的风险。Cadence 仓库同时维护 MySQL 与 PostgreSQL 两套 SQL 存储支持，schema 目录、配置示例和 docker-compose 文件都提供了对应的 PostgreSQL 变体，因此本地使用 Docker 起一个 Postgres 是最低成本的验证方式。

官方文档 POSTGRES_SETUP.md 的正文只有一条主线：拉镜像、起容器、登录验证。但要让 PostgreSQL 真正被 Cadence 使用，还需要补上三个环节：数据库建库、schema 初始化、以及服务端配置指向。本文将依次展开。

前置条件：先装好 Docker 并清理旧容器

文档在开头给出的前置条件非常直白：先在你的机器上安装 Docker，然后再安装 Postgres。注意文档中把"Postgres"误写成了"MySQL"，其真实意图是提醒读者先具备容器运行时。

此外，文档特别强调：确保所有 MySQL 容器已被终止并移除。因为 MySQL 与 PostgreSQL 默认都占用 5432 端口附近的服务端口（MySQL 默认 3306，PostgreSQL 默认 5432），残留的旧容器可能造成端口冲突或数据混淆。可以使用以下命令检查并清理：

docker ps -a docker kill <container_id> && docker rm <container_id> # 移除任何残留容器

docker ps -a列出所有容器（包括已停止的），docker kill强制终止、docker rm删除容器。如果只想清理 Postgres 相关容器，可在命令中结合docker ps -a | grep postgres过滤。

拉取并运行 PostgreSQL 容器

拉取官方镜像

docker pull postgres

docker pull postgres不带 tag 时默认拉取postgres:latest。文档中的命令示例基于最新版镜像；仓库内的 docker-compose-postgres.yml 则固定使用了postgres:17.4这一具体版本，生产或复现环境建议像这样锁定版本号，避免镜像漂移。

运行容器并暴露 5432 端口

mkdir -p ~/docker/volumes/postgres docker run --rm --name pg-docker -e POSTGRES_PASSWORD=cadence -d -p 5432:5432 -v ~/docker/volumes/postgres:/var/lib/postgresql/data postgres

逐参数解读这条核心命令：

关于数据目录需要特别说明：PostgreSQL 17 及以上版本中官方镜像的数据目录默认是/var/lib/postgresql/data（挂载卷时镜像会自动处理权限与初始化），而更早版本常见的是/var/lib/postgresql/data的子目录路径；若遇到数据目录冲突错误，可参考镜像官方文档调整挂载点。--rm与数据卷配合使用不会丢失数据，因为数据落在宿主机卷中。

登录验证：用 psql 客户端连入容器

容器启动后，在宿主机执行：

psql -h localhost -U postgres -d cadence

• -h localhost：通过宿主机回环地址连接（依赖-p 5432:5432的端口映射）；
• -U postgres：以超级用户身份登录；
• -d cadence：指定要连接的数据库；
• 提示输入密码时，输入上一步设置的cadence。

如果宿主机没有安装 psql 客户端，也可以直接进入容器执行：

docker exec -it pg-docker psql -U postgres

成功登录后会看到postgres=#提示符，可执行\l查看数据库列表、\q退出。

创建 Cadence 所需的两个数据库

登录验证只是第一步。Cadence 的持久化层实际需要两个数据库：默认存储库cadence和可见性（visibility）存储库cadence_visibility。这可以从仓库的 schema 定义确认：

• schema/postgres/cadence/database.sql：CREATE DATABASE cadence;
• schema/postgres/visibility/database.sql：CREATE DATABASE cadence_visibility;

在 psql 提示符下依次执行：

CREATE DATABASE cadence; CREATE DATABASE cadence_visibility;

或者在宿主机直接执行：

psql -h localhost -U postgres -c "CREATE DATABASE cadence;" psql -h localhost -U postgres -c "CREATE DATABASE cadence_visibility;"

注意：使用ubercadence/server:master-auto-setup这类 auto-setup 镜像时，容器启动会自动完成建库与 schema 初始化；但本地直接以源码方式运行 cadence-server 时，需要手动完成上述建库步骤。

初始化 schema

数据库建好之后，还需要创建表结构与版本管理表。仓库把 PostgreSQL 的 schema 文件放在 schema/postgres 下，其中cadence/与visibility/各自包含database.sql、schema.sql与versioned/版本化目录；schema/postgres/embed.go 通过//go:embed cadence/* visibility/*把这些 schema 文件内嵌进二进制，使得cadence-sql-tool与 auto-setup 镜像可以直接使用内嵌 schema。

使用 cadence-sql-tool 完成初始化（PostgreSQL 插件名为postgres，示例以本地 5432 端口为准）：

# 1. 创建数据库 ./cadence-sql-tool --ep 127.0.0.1 -p 5432 --plugin postgres create-database --db cadence ./cadence-sql-tool --ep 127.0.0.1 -p 5432 --plugin postgres create-database --db cadence_visibility # 2. 初始化 schema 版本表并升级到最新版本 ./cadence-sql-tool --ep 127.0.0.1 -p 5432 --plugin postgres --db cadence setup-schema -v 0.0 ./cadence-sql-tool --ep 127.0.0.1 -p 5432 --plugin postgres --db cadence update-schema -d ./schema/postgres/cadence/versioned ./cadence-sql-tool --ep 127.0.0.1 -p 5432 --plugin postgres --db cadence_visibility setup-schema -v 0.0 ./cadence-sql-tool --ep 127.0.0.1 -p 5432 --plugin postgres --db cadence_visibility update-schema -d ./schema/postgres/visibility/versioned

关于这一流程的详细说明可参考 tools/sql/README.md，其中明确提到这套 SQL 工具对底层存储引擎无感知，同一套命令既可作用于 MySQL 也可作用于 PostgreSQL（换--plugin postgres即可）。schema 升级还支持--dryrun参数做预演：update-schema ... -v x.x --dryrun只输出将要执行的变更而不实际写入。另外 tools/sql/README.md 也指出，cadence-sql-tool二进制同样内置在ubercadence/server的 Docker 镜像中。

让 Cadence 服务连接 PostgreSQL

方式一：修改本地配置文件

仓库提供了现成的 PostgreSQL 配置模板 config/development_postgres.yaml，其内容与上文 Docker 容器的端口、密码完全对应：

persistence: defaultStore: postgres-default visibilityStore: postgres-visibility datastores: postgres-default: sql: pluginName: "postgres" databaseName: "cadence" connectAddr: "127.0.0.1:5432" connectProtocol: "tcp" user: "postgres" password: "cadence" maxConns: 20 maxIdleConns: 20 maxConnLifetime: "1h" postgres-visibility: sql: pluginName: "postgres" databaseName: "cadence_visibility" connectAddr: "127.0.0.1:5432" connectProtocol: "tcp" user: "postgres" password: "cadence" maxConns: 2 maxIdleConns: 2 maxConnLifetime: "1h"

关键参数对照：

本地启动服务时可通过--config指向该文件运行 cadence-server，即可让服务连上刚启动的 PostgreSQL。

方式二：使用 docker-compose 一键启动完整栈

仓库提供了 docker/docker-compose-postgres.yml，用一条命令即可拉起 PostgreSQL + Cadence server + Cadence Web + Prometheus + Grafana 的完整本地开发栈：

cd docker docker compose -f docker-compose-postgres.yml up

该 compose 文件的关键要点：

• 固定使用postgres:17.4镜像，POSTGRES_USER=cadence、POSTGRES_PASSWORD=cadence；
• cadence 服务使用ubercadence/server:master-auto-setup（启动时自动建库并初始化 schema），并通过环境变量DB=postgres、DB_PORT=5432、POSTGRES_USER=cadence、POSTGRES_PWD=cadence、POSTGRES_SEEDS=postgres指向同 compose 网络中的 Postgres 服务；
• cadence-web 通过CADENCE_GRPC_PEERS=cadence:7833连接前端服务，Web 控制台暴露在 8088 端口；
• Grafana 与 Prometheus 提供指标监控面板，Grafana 在 3000 端口。

这些环境变量与 docker/config_template.yaml 中的模板一一对应，例如模板中connectAddr: "{{ default .Env.POSTGRES_SEEDS "" }}:{{ default .Env.DB_PORT "5432" }}"、user: {{ default .Env.POSTGRES_USER "" }}，即 compose 设置的环境变量会被 dockerize 模板机制自动填充到服务配置中。相关说明可参考 docker/README.md，其中列明docker-compose-postgres.yml uses PostgreSQL as persistence storage。

提示：master-auto-setup是持续变动（changing）的镜像，适合日常开发；如需稳定版本，可以改用发布镜像或自己按 docker/README.md 中TARGET=auto-setup的方式构建。

常见问题排查

1. 端口被占用：docker ps -a检查是否有其他容器占用 5432，按文档要求先docker kill+docker rm清理。
2. psql 连接失败 / 密码错误：确认容器是通过-e POSTGRES_PASSWORD=cadence启动的；若容器已存在则需删除重建（--rm容器停止即删，重建即生效）。
3. 数据卷权限问题：挂载到/var/lib/postgresql/data时若遇到权限错误，确认宿主机目录可写，或参考镜像文档调整挂载路径与用户。
4. Cadence 服务报"数据库不存在"：检查cadence与cadence_visibility两个库是否都已创建，可用psql -h localhost -U postgres -c "\l"确认。
5. schema 版本不匹配：使用cadence-sql-tool ... --dryrun先预演升级，确认目标版本后再实际执行。

总结

通过本文你可以完整走通"PostgreSQL 本地化"的全链路：docker pull postgres拉镜像 →docker run起容器并映射 5432 端口 →psql登录验证 → 创建cadence与cadence_visibility两个数据库 → 用cadence-sql-tool --plugin postgres初始化 schema → 通过 config/development_postgres.yaml 或 docker/docker-compose-postgres.yml 让 Cadence 服务接入 PostgreSQL。这套流程与仓库内 schema、配置模板及工具链保持了一致，可作为后续开发、测试乃至生产环境部署（改用固定版本镜像 + 手动建库）的可靠起点。

• 后端
• 任务调度
• 工作流自动化
• 微服务