RobustMQ

简体中文

English

简体中文

English

Appearance

RobustMQ 构建打包指南 ​

本指南介绍如何构建和打包 RobustMQ。

📦 构建产物概览 ​

RobustMQ 构建过程会生成以下类型的产物：

产物类型文件格式生成命令用途
安装包.tar.gz 压缩包make build / make build-full用户下载安装的二进制包
Docker 镜像Docker 镜像make release-docker容器化部署
GitHub 发布在线发布页面make release用户下载和查看发布

产物详细说明 ​

  • .tar.gz 安装包：包含 Rust 编译的二进制文件、配置文件、启动脚本等，用户解压后即可运行
  • Docker 镜像：容器化的 RobustMQ 应用，支持 Docker 和 Kubernetes 部署（使用 cargo-chef 优化依赖缓存）
  • GitHub 发布：在线发布页面，用户可以通过浏览器下载安装包

🚀 快速开始 ​

使用 Make 命令（推荐） ​

命令功能版本来源说明
make build基本构建自动读取 Cargo.toml构建当前平台包（不含前端）
make build-full完整构建自动读取 Cargo.toml构建包含前端的完整包
make build-version VERSION=v0.1.30指定版本构建手动指定构建指定版本的包

版本说明：不指定版本时，所有构建命令都会自动从项目根目录的 Cargo.toml 文件中读取当前版本号。

🐳 Docker 镜像构建 ​

应用镜像 ​

命令功能版本来源说明
make release-dockerGHCR 应用镜像自动读取 Cargo.toml构建并推送到 GitHub Container Registry（org=robustmq）

版本说明：release-docker 命令会自动从 Cargo.toml 读取版本号，并使用 robustmq 作为组织名称。

Docker 目录结构 ​

docker/
└── robustmq/               # 应用镜像相关文件
    ├── Dockerfile          # 应用镜像 Dockerfile（使用 cargo-chef 优化依赖缓存）
    ├── docker-compose.yml  # 本地开发 Docker Compose
    ├── monitoring/         # 监控配置
    │   ├── prometheus.yml  # Prometheus 配置
    │   ├── grafana/        # Grafana 配置
    │   └── jaeger/         # Jaeger 配置
    ├── .dockerignore       # 应用镜像构建忽略文件
    └── README.md           # 应用镜像说明文档

构建优化：Dockerfile 使用 cargo-chef 实现依赖层缓存，无需单独的 deps 镜像。cargo-chef 会自动生成依赖配方（recipe），只有当 Cargo.lock 改变时才重新编译依赖。

🚀 版本发布 ​

命令功能版本来源说明
make release创建新发布自动读取 Cargo.toml创建 GitHub 发布并上传包
make release-docker发布 Docker 镜像自动读取 Cargo.toml构建并推送 Docker 镜像到 GHCR
make release-version VERSION=v0.1.30指定版本发布手动指定创建指定版本的 GitHub 发布

前置条件 ​

bash
# 设置 GitHub Token（必需）
export GITHUB_TOKEN="your_github_token_here"

权限说明：

  • 应用镜像推送到指定的组织或用户账户
  • 确保您的 GITHUB_TOKEN 有 write:packages 权限

📦 输出结果 ​

构建产物说明 ​

产物类型文件位置内容说明用途
安装包build/robustmq-{version}-{platform}.tar.gz压缩的二进制安装包用户下载安装 RobustMQ
包信息build/robustmq-{version}-{platform}/package-info.txt版本、平台、构建时间等元数据了解包的详细信息
Docker 镜像robustmq/robustmq:{version}容器化的 RobustMQ 应用（内置 cargo-chef 优化）Docker 部署和运行
GitHub 发布https://github.com/robustmq/robustmq/releases/tag/{version}在线发布页面用户下载和查看发布说明

安装包结构详解 ​

目录/文件内容类型具体内容作用
bin/启动脚本robust-server, robust-ctl, robust-bench系统启动和管理脚本
libs/二进制可执行文件broker-server, cli-command, cli-bench核心 Rust 编译的二进制程序
config/配置文件server.toml, server-tracing.toml服务配置和日志配置
dist/前端静态文件HTML, CSS, JavaScript 文件Web 管理界面（如果包含前端）
LICENSE许可证文件Apache 2.0 许可证文本法律许可信息
package-info.txt元数据文件版本、平台、构建时间、二进制列表包的详细信息

📋 使用场景 ​

场景命令产物说明
开发测试make build本地 .tar.gz 安装包快速构建测试包，用于本地开发和测试
发布准备make build-full本地完整 .tar.gz 安装包构建包含前端的完整发布包，用于正式发布
应用部署make release-dockerDocker 应用镜像构建并推送应用镜像到 GitHub Container Registry（使用 cargo-chef 自动优化依赖缓存）
版本发布make releaseGitHub 发布页面 + 安装包创建 GitHub 发布并上传安装包，用户可下载

🔧 Docker 构建优化 ​

cargo-chef 依赖缓存 ​

方案：RobustMQ 使用 cargo-chef 实现高效的依赖层缓存，无需单独的 deps 镜像。

工作原理：

  1. Planner 阶段：分析 Cargo.toml 和 Cargo.lock，生成依赖配方（recipe.json）
  2. Builder 阶段：根据配方先编译依赖，再编译应用代码
  3. 分层缓存：只有 Cargo.lock 改变时才重新编译依赖，否则使用缓存层

优势：

  • ✅ 自动化依赖缓存管理，无需手动维护
  • ✅ Docker 原生层缓存，构建速度快
  • ✅ 只缓存纯依赖，不包含应用代码
  • ✅ 依赖改变时自动更新，应用代码改变时复用依赖缓存

构建加速技巧 ​

清理缓存重建：

bash
# 清理 Docker 构建缓存
docker builder prune -f

# 重新构建镜像（不使用缓存）
docker build --no-cache -f docker/robustmq/Dockerfile -t robustmq:latest .

多阶段构建：

  • Development 阶段：包含调试工具，用于开发和调试
  • Runtime 阶段：精简的生产镜像，只包含运行时必需组件

⚠️ 注意事项 ​

构建脚本限制 ​

特性状态说明
当前系统平台✅只构建当前系统平台
自动版本检测✅自动从 Cargo.toml 读取版本
发布模式构建✅使用 cargo build --release
自动前端克隆✅自动克隆前端代码
交叉编译❌不支持交叉编译

发布脚本限制 ​

特性状态说明
前端构建✅总是包含前端构建
当前平台✅总是构建当前系统平台

🔧 环境要求 ​

类型工具用途必需性
基本Rust (cargo, rustup)Rust 编译✅ 必需
前端pnpm前端包管理🔶 可选
前端git克隆前端代码🔶 可选
DockerdockerDocker 环境🔶 可选
发布curlAPI 请求🔶 可选
发布jqJSON 解析🔶 可选
发布GITHUB_TOKENGitHub 访问令牌🔶 可选

🆘 常见问题 ​

构建失败排查 ​

问题检查命令解决方案
Rust 环境问题cargo --version安装 Rust 环境
Docker 环境问题docker info启动 Docker 服务
网络连接问题ping github.com检查网络连接

Docker 构建失败排查 ​

问题检查命令解决方案
Docker 环境问题docker info启动 Docker 服务
权限问题echo $GITHUB_TOKEN设置正确的 GitHub Token
网络连接问题docker pull rust:1.90.0-bookworm检查 Docker Hub 连接
镜像推送失败docker login ghcr.io手动登录 GitHub Container Registry

发布失败排查 ​

问题检查命令解决方案
GitHub Token 问题echo $GITHUB_TOKEN设置正确的 Token
Token 权限问题curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user检查 Token 权限
网络连接问题curl -I https://api.github.com检查网络连接

查看构建产物 ​

操作命令说明
查看构建目录ls -la build/查看所有构建产物
解压测试tar -xzf build/robustmq-*.tar.gz解压安装包
测试二进制./robustmq-*/libs/broker-server --help测试可执行文件
查看包信息cat robustmq-*/package-info.txt查看包详细信息

查看 Docker 镜像 ​

操作命令说明
查看本地镜像`docker imagesgrep robustmq`
测试镜像docker run --rm robustmq/robustmq:latest --help测试应用镜像
查看镜像历史docker history robustmq/robustmq:latest查看镜像构建历史
查看镜像大小docker images robustmq/robustmq --format "\{\{.Size\}\}"查看镜像大小