Temporal 开发环境搭建在 macOS 上安装与运行 Cassandra v5.0【免费下载链接】temporalTemporal service项目地址: https://gitcode.com/gh_mirrors/te/temporal本指南以 Temporal 仓库中的 docs/development/macos/cassandra.md 为骨架详细讲解如何在 macOS 上通过 Homebrew 安装、启动并验证 Cassandra v5.0并将其接入 Temporal Server 作为默认持久化存储。读完本文你将掌握本地 Cassandra 的完整启动流程、cqlsh验证方法以及如何利用仓库自带的temporal-cassandra-tool初始化 schema 并用 Cassandra 配置启动 Temporal Server。为什么要在 macOS 本地直接运行 Cassandra在正式开始安装之前先说明一个背景动机。Temporal 仓库的开发文档 docs/development/run-dependencies-host.md 明确指出在 macOS 上进行 Temporal Server 开发时建议直接在宿主机上运行其依赖如 Cassandra、MySQL、PostgreSQL其中一个重要原因是macOS 上 Docker 文件系统file system性能较差会影响本地开发的体验与测试速度。因此仓库为 macOS 开发者单独提供了本机安装依赖的指引本文所讲解的 Cassandra 安装正是其中针对 Cassandra 的部分。提示Linux 用户则应使用docker compose方式运行依赖详见仓库根目录的 CONTRIBUTING.md本文聚焦 macOS 场景。第一步安装 Cassandra在 macOS 上安装 Cassandra 最简单的方式是使用 Homebrewbrew install cassandra该命令会从 Homebrew 官方公式仓库拉取 Cassandra 并安装到系统中默认安装路径通常为/opt/homebrew或/usr/local取决于你的 Mac 是 Apple Silicon 还是 Intel 架构。本文档标题针对Cassandra v5.0执行安装后可通过cassandra -v确认实际安装的版本与文档要求一致。安装完成后Homebrew 会同时提供cassandra服务端启动脚本、cqlsh交互式查询客户端等命令行工具这些都会自动加入 PATH无需额外配置环境变量。第二步启动 Cassandra安装完成后在前台启动 Cassandra 服务cassandra -f参数-fforeground表示在前台运行日志会直接输出到当前终端便于开发调试时实时观察服务启动过程。启动成功后Cassandra 默认会监听以下端口9042CQLCassandra Query Language客户端端口cqlsh和 Temporal Server 都通过该端口访问数据7000集群节点间通信端口7199JMX 监控端口。如果希望以后台守护进程方式运行不占用终端可以去掉-f参数直接执行cassandra也可以使用brew services start cassandra将其注册为 macOS 后台服务并开机自启。对于开发调试场景前台运行-f通常更直观。第三步验证 Cassandra 已正常运行启动完成后使用 Cassandra 自带的交互式客户端验证服务是否可用cqlsh执行后如果进入cqlsh交互提示符形如Connected to Test Cluster at 127.0.0.1:9042说明 Cassandra v5.0 已成功运行并对外提供服务。此时可以执行以下命令做进一步确认-- 查看当前集群名称与版本信息 SELECT cluster_name, release_version FROM system.local; -- 查看已存在的 keyspace DESCRIBE KEYSPACES;正常的输出中应包含system、system_schema等系统 keyspace。若cqlsh连接失败请检查Cassandra 进程是否仍在运行-f模式下终端是否被占用端口9042是否被其他进程占用可通过lsof -i :9042查看是否等待了足够的启动时间首次启动需要初始化数据目录与 commit log可能需要数十秒。第四步为 Temporal 初始化 Cassandra SchemaCassandra 本身只是数据库引擎要让 Temporal Server 正常使用还需要创建 Temporal 专属的 keyspace 并初始化 schema。仓库已在 schema/cassandra/temporal/keyspace.cql 中预置了 keyspace 定义CREATE KEYSPACE IF NOT EXISTS temporal WITH replication { class : SimpleStrategy, replication_factor : 1};该定义使用SimpleStrategy复制策略replication_factor为1适用于单节点本地开发环境。不过手动执行 CQL 初始化完整 schema 并不推荐——仓库提供了专门的命令行工具temporal-cassandra-tool源码位于 cmd/tools/cassandra。查看仓库根目录的 Makefile 可以看到官方推荐的初始化流程以install-schema-cass-es目标为例make bins # 构建 temporal-server、temporal-cassandra-tool 等二进制 ./temporal-cassandra-tool drop -k temporal -f # 可选删除已存在的 keyspace ./temporal-cassandra-tool create -k temporal --rf 1 # 创建 keyspace复制因子为 1 ./temporal-cassandra-tool -k temporal setup-schema -v 0.0 ./temporal-cassandra-tool -k temporal update-schema -d ./schema/cassandra/temporal/versioned其中create创建名为temporal的 keyspace--rf 1对应单节点开发环境setup-schema -v 0.0从版本0.0开始建立 schema 版本基线update-schema -d ./schema/cassandra/temporal/versioned按版本目录依次应用增量变更。仓库中的 schema 采用版本化目录管理见 schema/cassandra/README.md每个版本变更位于versioned/下的独立目录例如v1.0、v1.1…v1.13每个目录包含描述变更的manifest.json与包含CREATE/ALTER语句的.cql文件。当前 Cassandra schema 的发布版本为1.13见 schema/cassandra/version.go 中的Version常量。提示从源码结构看versioned/目录下已包含v1.0至v1.13共 13 个版本目录若你克隆的仓库更新实际版本目录可能更多update-schema会自动应用所有未执行的版本。第五步配置 Temporal Server 使用 Cassandra初始化 schema 后即可用 Cassandra 作为 Temporal Server 的默认持久化存储。仓库在 config/development-cass-es.yaml 中提供了以 Cassandra 为默认存储的参考配置该配置同时使用 Elasticsearch 作为 visibility store其中 Cassandra 相关的核心片段如下persistence: defaultStore: cass-default visibilityStore: es-visibility numHistoryShards: 4 datastores: cass-default: cassandra: hosts: 127.0.0.1 keyspace: temporal关键参数说明defaultStore: cass-default指定默认存储使用下方定义的cass-default数据源hosts: 127.0.0.1Cassandra 地址与上文cassandra -f监听的本机地址一致keyspace: temporal使用的 keyspace 名称须与第四步初始化时创建的 keyspace 一致numHistoryShards: 4历史分片数开发环境可根据需要调整。此外该配置的dynamicConfigClient.filepath指向config/dynamicconfig/development-cass.yaml即配套的 Cassandra 动态配置。如果你不需要 Elasticsearch 高级可见性也可以参考仓库中其他以development-cass-*命名的配置如development-cass-s3.yaml、development-cass-es-dual.yaml等均位于 config 目录按需组合。配置就绪后即可启动 Temporal Server./temporal-server start --config config --env development-cass-es启动成功后Server 的 frontend 服务会监听7233端口gRPC与7243端口HTTP说明本地开发环境已完整搭建。常见问题与注意事项版本匹配本文针对 Cassandra v5.0若brew install cassandra安装到的版本不是 v5.0请以cassandra -v的实际输出来核对必要时参考 Homebrew 的版本管理方式安装指定版本。首次启动较慢Cassandra 首次启动需要生成系统表与数据目录cqlsh在服务完全就绪前可能短暂连接失败稍等重试即可。keyspace 一致性第四步创建 keyspace 的名称必须与配置文件中persistence.datastores.cass-default.cassandra.keyspace保持一致否则 Server 启动时会因找不到 keyspace 而报错。schema 升级当升级到包含新 schema 版本的 Temporal 代码时重新执行./temporal-cassandra-tool -k temporal update-schema -d ./schema/cassandra/temporal/versioned即可完成增量迁移无需手工编写 CQL。小结围绕 Temporal 仓库的 docs/development/macos/cassandra.md本文完整复现了在 macOS 上运行 Cassandra v5.0 的全过程brew install cassandra安装 →cassandra -f前台启动 →cqlsh连接验证并在此基础上结合仓库源码补充了 schema 初始化temporal-cassandra-tool与 Server 配置development-cass-es.yaml两个关键环节。掌握这三步即可在本机跑起Cassandra Temporal Server的最小开发环境摆脱 macOS 上 Docker 文件系统性能不佳的困扰。【免费下载链接】temporalTemporal service项目地址: https://gitcode.com/gh_mirrors/te/temporal创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Temporal 开发环境搭建：在 macOS 上安装与运行 Cassandra v5.0
Temporal 开发环境搭建在 macOS 上安装与运行 Cassandra v5.0【免费下载链接】temporalTemporal service项目地址: https://gitcode.com/gh_mirrors/te/temporal本指南以 Temporal 仓库中的 docs/development/macos/cassandra.md 为骨架详细讲解如何在 macOS 上通过 Homebrew 安装、启动并验证 Cassandra v5.0并将其接入 Temporal Server 作为默认持久化存储。读完本文你将掌握本地 Cassandra 的完整启动流程、cqlsh验证方法以及如何利用仓库自带的temporal-cassandra-tool初始化 schema 并用 Cassandra 配置启动 Temporal Server。为什么要在 macOS 本地直接运行 Cassandra在正式开始安装之前先说明一个背景动机。Temporal 仓库的开发文档 docs/development/run-dependencies-host.md 明确指出在 macOS 上进行 Temporal Server 开发时建议直接在宿主机上运行其依赖如 Cassandra、MySQL、PostgreSQL其中一个重要原因是macOS 上 Docker 文件系统file system性能较差会影响本地开发的体验与测试速度。因此仓库为 macOS 开发者单独提供了本机安装依赖的指引本文所讲解的 Cassandra 安装正是其中针对 Cassandra 的部分。提示Linux 用户则应使用docker compose方式运行依赖详见仓库根目录的 CONTRIBUTING.md本文聚焦 macOS 场景。第一步安装 Cassandra在 macOS 上安装 Cassandra 最简单的方式是使用 Homebrewbrew install cassandra该命令会从 Homebrew 官方公式仓库拉取 Cassandra 并安装到系统中默认安装路径通常为/opt/homebrew或/usr/local取决于你的 Mac 是 Apple Silicon 还是 Intel 架构。本文档标题针对Cassandra v5.0执行安装后可通过cassandra -v确认实际安装的版本与文档要求一致。安装完成后Homebrew 会同时提供cassandra服务端启动脚本、cqlsh交互式查询客户端等命令行工具这些都会自动加入 PATH无需额外配置环境变量。第二步启动 Cassandra安装完成后在前台启动 Cassandra 服务cassandra -f参数-fforeground表示在前台运行日志会直接输出到当前终端便于开发调试时实时观察服务启动过程。启动成功后Cassandra 默认会监听以下端口9042CQLCassandra Query Language客户端端口cqlsh和 Temporal Server 都通过该端口访问数据7000集群节点间通信端口7199JMX 监控端口。如果希望以后台守护进程方式运行不占用终端可以去掉-f参数直接执行cassandra也可以使用brew services start cassandra将其注册为 macOS 后台服务并开机自启。对于开发调试场景前台运行-f通常更直观。第三步验证 Cassandra 已正常运行启动完成后使用 Cassandra 自带的交互式客户端验证服务是否可用cqlsh执行后如果进入cqlsh交互提示符形如Connected to Test Cluster at 127.0.0.1:9042说明 Cassandra v5.0 已成功运行并对外提供服务。此时可以执行以下命令做进一步确认-- 查看当前集群名称与版本信息 SELECT cluster_name, release_version FROM system.local; -- 查看已存在的 keyspace DESCRIBE KEYSPACES;正常的输出中应包含system、system_schema等系统 keyspace。若cqlsh连接失败请检查Cassandra 进程是否仍在运行-f模式下终端是否被占用端口9042是否被其他进程占用可通过lsof -i :9042查看是否等待了足够的启动时间首次启动需要初始化数据目录与 commit log可能需要数十秒。第四步为 Temporal 初始化 Cassandra SchemaCassandra 本身只是数据库引擎要让 Temporal Server 正常使用还需要创建 Temporal 专属的 keyspace 并初始化 schema。仓库已在 schema/cassandra/temporal/keyspace.cql 中预置了 keyspace 定义CREATE KEYSPACE IF NOT EXISTS temporal WITH replication { class : SimpleStrategy, replication_factor : 1};该定义使用SimpleStrategy复制策略replication_factor为1适用于单节点本地开发环境。不过手动执行 CQL 初始化完整 schema 并不推荐——仓库提供了专门的命令行工具temporal-cassandra-tool源码位于 cmd/tools/cassandra。查看仓库根目录的 Makefile 可以看到官方推荐的初始化流程以install-schema-cass-es目标为例make bins # 构建 temporal-server、temporal-cassandra-tool 等二进制 ./temporal-cassandra-tool drop -k temporal -f # 可选删除已存在的 keyspace ./temporal-cassandra-tool create -k temporal --rf 1 # 创建 keyspace复制因子为 1 ./temporal-cassandra-tool -k temporal setup-schema -v 0.0 ./temporal-cassandra-tool -k temporal update-schema -d ./schema/cassandra/temporal/versioned其中create创建名为temporal的 keyspace--rf 1对应单节点开发环境setup-schema -v 0.0从版本0.0开始建立 schema 版本基线update-schema -d ./schema/cassandra/temporal/versioned按版本目录依次应用增量变更。仓库中的 schema 采用版本化目录管理见 schema/cassandra/README.md每个版本变更位于versioned/下的独立目录例如v1.0、v1.1…v1.13每个目录包含描述变更的manifest.json与包含CREATE/ALTER语句的.cql文件。当前 Cassandra schema 的发布版本为1.13见 schema/cassandra/version.go 中的Version常量。提示从源码结构看versioned/目录下已包含v1.0至v1.13共 13 个版本目录若你克隆的仓库更新实际版本目录可能更多update-schema会自动应用所有未执行的版本。第五步配置 Temporal Server 使用 Cassandra初始化 schema 后即可用 Cassandra 作为 Temporal Server 的默认持久化存储。仓库在 config/development-cass-es.yaml 中提供了以 Cassandra 为默认存储的参考配置该配置同时使用 Elasticsearch 作为 visibility store其中 Cassandra 相关的核心片段如下persistence: defaultStore: cass-default visibilityStore: es-visibility numHistoryShards: 4 datastores: cass-default: cassandra: hosts: 127.0.0.1 keyspace: temporal关键参数说明defaultStore: cass-default指定默认存储使用下方定义的cass-default数据源hosts: 127.0.0.1Cassandra 地址与上文cassandra -f监听的本机地址一致keyspace: temporal使用的 keyspace 名称须与第四步初始化时创建的 keyspace 一致numHistoryShards: 4历史分片数开发环境可根据需要调整。此外该配置的dynamicConfigClient.filepath指向config/dynamicconfig/development-cass.yaml即配套的 Cassandra 动态配置。如果你不需要 Elasticsearch 高级可见性也可以参考仓库中其他以development-cass-*命名的配置如development-cass-s3.yaml、development-cass-es-dual.yaml等均位于 config 目录按需组合。配置就绪后即可启动 Temporal Server./temporal-server start --config config --env development-cass-es启动成功后Server 的 frontend 服务会监听7233端口gRPC与7243端口HTTP说明本地开发环境已完整搭建。常见问题与注意事项版本匹配本文针对 Cassandra v5.0若brew install cassandra安装到的版本不是 v5.0请以cassandra -v的实际输出来核对必要时参考 Homebrew 的版本管理方式安装指定版本。首次启动较慢Cassandra 首次启动需要生成系统表与数据目录cqlsh在服务完全就绪前可能短暂连接失败稍等重试即可。keyspace 一致性第四步创建 keyspace 的名称必须与配置文件中persistence.datastores.cass-default.cassandra.keyspace保持一致否则 Server 启动时会因找不到 keyspace 而报错。schema 升级当升级到包含新 schema 版本的 Temporal 代码时重新执行./temporal-cassandra-tool -k temporal update-schema -d ./schema/cassandra/temporal/versioned即可完成增量迁移无需手工编写 CQL。小结围绕 Temporal 仓库的 docs/development/macos/cassandra.md本文完整复现了在 macOS 上运行 Cassandra v5.0 的全过程brew install cassandra安装 →cassandra -f前台启动 →cqlsh连接验证并在此基础上结合仓库源码补充了 schema 初始化temporal-cassandra-tool与 Server 配置development-cass-es.yaml两个关键环节。掌握这三步即可在本机跑起Cassandra Temporal Server的最小开发环境摆脱 macOS 上 Docker 文件系统性能不佳的困扰。【免费下载链接】temporalTemporal service项目地址: https://gitcode.com/gh_mirrors/te/temporal创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考