feat(GOV-008): 采用 RocketMQ 消息队列架构

2026-08-13 14:22:50 +08:00
parent 3cc00de8f6
commit f5994ad77e
34 changed files with 463 additions and 43 deletions
@@ -7,11 +7,12 @@
 - 从 `deploy/env/production/` 准备四份真实配置，存放在服务器 `/etc/a-share-analysis/` 或其他受控目录。
 - Compose 通过外部路径加载，不在 YAML、镜像和 Git 中保存秘密。
 - 镜像引用必须包含版本或内容摘要，禁止浮动 `latest`。
- 第一阶段只依赖 Redis；MySQL 和 RabbitMQ 功能开关保持关闭。
+- 第一阶段只依赖 Redis；MySQL 和 RocketMQ 5.x 功能开关保持关闭。
+- 启用 RocketMQ 时优先连接受运维管理的外部集群或独立基础设施 Compose，不把 NameServer、Broker、Proxy 混入应用发布生命周期。

 ## 发布与回退

-部署前验证镜像对应已推送提交或标签、环境 Schema、健康检查和数据目录。升级只修改不可变镜像引用；失败时恢复上一完整镜像集合和未改变的外部配置。禁止删除 Redis、MySQL 或 RabbitMQ 数据目录作为应用回退手段。
+部署前验证镜像对应已推送提交或标签、环境 Schema、健康检查和数据目录。升级只修改不可变镜像引用；失败时恢复上一完整镜像集合和未改变的外部配置。禁止删除 Redis、MySQL 或 RocketMQ CommitLog 数据目录作为应用回退手段。

 ## 验证

@@ -1,6 +1,6 @@
 # 本地开发环境

-本地开发使用 Docker Compose 只启动 Redis，Web、API、Scheduler 和 Worker 从源码运行并使用开发环境模板。第一阶段不启动 MySQL 和 RabbitMQ。
+本地开发使用 Docker Compose 只启动 Redis，Web、API、Scheduler 和 Worker 从源码运行并使用开发环境模板。第一阶段不自动启动 MySQL 和 RocketMQ 5.x。

 ## 配置

@@ -16,6 +16,12 @@ docker compose -f deploy/compose/development.yml down

 Redis 只绑定 `127.0.0.1:6379`，数据写入仓库忽略的 `.local/redis/`。不得把该 Compose 文件用于生产。

+## RocketMQ 联调
+
+RocketMQ 由开发者在项目 Compose 外独立启动。应用启用前至少需要 NameServer、Broker；采用推荐的 Node.js Proxy 接入时还需要 Proxy。默认端口约定：NameServer `9876`、Broker `10911`、Proxy gRPC `8081`。
+
+`nc -vz 127.0.0.1 9876` 只能证明 NameServer TCP 可达，不能证明 Topic 路由、Broker 注册或消息收发可用。完整联调必须继续检查 Broker 列表，并执行一次测试 Topic 的生产与消费。开发模板默认 `ROCKETMQ_ENABLED=false`；启用后必须提供可用的 `ROCKETMQ_ENDPOINT`，不得把生产地址写入本地配置或仓库。
+
 ## 应用状态

 Web 和 Server 尚未完成脚手架，因此本版本只交付配置契约和 Redis 开发环境。后续脚手架必须使用 Node.js 22 LTS、pnpm 10 和这些模板，不能在本文档中假装应用已经可启动。
@@ -1,6 +1,6 @@
 # Ubuntu 源码生产部署

-正式支持 Ubuntu 22.04 LTS 与 Ubuntu 24.04 LTS 的 x86_64。服务器管理员预先提供 Node.js 22 LTS、pnpm 10、Nginx，以及 MySQL 5.7、Redis、RabbitMQ 或相应外部服务；项目不负责安装或升级这些软件，也不修改系统软件源。
+正式支持 Ubuntu 22.04 LTS 与 Ubuntu 24.04 LTS 的 x86_64。服务器管理员预先提供 Node.js 22 LTS、pnpm 10、Nginx，以及 MySQL 5.7、Redis、RocketMQ 5.x 或相应外部服务；项目不负责安装或升级这些软件，也不修改系统软件源。

 ## 前置验证

@@ -33,3 +33,5 @@ nginx -v
 在新的不可变发布目录完成安装、构建和配置校验后，原子切换 `current`，依次重启 API、Scheduler、Worker 并检查 `systemctl status`、`journalctl` 和 HTTP 健康端点。失败时切回上一完整目录并重启服务；生产配置不随版本切换覆盖。

 项目部署流程禁止连接或读取生产数据库做开发验证。数据库备份属于独立运维职责，应用回退不得删除或覆盖数据。
+
+RocketMQ 由运维独立维护 NameServer、Broker 和需要时的 Proxy。应用发布只读取受控的 RocketMQ Endpoint、Topic 前缀与 Group 配置，不负责创建或升级集群，也不得把 Broker 数据目录放进应用发布目录。