diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 22a3e98ae..dbba3cad8 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -577,6 +577,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode > 合法的图模式包括：NONE，RESTORING，MERGING，LOADING +存在活跃的 loading owner 时，此枚举 PUT 会拒绝所有模式修改，包括 `"LOADING"`。请先停止导入 worker，再释放其 owner。 + ##### Response Status ```javascript @@ -655,6 +657,55 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode } ``` +#### 6.3.5 LOADING owner 管理 {#loading-ownership} + +自 HugeGraph 1.8.0 起提供 owner 协议 1 接口；Loader 需使用配套的 1.8.0 及以上版本客户端。 +旧版本发行包不包含该协议；仅支持 `LOADING` 枚举不能说明支持这些接口。 +启用鉴权时，两个接口沿用模式设置接口的权限要求，即图空间管理权限（`space`）或该图所有者权限，并校验 STATUS 写权限。 +Server 将句柄绑定到实际鉴权用户；token 本身不赋予权限。申请、释放和重试必须保持相同身份。 + +```text +GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners +``` + +`200` 能力响应包含图实例 UUID 和当前非负 epoch： + +```json +{ + "protocol": 1, + "instance": "", + "epoch": 0 +} +``` + +每轮导入生成一个新的小写连字符 UUID（lowercase hyphenated UUID）作为 `token`，保留返回的 `instance` 和 `epoch`，通过以下请求申请，并设置 `Content-Type: application/json`： + +```text +PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners +``` + +```json +{ + "action": "acquire", + "instance": "", + "epoch": 0, + "token": "" +} +``` + +只有响应中包含 `state: "active"` 时才表示申请成功；此时返回 `200` 并回显 `protocol`、`instance`、`epoch`、`token` 以及 `mode: "LOADING"`。 +若返回 `200` 但 `state: "released"`，说明该句柄已失效或已被提前取消，此时并未获得 owner 保护，必须重新通过 GET 获取新的 `instance` 和 `epoch` 并生成全新 token 重新申请。 +释放时将 `action` 设置为 `release`，句柄保持不变；响应中包含 `state: "released"` 和当前实际模式。未申请前直接调用释放会被记录，并导致后续使用该句柄的申请直接返回 `released`。 +重试保留同一句柄；Server 校验其鉴权身份、instance 和 epoch。已释放句柄不能再次申请。 + +首个 owner 要求 `NONE`；其他 owner 共享由 owner 管理的 `LOADING`，最后一个释放后恢复 `NONE`。 +手动设置的 `LOADING`、`RESTORING` 和 `MERGING` 不会被接管；owner 活跃时，旧枚举 PUT 会拒绝模式修改。 + +该协议保护同一 Server 上实际运行的图实例中的普通导入，句柄绑定到实际鉴权身份、instance 和 epoch。 +它不提供跨 Server 协调、数据写入隔离或自动过期。请使用固定的 Server 直连地址，在导入停止后释放。 +升级后的 Loader 仅在 owner 探测返回接口路由不受支持的 `404` 时回退到旧行为；其他错误仍失败。 +图数据源和恢复导入保留原有枚举模式行为，参见 [Loader 兼容与恢复说明](/cn/docs/quickstart/toolchain/hugegraph-loader/#loading-ownership)。 + ### 6.4 Snapshot #### 6.4.1 创建快照 diff --git a/content/cn/docs/quickstart/toolchain/hugegraph-loader.md b/content/cn/docs/quickstart/toolchain/hugegraph-loader.md index 8cdcd4eab..814f8db3d 100644 --- a/content/cn/docs/quickstart/toolchain/hugegraph-loader.md +++ b/content/cn/docs/quickstart/toolchain/hugegraph-loader.md @@ -28,6 +28,9 @@ HugeGraph-Loader 是 HugeGraph 的数据导入组件，能够将多种数据源 > > **测试指南**：如需在本地运行 Loader 测试，请参考 [工具链本地测试指南](/cn/docs/guides/toolchain-local-test) +> **并发导入保护方案**：自 1.8.0 起，普通导入支持在同一 Server 实例上获取 owner 保护。 +> 旧版 Server 保持下文说明的原有导入行为。 + ### 2 获取 HugeGraph-Loader 可以通过以下三种方式获取 HugeGraph-Loader： @@ -982,6 +985,27 @@ bin/hugegraph-loader.sh \ 本例用独立的 `docs_smoke_person` 标签和 `docs_*` 属性，避免与预置的 `person` 样例数据冲突。成功时统计中应显示顶点写入成功数为 `2`、边写入成功数为 `0`。也可以在 Hubble 的 Gremlin 工作台查询 `g.V().hasLabel('docs_smoke_person').values('docs_name')`，结果应包含 `docs-smoke-alice` 和 `docs-smoke-bob`。 +#### 3.4.6 并发导入与 LOADING owner {#loading-ownership} + +自 1.8.0 版本起，Loader 支持并发导入模式所有权保护协议。 + +升级后的 Loader 在普通导入时探测 `/mode/owners`；仅接口路由不受支持的 `404` 会回退到原来的枚举 `LOADING`/`NONE` 流程。 +这会保留 Server 1.7 等旧 Server 的行为，但不提供不同 Loader 进程之间的保护。 +权限、网络、无效响应和申请 owner 的错误不会触发回退。图数据源和恢复导入保留原有 `RESTORING` 流程， +不探测 owner 能力，也不新增自动恢复 `NONE` 的行为。 + +支持该协议的 Server 上，每轮普通导入保留一个 `instance`/`epoch`/`token` 句柄。首个 owner 从 `NONE` 启用 `LOADING`， +其他 Loader 进程可加入该状态。一个导入结束时，其他 owner 仍活跃则保持 `LOADING`；最后一个 owner 释放后恢复 `NONE`。 +手动设置的 `LOADING`、`RESTORING` 和 `MERGING` 不会被接管；Schema 修改和 `--clear-all-data` 仍须单独协调。 + +申请和释放应使用同一个 Server 直连地址与鉴权身份。owner 属于该 Server 上实际运行的图实例， +不提供跨 Server 协调或普通数据写入隔离。导入停止后释放其原句柄；嵌入式调用方需要调用 `HugeGraphLoader.shutdown()` 关闭 Loader。 + +释放失败时，错误信息会打印对应句柄（格式为 `instance/epoch/token`，如 `Failed to release LOADING owner //`）。 +停止导入后，可通过相同鉴权身份调用 [RESTful API 释放接口](/cn/docs/clients/restful-api/graphs/#loading-ownership) 手动释放；shutdown 不保证自动重试。 +owner 不会自动过期。句柄丢失或 `kill -9` 后，先停止所有导入及其在途写入，再重新打开图或重启 Server。 +恢复不会撤销已有写入或 Schema/数据清理。Hubble 任务清理在后续版本中独立维护。 + ### 4 完整示例 下面给出的是 hugegraph-loader 包中 example 目录下的例子。([GitHub 地址](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader/assembly/static/example/file)) diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 235ff454c..d494b4bb3 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -576,6 +576,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode > Allowed graph mode values are: NONE, RESTORING, MERGING, LOADING +While loading owners are active, this enum PUT rejects all mode changes, including `"LOADING"`. Release the owners after their import workers stop. + ##### Response Status ```javascript @@ -660,6 +662,60 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode } ``` +#### 6.3.5 LOADING ownership {#loading-ownership} + +Starting with HugeGraph 1.8.0, the Server provides the protocol 1 endpoints for LOADING ownership; +Loader integration requires a matching 1.8.0 or newer client. +Released packages and earlier 1.8 builds lack this protocol. Support for the `LOADING` enum alone does not imply support for it. +With authentication enabled, both endpoints use the mode setter's permissions: graph-space management (`space`) or graph ownership, with STATUS write +authorization. Server binds the handle to the authenticated principal; a token grants no permission. Keep the same identity for acquire, release and retries. + +```text +GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners +``` + +The `200` capability response contains the graph-instance UUID and current nonnegative epoch: + +```json +{ + "protocol": 1, + "instance": "", + "epoch": 0 +} +``` + +Generate a new lowercase hyphenated UUID `token` for each import, retain the returned `instance` and `epoch`, +and acquire with `Content-Type: application/json`: + +```text +PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode/owners +``` + +```json +{ + "action": "acquire", + "instance": "", + "epoch": 0, + "token": "" +} +``` + +An acquire succeeded only when the response returns `200` with `state: "active"`, echoing `protocol`, `instance`, `epoch`, `token`, and `mode: "LOADING"`. +A `200` response with `state: "released"` means the handle is finished or was preemptively released; it does not grant ownership. In that case, start again +with a fresh GET for `instance` and `epoch` and generate a new token. +Release with `action: "release"` and the same handle; its response has `state: "released"` and the effective graph mode. Calling release before acquire is +recorded and causes a subsequent acquire with that handle to return `released`. +Keep one handle for retries; Server checks its principal, instance and epoch. A released handle cannot acquire again. + +The first owner requires `NONE`. Other owners share owner-managed `LOADING`; the last release restores `NONE`. +Manually set `LOADING`, `RESTORING` and `MERGING` are not adopted. While owners are active, the legacy enum PUT rejects mode changes. + +This protects ordinary imports on one live Server graph instance, with the handle bound to its authenticated principal, instance and epoch. +It provides no cross-Server coordination, data-write isolation or automatic expiry. Use a fixed direct Server endpoint and release after the import stops. +The upgraded Loader falls back to old behavior only for an unsupported-route `404` from its ownership probe; other errors remain failures. +Graph-source and restore imports retain their original enum-mode behavior. See +[Loader compatibility and recovery](/docs/quickstart/toolchain/hugegraph-loader/#loading-ownership). + ### 6.4 Snapshot #### 6.4.1 Create a snapshot diff --git a/content/en/docs/quickstart/toolchain/hugegraph-loader.md b/content/en/docs/quickstart/toolchain/hugegraph-loader.md index fa94864b7..3b74508ae 100644 --- a/content/en/docs/quickstart/toolchain/hugegraph-loader.md +++ b/content/en/docs/quickstart/toolchain/hugegraph-loader.md @@ -27,6 +27,9 @@ It will be explained in detail below. > Note: HugeGraph-Loader requires HugeGraph Server service, please refer to [HugeGraph-Server Quick Start](/docs/quickstart/hugegraph/hugegraph-server) to download and start Server +> **Concurrency protection:** starting with HugeGraph 1.8.0, ordinary imports acquire same-Server ownership protection. +> Older Servers retain the legacy import behavior described below. + > **Testing Guide**: For running HugeGraph-Loader tests locally, please refer to [HugeGraph Toolchain Local Testing Guide](/docs/guides/toolchain-local-test) ### 2 Get HugeGraph-Loader @@ -986,6 +989,29 @@ bin/hugegraph-loader.sh \ Expected result: two vertices and zero edges imported. This example uses dedicated schema names to avoid conflicts with a preloaded `person` label. In Hubble, run `g.V().hasLabel('docs_smoke_person').values('docs_name')` to confirm `docs-smoke-alice` and `docs-smoke-bob`. +#### 3.4.6 Concurrent imports and LOADING ownership {#loading-ownership} + +Starting with HugeGraph 1.8.0, Loader supports the concurrent import LOADING ownership protocol. + +For ordinary imports, the upgraded Loader probes `/mode/owners`. Only a route-level unsupported `404` selects the original enum `LOADING`/`NONE` flow. +That fallback preserves old-Server behavior, including Server 1.7, but provides no protection between separate Loader processes. +Permission, network, invalid-response and acquisition errors do not trigger fallback. Graph-source and restore imports keep their existing `RESTORING` +flow, without the ownership probe or a new automatic reset to `NONE`. + +On a supporting Server, each ordinary import retains one `instance`/`epoch`/`token` handle. The first owner requires `NONE` and enables `LOADING`; +other Loader processes can join that owned state. One import finishing leaves `LOADING` while another owner remains; the last release restores `NONE`. +Manual `LOADING`, `RESTORING` and `MERGING` are not adopted. Schema changes and `--clear-all-data` still need separate coordination. + +Use the same direct Server endpoint and authenticated identity for acquisition and release. Ownership belongs to that live graph instance; +it does not coordinate across Servers or isolate ordinary data writes. Release the retained handle after its import has stopped. +Embedded callers must close their Loader with `HugeGraphLoader.shutdown()`. + +If release fails, the failure message outputs the handle (`instance/epoch/token`, e.g., `Failed to release LOADING owner //`). +Stop the importer and retry the release manually via the [RESTful API release endpoint](/docs/clients/restful-api/graphs/#loading-ownership) with the +same handle and authenticated identity; shutdown does not promise automatic retry. +Owners have no automatic expiry. If the handle is lost or after `kill -9`, stop all imports and their in-flight writes before reopening the graph or +restarting Server. Recovery does not undo writes or Schema/data cleanup. Hubble task cleanup is maintained independently in subsequent releases. + ### 4 Complete example Given below is an example in the example directory of the hugegraph-loader package. ([GitHub address](https://github.com/apache/hugegraph-toolchain/tree/master/hugegraph-loader/assembly/static/example/file))