From 44d55e0a75dbc9a9813546bc80641f10f5fb5593 Mon Sep 17 00:00:00 2001 From: Logic Date: Thu, 30 Jul 2026 18:56:02 +0800 Subject: [PATCH] maintenance: scope quick-start listeners --- .../workflows/docker-compose-config-test.yml | 44 ++++++++++++++ script/ci/check-quickstart-compose.sh | 60 +++++++++++++++++++ .../.env.example | 20 +++++++ .../hertzbeat-postgresql-greptimedb/README.md | 34 ++++++++++- .../README_CN.md | 28 ++++++++- .../docker-compose.yaml | 21 ++++--- 6 files changed, 197 insertions(+), 10 deletions(-) create mode 100644 .github/workflows/docker-compose-config-test.yml create mode 100755 script/ci/check-quickstart-compose.sh create mode 100644 script/docker-compose/hertzbeat-postgresql-greptimedb/.env.example diff --git a/.github/workflows/docker-compose-config-test.yml b/.github/workflows/docker-compose-config-test.yml new file mode 100644 index 00000000000..4da7e2df068 --- /dev/null +++ b/.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 diff --git a/script/ci/check-quickstart-compose.sh b/script/ci/check-quickstart-compose.sh new file mode 100755 index 00000000000..7dc05aeaad8 --- /dev/null +++ b/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." diff --git a/script/docker-compose/hertzbeat-postgresql-greptimedb/.env.example b/script/docker-compose/hertzbeat-postgresql-greptimedb/.env.example new file mode 100644 index 00000000000..86dae967002 --- /dev/null +++ b/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 diff --git a/script/docker-compose/hertzbeat-postgresql-greptimedb/README.md b/script/docker-compose/hertzbeat-postgresql-greptimedb/README.md index 82e8291811f..ddf50d83083 100644 --- a/script/docker-compose/hertzbeat-postgresql-greptimedb/README.md +++ b/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 diff --git a/script/docker-compose/hertzbeat-postgresql-greptimedb/README_CN.md b/script/docker-compose/hertzbeat-postgresql-greptimedb/README_CN.md index 60347ce8732..7db7ca5e2fe 100644 --- a/script/docker-compose/hertzbeat-postgresql-greptimedb/README_CN.md +++ b/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 diff --git a/script/docker-compose/hertzbeat-postgresql-greptimedb/docker-compose.yaml b/script/docker-compose/hertzbeat-postgresql-greptimedb/docker-compose.yaml index 3ad6fc796f3..54781570aaf 100644 --- a/script/docker-compose/hertzbeat-postgresql-greptimedb/docker-compose.yaml +++ b/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