Temporal Server Docker 镜像文档

镜像概述和主要用途

Temporal Server 镜像是用于生产环境部署的核心组件，需连接外部数据库（支持 Cassandra、MySQL 或 PostgreSQL，默认 Cassandra）。若需部署包含预配置数据库的 Temporal，可参考 auto-setup 镜像。此外，Temporal 可选支持 Elasticsearch 以实现可见性功能。更多 docker-compose 示例可参考 docker-compose GitHub 仓库。

核心功能和特性

多数据库支持：兼容 Cassandra、MySQL 8、PostgreSQL 12 作为后端存储
Elasticsearch 集成：可选配置 Elasticsearch 实现工作流可见性，支持主/ secondary 索引
灵活的网络配置：支持绑定 IP、广播地址设置，适配代理或多网络环境
安全增强：全面的 TLS 配置（证书刷新、过期检查、客户端认证），支持 JWT 权限控制
监控集成：支持 statsd 和 Prometheus 指标导出，便于 observability
动态配置：通过 YAML 文件自定义服务参数，支持运行时调整
多服务端口管理：独立配置前端、匹配、历史、工作器服务的网络端口

使用场景和适用范围

生产环境部署：适用于需要稳定运行工作流引擎的企业级应用
复杂工作流管理：支持长期运行、状态ful的工作流编排，如微服务协调、数据处理管道
多数据库环境：可适配现有 Cassandra、MySQL 或 PostgreSQL 集群
可见性需求：需通过 Elasticsearch 实现工作流实例搜索、过滤和监控的场景
高可用架构：支持多节点部署，配合外部数据库实现数据持久化和故障恢复

详细使用方法和配置说明

环境变量配置

通用环境变量

名称	描述	默认值
`DB`	指定连接的数据库类型，允许值：`cassandra`、`mysql8`、`postgres12`	`cassandra`

Cassandra 环境变量

名称	描述	默认值
`KEYSPACE`	Cassandra 键空间名称	`temporal`
`CASSANDRA_SEEDS`	Cassandra 主机名	未设置
`CASSANDRA_PORT`	Cassandra 连接端口	9042
`CASSANDRA_USER`	Cassandra 用户名	未设置
`CASSANDRA_PASSWORD`	Cassandra 密码	未设置
`CASSANDRA_TLS_ENABLED`	是否启用 TLS 连接 Cassandra	`false`
`CASSANDRA_CERT`	TLS 证书文件路径（若启用 TLS）	未设置
`CASSANDRA_CERT_DATA`	以数据形式传入 TLS 证书（替代文件路径）	未设置
`CASSANDRA_CERT_KEY`	TLS 证书密钥文件路径（若启用 TLS）	未设置
`CASSANDRA_CERT_KEY_DATA`	以数据形式传入 TLS 证书密钥（替代文件路径）	未设置
`CASSANDRA_CA`	CA 证书文件路径（若需要）	未设置
`CASSANDRA_CA_DATA`	以数据形式传入 CA 证书（替代文件路径）	未设置
`CASSANDRA_HOST_VERIFICATION`	是否启用 Cassandra 主机验证	`false`
`CASSANDRA_HOST_NAME`	Cassandra 数据库主机名	未设置
`CASSANDRA_ADDRESS_TRANSLATOR`	地址转换器接口，用于将 Cassandra 节点 IP 转换为本地可访问地址	未设置
`CASSANDRA_ADDRESS_TRANSLATOR_OPTIONS`	地址转换器选项，参考文档	未设置

MySQL/PostgreSQL 环境变量

名称	描述	默认值
`DBNAME`	主数据库名称	`temporal`
`VISIBILITY_DBNAME`	可见性数据库名称（独立于主数据库）	`temporal_visibility`
`VISIBILITY_DB_PORT`	可见性数据库连接端口	MySQL: 3306，PostgreSQL: 5432
`VISIBILITY_MYSQL_SEEDS`	MySQL 可见性数据库主机名	未设置
`VISIBILITY_MYSQL_USER`	MySQL 可见性数据库用户名	未设置
`VISIBILITY_MYSQL_PWD`	MySQL 可见性数据库密码	未设置
`VISIBILITY_POSTGRES_SEEDS`	PostgreSQL 可见性数据库主机名	未设置
`VISIBILITY_POSTGRES_USER`	PostgreSQL 可见性数据库用户名	未设置
`VISIBILITY_POSTGRES_PWD`	PostgreSQL 可见性数据库密码	未设置
`DB_PORT`	主数据库连接端口	MySQL: 3306，PostgreSQL: 5432
`MYSQL_SEEDS`	MySQL 主机名	未设置
`MYSQL_USER`	MySQL 用户名	未设置
`MYSQL_PWD`	MySQL 密码	未设置
`MYSQL_TX_ISOLATION_COMPAT`	启用 MySQL 5.7.20 之前版本兼容性	`false`
`SQL_VIS_MAX_CONNS`	可见性数据库最大活跃连接数	`10`
`SQL_VIS_MAX_IDLE_CONNS`	可见性数据库最大空闲连接数	`10`
`SQL_VIS_MAX_CONN_TIME`	可见性数据库连接最大存活时间	`1h`
`SQL_MAX_CONNS`	主数据库最大活跃连接数	`20`
`SQL_MAX_IDLE_CONNS`	主数据库最大空闲连接数	`20`
`SQL_MAX_CONN_TIME`	主数据库连接最大存活时间	`1h`
`SQL_TLS_ENABLED`	是否启用 SQL 数据库 TLS 连接	`false`
`SQL_CA`	SQL 数据库 CA 证书路径	未设置
`SQL_CERT`	SQL 数据库证书路径	未设置
`SQL_CERT_KEY`	SQL 数据库证书密钥路径	未设置
`SQL_HOST_VERIFICATION`	是否启用 SQL 主机验证	`false`
`SQL_HOST_NAME`	TLS 连接时验证的主机名	未设置
`POSTGRES_SEEDS`	PostgreSQL 主机名	未设置
`POSTGRES_USER`	PostgreSQL 用户名	未设置
`POSTGRES_PWD`	PostgreSQL 密码	未设置
`POSTGRES_TLS_ENABLED`	是否启用 PostgreSQL TLS 连接	`false`
`POSTGRES_TLS_DISABLE_HOST_VERIFICATION`	是否跳过 PostgreSQL 主机验证（如 Amazon RDS 环境）	`false`
`POSTGRES_TLS_CERT_FILE`	PostgreSQL TLS 证书文件路径	未设置
`POSTGRES_TLS_KEY_FILE`	PostgreSQL TLS 证书密钥文件路径	未设置
`POSTGRES_TLS_CA_FILE`	PostgreSQL TLS CA 证书文件路径	未设置
`POSTGRES_TLS_SERVER_NAME`	PostgreSQL TLS 服务器主机名	未设置

Elasticsearch 环境变量

名称	描述	默认值
`ENABLE_ES`	是否启用 Elasticsearch	`false`
`ES_SCHEME`	Elasticsearch 连接协议，允许值：`http`、`https`	`http`
`ES_SEEDS`	Elasticsearch 节点列表（逗号分隔）	未设置
`ES_PORT`	Elasticsearch 连接端口	`9200`
`ES_USER`	Elasticsearch 用户名	未设置
`ES_PWD`	Elasticsearch 密码	未设置
`ES_VERSION`	Elasticsearch 版本	`v7`
`ES_VIS_INDEX`	可见性索引名称	`temporal_visibility_v1_dev`
`ES_SEC_VIS_INDEX`	secondary 可见性索引名称	未设置

服务器配置环境变量

名称	描述	默认值
`BIND_ON_IP`	前端服务绑定 IP 地址	`127.0.0.1`（本地主机）
`TEMPORAL_BROADCAST_ADDRESS`	客户端连接 IP 与 `BIND_ON_IP` 不同时需指定（如监听 0.0.0.0 或使用代理）	未设置
`PPROF_PORT`	启用 pprof 调试的端口	`0`（禁用）
`TEMPORAL_TLS_REFRESH_INTERVAL`	TLS 证书刷新间隔	`0s`（不刷新）
`TEMPORAL_TLS_EXPIRATION_CHECKS_CHECK_INTERVAL`	TLS 证书过期检查间隔	`0s`（不检查）
`TEMPORAL_TLS_EXPIRATION_CHECKS_WARNING_WINDOW`	证书过期警告窗口时间	`0s`
`TEMPORAL_TLS_EXPIRATION_CHECKS_ERROR_WINDOW`	证书过期错误窗口时间	`0s`
`TEMPORAL_TLS_REQUIRE_CLIENT_AUTH`	是否要求客户端（Worker、CLI、SDK）通过 TLS 认证	`false`
`TEMPORAL_TLS_SERVER_CERT`	服务器 TLS 证书路径	未设置
`TEMPORAL_TLS_SERVER_CERT_DATA`	服务器 TLS 证书数据（替代文件路径）	未设置
`TEMPORAL_TLS_SERVER_KEY`	服务器 TLS 证书密钥路径	未设置
`TEMPORAL_TLS_SERVER_KEY_DATA`	服务器 TLS 证书密钥数据（替代文件路径）	未设置
`TEMPORAL_TLS_SERVER_CA_CERT`	服务器 CA 证书路径	未设置
`TEMPORAL_TLS_SERVER_CA_CERT_DATA`	服务器 CA 证书数据（替代文件路径）	未设置
`TEMPORAL_TLS_INTERNODE_DISABLE_HOST_VERIFICATION`	是否跳过节点间（历史/匹配服务）主机验证	`false`
`TEMPORAL_TLS_INTERNODE_SERVER_NAME`	节点间 TLS 验证的主机名	未设置
`TEMPORAL_TLS_FRONTEND_CERT`	前端服务 TLS 证书路径	未设置
`TEMPORAL_TLS_FRONTEND_CERT_DATA`	前端服务 TLS 证书数据（替代文件路径）	未设置
`TEMPORAL_TLS_FRONTEND_KEY`	前端服务 TLS 证书密钥路径	未设置
`TEMPORAL_TLS_FRONTEND_KEY_DATA`	前端服务 TLS 证书密钥数据（替代文件路径）	未设置
`TEMPORAL_TLS_FRONTEND_DISABLE_HOST_VERIFICATION`	前端服务是否跳过主机验证	`false`
`TEMPORAL_TLS_FRONTEND_SERVER_NAME`	前端服务 TLS 验证的主机名	未设置
`TEMPORAL_TLS_CLIENT1_CA_CERT`	前端服务向外部客户端展示的 TLS 证书	未设置
`TEMPORAL_TLS_CLIENT1_CA_CERT_DATA`	客户端 TLS 证书数据（替代文件路径）	未设置
`TEMPORAL_TLS_CLIENT2_CA_CERT`	额外客户端 TLS 证书	未设置
`TEMPORAL_TLS_CLIENT2_CA_CERT_DATA`	额外客户端 TLS 证书数据（替代文件路径）	未设置
`STATSD_ENDPOINT`	statsd 监控端点	未设置
`PROMETHEUS_ENDPOINT`	Prometheus 指标暴露端点（用于数据采集）	未设置
`PROMETHEUS_TIMER_TYPE`	Prometheus 计时器指标类型，参考文档	`histogram`
`TEMPORAL_AUTH_AUTHORIZER`	授权插件配置	未设置
`TEMPORAL_AUTH_CLAIM_MAPPER`	ClaimMapper 插件配置	未设置
`TEMPORAL_JWT_KEY_SOURCE1`	ClaimMapper JWT 密钥源	未设置
`TEMPORAL_JWT_KEY_SOURCE2`	额外 JWT 密钥源	未设置
`TEMPORAL_JWT_KEY_REFRESH`	JWT 密钥刷新间隔	`1m`
`TEMPORAL_JWT_PERMISSIONS_CLAIM`	JWT 权限声明属性名	`permissions`
`FRONTEND_GRPC_PORT`	前端服务 GRPC 端口	`7233`
`FRONTEND_HTTP_PORT`	前端服务 HTTP 端口	`7243`
`FRONTEND_MEMBERSHIP_PORT`	前端服务成员端口	`6933`
`INTERNAL_FRONTEND_GRPC_PORT`	内部前端服务 GRPC 端口	`7236`
`INTERNAL_FRONTEND_MEMBERSHIP_PORT`	内部前端服务成员端口	`6936`
`MATCHING_GRPC_PORT`	匹配服务 GRPC 端口	`7235`
`MATCHING_MEMBERSHIP_PORT`	匹配服务成员端口	`6935`
`HISTORY_GRPC_PORT`	历史服务 GRPC 端口	`7234`
`HISTORY_MEMBERSHIP_PORT`	历史服务成员端口	`6934`
`WORKER_GRPC_PORT`	工作器服务 GRPC 端口	`7239`
`WORKER_MEMBERSHIP_PORT`	工作器服务成员端口	`6939`
`USE_INTERNAL_FRONTEND`	是否部署内部前端服务（部分认证配置需要）	未设置
`PUBLIC_FRONTEND_ADDRESS`	覆盖从 `BIND_ON_IP` 和 `FRONTEND_GRPC_PORT` 推导的公网前端地址	未设置
`DYNAMIC_CONFIG_FILE_PATH`	动态配置 YAML 文件路径	`/etc/temporal/config/dynamicconfig/docker.yaml`

部署示例

1. Docker Run 命令（连接 PostgreSQL）

bash
docker run -d \
  --name temporal-server \
  -p 7233:7233 \
  -e DB=postgres12 \
  -e POSTGRES_SEEDS=postgres-host \
  -e POSTGRES_USER=temporal \
  -e POSTGRES_PWD=temporal-password \
  -e DBNAME=temporal \
  -e VISIBILITY_DBNAME=temporal_visibility \
  -e BIND_ON_IP=0.0.0.0 \
  temporalio/server:latest