From 84ddd998372f24b3efdf02116d59193b7d4f098a Mon Sep 17 00:00:00 2001 From: orion Date: Sat, 31 Oct 2026 05:49:53 +0000 Subject: [PATCH 1/3] docs: clarify Store process lifecycle endpoint --- content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md | 7 +++++++ content/en/docs/quickstart/hugegraph/hugegraph-hstore.md | 8 ++++++++ 2 files changed, 15 insertions(+) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index 919a3b1af9..99b4283396 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -494,6 +494,7 @@ Store 节点在 `server.port` 上提供以下只读接口： | GET | `/actuator/prometheus` | Prometheus 抓取接口 | | GET | `/` | 节点概览，包含 `leaderCount` 和 `partitionCount` | | GET | `/-/state` | 运维设置的节点状态标志，取值为 `STARTING`、`ONLINE`、`STOPPING`；此标志不表示 PD 注册状态 | +| GET | `/-/lifecycle` | 进程生命周期观察，仅包含相应生命周期改动的构建提供 | | GET | `/-/echo?name=` | 回显检查 | | GET | `/-/scan` | 当前扫描流的状态 | | GET | `/v1/partitions` | 本节点上的所有 Raft 组及分区指标。加上 `?flags=accurate` 可获取精确的 key 数量，但更慢。 | @@ -502,6 +503,12 @@ Store 节点在 `server.port` 上提供以下只读接口： | GET | `/metrics/drive` | 数据路径所在磁盘的指标 | | GET | `/metrics/raft` | JRaft 节点指标，需要 `raft.metrics: true` | +拟新增的 `GET /-/lifecycle` 返回如 `{"status":0,"text":"STARTED"}` 的 JSON，`text` 取值为 +`STARTING`、`STARTED`、`STOPPING` 或 `UNAVAILABLE`。`STARTED` 仅表示 Spring 已发出就绪事件，且 gRPC +服务已启动、尚未关闭。这是**进程生命周期观察**，不是存储就绪检查：它不能证明已向 PD 注册、分区已恢复、 +Raft 已追平或图读写已就绪。替换下一台 Store 之前，仍需按部署文档逐组检查。旧版 Store 不提供此接口， +会返回 HTTP 404；不能把 404 当作 `STARTED`。 + 主线发行目录的 Store 配置将 `management.endpoints.web.exposure.include` 设为 `"*"`，并启用 Prometheus；Actuator 端点没有 PD REST Basic 认证保护，请限制 Store REST 端口的网络可达范围。 节点还提供一批会修改状态或执行重负载操作的运维接口：`PUT /-/state`、`GET /-/cleaner`、`GET /v1/partition/dump/{id}`、 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index 5d39d077ee..118b3d4a5e 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -500,6 +500,7 @@ The Store node exposes these read-only endpoints on `server.port`: | GET | `/actuator/prometheus` | Prometheus scrape endpoint | | GET | `/` | Node summary, `leaderCount` and `partitionCount` | | GET | `/-/state` | Operator-set `STARTING`, `ONLINE`, or `STOPPING` flag; distinct from PD registration state | +| GET | `/-/lifecycle` | Process lifecycle observation; available only in builds containing the lifecycle change | | GET | `/-/echo?name=` | Echo check | | GET | `/-/scan` | State of the running scan streams | | GET | `/v1/partitions` | All Raft groups on this node with per-partition metrics. Add `?flags=accurate` for exact key counts, which is slower. | @@ -508,6 +509,13 @@ The Store node exposes these read-only endpoints on `server.port`: | GET | `/metrics/drive` | Disk metrics for the data paths | | GET | `/metrics/raft` | JRaft node metrics, needs `raft.metrics: true` | +The proposed `GET /-/lifecycle` endpoint returns JSON such as `{"status":0,"text":"STARTED"}`. Its `text` is +`STARTING`, `STARTED`, `STOPPING`, or `UNAVAILABLE`. `STARTED` means Spring reached its ready event and the gRPC +server started and has not shut down. It is a **process lifecycle observation**, not a storage readiness check: +it does not establish PD registration, partition restoration, Raft catch-up, or graph read/write readiness. +Continue using the deployment's documented per-group checks before replacing another Store. Older Store versions +do not provide this endpoint and return HTTP 404; a 404 must not be treated as `STARTED`. + Master Store configuration exposes all Actuator endpoints with `management.endpoints.web.exposure.include: "*"` and enables Prometheus. These endpoints lack PD REST Basic protection; restrict Store REST network access. The node also serves maintenance endpoints that change state or run heavy work: `PUT /-/state`, `GET /-/cleaner`, From 77d1a1ef53593bf50e77aeba46c897aa7604e676 Mon Sep 17 00:00:00 2001 From: dark Date: Sun, 1 Nov 2026 17:37:16 +0800 Subject: [PATCH 2/3] docs(store): document GET /-/lifecycle and distinguish from readiness checks --- .../quickstart/hugegraph/hugegraph-hstore.md | 18 ++++++++++++------ .../quickstart/hugegraph/hugegraph-hstore.md | 19 ++++++++++++------- 2 files changed, 24 insertions(+), 13 deletions(-) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index 99b4283396..3a250f84c2 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -494,7 +494,7 @@ Store 节点在 `server.port` 上提供以下只读接口： | GET | `/actuator/prometheus` | Prometheus 抓取接口 | | GET | `/` | 节点概览，包含 `leaderCount` 和 `partitionCount` | | GET | `/-/state` | 运维设置的节点状态标志，取值为 `STARTING`、`ONLINE`、`STOPPING`；此标志不表示 PD 注册状态 | -| GET | `/-/lifecycle` | 进程生命周期观察，仅包含相应生命周期改动的构建提供 | +| GET | `/-/lifecycle` | 进程生命周期状态（1.8.0+ 提供） | | GET | `/-/echo?name=` | 回显检查 | | GET | `/-/scan` | 当前扫描流的状态 | | GET | `/v1/partitions` | 本节点上的所有 Raft 组及分区指标。加上 `?flags=accurate` 可获取精确的 key 数量，但更慢。 | @@ -503,11 +503,17 @@ Store 节点在 `server.port` 上提供以下只读接口： | GET | `/metrics/drive` | 数据路径所在磁盘的指标 | | GET | `/metrics/raft` | JRaft 节点指标，需要 `raft.metrics: true` | -拟新增的 `GET /-/lifecycle` 返回如 `{"status":0,"text":"STARTED"}` 的 JSON，`text` 取值为 -`STARTING`、`STARTED`、`STOPPING` 或 `UNAVAILABLE`。`STARTED` 仅表示 Spring 已发出就绪事件，且 gRPC -服务已启动、尚未关闭。这是**进程生命周期观察**，不是存储就绪检查：它不能证明已向 PD 注册、分区已恢复、 -Raft 已追平或图读写已就绪。替换下一台 Store 之前，仍需按部署文档逐组检查。旧版 Store 不提供此接口， -会返回 HTTP 404；不能把 404 当作 `STARTED`。 +`GET /-/lifecycle` 返回 JSON 格式的进程生命周期状态，形如 `{"status":0,"text":"STARTED"}`。其中 `text` 包含四种状态： +- `STARTING`：Spring 上下文或 gRPC 服务仍在启动中； +- `STARTED`：Spring 应用已就绪（ApplicationReadyEvent）且 gRPC 服务已启动运行； +- `STOPPING`：进程已进入关闭流程（ContextClosedEvent，优先级最高）； +- `UNAVAILABLE`：gRPC 服务已提前停止或已终止。 + +> [!WARNING] +> **进程生命周期不等于集群就绪**： +> `STARTED` 仅代表本地 JVM 与 gRPC 服务的进程状态，**不代表节点已就绪对外提供服务**。它不能证明节点已成功向 PD 注册、分片已完成恢复或 Raft 副本已追平日志。 +> - 在执行滚动重启或下线节点前，必须通过 PD 端点 `GET /v1/stores` 确认节点处于 `Up` 状态，并通过 `GET /v1/partitions` 确认本节点所有 Raft 分区状态健康，切勿仅凭 `STARTED` 作为滚动更新门禁。 +> - 1.8.0 之前的旧版本 Store 未提供此接口，调用将返回 HTTP 404；不能将 404 视为已启动或可替换状态。 主线发行目录的 Store 配置将 `management.endpoints.web.exposure.include` 设为 `"*"`，并启用 Prometheus；Actuator 端点没有 PD REST Basic 认证保护，请限制 Store REST 端口的网络可达范围。 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index 118b3d4a5e..8ef3a0e4bf 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -500,7 +500,7 @@ The Store node exposes these read-only endpoints on `server.port`: | GET | `/actuator/prometheus` | Prometheus scrape endpoint | | GET | `/` | Node summary, `leaderCount` and `partitionCount` | | GET | `/-/state` | Operator-set `STARTING`, `ONLINE`, or `STOPPING` flag; distinct from PD registration state | -| GET | `/-/lifecycle` | Process lifecycle observation; available only in builds containing the lifecycle change | +| GET | `/-/lifecycle` | Process lifecycle state (available in 1.8.0+) | | GET | `/-/echo?name=` | Echo check | | GET | `/-/scan` | State of the running scan streams | | GET | `/v1/partitions` | All Raft groups on this node with per-partition metrics. Add `?flags=accurate` for exact key counts, which is slower. | @@ -509,12 +509,17 @@ The Store node exposes these read-only endpoints on `server.port`: | GET | `/metrics/drive` | Disk metrics for the data paths | | GET | `/metrics/raft` | JRaft node metrics, needs `raft.metrics: true` | -The proposed `GET /-/lifecycle` endpoint returns JSON such as `{"status":0,"text":"STARTED"}`. Its `text` is -`STARTING`, `STARTED`, `STOPPING`, or `UNAVAILABLE`. `STARTED` means Spring reached its ready event and the gRPC -server started and has not shut down. It is a **process lifecycle observation**, not a storage readiness check: -it does not establish PD registration, partition restoration, Raft catch-up, or graph read/write readiness. -Continue using the deployment's documented per-group checks before replacing another Store. Older Store versions -do not provide this endpoint and return HTTP 404; a 404 must not be treated as `STARTED`. +`GET /-/lifecycle` reports the process lifecycle status as JSON, such as `{"status":0,"text":"STARTED"}`. The `text` field has four possible values: +- `STARTING`: Spring application context or gRPC service is still initializing; +- `STARTED`: Spring application is ready (ApplicationReadyEvent) and gRPC service is running; +- `STOPPING`: Process shutdown has initiated (ContextClosedEvent takes precedence); +- `UNAVAILABLE`: gRPC service stopped or terminated unexpectedly before shutdown. + +> [!WARNING] +> **Process lifecycle does not equal cluster readiness**: +> `STARTED` reflects only local JVM and gRPC process readiness, **not storage or cluster data readiness**. It does not prove that the node has registered with PD, that shards have completed restoration, or that Raft replicas have caught up. +> - Before continuing a rolling update or replacing nodes, always check PD via `GET /v1/stores` to confirm the store status is `Up`, and inspect `GET /v1/partitions` to ensure all Raft groups are healthy. Never rely solely on `STARTED` as a rolling update gate. +> - Versions prior to 1.8.0 do not support this endpoint and return HTTP 404; a 404 must not be treated as `STARTED`. Master Store configuration exposes all Actuator endpoints with `management.endpoints.web.exposure.include: "*"` and enables Prometheus. These endpoints lack PD REST Basic protection; restrict Store REST network access. From dea1931c7b858c12d250d612a735e800531a7f7e Mon Sep 17 00:00:00 2001 From: dark Date: Sun, 1 Nov 2026 17:45:18 +0800 Subject: [PATCH 3/3] docs(store): polish lifecycle warning prose and wrap lines --- content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md | 6 +++--- content/en/docs/quickstart/hugegraph/hugegraph-hstore.md | 6 ++++-- 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md index 3a250f84c2..1881caa28c 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -510,9 +510,9 @@ Store 节点在 `server.port` 上提供以下只读接口： - `UNAVAILABLE`：gRPC 服务已提前停止或已终止。 > [!WARNING] -> **进程生命周期不等于集群就绪**： -> `STARTED` 仅代表本地 JVM 与 gRPC 服务的进程状态，**不代表节点已就绪对外提供服务**。它不能证明节点已成功向 PD 注册、分片已完成恢复或 Raft 副本已追平日志。 -> - 在执行滚动重启或下线节点前，必须通过 PD 端点 `GET /v1/stores` 确认节点处于 `Up` 状态，并通过 `GET /v1/partitions` 确认本节点所有 Raft 分区状态健康，切勿仅凭 `STARTED` 作为滚动更新门禁。 +> **进程生命周期不等于存储或集群就绪**： +> `STARTED` 仅代表本地 JVM 与 gRPC 进程状态，**不代表节点可对外提供数据读写服务**。它无法证明节点已成功向 PD 注册、数据分片已恢复完成或 Raft 副本已追平日志。 +> - 在执行滚动重启或下线替换节点前，必须通过 PD 端点 `GET /v1/stores` 确认节点处于 `Up` 状态，并通过 `GET /v1/partitions` 确认本节点所有 Raft 分区状态健康，切勿仅凭 `STARTED` 作为滚动更新放行条件。 > - 1.8.0 之前的旧版本 Store 未提供此接口，调用将返回 HTTP 404；不能将 404 视为已启动或可替换状态。 主线发行目录的 Store 配置将 `management.endpoints.web.exposure.include` 设为 `"*"`，并启用 Prometheus；Actuator 端点没有 PD REST Basic 认证保护，请限制 Store REST 端口的网络可达范围。 diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md index 8ef3a0e4bf..d109c5e61e 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-hstore.md @@ -517,8 +517,10 @@ The Store node exposes these read-only endpoints on `server.port`: > [!WARNING] > **Process lifecycle does not equal cluster readiness**: -> `STARTED` reflects only local JVM and gRPC process readiness, **not storage or cluster data readiness**. It does not prove that the node has registered with PD, that shards have completed restoration, or that Raft replicas have caught up. -> - Before continuing a rolling update or replacing nodes, always check PD via `GET /v1/stores` to confirm the store status is `Up`, and inspect `GET /v1/partitions` to ensure all Raft groups are healthy. Never rely solely on `STARTED` as a rolling update gate. +> `STARTED` reflects only local JVM and gRPC process state, **not storage or cluster data readiness**. It does not prove that the node has registered with PD, +> that data shards have completed recovery, or that Raft replicas have caught up. +> - Before continuing a rolling update or replacing nodes, always check PD via `GET /v1/stores` to confirm the store status is `Up`, and inspect +> `GET /v1/partitions` to ensure all Raft groups are healthy. Never rely solely on `STARTED` as a rolling update gate. > - Versions prior to 1.8.0 do not support this endpoint and return HTTP 404; a 404 must not be treated as `STARTED`. Master Store configuration exposes all Actuator endpoints with `management.endpoints.web.exposure.include: "*"` and enables Prometheus. These endpoints lack PD REST Basic protection; restrict Store REST network access.