diff --git a/home/docs/start/h2-database.md b/home/docs/start/h2-database.md new file mode 100644 index 00000000000..980f8187aaf --- /dev/null +++ b/home/docs/start/h2-database.md @@ -0,0 +1,74 @@ +--- +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: [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/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..be9c8802ece --- /dev/null +++ b/home/i18n/zh-cn/docusaurus-plugin-content-docs/current/start/h2-database.md @@ -0,0 +1,74 @@ +--- +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 安全文档：[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..be9c8802ece --- /dev/null +++ b/home/i18n/zh-cn/docusaurus-plugin-content-docs/version-v1.6.x/start/h2-database.md @@ -0,0 +1,74 @@ +--- +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 安全文档：[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/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..980f8187aaf --- /dev/null +++ b/home/versioned_docs/version-v1.6.x/start/h2-database.md @@ -0,0 +1,74 @@ +--- +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: [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",