maintenance: scope quick-start listeners

.github/workflows/docker-compose-config-test.yml

@@ -0,0 +1,44 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#   http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+name: Docker Compose Config
+
+on:
+  push:
+    branches: [ master, dev ]
+    paths:
+      - '.github/workflows/docker-compose-config-test.yml'
+      - 'script/ci/check-quickstart-compose.sh'
+      - 'script/docker-compose/**'
+  pull_request:
+    branches: [ master, dev ]
+    paths:
+      - '.github/workflows/docker-compose-config-test.yml'
+      - 'script/ci/check-quickstart-compose.sh'
+      - 'script/docker-compose/**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  quickstart-config:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Validate quick-start listener bindings
+        run: sh script/ci/check-quickstart-compose.sh

script/ci/check-quickstart-compose.sh

@@ -0,0 +1,60 @@
+#!/bin/sh
+
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -eu
+
+repository_root=$(CDPATH= cd -- "$(dirname -- "$0")/../.." && pwd)
+compose_file="${repository_root}/script/docker-compose/hertzbeat-postgresql-greptimedb/docker-compose.yaml"
+default_config=$(mktemp)
+override_config=$(mktemp)
+trap 'rm -f "$default_config" "$override_config"' EXIT HUP INT TERM
+
+docker compose -f "$compose_file" config --format json > "$default_config"
+HERTZBEAT_BIND_ADDRESS=192.0.2.10 \
+  docker compose -f "$compose_file" config --format json > "$override_config"
+
+assert_binding() {
+  config_file=$1
+  service=$2
+  target=$3
+  published=$4
+  host_ip=$5
+
+  jq -e \
+    --arg service "$service" \
+    --argjson target "$target" \
+    --arg published "$published" \
+    --arg host_ip "$host_ip" \
+    '.services[$service].ports
+      | any(.target == $target
+        and .published == $published
+        and .host_ip == $host_ip)' \
+    "$config_file" > /dev/null
+}
+
+for service_port in 1157 1158; do
+  assert_binding "$default_config" hertzbeat "$service_port" "$service_port" 127.0.0.1
+  assert_binding "$override_config" hertzbeat "$service_port" "$service_port" 192.0.2.10
+done
+
+assert_binding "$default_config" postgres 5432 15432 127.0.0.1
+for datastore_port in 4000 4001 4002 4003; do
+  assert_binding "$default_config" greptime "$datastore_port" "1${datastore_port}" 127.0.0.1
+done
+
+echo "Quick-start Compose listener bindings are valid."

script/docker-compose/hertzbeat-postgresql-greptimedb/.env.example

@@ -0,0 +1,20 @@
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Bind HertzBeat's web/API listener (1157) and manager/collector transport
+# (1158) to loopback for a local quick start. Set this to a reachable manager
+# address only when remote access is required and network controls are ready.
+HERTZBEAT_BIND_ADDRESS=127.0.0.1

script/docker-compose/hertzbeat-postgresql-greptimedb/README.md

@@ -12,7 +12,7 @@
     Docker version 20.10.12, build e91ed57
     ```
 
-##### docker compose deploys hertzbeat and its dependent services
+##### Docker Compose deploys HertzBeat and its dependent services
 
 1. Download the hertzbeat-docker-compose installation deployment script file
    The script file is located in `script/docker-compose/hertzbeat-postgresql-greptimedb` link [script/docker-compose](https://github.com/apache/hertzbeat/tree/master/script/docker-compose/hertzbeat-postgresql-greptimedb)
@@ -24,10 +24,40 @@
    If you want HertzBeat to prefer JDBC after restart, place `mysql-connector-j` in `ext-lib`.
    Oracle and DB2 still require external JDBC jars in `ext-lib`.
 
-3. Enter the deployment script docker-compose directory, execute
+3. Enter the deployment script Docker Compose directory and execute:
 
    `docker compose up -d`
 
+##### Listener scope and remote collectors
+
+The quick-start stack publishes every host port on `127.0.0.1` by default:
+
+- `1157` is the HertzBeat web UI and API.
+- `1158` is the manager/collector transport.
+- `15432` and `14000`–`14003` are the PostgreSQL and GreptimeDB development
+  endpoints. They remain loopback-only because containers use the internal
+  `hertzbeat` network.
+
+No configuration change is needed for ordinary local use. To connect a
+collector from another host, copy `.env.example` to `.env` and set
+`HERTZBEAT_BIND_ADDRESS` to an address that the collector can reach:
+
+```shell
+cp .env.example .env
+# Edit HERTZBEAT_BIND_ADDRESS, then render and inspect the final mappings.
+docker compose config
+```
+
+Expose `1158` only to the collector source networks. If remote browser/API
+access is also needed, expose `1157` through a TLS reverse proxy where
+possible. Before setting a wildcard address such as `0.0.0.0`, replace all
+bundled/default credentials, restrict access with a firewall or security
+group, and configure TLS. `HERTZBEAT_BIND_ADDRESS` does not expose the
+PostgreSQL or GreptimeDB ports.
+
+Configure a remote collector with the manager's reachable address and port
+`1158`; do not point it at `127.0.0.1` unless the manager runs on the same
+host.
 
 ##### Start exploring HertzBeat
 

script/docker-compose/hertzbeat-postgresql-greptimedb/README_CN.md

@@ -25,10 +25,36 @@
    如果你希望 HertzBeat 在重启后优先走 JDBC，可以把 `mysql-connector-j` 放到 `ext-lib`。
    Oracle、DB2 这类场景仍然需要把外部 JDBC 驱动放到 `ext-lib`。
 
-3. 进入部署脚本 docker-compose 目录, 执行
+3. 进入部署脚本 Docker Compose 目录，执行
 
    `docker compose up -d`
 
+##### 监听地址与远程 Collector
+
+快速启动方案默认将所有宿主机端口绑定到 `127.0.0.1`：
+
+- `1157` 是 HertzBeat Web UI 和 API 端口。
+- `1158` 是 Manager 与 Collector 的通信端口。
+- `15432`、`14000`–`14003` 是 PostgreSQL 和 GreptimeDB 的开发调试端口。
+  容器之间通过内部 `hertzbeat` 网络访问，所以这些端口始终只监听本机。
+
+普通本地使用不需要修改配置。如果其他主机上的 Collector 需要连接 Manager，
+请将 `.env.example` 复制为 `.env`，并把 `HERTZBEAT_BIND_ADDRESS` 修改为
+Collector 可以访问的 Manager 地址：
+
+```shell
+cp .env.example .env
+# 修改 HERTZBEAT_BIND_ADDRESS，然后检查最终端口映射。
+docker compose config
+```
+
+只允许 Collector 所在的来源网络访问 `1158`。如需远程访问 Web/API，建议通过
+TLS 反向代理开放 `1157`。如果必须设置为 `0.0.0.0`，请先替换所有内置/默认凭证，
+通过防火墙或安全组限制来源并配置 TLS。`HERTZBEAT_BIND_ADDRESS` 不会开放
+PostgreSQL 或 GreptimeDB 端口。
+
+远程 Collector 应配置 Manager 的可达地址和 `1158` 端口；除非 Manager 与
+Collector 位于同一主机，否则不能使用 `127.0.0.1`。
 
 ##### 开始探索HertzBeat   
 

script/docker-compose/hertzbeat-postgresql-greptimedb/docker-compose.yaml

@@ -32,8 +32,10 @@ services:
       timeout: 5s
       retries: 5
       start_period: 30s
+    # PostgreSQL is an implementation detail of this stack. Keep it local;
+    # containers reach it through the hertzbeat bridge network.
     ports:
-      - '15432:5432'
+      - '127.0.0.1:15432:5432'
     environment:
       POSTGRES_USER: root
       POSTGRES_PASSWORD: 123456
@@ -58,11 +60,13 @@ services:
       start_period: 30s
     environment:
         TZ: Asia/Shanghai
+    # GreptimeDB is an implementation detail of this stack. Keep all of its
+    # published protocols local and use the bridge network from containers.
     ports:
-      - "14000:4000"
-      - "14001:4001"
-      - "14002:4002"
-      - "14003:4003"
+      - "127.0.0.1:14000:4000"
+      - "127.0.0.1:14001:4001"
+      - "127.0.0.1:14002:4002"
+      - "127.0.0.1:14003:4003"
     volumes:
       - greptime-tsdb-data:/greptimedb_data
     command:
@@ -100,8 +104,11 @@ services:
       - ./conf/sureness.yml:/opt/hertzbeat/config/sureness.yml
       - ./logs:/opt/hertzbeat/logs
       - ./ext-lib:/opt/hertzbeat/ext-lib
+    # Keep the quick-start manager and collector listeners local by default.
+    # Set HERTZBEAT_BIND_ADDRESS explicitly only after replacing the bundled
+    # credentials and applying the required network access controls.
     ports:
-      - "1157:1157"
-      - "1158:1158"
+      - "${HERTZBEAT_BIND_ADDRESS:-127.0.0.1}:1157:1157"
+      - "${HERTZBEAT_BIND_ADDRESS:-127.0.0.1}:1158:1158"
     networks:
       - hertzbeat