temporalio/gitpod-edu

Gitpod Temporal课程专用镜像文档

1. 镜像概述

Gitpod Temporal课程专用镜像是基于Gitpod云端IDE环境构建的预配置镜像，专为Temporal工作流平台课程设计。该镜像集成了Temporal开发、运行及学习所需的全套工具链与依赖环境，旨在简化Temporal课程学习者的环境搭建流程，实现"一键启动即开发"的学习体验。

2. 核心功能与特性

2.1 预配置Temporal环境

• 内置Temporal Server（包含服务端、Web UI及默认数据库）
• 预装Temporal CLI工具（tctl）及管理脚本
• 集成Temporal SDK开发依赖（支持Go、Java、Python、TypeScript等主流语言）

2.2 Gitpod深度集成

• 兼容Gitpod云端IDE标准工作流，支持通过Gitpod URL直接启动
• 自动配置Gitpod工作区目录映射，课程代码实时同步
• 内置Gitpod终端、代码编辑器及调试工具链

2.3 课程适配优化

• 预装Temporal官方课程示例代码及依赖库
• 标准化端口映射（Temporal Web UI: 8080，服务端口: 9093）
• 内置课程进度跟踪与环境验证脚本

2.4 版本兼容性

• 支持Temporal Server v1.20+主流稳定版本
• 兼容Gitpod最新工作区运行时环境
• 多语言SDK版本与Temporal Server自动匹配

3. 使用场景与适用范围

3.1 主要适用人群

• Temporal课程学习者（零基础入门至进阶开发者）
• Temporal技术讲师（统一教学环境配置）
• 企业内部Temporal培训（标准化学习环境）

3.2 典型使用场景

• 快速启动Temporal课程学习环境，无需本地配置
• 验证课程示例代码运行效果
• 开发与调试自定义Temporal工作流（基于课程案例扩展）
• 跨团队协作学习（统一环境避免"环境不一致"问题）

4. 使用方法与配置说明

4.1 快速启动（Gitpod云端环境）

通过Gitpod直接启动课程环境，需满足：

• 拥有Gitpod账号（支持GitHub/GitLab账号登录）
• 课程代码仓库已关联本镜像

操作步骤：

1. 访问课程代码仓库（如GitHub仓库）
2. 在仓库URL前添加 https://gitpod.io/#，例如：
   https://gitpod.io/#https://github.com/temporalio/course-example-repo
3. 等待Gitpod工作区初始化（首次启动约2-3分钟）
4. 初始化完成后，自动启动Temporal Server及课程环境

4.2 本地Docker部署（进阶用法）

如需在本地Docker环境运行（非Gitpod），需安装Docker Engine 20.10+。

4.2.1 基础运行命令

bash
docker run -d \
  --name gitpod-temporal-course \
  -p 8080:8080 \  # Temporal Web UI端口
  -p 9093:9093 \  # Temporal服务端口
  -e TEMPORAL_VERSION="1.22.0" \  # 指定Temporal版本
  -e ENABLE_EXAMPLES="true" \     # 启用课程示例代码
  temporalio/gitpod-course-image:latest

4.2.2 Docker Compose配置示例

创建 docker-compose.yml 文件：

yaml
version: '3.8'
services:
  temporal-course:
    image: temporalio/gitpod-course-image:latest
    container_name: gitpod-temporal-course
    ports:
      - "8080:8080"   # Web UI访问端口
      - "9093:9093"   # Temporal gRPC服务端口
      - "2222:22"     # SSH访问（可选，用于高级调试）
    environment:
      - TEMPORAL_VERSION=1.22.0
      - ENABLE_EXAMPLES=true
      - LOG_LEVEL=info
      - PERSISTENCE_TYPE=sqlite  # 本地开发默认使用SQLite
    volumes:
      - ./course-code:/workspace/course  # 本地课程代码映射（可选）
    restart: unless-stopped

启动服务：

bash
docker-compose up -d

4.3 配置参数说明

4.3.1 核心环境变量

4.3.2 高级配置（仅本地部署）

4.4 基本操作指南

4.4.1 访问Temporal Web UI

服务启动后，通过浏览器访问：
http://localhost:8080
（默认用户名/密码：无，本地部署无需认证）

4.4.2 运行课程示例代码

1. 进入容器终端：

   bash
   docker exec -it gitpod-temporal-course bash
   

2. 导航至示例代码目录：

   bash
   cd /workspace/course/examples
   

3. 运行指定语言示例（以Go为例）：

   bash
   go run ./hello-world/main.go
   

4.4.3 检查环境状态

执行内置环境验证脚本：

bash
/temporal/scripts/verify-env.sh

输出包含Temporal服务状态、SDK版本、端口占用等信息。

5. 常见问题

5.1 端口冲突

问题：启动时提示"端口8080已被占用"
解决：修改 WEB_UI_PORT 环境变量，例如 -e WEB_UI_PORT=8081，并映射对应宿主机端口。

5.2 示例代码未加载

问题：ENABLE_EXAMPLES=true 但未找到示例目录
解决：检查镜像版本是否为 latest，或手动拉取最新镜像：

bash
docker pull temporalio/gitpod-course-image:latest

5.3 Temporal Server启动失败

问题：日志显示"数据库连接失败"
解决：本地部署时若使用 postgres 持久化，需提前启动PostgreSQL服务并配置连接参数（通过 DB_HOST/DB_PORT 环境变量）。

6. 版本信息

• 镜像名称：temporalio/gitpod-course-image
• 最新稳定版：latest（对应Temporal Server v1.22.0）
• 版本标签规则：v{TEMPORAL_VERSION}-gitpod（如 v1.22.0-gitpod）