This is an automated email from the ASF dual-hosted git repository.
Duansg 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 664a25334c [doc] align Docker Compose quick-start docs with required
.env and loopback binding (#4359)
664a25334c is described below
commit 664a25334c723cd61982eb35d2ceeeb88e403b86
Author: Duansg <[email protected]>
AuthorDate: Mon Sep 7 09:45:10 2026 +0800
[doc] align Docker Compose quick-start docs with required .env and loopback
binding (#4359)
Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
---
home/docs/start/docker-compose-deploy.md | 19 ++++++++-
.../current/start/docker-compose-deploy.md | 17 +++++++-
.../current/start/upgrade.md | 4 +-
script/assembly/server/assembly-docker-compose.xml | 5 +++
.../README.md | 48 +++++++++++++++++++++-
.../README_CN.md | 43 ++++++++++++++++++-
6 files changed, 129 insertions(+), 7 deletions(-)
diff --git a/home/docs/start/docker-compose-deploy.md
b/home/docs/start/docker-compose-deploy.md
index 38e1319032..e21b01c78b 100644
--- a/home/docs/start/docker-compose-deploy.md
+++ b/home/docs/start/docker-compose-deploy.md
@@ -39,6 +39,15 @@ Run the `docker compose version` command to check if you
have a Docker Compose e
cd hertzbeat-postgresql-victoria-metrics
```
+ - Create the `.env` file and set the database password
+
+ > `POSTGRES_PASSWORD` is required. `docker compose up` refuses to start
without it.
+
+ ```shell
+ cp .env.example .env
+ # Edit .env and set POSTGRES_PASSWORD to a strong password of your own
+ ```
+
- One-click start
> Run script in `hertzbeat-postgresql-victoria-metrics` directory
@@ -56,7 +65,15 @@ Run the `docker compose version` command to check if you
have a Docker Compose e
```
3. Start exploring HertzBeat
- Access [http://ip:1157/](http://ip:1157/) in the browser to start exploring
and using it. The default account password is admin/hertzbeat.
+ Access [http://localhost:1157/](http://localhost:1157/) in the browser to
start exploring and using it. The default account password is admin/hertzbeat.
+
+ :::note
+
+ The quick-start stack publishes every host port on `127.0.0.1` by default,
so the web UI is reachable only from the machine running Docker. To open it to
other hosts, set `HERTZBEAT_BIND_ADDRESS` in `.env` to an address those hosts
can reach (a TLS reverse proxy is preferred over a wildcard address such as
`0.0.0.0`), then run `docker compose config` to inspect the final port bindings
and restart with `docker compose up -d`.
+
+ This setting also opens `1158` for remote Collectors; `14317` (OTLP/gRPC)
is controlled separately by `HERTZBEAT_OTLP_BIND_ADDRESS`. See the `README.md`
of the deployment solution for details.
+
+ :::
**HAVE FUN**
diff --git
a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/docker-compose-deploy.md
b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/docker-compose-deploy.md
index a956a0cc8a..021cb28003 100644
---
a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/docker-compose-deploy.md
+++
b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/docker-compose-deploy.md
@@ -39,6 +39,15 @@ sidebar_label: Docker Compose方式安装
cd hertzbeat-postgresql-victoria-metrics
```
+ - 创建 `.env` 文件并设置数据库密码
+
+ > `POSTGRES_PASSWORD` 为必填项，未设置时 `docker compose up` 会直接报错退出。
+
+ ```shell
+ cp .env.example .env
+ # 编辑 .env，将 POSTGRES_PASSWORD 设置为你自己的强密码
+ ```
+
- 一键启动
> 在 `hertzbeat-postgresql-victoria-metrics` 目录下执行以下命令
@@ -56,7 +65,13 @@ sidebar_label: Docker Compose方式安装
```
3. 开始探索 HertzBeat
- 浏览器访问 [http://ip:1157/](http://ip:1157/) 即可开始探索使用，默认账户密码 admin/hertzbeat。
+ 浏览器访问 [http://localhost:1157/](http://localhost:1157/) 即可开始探索使用，默认账户密码
admin/hertzbeat。
+
+ :::note
+
+ 快速启动方案默认将所有宿主机端口绑定到 `127.0.0.1`，因此 Web 页面只能在运行 Docker 的本机访问。如需从其他主机访问，请在
`.env` 中把 `HERTZBEAT_BIND_ADDRESS` 设置为其他主机可达的地址（建议通过 TLS 反向代理开放，而不是直接使用
`0.0.0.0` 这类通配地址），然后执行 `docker compose config` 检查最终端口映射，再重新执行 `docker compose
up -d`。该变量同时会开放 `1158` 供远程 Collector 连接；`14317`（OTLP/gRPC）由独立的
`HERTZBEAT_OTLP_BIND_ADDRESS` 控制。详见部署方案目录下的 `README.md`。
+
+ :::
**HAVE FUN**
diff --git
a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/upgrade.md
b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/upgrade.md
index b6026a6fad..b7482ed543 100644
--- a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/upgrade.md
+++ b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/upgrade.md
@@ -58,10 +58,12 @@ HertzBeat 的元数据信息保存在 H2 或 Mysql, PostgreSQL 关系型数据
### 新增 OTLP/gRPC 监听端口 14317
-当 `warehouse.store.greptime.enabled=true` 时，1.9.0 会额外启动一个 OTLP/gRPC 监听器，绑定
`0.0.0.0:14317`，供 exporter 通过 gRPC 推送指标、日志与链路。官方 Dockerfile 与 docker-compose
原样发布该端口，因此所有部署方式下端口一致。
+当 `warehouse.store.greptime.enabled=true` 时，1.9.0 会额外启动一个 OTLP/gRPC 监听器，绑定
`0.0.0.0:14317`，供 exporter 通过 gRPC 推送指标、日志与链路。官方 Dockerfile 会暴露该容器端口；仓库内的五个
Docker Compose 快速启动方案将其发布为宿主机端口 `14317`，并默认绑定到 `127.0.0.1`。
- **这里没有使用 OpenTelemetry 标准的 4317。** 同机的 OTel Collector、Jaeger 或 Tempo 通常已经占着
4317，而已发布端口一旦冲突，`docker compose up` 会直接失败。HertzBeat 的 OTLP/HTTP 同样走自有端口，因此
14317 与产品其余部分是一致的。
- 存量部署升级后会多出一个监听端口。如果你的防火墙或安全策略按端口清单管理，请把 14317 加进去。
+- 1.9.0 的所有 Docker Compose 快速启动方案现在默认把全部已发布端口绑定到 `127.0.0.1`，包括
`1157`、`1158`、`14317` 以及开发用的数据库/时序库端口。在旧的 Compose
检出目录上升级后，本机访问不受影响，但远程浏览器、Collector、OTLP 和数据库访问会被有意关闭，直到显式配置为止。
+- 如需接入远程 Collector，请把所选方案目录下的 `.env.example` 复制为 `.env`，将
`HERTZBEAT_BIND_ADDRESS` 设置为 Manager 的可达地址，并只允许 Collector 来源网络访问 `1158`。该变量同时控制
`1157`；远程访问 Web/API 时建议使用 TLS 反向代理。仅在有可信 OTLP 发送方时单独设置
`HERTZBEAT_OTLP_BIND_ADDRESS`。在使用通配地址前，请先替换默认凭证并配置防火墙或安全组限制。重启前执行 `docker
compose config`，逐项检查最终的宿主机端口绑定。
- 端口绑定失败**不会**导致 HertzBeat 启动失败：失败会被记录到日志，进程在没有 gRPC
接收能力的情况下继续启动，`/api/otlp/v1` 上的 OTLP/HTTP 不受影响。
- 如需把监听器改到 4317 或关闭它，可在 `application.yml` 中配置，或使用对应的环境变量，并同步修改 docker-compose
的端口映射：
diff --git a/script/assembly/server/assembly-docker-compose.xml
b/script/assembly/server/assembly-docker-compose.xml
index 2654ed2ef1..7849e96390 100644
--- a/script/assembly/server/assembly-docker-compose.xml
+++ b/script/assembly/server/assembly-docker-compose.xml
@@ -36,6 +36,7 @@ http://maven.apache.org/ASSEMBLY/2.0.0 ">
<include>*.yaml</include>
<include>*.md</include>
<include>ext-lib/README</include>
+ <include>.env.example</include>
</includes>
<outputDirectory>hertzbeat-mysql-iotdb</outputDirectory>
</fileSet>
@@ -47,6 +48,7 @@ http://maven.apache.org/ASSEMBLY/2.0.0 ">
<include>*.yaml</include>
<include>*.md</include>
<include>ext-lib/README</include>
+ <include>.env.example</include>
</includes>
<outputDirectory>hertzbeat-mysql-tdengine</outputDirectory>
</fileSet>
@@ -58,6 +60,7 @@ http://maven.apache.org/ASSEMBLY/2.0.0 ">
<include>*.yaml</include>
<include>*.md</include>
<include>ext-lib/README</include>
+ <include>.env.example</include>
</includes>
<outputDirectory>hertzbeat-mysql-victoria-metrics</outputDirectory>
</fileSet>
@@ -69,6 +72,7 @@ http://maven.apache.org/ASSEMBLY/2.0.0 ">
<include>*.yaml</include>
<include>*.md</include>
<include>ext-lib/README</include>
+ <include>.env.example</include>
</includes>
<outputDirectory>hertzbeat-postgresql-victoria-metrics</outputDirectory>
</fileSet>
@@ -80,6 +84,7 @@ http://maven.apache.org/ASSEMBLY/2.0.0 ">
<include>*.yaml</include>
<include>*.md</include>
<include>ext-lib/README</include>
+ <include>.env.example</include>
</includes>
<outputDirectory>hertzbeat-postgresql-greptimedb</outputDirectory>
</fileSet>
diff --git
a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/README.md
b/script/docker-compose/hertzbeat-postgresql-victoria-metrics/README.md
index a999460c94..dce5311f14 100644
--- a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/README.md
+++ b/script/docker-compose/hertzbeat-postgresql-victoria-metrics/README.md
@@ -1,4 +1,4 @@
-## docker-compose deployment HertzBeat+PostgreSQL+IoTDB solution
+## docker-compose deployment HertzBeat+PostgreSQL+VictoriaMetrics solution
> The docker-compose deployment scheme uses PostgreSQL + VictoriaMetrics as
> the dependent storage service of HertzBeat.
> This solution will start three container services PostgreSQL,
> VictoriaMetrics, HertzBeat
@@ -24,10 +24,54 @@
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 create `.env` from
`.env.example`
+
+ `POSTGRES_PASSWORD` is required; `docker compose up` refuses to start
without it.
+
+ ```shell
+ cp .env.example .env
+ # Edit .env and set POSTGRES_PASSWORD to a strong password of your own
+ ```
+
+4. 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 `18428` are the PostgreSQL and VictoriaMetrics 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, edit `.env` and set `HERTZBEAT_BIND_ADDRESS` to
+an address that the collector can reach:
+
+```shell
+# Edit HERTZBEAT_BIND_ADDRESS in .env, 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 VictoriaMetrics 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-victoria-metrics/README_CN.md
b/script/docker-compose/hertzbeat-postgresql-victoria-metrics/README_CN.md
index dc9c386147..3305f4e915 100644
--- a/script/docker-compose/hertzbeat-postgresql-victoria-metrics/README_CN.md
+++ b/script/docker-compose/hertzbeat-postgresql-victoria-metrics/README_CN.md
@@ -1,4 +1,4 @@
-## docker-compose部署 HertzBeat+Postgresql+IoTDB 方案
+## docker-compose部署 HertzBeat+Postgresql+VictoriaMetrics 方案
- 如果想自己本地快速部署的话，可以参考下面进行操作。
@@ -25,10 +25,49 @@
如果你希望 HertzBeat 在重启后优先走 JDBC，可以把 `mysql-connector-j` 放到 `ext-lib`。
Oracle、DB2 这类场景仍然需要把外部 JDBC 驱动放到 `ext-lib`。
-3. 进入部署脚本 docker-compose 目录, 执行
+3. 进入部署脚本 docker-compose 目录，将 `.env.example` 复制为 `.env` 并设置数据库密码
+
+ `POSTGRES_PASSWORD` 为必填项，未设置时 `docker compose up` 会直接报错退出。
+
+ ```shell
+ cp .env.example .env
+ # 编辑 .env，将 POSTGRES_PASSWORD 设置为你自己的强密码
+ ```
+
+4. 执行
`docker compose up -d`
+##### 监听地址与远程 Collector
+
+快速启动方案默认将所有宿主机端口绑定到 `127.0.0.1`：
+
+- `1157` 是 HertzBeat Web UI 和 API 端口。
+- `1158` 是 Manager 与 Collector 的通信端口。
+- `14317` 是 OTLP/gRPC 遥测写入端口。它使用独立的监听地址变量，避免仅为
+ 远程 Collector 开放网络时同时暴露遥测写入。
+- `15432`、`18428` 是 PostgreSQL 和 VictoriaMetrics 的开发调试端口。
+ 容器之间通过内部 `hertzbeat` 网络访问，所以这些端口始终只监听本机。
+
+普通本地使用不需要修改配置。如果其他主机上的 Collector 需要连接 Manager，
+请编辑 `.env`，把 `HERTZBEAT_BIND_ADDRESS` 修改为 Collector 可以访问的 Manager 地址：
+
+```shell
+# 修改 .env 中的 HERTZBEAT_BIND_ADDRESS，然后检查最终端口映射。
+docker compose config
+```
+
+只允许 Collector 所在的来源网络访问 `1158`。如需远程访问 Web/API，建议通过
+TLS 反向代理开放 `1157`。如果必须设置为 `0.0.0.0`，请先替换所有内置/默认凭证，
+通过防火墙或安全组限制来源并配置 TLS。`HERTZBEAT_BIND_ADDRESS` 不会开放
+OTLP、PostgreSQL 或 VictoriaMetrics 端口。
+
+如果需要远程 OTLP/gRPC 写入，请单独设置 `HERTZBEAT_OTLP_BIND_ADDRESS`，并只允许
+可信遥测来源访问 `14317`。建议先通过具备认证和 TLS 的 Collector 或网关，再把流量
+转发到 HertzBeat。
+
+远程 Collector 应配置 Manager 的可达地址和 `1158` 端口；除非 Manager 与
+Collector 位于同一主机，否则不能使用 `127.0.0.1`。
##### 开始探索HertzBeat
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
