From 17d024794c8d8d7bfbca95d2e8c5ba6b9388f979 Mon Sep 17 00:00:00 2001 From: mohit07dec Date: Sun, 21 Dec 2025 00:11:49 +0530 Subject: [PATCH 1/3] [docs]feature: add H2 database (testing-only) guidance --- home/docs/start/h2-database.md | 73 +++++++++++++++++++ home/sidebars.json | 1 + .../version-v1.6.x/start/h2-database.md | 73 +++++++++++++++++++ .../version-v1.6.x-sidebars.json | 1 + 4 files changed, 148 insertions(+) create mode 100644 home/docs/start/h2-database.md create mode 100644 home/versioned_docs/version-v1.6.x/start/h2-database.md diff --git a/home/docs/start/h2-database.md b/home/docs/start/h2-database.md new file mode 100644 index 00000000000..f8945ca8cde --- /dev/null +++ b/home/docs/start/h2-database.md @@ -0,0 +1,73 @@ +--- +id: h2-database +title: Using H2 Database (Testing Only) +sidebar_label: H2 (Testing only) +--- + +Apache HertzBeat uses an embedded H2 database by default to store metadata (monitoring tasks, alarm data, configuration, etc.). This default is intended for quick start, demos, and local development. + +:::caution Not for production +H2 is **not** designed to run in an adversarial environment, and HertzBeat's H2 usage is **not recommended for production deployments**. + +If an attacker can access your H2 database (for example via an exposed H2 Web Console or any other path that allows executing SQL), H2 features such as `CREATE ALIAS` can be abused to execute arbitrary Java code and potentially take full control of the HertzBeat server. + +For background, see the H2 security documentation: https://h2database.com/html/security.html +::: + +## Recommendation for production + +Use a production-grade database for HertzBeat metadata storage instead of H2: + +- MySQL: [Use MYSQL Replace H2 Database to Store Metadata(Optional)](./mysql-change) +- PostgreSQL: [Use PostgreSQL Replace H2 Database to Store Metadata(Optional)](./postgresql-change) + +## Safe ways to use H2 (sandbox only) + +If you still choose to run HertzBeat with H2 for testing, keep the deployment sandboxed and minimize exposure: + +1. Prefer **embedded/file mode** (the default) and avoid running H2 in TCP server mode. +2. Do **not** expose H2 endpoints to untrusted networks. +3. Treat the H2 data store as **ephemeral** (backup/export your HertzBeat configuration if you need it). + +## Default datasource configuration (example) + +Your `application.yml` typically looks similar to this when using H2: + +```yaml +spring: + datasource: + driver-class-name: org.h2.Driver + username: sa + password: 123456 + url: jdbc:h2:./data/hertzbeat;MODE=MYSQL + hikari: + max-lifetime: 120000 +``` + +> Notes +> - The defaults may vary by version and packaging. +> - If you run via Docker, you should mount the `data/` directory so your local test data persists. + +## H2 Web Console (high risk) + +H2 provides a Web Console that can execute SQL against your database. Enabling it makes it much easier to accidentally expose a powerful administrative surface. + +:::danger Do not enable in production +Only enable the H2 console for local, temporary troubleshooting in a sandbox environment. +::: + +To enable it, set: + +```yaml +spring: + h2: + console: + path: /h2-console + enabled: true +``` + +### If you enable the console, lock it down + +- Ensure it is only reachable from `localhost` or a tightly controlled admin network. +- Review your `sureness.yml`: many deployments configure `/h2-console/**` as an unauthenticated resource for convenience. Do not leave it publicly reachable. +- If you are behind a reverse proxy, restrict access by IP allowlist and/or additional authentication. diff --git a/home/sidebars.json b/home/sidebars.json index 4c9a1490724..a6c9b1e7cdb 100755 --- a/home/sidebars.json +++ b/home/sidebars.json @@ -41,6 +41,7 @@ "type": "category", "label": "change-db", "items": [ + "start/h2-database", "start/greptime-init", "start/victoria-metrics-init", "start/iotdb-init", diff --git a/home/versioned_docs/version-v1.6.x/start/h2-database.md b/home/versioned_docs/version-v1.6.x/start/h2-database.md new file mode 100644 index 00000000000..f8945ca8cde --- /dev/null +++ b/home/versioned_docs/version-v1.6.x/start/h2-database.md @@ -0,0 +1,73 @@ +--- +id: h2-database +title: Using H2 Database (Testing Only) +sidebar_label: H2 (Testing only) +--- + +Apache HertzBeat uses an embedded H2 database by default to store metadata (monitoring tasks, alarm data, configuration, etc.). This default is intended for quick start, demos, and local development. + +:::caution Not for production +H2 is **not** designed to run in an adversarial environment, and HertzBeat's H2 usage is **not recommended for production deployments**. + +If an attacker can access your H2 database (for example via an exposed H2 Web Console or any other path that allows executing SQL), H2 features such as `CREATE ALIAS` can be abused to execute arbitrary Java code and potentially take full control of the HertzBeat server. + +For background, see the H2 security documentation: https://h2database.com/html/security.html +::: + +## Recommendation for production + +Use a production-grade database for HertzBeat metadata storage instead of H2: + +- MySQL: [Use MYSQL Replace H2 Database to Store Metadata(Optional)](./mysql-change) +- PostgreSQL: [Use PostgreSQL Replace H2 Database to Store Metadata(Optional)](./postgresql-change) + +## Safe ways to use H2 (sandbox only) + +If you still choose to run HertzBeat with H2 for testing, keep the deployment sandboxed and minimize exposure: + +1. Prefer **embedded/file mode** (the default) and avoid running H2 in TCP server mode. +2. Do **not** expose H2 endpoints to untrusted networks. +3. Treat the H2 data store as **ephemeral** (backup/export your HertzBeat configuration if you need it). + +## Default datasource configuration (example) + +Your `application.yml` typically looks similar to this when using H2: + +```yaml +spring: + datasource: + driver-class-name: org.h2.Driver + username: sa + password: 123456 + url: jdbc:h2:./data/hertzbeat;MODE=MYSQL + hikari: + max-lifetime: 120000 +``` + +> Notes +> - The defaults may vary by version and packaging. +> - If you run via Docker, you should mount the `data/` directory so your local test data persists. + +## H2 Web Console (high risk) + +H2 provides a Web Console that can execute SQL against your database. Enabling it makes it much easier to accidentally expose a powerful administrative surface. + +:::danger Do not enable in production +Only enable the H2 console for local, temporary troubleshooting in a sandbox environment. +::: + +To enable it, set: + +```yaml +spring: + h2: + console: + path: /h2-console + enabled: true +``` + +### If you enable the console, lock it down + +- Ensure it is only reachable from `localhost` or a tightly controlled admin network. +- Review your `sureness.yml`: many deployments configure `/h2-console/**` as an unauthenticated resource for convenience. Do not leave it publicly reachable. +- If you are behind a reverse proxy, restrict access by IP allowlist and/or additional authentication. diff --git a/home/versioned_sidebars/version-v1.6.x-sidebars.json b/home/versioned_sidebars/version-v1.6.x-sidebars.json index 75916e06045..5b58da3a1c9 100644 --- a/home/versioned_sidebars/version-v1.6.x-sidebars.json +++ b/home/versioned_sidebars/version-v1.6.x-sidebars.json @@ -50,6 +50,7 @@ "type": "category", "label": "change-db", "items": [ + "start/h2-database", "start/victoria-metrics-init", "start/iotdb-init", "start/influxdb-init", From 44d2d2d1101fde986c70203ecd5a3b46667d73ce Mon Sep 17 00:00:00 2001 From: mohit07dec Date: Sun, 21 Dec 2025 00:12:23 +0530 Subject: [PATCH 2/3] [docs]i18n: add zh-cn H2 database page --- .../current/start/h2-database.md | 73 +++++++++++++++++++ .../version-v1.6.x/start/h2-database.md | 73 +++++++++++++++++++ 2 files changed, 146 insertions(+) create mode 100644 home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/h2-database.md create mode 100644 home/i18n/zh-cn/docusaurus-plugin-content-docs/version-v1.6.x/start/h2-database.md diff --git a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/h2-database.md b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/h2-database.md new file mode 100644 index 00000000000..38b2a4adf2f --- /dev/null +++ b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/h2-database.md @@ -0,0 +1,73 @@ +--- +id: h2-database +title: 使用 H2 数据库（仅用于测试） +sidebar_label: H2（仅用于测试） +--- + +Apache HertzBeat 默认使用嵌入式 H2 数据库存储元数据(监控任务，告警数据，配置等)。 此默认设置旨在用于快速启动、演示和本地开发。 + +:::caution 不适用于生产环境 +H2 并非设计为在对抗性环境中运行，HertzBeat 的 H2 用法不建议用于生产部署。 + +如果攻击者可以访问您的 H2 数据库（例如通过暴露的 H2 Web 控制台或任何其他允许执行 SQL 的路径），则 H2 的 `CREATE ALIAS` 等功能可能会被滥用以执行任意 Java 代码，并可能完全控制 HertzBeat 服务器。 + +有关背景信息，请参阅 H2 安全文档：https://h2database.com/html/security.html +::: + +## 生产建议 + +使用生产级数据库代替 H2 作为 HertzBeat 元数据存储： + +- MySQL：[使用 MYSQL 替换 H2 数据库存储元数据(可选)](./mysql-change) +- PostgreSQL：[使用 PostgreSQL 替换 H2 数据库存储元数据（可选）](./postgresql-change) + +## 使用 H2 的安全方式（仅限沙盒） + +如果您仍然选择使用 H2 运行 HertzBeat 进行测试，请保持部署沙盒化并尽量减少暴露： + +1. 优先选择**嵌入/文件模式**（默认），避免在 TCP 服务器模式下运行 H2。 +2. 不要将 H2 端点暴露给不受信任的网络。 +3. 将 H2 数据存储视为**临时**存储（如果需要，备份/导出您的 HertzBeat 配置）。 + +## 默认数据源配置（示例） + +使用 H2 时，您的 `application.yml` 通常如下所示： + +```yaml +spring: + datasource: + driver-class-name: org.h2.Driver + username: sa + password: 123456 + url: jdbc:h2:./data/hertzbeat;MODE=MYSQL + hikari: + max-lifetime: 120000 +``` + +> 注 +> - 默认值可能因版本和打包而异。 +> - 如果您通过 Docker 运行，则应装载 `data/` 目录，以便您的本地测试数据持久存在。 + +## H2 Web 控制台（高风险） + +H2 提供了一个 Web 控制台，可以针对您的数据库执行 SQL。 启用它会更容易意外地暴露强大的管理界面。 + +:::danger 不要在生产环境中启用 +仅在沙盒环境中启用 H2 控制台进行本地临时故障排除。 +::: + +要启用它，请设置： + +```yaml +spring: + h2: + console: + path: /h2-console + enabled: true +``` + +### 如果您启用控制台，请锁定它 + +- 确保它只能从 `localhost` 或严格控制的管理网络访问。 +- 查看您的 `sureness.yml`：许多部署将 `/h2-console/**` 配置为未经验证的资源，以方便使用。 不要让它公开可访问。 +- 如果您位于反向代理之后，请通过 IP 允许列表和/或附加身份验证来限制访问。 diff --git a/home/i18n/zh-cn/docusaurus-plugin-content-docs/version-v1.6.x/start/h2-database.md b/home/i18n/zh-cn/docusaurus-plugin-content-docs/version-v1.6.x/start/h2-database.md new file mode 100644 index 00000000000..38b2a4adf2f --- /dev/null +++ b/home/i18n/zh-cn/docusaurus-plugin-content-docs/version-v1.6.x/start/h2-database.md @@ -0,0 +1,73 @@ +--- +id: h2-database +title: 使用 H2 数据库（仅用于测试） +sidebar_label: H2（仅用于测试） +--- + +Apache HertzBeat 默认使用嵌入式 H2 数据库存储元数据(监控任务，告警数据，配置等)。 此默认设置旨在用于快速启动、演示和本地开发。 + +:::caution 不适用于生产环境 +H2 并非设计为在对抗性环境中运行，HertzBeat 的 H2 用法不建议用于生产部署。 + +如果攻击者可以访问您的 H2 数据库（例如通过暴露的 H2 Web 控制台或任何其他允许执行 SQL 的路径），则 H2 的 `CREATE ALIAS` 等功能可能会被滥用以执行任意 Java 代码，并可能完全控制 HertzBeat 服务器。 + +有关背景信息，请参阅 H2 安全文档：https://h2database.com/html/security.html +::: + +## 生产建议 + +使用生产级数据库代替 H2 作为 HertzBeat 元数据存储： + +- MySQL：[使用 MYSQL 替换 H2 数据库存储元数据(可选)](./mysql-change) +- PostgreSQL：[使用 PostgreSQL 替换 H2 数据库存储元数据（可选）](./postgresql-change) + +## 使用 H2 的安全方式（仅限沙盒） + +如果您仍然选择使用 H2 运行 HertzBeat 进行测试，请保持部署沙盒化并尽量减少暴露： + +1. 优先选择**嵌入/文件模式**（默认），避免在 TCP 服务器模式下运行 H2。 +2. 不要将 H2 端点暴露给不受信任的网络。 +3. 将 H2 数据存储视为**临时**存储（如果需要，备份/导出您的 HertzBeat 配置）。 + +## 默认数据源配置（示例） + +使用 H2 时，您的 `application.yml` 通常如下所示： + +```yaml +spring: + datasource: + driver-class-name: org.h2.Driver + username: sa + password: 123456 + url: jdbc:h2:./data/hertzbeat;MODE=MYSQL + hikari: + max-lifetime: 120000 +``` + +> 注 +> - 默认值可能因版本和打包而异。 +> - 如果您通过 Docker 运行，则应装载 `data/` 目录，以便您的本地测试数据持久存在。 + +## H2 Web 控制台（高风险） + +H2 提供了一个 Web 控制台，可以针对您的数据库执行 SQL。 启用它会更容易意外地暴露强大的管理界面。 + +:::danger 不要在生产环境中启用 +仅在沙盒环境中启用 H2 控制台进行本地临时故障排除。 +::: + +要启用它，请设置： + +```yaml +spring: + h2: + console: + path: /h2-console + enabled: true +``` + +### 如果您启用控制台，请锁定它 + +- 确保它只能从 `localhost` 或严格控制的管理网络访问。 +- 查看您的 `sureness.yml`：许多部署将 `/h2-console/**` 配置为未经验证的资源，以方便使用。 不要让它公开可访问。 +- 如果您位于反向代理之后，请通过 IP 允许列表和/或附加身份验证来限制访问。 From 5a6015f17080616756d1b3ac62d83fff1bb5d774 Mon Sep 17 00:00:00 2001 From: mohit07dec Date: Sun, 21 Dec 2025 14:32:01 +0530 Subject: [PATCH 3/3] docs(h2-database): fix markdownlint issues --- home/docs/start/h2-database.md | 3 ++- .../current/start/h2-database.md | 5 +++-- .../version-v1.6.x/start/h2-database.md | 5 +++-- home/versioned_docs/version-v1.6.x/start/h2-database.md | 3 ++- 4 files changed, 10 insertions(+), 6 deletions(-) diff --git a/home/docs/start/h2-database.md b/home/docs/start/h2-database.md index f8945ca8cde..980f8187aaf 100644 --- a/home/docs/start/h2-database.md +++ b/home/docs/start/h2-database.md @@ -11,7 +11,7 @@ H2 is **not** designed to run in an adversarial environment, and HertzBeat's H2 If an attacker can access your H2 database (for example via an exposed H2 Web Console or any other path that allows executing SQL), H2 features such as `CREATE ALIAS` can be abused to execute arbitrary Java code and potentially take full control of the HertzBeat server. -For background, see the H2 security documentation: https://h2database.com/html/security.html +For background, see the H2 security documentation: [H2 security documentation](https://h2database.com/html/security.html) ::: ## Recommendation for production @@ -45,6 +45,7 @@ spring: ``` > Notes +> > - The defaults may vary by version and packaging. > - If you run via Docker, you should mount the `data/` directory so your local test data persists. diff --git a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/h2-database.md b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/h2-database.md index 38b2a4adf2f..be9c8802ece 100644 --- a/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/h2-database.md +++ b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/h2-database.md @@ -11,7 +11,7 @@ H2 并非设计为在对抗性环境中运行，HertzBeat 的 H2 用法不建议 如果攻击者可以访问您的 H2 数据库（例如通过暴露的 H2 Web 控制台或任何其他允许执行 SQL 的路径），则 H2 的 `CREATE ALIAS` 等功能可能会被滥用以执行任意 Java 代码，并可能完全控制 HertzBeat 服务器。 -有关背景信息，请参阅 H2 安全文档：https://h2database.com/html/security.html +有关背景信息，请参阅 H2 安全文档：[H2 安全文档](https://h2database.com/html/security.html) ::: ## 生产建议 @@ -45,8 +45,9 @@ spring: ``` > 注 +> > - 默认值可能因版本和打包而异。 -> - 如果您通过 Docker 运行，则应装载 `data/` 目录，以便您的本地测试数据持久存在。 +> - 如果您通过 Docker 运行，则应装载 `data/` 目录，以便您的本地测试数据持久存在。 ## H2 Web 控制台（高风险） diff --git a/home/i18n/zh-cn/docusaurus-plugin-content-docs/version-v1.6.x/start/h2-database.md b/home/i18n/zh-cn/docusaurus-plugin-content-docs/version-v1.6.x/start/h2-database.md index 38b2a4adf2f..be9c8802ece 100644 --- a/home/i18n/zh-cn/docusaurus-plugin-content-docs/version-v1.6.x/start/h2-database.md +++ b/home/i18n/zh-cn/docusaurus-plugin-content-docs/version-v1.6.x/start/h2-database.md @@ -11,7 +11,7 @@ H2 并非设计为在对抗性环境中运行，HertzBeat 的 H2 用法不建议 如果攻击者可以访问您的 H2 数据库（例如通过暴露的 H2 Web 控制台或任何其他允许执行 SQL 的路径），则 H2 的 `CREATE ALIAS` 等功能可能会被滥用以执行任意 Java 代码，并可能完全控制 HertzBeat 服务器。 -有关背景信息，请参阅 H2 安全文档：https://h2database.com/html/security.html +有关背景信息，请参阅 H2 安全文档：[H2 安全文档](https://h2database.com/html/security.html) ::: ## 生产建议 @@ -45,8 +45,9 @@ spring: ``` > 注 +> > - 默认值可能因版本和打包而异。 -> - 如果您通过 Docker 运行，则应装载 `data/` 目录，以便您的本地测试数据持久存在。 +> - 如果您通过 Docker 运行，则应装载 `data/` 目录，以便您的本地测试数据持久存在。 ## H2 Web 控制台（高风险） diff --git a/home/versioned_docs/version-v1.6.x/start/h2-database.md b/home/versioned_docs/version-v1.6.x/start/h2-database.md index f8945ca8cde..980f8187aaf 100644 --- a/home/versioned_docs/version-v1.6.x/start/h2-database.md +++ b/home/versioned_docs/version-v1.6.x/start/h2-database.md @@ -11,7 +11,7 @@ H2 is **not** designed to run in an adversarial environment, and HertzBeat's H2 If an attacker can access your H2 database (for example via an exposed H2 Web Console or any other path that allows executing SQL), H2 features such as `CREATE ALIAS` can be abused to execute arbitrary Java code and potentially take full control of the HertzBeat server. -For background, see the H2 security documentation: https://h2database.com/html/security.html +For background, see the H2 security documentation: [H2 security documentation](https://h2database.com/html/security.html) ::: ## Recommendation for production @@ -45,6 +45,7 @@ spring: ``` > Notes +> > - The defaults may vary by version and packaging. > - If you run via Docker, you should mount the `data/` directory so your local test data persists.