temporalio/admin-tools

Temporal Docker镜像文档

1. 镜像概述和主要用途

Temporal是一个基于"Workflow as Code (TM)"理念的分布式工作流编排平台，旨在帮助开发者构建和运行弹性应用。本Docker镜像封装了Temporal服务端组件，提供开箱即用的工作流引擎环境，支持工作流定义、执行、监控和管理全生命周期，使开发者能够专注于业务逻辑而非基础设施复杂性。

2. 核心功能和特性

2.1 工作流编排

• 支持复杂业务流程的声明式定义，基于代码（Go/Java/TypeScript等）描述工作流逻辑
• 自动处理工作流状态持久化，确保流程中断后可恢复

2.2 弹性与可靠性

• 内置重试机制与错误处理策略，支持自定义重试规则
• 分布式状态管理，避免单点故障导致的流程中断
• 基于事件的异步通信模型，适配不稳定网络环境

2.3 可观测性与调试

• 原生集成分布式追踪（Jaeger/Zipkin）
• 详细的工作流执行日志与状态查询接口
• 支持工作流历史记录导出与重放分析

2.4 可扩展性

• 微服务架构设计，支持按组件（Frontend/History/Matching）水平扩展
• 多租户隔离机制，支持多团队共享集群资源
• 兼容主流数据库（PostgreSQL/MySQL/Cassandra）作为持久化存储

3. 使用场景和适用范围

3.1 典型使用场景

• 微服务协调：跨服务事务编排、分布式锁管理、服务依赖协调
• 长时间运行流程：订单履约流程、数据同步任务、审批流程（支持天/月级运行时长）
• 异步任务处理：批量数据处理、定时任务调度、事件驱动型业务逻辑
• 故障恢复自动化：基础设施自愈、服务降级/恢复流程、数据备份与恢复

3.2 适用范围

• 开发者：构建可靠的分布式应用，简化状态管理与错误处理
• 企业级应用：***交易流程、供应链管理、客户服务自动化等关键业务系统
• 技术团队：需要降低分布式系统复杂性、提升系统容错能力的研发团队

4. 使用方法和配置说明

4.1 快速启动（docker run）

4.1.1 开发环境启动（默认配置）

bash
docker run -d \
  --name temporal \
  -p 7233:7233 \  # Frontend服务端口（客户端连接）
  -p 8088:8088 \  # Web管理界面端口
  temporalio/server:latest

说明：默认使用SQLite作为嵌入式数据库（仅开发环境），启动Frontend/History/Matching/Worker服务组件，Web界面访问地址：http://localhost:8088

4.1.2 生产环境基础配置（外部PostgreSQL）

bash
docker run -d \
  --name temporal \
  -p 7233:7233 \
  -p 8088:8088 \
  -e DB=postgresql \
  -e DB_PORT=5432 \
  -e DB_HOST=postgres-host \
  -e DB_USER=postgres-user \
  -e DB_PASSWORD=postgres-password \
  -e DB_NAME=temporal \
  -e SERVICES=frontend,history,matching \  # 生产环境通常拆分Worker服务
  temporalio/server:latest

4.2 Docker Compose配置（推荐生产环境）

yaml
version: '3.8'

services:
  postgres:
    image: docker.xuanyuan.run/postgres:14-alpine
    environment:
      POSTGRES_USER: temporal
      POSTGRES_PASSWORD: temporal
      POSTGRES_DB: temporal
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U temporal"]
      interval: 5s
      timeout: 5s
      retries: 5

  temporal:
    image: docker.xuanyuan.run/temporalio/server:latest
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      SERVICES: frontend,history,matching  # 核心服务组件
      DB: postgresql
      DB_HOST: postgres
      DB_PORT: 5432
      DB_USER: temporal
      DB_PASSWORD: temporal
      DB_NAME: temporal
      PORT: 7233  # Frontend服务端口
      WEB_PORT: 8088  # Web管理界面端口
      LOG_LEVEL: info  # 日志级别：debug/info/warn/error
    ports:
      - "7233:7233"
      - "8088:8088"
    volumes:
      - temporal-data:/etc/temporal/config

  temporal-admin-tools:
    image: docker.xuanyuan.run/temporalio/admin-tools:latest
    depends_on:
      - temporal
    environment:
      TEMPORAL_CLI_ADDRESS: temporal:7233
    command: tail -f /dev/null  # 保持容器运行，用于执行tctl命令

volumes:
  postgres-data:
  temporal-data:

启动命令：

bash
docker-compose up -d

4.3 配置参数说明

4.3.1 核心环境变量配置

5. 注意事项

• 数据持久化：生产环境必须使用外部数据库（PostgreSQL/MySQL）并挂载数据卷，避免容器重启导致数据丢失
• 资源要求：单节点部署建议至少2核CPU、4GB内存；生产集群需根据工作流吞吐量调整资源配置
• 版本兼容性：镜像标签建议使用具体版本（如1.22.0）而非latest，避免自动升级导致兼容性问题
• 安全配置：生产环境需启用TLS加密（通过TLS_CERT/TLS_KEY环境变量），并限制数据库访问权限
• 备份策略：定期备份数据库，Temporal工作流状态完全依赖数据库存储，需确保数据可恢复性