# RabbitMQ 自建生产集群

本目录用于在客户自己的 Kubernetes 集群中部署 RabbitMQ，不依赖云厂商消息队列服务。模板使用 RabbitMQ 官方 Cluster Operator 管理三节点集群。客户已经提供可用 RabbitMQ 时，不需要部署本目录中的资源。

该组件独立于 EasyAI 主应用的 production overlay，需先部署 RabbitMQ，再把 Operator 生成的连接凭据写入 EasyAI 配置。

## 架构

- 3 个 RabbitMQ 节点，分别调度到不同 Worker 节点；
- 每个 RabbitMQ Pod 使用独立的 RWO PVC；
- 优先跨可用区调度；
- 客户端通过 `easyai-rabbitmq.easyai.svc.cluster.local:5672` 访问；
- 新建的普通持久化业务队列默认使用 quorum queue；
- Operator 负责 StatefulSet、内部 Service、节点发现和滚动更新，模板额外提供 `maxUnavailable: 1` 的 PodDisruptionBudget。

## 版本与配置边界

- `rabbitmq:4.3.2-management` 是本模板的默认镜像，不是 EasyAI 应用的硬性最低版本；
- EasyAI 使用标准 AMQP `0-9-1` 能力，不依赖 RabbitMQ `4.3` 专属功能；
- 已有 RabbitMQ `3.13.7` 及以上环境可以直接复用，但上线前必须验证队列声明、消息发布和消费、断线重连及故障切换；低于 `3.13.7` 的版本不在当前交付兼容范围内；
- RabbitMQ `3.13.x` 已停止社区支持，新建生产环境应选择官方当前处于支持期的版本；
- RabbitMQ 服务端参数位于 `rabbitmq-cluster.yaml` 的 `spec.rabbitmq.additionalConfig`，由 Cluster Operator 管理，因此本模板不需要单独的 RabbitMQ ConfigMap。

RabbitMQ 版本生命周期参考：

<https://www.rabbitmq.com/release-information>

## 默认资源规格与容量

当前自建模板的默认生产规格如下，CPU、内存和磁盘均为单个 RabbitMQ 节点的配置：

| 项目 | 单节点规格 | 3 节点合计 | 说明 |
| --- | --- | --- | --- |
| CPU | 请求 `1 vCPU`，上限 `2 vCPU` | 请求 `3 vCPU`，上限 `6 vCPU` | 当前 `rabbitmq-cluster.yaml` 实际值 |
| 内存 | 请求和上限均为 `2Gi` | 请求和上限均为 `6Gi` | 当前模板基线；高吞吐或大消息场景需压测后增加 |
| 持久化存储 | `50Gi` RWO SSD | `150Gi` | 每个节点使用独立 PVC，不包含备份和快照空间 |

以上规格是业务容量数据缺失时的首次上线基线，不代表固定性能或容量承诺。最终容量应按消息峰值、队列最大积压量、单条消息大小和保留时间确定，并在预发布环境完成压力测试。

持久化存储使用率达到 `70%` 时应告警，达到 `80%` 前完成 PVC 扩容。PVC 仅用于节点数据持久化，definitions 导出、存储快照和异地备份容量需要单独准备。生产环境优先使用低延迟 SSD，具体磁盘和内存规划可参考 RabbitMQ 官方 [Quorum Queues](https://www.rabbitmq.com/docs/quorum-queues) 说明。

## 前提条件

- Kubernetes 集群至少有 3 个可调度 Worker 节点；
- 已有支持动态创建 RWO PVC 的 StorageClass；
- 已安装与客户 Kubernetes 版本兼容的 RabbitMQ Cluster Operator；
- 节点可以拉取 `rabbitmq:4.3.2-management`，或已将该镜像同步到客户私有仓库。

安装 Operator 前请先核对官方兼容要求：

<https://www.rabbitmq.com/kubernetes/operator/install-operator>

联网环境可按官方方式安装：

```bash
kubectl apply -f https://github.com/rabbitmq/cluster-operator/releases/latest/download/cluster-operator.yml
kubectl -n rabbitmq-system rollout status deploy/rabbitmq-cluster-operator --timeout=10m
```

生产环境建议下载并审计 Operator YAML，将其中镜像同步到客户私有仓库后再安装，避免部署时依赖公网和浮动版本。

## 修改模板

编辑 `rabbitmq-cluster.yaml`：

1. 将 `CHANGE_ME_RABBITMQ_STORAGE_CLASS` 替换为客户的 RWO StorageClass；
2. 根据消息量调整每个节点的 `storage`、CPU 和内存；
3. 无法访问 Docker Hub 时，将 `image` 替换为客户私有仓库中的同版本镜像；
4. 确需修改默认 RabbitMQ 版本时，先核对官方支持周期，并在预发布环境完成兼容验证；已有数据的集群不得直接跨版本替换镜像；
5. 如果 Worker 节点不足 3 个，先扩容节点，不要删除主机级反亲和规则后直接用于生产。

检查占位符并渲染：

```bash
grep -R -n 'CHANGE_ME' k8s/addons/rabbitmq-cluster
kubectl kustomize k8s/addons/rabbitmq-cluster > /tmp/easyai-rabbitmq.yaml
```

## 部署

先创建 EasyAI namespace，再部署 RabbitMQ：

```bash
kubectl apply -f k8s/overlays/production/namespace.yaml
kubectl apply -k k8s/addons/rabbitmq-cluster
```

等待集群就绪：

```bash
kubectl -n easyai wait rabbitmqcluster/easyai-rabbitmq \
  --for=condition=AllReplicasReady \
  --timeout=15m

kubectl -n easyai get rabbitmqcluster easyai-rabbitmq
kubectl -n easyai get pod,svc,pvc,pdb \
  -l app.kubernetes.io/name=easyai-rabbitmq
```

## 配置 EasyAI

EasyAI 的非敏感连接参数保存在应用 ConfigMap 中，用户名和密码保存在应用 Secret 中。RabbitMQ 服务端配置由 `RabbitmqCluster` 资源管理，不需要另外创建 RabbitMQ ConfigMap。

Operator 会生成 `easyai-rabbitmq-default-user` Secret。初次连通性验证时可读取该 Secret 中的用户名和密码：

```bash
kubectl -n easyai get secret easyai-rabbitmq-default-user \
  -o jsonpath='{.data.username}' | base64 --decode
echo

kubectl -n easyai get secret easyai-rabbitmq-default-user \
  -o jsonpath='{.data.password}' | base64 --decode
echo
```

将读取到的值写入 `k8s/overlays/production/app-secret.yaml`：

```yaml
CONFIG_MQ_USER: Operator生成的用户名
CONFIG_MQ_PASSWORD: Operator生成的密码
```

Operator 生成的是集群默认管理用户。正式生产环境建议使用该用户完成初始化后，另行创建仅供 EasyAI 使用的应用用户，并只授予目标 vhost 的 configure/write/read 权限；随后将 `CONFIG_MQ_USER` 和 `CONFIG_MQ_PASSWORD` 替换为应用用户凭据。不要在多个系统之间共用默认管理用户。

修改 `k8s/overlays/production/app-config.yaml`：

```yaml
CONFIG_MQ_PROTOCOL: amqp
CONFIG_MQ_HOST: easyai-rabbitmq.easyai.svc.cluster.local
CONFIG_MQ_PORT: "5672"
CONFIG_MQ_VHOST: /
```

然后按仓库根目录 README 部署 EasyAI 主应用。

## 验证

```bash
kubectl -n easyai exec easyai-rabbitmq-server-0 -- rabbitmq-diagnostics -q ping
kubectl -n easyai exec easyai-rabbitmq-server-0 -- rabbitmqctl cluster_status
kubectl -n easyai exec easyai-rabbitmq-server-0 -- rabbitmqctl list_queues name type durable messages consumers
```

预期 `cluster_status` 中有 3 个运行节点，EasyAI 启动后业务持久化队列的 `type` 为 `quorum`。

## 运维注意事项

- 不要直接修改 Operator 生成的 StatefulSet；通过 `RabbitmqCluster` 资源修改集群。
- 不要同时重启两个 RabbitMQ 节点；维护前确认 quorum 状态正常。
- 模板保留 Operator 的默认终止宽限期，使 preStop 能在节点退出前检查 quorum 安全状态；不要为了加快删除而随意缩短。
- PVC 只解决节点重建时的数据持久化，不等同于备份。应定期导出 definitions，并结合存储快照制定恢复方案。
- 升级 RabbitMQ 或 Operator 前，先在测试环境验证队列声明、发布消费、断线重连和节点故障切换。
- 若要启用 AMQPS，应按客户证书体系配置 `spec.tls`，并将 EasyAI 的协议和端口调整为 `amqps`/`5671`。