docs(deploy): 澄清 RabbitMQ 版本与配置边界

README.md

@@ -61,13 +61,13 @@ kubectl get storageclass
 
 部署前需要准备以下基础依赖，并保证 EasyAI Pod 可以访问。依赖既可以使用云厂商托管服务，也可以由客户自行部署。
 
-以下版本为当前生产部署目标版本。请固定主版本和补丁版本；大版本升级前必须在测试环境完成连接、功能、性能和备份恢复验证。
+以下版本为新建生产环境的推荐基线；已有依赖满足各小节兼容条件时可以复用。实际部署时请固定主版本和补丁版本；大版本升级前必须在测试环境完成连接、功能、性能和备份恢复验证。
 
 | 依赖 | 推荐版本 | 用途 | 需要准备的信息 |
 | --- | --- | --- | --- |
 | MongoDB | `7.x` | 主服务业务数据 | 内网地址、端口、用户名、密码、连接参数 |
 | Redis | `7.x`，需支持至少 `16` 个逻辑 DB | 队列、缓存、WebSocket 集群状态 | 内网地址、端口、密码，需支持多个逻辑 DB |
-| RabbitMQ | `4.3.x`，自建模板固定为 `4.3.2`，需支持 AMQP `0-9-1` | 消息队列 | AMQP 地址、端口、用户名、密码、vhost |
+| RabbitMQ | 需支持 AMQP `0-9-1`；新建环境建议使用官方当前仍受支持的版本，自建模板默认使用 `4.3.2` | 消息队列 | AMQP 地址、端口、用户名、密码、vhost |
 | PostgreSQL + pgvector | PostgreSQL `18` + pgvector `0.8.2` | Agent 治理和记忆服务 | 地址、端口、用户名、密码、数据库、扩展 |
 | RWX 共享存储 | 与 Kubernetes 集群版本兼容的 CSI/存储插件 | 上传、备份、恢复文件共享 | 支持 `ReadWriteMany` 的 StorageClass |
 | OSS/S3 对象存储 | 兼容 AWS S3 Signature V4 或云厂商 OSS/S3 当前 API，可选 | 文件存储，可选 | Endpoint、Bucket、Access Key |
@@ -108,7 +108,11 @@ MongoDB 生命周期和驱动兼容性参考：
 
 #### RabbitMQ 托管或自建方案
 
-使用托管 RabbitMQ 时，向 EasyAI 提供内网 AMQP Service 地址、`5672`/`5671` 端口、用户名、密码和 vhost 即可。
+EasyAI 使用标准 AMQP `0-9-1` 能力，不依赖 RabbitMQ `4.3` 专属功能。自建模板中的 `4.3.2` 是默认部署版本，不是应用的硬性最低版本。
+
+已有 RabbitMQ `3.13.7` 及以上环境时，可以直接复用，不需要再部署本仓库的 RabbitMQ 模板；上线前应验证队列声明、消息发布和消费、断线重连及故障切换。低于 `3.13.7` 的版本不作为当前交付兼容范围。RabbitMQ `3.13.x` 已停止社区支持，因此新建生产环境仍建议选择官方当前处于支持期的版本。
+
+使用托管或客户已有的 RabbitMQ 时，向 EasyAI 提供内网 AMQP Service 地址、`5672`/`5671` 端口、用户名、密码和 vhost 即可。
 
 不能使用云服务时，使用以下目录中的 RabbitMQ Cluster Operator 三节点模板：
 
@@ -122,7 +126,13 @@ k8s/addons/rabbitmq-cluster
 k8s/addons/rabbitmq-cluster/README.md
 ```
 
-自建模板默认使用 RabbitMQ `4.3.2` 和 quorum queue。RabbitMQ `3.13.x` 已停止社区支持，只能作为存量过渡版本；升级现有集群前必须在测试环境验证队列声明、发布消费、重连和故障切换，不能直接跨版本替换数据节点。
+自建模板默认使用 RabbitMQ `4.3.2` 和 quorum queue。升级现有集群前必须在测试环境验证队列声明、发布消费、重连和故障切换，不能直接跨版本替换数据节点。
+
+RabbitMQ 配置分为三部分：
+
+- AMQP 协议、地址、端口和 vhost 等非敏感连接参数位于 `k8s/overlays/production/app-config.yaml`，该文件会生成 EasyAI 应用的 ConfigMap；
+- 用户名和密码位于 `k8s/overlays/production/app-secret.yaml`；
+- 使用自建模板时，RabbitMQ 服务端参数写在 `RabbitmqCluster` 资源的 `spec.rabbitmq.additionalConfig` 中，由 Cluster Operator 管理，不需要额外提供 RabbitMQ ConfigMap。
 
 RabbitMQ 版本生命周期参考：
 

k8s/addons/rabbitmq-cluster/README.md

@@ -1,6 +1,6 @@
 # RabbitMQ 自建生产集群
 
-本目录用于在客户自己的 Kubernetes 集群中部署 RabbitMQ，不依赖云厂商消息队列服务。模板使用 RabbitMQ 官方 Cluster Operator 管理三节点集群。
+本目录用于在客户自己的 Kubernetes 集群中部署 RabbitMQ，不依赖云厂商消息队列服务。模板使用 RabbitMQ 官方 Cluster Operator 管理三节点集群。客户已经提供可用 RabbitMQ 时，不需要部署本目录中的资源。
 
 该组件独立于 EasyAI 主应用的 production overlay，需先部署 RabbitMQ，再把 Operator 生成的连接凭据写入 EasyAI 配置。
 
@@ -13,6 +13,18 @@
 - 新建的普通持久化业务队列默认使用 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>
+
 ## 前提条件
 
 - Kubernetes 集群至少有 3 个可调度 Worker 节点；
@@ -40,7 +52,8 @@ kubectl -n rabbitmq-system rollout status deploy/rabbitmq-cluster-operator --tim
 1. 将 `CHANGE_ME_RABBITMQ_STORAGE_CLASS` 替换为客户的 RWO StorageClass；
 2. 根据消息量调整每个节点的 `storage`、CPU 和内存；
 3. 无法访问 Docker Hub 时，将 `image` 替换为客户私有仓库中的同版本镜像；
-4. 如果 Worker 节点不足 3 个，先扩容节点，不要删除主机级反亲和规则后直接用于生产。
+4. 确需修改默认 RabbitMQ 版本时，先核对官方支持周期，并在预发布环境完成兼容验证；已有数据的集群不得直接跨版本替换镜像；
+5. 如果 Worker 节点不足 3 个，先扩容节点，不要删除主机级反亲和规则后直接用于生产。
 
 检查占位符并渲染：
 
@@ -72,6 +85,8 @@ kubectl -n easyai get pod,svc,pvc,pdb \
 
 ## 配置 EasyAI
 
+EasyAI 的非敏感连接参数保存在应用 ConfigMap 中，用户名和密码保存在应用 Secret 中。RabbitMQ 服务端配置由 `RabbitmqCluster` 资源管理，不需要另外创建 RabbitMQ ConfigMap。
+
 Operator 会生成 `easyai-rabbitmq-default-user` Secret。初次连通性验证时可读取该 Secret 中的用户名和密码：
 
 ```bash