跳到主要内容

服务器运维

Dex Server 提供 FlowService API、协调持久化 Flow 执行，并提供 Dex Web API。将它作为 具有明确配置、健康检查和访问控制的托管生产服务来运行。

本地开发​

对于本地 stack，请安装 dexcli 并运行：

brew install superdurable/tap/dexcli
dexcli dev

这会启动 Dex Server 和 Dex Web 供本地使用。选项请参阅 CLI README。

生产部署形态​

  • 以带有 readiness 和 liveness check 的托管服务运行 Dex Server。
  • 为应用 client 和 Worker 提供稳定、经过认证的 server address。
  • 为大 payload 配置持久化 Blob Store。
  • 在需要可搜索投影时配置 MySQL 或 PostgreSQL Custom Attribute Store。
  • 只通过组织的认证访问路径发布 Dex Web。
  • 从每个 Server instance 收集日志和 Prometheus metrics。

独立部署 Server configuration 和应用 Worker 变更。Worker 发布可以改变 Flow 行为；在退役 定义前，使用应用运维中的 版本控制流程。

Server 组件​

dex-server 镜像默认在同一个 process 中启动 Dex Web、API 和 Interpreter。容器在 8801 端口提供 FlowService，在 8802 端口提供 Dex Web。是否发布任一端口仍由 deployment 显式决定。

使用 services 启动选项运行任意非空组件组合。当组件需要不同的 replica 数量或 resource limit 时，将它们分开部署：

dex-server start --services web
dex-server start --services api
dex-server start --services interpreter
dex-server start --services web,api

仅部署 Interpreter 时，必须将 interpreter.interpreterActivityConfig.internalServiceTarget 设置为 API service。 仅部署 Web 时不会连接 Temporal 或 Cadence。Web 会在 API upstream 可用前启动，因此 /healthz 只报告 Web process 的健康状态。在 FlowService 可用前，Web API request 会返回 upstream error。

配置​

Server 配置是 YAML 和有类型的 Go 配置。生产配置不同于 dexcli dev 接受的有限 flag。 将配置保存在已批准的 secret-management 和部署系统中，而不是应用镜像中。

Blob Store section 名为 blobStore。其中的 entry 使用 BlobStoreConfigEntry。 旧的 externalStorage key 不被接受。

在 web section 中配置 Web listener 和 API upstream：

web:
  bindAddress: 0.0.0.0
  port: 8802
  flowServiceTarget: dex-api:8801
  flowRenderingDirectory: ""

bind address 默认监听所有 interface，port 默认是 8802。空的 flowServiceTarget 使用 localhost 和已配置的 API port。Web connection 使用 plaintext gRPC，并复用 api.grpcMaxMessageBytes，因此应将其限制在可信 network path 内。

Blob Store​

在允许超过 inline limit 的 payload 前配置持久化 store。为每个环境使用独立凭据和 least-privilege policy。监控 write 和 read failure，并测试 credential rotation 后仍能读取 现有 object 的恢复流程。

Dex 默认将不超过 100 bytes 的 payload 保留在 history 中。101 bytes 的 string 或 encoded object 会被 offload。可通过 blobStore.thresholdInBytes 覆盖默认值。 比较时只计算 payload size，不计算最终 reference size。

blobStore:
  thresholdInBytes: 100
  objectIdLength: 10
  asyncStepInputSnapshotsEnabled: false
  supportedStorages:
    - status: active
      storageId: p1
      storageType: s3

由于每个 offloaded value 都会把 storageId 写入 durable history，请保持该值简短。例如， 在含义仍清楚时，用 p1 代替 production1。

应用必须将 Blob reference 视为 opaque value。其 wire format 为：

String: <storageId>|<YYMMDD>/<objectId>
Object: <storageId>|<YYMMDD>/<objectId>

示例：p1|260913/ab3de7kp2x

Value arm 用于区分 String 和 Object reference。Object Blob 保存完整的 EncodedObject， 其中包括 json、raw 或 custom encoding。reference 保留 storage ID 和 UTC write date， 但不保存 Flow ID 和 encoding。Dex 从可信的 request 或 Worker context 获取 owner Flow ID。 物理 object path 为：

<namespace>/<YYMMDD>$<base64url(flowId)>/<objectId>

两位年份表示 2000 到 2099 年。

internal reference 只属于一个 Flow。在 reference 跨越 Flow boundary 前，Dex 会先 hydrate， 再为目标 Flow 重写。目标 Flow 会收到 inline value，或收到存储在自身 Flow prefix 下的新 object。因此，删除源 Flow 不会损坏目标 Flow。public API 会拒绝客户端提交的 internal reference。

object ID 使用确定性的全小写 Base36 字符。同一个 invocation ID 和 stored bytes 的 retry 会 覆盖同一个 object，不会生成重复 object。Object stored bytes 包含 encoding。Dex 不执行 read-before-write、conditional create 或 collision retry。blobStore.objectIdLength 默认值为 10。0 表示使用默认值，负数无效，正数没有协议规定的范围。写入同一个 Blob Store namespace 的所有 Server 必须使用相同值，而且 Server 运行期间不能修改该值。 reader 接受任意非空的全小写 Base36 ID，因此 deployment 可在协调重启时修改配置长度。

10 位 Base36 提供约 51.7 bits。在单个 Flow 的单个 UTC day partition 内，10,000 个 object 至少发生一次碰撞的近似概率为 1.4 × 10⁻⁸；100,000 个时为 1.4 × 10⁻⁶；1,000,000 个时为 1.4 × 10⁻⁴。普通 deployment 使用 10。高吞吐 Flow 使用 12 或 16。长度 50 可以表达完整 SHA-256 值。更长的值只会增加前导零，不会增加 entropy。

cleanup 保留每个 Flow prefix 开头的 UTC date。它按字典序分页列出 prefix，describe 已编码 的 Flow 和可选 Run，并且只在 execution 已不存在时删除整个 prefix。随后使用返回的 continuation token 继续 list；该过程不使用 manifest。

ASYNC Step input snapshot 默认关闭。只有当 semantic history 必须保留成功的 ASYNC local Step method 收到的准确 input 时，才将 blobStore.asyncStepInputSnapshotsEnabled 设置为 true。snapshot 不受 payload offload threshold 影响，也不是 Flow execution、retry 或 recovery 所必需。关闭后，ASYNC local completion event 会将 input 标记为 unavailable。SYNC method 和 fallback 到 regular Activity 的 ASYNC method 仍会从 backend history 获得 input。

可选的 blobStore.blobCache 缓存 S3 支持的 Attribute object。非空 directory 会启用 它，并且只能属于一个 Server process。默认 budget 为 1 GiB。过大或被拒绝的 object 会 绕过 cache，继续访问源 Blob Store。损坏的 entry 会被失效并重新填充；初始化、恢复和 disk I/O error 是 Server error。local Blob Store object 和 Step-event input snapshot 不使用 此 cache。

Stream Store​

配置 streamStore 后可启用 best-effort Stream。单个本地 Server process 可以使用 memory backend。多个 Server process 需要共享 retained messages 时， 请使用 Redis 7 或更高版本。Redis backend 需要 redisURL。将 Redis 配置为 noeviction，使 capacity pressure 表现为可见的 Stream write failure。

maxMessageBytes 控制每条 serialized message 的大小，默认值为 100 KiB。 maxReadMessages 控制每个倒序分页的上限，默认值为 1000，并且必须为正数。Stream capacity 仍由各个已注册的 Stream definition 提供。其余 Stream Store 设置用于控制 approximate charging、trim watermark、trim batch、lease 和 worker concurrency。

Custom Attribute Store​

当关系型 projection 支持运维搜索或业务报表时，使用 Custom Attribute Store。请遵循 自定义 Attribute Store中的 schema 和 retry 要求。将其 数据库、凭据、migration 和 backup 作为 Dex deployment 的生产依赖。

Dex Web 访问控制​

Dex Web 可以显示 Flow input、output、Attribute 和 Worker stack trace。将它放在 TLS 以及 强制认证的 reverse proxy 或 gateway 后。按 role 授权生产访问，并将其限制给需要检查 Flow data 的 operator。

不要将 Dex Web 或 FlowService API 直接公开到公网上。使用 network policy、认证传输和 权限最小化的 service identity 保护 Server 和 Worker endpoint。按照你的 data-handling policy 审计对生产 Flow detail 的访问。