You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@hugegraph.apache.org by "imbajin (via GitHub)" <gi...@apache.org> on 2026/10/12 22:08:47 UTC
[PR] docs: explain legacy GraphID upgrade preflight [hugegraph-doc]
imbajin opened a new pull request, #523:
URL: https://github.com/apache/hugegraph-doc/pull/523
Store builds with the legacy GraphID preflight refuse affected data before allocation, cold partition opening, Raft startup or staged snapshot activation. The English and Chinese HStore configuration pages explain these checks and how to preserve DB versions, metadata, WAL and snapshot evidence after refusal.
Paired implementation: https://github.com/hugegraph/hugegraph/pull/301. The ID format stays unchanged; automatic ownership repair and complete deployment upgrades require separate validation. The upstream code PR will be linked when its org CI gate passes.
Validation: existing link and diff checks, one independent documentation review and the org site build passed. The paired implementation now uses effective column-family options for read-only checks; the duplicate review thread is resolved.
Org validation: https://github.com/hugegraph/hugegraph-doc/pull/47
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: explain legacy GraphID upgrade preflight [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on code in PR #523:
URL: https://github.com/apache/hugegraph-doc/pull/523#discussion_r4301522229
##########
content/en/docs/config/config-backend-hstore.md:
##########
@@ -246,3 +246,22 @@ curl http://localhost:8080/metrics/backend
The `nodes` value in the response is the count of active stores PD returns. A `nodes` value of `0` means the
Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.
+
+### 9 Legacy GraphID upgrade preflight
+
+HugeGraph-Store provides legacy GraphID upgrade preflight checks during bootstrap and upgrade processes.
+Released 1.7.0 and earlier Store builds do not contain this preflight guard.
+Use a Store build supporting this capability before relying on the refusal behavior below.
+
+These Store builds check existing graph-data column families before allocating a missing graph ID, first opening a cold
+partition DB during metadata bootstrap, starting its Raft state machine, or activating a staged snapshot. Before pruning, the first cold DB open checks
+all retained valid versions. Reserved `FFFE` legacy rows cause refusal.
+An incomplete selected DB version without `CURRENT` is also rejected when it would hide retained valid versions. This concerns affected old write paths;
+it does not mean that every 1.7 database needs migration, and the persisted ID format is unchanged.
+
+On refusal, preserve the original data DB versions, metadata, WAL and incoming/staged snapshots. Investigate the affected write and upgrade history before
Review Comment:
Updated both languages to explicitly state that released 1.7.0 and current master builds do not yet contain this preflight check (pending merge of the Store implementation), and pinned the documentation link to avoid 404. Once the code PR #3330 finalizes its refusal handling, we will document the exact observable Store state and logs accordingly.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: explain legacy GraphID upgrade preflight [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on code in PR #523:
URL: https://github.com/apache/hugegraph-doc/pull/523#discussion_r4254753947
##########
content/en/docs/config/config-backend-hstore.md:
##########
@@ -246,3 +246,17 @@ curl http://localhost:8080/metrics/backend
The `nodes` value in the response is the count of active stores PD returns. A `nodes` value of `0` means the
Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.
+
+Store builds containing the legacy GraphID preflight check existing graph-data column families before allocating a missing graph ID, first opening a cold
+partition DB during metadata bootstrap, starting its Raft state machine, or activating a staged snapshot. Before pruning, the first cold DB open checks
+all retained valid versions. Reserved `FFFE` legacy rows cause refusal.
+An incomplete selected DB version without `CURRENT` is also rejected when it would hide retained valid versions. This concerns affected old write paths;
+it does not mean that every 1.7 database needs migration, and the persisted ID format is unchanged.
+
+On refusal, preserve the original data DB versions, metadata, WAL and incoming/staged snapshots. Investigate the affected write and upgrade history before
+resuming writes or replay. Do not delete graph-to-ID mappings or assign all reserved-prefix rows to one graph: different graphs may share that prefix.
+Store/Raft location metadata may already have been updated before the check, so the entire bootstrap is not read-only. The check performs no automatic
+migration or ownership repair; a complete 1.7 upgrade and recovery still require deployment-specific validation.
+
+See the [preflight change](https://github.com/hugegraph/hugegraph/pull/301) and the
Review Comment:
Addressed in [the bilingual documentation correction](https://github.com/apache/hugegraph-doc/commit/0f296459c2adcd515429c04857d875b2fff289ab). Both pages now link the proposed [Apache HugeGraph #3330](https://github.com/apache/hugegraph/pull/3330) implementation, explicitly state that it is unmerged and absent from Apache releases, and limit the refusal behavior to builds containing that fix. The guide is pinned to the proposed revision. Coordinated code/docs merge and complete deployment upgrade/recovery acceptance remain open.
##########
content/en/docs/config/config-backend-hstore.md:
##########
@@ -246,3 +246,17 @@ curl http://localhost:8080/metrics/backend
The `nodes` value in the response is the count of active stores PD returns. A `nodes` value of `0` means the
Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.
+
+Store builds containing the legacy GraphID preflight check existing graph-data column families before allocating a missing graph ID, first opening a cold
Review Comment:
Fixed in [the bilingual documentation correction](https://github.com/apache/hugegraph-doc/commit/0f296459c2adcd515429c04857d875b2fff289ab). The English and Chinese pages now have their own numbered “9 Legacy GraphID upgrade preflight” / “9 旧 GraphID 升级预检” sections. Strict Hugo builds, link checks and rendered heading/outline readback passed for both languages.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: explain legacy GraphID upgrade preflight [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on code in PR #523:
URL: https://github.com/apache/hugegraph-doc/pull/523#discussion_r4260704655
##########
content/en/docs/config/config-backend-hstore.md:
##########
@@ -246,3 +246,25 @@ curl http://localhost:8080/metrics/backend
The `nodes` value in the response is the count of active stores PD returns. A `nodes` value of `0` means the
Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.
+
+### 9 Legacy GraphID upgrade preflight
+
+The following checks apply only to Store builds containing the implementation proposed in
+[Apache HugeGraph #3330](https://github.com/apache/hugegraph/pull/3330).
+This change is not yet merged into Apache HugeGraph or included in an Apache release. Earlier 1.8 builds do not guarantee this guard; verify that your
Review Comment:
Clarified both language versions: released 1.7 and current Apache master lack the proposed guard. The complete upgrade and recovery acceptance remains separately tracked. The published source matches the independently reviewed documentation update.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: explain legacy GraphID upgrade preflight [hugegraph-doc]
Posted by "bitflicker64 (via GitHub)" <gi...@apache.org>.
bitflicker64 commented on code in PR #523:
URL: https://github.com/apache/hugegraph-doc/pull/523#discussion_r4301465856
##########
content/en/docs/config/config-backend-hstore.md:
##########
@@ -246,3 +246,22 @@ curl http://localhost:8080/metrics/backend
The `nodes` value in the response is the count of active stores PD returns. A `nodes` value of `0` means the
Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.
+
+### 9 Legacy GraphID upgrade preflight
+
+HugeGraph-Store provides legacy GraphID upgrade preflight checks during bootstrap and upgrade processes.
+Released 1.7.0 and earlier Store builds do not contain this preflight guard.
+Use a Store build supporting this capability before relying on the refusal behavior below.
+
+These Store builds check existing graph-data column families before allocating a missing graph ID, first opening a cold
+partition DB during metadata bootstrap, starting its Raft state machine, or activating a staged snapshot. Before pruning, the first cold DB open checks
+all retained valid versions. Reserved `FFFE` legacy rows cause refusal.
+An incomplete selected DB version without `CURRENT` is also rejected when it would hide retained valid versions. This concerns affected old write paths;
+it does not mean that every 1.7 database needs migration, and the persisted ID format is unchanged.
+
+On refusal, preserve the original data DB versions, metadata, WAL and incoming/staged snapshots. Investigate the affected write and upgrade history before
Review Comment:
Minor: once #3330 lands, this section should say what a refusal does to the Store as a whole. At d9ff79f a cold-open refusal is not partition-scoped: `PartitionManager.loadPartitions` reaches the validator through `wrapper.scan` -> `getSession` -> `createGraphDB` with no catch, and `HgStoreEngine.stateChanged` only catches `InvalidShardException`, so `restoreLocalPartitionEngine` never runs. The Store keeps heartbeating and stays `Up` in PD, which the `nodes` check in section 8 reads as healthy.
This is a code question already open on #3330 (per-partition skip or explicit exit), so it is not a defect in this page yet. When #3330 settles it, please add the observable result in both pages (here and CN line 222): scope, Store state in PD, and the log line to look for.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: explain legacy GraphID upgrade preflight [hugegraph-doc]
Posted by "imbajin (via GitHub)" <gi...@apache.org>.
imbajin commented on code in PR #523:
URL: https://github.com/apache/hugegraph-doc/pull/523#discussion_r4260701920
##########
content/en/docs/config/config-backend-hstore.md:
##########
@@ -246,3 +246,25 @@ curl http://localhost:8080/metrics/backend
The `nodes` value in the response is the count of active stores PD returns. A `nodes` value of `0` means the
Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.
+
+### 9 Legacy GraphID upgrade preflight
+
+The following checks apply only to Store builds containing the implementation proposed in
+[Apache HugeGraph #3330](https://github.com/apache/hugegraph/pull/3330).
+This change is not yet merged into Apache HugeGraph or included in an Apache release. Earlier 1.8 builds do not guarantee this guard; verify that your
+build contains the fix before relying on the refusal behavior below.
+
+These Store builds check existing graph-data column families before allocating a missing graph ID, first opening a cold
+partition DB during metadata bootstrap, starting its Raft state machine, or activating a staged snapshot. Before pruning, the first cold DB open checks
+all retained valid versions. Reserved `FFFE` legacy rows cause refusal.
+An incomplete selected DB version without `CURRENT` is also rejected when it would hide retained valid versions. This concerns affected old write paths;
+it does not mean that every 1.7 database needs migration, and the persisted ID format is unchanged.
+
+On refusal, preserve the original data DB versions, metadata, WAL and incoming/staged snapshots. Investigate the affected write and upgrade history before
+resuming writes or replay. Do not delete graph-to-ID mappings or assign all reserved-prefix rows to one graph: different graphs may share that prefix.
+Store/Raft location metadata may already have been updated before the check, so the entire bootstrap is not read-only. The check performs no automatic
+migration or ownership repair; a complete 1.7 upgrade and recovery still require deployment-specific validation.
+
+See the
+[guide for the proposed revision](https://github.com/hugegraph/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)
Review Comment:
Updated both language versions to link the same pinned guide under apache/hugegraph. The Apache and fork files at that source revision have identical contents. The paired Server PR remains open; the link and availability note will be rechecked when it merges.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: explain legacy GraphID upgrade preflight [hugegraph-doc]
Posted by "bitflicker64 (via GitHub)" <gi...@apache.org>.
bitflicker64 commented on code in PR #523:
URL: https://github.com/apache/hugegraph-doc/pull/523#discussion_r4254176827
##########
content/en/docs/config/config-backend-hstore.md:
##########
@@ -246,3 +246,17 @@ curl http://localhost:8080/metrics/backend
The `nodes` value in the response is the count of active stores PD returns. A `nodes` value of `0` means the
Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.
+
+Store builds containing the legacy GraphID preflight check existing graph-data column families before allocating a missing graph ID, first opening a cold
Review Comment:
Minor: the new text is appended to `### 8 Verification` directly after the `nodes` metrics explanation, with no heading of its own (same on line 212 of the Chinese page).
Evidence: at this head the last heading in the page is `### 8 Verification` (line 237), and its content is the post-configuration `curl` checks. The upgrade refusal and evidence-preservation guidance is a different topic, has no anchor to link to from release notes or an error message, and does not show up in the page outline.
Requested change: put it under its own heading in both languages, for example `### 9 Legacy GraphID upgrade preflight` / `### 9 旧 GraphID 升级预检`.
##########
content/en/docs/config/config-backend-hstore.md:
##########
@@ -246,3 +246,17 @@ curl http://localhost:8080/metrics/backend
The `nodes` value in the response is the count of active stores PD returns. A `nodes` value of `0` means the
Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.
+
+Store builds containing the legacy GraphID preflight check existing graph-data column families before allocating a missing graph ID, first opening a cold
+partition DB during metadata bootstrap, starting its Raft state machine, or activating a staged snapshot. Before pruning, the first cold DB open checks
+all retained valid versions. Reserved `FFFE` legacy rows cause refusal.
+An incomplete selected DB version without `CURRENT` is also rejected when it would hide retained valid versions. This concerns affected old write paths;
+it does not mean that every 1.7 database needs migration, and the persisted ID format is unchanged.
+
+On refusal, preserve the original data DB versions, metadata, WAL and incoming/staged snapshots. Investigate the affected write and upgrade history before
+resuming writes or replay. Do not delete graph-to-ID mappings or assign all reserved-prefix rows to one graph: different graphs may share that prefix.
+Store/Raft location metadata may already have been updated before the check, so the entire bootstrap is not read-only. The check performs no automatic
+migration or ownership repair; a complete 1.7 upgrade and recovery still require deployment-specific validation.
+
+See the [preflight change](https://github.com/hugegraph/hugegraph/pull/301) and the
Review Comment:
Important: these paragraphs describe a Store refusal that no apache/hugegraph build performs yet, and both references point at an unmerged PR in the `hugegraph/hugegraph` fork.
Evidence: on apache/hugegraph master (2ae73704c) `git grep -n "checkLegacyGraphIdData\|resolveExistingDBPath\|store-graphid"` returns nothing, and `docs/store-graphid-upgrade.md` does not exist there. The check lives only in hugegraph/hugegraph#301, which is still open at 27731930, and a search of apache/hugegraph finds no matching PR. The same two links are on lines 221-222 of `content/cn/docs/config/config-backend-hstore.md`.
Once this is published on hugegraph.apache.org, an operator on 1.7.0 or current master who has reserved-prefix rows will read that Store refuses before allocating a graph ID, while their build allocates and continues. "Store builds containing the legacy GraphID preflight" gives them no way to tell which builds those are.
Requested change: hold this until the implementation is merged in apache/hugegraph, then name the first release that contains it and link the apache PR and the guide on apache master. If it has to land earlier, state in both pages that the check is not in any Apache release yet.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: explain legacy GraphID upgrade preflight [hugegraph-doc]
Posted by "bitflicker64 (via GitHub)" <gi...@apache.org>.
bitflicker64 commented on code in PR #523:
URL: https://github.com/apache/hugegraph-doc/pull/523#discussion_r4257616971
##########
content/en/docs/config/config-backend-hstore.md:
##########
@@ -246,3 +246,25 @@ curl http://localhost:8080/metrics/backend
The `nodes` value in the response is the count of active stores PD returns. A `nodes` value of `0` means the
Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.
+
+### 9 Legacy GraphID upgrade preflight
+
+The following checks apply only to Store builds containing the implementation proposed in
+[Apache HugeGraph #3330](https://github.com/apache/hugegraph/pull/3330).
+This change is not yet merged into Apache HugeGraph or included in an Apache release. Earlier 1.8 builds do not guarantee this guard; verify that your
Review Comment:
Minor: "Earlier 1.8 builds do not guarantee this guard" is weaker than the code and leaves out the release people actually run (same wording on line 215 of the Chinese page: "更早的 1.8 构建不保证具备该保护").
Evidence: `git grep -c "checkLegacyGraphIdData\|resolveExistingDBPath" origin/master -- hugegraph-store` on apache/hugegraph master (0b7c0de3e) returns nothing, and the 1.7.0 tag has neither method. 1.7.0 is also where the sentinel comes from (`GraphIdManager.maxGraphID = 65535 - 1`, which is `0xFFFE`). So the check is absent from 1.7.0 and from every master build so far, not merely unguaranteed, and a 1.7.0 operator reading "earlier 1.8 builds" is not told that their Store never refuses.
Requested change: state it as a fact in both pages, for example "No Apache release, including 1.7.0, and no `master` build before #3330 contains this check". This sentence and "not yet merged" also need an update in the same change that merges #3330, so please note that on the code PR.
##########
content/en/docs/config/config-backend-hstore.md:
##########
@@ -246,3 +246,25 @@ curl http://localhost:8080/metrics/backend
The `nodes` value in the response is the count of active stores PD returns. A `nodes` value of `0` means the
Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.
+
+### 9 Legacy GraphID upgrade preflight
+
+The following checks apply only to Store builds containing the implementation proposed in
+[Apache HugeGraph #3330](https://github.com/apache/hugegraph/pull/3330).
+This change is not yet merged into Apache HugeGraph or included in an Apache release. Earlier 1.8 builds do not guarantee this guard; verify that your
+build contains the fix before relying on the refusal behavior below.
+
+These Store builds check existing graph-data column families before allocating a missing graph ID, first opening a cold
+partition DB during metadata bootstrap, starting its Raft state machine, or activating a staged snapshot. Before pruning, the first cold DB open checks
+all retained valid versions. Reserved `FFFE` legacy rows cause refusal.
+An incomplete selected DB version without `CURRENT` is also rejected when it would hide retained valid versions. This concerns affected old write paths;
+it does not mean that every 1.7 database needs migration, and the persisted ID format is unchanged.
+
+On refusal, preserve the original data DB versions, metadata, WAL and incoming/staged snapshots. Investigate the affected write and upgrade history before
+resuming writes or replay. Do not delete graph-to-ID mappings or assign all reserved-prefix rows to one graph: different graphs may share that prefix.
+Store/Raft location metadata may already have been updated before the check, so the entire bootstrap is not read-only. The check performs no automatic
+migration or ownership repair; a complete 1.7 upgrade and recovery still require deployment-specific validation.
+
+See the
+[guide for the proposed revision](https://github.com/hugegraph/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)
Review Comment:
Minor: this guide link (and the one on line 226 of `content/cn/docs/config/config-backend-hstore.md`) points at the `hugegraph/hugegraph` fork, while the sentence above it cites Apache HugeGraph #3330 as the source.
Evidence: 27731930 is the current head of apache/hugegraph#3330, and the same file resolves in the Apache repository: `gh api -X GET "repos/apache/hugegraph/contents/docs/store-graphid-upgrade.md?ref=27731930ce4573481ac2f01092a288b0db239b53"` returns `https://github.com/apache/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md`. A page on hugegraph.apache.org then sends readers to a non-Apache organisation for the upgrade guidance, and the two references in one section name two different repositories for one change.
Requested change: use the apache/hugegraph URL for the pinned revision in both pages, and switch it to the `master` path once #3330 is merged.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org
Re: [PR] docs: explain legacy GraphID upgrade preflight [hugegraph-doc]
Posted by "bitflicker64 (via GitHub)" <gi...@apache.org>.
bitflicker64 commented on code in PR #523:
URL: https://github.com/apache/hugegraph-doc/pull/523#discussion_r4304096927
##########
content/cn/docs/config/config-backend-hstore.md:
##########
@@ -208,3 +208,27 @@ curl http://localhost:8080/metrics/backend
```
响应中的 `nodes` 就是 PD 返回的活跃 Store 数量。`nodes` 为 `0` 说明 Server 连上了 PD，但 PD 中没有状态为 `Up` 的 Store，通常是 Store 节点还没注册，或者因为不在 PD 的 `pd.initial-store-list` 中而注册成了 `Pending`。
+
+### 9 旧 GraphID 升级预检
+
+HugeGraph-Store 在启动和升级流程中提供针对旧版 GraphID 的安全预检保护机制。
+
+> [!NOTE]
+> 已发布的 1.7.0 发行版以及当前 `master` 分支暂未包含该预检保护（待对应 Store 补丁合并）；
+> 依赖下述拦截保护前，请确认使用的是已包含该修复特性的 Store 构建。
+
+包含该特性的 Store 构建会在分配缺失的图 ID、元数据启动阶段首次冷打开尚未缓存的分区 DB、启动对应分区的 Raft 状态机，
+或激活暂存快照前，检查已有图数据列族。首次打开时会在清理旧版本前检查所有仍保留的有效 DB 版本：
+- **旧数据前缀拦截**：发现保留前缀 `FFFE` 的旧数据时将拒绝操作并终止启动。
Review Comment:
Minor: Since 08565f95 the `FFFE` bullet on this line says the refusal also aborts startup (the clause added after the refusal verb). The English bullet (line 261) does not say it, and #3330 does not do it.
At d9ff79f a refusal rejects only the operation that hit it; the linked guide says it "rejects that operation and reports the partition and column family". Two of the four checks are not part of startup: `GraphIdManager.getGraphIdOrCreate` fails the write that needs a new graph ID, and `BusinessHandlerImpl.loadSnapshot` fails the snapshot load. On the cold open during bootstrap, the exception leaves `HgStoreEngine.stateChanged`, which handles only `InvalidShardException`, in the state-change thread, so the Store process keeps running. That is the open question in r4301465856.
Please drop the abort-startup clause so this line says only that the operation is refused, as the English text does, and describe the Store state once #3330 settles it.
##########
content/en/docs/config/config-backend-hstore.md:
##########
@@ -246,3 +246,32 @@ curl http://localhost:8080/metrics/backend
The `nodes` value in the response is the count of active stores PD returns. A `nodes` value of `0` means the
Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.
+
+### 9 Legacy GraphID upgrade preflight
+
+HugeGraph-Store provides legacy GraphID upgrade preflight guards during bootstrap and upgrade processes.
+
+> [!NOTE]
+> Released 1.7.0 and current `master` builds do not contain this preflight guard yet (pending merge of the corresponding Store implementation);
+> ensure you use a Store build containing this fix before relying on the refusal behavior below.
+
+These Store builds check existing graph-data column families before allocating a missing graph ID, first opening a cold partition DB during
+metadata bootstrap, starting its Raft state machine, or activating a staged snapshot. Before pruning, the first cold DB open checks all retained
+valid versions:
+- **Legacy Row Sentinel**: Discovered legacy rows with reserved prefix `FFFE` trigger an immediate refusal.
+- **Version Integrity Check**: An incomplete selected DB version without `CURRENT` is also rejected when it would shadow retained valid versions.
+
+This guard concerns affected legacy write paths; it does not imply that every 1.7 database requires migration, and the persisted ID format is unchanged.
+
+> [!IMPORTANT]
+> **Recommended Actions on Refusal**
+> - **Preserve Raw Data**: Keep original data DB versions, metadata, WAL, incoming snapshots, and staged copies. Investigate the affected write and
+> upgrade history before resuming writes or replay.
+> - **Avoid Mapping Deletions**: Do not delete graph-to-ID mappings or assign all reserved-prefix rows to a single graph
+> (different graphs may share that prefix).
+> - **Bootstrap Not Read-Only**: Store/Raft location metadata may already have been updated before the check, so the entire
+> bootstrap is not strictly read-only.
+> - **No Automatic Repair**: The preflight check only guards against corrupt states without automated data migration; 1.7 upgrade and recovery still require
Review Comment:
Minor: since 08565f95 this bullet no longer says that the check does no ownership repair, and it calls the affected data "corrupt states". The CN bullet (line 232) still says it performs no automatic data migration or ownership repair, and the #3330 guide says the change provides "detection and refusal, not automatic migration, repair".
Ownership repair is the step an operator is most likely to try by hand after a refusal. "Corrupt" also conflicts with line 264, which says these are rows from affected legacy write paths and that most 1.7 databases need no migration.
Please restore "performs no automatic migration or ownership repair" and drop "corrupt states", so EN and CN say the same thing.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: issues-unsubscribe@hugegraph.apache.org
For additional commands, e-mail: issues-help@hugegraph.apache.org