服务注册与分布式协调 / 系统课时
保护连接与 Payload 数据
保护连接与 Payload 数据
本课解决生产环境中 Temporal 连接凭证和 Workflow/Activity Payload 暴露的问题,最终让客户端通过 API Key 或 TLS/mTLS 安全接入,并用 Data Converter 与 Payload Codec 保护敏感业务字段。
学习目标
- 能区分 API Key、TLS 与 mTLS 分别解决的安全问题
- 能为 Temporal 客户端配置安全连接
- 能判断 Data Converter、Payload Codec 与服务端存储之间的保护边界
先划清两类保护边界
连接安全与业务数据保护不是同一件事。API Key 负责客户端身份认证;TLS 负责传输链路机密性与完整性;mTLS 在 TLS 基础上增加客户端证书校验。它们保护的是“谁能连接”和“数据怎样传输”。
Payload 安全解决的是另一层问题:Workflow 输入、Activity 参数、事件历史中的 Payload 可能包含订单号、邮箱、令牌或其他敏感字段。仅启用 TLS 并不等于这些数据在 Temporal 持久化和运维观察链路中已经被加密。

配置 Temporal Cloud 连接
Temporal Cloud 通常使用 TLS 保护 gRPC 连接,并通过 API Key 进行客户端认证。API Key 应放在环境变量或密钥管理系统中,不应直接写进源码、镜像或 Workflow 输入。
import { Connection } from '@temporalio/client';
const apiKey = process.env.TEMPORAL_API_KEY;
if (!apiKey) throw new Error('TEMPORAL_API_KEY is required');
const connection = await Connection.connect({
address: process.env.TEMPORAL_ADDRESS ?? '<HOST>:7233',
tls: true,
apiKey,
});
console.log('Temporal connection established');预期结果
Temporal connection established这里的 <HOST> 应替换为实际 Temporal Cloud Endpoint。生产环境不要把 API Key 写入日志,也不要把它作为 Activity 参数传递,否则可能进入 Workflow History 或业务观测数据。
自建环境使用 TLS 与 mTLS
自建 Temporal Service 是否启用 TLS、是否要求客户端证书,需要与服务端 gRPC TLS 配置保持一致。仅客户端打开 TLS 而服务端未按相同方式配置,会表现为握手或连接失败;启用 mTLS 时还必须让服务端信任客户端证书的签发链。
import { Connection } from '@temporalio/client';
import fs from 'node:fs';
const connection = await Connection.connect({
address: process.env.TEMPORAL_ADDRESS ?? '<HOST>:7233',
tls: {
caCert: fs.readFileSync('<PATH>/ca.pem'),
clientCertPair: {
crt: fs.readFileSync('<PATH>/client.pem'),
key: fs.readFileSync('<PATH>/client-key.pem'),
},
},
});
console.log('mTLS connection configured');预期结果
mTLS connection configured这是客户端配置示例,证书文件、私钥权限、服务端信任链和证书名称校验都依赖你的基础设施配置。私钥应通过 Secret、KMS 或等价密钥管理能力注入,不能提交到 Git。
用 Data Converter 与 Payload Codec 保护敏感字段
Temporal SDK 的 Data Converter 负责把语言对象转换为 Payload;Payload Codec 可以在序列化后的 Payload 上进一步执行压缩、加密等处理。常见安全设计是保持普通数据使用默认 Converter,而对敏感业务数据统一经过加密 Codec。
import { DefaultDataConverter } from '@temporalio/common';
// 片段示例:CustomPayloadCodec 需由应用按组织的 KMS/加密方案实现。
const secureDataConverter = new DefaultDataConverter({
payloadCodecs: [new CustomPayloadCodec()],
});
console.log('secure Data Converter ready');预期结果
secure Data Converter ready真正的 CustomPayloadCodec 至少需要定义编码与解码两条路径,并处理密钥轮换、密钥标识、认证标签校验和解密失败。推荐使用成熟的 AEAD 算法,例如 AES-GCM;密钥本身放在 KMS 或 Secret Manager,不要随 Payload 一起传输。
选择保护方案的边界
API Key 与 mTLS 解决的是服务访问控制;TLS 解决网络窃听和篡改;Payload Codec 解决 Payload 在 Temporal 数据生命周期中的进一步保护。三者可以同时使用,不能互相替代。
还要特别区分“加密 Payload”和“字段脱敏”。加密适合需要原样恢复的数据;脱敏适合日志、指标和人工排障仍需展示部分信息的场景。无论采用哪种方案,都应避免把长期凭证、支付密钥等不应进入 Workflow History 的秘密放进 Workflow 参数。
生产验收时至少确认三件事:连接使用了预期的 TLS/mTLS 方式,凭证不出现在源码与日志中,敏感 Payload 的编码链路使用了明确的加密策略。做到这三层,才能同时降低链路被窃听和业务历史数据泄露的风险。