服务注册与分布式协调 / 系统课时
启动本地 Temporal 开发服务
启动本地 Temporal 开发服务
本篇用 Temporal CLI 启动一套供 Go 示例使用的本地开发服务,并从 CLI、服务端口、健康检查、默认 Namespace 和 Web UI 五个方面完成验收。完成后,后续 Worker 和 Client 可以统一连接本机 Temporal 服务。
学习目标
- 使用 Temporal CLI 启动本地开发服务和 Web UI
- 确认默认服务端口、健康状态与
defaultNamespace - 根据启动和连接错误快速定位 CLI、端口与运行环境问题
前置检查
开始前需要已经安装 Temporal CLI,并确保 temporal 可执行文件位于当前终端的 PATH 中。先检查 CLI 是否能够正常执行:
temporal --version预期输出
temporal version <CLI_VERSION> (Server <SERVER_VERSION>, UI <UI_VERSION>)实际版本号会随安装时间变化。只要命令能够正常输出版本信息,就说明当前终端已经可以调用 Temporal CLI;如果提示找不到命令,应先修复安装路径或重新打开终端。
启动服务并确认端口
在一个独立终端中启动开发服务器:
temporal server start-dev预期输出
CLI <CLI_VERSION> (Server <SERVER_VERSION>, UI <UI_VERSION>)
Server: localhost:7233
UI: http://localhost:8233启动日志的附加字段可能随 CLI 版本变化,但默认环境应能够确认两项核心地址:Temporal Frontend 服务监听 localhost:7233,Web UI 使用 http://localhost:8233。保持这个终端运行,后续验证命令在另一个终端执行。
start-dev 面向本地开发,会自动准备可立即使用的 Temporal 服务和 default Namespace。默认数据主要用于开发验证,不要把这套启动方式当作生产部署方案;如果后续实验需要跨进程重启保留数据,可以再了解 --db-filename 持久化选项。
验证服务健康状态和 Namespace
仅看到进程存在还不够,应该通过 Temporal 自身的健康接口确认 Frontend 已经能够响应。打开第二个终端执行:
temporal operator cluster health预期输出
SERVINGSERVING 表示 CLI 已经能够通过默认地址连接 Temporal Frontend。若此处出现 connection refused,优先检查启动服务的终端是否仍在运行,以及客户端是否确实连接 localhost:7233。
接着确认开发服务器已经准备好默认 Namespace:
temporal operator namespace describe --namespace default预期输出
NamespaceInfo.Name default
NamespaceInfo.Id <ID><ID> 是环境动态生成的 Namespace ID,实际值不同属于正常现象。验证重点是命令成功,并且返回的 Namespace 名称为 default。
打开 Web UI 并完成验收
在浏览器访问 http://localhost:8233。新启动的环境还没有运行任何业务 Workflow,因此执行列表为空是正常现象;确认页面能够加载并且可以看到 default Namespace 即可。
此时本地环境应同时满足三个条件:CLI 健康检查返回 SERVING,default Namespace 可以查询,浏览器能够访问 8233 端口。后续 Go Client 和 Worker 默认连接 localhost:7233 时,就会进入这一套开发环境。
处理常见启动失败
如果 temporal server start-dev 提示端口被占用,通常是之前的开发服务仍未退出,或本机其他程序占用了 7233、8233。优先停止旧进程;确实需要并存时,可以分别通过 --port 和 --ui-port 调整服务端与 UI 端口,并保证后续 Client 使用相同地址。
如果 CLI 在 Docker 容器中运行,而浏览器需要从宿主机访问,容器内的 localhost 只代表容器自身。此时除了发布 7233 和 8233 端口,还需要让开发服务监听容器外可访问的地址,例如使用 --ip 0.0.0.0。普通本机安装不需要这个额外设置。
当版本检查、SERVING、default Namespace 和 Web UI 四项都通过后,本地 Temporal 基线就已经建立完成;后续代码出现连接问题时,应先回到这四项检查,再继续排查 Worker、Task Queue 或 Workflow 实现。