From ccce8eef76c6d55dee99ca3db0a837f7bc689c82 Mon Sep 17 00:00:00 2001
From: NekoPunch <engineer.jyao@gmail.com>
Date: Thu, 9 Jul 2026 01:17:49 -0700
Subject: [PATCH] fix: pin collector docker image root path across versions

The collector Docker image baked the version number into its
container path (/opt/apache-hertzbeat-collector-${VERSION}-bin),
requiring users to update their logs/ext-lib volume mounts on every
upgrade. It also relied on a --build-arg VERSION that the nightly CI
workflow never passed, breaking the ADD/WORKDIR path resolution.

Extract the tarball via a version-agnostic glob and rename it to a
fixed /opt/hertzbeat-collector root, matching the version-independent
layout the server image already uses. The glob is restricted to
apache-hertzbeat-collector-[0-9]*-bin.tar.gz so it doesn't also match
the native collector package that ships alongside it in dist/, which
would otherwise make the extraction step ambiguous.

Fixes #2175
---
 home/docs/help/collector.md                            |  3 +++
 home/docs/start/docker-deploy.md                       |  2 ++
 .../current/start/docker-deploy.md                     |  2 ++
 script/docker/collector/Dockerfile                     | 10 +++++-----
 script/docker/collector/build.sh                       | 10 +++++-----
 5 files changed, 17 insertions(+), 10 deletions(-)

diff --git a/home/docs/help/collector.md b/home/docs/help/collector.md
index 0725b0c963d..2f27b10a78e 100644
--- a/home/docs/help/collector.md
+++ b/home/docs/help/collector.md
@@ -54,8 +54,11 @@ Parameters explanation:
 - `-e MODE=public`: Set the running mode (public or private), for public cluster or private cloud-edge mode.
 - `-e MANAGER_HOST=192.168.1.100`: Important! Set the IP address of the main HertzBeat server. Replace with your actual server IP.
 - `-e MANAGER_PORT=1158`: (Optional) Set the port of the main HertzBeat server, default is 1158.
+- `-v $(pwd)/ext-lib:/opt/hertzbeat-collector/ext-lib`: (Optional) Mount external JDBC driver jars to the local collector.
 - `-v $(pwd)/logs:/opt/hertzbeat-collector/logs`: (Optional) Mount the log files to the local host.
 
+The collector image keeps `/opt/hertzbeat-collector` as a version-independent root path, so `logs` and `ext-lib` mounts remain stable across upgrades.
+
 ## Operating Modes
 
 HertzBeat Collector supports two operating modes:
diff --git a/home/docs/start/docker-deploy.md b/home/docs/start/docker-deploy.md
index 767baa99d9f..bdeebc70e04 100644
--- a/home/docs/start/docker-deploy.md
+++ b/home/docs/start/docker-deploy.md
@@ -85,6 +85,7 @@ By deploying multiple HertzBeat Collectors, high availability, load balancing, a
    - `-e MANAGER_HOST=127.0.0.1` : Important, Set the main hertzbeat server ip host, must use the server host instead of 127.0.0.1.
    - `-e MANAGER_PORT=1158` :  (optional) Set the main hertzbeat server port, default 1158.
    - `-e HERTZBEAT_COLLECTOR_MYSQL_QUERY_ENGINE=auto` : (optional) Override the MySQL-compatible monitoring query path. Supported values: `auto`, `jdbc`, `r2dbc`.
+   - `-v $(pwd)/ext-lib:/opt/hertzbeat-collector/ext-lib` : (optional) Mount external JDBC driver jars to the collector.
    - `-v $(pwd)/logs:/opt/hertzbeat-collector/logs` : (optional) Mount the log file to the local host to facilitate viewing.
    - `--name hertzbeat-collector` : Naming container name hertzbeat-collector
    - `apache/hertzbeat-collector` : Use the [official application mirror](https://hub.docker.com/r/apache/hertzbeat-collector) to start the container, if the network times out, use `quay.io/tancloud/hertzbeat-collector` instead.
@@ -95,6 +96,7 @@ By deploying multiple HertzBeat Collectors, high availability, load balancing, a
    - Marked as optional parameters, non-mandatory items, if not needed, delete them.
    - The `127.0.0.1` in `MANAGER_HOST` needs to be replaced with the external IP address of the HertzBeat Server.
    - When mounting files, the first parameter is your custom local file address, and the second parameter is the container file address. Make sure you have this file locally when mounting.
+   - The collector keeps `/opt/hertzbeat-collector` as the stable container root path across upgrades.
    - You can execute `docker update --restart=always hertzbeat-collector` to configure the container to restart automatically.
    - If you want to use the host network mode to start Docker, you can use `docker run -d --network host .....`
 
diff --git a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/docker-deploy.md b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/docker-deploy.md
index 658b8fb41ce..061f4eb852e 100644
--- a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/docker-deploy.md
+++ b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/docker-deploy.md
@@ -83,6 +83,7 @@ HertzBeat Collector 是一个轻量级的数据采集器，用于采集并将数
    - `-e MANAGER_HOST=127.0.0.1` : 重要, 配置连接的 HertzBeat Server 地址，127.0.0.1 需替换为 HertzBeat Server 对外 IP 地址。
    - `-e MANAGER_PORT=1158` :  (可选) 配置连接的 HertzBeat Server 端口，默认 1158.
    - `-e HERTZBEAT_COLLECTOR_MYSQL_QUERY_ENGINE=auto` : (可选) 覆盖 MySQL 兼容监控查询链路。可选值：`auto`、`jdbc`、`r2dbc`。
+   - `-v $(pwd)/ext-lib:/opt/hertzbeat-collector/ext-lib` : (可选) 挂载外部 JDBC 驱动到采集器。
    - `-v $(pwd)/logs:/opt/hertzbeat-collector/logs` : (可选)挂载日志文件到本地主机方便查看
    - `--name hertzbeat-collector` : 命名容器名称为 hertzbeat-collector
    - `apache/hertzbeat-collector` : 使用[官方应用镜像](https://hub.docker.com/r/apache/hertzbeat-collector)来启动容器, 若网络超时可用`quay.io/tancloud/hertzbeat-collector`代替。
@@ -92,6 +93,7 @@ HertzBeat Collector 是一个轻量级的数据采集器，用于采集并将数
    - `MANAGER_HOST=127.0.0.1` 中的 `127.0.0.1` 需被替换为 HertzBeat Server 对外 IP 地址。
    - 标记为可选的参数，非必填项，若不需要则删除。
    - 挂载文件时，前面参数为你自定义本地文件地址，后面参数为容器内文件地址。挂载时请确保你本地已有此文件。
+   - 采集器容器会将 `/opt/hertzbeat-collector` 保持为稳定根路径，升级版本时无需调整 `logs` 和 `ext-lib` 的挂载目标。
    - 可执行```docker update --restart=always hertzbeat-collector```配置容器自动重启。
 
    :::
diff --git a/script/docker/collector/Dockerfile b/script/docker/collector/Dockerfile
index 13d8f661575..2aa8f810be1 100644
--- a/script/docker/collector/Dockerfile
+++ b/script/docker/collector/Dockerfile
@@ -17,21 +17,21 @@
 
 FROM eclipse-temurin:25-jdk
 
-MAINTAINER Apache HertzBeat "dev@hertzbeat.apache.org"
-
-ARG VERSION
+LABEL maintainer="Apache HertzBeat <dev@hertzbeat.apache.org>"
 
 # Install SSH
 RUN  sed -i 's#http://#https://#g' /etc/apt/sources.list.d/ubuntu.sources && \
     apt-get update && apt-get install -y openssh-server
 RUN mkdir -p /var/run/sshd
 
-ADD apache-hertzbeat-collector-${VERSION}-bin.tar.gz /opt/
+ADD apache-hertzbeat-collector-[0-9]*-bin.tar.gz /opt/
+
+RUN mv /opt/apache-hertzbeat-collector-[0-9]*-bin /opt/hertzbeat-collector
 
 ENV JAVA_OPTS ""
 ENV TZ=Asia/Shanghai
 ENV LANG=en_US.UTF-8
 
-WORKDIR /opt/apache-hertzbeat-collector-${VERSION}-bin/
+WORKDIR /opt/hertzbeat-collector/
 
 ENTRYPOINT ["./bin/entrypoint.sh"]
diff --git a/script/docker/collector/build.sh b/script/docker/collector/build.sh
index 03f93312b0d..9c73f012514 100644
--- a/script/docker/collector/build.sh
+++ b/script/docker/collector/build.sh
@@ -38,17 +38,17 @@ fi
 # docker compile context
 CONTEXT_DIR=`pwd`
 
-COMMAND="docker buildx build --platform linux/arm64,linux/amd64 -t apache/hertzbeat-collector:$VERSION -f $CURRENT_DIR/Dockerfile $CONTEXT_DIR --build-arg VERSION="$VERSION" --push"
+COMMAND="docker buildx build --platform linux/arm64,linux/amd64 -t apache/hertzbeat-collector:$VERSION -f $CURRENT_DIR/Dockerfile $CONTEXT_DIR --push"
 
-#COMMAND="docker buildx build --platform linux/arm64,linux/amd64 -t apache/hertzbeat-collector:latest -f $CURRENT_DIR/Dockerfile $CONTEXT_DIR --build-arg VERSION="$VERSION" --push"
+#COMMAND="docker buildx build --platform linux/arm64,linux/amd64 -t apache/hertzbeat-collector:latest -f $CURRENT_DIR/Dockerfile $CONTEXT_DIR --push"
 
-#COMMAND="docker buildx build --platform linux/arm64,linux/amd64 -t quay.io/tancloud/hertzbeat-collector:$VERSION -f $CURRENT_DIR/Dockerfile $CONTEXT_DIR --build-arg VERSION="$VERSION" --push"
+#COMMAND="docker buildx build --platform linux/arm64,linux/amd64 -t quay.io/tancloud/hertzbeat-collector:$VERSION -f $CURRENT_DIR/Dockerfile $CONTEXT_DIR --push"
 
-#COMMAND="docker buildx build --platform linux/arm64,linux/amd64 -t quay.io/tancloud/hertzbeat-collector:latest -f $CURRENT_DIR/Dockerfile $CONTEXT_DIR --build-arg VERSION="$VERSION" --push"
+#COMMAND="docker buildx build --platform linux/arm64,linux/amd64 -t quay.io/tancloud/hertzbeat-collector:latest -f $CURRENT_DIR/Dockerfile $CONTEXT_DIR --push"
 
 # Build Local
 
-#COMMAND="docker build -t apache/hertzbeat-collector:$VERSION -f $CURRENT_DIR/Dockerfile $CONTEXT_DIR --build-arg VERSION="$VERSION" "
+#COMMAND="docker build -t apache/hertzbeat-collector:$VERSION -f $CURRENT_DIR/Dockerfile $CONTEXT_DIR"
 
 echo "$COMMAND"