From 664a25334c723cd61982eb35d2ceeeb88e403b86 Mon Sep 17 00:00:00 2001 From: Duansg Date: Mon, 7 Sep 2026 09:45:10 +0800 Subject: [PATCH] [doc] align Docker Compose quick-start docs with required .env and loopback binding (#4359) Co-authored-by: Claude Opus 5 (1M context) --- home/docs/start/docker-compose-deploy.md | 19 +++++++- .../current/start/docker-compose-deploy.md | 17 ++++++- .../current/start/upgrade.md | 4 +- .../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 "> *.yaml *.md ext-lib/README + .env.example hertzbeat-mysql-iotdb @@ -47,6 +48,7 @@ http://maven.apache.org/ASSEMBLY/2.0.0 "> *.yaml *.md ext-lib/README + .env.example hertzbeat-mysql-tdengine @@ -58,6 +60,7 @@ http://maven.apache.org/ASSEMBLY/2.0.0 "> *.yaml *.md ext-lib/README + .env.example hertzbeat-mysql-victoria-metrics @@ -69,6 +72,7 @@ http://maven.apache.org/ASSEMBLY/2.0.0 "> *.yaml *.md ext-lib/README + .env.example hertzbeat-postgresql-victoria-metrics @@ -80,6 +84,7 @@ http://maven.apache.org/ASSEMBLY/2.0.0 "> *.yaml *.md ext-lib/README + .env.example hertzbeat-postgresql-greptimedb 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