# RocketMQ 消息队列架构调整设计

- 功能编号：GOV-008
- 设计版本：0.1
- 状态：approved
- 日期：2026-08-13

## 架构

```text
Scheduler
  -> MessageBusAdapter.publish()
  -> RocketMQ 5.x Proxy 或受支持客户端
  -> NameServer / Broker
  -> MessageBusAdapter.consume()
  -> Worker
  -> Redis 当前状态 + MySQL 事实记录
```

`MessageBusAdapter` 是稳定边界。业务消息、Topic 和 Group 不引用 RocketMQ SDK 类型，未来客户端实现变化不要求重写调度与分析逻辑。项目只维护 RocketMQ 一套实现，不同时维护 RabbitMQ 兼容层。

## 接入模式

推荐 Node.js 通过 RocketMQ 5.x Proxy 接入，以降低对旧 Remoting 客户端实现的依赖。若后续选定的 Node 客户端直接连接 NameServer/Broker，必须先验证客户端维护状态、RocketMQ 5.3.2 兼容性、重试语义和优雅关闭，再通过 Adapter 接入。

`ROCKETMQ_NAMESRV_ADDR` 用于基础设施发现和诊断，`ROCKETMQ_ENDPOINT` 是应用客户端实际接入地址。两者不得混为同一项：只有 NameServer 端口可达时，不能完成生产或消费。

## Topic 与 Group

- Topic 前缀固定为 `a-share-analysis`，实际 Topic 按业务域追加，例如行情采集或指标计算。
- Tag 使用稳定事件类型，不用临时任务 ID。
- RocketMQ 5.x Proxy Producer 不配置 Producer Group；Worker 按独立消费语义使用 Consumer Group。
- 环境隔离通过受控前缀或独立集群完成，禁止开发消费者读取生产 Topic。

## 可靠性

RocketMQ 提供至少一次投递语义，Worker 必须幂等。消息处理完成并形成可验证结果后才能确认；可重试错误返回重试，永久错误记录原因后进入死信。顺序消息只在明确消息组键内保证，不假设跨证券或跨交易日全局顺序。

最大投递次数是 Consumer Group 的服务端重试策略，由 RocketMQ 运维配置和发布检查负责。应用客户端只声明 Consumer Group、并发与处理结果，不能用一个不会被官方 Node SDK读取的 env 字段假装控制死信边界。

## 本地状态

2026-08-13 首次检查到 `apache/rocketmq:5.3.2` 的 `rmqnamesrv` 容器曾运行并映射 `9876:9876`，日志为 NameServer boot success；随后串行复核发现该容器已以 137 退出且未配置自动重启，`OOMKilled=false`。

宿主机 `9876` 实际由 `/usr/local/rocketmq` 的原生 NameServer 监听，同时存在 `mqbroker --enable-proxy`。只读 `mqadmin` 验证结果：`broker-a` 已注册，版本 `V5_3_2`、`brokerActive=true`，Broker 地址 `192.168.2.37:10911`；本机 `10911`、Proxy `8081` 和 NameServer `9876` 均可达，Topic 列表可读取。当前可确认 RocketMQ 基础设施和管理链路连通，但尚未通过项目 Node 客户端执行消息收发。