# 集群部署

本文介绍如何使用 FlowMQ 的集群部署工具 **dm** 在多台 Linux 节点上自动化部署 FlowMQ 集群。

::: info 说明
本文示例以 3 台节点为例（node1~node3），实际请按你的拓扑进行调整。
:::

## 前置条件

- 目标节点为 Linux（Debian/Ubuntu 或 RHEL/CentOS 系）。
- 节点之间的网络互通。
- 已准备好 FlowMQ 的安装包（需要与节点的操作系统，CPU 架构相匹配）并分发到了各节点上。

## 步骤 1：安装 dm 与 dm-agent


解压 FlowMQ 的安装包并安装 dm （在所有**目标节点**均需要安装）。

### Debian/Ubuntu

```bash
sudo dpkg -i dm-<version>-amd64.deb
```

### RHEL/CentOS
```bash
sudo rpm -i dm-<version>-amd64.rpm
```

### 在目标节点启动 dm-agent

在每台目标节点安装完成后，启动 dm-agent ：

```bash
sudo systemctl enable --now dm-agent
```

验证 dm-agent 状态：

```bash
systemctl status dm-agent
```

## 步骤 2：创建部署配置文件

选定任一目标节点为控制节点，创建部署配置文件 `deploy.toml`。

示例：

```toml
[agents]
node1 = "192.168.1.10:14159"
node2 = "192.168.1.11:14159"
node3 = "192.168.1.12:14159"

[meta.deploy]
on = "all"
package = "flowmq-meta_7.4.5-1_amd64.deb"
processes-per-machine = 1
replication-mode = "double"
storage-engine = "ssd-redwood-1"

[meta.config]
datadir = "/var/lib/foundationdb/data/$ID"
logdir = "/var/log/foundationdb"

[flowmq.deploy]
on = "all"
package = "flowmq.deb"
num = 4

[flowmq.config]
cluster-id = "flowmq-cluster-1"
cluster-file = "/etc/foundationdb/fdb.cluster"
class = "mqtt"
```

配置说明：

- `[agents]`：填写目标节点 dm-agent 的监听地址（`IP:PORT`）,  dm-agent 默认监听 `14159` 端口。
- `[meta.deploy]`：指定 Meta 的部署配置。
- `[meta.config]`：指定 Meta 的启动和运行配置。
- `[flowmq.deploy]`：指定 FlowMQ 部署配置。
- `[flowmq.config]`：指定 FlowMQ 的启动和运行配置。


## 步骤 3：部署并启动 Meta

在控制机执行：

```bash
dm -c deploy.toml meta install
dm -c deploy.toml meta start
```

验证 Meta 集群状态：

```bash
fdbcli --exec "status"
```

当输出显示集群可用后，再进行下一步部署 FlowMQ 。

## 步骤 4：部署并启动 FlowMQ

在控制机执行：

```bash
dm -c deploy.toml flowmq install
dm -c deploy.toml flowmq start
```

验证 FlowMQ 集群成员（在任意已安装 FlowMQ 的节点执行）：

```bash
fmqcli cluster list-cluster-members
```

若返回成员列表且节点状态正常，则部署完成。

## 安装卸载 

停止服务：

```bash
# Stop services
dm -c deploy.toml flowmq stop
dm -c deploy.toml meta stop
```

卸载/移除服务

::: warning 
注意该操作会清除数据，请勿在生产环境直接操作
:::

```bash
dm -c deploy.toml flowmq remove
dm -c deploy.toml meta remove
```

## 配置参考

### `[meta.deploy]`

| 配置项 | 说明 | 默认值 |
|---|---|---|
| `on` | 目标节点范围（如 `all` 或指定节点集合） | - |
| `package` | flowmq-meta 安装包路径（`.deb` 或 `.rpm`） | 必填 |
| `processes-per-machine` | 每台机器启动的 `fdbserver` 进程数 | `1` |
| `replication-mode` | 复制模式：`single` / `double` / `triple` | `double` |
| `storage-engine` | 存储引擎：`ssd-2` / `ssd-redwood-1` / `memory` | `ssd-redwood-1` |
| `grv-proxies` | GRV proxy 进程数 | `1` |
| `commit-proxies` | Commit proxy 进程数 | `1` |
| `resolvers` | Resolver 进程数 | `1` |
| `clean-data` | 设为 `true` 在停止时清除数据目录 | `false` |

### `[meta.config]`

| 配置项 | 说明 | 默认值 |
|---|---|---|
| `datadir` | 数据目录（`$ID` 表示进程 ID） | `/var/lib/foundationdb/data/$ID` |
| `logdir` | 日志目录 | `/var/log/foundationdb` |
| `memory` | 内存限制（例如：`8GiB`） | - |

### `[flowmq.deploy]`

| 配置项 | 说明 | 默认值 |
|---|---|---|
| `on` | 目标节点范围（如 `all` 或指定节点集合） | - |
| `package` | FlowMQ 安装包路径（`.deb` 或 `.rpm`） | `/root/flowmq.deb` |
| `num` | 每台机器的 FlowMQ 实例数（与 `mqtt-num`/`kafka-num` 二选一） | `1` |
| `mqtt-num` | 每台机器的 FlowMQ 实例数（`class = mqtt`） | - |
| `kafka-num` | 每台机器的 FlowMQ 实例数（`class = kafka`） | - |
| `dashboard-port` | Dashboard 监听端口 | `5177` |

注意：`num` 与 `mqtt-num`/`kafka-num` 不可同时使用。

混合角色示例：

```toml
[flowmq.deploy]
on = "all"
package = "/root/flowmq.deb"
mqtt-num = 2
kafka-num = 1
```

### `[flowmq.config]`

| 配置项 | 说明 | 默认值 |
|---|---|---|
| `cluster-id` | FlowMQ 集群标识符 | 必填 |
| `cluster-file` | FDB `fdb.cluster` 文件路径 | `/etc/foundationdb/fdb.cluster` |
| `class` | 节点角色（如 `mqtt`、`kafka` 等）, 如果在 `[flowmq.deploy]` 里配置了 `mqtt-num` 或 `kafka-num` 会自动设置对应角色，无需填写 | - |
| `memory` | 内存限制（例如：`8GiB`） | - |

以下配置项在开启 Kafka 功能时需要配置：

::: tip 提示
可以使用 `fmqs3 init` 根据命令行提示填写信息生成如下参数。
:::

| 配置项 | 说明 | 默认值 |
|---|---|---|
| `knob-kafka-s3-host` | S3 端点地址。`path` 风格填纯端点（如 `s3.us-east-1.amazonaws.com`）；`virtualhost` 风格需带 bucket 前缀（如 `mybucket.s3.us-east-1.amazonaws.com`） | 必填 |
| `knob-kafka-s3-port` | S3 服务端口 | HTTPS 时通常为 `443`，HTTP 时如 MinIO 常用 `9000` |
| `knob-kafka-s3-region` | S3 存储区域（如 `us-east-1`、`cn-hangzhou`） | - |
| `knob-kafka-s3-bucket` | S3 存储桶名称 | 必填 |
| `knob-kafka-s3-bucket-prefix` | 存储桶内的对象前缀 | 默认为 cluster-id |
| `knob-kafka-s3-host-url-style` | URL 风格：`path`（`endpoint/bucket/key`）或 `virtualhost`（`bucket.endpoint/key`） | `path` |
| `knob-kafka-s3-disable-https` | 设为 `true` 禁用 HTTPS，使用 HTTP 明文传输 | `false` |
| `tls-ca-file` | 使用 HTTPS 访问 S3 时必须设置，指向系统 CA 证书包路径 | - |
| `knob-kafka-s3-auth-type` | 认证方式：`aksk`（静态 Access Key / Secret Key） | `aksk` |
| `knob-kafka-s3-access-key` | S3 Access Key（`aksk` 认证时必填） | - |
| `knob-kafka-s3-secret-key` | S3 Secret Key（`aksk` 认证时必填） | - |

常见 CA 证书包路径：
- Debian / Ubuntu：`/etc/ssl/certs/ca-certificates.crt`
- RHEL / CentOS：`/etc/pki/tls/certs/ca-bundle.crt`

各存储服务对 URL 风格的支持情况：

| 存储服务 | `path` | `virtualhost` |
|---|---|---|
| AWS S3 | 支持 | 支持 |
| 阿里云 OSS | 不支持 | 支持（唯一方式） |
| MinIO / 自建存储 | 支持 | 需 DNS 支持 |

::: tip 注意
`knob-kafka-s3-bucket` 始终为必填项。使用 `virtualhost` 风格时，`knob-kafka-s3-host` 必须以 `<bucket>.` 为前缀；使用 `path` 风格时则不能包含 bucket 前缀。
:::