安装部署

本文档详细介绍 TMQTT 在不同环境下的安装和部署方式。

---

Docker 部署

Docker 是最推荐的部署方式，环境隔离、易于管理。

构建镜像

# 基础版本（仅核心功能）
docker build -t tmqtt .

# 启用持久化存储
docker build --build-arg FEATURES="rocksdb" -t tmqtt .

# 启用消息桥接（Kafka）
docker build --build-arg FEATURES="bridge-kafka" -t tmqtt .

# 同时启用多个功能
docker build --build-arg FEATURES="rocksdb,bridge-kafka,bridge-tdengine" -t tmqtt .

启动容器

docker run -d --name tmqtt \
  -p 1883:1883 \
  -p 8883:8883 \
  -p 8083:8083 \
  -p 8080:8080 \
  -p 9090:9090 \
  -v /path/to/config.toml:/opt/tmqtt/config.toml \
  -v /path/to/data:/var/lib/tmqtt \
  tmqtt

说明：-v 参数用于挂载自定义配置文件和数据目录（持久化存储时使用）。

端口规划

端口	用途	是否需要暴露
1883	MQTT TCP	是，设备连接必需
8883	MQTT TLS	按需，启用加密时暴露
8083	WebSocket	按需，Web/移动端使用时暴露
8084	WSS（加密 WebSocket）	按需
8080	管理 API	建议仅内网暴露
9090	Prometheus 指标	建议仅内网暴露
7000/7001	集群通信	仅集群模式使用

---

裸机部署

Linux

# 安装 Rust（如尚未安装）
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# 编译
git clone <仓库地址>
cd tmqtt
cargo build --release

# 复制到系统目录（可选）
cp target/release/tmqtt /usr/local/bin/
cp config.toml /etc/tmqtt/config.toml

Windows

# 确保已安装 Rust 1.85+
# 在 PowerShell 中编译
cargo build --release

# 运行
.\target\release\tmqtt.exe

注意：Windows 下集群功能需要额外安装 protoc 编译器。单机模式无此限制。

macOS

# 安装 Rust
brew install rust

# 编译运行
cargo build --release
./target/release/tmqtt

---

生产部署建议

systemd 服务配置（Linux）

在 Linux 服务器上，建议使用 systemd 管理 TMQTT 进程：

[Unit]
Description=TMQTT MQTT Broker
After=network.target

[Service]
Type=simple
User=tmqtt
WorkingDirectory=/opt/tmqtt
ExecStart=/usr/local/bin/tmqtt
Restart=always
RestartSec=5
LimitNOFILE=1048576

[Install]
WantedBy=multi-user.target

防火墙规则

仅开放必要端口，管理接口（8080/9090）建议限制为内网访问：

# 开放 MQTT 端口
ufw allow 1883/tcp
ufw allow 8883/tcp

# 如需 WebSocket
ufw allow 8083/tcp

# 管理端口仅限内网
ufw allow from 10.0.0.0/8 to any port 8080
ufw allow from 10.0.0.0/8 to any port 9090

文件描述符限制

TMQTT 每个连接占用一个文件描述符，大规模连接场景需调高系统限制：

# /etc/security/limits.conf
tmqtt  soft  nofile  1048576
tmqtt  hard  nofile  1048576

---

功能模块按需启用

TMQTT 的部分功能需要在编译时通过 Feature 开关启用，默认编译只包含核心功能。

Feature	说明	是否需要额外依赖
（默认）	核心 MQTT Broker、集群、认证、监控	无
rocksdb	RocksDB 持久化存储	需要 CMake 和 C++ 编译器
bridge-kafka	桥接到 Kafka	需要 CMake（用于编译 librdkafka）
bridge-tdengine	桥接到 TDengine	无（纯 Rust WebSocket 连接）
bridge-rabbitmq	桥接到 RabbitMQ	无
bridge-rocketmq	桥接到 RocketMQ	无（HTTP Proxy 方式）
bridge-all	启用所有桥接后端	需要 CMake
io-uring	Linux io_uring 高性能后端	仅 Linux 可用

示例：

# 启用持久化 + Kafka 桥接
cargo build --release --features "rocksdb,bridge-kafka"

---

升级与回滚

TMQTT 支持平滑升级，建议步骤：

1. 备份配置文件：cp config.toml config.toml.bak
2. 编译新版本：cargo build --release
3. 停止旧进程：发送 SIGTERM 信号，TMQTT 会优雅关闭（自动保存会话）
4. 替换二进制：cp target/release/tmqtt /usr/local/bin/
5. 启动新版本：systemctl start tmqtt

如使用集群模式，建议逐节点滚动升级，配合 Drain 模式实现零停机。

Copyright (c) 2026 桃子 TaoZi.Pub https://taozi.pub | MIT License