XHIM Server Kubernetes / Helm 高可用部署

这是 XHIM Enterprise/OEM 的服务端 Helm Chart。它只部署无状态 XHIM Server Pod，生产 PostgreSQL、S3 对象存储、Push Provider、Ingress 和 Secret Manager 由客户基础设施提供，不把数据库或明文密钥偷塞进 Chart。

1. 已实现的高可用边界

默认 3 副本，滚动升级 maxUnavailable=0 / maxSurge=1；
PodDisruptionBudget 默认 minAvailable=2；
跨 Zone/主机 Topology Spread 与 Pod Anti-Affinity；
可选 HPA（CPU + 内存），最小副本不少于 3；
startup/readiness/liveness 分离，依赖 PostgreSQL/S3 不可用时不接流量；
pre-install,pre-upgrade 迁移 Job，专用 xhim-migrate 进程执行内置 Migration；PostgreSQL advisory lock 保证重放/并发仍为单实例；
PostgreSQL Bus 完成跨 Pod WebSocket/Presence/Typing/Custom Signal 路由；
只读根文件系统、non-root、禁止 privilege escalation、丢弃所有 Linux capabilities；
默认 NetworkPolicy 只接受同 Namespace 入站，对外 PostgreSQL/S3/ Push/Webhook 出站在客户确认 CIDR 后再收紧。

replicaCount >= 2 是 Schema 强制约束。Chart 渲染通过不等于已完成生产高可用验收；还必须在客户集群完成节点驱逐、Zone 断网、 PostgreSQL 主备切换、S3 故障、WebSocket 重连和 RPO/RTO 演练。

2. 前置依赖

Kubernetes 1.27+；
Helm 3.14+；
可通过 Digest 拉取的 XHIM Server 镜像；
PostgreSQL 16+（推荐托管高可用集群）；
私有 S3/S3-compatible Bucket；
Push Webhook 或 APNs/FCM/Huawei 直连凭证；
已签名 license.json 与 revocations.json；
Ingress Controller 和 TLS 证书。

3. Secret 合同

Chart 不创建 Secret。secrets.existingSecret 指向的 Secret 以 XHIM 环境变量为 Key，至少包含：

text

XHIM_DATABASE_URL
XHIM_ADMIN_KEY
XHIM_BUSINESS_API_KEY                    # 启用 /v1/server/* 时
XHIM_ADMIN_USERNAME
XHIM_ADMIN_PASSWORD_BCRYPT_BASE64
XHIM_ADMIN_SESSION_KEY_BASE64
XHIM_SIGNING_PRIVATE_KEY_BASE64
XHIM_SIGNING_VERIFY_KEYS_BASE64
XHIM_CURSOR_KEY_BASE64
XHIM_LICENSE_VERIFY_KEYS_BASE64
XHIM_PUSH_WEBHOOK_TOKEN                 # webhook 模式
XHIM_RTC_TOKEN_KEY_BASE64
AWS_ACCESS_KEY_ID                       # 或 Workload Identity
AWS_SECRET_ACCESS_KEY                   # 或 Workload Identity

Push 直连、事后 Webhook 或前置策略 Webhook 启用时，再按 XHIM Server 环境变量补齐对应密钥。

license.existingSecret 指向的 Secret 必须有两个文件 Key：

text

license.json
revocations.json

使用 External Secrets Operator、Sealed Secrets 或云厂商 Workload Identity 完成注入。如果只能手工初始化，先在离线终端生成 0600 权限的 env 文件，再执行 kubectl create secret generic --from-env-file=...，完成后立即安全删除临时文件。不要把明文写到 values.yaml、Shell 历史、 Git 或 CI 日志。

4. 生产 Values

复制默认 Values 到客户受控配置库，至少替换：

yaml

image:
  repository: registry.customer.example/xhim/server
  tag: "1.0.0"
  digest: sha256:REPLACE_WITH_IMMUTABLE_DIGEST

ingress:
  enabled: true
  className: nginx
  host: im.customer.example
  tls:
    - secretName: xhim-ingress-tls
      hosts: [im.customer.example]

config:
  deploymentID: customer-production-1
  defaultAppID: com.customer.im
  allowedOrigins: [https://app.customer.example]
  public:
    apiURL: https://im.customer.example
    websocketURL: wss://im.customer.example/v1/realtime
    uploadURL: https://im.customer.example
    mediaURL: https://im.customer.example
    endpointRevision: production-2026-08
  media:
    driver: s3
    s3Region: cn-hangzhou
    s3Bucket: customer-xhim-media
  push:
    mode: webhook
    webhookURL: https://push.customer.example/xhim
  rtc:
    provider: external
    endpoint: wss://rtc.customer.example/rtc
    signingKeyID: rtc-production-1

Production 必须使用 image.repository@sha256:digest。tag 仅作人类可读版本，不得作为唯一供应链身份。

5. 渲染、安装与验收

bash

helm lint server/deploy/helm/xhim-server \
  --values /secure/xhim/values-production.yaml

helm template xhim server/deploy/helm/xhim-server \
  --namespace xhim \
  --values /secure/xhim/values-production.yaml \
  > /secure/xhim/rendered.yaml

kubectl apply --dry-run=server -f /secure/xhim/rendered.yaml

helm upgrade --install xhim server/deploy/helm/xhim-server \
  --namespace xhim \
  --create-namespace \
  --values /secure/xhim/values-production.yaml \
  --atomic \
  --timeout 15m

Migration Hook 失败时 --atomic 会停止升级，新 Deployment 不会接管流量。Migration 只前进；数据库恢复与 N/N-1 兼容必须先走 PostgreSQL 发布工具链。

安装后至少执行：

bash

kubectl -n xhim rollout status deployment/xhim-xhim-server
kubectl -n xhim get pods -l app.kubernetes.io/instance=xhim -o wide
kubectl -n xhim get pdb,hpa,networkpolicy
helm test xhim -n xhim --logs

随后用两个真实测试账号执行：鉴权、WSS Upgrade、跨 Pod 单聊/ 群聊、已读、Presence、Typing、媒体上传与 Push；然后驱逐一个 Pod 并确认客户端自动重连、不丢消息、不重复投递。

6. 升级、回滚与 Secret 轮换

应用回滚：仅在 N/N-1 Schema 兼容门禁通过时使用 helm rollback；
数据回滚：不使用 Helm，须按受审批的数据库恢复流程；
外部 Secret 变更不会自动修改 Deployment Template Hash，密钥轮换后需执行 kubectl rollout restart deployment/<name> 并走同样 Postflight；
签名 Key/Cursor Key 需双 Key 兼容期，不得直接覆盖；
更新撤销清单后必须滚动重启，再核对管理后台 License ID/Key ID。

7. 不包含的东西

Chart 本身不证明以下结论：

PostgreSQL 已高可用或备份可恢复；
S3 已开启版本、KMS、跨区复制与生命周期；
Ingress 已正确保留 WebSocket Upgrade/长连超时；
真实 APNs/FCM/Huawei Push 已通；
24h/72h 稳态、容量边界或多区 RPO/RTO 已达标。

这些都必须在客户的目标集群上保留原始验收证据，不能用 helm lint 或本机渲染结果替代。

XHIM Server Kubernetes / Helm 高可用部署 ​

1. 已实现的高可用边界 ​

2. 前置依赖 ​

3. Secret 合同 ​

4. 生产 Values ​

5. 渲染、安装与验收 ​

6. 升级、回滚与 Secret 轮换 ​

7. 不包含的东西 ​