This is an automated email from the ASF dual-hosted git repository.
Aias00 pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/hertzbeat.git
The following commit(s) were added to refs/heads/master by this push:
new 8e9f8da341 maintenance: scope quick-start listeners (#4295)
8e9f8da341 is described below
commit 8e9f8da3419e5c85107e56fe817d76e226aa374f
Author: Logic <[email protected]>
AuthorDate: Thu Aug 27 11:32:57 2026 +0800
maintenance: scope quick-start listeners (#4295)
Co-authored-by: Duansg <[email protected]>
Co-authored-by: aias00 <[email protected]>
---
.github/workflows/docker-compose-config-test.yml | 48 +++++++++++
home/docs/start/upgrade.md | 19 ++++-
script/ci/check-quickstart-compose.sh | 92 ++++++++++++++++++++++
script/docker-compose/README.md | 20 +++++
.../.env.example | 11 ++-
.../.gitignore} | 4 +-
.../hertzbeat-mysql-iotdb/docker-compose.yaml | 12 +--
.../.env.example | 11 ++-
.../.gitignore} | 4 +-
.../hertzbeat-mysql-tdengine/docker-compose.yaml | 10 +--
.../.env.example | 11 ++-
.../.gitignore} | 4 +-
.../docker-compose.yaml | 10 +--
.../hertzbeat-postgresql-greptimedb/.env.example | 24 ++++++
.../.gitignore} | 4 +-
.../hertzbeat-postgresql-greptimedb/README.md | 40 +++++++++-
.../hertzbeat-postgresql-greptimedb/README_CN.md | 34 +++++++-
.../docker-compose.yaml | 9 ++-
.../.env.example | 9 +++
.../docker-compose.yaml | 10 +--
20 files changed, 334 insertions(+), 52 deletions(-)
diff --git a/.github/workflows/docker-compose-config-test.yml
b/.github/workflows/docker-compose-config-test.yml
new file mode 100644
index 0000000000..ed259afc39
--- /dev/null
+++ b/.github/workflows/docker-compose-config-test.yml
@@ -0,0 +1,48 @@
+# 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
+
+permissions:
+ contents: read
+
+jobs:
+ quickstart-config:
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ steps:
+ - uses: actions/checkout@v4
+ - name: Validate quick-start listener bindings
+ run: sh script/ci/check-quickstart-compose.sh
diff --git a/home/docs/start/upgrade.md b/home/docs/start/upgrade.md
index a83e6f23ff..7aa220003f 100644
--- a/home/docs/start/upgrade.md
+++ b/home/docs/start/upgrade.md
@@ -62,15 +62,26 @@ Recommended upgrade steps:
### New OTLP/gRPC listener on port 14317
When `warehouse.store.greptime.enabled=true`, 1.9.0 additionally starts an
OTLP/gRPC listener on
-`0.0.0.0:14317` so exporters can push metrics, logs and traces over gRPC. The
packaged Dockerfile and
-the docker-compose files publish it unchanged, so the port is the same on
every deployment.
+`0.0.0.0:14317` inside the HertzBeat container so exporters can push metrics,
logs and traces over
+gRPC. The packaged Dockerfile exposes that container port. The repository's
five Docker Compose
+quick-start variants publish it as host port `14317`, bound to `127.0.0.1` by
default.
- **It is not the OpenTelemetry standard 4317.** An OTel Collector, Jaeger or
Tempo on the same host
normally holds 4317 already, and a clash on a published port makes `docker
compose up` fail
outright. HertzBeat serves OTLP/HTTP on its own port as well, so 14317 is
consistent with the rest
of the product.
-- Existing deployments gain one newly bound port. If your firewall or security
policy enumerates
- listening ports, add 14317.
+- Existing non-Compose deployments gain one newly bound port. If your firewall
or security policy
+ enumerates listening ports, add 14317.
+- Every 1.9.0 Docker Compose quick-start now binds all published ports to
`127.0.0.1` by default,
+ including `1157`, `1158`, `14317`, and the development database/time-series
ports. Upgrading an
+ older Compose checkout therefore preserves local access but intentionally
stops remote browser,
+ Collector, OTLP, and datastore access until explicitly configured.
+- For a remote Collector, copy the selected variant's `.env.example` to
`.env`, set
+ `HERTZBEAT_BIND_ADDRESS` to the manager's reachable address, and allow
`1158` only from Collector
+ source networks. This setting also controls `1157`; prefer a TLS reverse
proxy for remote web/API
+ access. Set `HERTZBEAT_OTLP_BIND_ADDRESS` separately only for trusted OTLP
senders. Before using a
+ wildcard address, replace default credentials and apply firewall or
security-group restrictions.
+ Render `docker compose config` and inspect every final host binding before
restarting.
- A port that cannot be bound does **not** stop HertzBeat: the failure is
logged and the process
starts without gRPC ingestion, while OTLP/HTTP on `/api/otlp/v1` keeps
working.
- To move the listener to 4317, or disable it, set these in `application.yml`
or through the matching
diff --git a/script/ci/check-quickstart-compose.sh
b/script/ci/check-quickstart-compose.sh
new file mode 100755
index 0000000000..24f0de50af
--- /dev/null
+++ b/script/ci/check-quickstart-compose.sh
@@ -0,0 +1,92 @@
+#!/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)
+temporary_directory=$(mktemp -d)
+trap 'rm -f "$temporary_directory"/*.json; rmdir "$temporary_directory"' EXIT
HUP INT TERM
+
+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
+}
+
+assert_all_bindings() {
+ config_file=$1
+ expected_host=$2
+
+ jq -e \
+ --arg expected_host "$expected_host" \
+ '[.services[]?.ports[]?] | length > 0 and all(.host_ip == $expected_host)'
\
+ "$config_file" > /dev/null
+}
+
+assert_non_hertzbeat_bindings() {
+ config_file=$1
+ expected_host=$2
+
+ jq -e \
+ --arg expected_host "$expected_host" \
+ '[.services | to_entries[] | select(.key != "hertzbeat") | .value.ports[]?]
+ | all(.host_ip == $expected_host)' \
+ "$config_file" > /dev/null
+}
+
+for variant in \
+ hertzbeat-mysql-iotdb \
+ hertzbeat-mysql-tdengine \
+ hertzbeat-mysql-victoria-metrics \
+ hertzbeat-postgresql-greptimedb \
+ hertzbeat-postgresql-victoria-metrics
+do
+
compose_file="${repository_root}/script/docker-compose/${variant}/docker-compose.yaml"
+ default_config="${temporary_directory}/${variant}-default.json"
+ override_config="${temporary_directory}/${variant}-override.json"
+
+ unset HERTZBEAT_BIND_ADDRESS HERTZBEAT_OTLP_BIND_ADDRESS
+ POSTGRES_PASSWORD=compose-config-test \
+ docker compose -f "$compose_file" config --format json > "$default_config"
+ HERTZBEAT_BIND_ADDRESS=192.0.2.10 \
+ HERTZBEAT_OTLP_BIND_ADDRESS=192.0.2.20 \
+ POSTGRES_PASSWORD=compose-config-test \
+ docker compose -f "$compose_file" config --format json > "$override_config"
+
+ assert_all_bindings "$default_config" 127.0.0.1
+ for service_port in 1157 1158; do
+ assert_binding "$override_config" hertzbeat "$service_port"
"$service_port" 192.0.2.10
+ done
+ assert_binding "$override_config" hertzbeat 14317 14317 192.0.2.20
+ assert_non_hertzbeat_bindings "$override_config" 127.0.0.1
+done
+
+echo "Quick-start Compose listener bindings are valid."
diff --git a/script/docker-compose/README.md b/script/docker-compose/README.md
index 62b6daf2e4..721c70550d 100644
--- a/script/docker-compose/README.md
+++ b/script/docker-compose/README.md
@@ -8,6 +8,26 @@ Notes:
- If you place `mysql-connector-j` in `ext-lib`, HertzBeat prefers JDBC after
restart.
- Oracle and DB2 still require external JDBC driver jars in `ext-lib`.
+## Listener scope for every quick-start variant
+
+All five Docker Compose variants publish host ports on `127.0.0.1` by
+default. This includes the HertzBeat listeners and the development database or
+time-series database ports. Containers still communicate over their internal
+`hertzbeat` network, so ordinary local use needs no override.
+
+- `1157` (web/API) and `1158` (manager/collector transport) use
+ `HERTZBEAT_BIND_ADDRESS`.
+- `14317` (OTLP/gRPC ingestion) uses the independent
+ `HERTZBEAT_OTLP_BIND_ADDRESS` override.
+- Database and time-series database development ports remain loopback-only.
+
+For a remote Collector, copy the selected variant's `.env.example` to `.env`
+and set `HERTZBEAT_BIND_ADDRESS` to a reachable manager address. Expose `1158`
+only to Collector source networks. Set `HERTZBEAT_OTLP_BIND_ADDRESS` separately
+only for trusted OTLP senders. Before using `0.0.0.0`, replace bundled/default
+credentials, apply firewall or security-group restrictions, and configure TLS.
+Run `docker compose config` to inspect the final bindings before startup.
+
- Use Postgresql + GreptimeDB as HertzBeat dependent storage ->
[HertzBeat+PostgreSQL+GreptimeDB Solution](hertzbeat-postgresql-greptimedb)
- Use Postgresql + VictoriaMetrics as HertzBeat dependent storage ->
[HertzBeat+PostgreSQL+VictoriaMetrics
Solution](hertzbeat-postgresql-victoria-metrics)
diff --git
a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
b/script/docker-compose/hertzbeat-mysql-iotdb/.env.example
similarity index 63%
copy from
script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
copy to script/docker-compose/hertzbeat-mysql-iotdb/.env.example
index 77aa295e58..0a4e8fb785 100644
--- a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
+++ b/script/docker-compose/hertzbeat-mysql-iotdb/.env.example
@@ -13,6 +13,11 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-# Copy this file to .env and set your own strong password before running
docker compose up
-POSTGRES_USER=root
-POSTGRES_PASSWORD=
+# Bind the 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
+
+# Bind OTLP/gRPC ingestion (14317) separately so enabling a remote Collector
does
+# not also expose telemetry ingestion. Change this only for trusted OTLP
senders.
+HERTZBEAT_OTLP_BIND_ADDRESS=127.0.0.1
diff --git
a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
b/script/docker-compose/hertzbeat-mysql-iotdb/.gitignore
similarity index 85%
copy from
script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
copy to script/docker-compose/hertzbeat-mysql-iotdb/.gitignore
index 77aa295e58..51384e37c9 100644
--- a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
+++ b/script/docker-compose/hertzbeat-mysql-iotdb/.gitignore
@@ -13,6 +13,4 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-# Copy this file to .env and set your own strong password before running
docker compose up
-POSTGRES_USER=root
-POSTGRES_PASSWORD=
+.env
diff --git a/script/docker-compose/hertzbeat-mysql-iotdb/docker-compose.yaml
b/script/docker-compose/hertzbeat-mysql-iotdb/docker-compose.yaml
index 0094eed6d0..9f23392be3 100644
--- a/script/docker-compose/hertzbeat-mysql-iotdb/docker-compose.yaml
+++ b/script/docker-compose/hertzbeat-mysql-iotdb/docker-compose.yaml
@@ -31,7 +31,7 @@ services:
retries: 5
start_period: 30s
ports:
- - '13306:3306'
+ - '127.0.0.1:13306:3306'
environment:
TZ: Asia/Shanghai
MARIADB_ROOT_PASSWORD: 123456
@@ -55,8 +55,8 @@ services:
environment:
TZ: Asia/Shanghai
ports:
- - "18181:8181"
- - "16667:6667"
+ - "127.0.0.1:18181:8181"
+ - "127.0.0.1:16667:6667"
volumes:
- ./dbdata/iotdbdata:/iotdb/data
networks:
@@ -82,10 +82,10 @@ services:
- ./ext-lib:/opt/hertzbeat/ext-lib
- ./logs:/opt/hertzbeat/logs
ports:
- - "1157:1157"
- - "1158:1158"
+ - "${HERTZBEAT_BIND_ADDRESS:-127.0.0.1}:1157:1157"
+ - "${HERTZBEAT_BIND_ADDRESS:-127.0.0.1}:1158:1158"
# OTLP/gRPC ingestion. 14317 rather than the OpenTelemetry standard
4317, which a local
# OTel Collector normally holds - and a clash on a published port stops
the container.
- - "14317:14317"
+ - "${HERTZBEAT_OTLP_BIND_ADDRESS:-127.0.0.1}:14317:14317"
networks:
- hertzbeat
diff --git
a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
b/script/docker-compose/hertzbeat-mysql-tdengine/.env.example
similarity index 63%
copy from
script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
copy to script/docker-compose/hertzbeat-mysql-tdengine/.env.example
index 77aa295e58..0a4e8fb785 100644
--- a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
+++ b/script/docker-compose/hertzbeat-mysql-tdengine/.env.example
@@ -13,6 +13,11 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-# Copy this file to .env and set your own strong password before running
docker compose up
-POSTGRES_USER=root
-POSTGRES_PASSWORD=
+# Bind the 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
+
+# Bind OTLP/gRPC ingestion (14317) separately so enabling a remote Collector
does
+# not also expose telemetry ingestion. Change this only for trusted OTLP
senders.
+HERTZBEAT_OTLP_BIND_ADDRESS=127.0.0.1
diff --git
a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
b/script/docker-compose/hertzbeat-mysql-tdengine/.gitignore
similarity index 85%
copy from
script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
copy to script/docker-compose/hertzbeat-mysql-tdengine/.gitignore
index 77aa295e58..51384e37c9 100644
--- a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
+++ b/script/docker-compose/hertzbeat-mysql-tdengine/.gitignore
@@ -13,6 +13,4 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-# Copy this file to .env and set your own strong password before running
docker compose up
-POSTGRES_USER=root
-POSTGRES_PASSWORD=
+.env
diff --git a/script/docker-compose/hertzbeat-mysql-tdengine/docker-compose.yaml
b/script/docker-compose/hertzbeat-mysql-tdengine/docker-compose.yaml
index 321798368b..c7e813fd6a 100644
--- a/script/docker-compose/hertzbeat-mysql-tdengine/docker-compose.yaml
+++ b/script/docker-compose/hertzbeat-mysql-tdengine/docker-compose.yaml
@@ -31,7 +31,7 @@ services:
retries: 5
start_period: 30s
ports:
- - '13306:3306'
+ - '127.0.0.1:13306:3306'
environment:
TZ: Asia/Shanghai
MARIADB_ROOT_PASSWORD: 123456
@@ -55,7 +55,7 @@ services:
environment:
TZ: Asia/Shanghai
ports:
- - "16041:6041"
+ - "127.0.0.1:16041:6041"
volumes:
- ./dbdata/taosdata:/var/lib/taos/
networks:
@@ -81,10 +81,10 @@ services:
- ./ext-lib:/opt/hertzbeat/ext-lib
- ./logs:/opt/hertzbeat/logs
ports:
- - "1157:1157"
- - "1158:1158"
+ - "${HERTZBEAT_BIND_ADDRESS:-127.0.0.1}:1157:1157"
+ - "${HERTZBEAT_BIND_ADDRESS:-127.0.0.1}:1158:1158"
# OTLP/gRPC ingestion. 14317 rather than the OpenTelemetry standard
4317, which a local
# OTel Collector normally holds - and a clash on a published port stops
the container.
- - "14317:14317"
+ - "${HERTZBEAT_OTLP_BIND_ADDRESS:-127.0.0.1}:14317:14317"
networks:
- hertzbeat
diff --git
a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
b/script/docker-compose/hertzbeat-mysql-victoria-metrics/.env.example
similarity index 63%
copy from
script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
copy to script/docker-compose/hertzbeat-mysql-victoria-metrics/.env.example
index 77aa295e58..0a4e8fb785 100644
--- a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
+++ b/script/docker-compose/hertzbeat-mysql-victoria-metrics/.env.example
@@ -13,6 +13,11 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-# Copy this file to .env and set your own strong password before running
docker compose up
-POSTGRES_USER=root
-POSTGRES_PASSWORD=
+# Bind the 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
+
+# Bind OTLP/gRPC ingestion (14317) separately so enabling a remote Collector
does
+# not also expose telemetry ingestion. Change this only for trusted OTLP
senders.
+HERTZBEAT_OTLP_BIND_ADDRESS=127.0.0.1
diff --git
a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
b/script/docker-compose/hertzbeat-mysql-victoria-metrics/.gitignore
similarity index 85%
copy from
script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
copy to script/docker-compose/hertzbeat-mysql-victoria-metrics/.gitignore
index 77aa295e58..51384e37c9 100644
--- a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
+++ b/script/docker-compose/hertzbeat-mysql-victoria-metrics/.gitignore
@@ -13,6 +13,4 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-# Copy this file to .env and set your own strong password before running
docker compose up
-POSTGRES_USER=root
-POSTGRES_PASSWORD=
+.env
diff --git
a/script/docker-compose/hertzbeat-mysql-victoria-metrics/docker-compose.yaml
b/script/docker-compose/hertzbeat-mysql-victoria-metrics/docker-compose.yaml
index 45e66a1efe..b1e5fd46c5 100644
--- a/script/docker-compose/hertzbeat-mysql-victoria-metrics/docker-compose.yaml
+++ b/script/docker-compose/hertzbeat-mysql-victoria-metrics/docker-compose.yaml
@@ -31,7 +31,7 @@ services:
retries: 5
start_period: 30s
ports:
- - '13306:3306'
+ - '127.0.0.1:13306:3306'
environment:
TZ: Asia/Shanghai
MARIADB_ROOT_PASSWORD: 123456
@@ -55,7 +55,7 @@ services:
environment:
TZ: Asia/Shanghai
ports:
- - "18428:8428"
+ - "127.0.0.1:18428:8428"
volumes:
- ./dbdata/tsdbdata:/victoria-metrics-data
networks:
@@ -81,10 +81,10 @@ services:
- ./ext-lib:/opt/hertzbeat/ext-lib
- ./logs:/opt/hertzbeat/logs
ports:
- - "1157:1157"
- - "1158:1158"
+ - "${HERTZBEAT_BIND_ADDRESS:-127.0.0.1}:1157:1157"
+ - "${HERTZBEAT_BIND_ADDRESS:-127.0.0.1}:1158:1158"
# OTLP/gRPC ingestion. 14317 rather than the OpenTelemetry standard
4317, which a local
# OTel Collector normally holds - and a clash on a published port stops
the container.
- - "14317:14317"
+ - "${HERTZBEAT_OTLP_BIND_ADDRESS:-127.0.0.1}:14317:14317"
networks:
- hertzbeat
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 0000000000..75883527bb
--- /dev/null
+++ b/script/docker-compose/hertzbeat-postgresql-greptimedb/.env.example
@@ -0,0 +1,24 @@
+# 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 the 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
+
+# Bind OTLP/gRPC ingestion (14317) separately so enabling a remote Collector
does
+# not also expose telemetry ingestion. Change this only for trusted OTLP
senders.
+HERTZBEAT_OTLP_BIND_ADDRESS=127.0.0.1
diff --git
a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
b/script/docker-compose/hertzbeat-postgresql-greptimedb/.gitignore
similarity index 85%
copy from
script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
copy to script/docker-compose/hertzbeat-postgresql-greptimedb/.gitignore
index 77aa295e58..51384e37c9 100644
--- a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
+++ b/script/docker-compose/hertzbeat-postgresql-greptimedb/.gitignore
@@ -13,6 +13,4 @@
# See the License for the specific language governing permissions and
# limitations under the License.
-# Copy this file to .env and set your own strong password before running
docker compose up
-POSTGRES_USER=root
-POSTGRES_PASSWORD=
+.env
diff --git a/script/docker-compose/hertzbeat-postgresql-greptimedb/README.md
b/script/docker-compose/hertzbeat-postgresql-greptimedb/README.md
index 82e8291811..62c8d1627a 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,46 @@
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.
+- `14317` is OTLP/gRPC telemetry ingestion. It uses a separate bind override so
+ enabling a remote Collector does not also expose ingestion.
+- `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
+OTLP, PostgreSQL, or GreptimeDB ports.
+
+For remote OTLP/gRPC senders, set `HERTZBEAT_OTLP_BIND_ADDRESS` separately and
+allow `14317` only from trusted telemetry source networks. Prefer an
authenticated
+and TLS-protected collector or gateway before traffic reaches HertzBeat.
+
+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 60347ce873..17a9a4e157 100644
--- a/script/docker-compose/hertzbeat-postgresql-greptimedb/README_CN.md
+++ b/script/docker-compose/hertzbeat-postgresql-greptimedb/README_CN.md
@@ -25,10 +25,42 @@
如果你希望 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 的通信端口。
+- `14317` 是 OTLP/gRPC 遥测写入端口。它使用独立的监听地址变量，避免仅为
+ 远程 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` 不会开放
+OTLP、PostgreSQL 或 GreptimeDB 端口。
+
+如果需要远程 OTLP/gRPC 写入，请单独设置 `HERTZBEAT_OTLP_BIND_ADDRESS`，并只允许
+可信遥测来源访问 `14317`。建议先通过具备认证和 TLS 的 Collector 或网关，再把流量
+转发到 HertzBeat。
+
+远程 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 011ded3475..c366329404 100644
--- a/script/docker-compose/hertzbeat-postgresql-greptimedb/docker-compose.yaml
+++ b/script/docker-compose/hertzbeat-postgresql-greptimedb/docker-compose.yaml
@@ -106,11 +106,14 @@ 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"
# OTLP/gRPC ingestion. 14317 rather than the OpenTelemetry standard
4317, which a local
# OTel Collector normally holds - and a clash on a published port stops
the container.
- - "14317:14317"
+ - "${HERTZBEAT_OTLP_BIND_ADDRESS:-127.0.0.1}:14317:14317"
networks:
- hertzbeat
diff --git
a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
b/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
index 77aa295e58..5211e8117a 100644
--- a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
+++ b/script/docker-compose/hertzbeat-postgresql-victoria-metrics/.env.example
@@ -16,3 +16,12 @@
# Copy this file to .env and set your own strong password before running
docker compose up
POSTGRES_USER=root
POSTGRES_PASSWORD=
+
+# Bind the 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
+
+# Bind OTLP/gRPC ingestion (14317) separately so enabling a remote Collector
does
+# not also expose telemetry ingestion. Change this only for trusted OTLP
senders.
+HERTZBEAT_OTLP_BIND_ADDRESS=127.0.0.1
diff --git
a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/docker-compose.yaml
b/script/docker-compose/hertzbeat-postgresql-victoria-metrics/docker-compose.yaml
index f1f5cfae09..1bd1f4c8ed 100644
---
a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/docker-compose.yaml
+++
b/script/docker-compose/hertzbeat-postgresql-victoria-metrics/docker-compose.yaml
@@ -32,7 +32,7 @@ services:
retries: 5
start_period: 30s
ports:
- - '15432:5432'
+ - '127.0.0.1:15432:5432'
environment:
POSTGRES_USER: ${POSTGRES_USER:-root}
POSTGRES_PASSWORD: "${POSTGRES_PASSWORD:?Please set POSTGRES_PASSWORD
(e.g., in .env)}"
@@ -58,7 +58,7 @@ services:
environment:
TZ: Asia/Shanghai
ports:
- - "18428:8428"
+ - "127.0.0.1:18428:8428"
volumes:
- ./dbdata/tsdbdata:/victoria-metrics-data
networks:
@@ -86,10 +86,10 @@ services:
- ./logs:/opt/hertzbeat/logs
- ./ext-lib:/opt/hertzbeat/ext-lib
ports:
- - "1157:1157"
- - "1158:1158"
+ - "${HERTZBEAT_BIND_ADDRESS:-127.0.0.1}:1157:1157"
+ - "${HERTZBEAT_BIND_ADDRESS:-127.0.0.1}:1158:1158"
# OTLP/gRPC ingestion. 14317 rather than the OpenTelemetry standard
4317, which a local
# OTel Collector normally holds - and a clash on a published port stops
the container.
- - "14317:14317"
+ - "${HERTZBEAT_OTLP_BIND_ADDRESS:-127.0.0.1}:14317:14317"
networks:
- hertzbeat
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
