Hatchet Lite 中 gRPC 广播地址配置问题解析

问题背景

在使用 Hatchet Lite 进行小型项目部署时，开发者遇到了一个关于 gRPC 广播地址配置的问题。虽然设置了 SERVER_GRPC_BROADCAST_ADDRESS 环境变量，但生成的令牌仍然指向 localhost 地址，这影响了跨容器通信的能力。

技术分析

令牌生成机制

Hatchet Lite 生成的 JWT 令牌包含多个关键字段，其中与连接相关的包括：

• grpc_broadcast_address: 指定 gRPC 服务端地址
• server_url: HTTP API 服务地址
• aud 和 iss: 认证相关字段

从实际生成的令牌内容来看，虽然 grpc_broadcast_address 正确反映了配置的主机名（如 hatchet-engine:7077），但其他字段仍保持 localhost 地址。

环境变量配置

在 Docker Compose 配置中，关键的环境变量包括：

• SERVER_GRPC_BROADCAST_ADDRESS: 定义 gRPC 服务的广播地址
• SERVER_URL: 定义 HTTP API 服务地址
• SERVER_GRPC_BIND_ADDRESS: 定义 gRPC 服务绑定地址

跨容器通信问题

当 worker 服务运行在独立容器中时，需要确保：

1. 网络配置正确（使用同一 bridge 网络）
2. 主机名解析正确
3. 令牌中的地址能被容器解析

解决方案

1. 验证令牌内容：检查 JWT 令牌中的 grpc_broadcast_address 字段，确认是否包含预期的主机名

2. 环境变量一致性：确保所有相关环境变量使用相同的主机名配置

   • 将 SERVER_URL 也更新为容器可解析的地址

3. 网络配置检查：

   • 确认所有服务连接到同一 Docker 网络
   • 验证主机名解析是否正常

4. 配置持久化检查：

   • 检查 /config/server.yaml 文件中的 runtime.grpcBroadcastAddress 值
   • 确保没有旧配置覆盖环境变量

最佳实践

1. 对于容器化部署，建议使用服务名称作为主机名
2. 保持 HTTP 和 gRPC 地址配置的一致性
3. 在开发环境中，可以适当降低日志级别以便调试
4. 使用健康检查确保服务依赖关系正确

总结

这个问题实际上反映了容器化环境中服务发现的常见挑战。虽然初始看起来是配置问题，但深入分析后发现令牌本身已包含正确的主机名信息，真正的问题可能出在运行环境对主机名的解析上。通过系统性地检查网络配置和环境变量，可以确保 Hatchet Lite 在容器化环境中正常工作。