使用 Helm 在 Kubernetes 上部署 Mercure Hub：完整配置与源码级解析

Mercure 是一种允许服务器向浏览器及其他 HTTP 客户端实时推送数据更新的开放协议，具有便捷、快速、可靠且低功耗（battery-efficient）的特点。本篇文章以 charts 仓库中 stable/mercure 官方 Helm Chart 为核心，完整讲解如何在 Kubernetes 集群上通过 Helm 部署 Mercure Hub，逐项解读 Chart 暴露的全部配置参数（JWT 鉴权、传输层、超时、CORS、监控指标等），并结合 Chart 的模板源码说明每个参数如何落地为容器的环境变量与 Secret，帮助读者实现一套可复制、可调优的实时推送基础设施。

Chart 概览与废弃状态说明

在开始之前，需要先明确该 Chart 的当前状态：

• 仓库归档：charts 仓库自 2020 年 11 月 13 日起不再更新（见根目录的 Repo Archive Notice），helm/charts 官方仓库整体进入废弃归档流程。
• Chart 废弃：Chart.yaml 中deprecated: true，明确指出该 Chart 已废弃且不再维护。
• 版本信息：Chart 版本4.0.3，对应的应用版本appVersion: 0.10.0（即 Mercure Hub 镜像版本）；Chart 关键字为mercure、hub、push、streaming-api、async-api。

虽然 Chart 已废弃，但其整体结构完整、配置参数丰富，对于理解「如何将外部服务打包为 Kubernetes Helm Chart」以及「Mercure Hub 的部署与配置模型」仍有较高的参考价值。历史版本用户亦可据此进行升级与排障。

前置条件

根据 README.md，部署本 Chart 需要满足：

• Kubernetes 1.4+，且启用 Beta API（早期版本需要extensions/v1beta1等 Beta API 支持；Ingress 模板中通过semverCompare ">=1.14-0"判断使用networking.k8s.io/v1beta1还是extensions/v1beta1，见 ingress.yaml）。
• PV provisioner 支持：默认的 BoltDB 传输（transport）需要底层基础设施提供持久卷供给能力，用于保存历史数据。

安装与卸载 Chart

快速安装

使用默认配置安装（release 名称由 Helm 自动生成）：

$ helm install stable/mercure

指定 release 名称为my-release：

$ helm install --name my-release stable/mercure

该命令会以默认配置在集群中部署 Mercure Hub。可以使用helm list查看所有已安装的 release。

卸载

$ helm delete my-release

该命令会移除与 Chart 关联的所有 Kubernetes 组件，并删除该 release。

核心配置参数详解

README 提供了完整的可配置参数表，这也是本 Chart 的核心内容。以下按「Hub 功能参数」「安全与鉴权」「传输与超时」「镜像与部署」几个维度逐项展开。

Hub 核心功能参数

安全与 JWT 鉴权参数

传输与超时参数

镜像与部署参数

注意：README 中的参数表与 values.yaml 实际默认值存在少量差异（如image.tag、service.type、ingress.hosts），这是 README 未随版本同步所致。以 values.yaml 中的实际默认值为准。

此外，values.yaml 还包含两个 README 参数表之外的关键配置：

• backendConfig：enabled: false，timeoutSec: 30。GCP 负载均衡器默认在连接 30 秒后终止连接，可通过启用 backendConfig 并调整timeoutSec属性来解决（对应 Mercure 项目 issue #106 的场景）。
• replicaCount: 1：如果使用 BoltDB 传输（默认），replicaCount 必须为 1，因为 BoltDB 不支持多副本共享同一数据库文件。

两种参数配置方式

方式一：--set命令行参数

使用--set key=value[,key=value]为helm install指定参数。例如：

$ helm install --name my-release --set jwtKey=FooBar,corsAllowedOrigins=example.com stable/mercure

上述命令将 JWT 密钥设置为FooBar，并允许从example.com提供页面的客户端连接到 Hub。

方式二：-f指定 YAML 文件

将配置写入 YAML 文件后，通过-f参数传入：

$ helm install --name my-release -f values.yaml stable/mercure

完整的默认配置可直接参考 values.yaml，在此基础上进行覆盖即可。

源码级解析：配置参数如何注入容器

仅了解参数含义是不够的，还需要理解这些参数如何生效。本 Chart 通过ConfigMap + Secret + 环境变量三层机制完成配置下发。

布尔与列表参数的编码方式

configmap.yaml 将多数参数写入 ConfigMap：

• 布尔参数编码为"1"/"0"，例如allowAnonymous、subscriptions、metrics、debug、demo、compress、useForwardedHeaders；
• 列表参数（corsAllowedOrigins、publishAllowedOrigins）通过join " "以空格分隔拼成单个字符串；
• logFormat会被upper转为大写；
• 各类超时参数（heartbeatInterval、readTimeout、writeTimeout、dispatchTimeout）以字符串形式原样保留。

ConfigMap 还带有helm.sh/hook: pre-install,pre-upgrade与helm.sh/hook-delete-policy: before-hook-creation注解，确保在安装/升级前创建并在下次 hook 执行前删除重建。

敏感参数的 Secret 化与随机生成

secret.yaml 将敏感信息写入 Kubernetes Secret 并做 Base64 编码：

• transportUrl：直接编码；
• jwtKey：若未配置，自动用randAlphaNum 12生成 12 位随机字符串；
• metricsPassword：同样在未配置时随机生成 12 位字符串；
• publisherJwtKey、subscriberJwtKey、license：均编码写入。

这意味着：如果你在安装时未显式指定jwtKey，Helm 会为每个 release 生成独立的随机密钥，两个 release 之间互不通用——生产环境请务必通过--set jwtKey=...或 values 文件显式指定。

环境变量的注入方式

deployment.yaml 通过valueFrom将上述配置逐一注入容器环境变量：

• 常规参数（ALLOW_ANONYMOUS、METRICS、CORS_ALLOWED_ORIGINS、JWT_ALGORITHM等）来自configMapKeyRef；
• 敏感参数（TRANSPORT_URL、JWT_KEY、METRICS_PASSWORD、PUBLISHER_JWT_KEY、SUBSCRIBER_JWT_KEY、LICENSE）来自secretKeyRef。

环境变量名与参数名一一对应（如jwtAlgorithm→JWT_ALGORITHM），这些正是 Mercure Hub 镜像官方读取的环境变量命名规范，因此 Chart 参数与 Hub 容器能力完全对齐。此外 Deployment 上带有checksum/config与checksum/secret注解，配置变更时会自动触发 Pod 滚动更新，无需手动重启。

健康检查

Deployment 同时配置了livenessProbe与readinessProbe，均通过 HTTP GET 请求/healthz端口进行探测，保证 Hub 异常时能被自动重启或从 Service 端点摘除。

网络与外部访问

Service

service.yaml 定义 Service，默认类型ClusterIP、端口 80，targetPort: http。若启用backendConfig，Service 会附带 GCP BackendConfig 注解：

beta.cloud.google.com/backend-config: '{"default": "<release-name>-mercure"}'

同时 backend-config.yaml 会创建一个cloud.google.com/v1beta1的BackendConfig资源，用于调整负载均衡器的timeoutSec。

Ingress

ingress.yaml 在ingress.enabled: true时创建 Ingress：

• 根据集群版本自动选择networking.k8s.io/v1beta1（>= 1.14）或extensions/v1beta1API；
• 支持ingress.annotations、ingress.hosts（host + paths）与ingress.tls（secretName + hosts）配置。

访问地址获取

安装完成后，NOTES.txt 会根据部署形态给出访问指引：

• 启用 Ingress：直接输出http(s)://<host>/<path>；
• NodePort 类型：通过kubectl读取 NodePort 与节点 IP，输出http://$NODE_IP:$NODE_PORT；
• LoadBalancer 类型：提示等待外部 IP 就绪，可通过kubectl get svc -w观察状态，并输出http://$SERVICE_IP:<port>；
• ClusterIP 类型：使用kubectl port-forward <pod> 8080:80转发本地端口，访问http://127.0.0.1:8080。

安装验证

Chart 内置了连接性测试：tests/test-connection.yaml 创建一个 busybox Pod，通过wget访问<release>-mercure:<service.port>验证 Service 可达。安装后可执行：

$ helm test my-release

部署注意事项与最佳实践

综合 README、values.yaml 与模板源码，实际部署时建议重点关注以下几点：

1. 单副本约束：默认 BoltDB 传输不支持多副本，replicaCount必须保持为 1；如需横向扩容，需要切换到支持集群化的传输（transport）后端。
2. 显式指定 JWT 密钥：jwtKey默认随机生成，跨 release 不共享；生产环境务必显式设置，并可通过publisherJwtKey/subscriberJwtKey实现发布者与订阅者密钥分离（支持RS512等非对称算法）。
3. 匿名与订阅功能默认关闭：allowAnonymous、subscriptions默认false，按需开启，避免未授权订阅与额外 API 暴露。
4. 监控指标按需开启：metrics: true会暴露/metrics端点（OpenMetrics/Prometheus 格式），注意通过metricsLogin/metricsPassword保护，密码默认随机生成，需要提前从 Secret 中读取。
5. 反向代理场景：若 Hub 位于反向代理之后，启用useForwardedHeaders前必须确保代理覆盖/移除相关头，否则存在 IP 伪造风险。
6. GCP 负载均衡：若使用 GKE，建议启用backendConfig并适当调大timeoutSec（默认 30s 会断开长连接），避免实时推送连接被过早终止。
7. 长连接超时：SSE 长连接场景下，writeTimeout默认 60s，dispatchTimeout默认 5s，heartbeatInterval默认0s；可根据实际网络与代理环境调整，必要时将readTimeout/writeTimeout设为0s以禁用超时。

小结

通过本文，读者可以掌握从helm install stable/mercure到精细调优的完整链路：理解每个配置参数的语义与默认值，了解 JWT 鉴权、BoltDB 传输、监控与 CORS 等核心能力的启用方式，并借助模板源码厘清「values 参数 → ConfigMap/Secret → 容器环境变量」的配置下发机制。尽管该 Chart 已随 charts 仓库归档废弃，但其参数模型与 Helm 模板组织方式，对部署 Mercure Hub 及编写同类服务型 Chart 仍具有直接的参考价值。