This is an automated email from the ASF dual-hosted git repository.
morningman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/doris-website.git
The following commit(s) were added to refs/heads/master by this push:
new b00e7501fe2 [fix](doc) clarify computation BE role behavior across
storage modes (#3758)
b00e7501fe2 is described below
commit b00e7501fe23335314732fe021127e59f24cc1d5
Author: Mingyu Chen (Rayner) <[email protected]>
AuthorDate: Sun May 24 18:23:43 2026 -0700
[fix](doc) clarify computation BE role behavior across storage modes (#3758)
## Summary
- A `computation`-type BE node only serves data lake (external table)
queries — it never serves internal table queries. If every BE in the
cluster is `computation`, internal-table queries fail with `has no
queryable replicas`.
- The existing doc claimed compute nodes only apply to the
storage-compute integrated mode and were "no longer needed" in the
storage-compute separation mode. That is wrong: they work in **both**
modes, with the same external-only restriction. The wording is corrected
to describe the two modes side by side and call out the
workload-isolation use case.
- Added a `:::caution` admonition warning about:
- the `has no queryable replicas` failure when all BEs are `computation`
- `SHOW BACKENDS` always showing `NodeRole = mix` in storage-compute
separation mode regardless of `be_node_role` (a real-world user got
confused by this and changed their config the wrong way)
- Added two FAQ entries covering the same two pitfalls.
Updates the four file copies that contain this section: zh-CN `current`
+ zh-CN `version-4.x`, English `current` (`docs/`) + English
`version-4.x` (`versioned_docs/`).
## Test plan
- [ ] Spot-check the rendered Chinese page in the local Docusaurus build
- [ ] Spot-check the rendered English page in the local Docusaurus build
- [ ] Verify the `:::caution` admonition renders correctly in both
languages
---------
Co-authored-by: Claude Opus 4.7 (1M context) <[email protected]>
---
docs/getting-started/quick-start.mdx | 6 ++++++
docs/lakehouse/compute-node.md | 22 ++++++++++++++++++++--
.../current/getting-started/quick-start.mdx | 6 ++++++
.../current/lakehouse/compute-node.md | 20 +++++++++++++++++++-
.../version-4.x/getting-started/quick-start.mdx | 6 ++++++
.../version-4.x/lakehouse/compute-node.md | 20 +++++++++++++++++++-
.../version-4.x/getting-started/quick-start.mdx | 6 ++++++
.../version-4.x/lakehouse/compute-node.md | 22 ++++++++++++++++++++--
8 files changed, 102 insertions(+), 6 deletions(-)
diff --git a/docs/getting-started/quick-start.mdx
b/docs/getting-started/quick-start.mdx
index 049edf733ef..27a2b2ad5c2 100644
--- a/docs/getting-started/quick-start.mdx
+++ b/docs/getting-started/quick-start.mdx
@@ -249,6 +249,12 @@ As a temporary workaround, remove the `credsStore` field
from `~/.docker/config.
Check whether the BE's `priority_networks` is in the same network segment as
the FE, and confirm that the BE ports (9050/9060/8040/8060) are not blocked by
a firewall.
+### Q: Running the local deployment under WSL2 — the BE never joins the
cluster. What's wrong?
+
+WSL2's loopback is namespaced per-distribution, so the FE and BE cannot reach
each other through `127.0.0.1`. The default `priority_networks=127.0.0.1/32`
therefore causes BE registration or heartbeats to fail under WSL2.
+
+To fix it, run `ip addr show eth0` to find the actual WSL network segment
(typically `172.16.0.0/12` or `172.x.x.x/20`), then set `priority_networks` to
that segment in both `fe/conf/fe.conf` and `be/conf/be.conf`, restart the FE
and BE, and re-run `ALTER SYSTEM ADD BACKEND`.
+
### Q: How do I confirm that the cluster is healthy overall?
Run `SHOW FRONTENDS;` and `SHOW BACKENDS;`, and ensure that the `Alive` column
is `true` for every node.
diff --git a/docs/lakehouse/compute-node.md b/docs/lakehouse/compute-node.md
index 70be0f54feb..51432660cc2 100644
--- a/docs/lakehouse/compute-node.md
+++ b/docs/lakehouse/compute-node.md
@@ -10,7 +10,15 @@ Elastic compute nodes, as a special type of BE node, do not
have data storage ca
In lakehouse data analysis scenarios, elastic compute nodes can be used to
query external data sources such as Hive, Iceberg, Hudi, Paimon, JDBC, etc.
Doris does not handle the storage of external data source data, so elastic
compute nodes can be used to easily expand the computing power for external
data sources. Additionally, compute nodes can also be configured with cache
directories to cache hot data from external data sources, further accelerating
data reading.
-Elastic compute nodes **are suitable for elastic resource control in the
integrated storage and computing mode of Doris**. In the storage-compute
separation architecture of Doris 3.0, BE nodes are stateless, so separate
elastic compute nodes are no longer needed.
+Elastic compute nodes can be used in both **integrated storage and computing
mode** and **storage-compute separation mode**. They are primarily used to
isolate the compute resources for data lake (external table) queries from those
for internal table queries:
+
+- **Integrated storage and computing mode**: BE nodes are of type `mix` by
default and are responsible for both storage and computation. You can deploy a
separate group of `computation`-type BE nodes dedicated to external table
queries and scale them up or down elastically without affecting the storage of
internal table data.
+- **Storage-compute separation mode**: BE nodes are already stateless and can
be scaled up or down easily. You can still set some BE nodes to `computation`
type to make them dedicated to data lake (external table) queries, achieving
workload isolation from the BE nodes serving internal table queries.
+
+:::caution Important
+- BE nodes set to `computation` type **only serve data lake (external table)
queries; they do NOT serve any internal table query requests**. If all BE nodes
in the cluster are set to `computation`, queries on internal tables will fail
with the error `has no queryable replicas`. Make sure at least one `mix`-type
BE node is kept in the cluster to serve internal table queries.
+- In **storage-compute separation mode**, the `NodeRole` column shown by `SHOW
BACKENDS` is always `mix`, regardless of the `be_node_role` setting in the BE
configuration file. This is a known display behavior; the actual role of a node
is still determined by the `be_node_role` value in `be.conf`.
+:::
## Usage of Compute Nodes
@@ -93,4 +101,14 @@ At the same time, as stateless BE nodes, compute nodes can
be easily scaled up a
4. Do compute nodes need to be decommissioned through the DECOMMISION
operation?
- No. Compute nodes can be directly deleted using the `DROP BACKEND` operation.
\ No newline at end of file
+ No. Compute nodes can be directly deleted using the `DROP BACKEND` operation.
+
+5. Why does querying an internal table on a compute node fail with `has no
queryable replicas`?
+
+ This is the expected behavior. `computation`-type BE nodes do not serve any
internal table queries. If all BE nodes in the cluster are of `computation`
type (or the `mix`-type nodes in the cluster are not enough to hold the
replicas of the internal table), queries on internal tables will fail with this
error.
+
+ Resolution: keep or add at least one `mix`-type BE node in the cluster to
serve internal table queries.
+
+6. In storage-compute separation mode, the `NodeRole` shown by `SHOW BACKENDS`
is always `mix`. Does that mean the `be_node_role = computation` setting did
not take effect?
+
+ No. In storage-compute separation mode, the `NodeRole` column of `SHOW
BACKENDS` is always displayed as `mix`. This is a known display behavior and is
unrelated to the actual `be_node_role` setting in `be.conf`. The parameter
still takes effect in storage-compute separation mode: nodes configured as
`computation` will only participate in external table queries.
\ No newline at end of file
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/quick-start.mdx
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/quick-start.mdx
index cee802b7801..fffc3dde839 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/quick-start.mdx
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/getting-started/quick-start.mdx
@@ -249,6 +249,12 @@ sudo ln -s
/Applications/Docker.app/Contents/Resources/bin/docker /usr/local/bin
检查 BE 的 `priority_networks` 是否与 FE 所在网段一致，并确认 BE
端口（9050/9060/8040/8060）未被防火墙拦截。
+### Q: 在 WSL2 中本地部署，BE 始终无法加入集群？
+
+WSL2 的回环网络按发行版隔离，FE 与 BE 之间无法通过 `127.0.0.1` 互通，因此默认配置
`priority_networks=127.0.0.1/32` 在 WSL2 下会导致 BE 注册失败或心跳异常。
+
+解决方法：通过 `ip addr show eth0` 查看 WSL 实际网卡所在网段（通常为 `172.16.0.0/12` 或
`172.x.x.x/20`），然后将 `fe/conf/fe.conf` 与 `be/conf/be.conf` 中的
`priority_networks` 同步修改为该网段，重启 FE、BE 后重新执行 `ALTER SYSTEM ADD BACKEND`。
+
### Q: 如何确认集群整体健康？
执行 `SHOW FRONTENDS;` 和 `SHOW BACKENDS;`，确保所有节点的 `Alive` 列为 `true`。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/compute-node.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/compute-node.md
index eabe9de8584..14f979a20a7 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/compute-node.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/lakehouse/compute-node.md
@@ -10,7 +10,15 @@
在湖仓数据分析场景中，弹性计算节点可用于查询外部数据源，如 Hive、Iceberg、Hudi、Paimon、JDBC 等。Doris
不负责外部数据源数据的存储，因此，可以使用弹性计算节点方便的扩展对外部数据源的计算能力。同时，计算节点也可以配置缓存目录，用于缓存外部数据源的热点数据，进一步加速数据读取。
-弹性计算节点**适用于在 Doris 存算一体模式**，进行弹性资源控制。在 Doris 3.0 版本的存算分离架构下，BE
节点都是无状态的，因此不再需要单独的弹性计算节点。
+弹性计算节点在**存算一体**和**存算分离**两种模式下均可使用，主要用于将数据湖（外表）查询与内表查询的计算资源进行隔离：
+
+- **存算一体模式**：BE 节点默认是 `mix` 类型，同时承担数据存储和计算。可以单独部署一组 `computation` 类型的 BE
节点专门用于外表查询，并方便的进行弹性扩缩容，而不影响内表的数据存储。
+- **存算分离模式**：BE 节点本身已是无状态的，可以方便的进行扩缩容。但仍然可以通过将部分 BE 节点设置为 `computation`
类型，将其专用于数据湖（外表）查询，从而和服务内表查询的 BE 节点进行负载隔离。
+
+:::caution 重要说明
+- 设置为 `computation` 类型的 BE 节点**仅服务数据湖（外表）查询，不会处理任何内表查询请求**。如果集群中所有 BE 节点都被设置为
`computation`，对内表的查询会失败并报错 `has no queryable replicas`。因此，请确保集群中至少保留一个 `mix`
类型的 BE 节点来承载内表查询。
+- 在**存算分离模式**下，`SHOW BACKENDS` 显示的 `NodeRole` 列始终为 `mix`，与 BE 配置文件中的
`be_node_role` 设置无关。这是已知的显示行为，节点的实际角色仍以 `be.conf` 中的 `be_node_role` 配置为准。
+:::
## 计算节点的使用
@@ -94,3 +102,13 @@
4. 计算节点是否需要通过 DECOMMISION 操作下线
不需要。计算节点可以直接通过 `DROP BACKEND` 操作删除。
+
+5. 在计算节点上查询内表报错 `has no queryable replicas`
+
+ 这是符合预期的行为。`computation` 类型的 BE 节点不会服务任何内表查询。如果集群内所有 BE 节点都是 `computation`
类型（或集群内 `mix` 节点不足以承载内表的副本），对内表的查询就会失败并报此错误。
+
+ 解决方法：在集群中保留或新增至少一个 `mix` 类型的 BE 节点用于承载内表查询。
+
+6. 存算分离模式下 `SHOW BACKENDS` 显示的 `NodeRole` 始终是 `mix`，是否表示 `be_node_role =
computation` 配置没生效
+
+ 没有这个意思。在存算分离模式下，`SHOW BACKENDS` 的 `NodeRole` 列始终显示为 `mix`，这是已知的显示行为，与
`be.conf` 中 `be_node_role` 的实际配置无关。该参数在存算分离模式下仍然生效，配置为 `computation`
的节点同样只会参与外表查询。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/getting-started/quick-start.mdx
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/getting-started/quick-start.mdx
index cee802b7801..fffc3dde839 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/getting-started/quick-start.mdx
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/getting-started/quick-start.mdx
@@ -249,6 +249,12 @@ sudo ln -s
/Applications/Docker.app/Contents/Resources/bin/docker /usr/local/bin
检查 BE 的 `priority_networks` 是否与 FE 所在网段一致，并确认 BE
端口（9050/9060/8040/8060）未被防火墙拦截。
+### Q: 在 WSL2 中本地部署，BE 始终无法加入集群？
+
+WSL2 的回环网络按发行版隔离，FE 与 BE 之间无法通过 `127.0.0.1` 互通，因此默认配置
`priority_networks=127.0.0.1/32` 在 WSL2 下会导致 BE 注册失败或心跳异常。
+
+解决方法：通过 `ip addr show eth0` 查看 WSL 实际网卡所在网段（通常为 `172.16.0.0/12` 或
`172.x.x.x/20`），然后将 `fe/conf/fe.conf` 与 `be/conf/be.conf` 中的
`priority_networks` 同步修改为该网段，重启 FE、BE 后重新执行 `ALTER SYSTEM ADD BACKEND`。
+
### Q: 如何确认集群整体健康？
执行 `SHOW FRONTENDS;` 和 `SHOW BACKENDS;`，确保所有节点的 `Alive` 列为 `true`。
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/compute-node.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/compute-node.md
index eabe9de8584..14f979a20a7 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/compute-node.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/lakehouse/compute-node.md
@@ -10,7 +10,15 @@
在湖仓数据分析场景中，弹性计算节点可用于查询外部数据源，如 Hive、Iceberg、Hudi、Paimon、JDBC 等。Doris
不负责外部数据源数据的存储，因此，可以使用弹性计算节点方便的扩展对外部数据源的计算能力。同时，计算节点也可以配置缓存目录，用于缓存外部数据源的热点数据，进一步加速数据读取。
-弹性计算节点**适用于在 Doris 存算一体模式**，进行弹性资源控制。在 Doris 3.0 版本的存算分离架构下，BE
节点都是无状态的，因此不再需要单独的弹性计算节点。
+弹性计算节点在**存算一体**和**存算分离**两种模式下均可使用，主要用于将数据湖（外表）查询与内表查询的计算资源进行隔离：
+
+- **存算一体模式**：BE 节点默认是 `mix` 类型，同时承担数据存储和计算。可以单独部署一组 `computation` 类型的 BE
节点专门用于外表查询，并方便的进行弹性扩缩容，而不影响内表的数据存储。
+- **存算分离模式**：BE 节点本身已是无状态的，可以方便的进行扩缩容。但仍然可以通过将部分 BE 节点设置为 `computation`
类型，将其专用于数据湖（外表）查询，从而和服务内表查询的 BE 节点进行负载隔离。
+
+:::caution 重要说明
+- 设置为 `computation` 类型的 BE 节点**仅服务数据湖（外表）查询，不会处理任何内表查询请求**。如果集群中所有 BE 节点都被设置为
`computation`，对内表的查询会失败并报错 `has no queryable replicas`。因此，请确保集群中至少保留一个 `mix`
类型的 BE 节点来承载内表查询。
+- 在**存算分离模式**下，`SHOW BACKENDS` 显示的 `NodeRole` 列始终为 `mix`，与 BE 配置文件中的
`be_node_role` 设置无关。这是已知的显示行为，节点的实际角色仍以 `be.conf` 中的 `be_node_role` 配置为准。
+:::
## 计算节点的使用
@@ -94,3 +102,13 @@
4. 计算节点是否需要通过 DECOMMISION 操作下线
不需要。计算节点可以直接通过 `DROP BACKEND` 操作删除。
+
+5. 在计算节点上查询内表报错 `has no queryable replicas`
+
+ 这是符合预期的行为。`computation` 类型的 BE 节点不会服务任何内表查询。如果集群内所有 BE 节点都是 `computation`
类型（或集群内 `mix` 节点不足以承载内表的副本），对内表的查询就会失败并报此错误。
+
+ 解决方法：在集群中保留或新增至少一个 `mix` 类型的 BE 节点用于承载内表查询。
+
+6. 存算分离模式下 `SHOW BACKENDS` 显示的 `NodeRole` 始终是 `mix`，是否表示 `be_node_role =
computation` 配置没生效
+
+ 没有这个意思。在存算分离模式下，`SHOW BACKENDS` 的 `NodeRole` 列始终显示为 `mix`，这是已知的显示行为，与
`be.conf` 中 `be_node_role` 的实际配置无关。该参数在存算分离模式下仍然生效，配置为 `computation`
的节点同样只会参与外表查询。
diff --git a/versioned_docs/version-4.x/getting-started/quick-start.mdx
b/versioned_docs/version-4.x/getting-started/quick-start.mdx
index 049edf733ef..27a2b2ad5c2 100644
--- a/versioned_docs/version-4.x/getting-started/quick-start.mdx
+++ b/versioned_docs/version-4.x/getting-started/quick-start.mdx
@@ -249,6 +249,12 @@ As a temporary workaround, remove the `credsStore` field
from `~/.docker/config.
Check whether the BE's `priority_networks` is in the same network segment as
the FE, and confirm that the BE ports (9050/9060/8040/8060) are not blocked by
a firewall.
+### Q: Running the local deployment under WSL2 — the BE never joins the
cluster. What's wrong?
+
+WSL2's loopback is namespaced per-distribution, so the FE and BE cannot reach
each other through `127.0.0.1`. The default `priority_networks=127.0.0.1/32`
therefore causes BE registration or heartbeats to fail under WSL2.
+
+To fix it, run `ip addr show eth0` to find the actual WSL network segment
(typically `172.16.0.0/12` or `172.x.x.x/20`), then set `priority_networks` to
that segment in both `fe/conf/fe.conf` and `be/conf/be.conf`, restart the FE
and BE, and re-run `ALTER SYSTEM ADD BACKEND`.
+
### Q: How do I confirm that the cluster is healthy overall?
Run `SHOW FRONTENDS;` and `SHOW BACKENDS;`, and ensure that the `Alive` column
is `true` for every node.
diff --git a/versioned_docs/version-4.x/lakehouse/compute-node.md
b/versioned_docs/version-4.x/lakehouse/compute-node.md
index 70be0f54feb..51432660cc2 100644
--- a/versioned_docs/version-4.x/lakehouse/compute-node.md
+++ b/versioned_docs/version-4.x/lakehouse/compute-node.md
@@ -10,7 +10,15 @@ Elastic compute nodes, as a special type of BE node, do not
have data storage ca
In lakehouse data analysis scenarios, elastic compute nodes can be used to
query external data sources such as Hive, Iceberg, Hudi, Paimon, JDBC, etc.
Doris does not handle the storage of external data source data, so elastic
compute nodes can be used to easily expand the computing power for external
data sources. Additionally, compute nodes can also be configured with cache
directories to cache hot data from external data sources, further accelerating
data reading.
-Elastic compute nodes **are suitable for elastic resource control in the
integrated storage and computing mode of Doris**. In the storage-compute
separation architecture of Doris 3.0, BE nodes are stateless, so separate
elastic compute nodes are no longer needed.
+Elastic compute nodes can be used in both **integrated storage and computing
mode** and **storage-compute separation mode**. They are primarily used to
isolate the compute resources for data lake (external table) queries from those
for internal table queries:
+
+- **Integrated storage and computing mode**: BE nodes are of type `mix` by
default and are responsible for both storage and computation. You can deploy a
separate group of `computation`-type BE nodes dedicated to external table
queries and scale them up or down elastically without affecting the storage of
internal table data.
+- **Storage-compute separation mode**: BE nodes are already stateless and can
be scaled up or down easily. You can still set some BE nodes to `computation`
type to make them dedicated to data lake (external table) queries, achieving
workload isolation from the BE nodes serving internal table queries.
+
+:::caution Important
+- BE nodes set to `computation` type **only serve data lake (external table)
queries; they do NOT serve any internal table query requests**. If all BE nodes
in the cluster are set to `computation`, queries on internal tables will fail
with the error `has no queryable replicas`. Make sure at least one `mix`-type
BE node is kept in the cluster to serve internal table queries.
+- In **storage-compute separation mode**, the `NodeRole` column shown by `SHOW
BACKENDS` is always `mix`, regardless of the `be_node_role` setting in the BE
configuration file. This is a known display behavior; the actual role of a node
is still determined by the `be_node_role` value in `be.conf`.
+:::
## Usage of Compute Nodes
@@ -93,4 +101,14 @@ At the same time, as stateless BE nodes, compute nodes can
be easily scaled up a
4. Do compute nodes need to be decommissioned through the DECOMMISION
operation?
- No. Compute nodes can be directly deleted using the `DROP BACKEND` operation.
\ No newline at end of file
+ No. Compute nodes can be directly deleted using the `DROP BACKEND` operation.
+
+5. Why does querying an internal table on a compute node fail with `has no
queryable replicas`?
+
+ This is the expected behavior. `computation`-type BE nodes do not serve any
internal table queries. If all BE nodes in the cluster are of `computation`
type (or the `mix`-type nodes in the cluster are not enough to hold the
replicas of the internal table), queries on internal tables will fail with this
error.
+
+ Resolution: keep or add at least one `mix`-type BE node in the cluster to
serve internal table queries.
+
+6. In storage-compute separation mode, the `NodeRole` shown by `SHOW BACKENDS`
is always `mix`. Does that mean the `be_node_role = computation` setting did
not take effect?
+
+ No. In storage-compute separation mode, the `NodeRole` column of `SHOW
BACKENDS` is always displayed as `mix`. This is a known display behavior and is
unrelated to the actual `be_node_role` setting in `be.conf`. The parameter
still takes effect in storage-compute separation mode: nodes configured as
`computation` will only participate in external table queries.
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
