[doc] align Docker Compose quick-start docs with required .env and loopback binding

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**
 

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**
 

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 的端口映射：
 

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>

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
 

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