Hermes 搭建指南：从零到能收发第一条消息

这份指南的目标很窄：在一台干净的机器上把 Hermes 跑起来，并且发出、消费掉第一条消息。不谈调优，不谈多机房，把最小可用集群立起来再说。

拓扑：先看清楚要装几个东西

很多人第一次搭失败，是因为把它当成"一个进程"。Hermes 至少是三块：元数据存储、Broker 集群、接入层，加上可选的控制台。

Step 1 · 依赖与主机准备

先把宿主机弄对，后面九成的"启动失败"其实都在这一步。

# 句柄数：临时生效 + 永久写入
ulimit -n 65536
cat <<'EOF' | sudo tee -a /etc/security/limits.conf
*  soft  nofile  65536
*  hard  nofile  65536
EOF

# 内核参数：连接积压与端口回收
cat <<'EOF' | sudo tee /etc/sysctl.d/99-hermes.conf
net.core.somaxconn = 32768
net.ipv4.tcp_max_syn_backlog = 16384
vm.max_map_count = 262144
vm.swappiness = 1
EOF
sudo sysctl --system

# 数据目录（独立盘挂在这里）
sudo mkdir -p /data/hermes/{store,meta,logs}
sudo chown -R 1000:1000 /data/hermes

Step 2 · 容器编排

单机验证用 compose 就够。三个 Broker 跑在同一台机器上只是为了走通流程，生产必须分散到不同物理机，否则副本没有意义。

docker-compose.yml

version: "3.8"

x-broker-common: &broker-common
  image: hermes/broker:1.8.2
  restart: unless-stopped
  environment:
    HERMES_META_ADDR: "meta:2379"
    HERMES_HEAP_OPTS: "-Xms4g -Xmx4g -XX:+UseG1GC"
    HERMES_STORE_PATH: "/data/store"
  ulimits:
    nofile: { soft: 65536, hard: 65536 }
  depends_on: [meta]

services:
  meta:
    image: hermes/meta:1.8.2
    environment:
      META_DATA_DIR: "/data/meta"
      META_INITIAL_CLUSTER: "meta=http://meta:2380"
    volumes:
      - /data/hermes/meta:/data/meta
    ports: ["2379:2379"]

  broker-0:
    <<: *broker-common
    environment:
      HERMES_BROKER_ID: "0"
      HERMES_BROKER_ROLE: "leader"
    volumes: ["/data/hermes/store/0:/data/store"]

  broker-1:
    <<: *broker-common
    environment: { HERMES_BROKER_ID: "1" }
    volumes: ["/data/hermes/store/1:/data/store"]

  broker-2:
    <<: *broker-common
    environment: { HERMES_BROKER_ID: "2" }
    volumes: ["/data/hermes/store/2:/data/store"]

  proxy:
    image: hermes/proxy:1.8.2
    environment:
      HERMES_META_ADDR: "meta:2379"
    ports: ["9876:9876", "8080:8080"]
    depends_on: [broker-0, broker-1, broker-2]

docker compose up -d
docker compose ps            # 五个容器都应该是 running
docker compose logs -f proxy # 等到出现 "proxy started, listening on 9876"

Step 3 · 元数据初始化

集群起来之后是空的，需要先建租户和 topic。这一步很多文档一笔带过，但分区数一旦定下来，后面改的代价很大。

# 建租户（命名空间隔离，多业务共用集群时必须做）
hermesctl tenant create --name iot --quota-msg-per-sec 20000

# 建 topic：分区数 = 期望的最大并行消费度
hermesctl topic create \
  --tenant iot \
  --name device.telemetry \
  --partitions 12 \
  --replicas 3 \
  --retention 72h

# 建消费组
hermesctl group create --tenant iot --topic device.telemetry --name analytics

# 确认
hermesctl topic describe --tenant iot --name device.telemetry

Step 4 · 接入方配置

Spring Boot 服务侧的最小配置。注意几个默认值不太友好的地方，我在注释里标出来了。

application.yml

hermes:
  endpoint: hermes-proxy.internal:9876
  tenant: iot
  producer:
    # 默认 async。要求不丢就必须显式改 sync + acks=all
    ack-mode: sync
    acks: all
    # 默认 0，即失败直接抛。业务侧几乎总要改
    retries: 3
    retry-backoff: 200ms
    # 攒批：吞吐和延迟的唯一旋钮
    batch-size: 256
    linger: 20ms
  consumer:
    group: analytics
    # 默认 latest —— 新消费组会跳过历史消息，首次接入常踩
    offset-reset: earliest
    max-poll-records: 200
    # 必须大于业务处理 max-poll-records 条的最坏耗时，否则会被判死反复重平衡
    max-poll-interval: 5m

Producer.java

@Service
public class TelemetryPublisher {

    private final HermesTemplate hermes;

    public void publish(String deviceSn, Telemetry t) {
        // key 决定分区。用 deviceSn 保证同一设备的消息严格有序
        hermes.send("device.telemetry", deviceSn, t)
              .whenComplete((r, e) -> {
                  if (e != null) {
                      log.error("publish failed sn={}", deviceSn, e);
                      // 落本地表，由补偿任务重发。不要在这里同步重试
                      outbox.save(deviceSn, t);
                  }
              });
    }
}

Step 5 · 上线前必须验证的七件事

能收发消息只说明装对了，不说明能上线。这七条我每次都跑一遍。

常见故障与对应现象