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: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
