docs: document new dedicated HTTP API server port (http.enable_api_server) (#2670)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Ning Sun <sunng@protonmail.com>
Co-authored-by: dennis zhuang <killme2008@gmail.com>

Author: 3 people

docs/reference/http-endpoints.md

@@ -5,12 +5,37 @@ description: Provides a full list of HTTP paths and their usage in GreptimeDB, i
 
 # HTTP API Endpoint List
 
+GreptimeDB provides two HTTP servers:
+
+| Server | Default address | Purpose |
+|--------|----------------|---------|
+| **Main HTTP server** | `127.0.0.1:4000` | Internal / operational use. Serves all paths, including admin endpoints such as `/health`, `/metrics`, `/config`, and `/debug/*`, as well as all `/v1` and `/dashboard` paths. Keep this port private and accessible only by trusted operators. |
+| **Public HTTP API server** | `127.0.0.1:4006` | User-facing access. Serves only `/v1` APIs and `/dashboard`. Safe to expose to database end-users. Disabled by default; enable it with `http.enable_api_server = true` in your configuration file. |
+
+We recommend keeping the main HTTP server port for internal/operational use only. Alternatively, it can be safely exposed through an HTTP proxy, provided direct access is restricted and the proxy allows only the required protocols. But If you want to expose GreptimeDB as a service to end-users, enable the dedicated public API server and expose only its port.
+
+```toml
+[http]
+# Main HTTP server — keep this internal
+addr = "127.0.0.1:4000"
+
+# Enable the public API server and bind it to an externally accessible address
+enable_api_server = true
+api_server_addr = "0.0.0.0:4006"
+```
+
+See the [configuration documentation](/user-guide/deployments-administration/configuration.md#protocol-options) for all `[http]` options.
+
 Here is the full list for the various HTTP paths and their usage in GreptimeDB:
 
 ## Admin APIs
 
 Endpoints that is not versioned (under `/v1`). For admin usage like health check, status, metrics, etc.
 
+:::note
+Admin API endpoints are available **only** on the main HTTP server (default port `4000`). They are not exposed by the dedicated public API server even when `http.enable_api_server` is enabled.
+:::
+
 ### Health Check
 
 - **Path**: `/health`

docs/user-guide/deployments-administration/configuration.md

@@ -189,6 +189,9 @@ concurrent_query_limiter_timeout = "100ms"
 
 Protocol options are valid in `frontend` and `standalone` subcommands,
 specifying protocol server addresses and other protocol-related options.
+In particular, `http.enable_api_server` lets you start a dedicated public HTTP API server that serves only the `/v1` APIs and `/dashboard`, while keeping the main HTTP server for internal and operational endpoints.
+This separation is useful when you want to expose GreptimeDB to end users or applications without also exposing admin paths such as health, metrics, config, or debug endpoints.
+To use it, set `http.enable_api_server = true` and configure `http.api_server_addr` to the address you want to expose externally, while keeping `http.addr` private for operator access.
 
 :::tip NOTE
 The HTTP protocol configuration is available for all GreptimeDB components: `frontend`, `datanode`, `flownode`, and `metasrv`.
@@ -207,6 +210,9 @@ body_limit = "64MB"
 enable_cors = true
 # cors_allowed_origins = ["https://example.com"]  # Optional: customize allowed origins
 experimental_enable_explain_analyze_stream = true
+# Enable the dedicated public HTTP API server (serves /v1 and /dashboard only)
+enable_api_server = false
+api_server_addr = "127.0.0.1:4006"
 [grpc]
 bind_addr = "127.0.0.1:4001"
 runtime_size = 8
@@ -281,6 +287,8 @@ The following table describes the options in detail:
 |            | enable_cors          | Boolean | Whether to enable HTTP CORS support, true by default. |
 |            | cors_allowed_origins | Array   | Customized allowed origins for HTTP CORS. |
 |            | experimental_enable_explain_analyze_stream | Boolean | Experimental: enable `POST /v1/sql/analyze/stream` for streaming `EXPLAIN ANALYZE VERBOSE` metrics, true by default. |
+|            | enable_api_server    | Boolean | Whether to start the dedicated public HTTP API server. This server serves only the `/v1` APIs and `/dashboard`, making it safe to expose to end users. The main HTTP server (`addr`) is intended for internal use. Disabled by default; set to `true` to enable. |
+|            | api_server_addr      | String  | The address to bind the dedicated public HTTP API server, `"127.0.0.1:4006"` by default. Only takes effect when `enable_api_server` is `true`. |
 | grpc       |                      |         | gRPC server options                                                                                                                                                                                                                                                                                                                                                                        |
 |            | bind_addr            | String  | The address to bind the gRPC server, "127.0.0.1:4001" by default                                                                                                                                                                                                                                                                                                                           |
 |            | runtime_size         | Integer | The number of server worker threads, 8 by default                                                                                                                                                                                                                                                                                                                                          |
@@ -823,6 +831,9 @@ http2_keep_alive_timeout = "3s"
 addr = "127.0.0.1:4000"
 timeout = "0s"
 body_limit = "64MB"
+## Enable the dedicated public HTTP API server (serves /v1 and /dashboard only).
+enable_api_server = false
+api_server_addr = "127.0.0.1:4006"
 
 ## Procedure storage options.
 [procedure]
@@ -971,6 +982,8 @@ timeout = "3s"
 | `http.addr`                                   | String  | `127.0.0.1:4000`             | HTTP server address. |
 | `http.timeout`                                | String  | `0s`                         | HTTP request timeout. Set to `0s` to disable timeout. |
 | `http.body_limit`                             | String  | `64MB`                       | HTTP max body size.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| `http.enable_api_server`                      | Bool    | `false`                      | Whether to start the dedicated public HTTP API server. When enabled, a separate server is started at `api_server_addr` that serves only `/v1` APIs and `/dashboard`. The main HTTP server is kept for internal use. |
+| `http.api_server_addr`                        | String  | `127.0.0.1:4006`             | The address to bind the dedicated public HTTP API server. Only takes effect when `enable_api_server` is `true`. |
 | `backend`                                     | String  | `etcd_store`                 | The datastore for metasrv.<br/>- `etcd_store` (default)<br/>- `memory_store` (In memory metadata storage - only used for testing.)<br/>- `postgres_store`<br/>- `mysql_store`                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `meta_table_name`                             | String  | `greptime_metakv`            | Table name in RDS to store metadata. Effect when using a RDS kvbackend.<br/>**Only used when backend is RDS kvbackend.**                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `meta_schema_name`                            | String  | --                           | Optional PostgreSQL schema for metadata table and election table name qualification. When PostgreSQL public schema is not writable (e.g., PostgreSQL 15+ with restricted public), set this to a writable schema. GreptimeDB will use `meta_schema_name.meta_table_name`.<br/>**Only used when backend is `postgres_store`.**                                                                                                                                                                                                                                                                                           |

i18n/zh/docusaurus-plugin-content-docs/current/reference/http-endpoints.md

@@ -5,12 +5,37 @@ description: 介绍 GreptimeDB 中各种 HTTP 路径及其用法的完整列表
 
 # HTTP API 端点列表
 
+GreptimeDB 提供两个 HTTP Server：
+
+| Server | 默认地址 | 用途 |
+|--------|---------|------|
+| **主 HTTP Server** | `127.0.0.1:4000` | 内部/运维使用。提供所有路径，包括 `/health`、`/metrics`、`/config`、`/debug/*` 等管理端点，以及全部 `/v1` 和 `/dashboard` 路径。该端口应保持私有，仅对可信运维人员开放。 |
+| **公共 HTTP API Server** | `127.0.0.1:4006` | 面向用户的访问。仅提供 `/v1` API 和 `/dashboard`，可安全地暴露给数据库终端用户。默认禁用；可在配置文件中设置 `http.enable_api_server = true` 来启用。 |
+
+建议仅在内部/运维场景下使用主 HTTP Server 端口。或者也可以通过 HTTP 代理安全地暴露该端口，前提是限制直接访问，并且代理仅允许所需的协议。但是如需将 GreptimeDB 作为服务对外暴露给终端用户，我们更推荐启用专用公共 API Server，并仅对外暴露该端口。
+
+```toml
+[http]
+# 主 HTTP Server — 保持内部访问
+addr = "127.0.0.1:4000"
+
+# 启用公共 API Server 并将其绑定到可外部访问的地址
+enable_api_server = true
+api_server_addr = "0.0.0.0:4006"
+```
+
+详见[配置文档](/user-guide/deployments-administration/configuration.md#协议选项)中的 `[http]` 选项。
+
 以下是 GreptimeDB 中各种 HTTP 路径及其用法的完整列表：
 
 ## 管理 API
 
 未版本化的端点（不在 `/v1` 下）。用于健康检查、状态、指标等管理用途。
 
+:::note
+管理 API 端点**仅**在主 HTTP Server（默认端口 `4000`）上可用。即使启用了 `http.enable_api_server`，专用公共 API Server 也不会暴露这些端点。
+:::
+
 ### 健康检查
 
 - **路径**: `/health`

i18n/zh/docusaurus-plugin-content-docs/current/user-guide/deployments-administration/configuration.md

@@ -188,6 +188,9 @@ concurrent_query_limiter_timeout = "100ms"
 ### 协议选项
 
 协议选项适用于 `frontend` 和 `standalone` 子命令，它指定了协议服务器地址和其他协议相关的选项。
+其中，`http.enable_api_server` 可用于启动一个专门对外提供服务的公共 HTTP API Server，它只暴露 `/v1` API 和 `/dashboard`，而主 HTTP Server 继续用于内部和运维端点。
+这种分离方式适合希望将 GreptimeDB 暴露给终端用户或应用程序、同时又不暴露 health、metrics、config、debug 等管理路径的场景。
+使用时，将 `http.enable_api_server = true`，并把 `http.api_server_addr` 配置为你希望对外暴露的地址，同时将 `http.addr` 保持为仅供运维访问的内部地址。
 
 :::tip 提示
 HTTP 协议配置适用于所有 GreptimeDB 组件：`frontend`、`datanode`、`flownode` 和 `metasrv`。
@@ -206,6 +209,9 @@ body_limit = "64MB"
 enable_cors = true
 # cors_allowed_origins = ["https://example.com"]  # Optional: customize allowed origins
 experimental_enable_explain_analyze_stream = true
+# 启用专用公共 HTTP API Server（仅提供 /v1 和 /dashboard）
+enable_api_server = false
+api_server_addr = "127.0.0.1:4006"
 [grpc]
 bind_addr = "127.0.0.1:4001"
 runtime_size = 8
@@ -280,6 +286,8 @@ max_inflight_requests = 3000
 |            | enable_cors        | 布尔值 | 是否启用 HTTP CORS 支持，默认为 true。 |
 |            | cors_allowed_origins | 数组 | 自定义 HTTP CORS 允许的来源。 |
 |            | experimental_enable_explain_analyze_stream | 布尔值 | 实验性：启用 `POST /v1/sql/analyze/stream`，用于流式返回 `EXPLAIN ANALYZE VERBOSE` 指标，默认为 true。 |
+|            | enable_api_server    | 布尔值 | 是否启动专用公共 HTTP API Server。该 Server 仅提供 `/v1` API 和 `/dashboard`，可安全地对外暴露给终端用户。主 HTTP Server（`addr`）用于内部使用。默认禁用；设为 `true` 可启用。 |
+|            | api_server_addr      | 字符串 | 专用公共 HTTP API Server 的绑定地址，默认为 `"127.0.0.1:4006"`。仅在 `enable_api_server` 为 `true` 时生效。 |
 | grpc       |                    |        | gRPC 服务器选项                                              |
 |            | bind_addr               | 字符串 | gRPC 服务绑定地址，默认为 "127.0.0.1:4001"                          |
 |            | runtime_size       | 整数   | 服务器工作线程数量，默认为 8                                 |
@@ -827,6 +835,9 @@ http2_keep_alive_timeout = "3s"
 addr = "127.0.0.1:4000"
 timeout = "0s"
 body_limit = "64MB"
+## 启用专用公共 HTTP API Server（仅提供 /v1 和 /dashboard）。
+enable_api_server = false
+api_server_addr = "127.0.0.1:4006"
 
 ## Procedure 选项
 [procedure]
@@ -957,6 +968,8 @@ timeout = "3s"
 | `http.addr`                                   | String  | `127.0.0.1:4000`     | HTTP 服务器地址。 |
 | `http.timeout`                                | String  | `0s`                 | HTTP 请求超时时间。设为 `0s` 可禁用超时。 |
 | `http.body_limit`                             | String  | `64MB`               | HTTP 最大 body 大小。 |
+| `http.enable_api_server`                      | Bool    | `false`              | 是否启动专用公共 HTTP API Server。启用后，会在 `api_server_addr` 地址启动一个独立 Server，仅提供 `/v1` API 和 `/dashboard`。主 HTTP Server 保留用于内部使用。 |
+| `http.api_server_addr`                        | String  | `127.0.0.1:4006`     | 专用公共 HTTP API Server 的绑定地址。仅在 `enable_api_server` 为 `true` 时生效。 |
 | `backend`                                     | String  | `etcd_store`           | 元数据存储类型。<br/>- `etcd_store` (默认)<br/>- `memory_store` (纯内存存储 - 仅用于测试)<br/>- `postgres_store`<br/>- `mysql_store` |
 | `meta_table_name` | String | `greptime_metakv` | 使用 RDS 存储元数据时的表名。**仅在 backend 为 RDS kvbackend 时有效。** |
 | `meta_schema_name` | String | -- | 可选的 PostgreSQL schema，用于元数据表和选举表名称限定。当 PostgreSQL public schema 不可写入时（例如 PostgreSQL 15+ 限制 public schema），可设置此参数为可写入的 schema。GreptimeDB 将使用 `meta_schema_name.meta_table_name`。<br/>**仅在 backend 为 postgres_store 时有效。** |