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 b73518970af [doc] Recommend 3 FOLLOWER FEs in metadata best practices
(#4167)
b73518970af is described below
commit b73518970afc62a0989f0879b033be91c4198948
Author: ZhenchaoXu <[email protected]>
AuthorDate: Sat Sep 26 17:29:20 2026 +0800
[doc] Recommend 3 FOLLOWER FEs in metadata best practices (#4167)
## Versions
- [x] dev
- [x] 4.x
- [x] 3.x
- [ ] 2.1 or older (not covered by version/language sync gate)
## Languages
- [x] Chinese
- [x] English
## Docs Checklist
- [x] Checked by AI
- [ ] Test Cases Built
- [x] Updated required version and language counterparts, or explained
why not
- [x] If only one language changed, confirmed whether source/translation
counterparts need sync
## Summary
- The metadata operation page still recommended deploying only one
FOLLOWER-type FE as MASTER and making the rest OBSERVERs. That advice is
outdated and conflicts with current deployment docs, which recommend 3
FOLLOWERs for production HA.
- Update Best Practices and the "FOLLOWER FE hangs up one after another"
FAQ for current/dev, 4.x, and 3.x (English and Chinese). Majority-write
behavior is kept; the conclusion is now to deploy 3 FOLLOWERs and avoid
stopping a majority of them.
- 2.1 and older docs are unchanged.
## Test plan
- [x] Review the Best Practices and FAQ #5 wording in current, 4.x, and
3.x English/Chinese pages
- [ ] Confirm the rendered docs after merge:
`/docs/dev/admin-manual/trouble-shooting/metadata-operation#best-practices`
---
docs/admin-manual/trouble-shooting/metadata-operation.md | 6 ++++--
.../current/admin-manual/trouble-shooting/metadata-operation.md | 6 ++++--
.../version-3.x/admin-manual/trouble-shooting/metadata-operation.md | 6 ++++--
.../version-4.x/admin-manual/trouble-shooting/metadata-operation.md | 6 ++++--
.../version-3.x/admin-manual/trouble-shooting/metadata-operation.md | 6 ++++--
.../version-4.x/admin-manual/trouble-shooting/metadata-operation.md | 6 ++++--
6 files changed, 24 insertions(+), 12 deletions(-)
diff --git a/docs/admin-manual/trouble-shooting/metadata-operation.md
b/docs/admin-manual/trouble-shooting/metadata-operation.md
index b450773025f..6fc10133f59 100644
--- a/docs/admin-manual/trouble-shooting/metadata-operation.md
+++ b/docs/admin-manual/trouble-shooting/metadata-operation.md
@@ -270,7 +270,9 @@ The third level can display the value information of the
specified key.
The deployment recommendation of FE is described in the Installation and
[Deployment
Document](../../install/deploy-manually/integrated-storage-compute-deploy-manually.md).
Here are some supplements.
-* **If you don't know the operation logic of FE metadata very well, or you
don't have enough experience in the operation and maintenance of FE metadata,
we strongly recommend that only one FOLLOWER-type FE be deployed as MASTER in
practice, and the other FEs are OBSERVER, which can reduce many complex
operation and maintenance problems.** Don't worry too much about the failure of
MASTER single point to write metadata. First, if you configure it properly, FE
as a java process is very diff [...]
+* In production, deploy an **odd number of FOLLOWER FEs** (typically 3: 1
MASTER + 2 FOLLOWERs) so that metadata writes remain highly available.
FOLLOWERs participate in leader election and majority writes; if the Master
fails, the remaining FOLLOWERs elect a new Master. OBSERVERs do not participate
in elections; they only sync metadata and are used to scale FE read capacity. A
single FOLLOWER is acceptable for test or development.
+
+* Majority write means a journal is committed only after it is written to a
majority of FOLLOWERs. With 3 FOLLOWERs, one failure is tolerated; if only one
FOLLOWER remains, it cannot continue writing metadata. This is expected, not a
reason to avoid a 3-FOLLOWER deployment. Keep FOLLOWER clocks in sync, give the
FE JVM enough memory, and do not stop a majority of FOLLOWERs at the same time.
* The JVM of the FE process must ensure sufficient memory. We **strongly
recommend** that FE's JVM memory should be at least 10GB and 32GB to 64GB. And
deploy monitoring to monitor JVM memory usage. Because if OOM occurs in FE,
metadata writing may fail, resulting in some failures that **cannot recover**!
@@ -304,7 +306,7 @@ The deployment recommendation of FE is described in the
Installation and [Deploy
5. FOLLOWER FE hangs up one after another
- Because Doris's metadata adopts the majority writing strategy, that is,
a metadata journal must be written to at least a number of FOLLOWER FEs (for
example, three FOLLOWERs, two must be written successfully) before it can be
considered successful. If the write fails, the FE process exits on its own
initiative. So suppose there are three FOLLOWERs: A, B and C. C hangs up first,
and then B hangs up, then A will hang up. So as described in the `Best
Practices `section, if you don't have e [...]
+ Because Doris's metadata adopts the majority writing strategy, that is,
a metadata journal must be written to at least a number of FOLLOWER FEs (for
example, three FOLLOWERs, two must be written successfully) before it can be
considered successful. If the write fails, the FE process exits on its own
initiative. So suppose there are three FOLLOWERs: A, B and C. C hangs up first,
and then B hangs up, then A will hang up. This is expected majority-write
behavior. Production environments sh [...]
6. fe.log 中出现 `get exception when try to close previously opened bdb database.
ignore it`
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/trouble-shooting/metadata-operation.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/trouble-shooting/metadata-operation.md
index 5b6aa1e8da5..b547f11821f 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/trouble-shooting/metadata-operation.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/current/admin-manual/trouble-shooting/metadata-operation.md
@@ -270,7 +270,9 @@ mysql> show proc "/bdbje/110589/114861";
FE 的部署推荐，在
[安装与部署文档](../../install/deploy-manually/integrated-storage-compute-deploy-manually)
中有介绍，这里再做一些补充。
-* **如果你并不十分了解 FE 元数据的运行逻辑，或者没有足够 FE 元数据的运维经验，我们强烈建议在实际使用中，只部署一个 FOLLOWER 类型的
FE 作为 MASTER，其余 FE 都是 OBSERVER，这样可以减少很多复杂的运维问题！** 不用过于担心 MASTER
单点故障导致无法进行元数据写操作。首先，如果你配置合理，FE 作为 java 进程很难挂掉。其次，如果 MASTER 磁盘损坏（概率非常低），我们也可以用
OBSERVER 上的元数据，通过 `元数据恢复模式` 的方式手动恢复。
+* 生产环境建议部署 **奇数个 FOLLOWER**（通常为 3 个：1 个 MASTER + 2 个
FOLLOWER），以保证元数据写入高可用。FOLLOWER 参与选举和多数写；Master 故障时，其余 FOLLOWER 会自动选出新
Master。Observer 不参与选举，只同步元数据，适合用来扩展 FE 读能力。测试或开发环境可以只部署 1 个 FOLLOWER。
+
+* 多数写意味着一条 journal 必须写入多数 FOLLOWER 才算成功。3 个 FOLLOWER 时允许 1 个故障；如果同时只剩 1
个存活，该节点也无法继续写元数据。这是预期行为，不是避免部署 3 个 FOLLOWER 的理由。请保证 FOLLOWER 节点时钟同步、JVM
内存充足，并避免同时停掉多数 FOLLOWER。
* FE 进程的 JVM 一定要保证足够的内存。我们**强烈建议** FE 的 JVM 内存至少在 10GB 以上，推荐 32GB 至
64GB。并且部署监控来监控 JVM 的内存使用情况。因为如果 FE 出现 OOM，可能导致元数据写入失败，造成一些**无法恢复**的故障！
@@ -303,7 +305,7 @@ FE 的部署推荐，在 [安装与部署文档](../../install/deploy-manually/i
5. FOLLOWER FE 接连挂掉
- 因为 Doris 的元数据采用多数写策略，即一条元数据 journal 必须至少写入多数个 FOLLOWER FE 后（比如 3 个
FOLLOWER，必须写成功 2 个），才算成功。而如果写入失败，FE 进程会主动退出。那么假设有 A、B、C 三个 FOLLOWER，C 先挂掉，然后 B
再挂掉，那么 A 也会跟着挂掉。所以如 `最佳实践` 一节中所述，如果你没有丰富的元数据运维经验，不建议部署多 FOLLOWER。
+ 因为 Doris 的元数据采用多数写策略，即一条元数据 journal 必须至少写入多数个 FOLLOWER FE 后（比如 3 个
FOLLOWER，必须写成功 2 个），才算成功。而如果写入失败，FE 进程会主动退出。那么假设有 A、B、C 三个 FOLLOWER，C 先挂掉，然后 B
再挂掉，那么 A 也会跟着挂掉。这是多数写的预期行为。生产环境仍建议部署 3 个 FOLLOWER；运维时不要同时停掉多数 FOLLOWER。如果只剩 1 个
FOLLOWER 存活，应先恢复其他 FOLLOWER，再一起启动，而不是只启动这一个。否则会出现第 1 条里的 `meta out of date`。
6. fe.log 中出现 `get exception when try to close previously opened bdb database.
ignore it`
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/trouble-shooting/metadata-operation.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/trouble-shooting/metadata-operation.md
index 5b6aa1e8da5..b547f11821f 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/trouble-shooting/metadata-operation.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/admin-manual/trouble-shooting/metadata-operation.md
@@ -270,7 +270,9 @@ mysql> show proc "/bdbje/110589/114861";
FE 的部署推荐，在
[安装与部署文档](../../install/deploy-manually/integrated-storage-compute-deploy-manually)
中有介绍，这里再做一些补充。
-* **如果你并不十分了解 FE 元数据的运行逻辑，或者没有足够 FE 元数据的运维经验，我们强烈建议在实际使用中，只部署一个 FOLLOWER 类型的
FE 作为 MASTER，其余 FE 都是 OBSERVER，这样可以减少很多复杂的运维问题！** 不用过于担心 MASTER
单点故障导致无法进行元数据写操作。首先，如果你配置合理，FE 作为 java 进程很难挂掉。其次，如果 MASTER 磁盘损坏（概率非常低），我们也可以用
OBSERVER 上的元数据，通过 `元数据恢复模式` 的方式手动恢复。
+* 生产环境建议部署 **奇数个 FOLLOWER**（通常为 3 个：1 个 MASTER + 2 个
FOLLOWER），以保证元数据写入高可用。FOLLOWER 参与选举和多数写；Master 故障时，其余 FOLLOWER 会自动选出新
Master。Observer 不参与选举，只同步元数据，适合用来扩展 FE 读能力。测试或开发环境可以只部署 1 个 FOLLOWER。
+
+* 多数写意味着一条 journal 必须写入多数 FOLLOWER 才算成功。3 个 FOLLOWER 时允许 1 个故障；如果同时只剩 1
个存活，该节点也无法继续写元数据。这是预期行为，不是避免部署 3 个 FOLLOWER 的理由。请保证 FOLLOWER 节点时钟同步、JVM
内存充足，并避免同时停掉多数 FOLLOWER。
* FE 进程的 JVM 一定要保证足够的内存。我们**强烈建议** FE 的 JVM 内存至少在 10GB 以上，推荐 32GB 至
64GB。并且部署监控来监控 JVM 的内存使用情况。因为如果 FE 出现 OOM，可能导致元数据写入失败，造成一些**无法恢复**的故障！
@@ -303,7 +305,7 @@ FE 的部署推荐，在 [安装与部署文档](../../install/deploy-manually/i
5. FOLLOWER FE 接连挂掉
- 因为 Doris 的元数据采用多数写策略，即一条元数据 journal 必须至少写入多数个 FOLLOWER FE 后（比如 3 个
FOLLOWER，必须写成功 2 个），才算成功。而如果写入失败，FE 进程会主动退出。那么假设有 A、B、C 三个 FOLLOWER，C 先挂掉，然后 B
再挂掉，那么 A 也会跟着挂掉。所以如 `最佳实践` 一节中所述，如果你没有丰富的元数据运维经验，不建议部署多 FOLLOWER。
+ 因为 Doris 的元数据采用多数写策略，即一条元数据 journal 必须至少写入多数个 FOLLOWER FE 后（比如 3 个
FOLLOWER，必须写成功 2 个），才算成功。而如果写入失败，FE 进程会主动退出。那么假设有 A、B、C 三个 FOLLOWER，C 先挂掉，然后 B
再挂掉，那么 A 也会跟着挂掉。这是多数写的预期行为。生产环境仍建议部署 3 个 FOLLOWER；运维时不要同时停掉多数 FOLLOWER。如果只剩 1 个
FOLLOWER 存活，应先恢复其他 FOLLOWER，再一起启动，而不是只启动这一个。否则会出现第 1 条里的 `meta out of date`。
6. fe.log 中出现 `get exception when try to close previously opened bdb database.
ignore it`
diff --git
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/trouble-shooting/metadata-operation.md
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/trouble-shooting/metadata-operation.md
index 5b6aa1e8da5..b547f11821f 100644
---
a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/trouble-shooting/metadata-operation.md
+++
b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/admin-manual/trouble-shooting/metadata-operation.md
@@ -270,7 +270,9 @@ mysql> show proc "/bdbje/110589/114861";
FE 的部署推荐，在
[安装与部署文档](../../install/deploy-manually/integrated-storage-compute-deploy-manually)
中有介绍，这里再做一些补充。
-* **如果你并不十分了解 FE 元数据的运行逻辑，或者没有足够 FE 元数据的运维经验，我们强烈建议在实际使用中，只部署一个 FOLLOWER 类型的
FE 作为 MASTER，其余 FE 都是 OBSERVER，这样可以减少很多复杂的运维问题！** 不用过于担心 MASTER
单点故障导致无法进行元数据写操作。首先，如果你配置合理，FE 作为 java 进程很难挂掉。其次，如果 MASTER 磁盘损坏（概率非常低），我们也可以用
OBSERVER 上的元数据，通过 `元数据恢复模式` 的方式手动恢复。
+* 生产环境建议部署 **奇数个 FOLLOWER**（通常为 3 个：1 个 MASTER + 2 个
FOLLOWER），以保证元数据写入高可用。FOLLOWER 参与选举和多数写；Master 故障时，其余 FOLLOWER 会自动选出新
Master。Observer 不参与选举，只同步元数据，适合用来扩展 FE 读能力。测试或开发环境可以只部署 1 个 FOLLOWER。
+
+* 多数写意味着一条 journal 必须写入多数 FOLLOWER 才算成功。3 个 FOLLOWER 时允许 1 个故障；如果同时只剩 1
个存活，该节点也无法继续写元数据。这是预期行为，不是避免部署 3 个 FOLLOWER 的理由。请保证 FOLLOWER 节点时钟同步、JVM
内存充足，并避免同时停掉多数 FOLLOWER。
* FE 进程的 JVM 一定要保证足够的内存。我们**强烈建议** FE 的 JVM 内存至少在 10GB 以上，推荐 32GB 至
64GB。并且部署监控来监控 JVM 的内存使用情况。因为如果 FE 出现 OOM，可能导致元数据写入失败，造成一些**无法恢复**的故障！
@@ -303,7 +305,7 @@ FE 的部署推荐，在 [安装与部署文档](../../install/deploy-manually/i
5. FOLLOWER FE 接连挂掉
- 因为 Doris 的元数据采用多数写策略，即一条元数据 journal 必须至少写入多数个 FOLLOWER FE 后（比如 3 个
FOLLOWER，必须写成功 2 个），才算成功。而如果写入失败，FE 进程会主动退出。那么假设有 A、B、C 三个 FOLLOWER，C 先挂掉，然后 B
再挂掉，那么 A 也会跟着挂掉。所以如 `最佳实践` 一节中所述，如果你没有丰富的元数据运维经验，不建议部署多 FOLLOWER。
+ 因为 Doris 的元数据采用多数写策略，即一条元数据 journal 必须至少写入多数个 FOLLOWER FE 后（比如 3 个
FOLLOWER，必须写成功 2 个），才算成功。而如果写入失败，FE 进程会主动退出。那么假设有 A、B、C 三个 FOLLOWER，C 先挂掉，然后 B
再挂掉，那么 A 也会跟着挂掉。这是多数写的预期行为。生产环境仍建议部署 3 个 FOLLOWER；运维时不要同时停掉多数 FOLLOWER。如果只剩 1 个
FOLLOWER 存活，应先恢复其他 FOLLOWER，再一起启动，而不是只启动这一个。否则会出现第 1 条里的 `meta out of date`。
6. fe.log 中出现 `get exception when try to close previously opened bdb database.
ignore it`
diff --git
a/versioned_docs/version-3.x/admin-manual/trouble-shooting/metadata-operation.md
b/versioned_docs/version-3.x/admin-manual/trouble-shooting/metadata-operation.md
index 635764c1c9a..76b02a419b0 100644
---
a/versioned_docs/version-3.x/admin-manual/trouble-shooting/metadata-operation.md
+++
b/versioned_docs/version-3.x/admin-manual/trouble-shooting/metadata-operation.md
@@ -270,7 +270,9 @@ The third level can display the value information of the
specified key.
The deployment recommendation of FE is described in the Installation and
[Deployment
Document](../../install/deploy-manually/integrated-storage-compute-deploy-manually).
Here are some supplements.
-* **If you don't know the operation logic of FE metadata very well, or you
don't have enough experience in the operation and maintenance of FE metadata,
we strongly recommend that only one FOLLOWER-type FE be deployed as MASTER in
practice, and the other FEs are OBSERVER, which can reduce many complex
operation and maintenance problems.** Don't worry too much about the failure of
MASTER single point to write metadata. First, if you configure it properly, FE
as a java process is very diff [...]
+* In production, deploy an **odd number of FOLLOWER FEs** (typically 3: 1
MASTER + 2 FOLLOWERs) so that metadata writes remain highly available.
FOLLOWERs participate in leader election and majority writes; if the Master
fails, the remaining FOLLOWERs elect a new Master. OBSERVERs do not participate
in elections; they only sync metadata and are used to scale FE read capacity. A
single FOLLOWER is acceptable for test or development.
+
+* Majority write means a journal is committed only after it is written to a
majority of FOLLOWERs. With 3 FOLLOWERs, one failure is tolerated; if only one
FOLLOWER remains, it cannot continue writing metadata. This is expected, not a
reason to avoid a 3-FOLLOWER deployment. Keep FOLLOWER clocks in sync, give the
FE JVM enough memory, and do not stop a majority of FOLLOWERs at the same time.
* The JVM of the FE process must ensure sufficient memory. We **strongly
recommend** that FE's JVM memory should be at least 10GB and 32GB to 64GB. And
deploy monitoring to monitor JVM memory usage. Because if OOM occurs in FE,
metadata writing may fail, resulting in some failures that **cannot recover**!
@@ -304,7 +306,7 @@ The deployment recommendation of FE is described in the
Installation and [Deploy
5. FOLLOWER FE hangs up one after another
- Because Doris's metadata adopts the majority writing strategy, that is,
a metadata journal must be written to at least a number of FOLLOWER FEs (for
example, three FOLLOWERs, two must be written successfully) before it can be
considered successful. If the write fails, the FE process exits on its own
initiative. So suppose there are three FOLLOWERs: A, B and C. C hangs up first,
and then B hangs up, then A will hang up. So as described in the `Best
Practices `section, if you don't have e [...]
+ Because Doris's metadata adopts the majority writing strategy, that is,
a metadata journal must be written to at least a number of FOLLOWER FEs (for
example, three FOLLOWERs, two must be written successfully) before it can be
considered successful. If the write fails, the FE process exits on its own
initiative. So suppose there are three FOLLOWERs: A, B and C. C hangs up first,
and then B hangs up, then A will hang up. This is expected majority-write
behavior. Production environments sh [...]
6. fe.log 中出现 `get exception when try to close previously opened bdb database.
ignore it`
diff --git
a/versioned_docs/version-4.x/admin-manual/trouble-shooting/metadata-operation.md
b/versioned_docs/version-4.x/admin-manual/trouble-shooting/metadata-operation.md
index b450773025f..6fc10133f59 100644
---
a/versioned_docs/version-4.x/admin-manual/trouble-shooting/metadata-operation.md
+++
b/versioned_docs/version-4.x/admin-manual/trouble-shooting/metadata-operation.md
@@ -270,7 +270,9 @@ The third level can display the value information of the
specified key.
The deployment recommendation of FE is described in the Installation and
[Deployment
Document](../../install/deploy-manually/integrated-storage-compute-deploy-manually.md).
Here are some supplements.
-* **If you don't know the operation logic of FE metadata very well, or you
don't have enough experience in the operation and maintenance of FE metadata,
we strongly recommend that only one FOLLOWER-type FE be deployed as MASTER in
practice, and the other FEs are OBSERVER, which can reduce many complex
operation and maintenance problems.** Don't worry too much about the failure of
MASTER single point to write metadata. First, if you configure it properly, FE
as a java process is very diff [...]
+* In production, deploy an **odd number of FOLLOWER FEs** (typically 3: 1
MASTER + 2 FOLLOWERs) so that metadata writes remain highly available.
FOLLOWERs participate in leader election and majority writes; if the Master
fails, the remaining FOLLOWERs elect a new Master. OBSERVERs do not participate
in elections; they only sync metadata and are used to scale FE read capacity. A
single FOLLOWER is acceptable for test or development.
+
+* Majority write means a journal is committed only after it is written to a
majority of FOLLOWERs. With 3 FOLLOWERs, one failure is tolerated; if only one
FOLLOWER remains, it cannot continue writing metadata. This is expected, not a
reason to avoid a 3-FOLLOWER deployment. Keep FOLLOWER clocks in sync, give the
FE JVM enough memory, and do not stop a majority of FOLLOWERs at the same time.
* The JVM of the FE process must ensure sufficient memory. We **strongly
recommend** that FE's JVM memory should be at least 10GB and 32GB to 64GB. And
deploy monitoring to monitor JVM memory usage. Because if OOM occurs in FE,
metadata writing may fail, resulting in some failures that **cannot recover**!
@@ -304,7 +306,7 @@ The deployment recommendation of FE is described in the
Installation and [Deploy
5. FOLLOWER FE hangs up one after another
- Because Doris's metadata adopts the majority writing strategy, that is,
a metadata journal must be written to at least a number of FOLLOWER FEs (for
example, three FOLLOWERs, two must be written successfully) before it can be
considered successful. If the write fails, the FE process exits on its own
initiative. So suppose there are three FOLLOWERs: A, B and C. C hangs up first,
and then B hangs up, then A will hang up. So as described in the `Best
Practices `section, if you don't have e [...]
+ Because Doris's metadata adopts the majority writing strategy, that is,
a metadata journal must be written to at least a number of FOLLOWER FEs (for
example, three FOLLOWERs, two must be written successfully) before it can be
considered successful. If the write fails, the FE process exits on its own
initiative. So suppose there are three FOLLOWERs: A, B and C. C hangs up first,
and then B hangs up, then A will hang up. This is expected majority-write
behavior. Production environments sh [...]
6. fe.log 中出现 `get exception when try to close previously opened bdb database.
ignore it`
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
