配置指南
TMQTT 使用 TOML 格式的配置文件，默认文件名为 config.toml，位于程序运行目录下。
本文档逐项说明每个配置项的含义、默认值和推荐设置。
基础配置
节点信息 [node]
| 配置项 | 默认值 | 说明 |
|---|---|---|
id | node-1 | 节点唯一标识，集群模式下各节点须不同 |
name | tmqtt-node-1 | 节点名称，用于日志和监控展示 |
监听端口 [listener]
| 配置项 | 默认值 | 说明 |
|---|---|---|
tcp.bind | 0.0.0.0:1883 | MQTT TCP 监听地址 |
tcp.backlog | 1024 | TCP 连接等待队列大小 |
tcp.max_connections | 10000 | 最大并发连接数 |
TLS 加密连接 [listener.tls]（默认未启用，取消注释即可开启）：
| 配置项 | 默认值 | 说明 |
|---|---|---|
bind | 0.0.0.0:8883 | TLS 监听地址 |
cert | — | 服务端证书 PEM 文件路径（必填） |
key | — | 服务端私钥 PEM 文件路径（必填） |
ca_cert | — | CA 证书路径（启用 mTLS 时必填） |
mtls | false | 是否强制客户端证书认证 |
WebSocket [listener.ws]（默认未启用）：
| 配置项 | 默认值 | 说明 |
|---|---|---|
bind | 0.0.0.0:8083 | WebSocket 监听地址 |
加密 WebSocket [listener.wss]（默认未启用）：
| 配置项 | 默认值 | 说明 |
|---|---|---|
bind | 0.0.0.0:8084 | WSS 监听地址 |
cert | — | 证书路径（必填） |
key | — | 私钥路径（必填） |
日志 [log]
| 配置项 | 默认值 | 说明 |
|---|---|---|
level | info | 日志级别：trace / debug / info / warn / error |
format | text | 输出格式：text（人类可读）或 json（适合日志采集） |
认证与安全 [auth]
| 配置项 | 默认值 | 说明 |
|---|---|---|
anonymous_allow | false | 是否允许无用户名密码的连接。生产环境务必保持 false |
密码文件认证 [auth.password_file]：
| 配置项 | 说明 |
|---|---|
path | 密码文件路径，每行格式为 username:argon2id_hash |
JWT 认证 [auth.jwt]：
| 配置项 | 默认值 | 说明 |
|---|---|---|
algorithm | RS256 | 签名算法：RS256 或 ES256 |
public_key | — | 公钥 PEM 文件路径（必填） |
expiry_check | true | 是否校验 Token 过期时间 |
audience | [] | 期望的 audience 列表，非空时 JWT 的 aud 必须匹配 |
速率限制 [auth.rate_limit]：
| 配置项 | 默认值 | 说明 |
|---|---|---|
max_connections_per_sec | 100 | 每个 IP 每秒最大连接数 |
max_publish_per_sec | 1000 | 每个连接每秒最大发布消息数 |
访问控制 [acl]：
| 配置项 | 说明 |
|---|---|
path | ACL 规则文件路径，支持热加载（修改文件后自动生效） |
会话配置 [session]
| 配置项 | 默认值 | 说明 |
|---|---|---|
max_inflight | 32 | 飞行窗口大小，即同时等待 ACK 的最大消息数 |
max_packet_size | 1048576 | 单条消息最大字节数（默认 1MB） |
session_expiry_sec | 86400 | 持久会话过期时间（秒），默认 1 天 |
max_topic_alias | 100 | v5.0 最大主题别名数（0 表示不启用） |
存储配置 [storage]
| 配置项 | 默认值 | 说明 |
|---|---|---|
storage_type | memory | 存储后端：memory（内存）或 rocksdb（持久化） |
path | ./data | RocksDB 数据目录（仅 rocksdb 时生效） |
max_offline_messages | 1000 | 每个客户端最大离线缓存消息数（0 表示无限制） |
使用
rocksdb需要在编译时启用--features rocksdb。
管理 API [api]
| 配置项 | 默认值 | 说明 |
|---|---|---|
enabled | true | 是否启用管理 HTTP API |
bind | 0.0.0.0:8080 | API 监听地址 |
auth_token | — | 鉴权 Token，配置后所有接口（除 /healthz）需携带 Authorization: Bearer <token> 请求头。生产环境务必配置 |
监控 [metrics]
| 配置项 | 默认值 | 说明 |
|---|---|---|
enabled | true | 是否启用 Prometheus 指标导出 |
bind | 0.0.0.0:9090 | Prometheus Exporter 监听地址 |
性能配置 [performance]
| 配置项 | 默认值 | 说明 |
|---|---|---|
tcp_nodelay | true | 启用 TCP_NODELAY，减少小包延迟 |
tcp_keepalive_secs | 60 | TCP 保活探测间隔（秒），0 表示不启用 |
send_buffer_size | 0 | 发送缓冲区大小（0 表示系统默认） |
recv_buffer_size | 0 | 接收缓冲区大小（0 表示系统默认） |
worker_threads | 0 | 工作线程数（0 表示等于 CPU 核心数） |
慢消费者配置 [slow_consumer]
当客户端接收消息速度过慢时，TMQTT 会自动检测并处理。
| 配置项 | 默认值 | 说明 |
|---|---|---|
queue_threshold | 0.8 | 发送队列容量占比阈值（0.8 即 80% 满时触发告警） |
disconnect_after_secs | 30 | 持续超过阈值多少秒后断开该客户端 |
drop_on_full | true | 队列满时是否丢弃新消息（false 则阻塞等待） |
配置热重载
TMQTT 支持在不停机的情况下修改部分配置并自动生效。
支持热重载的配置：
- 日志级别（
log.level）：修改配置文件后自动应用 - ACL 规则文件：文件变更后自动重新加载
- TLS 证书：检测到证书文件变更后生效（部分场景需重启）
触发方式：
- 自动：修改
config.toml文件后，TMQTT 会自动检测并加载变更 - 手动：通过管理 API 调用
POST /api/v1/config/reload
常见配置场景
开发环境（最简配置）
仅需 TCP 端口，允许匿名连接，不启用安全特性：
toml
[auth]
anonymous_allow = true
[api]
enabled = true
bind = "127.0.0.1:8080"生产单机
启用认证、ACL、API 鉴权、TLS：
toml
[auth]
anonymous_allow = false
[auth.password_file]
path = "/etc/tmqtt/passwd"
[auth.rate_limit]
max_connections_per_sec = 50
max_publish_per_sec = 500
[acl]
path = "/etc/tmqtt/acl.toml"
[listener.tls]
bind = "0.0.0.0:8883"
cert = "/etc/tmqtt/server.crt"
key = "/etc/tmqtt/server.key"
[api]
auth_token = "your-secure-token-here"生产集群
参见 集群部署 中的集群配置示例。
Copyright (c) 2026 桃子 TaoZi.Pub https://taozi.pub | MIT License