3分钟搭建Temporal开发环境：Docker与工具链配置指南-优快云博客

3分钟搭建Temporal开发环境：Docker与工具链配置指南

【免费下载链接】temporal Temporal service 项目地址: https://gitcode.com/gh_mirrors/te/temporal

你还在为分布式系统开发环境配置繁琐而头疼？依赖冲突、版本不兼容、服务启动失败……这些问题是否让你耗费数小时却寸步难行？本文将带你通过Docker容器化方案和本地工具链两种方式，5分钟内完成Temporal开发环境的搭建，让你专注于业务逻辑而非环境配置。

读完本文你将掌握：

Docker一键启动Temporal完整依赖集群
本地编译Temporal Server核心组件
环境验证与常见问题排查技巧
开发工具链最佳配置实践

环境准备清单

工具名称	最低版本要求	作用说明	安装指南
Docker	20.10+	容器化运行依赖服务	Docker官网
Docker Compose	2.0+	编排多容器应用	随Docker Desktop内置
Git	2.30+	代码版本控制	Git国内镜像
Go	1.21+	编译Temporal源码	Go中国镜像
Make	3.81+	自动化构建工具	Windows用户建议通过Chocolatey安装

⚠️ 注意：Windows用户需开启WSL2功能，避免Docker Desktop性能问题。详细配置可参考开发环境依赖文档

Docker容器化部署（推荐新手）

1. 获取Docker Compose配置

Temporal官方提供了预配置的Docker Compose模板，包含所有必要依赖服务：

# 克隆代码仓库
git clone https://link.gitcode.com/i/4ca54c121f8efe2ac77922ea2d69377c.git
cd temporal

# 查看完整配置结构
ls -l develop/docker-compose/

核心配置文件说明：

docker-compose.yml：基础服务定义（MySQL、Elasticsearch等）
docker-compose.linux.yml：Linux平台优化配置
grafana/：监控面板配置

2. 启动完整依赖集群

# 启动所有依赖服务（首次运行会下载镜像，耗时约3-5分钟）
docker-compose -f develop/docker-compose/docker-compose.yml \
              -f develop/docker-compose/docker-compose.linux.yml up -d

# 查看服务状态（确保所有容器状态为Up）
docker-compose -f develop/docker-compose/docker-compose.yml ps

成功启动后将自动部署以下服务：

Temporal Server（默认端口7233）
Web UI（默认端口8088）
数据库：MySQL 8.0 + Elasticsearch 7.10
监控套件：Prometheus + Grafana

3. 访问Web管理界面

打开浏览器访问 http://localhost:8088，即可看到Temporal Web UI。首次登录无需认证，可直接查看集群状态、工作流执行历史和任务队列情况。

本地工具链配置（进阶开发）

1. 编译核心组件

Temporal提供Makefile自动化构建流程，执行以下命令编译服务器和工具：

# 查看所有可用构建目标
make help

# 编译核心二进制文件
make bins

# 输出产物说明
ls -lh temporal-server temporal-cassandra-tool tdbg

核心产物说明：

temporal-server：Temporal服务主程序
temporal-cassandra-tool：Cassandra数据库工具
tdbg：Temporal命令行调试工具
temporal-sql-tool：SQL数据库迁移工具

2. 初始化数据库 schema

根据选择的持久化存储类型，执行对应的schema初始化命令：

# MySQL8初始化（默认配置）
make install-schema-mysql8

# 或PostgreSQL初始化
make install-schema-postgresql12

# 或Cassandra初始化（配合Elasticsearch）
make install-schema-cass-es

⚠️ 数据库连接参数可通过环境变量调整，详细配置见config/development.yaml

3. 本地启动Temporal Server

# 使用默认配置启动
./temporal-server start --config config/development.yaml

# 或使用调试模式启动（含详细日志）
./temporal-server-debug start --config config/development.yaml

服务启动成功后，日志将显示：temporal server started，此时可通过http://localhost:7233访问gRPC API，通过http://localhost:8088访问Web UI。

环境验证与测试

1. 运行示例工作流

# 启动示例worker
go run ./service/worker/main.go

# 运行测试工作流
go run ./cmd/tools/tdbg/main.go wf start -w test-workflow -t default -wft hello-world

2. 查看工作流执行状态

通过Web UI或命令行工具验证工作流执行结果：

# 列出所有工作流
./tdbg wf list

# 查看工作流详情
./tdbg wf show -w <workflow-id>

常见问题解决

端口冲突处理

当提示"address already in use"错误时，修改配置文件中的端口映射：

# 在docker-compose.yml中修改冲突端口
services:
  mysql:
    ports:
      - "3307:3306"  # 将默认3306端口改为3307

依赖服务启动失败

查看容器日志定位具体错误：

# 查看服务日志
docker-compose -f develop/docker-compose/docker-compose.yml logs -f mysql

# 常见问题：Elasticsearch启动失败
# 解决：增加系统虚拟内存限制
sysctl -w vm.max_map_count=262144

编译错误处理

# 清除构建缓存
make clean

# 安装缺失依赖
go mod tidy

# 单独编译指定组件
make temporal-server

开发工具链优化

1. 配置IDE开发环境

推荐使用GoLand或VS Code+Go插件，导入项目后配置：

// .vscode/settings.json
{
  "go.buildTags": "disable_grpc_modules",
  "go.testTags": "test_dep",
  "go.toolsManagement.autoUpdate": true
}

2. 集成调试工具

# 安装Temporal CLI补全
tdbg completion bash > /etc/bash_completion.d/tdbg

# 配置Grafana监控面板
open http://localhost:3000/d/temporal-tbd/temporal-cluster-overview

总结与下一步

通过本文介绍的两种方案，你已成功搭建Temporal开发环境：

Docker方案适合快速上手和CI/CD环境
本地编译方案适合源码开发和调试

接下来你可以：

学习工作流开发教程
探索高级特性如重试策略、信号和查询
参与社区贡献，提交PR到GitHub仓库

如果觉得本文有帮助，请点赞收藏并关注作者，下期将带来"Temporal工作流设计模式实战"。遇到任何问题，欢迎在评论区留言讨论！

📚 扩展资源：

官方文档
API参考
测试用例

【免费下载链接】temporal Temporal service 项目地址: https://gitcode.com/gh_mirrors/te/temporal

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考