maintenance: version cluster message envelopes

.gitignore

@@ -57,6 +57,10 @@ application-pg.yml
 /package.json
 /yarn.lock
 
+# Local deployment secrets
+/.env
+/script/docker-compose/*/.env
+
 # Local Codex workspace files
 .codex/
 AGENTS.md

README.md

@@ -59,18 +59,24 @@
 
 ##### 1：Install quickly via docker
 
-1. Just one command to get started
+1. Create and preserve two independent install-specific secrets, then start
+   HertzBeat. `COMMON_SECRET` is a 32-byte AES key shared by Manager and every
+   standalone Collector. `CLUSTER_AUTH_ACTIVE_SECRET` is a separate message
+   authentication secret. Do not commit `.env` or reuse one value for both.
 
    ```shell
-   docker run -d -p 1157:1157 -p 1158:1158 --name hertzbeat apache/hertzbeat
+   umask 077
+   printf 'COMMON_SECRET=%s\n' "$(openssl rand -hex 16)" > .env
+   printf 'CLUSTER_AUTH_ACTIVE_SECRET=%s\n' "$(openssl rand -hex 32)" >> .env
+   docker run -d --env-file .env -p 1157:1157 -p 1158:1158 --name hertzbeat apache/hertzbeat
    ```
 
 2. Access `http://localhost:1157` to start, default account: `admin/hertzbeat`
 
 3. Deploy collector clusters (Optional)
 
    ```shell
-   docker run -d -e IDENTITY=custom-collector-name -e MANAGER_HOST=127.0.0.1 -e MANAGER_PORT=1158 --name hertzbeat-collector apache/hertzbeat-collector
+   docker run -d --env-file .env -e IDENTITY=custom-collector-name -e MANAGER_HOST=127.0.0.1 -e MANAGER_PORT=1158 --name hertzbeat-collector apache/hertzbeat-collector
    ```
 
    - `-e IDENTITY=custom-collector-name` : set the collector unique identity name.
@@ -84,10 +90,14 @@ Detailed config refer to [Install HertzBeat via Docker](https://hertzbeat.apache
 ##### 2：Install via package
 
 1. Download the release package `apache-hertzbeat-xx-bin.tar.gz` [Download](https://hertzbeat.apache.org/docs/download)
-2. Configure the HertzBeat configuration yml file `hertzbeat/config/application.yml` (optional)
-3. Run command `$ ./bin/startup.sh ` or `bin/startup.bat`
-4. Access `http://localhost:1157` to start, default account: `admin/hertzbeat`
-5. Deploy collector clusters (Optional)
+2. Generate two independent secrets with the commands above. Configure the
+   same 16/24/32-byte `COMMON_SECRET` on Manager and every standalone
+   Collector, and separately configure the same
+   `CLUSTER_AUTH_ACTIVE_SECRET` on both sides. Preserve both across upgrades.
+3. Configure the HertzBeat configuration yml file `hertzbeat/config/application.yml` (optional)
+4. Run command `$ ./bin/startup.sh ` or `bin/startup.bat`
+5. Access `http://localhost:1157` to start, default account: `admin/hertzbeat`
+6. Deploy collector clusters (Optional)
     - Download the release package `apache-hertzbeat-collector-xx-bin.tar.gz` (JVM collector) or the native collector package for your platform, such as `apache-hertzbeat-collector-native-xx-linux-amd64-bin.tar.gz` or `apache-hertzbeat-collector-native-xx-windows-amd64-bin.zip`, to the new machine [Download](https://hertzbeat.apache.org/docs/download)
     - Configure the collector configuration yml file `hertzbeat-collector/config/application.yml`: unique `identity` name, running `mode` (public or private), hertzbeat `manager-host`, hertzbeat `manager-port`
       ```yaml

README_CN.md

@@ -58,18 +58,24 @@
 
 ##### 方式一：Docker 方式快速安装
 
-1. `docker` 环境仅需一条命令即可开始
+1. 创建并妥善保存两个相互独立的安装密钥。`COMMON_SECRET` 是 Manager 与所有
+   独立 Collector 必须完全相同的 32 字节 AES 密钥；
+   `CLUSTER_AUTH_ACTIVE_SECRET` 是另一份消息认证密钥。不要复用两个值，也不要
+   提交 `.env`。
 
    ```shell
-   docker run -d -p 1157:1157 -p 1158:1158 --name hertzbeat apache/hertzbeat
+   umask 077
+   printf 'COMMON_SECRET=%s\n' "$(openssl rand -hex 16)" > .env
+   printf 'CLUSTER_AUTH_ACTIVE_SECRET=%s\n' "$(openssl rand -hex 32)" >> .env
+   docker run -d --env-file .env -p 1157:1157 -p 1158:1158 --name hertzbeat apache/hertzbeat
    ```
 
 2. 浏览器访问 `http://localhost:1157` 即可开始，默认账号密码 `admin/hertzbeat`
 
 3. 部署采集器集群（可选）
 
    ```shell
-   docker run -d -e IDENTITY=custom-collector-name -e MANAGER_HOST=127.0.0.1 -e MANAGER_PORT=1158 --name hertzbeat-collector apache/hertzbeat-collector
+   docker run -d --env-file .env -e IDENTITY=custom-collector-name -e MANAGER_HOST=127.0.0.1 -e MANAGER_PORT=1158 --name hertzbeat-collector apache/hertzbeat-collector
    ```
 
    - `-e IDENTITY=custom-collector-name` : 配置此采集器的唯一性标识符名称，多个采集器名称不能相同，建议自定义英文名称。
@@ -83,10 +89,13 @@
 ##### 方式二：通过安装包安装
 
 1. 下载您系统环境对应的安装包 `apache-hertzbeat-xx-bin.tar.gz` [Download](https://hertzbeat.apache.org/docs/download)
-2. 配置 HertzBeat 的配置文件 `hertzbeat/config/application.yml` (可选)
-3. 部署启动 `$ ./bin/startup.sh ` 或 `bin/startup.bat`
-4. 浏览器访问 `http://localhost:1157` 即可开始，默认账号密码 `admin/hertzbeat`
-5. 部署采集器集群（可选）
+2. 按上面的命令生成两份独立密钥。在 Manager 和所有独立 Collector 上配置
+   完全相同且长度为 16/24/32 字节的 `COMMON_SECRET`，并另外配置相同的
+   `CLUSTER_AUTH_ACTIVE_SECRET`；升级时必须保留两者。
+3. 配置 HertzBeat 的配置文件 `hertzbeat/config/application.yml` (可选)
+4. 部署启动 `$ ./bin/startup.sh ` 或 `bin/startup.bat`
+5. 浏览器访问 `http://localhost:1157` 即可开始，默认账号密码 `admin/hertzbeat`
+6. 部署采集器集群（可选）
    - 下载采集器安装包 `apache-hertzbeat-collector-xx-bin.tar.gz`（JVM 采集器）或与你目标平台匹配的 Native 采集器安装包，例如 `apache-hertzbeat-collector-native-xx-linux-amd64-bin.tar.gz`、`apache-hertzbeat-collector-native-xx-windows-amd64-bin.zip`，到规划的另一台部署主机上 [Download](https://hertzbeat.apache.org/docs/download)
    - 配置采集器的配置文件 `hertzbeat-collector/config/application.yml` 里面的连接主 HertzBeat 服务的对外 IP，端口，当前采集器名称(需保证唯一性)等参数 `identity` `mode` (public or private) `manager-host` `manager-port`
      ```yaml

README_JP.md

@@ -57,18 +57,24 @@
 
 ##### 方式１：Docker
 
-1. `docker` で以下の指令を実行します：
+1. インストール専用の独立した 2 つのシークレットを作成します。
+   `COMMON_SECRET` は Manager とすべてのスタンドアロン Collector で同一にする
+   32 バイトの AES キーです。`CLUSTER_AUTH_ACTIVE_SECRET` は別のメッセージ認証
+   シークレットです。2 つの値を再利用せず、`.env` をコミットしないでください。
 
    ```shell
-   docker run -d -p 1157:1157 -p 1158:1158 --name hertzbeat apache/hertzbeat
+   umask 077
+   printf 'COMMON_SECRET=%s\n' "$(openssl rand -hex 16)" > .env
+   printf 'CLUSTER_AUTH_ACTIVE_SECRET=%s\n' "$(openssl rand -hex 32)" >> .env
+   docker run -d --env-file .env -p 1157:1157 -p 1158:1158 --name hertzbeat apache/hertzbeat
    ```
 
 2. スタート：`http://localhost:1157`にアクセスします。デフォルトのアカウントとパスワード：`admin/hertzbeat`。
 
 3. コレクタークラスタのデプロイメント（オプション）
 
    ```shell
-   docker run -d -e IDENTITY=custom-collector-name -e MANAGER_HOST=127.0.0.1 -e MANAGER_PORT=1158 --name hertzbeat-collector apache/hertzbeat-collector
+   docker run -d --env-file .env -e IDENTITY=custom-collector-name -e MANAGER_HOST=127.0.0.1 -e MANAGER_PORT=1158 --name hertzbeat-collector apache/hertzbeat-collector
    ```
 
    - `-e IDENTITY=custom-collector-name` ：コレクターのユニーク ID。
@@ -82,10 +88,14 @@
 ##### 方式２：インストールパッケージ
 
 1. リリースパッケージ `apache-hertzbeat-xx-bin.tar.gz` をダウンロードします [Download](https://hertzbeat.apache.org/docs/download)
-2. HertzBeat の設定ファイル `hertzbeat/config/application.yml` を編集します（任意）
-3. コマンド `$ ./bin/startup.sh` または `bin/startup.bat` を実行します
-4. ブラウザで `http://localhost:1157` にアクセスします。デフォルトのアカウントとパスワードは `admin/hertzbeat` です
-5. コレクタークラスタのデプロイメント（オプション）
+2. 上記のコマンドで 2 つの独立したシークレットを生成します。Manager とすべての
+   スタンドアロン Collector に同一で 16/24/32 バイトの `COMMON_SECRET` を設定し、
+   さらに同一の `CLUSTER_AUTH_ACTIVE_SECRET` を設定します。アップグレード時も
+   両方を保持してください。
+3. HertzBeat の設定ファイル `hertzbeat/config/application.yml` を編集します（任意）
+4. コマンド `$ ./bin/startup.sh` または `bin/startup.bat` を実行します
+5. ブラウザで `http://localhost:1157` にアクセスします。デフォルトのアカウントとパスワードは `admin/hertzbeat` です
+6. コレクタークラスタのデプロイメント（オプション）
    - 別ホストにコレクターのインストールパッケージ `apache-hertzbeat-collector-xx-bin.tar.gz`（JVM コレクター）または対象プラットフォーム向けの Native コレクターパッケージ（例: `apache-hertzbeat-collector-native-xx-linux-amd64-bin.tar.gz`、`apache-hertzbeat-collector-native-xx-windows-amd64-bin.zip`）をダウンロードします [Download](https://hertzbeat.apache.org/docs/download)
    - コレクターの設定ファイル `hertzbeat-collector/config/application.yml` を編集します
      ```yaml

hertzbeat-collector/hertzbeat-collector-basic/src/test/java/org/apache/hertzbeat/collector/dispatch/entrance/CollectServerTest.java

@@ -20,6 +20,7 @@
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.Mockito.mock;
@@ -39,7 +40,10 @@
 import org.apache.hertzbeat.common.concurrent.BackgroundTaskExecutor;
 import org.apache.hertzbeat.common.config.VirtualThreadProperties;
 import org.apache.hertzbeat.common.entity.message.ClusterMsg;
+import org.apache.hertzbeat.common.util.AesUtil;
 import org.apache.hertzbeat.remoting.RemotingClient;
+import org.apache.hertzbeat.remoting.netty.ClusterMessageAuthConfig;
+import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
@@ -79,15 +83,22 @@ class CollectServerTest {
 
     private CollectServer.CollectNettyEventListener collectNettyEventListener;
 
+    @AfterEach
+    void tearDown() {
+        AesUtil.setDefaultSecretKey(AesUtil.DEFAULT_ENCODE_RULES);
+    }
+
     @BeforeEach
     void setUp() {
 
         when(nettyProperties.getManagerHost()).thenReturn("127.0.0.1");
         when(nettyProperties.getManagerPort()).thenReturn(8080);
+        when(nettyProperties.getAuthentication()).thenReturn(new ClusterMessageAuthConfig());
         when(entranceProperties.getNetty()).thenReturn(nettyProperties);
         when(properties.getEntrance()).thenReturn(entranceProperties);
 
         collectServer = new CollectServer(collectJobService, timerDispatch, properties, threadPool, infoProperties);
+        ReflectionTestUtils.setField(collectServer, "commonSecret", "local-key-123456");
         collectNettyEventListener = collectServer.new CollectNettyEventListener();
     }
 
@@ -100,6 +111,31 @@ void testRun() throws Exception {
         collectServer.run();
 
         verify(remotingClient, times(1)).start();
+        assertEquals("local-key-123456", AesUtil.getDefaultSecretKey());
+    }
+
+    @Test
+    void testRunRejectsMissingCommonSecret() {
+        RemotingClient remotingClient = mock(RemotingClient.class);
+        ReflectionTestUtils.setField(collectServer, "remotingClient", remotingClient);
+        ReflectionTestUtils.setField(collectServer, "commonSecret", " ");
+
+        IllegalStateException exception = assertThrows(IllegalStateException.class, collectServer::run);
+
+        assertTrue(exception.getMessage().contains("COMMON_SECRET"));
+        verify(remotingClient, times(0)).start();
+    }
+
+    @Test
+    void testRunRejectsInvalidCommonSecretLength() {
+        RemotingClient remotingClient = mock(RemotingClient.class);
+        ReflectionTestUtils.setField(collectServer, "remotingClient", remotingClient);
+        ReflectionTestUtils.setField(collectServer, "commonSecret", "too-short");
+
+        IllegalStateException exception = assertThrows(IllegalStateException.class, collectServer::run);
+
+        assertTrue(exception.getMessage().contains("16, 24, or 32"));
+        verify(remotingClient, times(0)).start();
     }
 
     @Test

hertzbeat-collector/hertzbeat-collector-collector/src/main/java/org/apache/hertzbeat/collector/nativex/CollectorRuntimeHintsRegistrar.java

@@ -32,7 +32,6 @@
 import org.apache.arrow.vector.types.pojo.Field;
 import org.apache.arrow.vector.types.pojo.FieldType;
 import org.apache.arrow.vector.types.pojo.Schema;
-import org.apache.hertzbeat.common.entity.dto.ServerInfo;
 import org.springframework.aot.hint.BindingReflectionHintsRegistrar;
 import org.springframework.aot.hint.MemberCategory;
 import org.springframework.aot.hint.RuntimeHints;
@@ -55,7 +54,6 @@ public class CollectorRuntimeHintsRegistrar implements RuntimeHintsRegistrar {
     @Override
     public void registerHints(@NonNull RuntimeHints hints, ClassLoader classLoader) {
         BindingReflectionHintsRegistrar bindingRegistrar = new BindingReflectionHintsRegistrar();
-        registerType(bindingRegistrar, hints, ServerInfo.class);
         scanBindingPackage(classLoader, bindingRegistrar, hints, JOB_PACKAGE);
         scanBindingPackage(classLoader, bindingRegistrar, hints, JOB_PROTOCOL_PACKAGE);
         hints.reflection().registerType(NettyAllocationManager.class, MemberCategory.DECLARED_FIELDS);

hertzbeat-collector/hertzbeat-collector-collector/src/main/resources/application.yml

@@ -64,12 +64,24 @@ collector:
         mode: ${MODE:public}
         manager-host: ${MANAGER_HOST:}${MANAGER_IP:}
         manager-port: ${MANAGER_PORT:1158}
+        authentication:
+          # Required by default. Set optional explicitly only during a mixed-version rolling upgrade.
+          mode: ${CLUSTER_AUTH_MODE:required}
+          active-key-id: ${CLUSTER_AUTH_ACTIVE_KEY_ID:primary}
+          # Leave empty to derive a domain-separated key from common.secret.
+          active-secret: ${CLUSTER_AUTH_ACTIVE_SECRET:}
+          previous-key-id: ${CLUSTER_AUTH_PREVIOUS_KEY_ID:}
+          previous-secret: ${CLUSTER_AUTH_PREVIOUS_SECRET:}
+          max-clock-skew: ${CLUSTER_AUTH_MAX_CLOCK_SKEW:5m}
+          handshake-timeout: ${CLUSTER_AUTH_HANDSHAKE_TIMEOUT:3s}
 
 push:
   uri: "127.0.0.1:1157"
 
 
 common:
+  # Use the same key as Manager. Inject it through deployment configuration, never over Netty.
+  secret: ${COMMON_SECRET:}
   queue:
     type: netty