服务注册与分布式协调 / 系统课时

保护连接与 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 连接安全与 Payload 保护边界

配置 Temporal Cloud 连接

Temporal Cloud 通常使用 TLS 保护 gRPC 连接,并通过 API Key 进行客户端认证。API Key 应放在环境变量或密钥管理系统中,不应直接写进源码、镜像或 Workflow 输入。

ts
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');

预期结果

text
Temporal connection established

这里的 <HOST> 应替换为实际 Temporal Cloud Endpoint。生产环境不要把 API Key 写入日志,也不要把它作为 Activity 参数传递,否则可能进入 Workflow History 或业务观测数据。

自建环境使用 TLS 与 mTLS

自建 Temporal Service 是否启用 TLS、是否要求客户端证书,需要与服务端 gRPC TLS 配置保持一致。仅客户端打开 TLS 而服务端未按相同方式配置,会表现为握手或连接失败;启用 mTLS 时还必须让服务端信任客户端证书的签发链。

ts
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');

预期结果

text
mTLS connection configured

这是客户端配置示例,证书文件、私钥权限、服务端信任链和证书名称校验都依赖你的基础设施配置。私钥应通过 Secret、KMS 或等价密钥管理能力注入,不能提交到 Git。

用 Data Converter 与 Payload Codec 保护敏感字段

Temporal SDK 的 Data Converter 负责把语言对象转换为 Payload;Payload Codec 可以在序列化后的 Payload 上进一步执行压缩、加密等处理。常见安全设计是保持普通数据使用默认 Converter,而对敏感业务数据统一经过加密 Codec。

ts
import { DefaultDataConverter } from '@temporalio/common';

// 片段示例:CustomPayloadCodec 需由应用按组织的 KMS/加密方案实现。
const secureDataConverter = new DefaultDataConverter({
  payloadCodecs: [new CustomPayloadCodec()],
});

console.log('secure Data Converter ready');

预期结果

text
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 的编码链路使用了明确的加密策略。做到这三层,才能同时降低链路被窃听和业务历史数据泄露的风险。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

保护连接与 Payload 数据

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通