From 47ac77db17b717ad6ec1597a9ed0737eeed553fd Mon Sep 17 00:00:00 2001 From: imbajin Date: Mon, 12 Oct 2026 15:28:56 +0800 Subject: [PATCH 01/11] docs: explain graph reload recovery - describe startup source recovery and failure retries - document local deletion protection across graph spaces - explain authentication and cache RPC reload limits --- content/cn/docs/clients/restful-api/graphs.md | 31 ++++++++++++- content/cn/docs/config/config-guide.md | 23 +++++++--- content/cn/docs/guides/faq.md | 11 ++++- .../quickstart/hugegraph/hugegraph-server.md | 11 ++++- content/en/docs/clients/restful-api/graphs.md | 45 ++++++++++++++++++- content/en/docs/config/config-guide.md | 28 +++++++++--- content/en/docs/guides/faq.md | 14 +++++- .../quickstart/hugegraph/hugegraph-server.md | 14 +++++- 8 files changed, 159 insertions(+), 18 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 22a3e98ae..37d907222 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -240,6 +240,10 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx 启用鉴权时需要图空间管理权限（`space`）。 +启用 PD 时，`DEFAULT` 中已成功加载的本地图会拒绝公开删除，不受 `graph.load_from_local_config` 影响；设为 `true` 时，还保护成功扫描到的全部配置名， +包括本地加载失败后由 PD 元数据恢复的同名图。先移除文件，再执行 reload，目录扫描成功即在分离图之前解除保护；后续阶段返回 HTTP 400 也不回滚该快照。 +也可重启 Server。其他图空间的同名图不受此本地文件保护。 + ##### Params **路径参数说明：** @@ -433,7 +437,30 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default #### 6.1.10 重新加载图空间中的图 -重新加载服务中的图，适用于图配置在服务外部被改动之后。 +在图配置变更后，重新加载此 Server 持有的所有图。Reload 保留后端数据和本地配置文件。 + +通过预检且未启用 PD 时，reload 会重扫启动图配置目录中的所有当前文件，即使 `graph.load_from_local_config=false`。 +启用 PD 且该选项为 `false` 时，只恢复之前成功加载且配置文件仍存在的本地图，不加载新增本地文件；设为 `true` 时还会发现新增本地文件。 +先加载本地配置，再从 PD 元数据加载尚未恢复的图。新加载的图在启用 RPC 时先等待就绪，再完成启动和任务调度初始化，然后恢复 Gremlin 图与遍历绑定。 + +目录扫描成功后，会在关闭图之前更新本地来源记录；启用 PD 时，也会更新本地图删除保护。扫描失败时会在关闭任何图之前返回 HTTP 400，保留现有图和保护状态。 +启用 PD 时，`DEFAULT` 中已成功加载的本地图在配置文件仍存在时会拒绝公开删除，不受 `graph.load_from_local_config` 影响，无论删除是否要求清空数据。 +其他图空间的同名图不受该本地文件保护。启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，即使本地加载失败后由 PD 元数据恢复同名图也受保护。 +启用 PD 且设为 `false` 时，从未加载的新增本地文件仍被忽略，也不会建立删除保护。移除配置文件后，reload 中的目录扫描成功即在分离图之前清除对应来源和保护。 +后续打开或启动失败、整个 reload 返回 HTTP 400，也不会回滚已成功扫描的快照。旧实例成功关闭并分离后，若 PD 元数据中仍有该图，则可恢复并公开删除； +否则移除其运行时注册，但保留后端数据。关闭失败则保留旧注册，供显式重试。本地启动来源已移除，下次重启不会再从已删除的文件加载该图。 +来源记录跟随实际注册的图实例；旧实例移除不会清除新的本地替代实例。公开删除 `DEFAULT` 中的图时，仅在删除完成后清除对应的来源记录。 +未启用 PD 时，公开删除图仍会清空数据并移除本地配置，上述 PD 删除保护不适用。 + +配置了 `auth.authenticator` 时，请求会在关闭任何图之前返回 HTTP 400，因为鉴权服务保留了图引用。此类部署需要重启 Server 应用图配置变化， +被拒绝的 reload 不会改动原有图、数据或配置。 + +关闭失败的图仍保留注册，供显式重试；重载启动失败后，清理时仍未关闭的对象也会保留。其他可恢复的图可能先完成重载，再汇报打开或启动失败。不完整的 reload 会返回 HTTP 400， +部分图恢复成功不能作为整个请求成功的依据。排除故障后重试。 + +受管理的图已注册图/Schema 缓存通知 RPC 服务时，reload 同样会在关闭任何图之前返回 HTTP 400。这些服务的安全重绑尚未实现，需要重启 Server +应用变化；该拒绝会保留原有图、数据和配置。此类热重载需要在 Linux 高性能机器的分布式部署中完成修复与验证后再使用。 +未触发上述预检限制时，PD/本地配置的来源选择规则仍然适用，但不代表完整的分布式热重载支持。 ##### Params @@ -465,6 +492,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/manage 200 ``` +HTTP 400 表示配置了鉴权器、图/Schema 缓存通知 RPC 服务已注册、目录扫描失败，或图重载未完整完成。HTTP 200 表示允许执行的图重载步骤未汇报失败。 + ##### Response Body ```javascript diff --git a/content/cn/docs/config/config-guide.md b/content/cn/docs/config/config-guide.md index 9fde1a618..85f0d2a06 100644 --- a/content/cn/docs/config/config-guide.md +++ b/content/cn/docs/config/config-guide.md @@ -25,13 +25,13 @@ HugeGraphServer 内部集成了 GremlinServer 和 RestServer，而 gremlin-serve > 本页的认证配置属于 HugeGraph Server。生产环境必须按 [Server 认证与授权配置](/cn/docs/config/config-authentication/)启用 Auth、配置 IP 白名单和最小权限，并保留、保护 Server `audit-*.log`。示例中注释掉的认证配置表示默认未启用。 发行包把默认配置放在安装目录的 `conf/` 下；这些文件来自 Server 仓库的静态发行素材，构建时随包复制。未在配置文件中出现的选项采用代码定义的默认值；配置文件显式写入的值会覆盖该默认值。 -本页的默认文件行为按固定 Server 主线 `2f827d6` 核对；实际使用的发布包应以其自身版本对应的配置文件和入口脚本为准。 +默认发行配置的文件布局和设置按固定 Server 主线 `2f827d6` 核对；实际使用的发布包应以其自身版本对应的配置文件和入口脚本为准。 | 文件 | 来源和用途 | 装载行为 | |------|------------|----------| | `conf/gremlin-server.yaml` | 随发行包提供；配置 Gremlin Server。 | `start-hugegraph.sh` 将它作为 Server 启动参数传入。 | | `conf/rest-server.properties` | 按固定 Server 主线构建时随发行包提供；配置 REST Server、PD、认证等。 | 启动脚本和 Server 进程读取；对应主线构建的容器入口脚本也会在启动前更新其中受支持的选项。 | -| `conf/graphs/hugegraph.properties` | 随发行包提供的默认图配置，使用 RocksDB。 | `init-store.sh` 和 Server 应用初始化都会扫描该目录；初始化阶段会尝试加载其中的图配置。`graph.load_from_local_config` 默认 `false`，只控制管理器构造阶段预加载及 `reload()` 重扫。 | +| `conf/graphs/hugegraph.properties` | 随发行包提供的默认图配置，使用 RocksDB。 | `init-store.sh` 和 Server 应用初始化都会扫描该目录；初始化阶段会尝试加载其中的图配置。`graph.load_from_local_config` 默认 `false`，控制管理器构造阶段预加载；通过预检且未启用 PD 时 reload 会本地重扫；启用 PD 时恢复已成功加载且文件仍存在的本地图，`true` 还会发现新增本地文件。 | | `conf/graphs/hstore.properties.template` | 随发行包提供的 HStore 模板；其他图配置由用户按需创建。 | HStore 镜像在构建时把模板改名为 `hugegraph.properties`；裸发行包用户可复制模板并修改。 | 完整的默认文件见Server 主线源码：[gremlin-server.yaml](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/gremlin-server.yaml)、[rest-server.properties](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/rest-server.properties)、[hugegraph.properties](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/graphs/hugegraph.properties) 和 [hstore.properties.template](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/graphs/hstore.properties.template)。 @@ -53,7 +53,7 @@ graphs: {} ssl: { enabled: false } ``` -通常只需关注 `channelizer`、`host` 和 `port`。图不在 Gremlin Server 的 `graphs` 段加载；REST 侧管理器会在 Server 应用初始化时扫描 `graphs` 目录并尝试载入本地图配置。`graph.load_from_local_config` 只控制管理器构造阶段的预加载与 `reload()` 重扫；默认 `false` 不会关闭应用初始化阶段的本地加载。 +通常只需关注 `channelizer`、`host` 和 `port`。图不在 Gremlin Server 的 `graphs` 段加载；REST 侧管理器会在 Server 应用初始化时扫描 `graphs` 目录并尝试载入本地图配置。`graph.load_from_local_config` 控制管理器构造阶段的预加载；默认 `false` 不会关闭应用初始化阶段的本地加载。通过预检且未启用 PD 时，reload 会重扫该目录。启用 PD 时，会恢复已成功加载且文件仍存在的本地图；`true` 还会发现新增本地文件。本地配置先于 PD 元数据加载。 - channelizer：默认的 `WsAndHttpChannelizer` 同时支持 WebSocket 和 HTTP。Gremlin-Console 使用 WebSocket，HugeGraph-Client、Loader 和 Hubble 使用 HTTP； @@ -66,7 +66,7 @@ ssl: { enabled: false } ### 3 rest-server.properties -下面是可用的 `rest-server.properties` 示例。主线模板未写出 `graph.load_from_local_config`，源码默认值为 `false`。示例中设为 `true` 是可选的：它开启管理器构造阶段预加载和 `reload()` 重扫；Server 应用初始化阶段仍会扫描并尝试加载本地图配置。 +下面是可用的 `rest-server.properties` 示例。主线模板未写出 `graph.load_from_local_config`，源码默认值为 `false`。示例中设为 `true` 是可选的：它开启管理器构造阶段预加载，以及启用 PD 时 reload 对新增本地文件的发现；设为 `false` 时仍会恢复已成功加载且文件仍存在的本地图；通过预检且未启用 PD 时 reload 总会本地重扫，不受该选项限制。Server 应用初始化阶段仍会扫描并尝试加载本地图配置。 ```properties # bind url @@ -110,7 +110,18 @@ memory_monitor.period=2000 - restserver.url：RestServer 提供服务的 url，根据实际环境修改。如果其他 IP 地址无法访问，可以尝试修改为特定的地址；或修改为 `http://0.0.0.0` 来监听来自任何 IP 地址的请求，这种方案较为便捷，但需要留意服务可被访问的网络范围； - graphs：图配置文件所在目录，默认值是 `./conf/graphs`。`init-store.sh` 会扫描该目录；Server 应用初始化也会扫描并尝试加载其中的 properties 文件； -- graph.load_from_local_config：是否在管理器构造阶段预加载本地图配置，以及在 `reload()` 时重新扫描；源码默认值为 `false`。它不会禁止 Server 应用初始化阶段的本地加载，也不是安全隔离开关； +- graph.load_from_local_config：是否在管理器构造阶段预加载本地图配置，源码默认值为 `false`。通过预检且未启用 PD 时，reload 会重扫启动图配置目录。启用 PD 时，会恢复已成功加载且文件仍存在的本地图；`true` 还会发现新增本地文件。本地配置先于 PD 元数据加载。它不会禁止 Server 应用初始化阶段的本地加载，也不是安全隔离开关； + +目录扫描成功后，reload 会更新本地来源记录；启用 PD 时，也会更新本地图删除保护。 +启用 PD 时，`DEFAULT` 中已成功加载的本地图在配置文件仍存在时会拒绝公开删除，不受该选项影响，无论是否清空数据。 +启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，包括本地加载失败后由 PD 元数据恢复的同名图。 +其他图空间的同名图不受此本地文件保护；启用 PD 且设为 `false` 时，从未加载的新增本地文件仍被忽略，不会建立删除保护。 +移除本地文件后，reload 中的目录扫描成功即在分离图之前清除对应来源和保护；后续阶段失败、整个请求返回 HTTP 400，也不会回滚该扫描快照。 +旧实例成功关闭并分离后，图可改由 PD 元数据恢复；否则移除运行时注册，但保留后端数据。关闭失败则保留旧注册，供显式重试。 +扫描失败会保留现有图和保护状态。未启用 PD 时，公开删除图仍会清空数据并移除本地配置。详细行为见下方图管理 API。 + +配置了 `auth.authenticator` 时，reload 会在关闭任何图之前以 HTTP 400 拒绝请求，需要重启 Server 应用图配置变化。失败与恢复行为详见[图管理 API](/cn/docs/clients/restful-api/graphs/)。 +图/Schema 缓存通知 RPC 服务已注册时，reload 同样会在关闭任何图之前返回 HTTP 400，应改用重启 Server。服务的安全重绑尚未实现，需要在 Linux 高性能机器的分布式部署中修复并验证。 > 当前上游模板中的 Arthas 键仍写作 `arthas.telnet_port`、`arthas.http_port` 和 `arthas.disabled_commands`，但 `ServerOptions` 读取的是下方示例中的 camelCase 名称。自定义配置应使用 `arthas.telnetPort`、`arthas.httpPort` 和 `arthas.disabledCommands`。 @@ -145,7 +156,7 @@ store=hugegraph **[可选]：修改 rest-server.properties** -通过修改 `rest-server.properties` 中的 `graphs` 配置项来设置图的配置文件目录。默认配置为 `graphs=./conf/graphs`；需要其他目录时调整 `graphs`。下面将 `graph.load_from_local_config` 设为 `true`，作为管理器构造阶段预加载和 `reload()` 重扫的可选设置；应用初始化仍会读取该目录中的本地图配置： +通过修改 `rest-server.properties` 中的 `graphs` 配置项来设置图的配置文件目录。默认配置为 `graphs=./conf/graphs`；需要其他目录时调整 `graphs`。下面将 `graph.load_from_local_config` 设为 `true`，作为管理器构造阶段预加载的可选设置。启用 PD 时，它也会让 reload 发现新增本地文件；`false` 仍会恢复已成功加载且文件仍存在的本地图。通过预检且未启用 PD 时，reload 会重扫该目录。应用初始化仍会读取该目录中的本地图配置： ```properties graphs=./conf/graphs diff --git a/content/cn/docs/guides/faq.md b/content/cn/docs/guides/faq.md index eb43ed8c4..3d687c6a7 100644 --- a/content/cn/docs/guides/faq.md +++ b/content/cn/docs/guides/faq.md @@ -34,7 +34,16 @@ weight: 6 - 配置了两个图，名字是`hugegraph`和`hugegraph1`，而启动服务的命令是`start-hugegraph.sh`，是只打开了`hugegraph`这个图吗 - 脚本名称与图名无关。Server 默认从 `conf/graphs` 扫描并加载本地图配置，目录可在 `conf/rest-server.properties` 的 `graphs` 配置项中修改。`graph.load_from_local_config` 的默认值是 `false`，只控制图管理器构造阶段的预加载及 `reload()` 重扫，不能用于禁止启动时加载；需要加载多个本地图时，为每个图准备独立配置文件。详见[服务端配置说明](/cn/docs/config/config-guide/)。 + 脚本名称与图名无关。Server 默认从 `conf/graphs` 扫描并加载本地图配置，目录可在 `conf/rest-server.properties` 的 `graphs` 配置项中修改。`graph.load_from_local_config` 的默认值是 `false`，控制图管理器构造阶段的预加载，不能用于禁止启动时加载。通过预检且未启用 PD 时，reload 会重扫启动配置目录。启用 PD 时，会恢复已成功加载且配置文件仍存在的本地图；设为 `true` 时还会发现新增本地文件。本地配置优先于 PD 元数据。配置了 `auth.authenticator` 的部署会在关闭任何图之前以 HTTP 400 拒绝 reload，需要重启 Server 应用配置变化；需要加载多个本地图时，为每个图准备独立配置文件。详见[服务端配置说明](/cn/docs/config/config-guide/)。 + + 启用 PD 时，`DEFAULT` 中已成功加载的本地图在配置文件仍存在时会拒绝公开删除，不受该选项影响；其他图空间的同名图不受此保护。 + 启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，即使本地加载失败后由 PD 元数据恢复同名图也受保护。 + 启用 PD 且设为 `false` 时，从未加载的新增本地文件仍被忽略，也不会建立删除保护。 + 移除本地文件后，reload 中的目录扫描成功即在分离图之前解除保护；后续阶段失败、整个请求返回 HTTP 400，也不会回滚该扫描快照。 + 旧实例成功关闭并分离后，图可改由 PD 元数据恢复；否则移除运行时注册，保留后端数据。关闭失败则保留旧注册，供显式重试。 + 扫描失败会保留现有图和保护状态。未启用 PD 时，公开删除图仍会清空数据并移除本地配置。 + + 图/Schema 缓存通知 RPC 服务已注册时，reload 也会在关闭任何图之前返回 HTTP 400，应改用重启 Server。服务的安全重绑尚未实现，Linux 高性能机器上的修复与验证要求见[图管理 API](/cn/docs/clients/restful-api/graphs/)。 - 服务启动成功后，使用`curl`查询所有顶点时返回乱码 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 19ea7f312..ca8184ef5 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -221,7 +221,16 @@ mvn package -DskipTests -ntp -Drocksdb-only Server 的 tar 包随包提供 `conf/rest-server.properties`、`conf/gremlin-server.yaml` 和 `conf/graphs/hugegraph.properties`；源码构建包从 `hugegraph-server/hugegraph-dist/src/assembly/static/conf/` 装配这些文件。解压后在 Server 安装目录内编辑配置，无需另行生成。发行包版本之间可能有默认值差异，下面涉及的默认值和启动行为按 `master` 主线说明。 -单机 RocksDB 快速上手只需确认 `conf/graphs/hugegraph.properties` 使用 `backend=rocksdb`、`serializer=binary`。正常 Server 初始化会扫描 `conf/graphs/` 并加载本地图配置，无需额外设置 `graph.load_from_local_config=true`。该选项默认值为 `false`，控制构造阶段的提前加载和 `reload()` 时是否重新扫描本地配置。 +单机 RocksDB 快速上手只需确认 `conf/graphs/hugegraph.properties` 使用 `backend=rocksdb`、`serializer=binary`。正常 Server 初始化会扫描 `conf/graphs/` 并加载本地图配置，无需额外设置 `graph.load_from_local_config=true`。该选项默认值为 `false`，控制构造阶段的提前加载。通过预检且未启用 PD 时，reload 会重扫启动图配置目录。启用 PD 时，会恢复已成功加载且文件仍存在的本地图；`true` 还会发现新增本地文件。本地配置优先于 PD 元数据。配置了 `auth.authenticator` 时，reload 会在关闭图之前返回 HTTP 400，需要重启 Server 应用配置变化。重载行为详见[图管理 API](/cn/docs/clients/restful-api/graphs/)。 + +启用 PD 时，`DEFAULT` 中已成功加载的本地图在配置文件仍存在时会拒绝公开删除，不受该选项影响；其他图空间的同名图不受此保护。 +启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，即使本地加载失败后由 PD 元数据恢复同名图也受保护。 +启用 PD 且设为 `false` 时，从未加载的新增本地文件仍被忽略，也不会建立删除保护。 +移除本地文件后，reload 中的目录扫描成功即在分离图之前解除保护；后续阶段失败、整个请求返回 HTTP 400，也不会回滚该扫描快照。 +旧实例成功关闭并分离后，图可改由 PD 元数据恢复；否则移除运行时注册，保留后端数据。关闭失败则保留旧注册，供显式重试。 +扫描失败会保留现有图和保护状态。未启用 PD 时，公开删除图仍会清空数据并移除本地配置。 + +图/Schema 缓存通知 RPC 服务已注册时，reload 也会在关闭任何图之前返回 HTTP 400，应改用重启 Server。服务的安全重绑尚未实现，Linux 高性能机器上的修复与验证要求见图管理 API。 详细的配置介绍请参考[配置文档](/docs/config/config-guide)及[配置项介绍](/docs/config/config-option)。 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 235ff454c..78d34bb59 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -215,6 +215,11 @@ Create a graph (set `Content-Type: application/json`) Graph-space management permission (`space`) is required when authentication is enabled. +With PD, public deletion in `DEFAULT` returns HTTP 400 for successfully loaded local graphs regardless of `graph.load_from_local_config`, +and, with `true`, for every configuration name from a successful directory scan, including metadata fallback after local loading fails. +Remove the file and run reload: a successful directory scan releases the protection before detachment, even if later reload phases return HTTP 400. +Restarting Server is another option. This protection does not apply to a graph with the same name in another graph space. + ##### Params **Path parameters** @@ -409,7 +414,41 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default #### 6.1.10 Reload the graphs of the graphspace -Reloads the graphs the server holds, which is useful after the graph configuration has changed outside the server. +Reloads all graphs held by this Server after graph configuration changes. Reload preserves backend data and local configuration files. + +Without PD, a reload that passes preflight rescans all current files in the startup graph configuration directory, +even when `graph.load_from_local_config=false`. With PD and `false`, reload restores only local graphs previously loaded successfully +whose configuration files still exist; it ignores new local files. Setting the flag to `true` also discovers new local files. +Local configurations are loaded first, then PD metadata is used for graphs not already restored locally. +Newly loaded graphs wait for readiness when RPC is enabled, complete startup and task scheduling initialization, +then restore their Gremlin graph/traversal bindings. + +A successful directory scan updates local-source tracking before graphs are closed; with PD, it also updates local graph deletion protection. +A scan failure returns HTTP 400 before closing any graph and preserves existing graphs and protection. +With PD, local graphs successfully loaded in `DEFAULT` reject public deletion while their configuration files remain, +regardless of `graph.load_from_local_config` and whether deletion requests data clearing. A graph with the same name in another graph space +is not protected by that local file. With PD and `true`, protection also covers all configuration names from a successful scan, even if local loading fails +and PD metadata restores a graph with that name. With PD and `false`, a new local file that has never been loaded remains ignored and unprotected. +Remove the configuration file: a successful directory scan during reload clears its local-source tracking and deletion protection before detachment. +Later opening or startup failures do not roll back that scan snapshot, even when the whole reload returns HTTP 400. +After the old instance closes and detaches, PD metadata may restore the graph for public deletion; otherwise its runtime registration is removed +while backend data remains. If closing fails, the old registration is retained for an explicit retry. This removes the local startup source, so a subsequent restart will not reload it from that deleted file. +Source tracking follows the registered graph instance: removal of an old instance does not discard a newer local replacement. +For public deletion in `DEFAULT`, the corresponding local-source tracking is cleared only after deletion completes. +Without PD, public graph deletion still clears data and removes its local configuration; the PD protection rule does not apply. + +A configured `auth.authenticator` causes HTTP 400 before any graph is closed, because authentication services retain graph references. +Restart Server to apply graph configuration changes in that deployment; the rejected reload leaves the original graphs, data and configuration intact. + +Graphs that fail to close remain registered for an explicit retry, including objects whose cleanup fails after a reload startup failure. +Other recoverable graphs may reload before an opening or startup failure is reported. +An incomplete reload returns HTTP 400; successful recovery of some graphs does not make the whole reload successful. +Correct the failure and retry. + +Reload also returns HTTP 400 before closing any graph when graph/schema cache-notification RPC services are registered for a managed graph. +Safe rebinding of those services remains unimplemented, so restart Server to apply changes; this rejection preserves the original graphs, data and +configuration. Repair and validate that hot-reload lifecycle on a high-performance Linux distributed deployment before relying on it. +The PD/local-config rules above apply when these preflight restrictions are absent; they do not establish full distributed reload support. ##### Params @@ -441,6 +480,10 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/manage 200 ``` +HTTP 400 indicates a configured authenticator, registered graph/schema cache-notification RPC services, a directory scan failure, +or an incomplete graph reload. +HTTP 200 means the permitted graph reload phases reported no failure. + ##### Response Body ```javascript diff --git a/content/en/docs/config/config-guide.md b/content/en/docs/config/config-guide.md index bc500dae1..630c94a7c 100644 --- a/content/en/docs/config/config-guide.md +++ b/content/en/docs/config/config-guide.md @@ -25,13 +25,13 @@ The following sections describe these files. > The authentication settings on this page apply to HugeGraph Server. In production, enable [authentication and authorization](/docs/config/config-authentication/), maintain an IP allowlist, grant minimum permissions, and retain and protect Server `audit-*.log` files. Commented authentication settings in the examples indicate that authentication is disabled by default. The distribution copies default files from the Server repository into the installation directory's `conf/` folder. Options absent from these files use source-code defaults; explicit file settings override those defaults. -The file-loading behavior on this page was checked against Server master commit `2f827d6`. Use the configuration files and entry scripts that correspond to your installed release. +The default distribution file layout and settings were checked against Server master commit `2f827d6`. Use the configuration files and entry scripts that correspond to your installed release. | File | Source and purpose | Loading behavior | |------|------------|----------| | `conf/gremlin-server.yaml` | Shipped with the distribution; configures Gremlin Server. | Passed to Server by `start-hugegraph.sh`. | | `conf/rest-server.properties` | Shipped when building the checked Server master; configures REST Server, PD, authentication, and related settings. | Read by startup scripts and Server; the corresponding container entrypoint also updates supported settings before startup. | -| `conf/graphs/hugegraph.properties` | Shipped default graph configuration, using RocksDB. | Scanned by both `init-store.sh` and application initialization, which attempts to load local graphs. `graph.load_from_local_config` defaults to `false` and controls only constructor preloading and rescanning on `reload()`. | +| `conf/graphs/hugegraph.properties` | Shipped default graph configuration, using RocksDB. | Scanned by both `init-store.sh` and application initialization, which attempts to load local graphs. `graph.load_from_local_config` defaults to `false` and controls constructor preloading. After preflight, reload rescans locally without PD. With PD, it restores local graphs previously loaded successfully whose files still exist; `true` also discovers new local files. | | `conf/graphs/hstore.properties.template` | Shipped HStore template; users create other graph configurations as needed. | The HStore image renames it to `hugegraph.properties` during its build; distribution users can copy and customize it. | Complete defaults are in Server master: [gremlin-server.yaml](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/gremlin-server.yaml), [rest-server.properties](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/rest-server.properties), [hugegraph.properties](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/graphs/hugegraph.properties), and [hstore.properties.template](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/graphs/hstore.properties.template). @@ -53,7 +53,7 @@ graphs: {} ssl: { enabled: false } ``` -Usually, focus on `channelizer`, `host`, and `port`. Graphs are not loaded from the Gremlin Server `graphs` section. During application initialization, the REST-side manager scans the `graphs` directory and attempts to load local graph configurations. `graph.load_from_local_config` controls only constructor preloading and rescanning on `reload()`; its default `false` does not disable local loading during application initialization. +Usually, focus on `channelizer`, `host`, and `port`. Graphs are not loaded from the Gremlin Server `graphs` section. During application initialization, the REST-side manager scans the `graphs` directory and attempts to load local graph configurations. `graph.load_from_local_config` controls constructor preloading; its default `false` does not disable local loading during application initialization. Without PD, a reload that passes preflight rescans this directory. With PD, it restores local graphs previously loaded successfully whose files still exist; `true` also discovers new local files. Local configurations are loaded before PD metadata. - `channelizer`: The default `WsAndHttpChannelizer` supports WebSocket and HTTP. Gremlin Console uses WebSocket; HugeGraph Client, Loader, and Hubble use HTTP. @@ -66,7 +66,7 @@ Set the matching `gremlinserver.url=http://host:port` in `rest-server.properties ### 3 rest-server.properties -The following example lists `rest-server.properties` options. The master template omits `graph.load_from_local_config`, whose source-code default is `false`. Setting it to `true` is optional: it enables constructor preloading and rescanning on `reload()`. Application initialization still scans and attempts to load local graph configurations. +The following example lists `rest-server.properties` options. The master template omits `graph.load_from_local_config`, whose source-code default is `false`. Setting it to `true` is optional: it enables constructor preloading and discovery of new local files on reload when PD is enabled. With PD and `false`, reload still restores local graphs previously loaded successfully whose files still exist. A reload that passes preflight without PD always rescans locally, regardless of this flag. Application initialization still scans and attempts to load local graph configurations. ```properties # bind url @@ -110,7 +110,23 @@ memory_monitor.period=2000 - `restserver.url`: The REST listener URL. Use a specific address for remote access, or `http://0.0.0.0` to listen on every interface while restricting the accessible network. - `graphs`: The graph configuration directory, defaulting to `./conf/graphs`. Both `init-store.sh` and application initialization scan it; initialization attempts to load its properties files. -- `graph.load_from_local_config`: Controls constructor preloading and rescanning on `reload()`, with source-code default `false`. It does not block local loading during application initialization and is not a security isolation switch. +- `graph.load_from_local_config`: Controls constructor preloading, with source-code default `false`. Without PD, a reload that passes preflight rescans the startup graph directory. With PD, it restores local graphs previously loaded successfully whose files still exist; `true` also discovers new local files. Local configurations are loaded before PD metadata. It does not block local loading during application initialization and is not a security isolation switch. + +A successful reload scan updates local-source tracking; with PD, it also updates local graph deletion protection. +With PD, local graphs successfully loaded in `DEFAULT` reject public deletion while their configuration files remain, regardless of the flag. +With PD and `true`, protection also covers all configuration names from a successful scan, including a graph restored from PD metadata after local loading fails. +This applies with or without data clearing; a graph with the same name in another graph space is not protected by the local file. +With PD and `false`, a new local file that has never been loaded remains ignored and does not create deletion protection. +After a local file is removed, a successful directory scan during reload clears that source and protection before detachment. +Later reload failures do not roll back this snapshot, even if the request returns HTTP 400. After the old instance closes and detaches, +PD metadata may restore it; otherwise its runtime registration is removed while backend data remains. A close failure retains the old registration +for an explicit retry. A scan failure preserves existing graphs and protection. +Without PD, public graph deletion still clears data and removes its local configuration. See the graph API below for details. + +Reload is rejected with HTTP 400 before any graph is closed when `auth.authenticator` is configured. Restart Server to apply graph configuration changes in that +deployment. See the [graph API](/docs/clients/restful-api/graphs/) for reload failure and recovery behavior. +Registered graph/schema cache-notification RPC services also make reload return HTTP 400 before closing any graph; use Server restart. +Their safe rebinding remains unimplemented and requires repair and validation on a high-performance Linux distributed deployment. > The upstream template still uses `arthas.telnet_port`, `arthas.http_port`, and `arthas.disabled_commands`, but `ServerOptions` reads the camelCase names in the example. Use `arthas.telnetPort`, `arthas.httpPort`, and `arthas.disabledCommands` in custom configurations. @@ -145,7 +161,7 @@ A Server can load multiple graphs, each with its own properties file. This examp **[Optional]: Modify rest-server.properties** -Set the graph configuration directory with `graphs` in `rest-server.properties`, defaulting to `graphs=./conf/graphs`. Adjust it for another directory. The example optionally enables constructor preloading and rescanning on `reload()` with `graph.load_from_local_config=true`; application initialization still reads local graph configurations from this directory: +Set the graph configuration directory with `graphs` in `rest-server.properties`, defaulting to `graphs=./conf/graphs`. Adjust it for another directory. The example optionally enables constructor preloading with `graph.load_from_local_config=true`. With PD, the flag also enables discovery of new local files on reload; `false` still restores local graphs previously loaded successfully whose files still exist. Without PD, a reload that passes preflight rescans this directory. Application initialization still reads local graph configurations from it: ```properties graphs=./conf/graphs diff --git a/content/en/docs/guides/faq.md b/content/en/docs/guides/faq.md index 8b68bd643..2cf51d106 100644 --- a/content/en/docs/guides/faq.md +++ b/content/en/docs/guides/faq.md @@ -34,7 +34,19 @@ weight: 6 - Two graphs are configured, the names are `hugegraph` and `hugegraph1`, and the command to start the service is `start-hugegraph.sh`. Is only the hugegraph graph opened? - The script name is unrelated to the graph name. Server scans and loads local graph configurations from `conf/graphs` by default; change the directory with `graphs` in `conf/rest-server.properties`. `graph.load_from_local_config` defaults to `false` and controls only constructor preloading and rescanning on `reload()`, not whether startup loads local graphs. Give each local graph its own configuration file. See the [Server configuration guide](/docs/config/config-guide/). + The script name is unrelated to the graph name. Server scans and loads local graph configurations from `conf/graphs` by default; change the directory with `graphs` in `conf/rest-server.properties`. `graph.load_from_local_config` defaults to `false` and controls constructor preloading, not whether startup loads local graphs. Without PD, a reload that passes preflight rescans the startup configuration directory. With PD, it restores local graphs previously loaded successfully whose configuration files still exist; setting the flag to `true` also discovers new local files. Local configurations take precedence over PD metadata. A configured `auth.authenticator` rejects reload with HTTP 400 before closing any graph; restart Server to apply configuration changes in that deployment. Give each local graph its own configuration file. See the [Server configuration guide](/docs/config/config-guide/). + + With PD, local graphs successfully loaded in `DEFAULT` reject public deletion while their configuration files remain, regardless of this flag. + With PD and `true`, protection also covers every name in a successful directory scan, even if local loading fails and PD metadata restores that graph. + With PD and `false`, never-loaded new files remain ignored and unprotected. + Other graph spaces are outside this protection. Remove the file; a successful directory scan during reload releases its protection before detachment. + Later reload failures do not roll back that scan snapshot, even when the request returns HTTP 400. + After the old instance closes and detaches, PD metadata may restore it; otherwise its runtime registration is removed while backend data remains. + If closing fails, the old registration is retained for an explicit retry. + A scan failure preserves existing graphs and protection. Without PD, public graph deletion still clears data and removes its local configuration. + + Registered graph/schema cache-notification RPC services also cause reload to return HTTP 400 before closing any graph. Restart Server instead; + safe service rebinding remains unimplemented. See the [graph API](/docs/clients/restful-api/graphs/) for the Linux repair and validation requirement. - After the service starts successfully, garbled characters are returned when using `curl` to query all vertices diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 8b7bb55d8..f05a0102e 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -226,7 +226,19 @@ mvn package -DskipTests -ntp -Drocksdb-only Server archives include `conf/rest-server.properties`, `conf/gremlin-server.yaml`, and `conf/graphs/hugegraph.properties`; source builds assemble them from `hugegraph-server/hugegraph-dist/src/assembly/static/conf/`. Edit them inside the extracted Server directory without a separate generation step. Defaults vary by release; the following defaults and startup behavior describe master. -For standalone RocksDB, confirm `backend=rocksdb` and `serializer=binary` in `conf/graphs/hugegraph.properties`. Normal Server initialization scans `conf/graphs/` and loads local graphs without requiring `graph.load_from_local_config=true`. This option defaults to `false` and controls constructor preloading and rescanning on `reload()`. +For standalone RocksDB, confirm `backend=rocksdb` and `serializer=binary` in `conf/graphs/hugegraph.properties`. Normal Server initialization scans `conf/graphs/` and loads local graphs without requiring `graph.load_from_local_config=true`. This option defaults to `false` and controls constructor preloading. Without PD, a reload that passes preflight rescans the startup graph directory. With PD, it restores local graphs previously loaded successfully whose files still exist; `true` also discovers new local files. Local configurations take precedence over PD metadata. If `auth.authenticator` is configured, reload returns HTTP 400 before closing graphs; restart Server to apply configuration changes. See the [graph API](/docs/clients/restful-api/graphs/) for reload behavior. + +With PD, local graphs successfully loaded in `DEFAULT` reject public deletion while their configuration files remain, regardless of this flag. +With PD and `true`, protection also covers every name in a successful directory scan, even if local loading fails and PD metadata restores that graph. +With PD and `false`, never-loaded new files remain ignored and unprotected. +Other graph spaces are outside this protection. Remove the file; a successful directory scan during reload releases its protection before detachment. +Later reload failures do not roll back that scan snapshot, even when the request returns HTTP 400. +After the old instance closes and detaches, PD metadata may restore it; otherwise its runtime registration is removed while backend data remains. +If closing fails, the old registration is retained for an explicit retry. +A scan failure preserves existing graphs and protection. Without PD, public graph deletion still clears data and removes its local configuration. + +Registered graph/schema cache-notification RPC services also make reload return HTTP 400 before closing any graph; use Server restart. +Their safe rebinding remains unimplemented; the graph API documents the required repair and validation on a high-performance Linux deployment. See the [configuration guide](/docs/config/config-guide/) and [option reference](/docs/config/config-option/) for details. From 534c4f7a12a0996701ba6d33a98233baf2504721 Mon Sep 17 00:00:00 2001 From: imbajin Date: Mon, 12 Oct 2026 17:17:18 +0800 Subject: [PATCH 02/11] docs: clarify graph reload sources - align configuration references with startup sources - preserve reload protection and recovery boundaries - wrap the added prose to the repository line limit --- .../cn/docs/config/config-backend-hstore.md | 2 +- content/cn/docs/config/config-guide.md | 12 ++++++--- content/cn/docs/config/config-option.md | 2 +- content/cn/docs/guides/faq.md | 4 ++- .../quickstart/hugegraph/hugegraph-server.md | 4 ++- content/en/docs/clients/restful-api/graphs.md | 3 ++- .../en/docs/config/config-backend-hstore.md | 2 +- content/en/docs/config/config-guide.md | 27 ++++++++++++++----- content/en/docs/config/config-option.md | 2 +- content/en/docs/guides/faq.md | 8 +++++- .../quickstart/hugegraph/hugegraph-server.md | 7 ++++- 11 files changed, 54 insertions(+), 19 deletions(-) diff --git a/content/cn/docs/config/config-backend-hstore.md b/content/cn/docs/config/config-backend-hstore.md index 59a0131b0..bb4574940 100644 --- a/content/cn/docs/config/config-backend-hstore.md +++ b/content/cn/docs/config/config-backend-hstore.md @@ -143,7 +143,7 @@ PD 对该值的处理方式： | usePD | rest-server.properties | false | Server 启动时是否从 PD 加载元数据 | `ServerOptions.java:401-407` | | cluster | rest-server.properties | hg-test | 集群名，作为所有 PD 元数据 key 的前缀 | `ServerOptions.java:187-193` | | init_store.enabled | rest-server.properties | true | PD/Store 部署下应设为 `false`，元数据已由存储侧负责 | `ServerOptions.java:382-390` | -| graph.load_from_local_config | rest-server.properties | false | 控制管理器构造阶段预加载及 `reload()` 重扫本地图配置；应用初始化仍扫描并尝试加载，因此 `false` 不是阻止本地配置加载的安全开关 | `ServerOptions.java:366-372` | +| graph.load_from_local_config | rest-server.properties | false | 控制构造阶段预加载。未启用 PD 时，通过预检的 reload 会重扫配置；启用 PD 时恢复文件仍存在的已成功加载本地图，`true` 还会发现新增配置。应用初始化仍扫描并尝试加载本地配置，`false` 不会阻止本地加载。 | `ServerOptions.java:366-372` | | auth.graph_store | rest-server.properties | hugegraph | 保存权限数据的图，关闭 init-store 时会校验它使用 `hstore` 后端 | `ServerOptions.java:602-609` | | graphspace | {graph}.properties | DEFAULT | PD 看到的图名的第一段 | `CoreOptions.java:679-685` | diff --git a/content/cn/docs/config/config-guide.md b/content/cn/docs/config/config-guide.md index 85f0d2a06..19596ae50 100644 --- a/content/cn/docs/config/config-guide.md +++ b/content/cn/docs/config/config-guide.md @@ -53,7 +53,8 @@ graphs: {} ssl: { enabled: false } ``` -通常只需关注 `channelizer`、`host` 和 `port`。图不在 Gremlin Server 的 `graphs` 段加载；REST 侧管理器会在 Server 应用初始化时扫描 `graphs` 目录并尝试载入本地图配置。`graph.load_from_local_config` 控制管理器构造阶段的预加载；默认 `false` 不会关闭应用初始化阶段的本地加载。通过预检且未启用 PD 时，reload 会重扫该目录。启用 PD 时，会恢复已成功加载且文件仍存在的本地图；`true` 还会发现新增本地文件。本地配置先于 PD 元数据加载。 +通常只需关注 `channelizer`、`host` 和 `port`。图不在 Gremlin Server 的 `graphs` 段加载；REST 侧管理器会在 Server 应用初始化时扫描 `graphs` 目录并尝试载入本地图配置。`graph.load_from_local_config` +控制管理器构造阶段的预加载；默认 `false` 不会关闭应用初始化阶段的本地加载。通过预检且未启用 PD 时，reload 会重扫该目录。启用 PD 时，会恢复已成功加载且文件仍存在的本地图；`true` 还会发现新增本地文件。本地配置先于 PD 元数据加载。 - channelizer：默认的 `WsAndHttpChannelizer` 同时支持 WebSocket 和 HTTP。Gremlin-Console 使用 WebSocket，HugeGraph-Client、Loader 和 Hubble 使用 HTTP； @@ -66,7 +67,8 @@ ssl: { enabled: false } ### 3 rest-server.properties -下面是可用的 `rest-server.properties` 示例。主线模板未写出 `graph.load_from_local_config`，源码默认值为 `false`。示例中设为 `true` 是可选的：它开启管理器构造阶段预加载，以及启用 PD 时 reload 对新增本地文件的发现；设为 `false` 时仍会恢复已成功加载且文件仍存在的本地图；通过预检且未启用 PD 时 reload 总会本地重扫，不受该选项限制。Server 应用初始化阶段仍会扫描并尝试加载本地图配置。 +下面是可用的 `rest-server.properties` 示例。主线模板未写出 `graph.load_from_local_config`，源码默认值为 `false`。示例中设为 `true` 是可选的：它开启管理器构造阶段预加载，以及启用 PD 时 reload 对新增本地文件的发现；设为 +`false` 时仍会恢复已成功加载且文件仍存在的本地图；通过预检且未启用 PD 时 reload 总会本地重扫，不受该选项限制。Server 应用初始化阶段仍会扫描并尝试加载本地图配置。 ```properties # bind url @@ -110,7 +112,8 @@ memory_monitor.period=2000 - restserver.url：RestServer 提供服务的 url，根据实际环境修改。如果其他 IP 地址无法访问，可以尝试修改为特定的地址；或修改为 `http://0.0.0.0` 来监听来自任何 IP 地址的请求，这种方案较为便捷，但需要留意服务可被访问的网络范围； - graphs：图配置文件所在目录，默认值是 `./conf/graphs`。`init-store.sh` 会扫描该目录；Server 应用初始化也会扫描并尝试加载其中的 properties 文件； -- graph.load_from_local_config：是否在管理器构造阶段预加载本地图配置，源码默认值为 `false`。通过预检且未启用 PD 时，reload 会重扫启动图配置目录。启用 PD 时，会恢复已成功加载且文件仍存在的本地图；`true` 还会发现新增本地文件。本地配置先于 PD 元数据加载。它不会禁止 Server 应用初始化阶段的本地加载，也不是安全隔离开关； +- graph.load_from_local_config：是否在管理器构造阶段预加载本地图配置，源码默认值为 `false`。通过预检且未启用 PD 时，reload 会重扫启动图配置目录。启用 PD 时，会恢复已成功加载且文件仍存在的本地图；`true` 还会发现新增本地文件。本地配置先于 PD + 元数据加载。它不会禁止 Server 应用初始化阶段的本地加载，也不是安全隔离开关； 目录扫描成功后，reload 会更新本地来源记录；启用 PD 时，也会更新本地图删除保护。 启用 PD 时，`DEFAULT` 中已成功加载的本地图在配置文件仍存在时会拒绝公开删除，不受该选项影响，无论是否清空数据。 @@ -156,7 +159,8 @@ store=hugegraph **[可选]：修改 rest-server.properties** -通过修改 `rest-server.properties` 中的 `graphs` 配置项来设置图的配置文件目录。默认配置为 `graphs=./conf/graphs`；需要其他目录时调整 `graphs`。下面将 `graph.load_from_local_config` 设为 `true`，作为管理器构造阶段预加载的可选设置。启用 PD 时，它也会让 reload 发现新增本地文件；`false` 仍会恢复已成功加载且文件仍存在的本地图。通过预检且未启用 PD 时，reload 会重扫该目录。应用初始化仍会读取该目录中的本地图配置： +通过修改 `rest-server.properties` 中的 `graphs` 配置项来设置图的配置文件目录。默认配置为 `graphs=./conf/graphs`；需要其他目录时调整 `graphs`。下面将 `graph.load_from_local_config` 设为 +`true`，作为管理器构造阶段预加载的可选设置。启用 PD 时，它也会让 reload 发现新增本地文件；`false` 仍会恢复已成功加载且文件仍存在的本地图。通过预检且未启用 PD 时，reload 会重扫该目录。应用初始化仍会读取该目录中的本地图配置： ```properties graphs=./conf/graphs diff --git a/content/cn/docs/config/config-option.md b/content/cn/docs/config/config-option.md index 917a46df2..9c28af51c 100644 --- a/content/cn/docs/config/config-option.md +++ b/content/cn/docs/config/config-option.md @@ -36,7 +36,7 @@ search_boost: 1.5 | config option | default value | description | |----------------------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | graphs | ./conf/graphs | 图配置 properties 文件所在目录。 | -| graph.load_from_local_config | false | 控制管理器构造阶段是否预加载本地图配置，以及 `reload()` 时是否重扫。应用初始化仍会扫描并尝试加载 `graphs` 目录，因此 `false` 不是阻止本地配置加载的安全开关。 | +| graph.load_from_local_config | false | 控制构造阶段预加载。未启用 PD 时，通过预检的 reload 会重扫配置；启用 PD 时恢复文件仍存在的已成功加载本地图，`true` 还会发现新增配置。应用初始化仍扫描并尝试加载本地配置，`false` 不会阻止本地加载。 | | graphs.enable_dynamic_create_drop | true | Whether to enable create or drop graph dynamically. | | init_store.enabled | true | Whether init-store initializes the local backend stores and the built-in admin account. Set false in distributed deployments (PD/HStore) where the storage side already owns the metadata. | | server.id | 空字符串 | The optional legacy id of hugegraph-server. | diff --git a/content/cn/docs/guides/faq.md b/content/cn/docs/guides/faq.md index 3d687c6a7..cd918d06e 100644 --- a/content/cn/docs/guides/faq.md +++ b/content/cn/docs/guides/faq.md @@ -34,7 +34,9 @@ weight: 6 - 配置了两个图，名字是`hugegraph`和`hugegraph1`，而启动服务的命令是`start-hugegraph.sh`，是只打开了`hugegraph`这个图吗 - 脚本名称与图名无关。Server 默认从 `conf/graphs` 扫描并加载本地图配置，目录可在 `conf/rest-server.properties` 的 `graphs` 配置项中修改。`graph.load_from_local_config` 的默认值是 `false`，控制图管理器构造阶段的预加载，不能用于禁止启动时加载。通过预检且未启用 PD 时，reload 会重扫启动配置目录。启用 PD 时，会恢复已成功加载且配置文件仍存在的本地图；设为 `true` 时还会发现新增本地文件。本地配置优先于 PD 元数据。配置了 `auth.authenticator` 的部署会在关闭任何图之前以 HTTP 400 拒绝 reload，需要重启 Server 应用配置变化；需要加载多个本地图时，为每个图准备独立配置文件。详见[服务端配置说明](/cn/docs/config/config-guide/)。 + 脚本名称与图名无关。Server 默认从 `conf/graphs` 扫描并加载本地图配置，目录可在 `conf/rest-server.properties` 的 `graphs` 配置项中修改。`graph.load_from_local_config` 的默认值是 + `false`，控制图管理器构造阶段的预加载，不能用于禁止启动时加载。通过预检且未启用 PD 时，reload 会重扫启动配置目录。启用 PD 时，会恢复已成功加载且配置文件仍存在的本地图；设为 `true` 时还会发现新增本地文件。本地配置优先于 PD 元数据。配置了 + `auth.authenticator` 的部署会在关闭任何图之前以 HTTP 400 拒绝 reload，需要重启 Server 应用配置变化；需要加载多个本地图时，为每个图准备独立配置文件。详见[服务端配置说明](/cn/docs/config/config-guide/)。 启用 PD 时，`DEFAULT` 中已成功加载的本地图在配置文件仍存在时会拒绝公开删除，不受该选项影响；其他图空间的同名图不受此保护。 启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，即使本地加载失败后由 PD 元数据恢复同名图也受保护。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index ca8184ef5..806f063e4 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -221,7 +221,9 @@ mvn package -DskipTests -ntp -Drocksdb-only Server 的 tar 包随包提供 `conf/rest-server.properties`、`conf/gremlin-server.yaml` 和 `conf/graphs/hugegraph.properties`；源码构建包从 `hugegraph-server/hugegraph-dist/src/assembly/static/conf/` 装配这些文件。解压后在 Server 安装目录内编辑配置，无需另行生成。发行包版本之间可能有默认值差异，下面涉及的默认值和启动行为按 `master` 主线说明。 -单机 RocksDB 快速上手只需确认 `conf/graphs/hugegraph.properties` 使用 `backend=rocksdb`、`serializer=binary`。正常 Server 初始化会扫描 `conf/graphs/` 并加载本地图配置，无需额外设置 `graph.load_from_local_config=true`。该选项默认值为 `false`，控制构造阶段的提前加载。通过预检且未启用 PD 时，reload 会重扫启动图配置目录。启用 PD 时，会恢复已成功加载且文件仍存在的本地图；`true` 还会发现新增本地文件。本地配置优先于 PD 元数据。配置了 `auth.authenticator` 时，reload 会在关闭图之前返回 HTTP 400，需要重启 Server 应用配置变化。重载行为详见[图管理 API](/cn/docs/clients/restful-api/graphs/)。 +单机 RocksDB 快速上手只需确认 `conf/graphs/hugegraph.properties` 使用 `backend=rocksdb`、`serializer=binary`。正常 Server 初始化会扫描 `conf/graphs/` 并加载本地图配置，无需额外设置 +`graph.load_from_local_config=true`。该选项默认值为 `false`，控制构造阶段的提前加载。通过预检且未启用 PD 时，reload 会重扫启动图配置目录。启用 PD 时，会恢复已成功加载且文件仍存在的本地图；`true` 还会发现新增本地文件。本地配置优先于 PD +元数据。配置了 `auth.authenticator` 时，reload 会在关闭图之前返回 HTTP 400，需要重启 Server 应用配置变化。重载行为详见[图管理 API](/cn/docs/clients/restful-api/graphs/)。 启用 PD 时，`DEFAULT` 中已成功加载的本地图在配置文件仍存在时会拒绝公开删除，不受该选项影响；其他图空间的同名图不受此保护。 启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，即使本地加载失败后由 PD 元数据恢复同名图也受保护。 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 78d34bb59..98107468a 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -432,7 +432,8 @@ and PD metadata restores a graph with that name. With PD and `false`, a new loca Remove the configuration file: a successful directory scan during reload clears its local-source tracking and deletion protection before detachment. Later opening or startup failures do not roll back that scan snapshot, even when the whole reload returns HTTP 400. After the old instance closes and detaches, PD metadata may restore the graph for public deletion; otherwise its runtime registration is removed -while backend data remains. If closing fails, the old registration is retained for an explicit retry. This removes the local startup source, so a subsequent restart will not reload it from that deleted file. +while backend data remains. If closing fails, the old registration is retained for an explicit retry. This removes the local startup source, so a +subsequent restart will not reload it from that deleted file. Source tracking follows the registered graph instance: removal of an old instance does not discard a newer local replacement. For public deletion in `DEFAULT`, the corresponding local-source tracking is cleared only after deletion completes. Without PD, public graph deletion still clears data and removes its local configuration; the PD protection rule does not apply. diff --git a/content/en/docs/config/config-backend-hstore.md b/content/en/docs/config/config-backend-hstore.md index 189ade32c..e30d07eb6 100644 --- a/content/en/docs/config/config-backend-hstore.md +++ b/content/en/docs/config/config-backend-hstore.md @@ -168,7 +168,7 @@ in the checked Server master commit `2f827d6` where the option is declared. | usePD | rest-server.properties | false | Whether Server loads its metadata from PD at startup | `ServerOptions.java:401-407` | | cluster | rest-server.properties | hg-test | Cluster name used as the prefix of every PD metadata key | `ServerOptions.java:187-193` | | init_store.enabled | rest-server.properties | true | Set it to `false` in a PD/Store deployment, where the storage side already owns the metadata | `ServerOptions.java:382-390` | -| graph.load_from_local_config | rest-server.properties | false | Controls constructor preloading and rescanning on `reload()`; application initialization still scans and attempts to load local configurations, so `false` does not block local loading | `ServerOptions.java:366-372` | +| graph.load_from_local_config | rest-server.properties | false | Controls constructor preloading. Without PD, reloads that pass preflight rescan configurations. With PD, reload restores successfully loaded local sources whose files remain; `true` also discovers new files. Application initialization still scans and attempts to load local configurations, so `false` does not block local loading. | `ServerOptions.java:366-372` | | auth.graph_store | rest-server.properties | hugegraph | The graph that holds auth data, checked against the `hstore` backend when init-store is off | `ServerOptions.java:602-609` | | graphspace | {graph}.properties | DEFAULT | First segment of the graph name PD sees | `CoreOptions.java:679-685` | diff --git a/content/en/docs/config/config-guide.md b/content/en/docs/config/config-guide.md index 630c94a7c..2583effda 100644 --- a/content/en/docs/config/config-guide.md +++ b/content/en/docs/config/config-guide.md @@ -25,7 +25,8 @@ The following sections describe these files. > The authentication settings on this page apply to HugeGraph Server. In production, enable [authentication and authorization](/docs/config/config-authentication/), maintain an IP allowlist, grant minimum permissions, and retain and protect Server `audit-*.log` files. Commented authentication settings in the examples indicate that authentication is disabled by default. The distribution copies default files from the Server repository into the installation directory's `conf/` folder. Options absent from these files use source-code defaults; explicit file settings override those defaults. -The default distribution file layout and settings were checked against Server master commit `2f827d6`. Use the configuration files and entry scripts that correspond to your installed release. +The default distribution file layout and settings were checked against Server master commit `2f827d6`. Use the configuration files and entry scripts that +correspond to your installed release. | File | Source and purpose | Loading behavior | |------|------------|----------| @@ -53,7 +54,11 @@ graphs: {} ssl: { enabled: false } ``` -Usually, focus on `channelizer`, `host`, and `port`. Graphs are not loaded from the Gremlin Server `graphs` section. During application initialization, the REST-side manager scans the `graphs` directory and attempts to load local graph configurations. `graph.load_from_local_config` controls constructor preloading; its default `false` does not disable local loading during application initialization. Without PD, a reload that passes preflight rescans this directory. With PD, it restores local graphs previously loaded successfully whose files still exist; `true` also discovers new local files. Local configurations are loaded before PD metadata. +Usually, focus on `channelizer`, `host`, and `port`. Graphs are not loaded from the Gremlin Server `graphs` section. During application initialization, the +REST-side manager scans the `graphs` directory and attempts to load local graph configurations. `graph.load_from_local_config` controls constructor +preloading; its default `false` does not disable local loading during application initialization. Without PD, a reload that passes preflight rescans this +directory. With PD, it restores local graphs previously loaded successfully whose files still exist; `true` also discovers new local files. Local +configurations are loaded before PD metadata. - `channelizer`: The default `WsAndHttpChannelizer` supports WebSocket and HTTP. Gremlin Console uses WebSocket; HugeGraph Client, Loader, and Hubble use HTTP. @@ -66,7 +71,10 @@ Set the matching `gremlinserver.url=http://host:port` in `rest-server.properties ### 3 rest-server.properties -The following example lists `rest-server.properties` options. The master template omits `graph.load_from_local_config`, whose source-code default is `false`. Setting it to `true` is optional: it enables constructor preloading and discovery of new local files on reload when PD is enabled. With PD and `false`, reload still restores local graphs previously loaded successfully whose files still exist. A reload that passes preflight without PD always rescans locally, regardless of this flag. Application initialization still scans and attempts to load local graph configurations. +The following example lists `rest-server.properties` options. The master template omits `graph.load_from_local_config`, whose source-code default is +`false`. Setting it to `true` is optional: it enables constructor preloading and discovery of new local files on reload when PD is enabled. With PD and +`false`, reload still restores local graphs previously loaded successfully whose files still exist. A reload that passes preflight without PD always +rescans locally, regardless of this flag. Application initialization still scans and attempts to load local graph configurations. ```properties # bind url @@ -110,11 +118,15 @@ memory_monitor.period=2000 - `restserver.url`: The REST listener URL. Use a specific address for remote access, or `http://0.0.0.0` to listen on every interface while restricting the accessible network. - `graphs`: The graph configuration directory, defaulting to `./conf/graphs`. Both `init-store.sh` and application initialization scan it; initialization attempts to load its properties files. -- `graph.load_from_local_config`: Controls constructor preloading, with source-code default `false`. Without PD, a reload that passes preflight rescans the startup graph directory. With PD, it restores local graphs previously loaded successfully whose files still exist; `true` also discovers new local files. Local configurations are loaded before PD metadata. It does not block local loading during application initialization and is not a security isolation switch. +- `graph.load_from_local_config`: Controls constructor preloading, with source-code default `false`. Without PD, a reload that passes preflight rescans the + startup graph directory. With PD, it restores local graphs previously loaded successfully whose files still exist; `true` also discovers new local files. + Local configurations are loaded before PD metadata. It does not block local loading during application initialization and is not a security isolation + switch. A successful reload scan updates local-source tracking; with PD, it also updates local graph deletion protection. With PD, local graphs successfully loaded in `DEFAULT` reject public deletion while their configuration files remain, regardless of the flag. -With PD and `true`, protection also covers all configuration names from a successful scan, including a graph restored from PD metadata after local loading fails. +With PD and `true`, protection also covers all configuration names from a successful scan, including a graph restored from PD metadata after local loading +fails. This applies with or without data clearing; a graph with the same name in another graph space is not protected by the local file. With PD and `false`, a new local file that has never been loaded remains ignored and does not create deletion protection. After a local file is removed, a successful directory scan during reload clears that source and protection before detachment. @@ -161,7 +173,10 @@ A Server can load multiple graphs, each with its own properties file. This examp **[Optional]: Modify rest-server.properties** -Set the graph configuration directory with `graphs` in `rest-server.properties`, defaulting to `graphs=./conf/graphs`. Adjust it for another directory. The example optionally enables constructor preloading with `graph.load_from_local_config=true`. With PD, the flag also enables discovery of new local files on reload; `false` still restores local graphs previously loaded successfully whose files still exist. Without PD, a reload that passes preflight rescans this directory. Application initialization still reads local graph configurations from it: +Set the graph configuration directory with `graphs` in `rest-server.properties`, defaulting to `graphs=./conf/graphs`. Adjust it for another directory. The +example optionally enables constructor preloading with `graph.load_from_local_config=true`. With PD, the flag also enables discovery of new local files on +reload; `false` still restores local graphs previously loaded successfully whose files still exist. Without PD, a reload that passes preflight rescans this +directory. Application initialization still reads local graph configurations from it: ```properties graphs=./conf/graphs diff --git a/content/en/docs/config/config-option.md b/content/en/docs/config/config-option.md index 633c627e5..7f2d2738f 100644 --- a/content/en/docs/config/config-option.md +++ b/content/en/docs/config/config-option.md @@ -36,7 +36,7 @@ Corresponding configuration file `rest-server.properties` | config option | default value | description | |----------------------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | graphs | ./conf/graphs | Directory containing graph configuration properties files. | -| graph.load_from_local_config | false | Controls local graph preloading in the manager constructor and rescanning on `reload()`. Application initialization still scans and attempts to load `graphs`; `false` does not prevent local loading. | +| graph.load_from_local_config | false | Controls constructor preloading. Without PD, reloads that pass preflight rescan configurations. With PD, reload restores successfully loaded local sources whose files remain; `true` also discovers new files. Application initialization still scans and attempts to load local configurations, so `false` does not block local loading. | | graphs.enable_dynamic_create_drop | true | Whether to enable create or drop graph dynamically. | | init_store.enabled | true | Whether init-store initializes the local backend stores and the built-in admin account. Set false in distributed deployments (PD/HStore) where the storage side already owns the metadata. | | server.id | Empty string | The optional legacy id of hugegraph-server. | diff --git a/content/en/docs/guides/faq.md b/content/en/docs/guides/faq.md index 2cf51d106..a56a02ed7 100644 --- a/content/en/docs/guides/faq.md +++ b/content/en/docs/guides/faq.md @@ -34,7 +34,13 @@ weight: 6 - Two graphs are configured, the names are `hugegraph` and `hugegraph1`, and the command to start the service is `start-hugegraph.sh`. Is only the hugegraph graph opened? - The script name is unrelated to the graph name. Server scans and loads local graph configurations from `conf/graphs` by default; change the directory with `graphs` in `conf/rest-server.properties`. `graph.load_from_local_config` defaults to `false` and controls constructor preloading, not whether startup loads local graphs. Without PD, a reload that passes preflight rescans the startup configuration directory. With PD, it restores local graphs previously loaded successfully whose configuration files still exist; setting the flag to `true` also discovers new local files. Local configurations take precedence over PD metadata. A configured `auth.authenticator` rejects reload with HTTP 400 before closing any graph; restart Server to apply configuration changes in that deployment. Give each local graph its own configuration file. See the [Server configuration guide](/docs/config/config-guide/). + The script name is unrelated to the graph name. Server scans and loads local graph configurations from `conf/graphs` by default; change the directory + with `graphs` in `conf/rest-server.properties`. `graph.load_from_local_config` defaults to `false` and controls constructor preloading, not whether + startup loads local graphs. Without PD, a reload that passes preflight rescans the startup configuration directory. With PD, it restores local graphs + previously loaded successfully whose configuration files still exist; setting the flag to `true` also discovers new local files. Local configurations + take precedence over PD metadata. A configured `auth.authenticator` rejects reload with HTTP 400 before closing any graph; restart Server to apply + configuration changes in that deployment. Give each local graph its own configuration file. See the [Server configuration + guide](/docs/config/config-guide/). With PD, local graphs successfully loaded in `DEFAULT` reject public deletion while their configuration files remain, regardless of this flag. With PD and `true`, protection also covers every name in a successful directory scan, even if local loading fails and PD metadata restores that graph. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index f05a0102e..55fd68c41 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -226,7 +226,12 @@ mvn package -DskipTests -ntp -Drocksdb-only Server archives include `conf/rest-server.properties`, `conf/gremlin-server.yaml`, and `conf/graphs/hugegraph.properties`; source builds assemble them from `hugegraph-server/hugegraph-dist/src/assembly/static/conf/`. Edit them inside the extracted Server directory without a separate generation step. Defaults vary by release; the following defaults and startup behavior describe master. -For standalone RocksDB, confirm `backend=rocksdb` and `serializer=binary` in `conf/graphs/hugegraph.properties`. Normal Server initialization scans `conf/graphs/` and loads local graphs without requiring `graph.load_from_local_config=true`. This option defaults to `false` and controls constructor preloading. Without PD, a reload that passes preflight rescans the startup graph directory. With PD, it restores local graphs previously loaded successfully whose files still exist; `true` also discovers new local files. Local configurations take precedence over PD metadata. If `auth.authenticator` is configured, reload returns HTTP 400 before closing graphs; restart Server to apply configuration changes. See the [graph API](/docs/clients/restful-api/graphs/) for reload behavior. +For standalone RocksDB, confirm `backend=rocksdb` and `serializer=binary` in `conf/graphs/hugegraph.properties`. Normal Server initialization scans +`conf/graphs/` and loads local graphs without requiring `graph.load_from_local_config=true`. This option defaults to `false` and controls constructor +preloading. Without PD, a reload that passes preflight rescans the startup graph directory. With PD, it restores local graphs previously loaded +successfully whose files still exist; `true` also discovers new local files. Local configurations take precedence over PD metadata. If `auth.authenticator` +is configured, reload returns HTTP 400 before closing graphs; restart Server to apply configuration changes. See the [graph +API](/docs/clients/restful-api/graphs/) for reload behavior. With PD, local graphs successfully loaded in `DEFAULT` reject public deletion while their configuration files remain, regardless of this flag. With PD and `true`, protection also covers every name in a successful directory scan, even if local loading fails and PD metadata restores that graph. From 60ab81dbb03ba79618ab807e71624725f1344480 Mon Sep 17 00:00:00 2001 From: imbajin Date: Mon, 12 Oct 2026 18:26:04 +0800 Subject: [PATCH 03/11] docs: clarify reload and task deletion - document overlapping reload rejection and retry - qualify closed graph cleanup and data boundaries - explain local task owner waits and forced cancellation --- content/cn/docs/clients/restful-api/graphs.md | 10 ++++++++-- content/cn/docs/clients/restful-api/task.md | 7 ++++++- content/cn/docs/config/config-guide.md | 4 +++- content/cn/docs/guides/faq.md | 4 +++- .../docs/quickstart/hugegraph/hugegraph-server.md | 4 +++- content/en/docs/clients/restful-api/graphs.md | 13 ++++++++++--- content/en/docs/clients/restful-api/task.md | 8 +++++++- content/en/docs/config/config-guide.md | 8 ++++++-- content/en/docs/guides/faq.md | 5 ++++- .../docs/quickstart/hugegraph/hugegraph-server.md | 5 ++++- 10 files changed, 54 insertions(+), 14 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 37d907222..3e8225965 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -244,6 +244,9 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx 包括本地加载失败后由 PD 元数据恢复的同名图。先移除文件，再执行 reload，目录扫描成功即在分离图之前解除保护；后续阶段返回 HTTP 400 也不回滚该快照。 也可重启 Server。其他图空间的同名图不受此本地文件保护。 +移除图时捕获到 `close()` 异常，若图已标记关闭，会记录异常并移除运行时绑定；若图仍未关闭，则保留注册供重试。 +后端数据或 PD 元数据可能已被移除，重试不会恢复这些数据。 + ##### Params **路径参数说明：** @@ -439,6 +442,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default 在图配置变更后，重新加载此 Server 持有的所有图。Reload 保留后端数据和本地配置文件。 +每个图管理器同一时间只执行一个 reload。重叠请求会在扫描配置或关闭图之前返回 HTTP 400；当前请求结束后可重试，无论该请求成功还是失败。 + 通过预检且未启用 PD 时，reload 会重扫启动图配置目录中的所有当前文件，即使 `graph.load_from_local_config=false`。 启用 PD 且该选项为 `false` 时，只恢复之前成功加载且配置文件仍存在的本地图，不加载新增本地文件；设为 `true` 时还会发现新增本地文件。 先加载本地配置，再从 PD 元数据加载尚未恢复的图。新加载的图在启用 RPC 时先等待就绪，再完成启动和任务调度初始化，然后恢复 Gremlin 图与遍历绑定。 @@ -448,14 +453,15 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default 其他图空间的同名图不受该本地文件保护。启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，即使本地加载失败后由 PD 元数据恢复同名图也受保护。 启用 PD 且设为 `false` 时，从未加载的新增本地文件仍被忽略，也不会建立删除保护。移除配置文件后，reload 中的目录扫描成功即在分离图之前清除对应来源和保护。 后续打开或启动失败、整个 reload 返回 HTTP 400，也不会回滚已成功扫描的快照。旧实例成功关闭并分离后，若 PD 元数据中仍有该图，则可恢复并公开删除； -否则移除其运行时注册，但保留后端数据。关闭失败则保留旧注册，供显式重试。本地启动来源已移除，下次重启不会再从已删除的文件加载该图。 +否则移除其运行时注册，但保留后端数据。关闭尝试后图仍未关闭时，保留旧注册供显式重试。 +图已标记关闭后捕获到关闭异常时，会记录异常并移除运行时绑定。本地启动来源已移除，下次重启不会再从已删除的文件加载该图。 来源记录跟随实际注册的图实例；旧实例移除不会清除新的本地替代实例。公开删除 `DEFAULT` 中的图时，仅在删除完成后清除对应的来源记录。 未启用 PD 时，公开删除图仍会清空数据并移除本地配置，上述 PD 删除保护不适用。 配置了 `auth.authenticator` 时，请求会在关闭任何图之前返回 HTTP 400，因为鉴权服务保留了图引用。此类部署需要重启 Server 应用图配置变化， 被拒绝的 reload 不会改动原有图、数据或配置。 -关闭失败的图仍保留注册，供显式重试；重载启动失败后，清理时仍未关闭的对象也会保留。其他可恢复的图可能先完成重载，再汇报打开或启动失败。不完整的 reload 会返回 HTTP 400， +关闭尝试后仍未关闭的图会保留注册，供显式重试；重载启动失败后，清理时仍未关闭的对象也会保留。其他可恢复的图可能先完成重载，再汇报打开或启动失败。不完整的 reload 会返回 HTTP 400， 部分图恢复成功不能作为整个请求成功的依据。排除故障后重试。 受管理的图已注册图/Schema 缓存通知 RPC 服务时，reload 同样会在关闭任何图之前返回 HTTP 400。这些服务的安全重绑尚未实现，需要重启 Server diff --git a/content/cn/docs/clients/restful-api/task.md b/content/cn/docs/clients/restful-api/task.md index 6cae55ffc..c0d180524 100644 --- a/content/cn/docs/clients/restful-api/task.md +++ b/content/cn/docs/clients/restful-api/task.md @@ -88,7 +88,12 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2 ##### Params -- force: 任务仍在运行时是否强制删除，默认为 false +- force: 是否允许删除未完成任务的信息，默认为 false。本地任务未完成且仍在运行时会请求取消；该参数不会跳过下述执行等待。 + +使用本地调度器时，`SUCCESS` 状态可能先于完成回调保存结果结束而可见。 +删除会等待最多 `task.wait_timeout` 秒，直到执行及其回调结束，再检查存储状态并移除记录。 +超时或中断会保留任务记录及仍活跃的执行对象，供重试；即使 `force=true`，执行对象仍活跃时也不会移除记录。 +上述等待行为适用于本地调度器。 ##### Method & Url diff --git a/content/cn/docs/config/config-guide.md b/content/cn/docs/config/config-guide.md index 19596ae50..ac995d97f 100644 --- a/content/cn/docs/config/config-guide.md +++ b/content/cn/docs/config/config-guide.md @@ -120,8 +120,10 @@ memory_monitor.period=2000 启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，包括本地加载失败后由 PD 元数据恢复的同名图。 其他图空间的同名图不受此本地文件保护；启用 PD 且设为 `false` 时，从未加载的新增本地文件仍被忽略，不会建立删除保护。 移除本地文件后，reload 中的目录扫描成功即在分离图之前清除对应来源和保护；后续阶段失败、整个请求返回 HTTP 400，也不会回滚该扫描快照。 -旧实例成功关闭并分离后，图可改由 PD 元数据恢复；否则移除运行时注册，但保留后端数据。关闭失败则保留旧注册，供显式重试。 +旧实例成功关闭并分离后，图可改由 PD 元数据恢复；否则移除运行时注册，但保留后端数据。关闭尝试后图仍未关闭时，保留旧注册供显式重试。 +图已标记关闭后捕获到关闭异常时，会记录异常并移除运行时绑定。 扫描失败会保留现有图和保护状态。未启用 PD 时，公开删除图仍会清空数据并移除本地配置。详细行为见下方图管理 API。 +每个图管理器同一时间只执行一个 reload。重叠请求会在扫描配置或关闭图之前返回 HTTP 400；当前请求结束后可重试，无论该请求成功还是失败。 配置了 `auth.authenticator` 时，reload 会在关闭任何图之前以 HTTP 400 拒绝请求，需要重启 Server 应用图配置变化。失败与恢复行为详见[图管理 API](/cn/docs/clients/restful-api/graphs/)。 图/Schema 缓存通知 RPC 服务已注册时，reload 同样会在关闭任何图之前返回 HTTP 400，应改用重启 Server。服务的安全重绑尚未实现，需要在 Linux 高性能机器的分布式部署中修复并验证。 diff --git a/content/cn/docs/guides/faq.md b/content/cn/docs/guides/faq.md index cd918d06e..9c304fc29 100644 --- a/content/cn/docs/guides/faq.md +++ b/content/cn/docs/guides/faq.md @@ -42,8 +42,10 @@ weight: 6 启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，即使本地加载失败后由 PD 元数据恢复同名图也受保护。 启用 PD 且设为 `false` 时，从未加载的新增本地文件仍被忽略，也不会建立删除保护。 移除本地文件后，reload 中的目录扫描成功即在分离图之前解除保护；后续阶段失败、整个请求返回 HTTP 400，也不会回滚该扫描快照。 - 旧实例成功关闭并分离后，图可改由 PD 元数据恢复；否则移除运行时注册，保留后端数据。关闭失败则保留旧注册，供显式重试。 + 旧实例成功关闭并分离后，图可改由 PD 元数据恢复；否则移除运行时注册，保留后端数据。关闭尝试后图仍未关闭时，保留旧注册供显式重试。 + 图已标记关闭后捕获到关闭异常时，会记录异常并移除运行时绑定。 扫描失败会保留现有图和保护状态。未启用 PD 时，公开删除图仍会清空数据并移除本地配置。 + 每个图管理器同一时间只执行一个 reload。重叠请求会在扫描配置或关闭图之前返回 HTTP 400；当前请求结束后可重试，无论该请求成功还是失败。 图/Schema 缓存通知 RPC 服务已注册时，reload 也会在关闭任何图之前返回 HTTP 400，应改用重启 Server。服务的安全重绑尚未实现，Linux 高性能机器上的修复与验证要求见[图管理 API](/cn/docs/clients/restful-api/graphs/)。 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index 806f063e4..c7cf163fb 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -229,8 +229,10 @@ Server 的 tar 包随包提供 `conf/rest-server.properties`、`conf/gremlin-ser 启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，即使本地加载失败后由 PD 元数据恢复同名图也受保护。 启用 PD 且设为 `false` 时，从未加载的新增本地文件仍被忽略，也不会建立删除保护。 移除本地文件后，reload 中的目录扫描成功即在分离图之前解除保护；后续阶段失败、整个请求返回 HTTP 400，也不会回滚该扫描快照。 -旧实例成功关闭并分离后，图可改由 PD 元数据恢复；否则移除运行时注册，保留后端数据。关闭失败则保留旧注册，供显式重试。 +旧实例成功关闭并分离后，图可改由 PD 元数据恢复；否则移除运行时注册，保留后端数据。关闭尝试后图仍未关闭时，保留旧注册供显式重试。 +图已标记关闭后捕获到关闭异常时，会记录异常并移除运行时绑定。 扫描失败会保留现有图和保护状态。未启用 PD 时，公开删除图仍会清空数据并移除本地配置。 +每个图管理器同一时间只执行一个 reload。重叠请求会在扫描配置或关闭图之前返回 HTTP 400；当前请求结束后可重试，无论该请求成功还是失败。 图/Schema 缓存通知 RPC 服务已注册时，reload 也会在关闭任何图之前返回 HTTP 400，应改用重启 Server。服务的安全重绑尚未实现，Linux 高性能机器上的修复与验证要求见图管理 API。 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 98107468a..0ae5942dc 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -220,6 +220,9 @@ and, with `true`, for every configuration name from a successful directory scan, Remove the file and run reload: a successful directory scan releases the protection before detachment, even if later reload phases return HTTP 400. Restarting Server is another option. This protection does not apply to a graph with the same name in another graph space. +When graph removal catches an exception from `close()`, it logs the failure and removes runtime bindings if the graph is already marked closed. +If the graph is still open, its registration is retained for retry. Backend data or PD metadata may already have been removed; retry does not restore it. + ##### Params **Path parameters** @@ -416,6 +419,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default Reloads all graphs held by this Server after graph configuration changes. Reload preserves backend data and local configuration files. +Only one reload request can run at a time per graph manager. An overlapping request returns HTTP 400 before scanning configurations or closing graphs. +Retry after the active request finishes, whether it succeeds or fails. + Without PD, a reload that passes preflight rescans all current files in the startup graph configuration directory, even when `graph.load_from_local_config=false`. With PD and `false`, reload restores only local graphs previously loaded successfully whose configuration files still exist; it ignores new local files. Setting the flag to `true` also discovers new local files. @@ -432,8 +438,9 @@ and PD metadata restores a graph with that name. With PD and `false`, a new loca Remove the configuration file: a successful directory scan during reload clears its local-source tracking and deletion protection before detachment. Later opening or startup failures do not roll back that scan snapshot, even when the whole reload returns HTTP 400. After the old instance closes and detaches, PD metadata may restore the graph for public deletion; otherwise its runtime registration is removed -while backend data remains. If closing fails, the old registration is retained for an explicit retry. This removes the local startup source, so a -subsequent restart will not reload it from that deleted file. +while backend data remains. If closing leaves the graph open, the old registration is retained for an explicit retry. +A caught close exception after the graph is marked closed is logged and its runtime bindings are removed. +This removes the local startup source, so a subsequent restart will not reload it from that deleted file. Source tracking follows the registered graph instance: removal of an old instance does not discard a newer local replacement. For public deletion in `DEFAULT`, the corresponding local-source tracking is cleared only after deletion completes. Without PD, public graph deletion still clears data and removes its local configuration; the PD protection rule does not apply. @@ -441,7 +448,7 @@ Without PD, public graph deletion still clears data and removes its local config A configured `auth.authenticator` causes HTTP 400 before any graph is closed, because authentication services retain graph references. Restart Server to apply graph configuration changes in that deployment; the rejected reload leaves the original graphs, data and configuration intact. -Graphs that fail to close remain registered for an explicit retry, including objects whose cleanup fails after a reload startup failure. +Graphs still open after a close attempt remain registered for an explicit retry, including objects not closed during cleanup after a reload startup failure. Other recoverable graphs may reload before an opening or startup failure is reported. An incomplete reload returns HTTP 400; successful recovery of some graphs does not make the whole reload successful. Correct the failure and retry. diff --git a/content/en/docs/clients/restful-api/task.md b/content/en/docs/clients/restful-api/task.md index bfebd8d6c..80140a595 100644 --- a/content/en/docs/clients/restful-api/task.md +++ b/content/en/docs/clients/restful-api/task.md @@ -88,7 +88,13 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2 ##### Params -- force: whether to delete the task even when it is still running, default is false +- force: allows deletion of incomplete task information, default is false. For local tasks, it requests cancellation of an incomplete running task; + it does not bypass the execution wait below. + +For the local scheduler, a `SUCCESS` status can become visible before the completion callback finishes saving the result. +Deletion waits up to `task.wait_timeout` seconds for execution and its callback to finish, then checks the stored status before removing the record. +Timeout or interruption retains the task record and any active execution owner for retry. Even with `force=true`, the record is not removed +while its execution owner is active. This waiting behavior applies to local schedulers. ##### Method & Url diff --git a/content/en/docs/config/config-guide.md b/content/en/docs/config/config-guide.md index 2583effda..52ed77d44 100644 --- a/content/en/docs/config/config-guide.md +++ b/content/en/docs/config/config-guide.md @@ -131,9 +131,13 @@ This applies with or without data clearing; a graph with the same name in anothe With PD and `false`, a new local file that has never been loaded remains ignored and does not create deletion protection. After a local file is removed, a successful directory scan during reload clears that source and protection before detachment. Later reload failures do not roll back this snapshot, even if the request returns HTTP 400. After the old instance closes and detaches, -PD metadata may restore it; otherwise its runtime registration is removed while backend data remains. A close failure retains the old registration -for an explicit retry. A scan failure preserves existing graphs and protection. +PD metadata may restore it; otherwise its runtime registration is removed while backend data remains. If closing leaves the graph open, the old +registration is retained for an explicit retry. +A caught close exception after the graph is marked closed is logged and its runtime bindings are removed. A scan failure preserves existing graphs and +protection. Without PD, public graph deletion still clears data and removes its local configuration. See the graph API below for details. +Only one reload runs at a time per graph manager. Overlapping requests return HTTP 400 before scanning configurations or closing graphs; +retry after the active request finishes, whether it succeeds or fails. Reload is rejected with HTTP 400 before any graph is closed when `auth.authenticator` is configured. Restart Server to apply graph configuration changes in that deployment. See the [graph API](/docs/clients/restful-api/graphs/) for reload failure and recovery behavior. diff --git a/content/en/docs/guides/faq.md b/content/en/docs/guides/faq.md index a56a02ed7..388af8237 100644 --- a/content/en/docs/guides/faq.md +++ b/content/en/docs/guides/faq.md @@ -48,8 +48,11 @@ weight: 6 Other graph spaces are outside this protection. Remove the file; a successful directory scan during reload releases its protection before detachment. Later reload failures do not roll back that scan snapshot, even when the request returns HTTP 400. After the old instance closes and detaches, PD metadata may restore it; otherwise its runtime registration is removed while backend data remains. - If closing fails, the old registration is retained for an explicit retry. + If closing leaves the graph open, the old registration is retained for an explicit retry. + A caught close exception after the graph is marked closed is logged and its runtime bindings are removed. A scan failure preserves existing graphs and protection. Without PD, public graph deletion still clears data and removes its local configuration. + Only one reload runs at a time per graph manager. Overlapping requests return HTTP 400 before scanning configurations or closing graphs; + retry after the active request finishes, whether it succeeds or fails. Registered graph/schema cache-notification RPC services also cause reload to return HTTP 400 before closing any graph. Restart Server instead; safe service rebinding remains unimplemented. See the [graph API](/docs/clients/restful-api/graphs/) for the Linux repair and validation requirement. diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 55fd68c41..5e65d2e8a 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -239,8 +239,11 @@ With PD and `false`, never-loaded new files remain ignored and unprotected. Other graph spaces are outside this protection. Remove the file; a successful directory scan during reload releases its protection before detachment. Later reload failures do not roll back that scan snapshot, even when the request returns HTTP 400. After the old instance closes and detaches, PD metadata may restore it; otherwise its runtime registration is removed while backend data remains. -If closing fails, the old registration is retained for an explicit retry. +If closing leaves the graph open, the old registration is retained for an explicit retry. +A caught close exception after the graph is marked closed is logged and its runtime bindings are removed. A scan failure preserves existing graphs and protection. Without PD, public graph deletion still clears data and removes its local configuration. +Only one reload runs at a time per graph manager. Overlapping requests return HTTP 400 before scanning configurations or closing graphs; +retry after the active request finishes, whether it succeeds or fails. Registered graph/schema cache-notification RPC services also make reload return HTTP 400 before closing any graph; use Server restart. Their safe rebinding remains unimplemented; the graph API documents the required repair and validation on a high-performance Linux deployment. From d7fee004ab35c4d49cbe0e0a055f76ed05838ee5 Mon Sep 17 00:00:00 2001 From: imbajin Date: Mon, 12 Oct 2026 20:02:49 +0800 Subject: [PATCH 04/11] docs: clarify reload and removal exclusion - describe the manager lifecycle admission guard - retain explicit retry and notification boundaries - align the Chinese and English API guidance --- content/cn/docs/clients/restful-api/graphs.md | 3 ++- content/en/docs/clients/restful-api/graphs.md | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 3e8225965..4d03eb41e 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -442,7 +442,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default 在图配置变更后，重新加载此 Server 持有的所有图。Reload 保留后端数据和本地配置文件。 -每个图管理器同一时间只执行一个 reload。重叠请求会在扫描配置或关闭图之前返回 HTTP 400；当前请求结束后可重试，无论该请求成功还是失败。 +每个图管理器中的 reload 与图移除互斥，包括本地图删除和远端移除通知。重叠的此类 REST 请求会在扫描配置或改动图之前返回 HTTP 400。 +当前操作持续占用该互斥入口，直到 reload 完成图的关闭与重开，或图移除结束。操作结束后，包括失败或超时，需显式重试；远端移除通知不会自动重试。 通过预检且未启用 PD 时，reload 会重扫启动图配置目录中的所有当前文件，即使 `graph.load_from_local_config=false`。 启用 PD 且该选项为 `false` 时，只恢复之前成功加载且配置文件仍存在的本地图，不加载新增本地文件；设为 `true` 时还会发现新增本地文件。 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 0ae5942dc..acc195ef2 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -419,8 +419,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default Reloads all graphs held by this Server after graph configuration changes. Reload preserves backend data and local configuration files. -Only one reload request can run at a time per graph manager. An overlapping request returns HTTP 400 before scanning configurations or closing graphs. -Retry after the active request finishes, whether it succeeds or fails. +Reload and graph removal are mutually exclusive within each graph manager, including local deletion and remote removal notifications. +An overlapping REST request for these operations returns HTTP 400 before scanning configurations or changing graphs. +The active operation retains this exclusion until reload finishes closing and reopening graphs, or graph removal ends. +Retry explicitly after it ends, including failure or timeout. Remote removal notifications are not automatically retried. Without PD, a reload that passes preflight rescans all current files in the startup graph configuration directory, even when `graph.load_from_local_config=false`. With PD and `false`, reload restores only local graphs previously loaded successfully From 61eef10d277f6a8e4aedc2ee68cd8b634411cbd9 Mon Sep 17 00:00:00 2001 From: imbajin Date: Mon, 12 Oct 2026 20:42:45 +0800 Subject: [PATCH 05/11] docs: clarify removal and task retry behavior - explain deferred remote graph removal notifications - include overlapping operations in reload error summary - distinguish local waiting from distributed task deletion --- content/cn/docs/clients/restful-api/graphs.md | 7 +++++-- content/cn/docs/clients/restful-api/task.md | 6 +++++- content/en/docs/clients/restful-api/graphs.md | 9 ++++++--- content/en/docs/clients/restful-api/task.md | 6 +++++- 4 files changed, 21 insertions(+), 7 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 4d03eb41e..625c0cbc0 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -443,7 +443,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default 在图配置变更后，重新加载此 Server 持有的所有图。Reload 保留后端数据和本地配置文件。 每个图管理器中的 reload 与图移除互斥，包括本地图删除和远端移除通知。重叠的此类 REST 请求会在扫描配置或改动图之前返回 HTTP 400。 -当前操作持续占用该互斥入口，直到 reload 完成图的关闭与重开，或图移除结束。操作结束后，包括失败或超时，需显式重试；远端移除通知不会自动重试。 +当前操作持续占用该互斥入口，直到 reload 完成图的关闭与重开，或图移除结束。操作结束后，包括失败或超时，需显式重试被拒绝的 REST 请求。 +操作执行期间收到的远端移除通知会延后处理，待当前操作结束后再执行；若此时 PD 元数据中已重新建立该图，则保留该图。 +实际关闭图失败时仍会记录异常，并需要显式重试。 通过预检且未启用 PD 时，reload 会重扫启动图配置目录中的所有当前文件，即使 `graph.load_from_local_config=false`。 启用 PD 且该选项为 `false` 时，只恢复之前成功加载且配置文件仍存在的本地图，不加载新增本地文件；设为 `true` 时还会发现新增本地文件。 @@ -499,7 +501,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/manage 200 ``` -HTTP 400 表示配置了鉴权器、图/Schema 缓存通知 RPC 服务已注册、目录扫描失败，或图重载未完整完成。HTTP 200 表示允许执行的图重载步骤未汇报失败。 +HTTP 400 表示配置了鉴权器、图/Schema 缓存通知 RPC 服务已注册、重叠的 reload/图移除请求、目录扫描失败，或图重载未完整完成。 +HTTP 200 表示允许执行的图重载步骤未汇报失败。 ##### Response Body diff --git a/content/cn/docs/clients/restful-api/task.md b/content/cn/docs/clients/restful-api/task.md index c0d180524..43295f156 100644 --- a/content/cn/docs/clients/restful-api/task.md +++ b/content/cn/docs/clients/restful-api/task.md @@ -93,7 +93,11 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2 使用本地调度器时，`SUCCESS` 状态可能先于完成回调保存结果结束而可见。 删除会等待最多 `task.wait_timeout` 秒，直到执行及其回调结束，再检查存储状态并移除记录。 超时或中断会保留任务记录及仍活跃的执行对象，供重试；即使 `force=true`，执行对象仍活跃时也不会移除记录。 -上述等待行为适用于本地调度器。 +上述取消、等待和执行对象保留规则仅适用于本地调度器。 + +分布式调度器通过任务锁和持久化状态协调删除，`force=true` 不会绕过其他 Server 持有的任务锁。 +成功响应可能只是确认已标记为 `DELETING`、等待后续清理；HTTP 204 不表示执行已结束或任务记录已移除。 +取消或删除请求在持久化期间失败时，需先排除存储故障再重试。 ##### Method & Url diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index acc195ef2..5ebe94dfe 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -422,7 +422,10 @@ Reloads all graphs held by this Server after graph configuration changes. Reload Reload and graph removal are mutually exclusive within each graph manager, including local deletion and remote removal notifications. An overlapping REST request for these operations returns HTTP 400 before scanning configurations or changing graphs. The active operation retains this exclusion until reload finishes closing and reopening graphs, or graph removal ends. -Retry explicitly after it ends, including failure or timeout. Remote removal notifications are not automatically retried. +Retry an overlapping REST request explicitly after the active operation ends, including failure or timeout. +A remote removal notification received during an active operation is deferred and processed after it ends. +If current PD metadata already contains a recreated graph, that graph is retained. +An actual graph-close failure is logged and still requires an explicit retry. Without PD, a reload that passes preflight rescans all current files in the startup graph configuration directory, even when `graph.load_from_local_config=false`. With PD and `false`, reload restores only local graphs previously loaded successfully @@ -490,8 +493,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/manage 200 ``` -HTTP 400 indicates a configured authenticator, registered graph/schema cache-notification RPC services, a directory scan failure, -or an incomplete graph reload. +HTTP 400 indicates a configured authenticator, registered graph/schema cache-notification RPC services, +an overlapping reload/removal request, a directory scan failure, or an incomplete graph reload. HTTP 200 means the permitted graph reload phases reported no failure. ##### Response Body diff --git a/content/en/docs/clients/restful-api/task.md b/content/en/docs/clients/restful-api/task.md index 80140a595..2770c2ffe 100644 --- a/content/en/docs/clients/restful-api/task.md +++ b/content/en/docs/clients/restful-api/task.md @@ -94,7 +94,11 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2 For the local scheduler, a `SUCCESS` status can become visible before the completion callback finishes saving the result. Deletion waits up to `task.wait_timeout` seconds for execution and its callback to finish, then checks the stored status before removing the record. Timeout or interruption retains the task record and any active execution owner for retry. Even with `force=true`, the record is not removed -while its execution owner is active. This waiting behavior applies to local schedulers. +while its execution owner is active. These cancellation, waiting and execution-owner retention rules apply only to local schedulers. + +Distributed schedulers coordinate deletion through task locks and persistent state. `force=true` does not bypass a lock held by another Server. +A successful response can acknowledge a `DELETING` record awaiting cleanup; HTTP 204 does not prove that execution has stopped or the record is gone. +If a cancellation or deletion request fails during persistence, correct the storage failure before retrying. ##### Method & Url From 0e7bc7c8fdf1d3466e5567678d8013f619037d9a Mon Sep 17 00:00:00 2001 From: imbajin Date: Mon, 12 Oct 2026 20:51:29 +0800 Subject: [PATCH 06/11] docs: clarify graph deletion maintenance - require quiesced writes during deletion and retries - retain failed owners only for cleanup recovery - explain partial deletion and closed task admission --- content/cn/docs/clients/restful-api/graphs.md | 7 +++++-- content/en/docs/clients/restful-api/graphs.md | 7 ++++++- 2 files changed, 11 insertions(+), 3 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 625c0cbc0..5325cff59 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -240,12 +240,15 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx 启用鉴权时需要图空间管理权限（`space`）。 +删图前先停止业务写入，并在失败及重试期间持续隔离该图、保持停写。删除接口不隔离其他请求中的图写事务。 +调度器开始关闭后会拒绝新任务；删除失败不会自动重新开放已关闭的任务准入。 + 启用 PD 时，`DEFAULT` 中已成功加载的本地图会拒绝公开删除，不受 `graph.load_from_local_config` 影响；设为 `true` 时，还保护成功扫描到的全部配置名， 包括本地加载失败后由 PD 元数据恢复的同名图。先移除文件，再执行 reload，目录扫描成功即在分离图之前解除保护；后续阶段返回 HTTP 400 也不回滚该快照。 也可重启 Server。其他图空间的同名图不受此本地文件保护。 -移除图时捕获到 `close()` 异常，若图已标记关闭，会记录异常并移除运行时绑定；若图仍未关闭，则保留注册供重试。 -后端数据或 PD 元数据可能已被移除，重试不会恢复这些数据。 +移除图时捕获到 `close()` 异常，若图已标记关闭，会记录异常并移除运行时绑定；若图仍未关闭，则只保留注册供继续清理和重试，不表示可以恢复业务使用。 +后端数据或 PD 元数据可能已被移除。删图不是事务操作，重试不会回滚删除，也不会恢复已移除的后端数据或 PD 元数据。 ##### Params diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 5ebe94dfe..ce4ec6f79 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -215,13 +215,18 @@ Create a graph (set `Content-Type: application/json`) Graph-space management permission (`space`) is required when authentication is enabled. +Stop application writes before deleting a graph and keep it isolated with writes stopped throughout failures and retries. +The delete operation does not fence graph write transactions across requests. +Once scheduler shutdown has closed task admission, a failed deletion does not automatically reopen it. + With PD, public deletion in `DEFAULT` returns HTTP 400 for successfully loaded local graphs regardless of `graph.load_from_local_config`, and, with `true`, for every configuration name from a successful directory scan, including metadata fallback after local loading fails. Remove the file and run reload: a successful directory scan releases the protection before detachment, even if later reload phases return HTTP 400. Restarting Server is another option. This protection does not apply to a graph with the same name in another graph space. When graph removal catches an exception from `close()`, it logs the failure and removes runtime bindings if the graph is already marked closed. -If the graph is still open, its registration is retained for retry. Backend data or PD metadata may already have been removed; retry does not restore it. +If the graph is still open, its registration is retained only for cleanup and retry; it does not mean that normal application use can resume. +Backend data or PD metadata may already have been removed. Deletion is not transactional; retry does not roll back deletion or restore removed data or metadata. ##### Params From 856dd8a99463abaaab0074cfc3dd84681498c06c Mon Sep 17 00:00:00 2001 From: imbajin Date: Mon, 12 Oct 2026 23:09:46 +0800 Subject: [PATCH 07/11] docs: clarify graph lifecycle retry boundaries - describe local publication and notification coordination - retain quota and local configuration protection rules - prohibit same-name recreation during failed cleanup - document explicit recovery after replacement failures --- content/cn/docs/clients/restful-api/graphs.md | 21 ++++++++++++--- content/en/docs/clients/restful-api/graphs.md | 27 +++++++++++++++---- 2 files changed, 39 insertions(+), 9 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 5325cff59..be5e6edd2 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -240,7 +240,9 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx 启用鉴权时需要图空间管理权限（`space`）。 -删图前先停止业务写入，并在失败及重试期间持续隔离该图、保持停写。删除接口不隔离其他请求中的图写事务。 +删图前先停止业务写入，并在失败及重试期间持续隔离该图、保持停写。 +删除失败的清理和重试完成前，所有 Server 都不得在该图空间中重建同名图。 +首轮清空后端失败时，重试会再次清空后端，可能删除其他 Server 随后写入的新数据。删除接口不隔离其他请求中的图写事务。 调度器开始关闭后会拒绝新任务；删除失败不会自动重新开放已关闭的任务准入。 启用 PD 时，`DEFAULT` 中已成功加载的本地图会拒绝公开删除，不受 `graph.load_from_local_config` 影响；设为 `true` 时，还保护成功扫描到的全部配置名， @@ -445,9 +447,20 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default 在图配置变更后，重新加载此 Server 持有的所有图。Reload 保留后端数据和本地配置文件。 -每个图管理器中的 reload 与图移除互斥，包括本地图删除和远端移除通知。重叠的此类 REST 请求会在扫描配置或改动图之前返回 HTTP 400。 -当前操作持续占用该互斥入口，直到 reload 完成图的关闭与重开，或图移除结束。操作结束后，包括失败或超时，需显式重试被拒绝的 REST 请求。 -操作执行期间收到的远端移除通知会延后处理，待当前操作结束后再执行；若此时 PD 元数据中已重新建立该图，则保留该图。 +每个图管理器中的 reload、图移除、图空间清空和移除，以及 API 建图和克隆共用生命周期协调入口。 +启用 PD 时，缓存未命中的图加载从读取元数据到注册本地实例也使用该入口；已缓存图的读取不受其阻塞。 +这不会隔离所有 HTTP 请求或图事务；远端图新增与移除通知也使用同一入口。 +重叠的 reload 或图移除 REST 请求会在扫描配置或改动图之前返回 HTTP 400。 +当前操作持续占用该入口直到结束，包括 reload 完整的关闭与重开过程。操作结束后，包括失败或超时，需显式重试被拒绝的 REST 请求。 +操作执行期间收到的远端图新增与移除通知会延后处理，待当前操作结束后按当前 PD 配置协调。 +对于从 PD 加载且不受 `DEFAULT` 本地配置保护的图， +仅在本地实例的创建信息和打开图时使用的配置仍与当前 PD 记录一致时保留该实例。 +若二者不同，Server 关闭旧实例并按当前 PD 配置重新加载；图仍在 PD 中登记时，不回收其图空间配额。 +受 `DEFAULT` 本地配置保护的图仍沿用下文的本地保护规则。 +若创建信息和打开配置完全相同，包括复用了旧创建时间，Server 无法可靠区分旧实例和重新创建的同名图。 +维护期间须持续停写，再显式 reload 或重启 Server 并确认实际加载的是预期图。 +若替换图的加载或启动失败，当前 Server 可能暂时缺少该图；须持续停写，排除故障后显式 reload 或重启 Server 恢复。 +下文的 reload 预检限制同样适用；这些步骤不是分布式事务。 实际关闭图失败时仍会记录异常，并需要显式重试。 通过预检且未启用 PD 时，reload 会重扫启动图配置目录中的所有当前文件，即使 `graph.load_from_local_config=false`。 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index ce4ec6f79..e0ecc3ace 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -216,6 +216,8 @@ Create a graph (set `Content-Type: application/json`) Graph-space management permission (`space`) is required when authentication is enabled. Stop application writes before deleting a graph and keep it isolated with writes stopped throughout failures and retries. +Do not recreate a same-named graph in that graph space on any Server until failed deletion cleanup and retries finish. +If the initial backend clear fails, retry clears it again and may erase new data written by another Server. The delete operation does not fence graph write transactions across requests. Once scheduler shutdown has closed task admission, a failed deletion does not automatically reopen it. @@ -424,12 +426,27 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default Reloads all graphs held by this Server after graph configuration changes. Reload preserves backend data and local configuration files. -Reload and graph removal are mutually exclusive within each graph manager, including local deletion and remote removal notifications. -An overlapping REST request for these operations returns HTTP 400 before scanning configurations or changing graphs. -The active operation retains this exclusion until reload finishes closing and reopening graphs, or graph removal ends. +Within each graph manager, reload, graph removal, graph-space clearing or removal, and API graph creation +and cloning share lifecycle coordination. With PD, a graph lookup that misses the cache holds the same +coordination from reading metadata until registering the local instance. Cached graph reads are outside +it; this is not a barrier for all HTTP requests or graph transactions. +Remote graph-addition and removal notifications use the same lifecycle coordination. +An overlapping REST request for reload or graph removal returns HTTP 400 before scanning configurations or changing graphs. +The active operation holds this coordination until it completes, including the full close-and-reopen sequence of reload. Retry an overlapping REST request explicitly after the active operation ends, including failure or timeout. -A remote removal notification received during an active operation is deferred and processed after it ends. -If current PD metadata already contains a recreated graph, that graph is retained. +Remote graph-addition and removal notifications received during an active operation are deferred +and processed afterward using current PD configuration. For a graph loaded from PD that is not protected +by a local configuration in `DEFAULT`, the local instance is retained only when its creation details +and opening configuration still match the current PD record. If they differ, Server closes the old +instance and reloads the current PD configuration, preserving its graph-space quota while the graph +remains registered in PD. Graphs protected by local configuration in `DEFAULT` keep the local protection +rules described below. +If creation details and opening configuration are identical, including a reused creation time, Server +cannot reliably distinguish an old instance from a recreated graph with the same name. Keep writes +stopped during maintenance, then explicitly reload or restart Server and verify the intended graph. +If replacement loading or startup fails, the graph may temporarily be absent from this Server. Keep writes +stopped and, after fixing the cause, explicitly reload or restart Server to restore it. The reload +restrictions below still apply; this process is not a distributed transaction. An actual graph-close failure is logged and still requires an explicit retry. Without PD, a reload that passes preflight rescans all current files in the startup graph configuration directory, From 879fcd2542937878e01fd8b7ce3ed378e085aed7 Mon Sep 17 00:00:00 2001 From: imbajin Date: Mon, 12 Oct 2026 23:27:11 +0800 Subject: [PATCH 08/11] docs: explain startup lifecycle waiting - describe waiting behind an active lifecycle operation - state the wait has no configured timeout - distinguish interruption and immediate API rejection --- content/cn/docs/clients/restful-api/graphs.md | 2 ++ content/en/docs/clients/restful-api/graphs.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index be5e6edd2..14b844fc2 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -450,6 +450,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default 每个图管理器中的 reload、图移除、图空间清空和移除，以及 API 建图和克隆共用生命周期协调入口。 启用 PD 时，缓存未命中的图加载从读取元数据到注册本地实例也使用该入口；已缓存图的读取不受其阻塞。 这不会隔离所有 HTTP 请求或图事务；远端图新增与移除通知也使用同一入口。 +启动时加载本地图配置会等待当前生命周期操作结束，没有可配置的等待超时；中断等待会中止启动。 +重叠的生命周期 API 请求仍会立即拒绝。 重叠的 reload 或图移除 REST 请求会在扫描配置或改动图之前返回 HTTP 400。 当前操作持续占用该入口直到结束，包括 reload 完整的关闭与重开过程。操作结束后，包括失败或超时，需显式重试被拒绝的 REST 请求。 操作执行期间收到的远端图新增与移除通知会延后处理，待当前操作结束后按当前 PD 配置协调。 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index e0ecc3ace..830679f08 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -430,6 +430,8 @@ Within each graph manager, reload, graph removal, graph-space clearing or remova and cloning share lifecycle coordination. With PD, a graph lookup that misses the cache holds the same coordination from reading metadata until registering the local instance. Cached graph reads are outside it; this is not a barrier for all HTTP requests or graph transactions. +Local startup configuration loading waits for an active lifecycle operation without a configured timeout; +interrupting that wait aborts startup. Overlapping API requests still fail immediately. Remote graph-addition and removal notifications use the same lifecycle coordination. An overlapping REST request for reload or graph removal returns HTTP 400 before scanning configurations or changing graphs. The active operation holds this coordination until it completes, including the full close-and-reopen sequence of reload. From 99a3fa3ae8efce32a0fb9ceb0268c8034afe5389 Mon Sep 17 00:00:00 2001 From: imbajin Date: Mon, 12 Oct 2026 23:37:55 +0800 Subject: [PATCH 09/11] docs: require config removal before restart - make file removal mandatory for reload and restart - explain retained files restore deletion protection - preserve the DEFAULT graph-space protection scope --- content/cn/docs/clients/restful-api/graphs.md | 5 +++-- content/en/docs/clients/restful-api/graphs.md | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 14b844fc2..018f7e567 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -246,8 +246,9 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx 调度器开始关闭后会拒绝新任务；删除失败不会自动重新开放已关闭的任务准入。 启用 PD 时，`DEFAULT` 中已成功加载的本地图会拒绝公开删除，不受 `graph.load_from_local_config` 影响；设为 `true` 时，还保护成功扫描到的全部配置名， -包括本地加载失败后由 PD 元数据恢复的同名图。先移除文件，再执行 reload，目录扫描成功即在分离图之前解除保护；后续阶段返回 HTTP 400 也不回滚该快照。 -也可重启 Server。其他图空间的同名图不受此本地文件保护。 +包括本地加载失败后由 PD 元数据恢复的同名图。无论执行 reload 还是重启 Server，都必须先移除对应本地配置文件。 +执行 reload 时，目录扫描成功即在分离图之前解除保护；后续阶段返回 HTTP 400 也不回滚该快照。 +保留文件会在启动时重新建立删除保护。其他图空间的同名图不受此本地文件保护。 移除图时捕获到 `close()` 异常，若图已标记关闭，会记录异常并移除运行时绑定；若图仍未关闭，则只保留注册供继续清理和重试，不表示可以恢复业务使用。 后端数据或 PD 元数据可能已被移除。删图不是事务操作，重试不会回滚删除，也不会恢复已移除的后端数据或 PD 元数据。 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 830679f08..6e31ad80f 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -223,8 +223,9 @@ Once scheduler shutdown has closed task admission, a failed deletion does not au With PD, public deletion in `DEFAULT` returns HTTP 400 for successfully loaded local graphs regardless of `graph.load_from_local_config`, and, with `true`, for every configuration name from a successful directory scan, including metadata fallback after local loading fails. -Remove the file and run reload: a successful directory scan releases the protection before detachment, even if later reload phases return HTTP 400. -Restarting Server is another option. This protection does not apply to a graph with the same name in another graph space. +Remove the corresponding local configuration file before either reload or restarting Server. +On reload, a successful directory scan releases the protection before detachment, even if later phases return HTTP 400. +Keeping the file allows startup to restore deletion protection. This protection does not apply to a graph with the same name in another graph space. When graph removal catches an exception from `close()`, it logs the failure and removes runtime bindings if the graph is already marked closed. If the graph is still open, its registration is retained only for cleanup and retry; it does not mean that normal application use can resume. From f7480259cebb2d4a895adaf2853354155b93f432 Mon Sep 17 00:00:00 2001 From: imbajin Date: Tue, 13 Oct 2026 06:35:02 +0800 Subject: [PATCH 10/11] docs: align graph maintenance scope - describe local task drain and manual maintenance - require restart for configuration changes - clarify uncertain cleanup and reload data risk - preserve existing Go schema routing guidance --- content/cn/docs/clients/restful-api/graphs.md | 67 +++---------- content/cn/docs/clients/restful-api/task.md | 11 +-- .../cn/docs/config/config-backend-hstore.md | 2 +- content/cn/docs/config/config-guide.md | 29 ++---- content/cn/docs/config/config-option.md | 2 +- content/cn/docs/guides/faq.md | 16 +--- .../quickstart/hugegraph/hugegraph-server.md | 15 +-- content/en/docs/clients/restful-api/graphs.md | 95 +++---------------- content/en/docs/clients/restful-api/task.md | 13 +-- .../en/docs/config/config-backend-hstore.md | 2 +- content/en/docs/config/config-guide.md | 48 ++-------- content/en/docs/config/config-option.md | 2 +- content/en/docs/guides/faq.md | 26 +---- .../quickstart/hugegraph/hugegraph-server.md | 22 +---- 14 files changed, 55 insertions(+), 295 deletions(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 018f7e567..28198e29e 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -240,18 +240,16 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx 启用鉴权时需要图空间管理权限（`space`）。 -删图前先停止业务写入，并在失败及重试期间持续隔离该图、保持停写。 -删除失败的清理和重试完成前，所有 Server 都不得在该图空间中重建同名图。 -首轮清空后端失败时，重试会再次清空后端，可能删除其他 Server 随后写入的新数据。删除接口不隔离其他请求中的图写事务。 -调度器开始关闭后会拒绝新任务；删除失败不会自动重新开放已关闭的任务准入。 +删图前停止所有使用该图的 Server 的写入和任务，并在失败及重试期间持续保持停止状态。 +所有 Server 上的删除完成且经确认前，不得重建同名图。通知送达不构成集群范围的屏障。 -启用 PD 时，`DEFAULT` 中已成功加载的本地图会拒绝公开删除，不受 `graph.load_from_local_config` 影响；设为 `true` 时，还保护成功扫描到的全部配置名， -包括本地加载失败后由 PD 元数据恢复的同名图。无论执行 reload 还是重启 Server，都必须先移除对应本地配置文件。 -执行 reload 时，目录扫描成功即在分离图之前解除保护；后续阶段返回 HTTP 400 也不回滚该快照。 -保留文件会在启动时重新建立删除保护。其他图空间的同名图不受此本地文件保护。 +执行删除的 Server 会关闭新任务准入，并等待实际执行、取消回调和事务清理结束。 +配置的任务等待超时（`task.wait_timeout`，单位秒）时，会在移除数据、配置或元数据前拒绝删除；待执行对象退出后再重试。 +仅关闭调度器时，尚未开始的持久化任务仍保留在存储中。 -移除图时捕获到 `close()` 异常，若图已标记关闭，会记录异常并移除运行时绑定；若图仍未关闭，则只保留注册供继续清理和重试，不表示可以恢复业务使用。 -后端数据或 PD 元数据可能已被移除。删图不是事务操作，重试不会回滚删除，也不会恢复已移除的后端数据或 PD 元数据。 +删图不是事务操作，破坏性清理后的失败不会恢复已移除的数据或元数据。执行对象或原生资源的清理结果不确定时需要人工检查， +不能强制移除调度器，也不能仅凭任务 Future 已完成就恢复写入。 +若因本地配置保护而拒绝删除，先移除对应配置文件并重启 Server，再重试。 ##### Params @@ -446,49 +444,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default #### 6.1.10 重新加载图空间中的图 -在图配置变更后，重新加载此 Server 持有的所有图。Reload 保留后端数据和本地配置文件。 - -每个图管理器中的 reload、图移除、图空间清空和移除，以及 API 建图和克隆共用生命周期协调入口。 -启用 PD 时，缓存未命中的图加载从读取元数据到注册本地实例也使用该入口；已缓存图的读取不受其阻塞。 -这不会隔离所有 HTTP 请求或图事务；远端图新增与移除通知也使用同一入口。 -启动时加载本地图配置会等待当前生命周期操作结束，没有可配置的等待超时；中断等待会中止启动。 -重叠的生命周期 API 请求仍会立即拒绝。 -重叠的 reload 或图移除 REST 请求会在扫描配置或改动图之前返回 HTTP 400。 -当前操作持续占用该入口直到结束，包括 reload 完整的关闭与重开过程。操作结束后，包括失败或超时，需显式重试被拒绝的 REST 请求。 -操作执行期间收到的远端图新增与移除通知会延后处理，待当前操作结束后按当前 PD 配置协调。 -对于从 PD 加载且不受 `DEFAULT` 本地配置保护的图， -仅在本地实例的创建信息和打开图时使用的配置仍与当前 PD 记录一致时保留该实例。 -若二者不同，Server 关闭旧实例并按当前 PD 配置重新加载；图仍在 PD 中登记时，不回收其图空间配额。 -受 `DEFAULT` 本地配置保护的图仍沿用下文的本地保护规则。 -若创建信息和打开配置完全相同，包括复用了旧创建时间，Server 无法可靠区分旧实例和重新创建的同名图。 -维护期间须持续停写，再显式 reload 或重启 Server 并确认实际加载的是预期图。 -若替换图的加载或启动失败，当前 Server 可能暂时缺少该图；须持续停写，排除故障后显式 reload 或重启 Server 恢复。 -下文的 reload 预检限制同样适用；这些步骤不是分布式事务。 -实际关闭图失败时仍会记录异常，并需要显式重试。 - -通过预检且未启用 PD 时，reload 会重扫启动图配置目录中的所有当前文件，即使 `graph.load_from_local_config=false`。 -启用 PD 且该选项为 `false` 时，只恢复之前成功加载且配置文件仍存在的本地图，不加载新增本地文件；设为 `true` 时还会发现新增本地文件。 -先加载本地配置，再从 PD 元数据加载尚未恢复的图。新加载的图在启用 RPC 时先等待就绪，再完成启动和任务调度初始化，然后恢复 Gremlin 图与遍历绑定。 - -目录扫描成功后，会在关闭图之前更新本地来源记录；启用 PD 时，也会更新本地图删除保护。扫描失败时会在关闭任何图之前返回 HTTP 400，保留现有图和保护状态。 -启用 PD 时，`DEFAULT` 中已成功加载的本地图在配置文件仍存在时会拒绝公开删除，不受 `graph.load_from_local_config` 影响，无论删除是否要求清空数据。 -其他图空间的同名图不受该本地文件保护。启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，即使本地加载失败后由 PD 元数据恢复同名图也受保护。 -启用 PD 且设为 `false` 时，从未加载的新增本地文件仍被忽略，也不会建立删除保护。移除配置文件后，reload 中的目录扫描成功即在分离图之前清除对应来源和保护。 -后续打开或启动失败、整个 reload 返回 HTTP 400，也不会回滚已成功扫描的快照。旧实例成功关闭并分离后，若 PD 元数据中仍有该图，则可恢复并公开删除； -否则移除其运行时注册，但保留后端数据。关闭尝试后图仍未关闭时，保留旧注册供显式重试。 -图已标记关闭后捕获到关闭异常时，会记录异常并移除运行时绑定。本地启动来源已移除，下次重启不会再从已删除的文件加载该图。 -来源记录跟随实际注册的图实例；旧实例移除不会清除新的本地替代实例。公开删除 `DEFAULT` 中的图时，仅在删除完成后清除对应的来源记录。 -未启用 PD 时，公开删除图仍会清空数据并移除本地配置，上述 PD 删除保护不适用。 - -配置了 `auth.authenticator` 时，请求会在关闭任何图之前返回 HTTP 400，因为鉴权服务保留了图引用。此类部署需要重启 Server 应用图配置变化， -被拒绝的 reload 不会改动原有图、数据或配置。 - -关闭尝试后仍未关闭的图会保留注册，供显式重试；重载启动失败后，清理时仍未关闭的对象也会保留。其他可恢复的图可能先完成重载，再汇报打开或启动失败。不完整的 reload 会返回 HTTP 400， -部分图恢复成功不能作为整个请求成功的依据。排除故障后重试。 - -受管理的图已注册图/Schema 缓存通知 RPC 服务时，reload 同样会在关闭任何图之前返回 HTTP 400。这些服务的安全重绑尚未实现，需要重启 Server -应用变化；该拒绝会保留原有图、数据和配置。此类热重载需要在 Linux 高性能机器的分布式部署中完成修复与验证后再使用。 -未触发上述预检限制时，PD/本地配置的来源选择规则仍然适用，但不代表完整的分布式热重载支持。 +图配置变化通过重启 Server 应用。热重载恢复尚未实现，不要使用此接口进行配置维护。 +当前未启用 PD 的执行路径中，reload 会调用删图流程，可能清空后端数据。重启完成并确认加载了预期图之前，持续停止写入和任务。 +下方请求及响应仅说明 API 格式，不代表维护或恢复保障。 ##### Params @@ -520,9 +478,6 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/manage 200 ``` -HTTP 400 表示配置了鉴权器、图/Schema 缓存通知 RPC 服务已注册、重叠的 reload/图移除请求、目录扫描失败，或图重载未完整完成。 -HTTP 200 表示允许执行的图重载步骤未汇报失败。 - ##### Response Body ```javascript diff --git a/content/cn/docs/clients/restful-api/task.md b/content/cn/docs/clients/restful-api/task.md index 43295f156..8badafd9c 100644 --- a/content/cn/docs/clients/restful-api/task.md +++ b/content/cn/docs/clients/restful-api/task.md @@ -88,16 +88,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2 ##### Params -- force: 是否允许删除未完成任务的信息，默认为 false。本地任务未完成且仍在运行时会请求取消；该参数不会跳过下述执行等待。 +- force: 任务仍在运行时是否强制删除，默认为 false -使用本地调度器时，`SUCCESS` 状态可能先于完成回调保存结果结束而可见。 -删除会等待最多 `task.wait_timeout` 秒，直到执行及其回调结束，再检查存储状态并移除记录。 -超时或中断会保留任务记录及仍活跃的执行对象，供重试；即使 `force=true`，执行对象仍活跃时也不会移除记录。 -上述取消、等待和执行对象保留规则仅适用于本地调度器。 - -分布式调度器通过任务锁和持久化状态协调删除，`force=true` 不会绕过其他 Server 持有的任务锁。 -成功响应可能只是确认已标记为 `DELETING`、等待后续清理；HTTP 204 不表示执行已结束或任务记录已移除。 -取消或删除请求在持久化期间失败时，需先排除存储故障再重试。 +任务记录删除与删图是不同操作。图维护须遵守[图 API](/cn/docs/clients/restful-api/graphs/)中的停写和任务清理要求。 ##### Method & Url diff --git a/content/cn/docs/config/config-backend-hstore.md b/content/cn/docs/config/config-backend-hstore.md index bb4574940..541ddb37f 100644 --- a/content/cn/docs/config/config-backend-hstore.md +++ b/content/cn/docs/config/config-backend-hstore.md @@ -143,7 +143,7 @@ PD 对该值的处理方式： | usePD | rest-server.properties | false | Server 启动时是否从 PD 加载元数据 | `ServerOptions.java:401-407` | | cluster | rest-server.properties | hg-test | 集群名，作为所有 PD 元数据 key 的前缀 | `ServerOptions.java:187-193` | | init_store.enabled | rest-server.properties | true | PD/Store 部署下应设为 `false`，元数据已由存储侧负责 | `ServerOptions.java:382-390` | -| graph.load_from_local_config | rest-server.properties | false | 控制构造阶段预加载。未启用 PD 时，通过预检的 reload 会重扫配置；启用 PD 时恢复文件仍存在的已成功加载本地图，`true` 还会发现新增配置。应用初始化仍扫描并尝试加载本地配置，`false` 不会阻止本地加载。 | `ServerOptions.java:366-372` | +| graph.load_from_local_config | rest-server.properties | false | 控制构造阶段预加载。应用初始化仍扫描并尝试加载本地配置，`false` 不会阻止本地加载。图配置变化通过重启 Server 应用。 | `ServerOptions.java:366-372` | | auth.graph_store | rest-server.properties | hugegraph | 保存权限数据的图，关闭 init-store 时会校验它使用 `hstore` 后端 | `ServerOptions.java:602-609` | | graphspace | {graph}.properties | DEFAULT | PD 看到的图名的第一段 | `CoreOptions.java:679-685` | diff --git a/content/cn/docs/config/config-guide.md b/content/cn/docs/config/config-guide.md index ac995d97f..01c3dba6d 100644 --- a/content/cn/docs/config/config-guide.md +++ b/content/cn/docs/config/config-guide.md @@ -25,13 +25,13 @@ HugeGraphServer 内部集成了 GremlinServer 和 RestServer，而 gremlin-serve > 本页的认证配置属于 HugeGraph Server。生产环境必须按 [Server 认证与授权配置](/cn/docs/config/config-authentication/)启用 Auth、配置 IP 白名单和最小权限，并保留、保护 Server `audit-*.log`。示例中注释掉的认证配置表示默认未启用。 发行包把默认配置放在安装目录的 `conf/` 下；这些文件来自 Server 仓库的静态发行素材，构建时随包复制。未在配置文件中出现的选项采用代码定义的默认值；配置文件显式写入的值会覆盖该默认值。 -默认发行配置的文件布局和设置按固定 Server 主线 `2f827d6` 核对；实际使用的发布包应以其自身版本对应的配置文件和入口脚本为准。 +本页的默认文件行为按固定 Server 主线 `2f827d6` 核对；实际使用的发布包应以其自身版本对应的配置文件和入口脚本为准。 | 文件 | 来源和用途 | 装载行为 | |------|------------|----------| | `conf/gremlin-server.yaml` | 随发行包提供；配置 Gremlin Server。 | `start-hugegraph.sh` 将它作为 Server 启动参数传入。 | | `conf/rest-server.properties` | 按固定 Server 主线构建时随发行包提供；配置 REST Server、PD、认证等。 | 启动脚本和 Server 进程读取；对应主线构建的容器入口脚本也会在启动前更新其中受支持的选项。 | -| `conf/graphs/hugegraph.properties` | 随发行包提供的默认图配置，使用 RocksDB。 | `init-store.sh` 和 Server 应用初始化都会扫描该目录；初始化阶段会尝试加载其中的图配置。`graph.load_from_local_config` 默认 `false`，控制管理器构造阶段预加载；通过预检且未启用 PD 时 reload 会本地重扫；启用 PD 时恢复已成功加载且文件仍存在的本地图，`true` 还会发现新增本地文件。 | +| `conf/graphs/hugegraph.properties` | 随发行包提供的默认图配置，使用 RocksDB。 | `init-store.sh` 和 Server 应用初始化都会扫描该目录；初始化阶段会尝试加载其中的图配置。`graph.load_from_local_config` 默认 `false`，控制管理器构造阶段预加载。 | | `conf/graphs/hstore.properties.template` | 随发行包提供的 HStore 模板；其他图配置由用户按需创建。 | HStore 镜像在构建时把模板改名为 `hugegraph.properties`；裸发行包用户可复制模板并修改。 | 完整的默认文件见Server 主线源码：[gremlin-server.yaml](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/gremlin-server.yaml)、[rest-server.properties](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/rest-server.properties)、[hugegraph.properties](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/graphs/hugegraph.properties) 和 [hstore.properties.template](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/graphs/hstore.properties.template)。 @@ -53,8 +53,7 @@ graphs: {} ssl: { enabled: false } ``` -通常只需关注 `channelizer`、`host` 和 `port`。图不在 Gremlin Server 的 `graphs` 段加载；REST 侧管理器会在 Server 应用初始化时扫描 `graphs` 目录并尝试载入本地图配置。`graph.load_from_local_config` -控制管理器构造阶段的预加载；默认 `false` 不会关闭应用初始化阶段的本地加载。通过预检且未启用 PD 时，reload 会重扫该目录。启用 PD 时，会恢复已成功加载且文件仍存在的本地图；`true` 还会发现新增本地文件。本地配置先于 PD 元数据加载。 +通常只需关注 `channelizer`、`host` 和 `port`。图不在 Gremlin Server 的 `graphs` 段加载；REST 侧管理器会在 Server 应用初始化时扫描 `graphs` 目录并尝试载入本地图配置。`graph.load_from_local_config` 控制管理器构造阶段的预加载；默认 `false` 不会关闭应用初始化阶段的本地加载。 - channelizer：默认的 `WsAndHttpChannelizer` 同时支持 WebSocket 和 HTTP。Gremlin-Console 使用 WebSocket，HugeGraph-Client、Loader 和 Hubble 使用 HTTP； @@ -67,8 +66,7 @@ ssl: { enabled: false } ### 3 rest-server.properties -下面是可用的 `rest-server.properties` 示例。主线模板未写出 `graph.load_from_local_config`，源码默认值为 `false`。示例中设为 `true` 是可选的：它开启管理器构造阶段预加载，以及启用 PD 时 reload 对新增本地文件的发现；设为 -`false` 时仍会恢复已成功加载且文件仍存在的本地图；通过预检且未启用 PD 时 reload 总会本地重扫，不受该选项限制。Server 应用初始化阶段仍会扫描并尝试加载本地图配置。 +下面是可用的 `rest-server.properties` 示例。主线模板未写出 `graph.load_from_local_config`，源码默认值为 `false`。示例中设为 `true` 是可选的：它开启管理器构造阶段预加载；Server 应用初始化阶段仍会扫描并尝试加载本地图配置。 ```properties # bind url @@ -112,21 +110,7 @@ memory_monitor.period=2000 - restserver.url：RestServer 提供服务的 url，根据实际环境修改。如果其他 IP 地址无法访问，可以尝试修改为特定的地址；或修改为 `http://0.0.0.0` 来监听来自任何 IP 地址的请求，这种方案较为便捷，但需要留意服务可被访问的网络范围； - graphs：图配置文件所在目录，默认值是 `./conf/graphs`。`init-store.sh` 会扫描该目录；Server 应用初始化也会扫描并尝试加载其中的 properties 文件； -- graph.load_from_local_config：是否在管理器构造阶段预加载本地图配置，源码默认值为 `false`。通过预检且未启用 PD 时，reload 会重扫启动图配置目录。启用 PD 时，会恢复已成功加载且文件仍存在的本地图；`true` 还会发现新增本地文件。本地配置先于 PD - 元数据加载。它不会禁止 Server 应用初始化阶段的本地加载，也不是安全隔离开关； - -目录扫描成功后，reload 会更新本地来源记录；启用 PD 时，也会更新本地图删除保护。 -启用 PD 时，`DEFAULT` 中已成功加载的本地图在配置文件仍存在时会拒绝公开删除，不受该选项影响，无论是否清空数据。 -启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，包括本地加载失败后由 PD 元数据恢复的同名图。 -其他图空间的同名图不受此本地文件保护；启用 PD 且设为 `false` 时，从未加载的新增本地文件仍被忽略，不会建立删除保护。 -移除本地文件后，reload 中的目录扫描成功即在分离图之前清除对应来源和保护；后续阶段失败、整个请求返回 HTTP 400，也不会回滚该扫描快照。 -旧实例成功关闭并分离后，图可改由 PD 元数据恢复；否则移除运行时注册，但保留后端数据。关闭尝试后图仍未关闭时，保留旧注册供显式重试。 -图已标记关闭后捕获到关闭异常时，会记录异常并移除运行时绑定。 -扫描失败会保留现有图和保护状态。未启用 PD 时，公开删除图仍会清空数据并移除本地配置。详细行为见下方图管理 API。 -每个图管理器同一时间只执行一个 reload。重叠请求会在扫描配置或关闭图之前返回 HTTP 400；当前请求结束后可重试，无论该请求成功还是失败。 - -配置了 `auth.authenticator` 时，reload 会在关闭任何图之前以 HTTP 400 拒绝请求，需要重启 Server 应用图配置变化。失败与恢复行为详见[图管理 API](/cn/docs/clients/restful-api/graphs/)。 -图/Schema 缓存通知 RPC 服务已注册时，reload 同样会在关闭任何图之前返回 HTTP 400，应改用重启 Server。服务的安全重绑尚未实现，需要在 Linux 高性能机器的分布式部署中修复并验证。 +- graph.load_from_local_config：默认 `false`，控制构造阶段预加载；不会禁止 Server 应用初始化阶段的本地加载，也不是安全隔离开关。图配置变化通过重启 Server 应用。 > 当前上游模板中的 Arthas 键仍写作 `arthas.telnet_port`、`arthas.http_port` 和 `arthas.disabled_commands`，但 `ServerOptions` 读取的是下方示例中的 camelCase 名称。自定义配置应使用 `arthas.telnetPort`、`arthas.httpPort` 和 `arthas.disabledCommands`。 @@ -161,8 +145,7 @@ store=hugegraph **[可选]：修改 rest-server.properties** -通过修改 `rest-server.properties` 中的 `graphs` 配置项来设置图的配置文件目录。默认配置为 `graphs=./conf/graphs`；需要其他目录时调整 `graphs`。下面将 `graph.load_from_local_config` 设为 -`true`，作为管理器构造阶段预加载的可选设置。启用 PD 时，它也会让 reload 发现新增本地文件；`false` 仍会恢复已成功加载且文件仍存在的本地图。通过预检且未启用 PD 时，reload 会重扫该目录。应用初始化仍会读取该目录中的本地图配置： +通过修改 `rest-server.properties` 中的 `graphs` 配置项来设置图的配置文件目录。默认配置为 `graphs=./conf/graphs`；需要其他目录时调整 `graphs`。下面将 `graph.load_from_local_config` 设为 `true`，作为管理器构造阶段预加载的可选设置；应用初始化仍会读取该目录中的本地图配置： ```properties graphs=./conf/graphs diff --git a/content/cn/docs/config/config-option.md b/content/cn/docs/config/config-option.md index 9c28af51c..0249fe498 100644 --- a/content/cn/docs/config/config-option.md +++ b/content/cn/docs/config/config-option.md @@ -36,7 +36,7 @@ search_boost: 1.5 | config option | default value | description | |----------------------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | graphs | ./conf/graphs | 图配置 properties 文件所在目录。 | -| graph.load_from_local_config | false | 控制构造阶段预加载。未启用 PD 时，通过预检的 reload 会重扫配置；启用 PD 时恢复文件仍存在的已成功加载本地图，`true` 还会发现新增配置。应用初始化仍扫描并尝试加载本地配置，`false` 不会阻止本地加载。 | +| graph.load_from_local_config | false | 控制构造阶段预加载。应用初始化仍扫描并尝试加载本地配置，`false` 不会阻止本地加载。图配置变化通过重启 Server 应用。 | | graphs.enable_dynamic_create_drop | true | Whether to enable create or drop graph dynamically. | | init_store.enabled | true | Whether init-store initializes the local backend stores and the built-in admin account. Set false in distributed deployments (PD/HStore) where the storage side already owns the metadata. | | server.id | 空字符串 | The optional legacy id of hugegraph-server. | diff --git a/content/cn/docs/guides/faq.md b/content/cn/docs/guides/faq.md index 9c304fc29..cd003085a 100644 --- a/content/cn/docs/guides/faq.md +++ b/content/cn/docs/guides/faq.md @@ -34,20 +34,8 @@ weight: 6 - 配置了两个图，名字是`hugegraph`和`hugegraph1`，而启动服务的命令是`start-hugegraph.sh`，是只打开了`hugegraph`这个图吗 - 脚本名称与图名无关。Server 默认从 `conf/graphs` 扫描并加载本地图配置，目录可在 `conf/rest-server.properties` 的 `graphs` 配置项中修改。`graph.load_from_local_config` 的默认值是 - `false`，控制图管理器构造阶段的预加载，不能用于禁止启动时加载。通过预检且未启用 PD 时，reload 会重扫启动配置目录。启用 PD 时，会恢复已成功加载且配置文件仍存在的本地图；设为 `true` 时还会发现新增本地文件。本地配置优先于 PD 元数据。配置了 - `auth.authenticator` 的部署会在关闭任何图之前以 HTTP 400 拒绝 reload，需要重启 Server 应用配置变化；需要加载多个本地图时，为每个图准备独立配置文件。详见[服务端配置说明](/cn/docs/config/config-guide/)。 - - 启用 PD 时，`DEFAULT` 中已成功加载的本地图在配置文件仍存在时会拒绝公开删除，不受该选项影响；其他图空间的同名图不受此保护。 - 启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，即使本地加载失败后由 PD 元数据恢复同名图也受保护。 - 启用 PD 且设为 `false` 时，从未加载的新增本地文件仍被忽略，也不会建立删除保护。 - 移除本地文件后，reload 中的目录扫描成功即在分离图之前解除保护；后续阶段失败、整个请求返回 HTTP 400，也不会回滚该扫描快照。 - 旧实例成功关闭并分离后，图可改由 PD 元数据恢复；否则移除运行时注册，保留后端数据。关闭尝试后图仍未关闭时，保留旧注册供显式重试。 - 图已标记关闭后捕获到关闭异常时，会记录异常并移除运行时绑定。 - 扫描失败会保留现有图和保护状态。未启用 PD 时，公开删除图仍会清空数据并移除本地配置。 - 每个图管理器同一时间只执行一个 reload。重叠请求会在扫描配置或关闭图之前返回 HTTP 400；当前请求结束后可重试，无论该请求成功还是失败。 - - 图/Schema 缓存通知 RPC 服务已注册时，reload 也会在关闭任何图之前返回 HTTP 400，应改用重启 Server。服务的安全重绑尚未实现，Linux 高性能机器上的修复与验证要求见[图管理 API](/cn/docs/clients/restful-api/graphs/)。 + 脚本名称与图名无关。Server 默认从 `conf/graphs` 扫描并加载本地图配置，目录可在 `conf/rest-server.properties` 的 `graphs` 配置项中修改。`graph.load_from_local_config` 默认 + `false`，控制构造阶段预加载，不能用于禁止启动时加载。每个本地图使用独立配置文件，配置变化后重启 Server。详见[服务端配置说明](/cn/docs/config/config-guide/)。 - 服务启动成功后，使用`curl`查询所有顶点时返回乱码 diff --git a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md index c7cf163fb..66ee2330a 100644 --- a/content/cn/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/cn/docs/quickstart/hugegraph/hugegraph-server.md @@ -221,20 +221,7 @@ mvn package -DskipTests -ntp -Drocksdb-only Server 的 tar 包随包提供 `conf/rest-server.properties`、`conf/gremlin-server.yaml` 和 `conf/graphs/hugegraph.properties`；源码构建包从 `hugegraph-server/hugegraph-dist/src/assembly/static/conf/` 装配这些文件。解压后在 Server 安装目录内编辑配置，无需另行生成。发行包版本之间可能有默认值差异，下面涉及的默认值和启动行为按 `master` 主线说明。 -单机 RocksDB 快速上手只需确认 `conf/graphs/hugegraph.properties` 使用 `backend=rocksdb`、`serializer=binary`。正常 Server 初始化会扫描 `conf/graphs/` 并加载本地图配置，无需额外设置 -`graph.load_from_local_config=true`。该选项默认值为 `false`，控制构造阶段的提前加载。通过预检且未启用 PD 时，reload 会重扫启动图配置目录。启用 PD 时，会恢复已成功加载且文件仍存在的本地图；`true` 还会发现新增本地文件。本地配置优先于 PD -元数据。配置了 `auth.authenticator` 时，reload 会在关闭图之前返回 HTTP 400，需要重启 Server 应用配置变化。重载行为详见[图管理 API](/cn/docs/clients/restful-api/graphs/)。 - -启用 PD 时，`DEFAULT` 中已成功加载的本地图在配置文件仍存在时会拒绝公开删除，不受该选项影响；其他图空间的同名图不受此保护。 -启用 PD 且设为 `true` 时，保护还覆盖成功扫描到的全部配置名，即使本地加载失败后由 PD 元数据恢复同名图也受保护。 -启用 PD 且设为 `false` 时，从未加载的新增本地文件仍被忽略，也不会建立删除保护。 -移除本地文件后，reload 中的目录扫描成功即在分离图之前解除保护；后续阶段失败、整个请求返回 HTTP 400，也不会回滚该扫描快照。 -旧实例成功关闭并分离后，图可改由 PD 元数据恢复；否则移除运行时注册，保留后端数据。关闭尝试后图仍未关闭时，保留旧注册供显式重试。 -图已标记关闭后捕获到关闭异常时，会记录异常并移除运行时绑定。 -扫描失败会保留现有图和保护状态。未启用 PD 时，公开删除图仍会清空数据并移除本地配置。 -每个图管理器同一时间只执行一个 reload。重叠请求会在扫描配置或关闭图之前返回 HTTP 400；当前请求结束后可重试，无论该请求成功还是失败。 - -图/Schema 缓存通知 RPC 服务已注册时，reload 也会在关闭任何图之前返回 HTTP 400，应改用重启 Server。服务的安全重绑尚未实现，Linux 高性能机器上的修复与验证要求见图管理 API。 +单机 RocksDB 快速上手只需确认 `conf/graphs/hugegraph.properties` 使用 `backend=rocksdb`、`serializer=binary`。正常 Server 初始化会扫描 `conf/graphs/` 并加载本地图配置，无需额外设置 `graph.load_from_local_config=true`。该选项默认 `false`，控制构造阶段的提前加载。图配置变化通过重启 Server 应用，不使用热重载进行维护。 详细的配置介绍请参考[配置文档](/docs/config/config-guide)及[配置项介绍](/docs/config/config-option)。 diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index 6e31ad80f..af8c93de9 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -215,21 +215,17 @@ Create a graph (set `Content-Type: application/json`) Graph-space management permission (`space`) is required when authentication is enabled. -Stop application writes before deleting a graph and keep it isolated with writes stopped throughout failures and retries. -Do not recreate a same-named graph in that graph space on any Server until failed deletion cleanup and retries finish. -If the initial backend clear fails, retry clears it again and may erase new data written by another Server. -The delete operation does not fence graph write transactions across requests. -Once scheduler shutdown has closed task admission, a failed deletion does not automatically reopen it. - -With PD, public deletion in `DEFAULT` returns HTTP 400 for successfully loaded local graphs regardless of `graph.load_from_local_config`, -and, with `true`, for every configuration name from a successful directory scan, including metadata fallback after local loading fails. -Remove the corresponding local configuration file before either reload or restarting Server. -On reload, a successful directory scan releases the protection before detachment, even if later phases return HTTP 400. -Keeping the file allows startup to restore deletion protection. This protection does not apply to a graph with the same name in another graph space. - -When graph removal catches an exception from `close()`, it logs the failure and removes runtime bindings if the graph is already marked closed. -If the graph is still open, its registration is retained only for cleanup and retry; it does not mean that normal application use can resume. -Backend data or PD metadata may already have been removed. Deletion is not transactional; retry does not roll back deletion or restore removed data or metadata. +Stop writes and tasks on every Server that uses the graph before deletion, and keep them stopped during failures and retries. +Do not recreate the same graph name until deletion has completed and been confirmed on every Server. Notifications are not a cluster-wide barrier. + +On the deleting Server, scheduler shutdown fences new task admission and waits for actual executions, cancellation callbacks and transaction cleanup. +If the configured task-drain wait times out (`task.wait_timeout`, seconds), deletion is refused before data, configuration or metadata removal; retry after +the owners exit. +Closing the scheduler alone retains persistent work that has not started. + +Deletion is not transactional. A failure after destructive cleanup does not restore removed data or metadata. An uncertain owner or native-resource cleanup +needs manual inspection; do not force-remove the scheduler or resume writes just because a task Future is done. +If deletion is refused because the graph uses local configuration, remove its configuration file and restart Server before retrying. ##### Params @@ -425,68 +421,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default #### 6.1.10 Reload the graphs of the graphspace -Reloads all graphs held by this Server after graph configuration changes. Reload preserves backend data and local configuration files. - -Within each graph manager, reload, graph removal, graph-space clearing or removal, and API graph creation -and cloning share lifecycle coordination. With PD, a graph lookup that misses the cache holds the same -coordination from reading metadata until registering the local instance. Cached graph reads are outside -it; this is not a barrier for all HTTP requests or graph transactions. -Local startup configuration loading waits for an active lifecycle operation without a configured timeout; -interrupting that wait aborts startup. Overlapping API requests still fail immediately. -Remote graph-addition and removal notifications use the same lifecycle coordination. -An overlapping REST request for reload or graph removal returns HTTP 400 before scanning configurations or changing graphs. -The active operation holds this coordination until it completes, including the full close-and-reopen sequence of reload. -Retry an overlapping REST request explicitly after the active operation ends, including failure or timeout. -Remote graph-addition and removal notifications received during an active operation are deferred -and processed afterward using current PD configuration. For a graph loaded from PD that is not protected -by a local configuration in `DEFAULT`, the local instance is retained only when its creation details -and opening configuration still match the current PD record. If they differ, Server closes the old -instance and reloads the current PD configuration, preserving its graph-space quota while the graph -remains registered in PD. Graphs protected by local configuration in `DEFAULT` keep the local protection -rules described below. -If creation details and opening configuration are identical, including a reused creation time, Server -cannot reliably distinguish an old instance from a recreated graph with the same name. Keep writes -stopped during maintenance, then explicitly reload or restart Server and verify the intended graph. -If replacement loading or startup fails, the graph may temporarily be absent from this Server. Keep writes -stopped and, after fixing the cause, explicitly reload or restart Server to restore it. The reload -restrictions below still apply; this process is not a distributed transaction. -An actual graph-close failure is logged and still requires an explicit retry. - -Without PD, a reload that passes preflight rescans all current files in the startup graph configuration directory, -even when `graph.load_from_local_config=false`. With PD and `false`, reload restores only local graphs previously loaded successfully -whose configuration files still exist; it ignores new local files. Setting the flag to `true` also discovers new local files. -Local configurations are loaded first, then PD metadata is used for graphs not already restored locally. -Newly loaded graphs wait for readiness when RPC is enabled, complete startup and task scheduling initialization, -then restore their Gremlin graph/traversal bindings. - -A successful directory scan updates local-source tracking before graphs are closed; with PD, it also updates local graph deletion protection. -A scan failure returns HTTP 400 before closing any graph and preserves existing graphs and protection. -With PD, local graphs successfully loaded in `DEFAULT` reject public deletion while their configuration files remain, -regardless of `graph.load_from_local_config` and whether deletion requests data clearing. A graph with the same name in another graph space -is not protected by that local file. With PD and `true`, protection also covers all configuration names from a successful scan, even if local loading fails -and PD metadata restores a graph with that name. With PD and `false`, a new local file that has never been loaded remains ignored and unprotected. -Remove the configuration file: a successful directory scan during reload clears its local-source tracking and deletion protection before detachment. -Later opening or startup failures do not roll back that scan snapshot, even when the whole reload returns HTTP 400. -After the old instance closes and detaches, PD metadata may restore the graph for public deletion; otherwise its runtime registration is removed -while backend data remains. If closing leaves the graph open, the old registration is retained for an explicit retry. -A caught close exception after the graph is marked closed is logged and its runtime bindings are removed. -This removes the local startup source, so a subsequent restart will not reload it from that deleted file. -Source tracking follows the registered graph instance: removal of an old instance does not discard a newer local replacement. -For public deletion in `DEFAULT`, the corresponding local-source tracking is cleared only after deletion completes. -Without PD, public graph deletion still clears data and removes its local configuration; the PD protection rule does not apply. - -A configured `auth.authenticator` causes HTTP 400 before any graph is closed, because authentication services retain graph references. -Restart Server to apply graph configuration changes in that deployment; the rejected reload leaves the original graphs, data and configuration intact. - -Graphs still open after a close attempt remain registered for an explicit retry, including objects not closed during cleanup after a reload startup failure. -Other recoverable graphs may reload before an opening or startup failure is reported. -An incomplete reload returns HTTP 400; successful recovery of some graphs does not make the whole reload successful. -Correct the failure and retry. - -Reload also returns HTTP 400 before closing any graph when graph/schema cache-notification RPC services are registered for a managed graph. -Safe rebinding of those services remains unimplemented, so restart Server to apply changes; this rejection preserves the original graphs, data and -configuration. Repair and validate that hot-reload lifecycle on a high-performance Linux distributed deployment before relying on it. -The PD/local-config rules above apply when these preflight restrictions are absent; they do not establish full distributed reload support. +Apply graph configuration changes by restarting Server. Hot-reload recovery is deferred; do not use this endpoint for configuration maintenance. +In the current non-PD path, reload invokes graph deletion and can clear backend data. Keep writes and tasks stopped until Server has restarted and the +intended graphs have been verified. The request and response below document the API shape, not a maintenance or recovery guarantee. ##### Params @@ -518,10 +455,6 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/manage 200 ``` -HTTP 400 indicates a configured authenticator, registered graph/schema cache-notification RPC services, -an overlapping reload/removal request, a directory scan failure, or an incomplete graph reload. -HTTP 200 means the permitted graph reload phases reported no failure. - ##### Response Body ```javascript diff --git a/content/en/docs/clients/restful-api/task.md b/content/en/docs/clients/restful-api/task.md index 2770c2ffe..4e6a70594 100644 --- a/content/en/docs/clients/restful-api/task.md +++ b/content/en/docs/clients/restful-api/task.md @@ -88,17 +88,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2 ##### Params -- force: allows deletion of incomplete task information, default is false. For local tasks, it requests cancellation of an incomplete running task; - it does not bypass the execution wait below. +- force: whether to delete the task even when it is still running, default is false -For the local scheduler, a `SUCCESS` status can become visible before the completion callback finishes saving the result. -Deletion waits up to `task.wait_timeout` seconds for execution and its callback to finish, then checks the stored status before removing the record. -Timeout or interruption retains the task record and any active execution owner for retry. Even with `force=true`, the record is not removed -while its execution owner is active. These cancellation, waiting and execution-owner retention rules apply only to local schedulers. - -Distributed schedulers coordinate deletion through task locks and persistent state. `force=true` does not bypass a lock held by another Server. -A successful response can acknowledge a `DELETING` record awaiting cleanup; HTTP 204 does not prove that execution has stopped or the record is gone. -If a cancellation or deletion request fails during persistence, correct the storage failure before retrying. +Task-record deletion is separate from graph deletion. For graph maintenance, follow the stop-write and task-drain requirements in the [graph +API](/docs/clients/restful-api/graphs/). ##### Method & Url diff --git a/content/en/docs/config/config-backend-hstore.md b/content/en/docs/config/config-backend-hstore.md index e30d07eb6..c4f21d2d0 100644 --- a/content/en/docs/config/config-backend-hstore.md +++ b/content/en/docs/config/config-backend-hstore.md @@ -168,7 +168,7 @@ in the checked Server master commit `2f827d6` where the option is declared. | usePD | rest-server.properties | false | Whether Server loads its metadata from PD at startup | `ServerOptions.java:401-407` | | cluster | rest-server.properties | hg-test | Cluster name used as the prefix of every PD metadata key | `ServerOptions.java:187-193` | | init_store.enabled | rest-server.properties | true | Set it to `false` in a PD/Store deployment, where the storage side already owns the metadata | `ServerOptions.java:382-390` | -| graph.load_from_local_config | rest-server.properties | false | Controls constructor preloading. Without PD, reloads that pass preflight rescan configurations. With PD, reload restores successfully loaded local sources whose files remain; `true` also discovers new files. Application initialization still scans and attempts to load local configurations, so `false` does not block local loading. | `ServerOptions.java:366-372` | +| graph.load_from_local_config | rest-server.properties | false | Controls constructor preloading. Application initialization still scans and attempts to load local configurations, so `false` does not block local loading. Restart Server to apply graph configuration changes. | `ServerOptions.java:366-372` | | auth.graph_store | rest-server.properties | hugegraph | The graph that holds auth data, checked against the `hstore` backend when init-store is off | `ServerOptions.java:602-609` | | graphspace | {graph}.properties | DEFAULT | First segment of the graph name PD sees | `CoreOptions.java:679-685` | diff --git a/content/en/docs/config/config-guide.md b/content/en/docs/config/config-guide.md index 52ed77d44..32aadcb96 100644 --- a/content/en/docs/config/config-guide.md +++ b/content/en/docs/config/config-guide.md @@ -25,14 +25,13 @@ The following sections describe these files. > The authentication settings on this page apply to HugeGraph Server. In production, enable [authentication and authorization](/docs/config/config-authentication/), maintain an IP allowlist, grant minimum permissions, and retain and protect Server `audit-*.log` files. Commented authentication settings in the examples indicate that authentication is disabled by default. The distribution copies default files from the Server repository into the installation directory's `conf/` folder. Options absent from these files use source-code defaults; explicit file settings override those defaults. -The default distribution file layout and settings were checked against Server master commit `2f827d6`. Use the configuration files and entry scripts that -correspond to your installed release. +The file-loading behavior on this page was checked against Server master commit `2f827d6`. Use the configuration files and entry scripts that correspond to your installed release. | File | Source and purpose | Loading behavior | |------|------------|----------| | `conf/gremlin-server.yaml` | Shipped with the distribution; configures Gremlin Server. | Passed to Server by `start-hugegraph.sh`. | | `conf/rest-server.properties` | Shipped when building the checked Server master; configures REST Server, PD, authentication, and related settings. | Read by startup scripts and Server; the corresponding container entrypoint also updates supported settings before startup. | -| `conf/graphs/hugegraph.properties` | Shipped default graph configuration, using RocksDB. | Scanned by both `init-store.sh` and application initialization, which attempts to load local graphs. `graph.load_from_local_config` defaults to `false` and controls constructor preloading. After preflight, reload rescans locally without PD. With PD, it restores local graphs previously loaded successfully whose files still exist; `true` also discovers new local files. | +| `conf/graphs/hugegraph.properties` | Shipped default graph configuration, using RocksDB. | Scanned by both `init-store.sh` and application initialization, which attempts to load local graphs. `graph.load_from_local_config` defaults to `false` and controls constructor preloading. Restart Server to apply graph configuration changes. | | `conf/graphs/hstore.properties.template` | Shipped HStore template; users create other graph configurations as needed. | The HStore image renames it to `hugegraph.properties` during its build; distribution users can copy and customize it. | Complete defaults are in Server master: [gremlin-server.yaml](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/gremlin-server.yaml), [rest-server.properties](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/rest-server.properties), [hugegraph.properties](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/graphs/hugegraph.properties), and [hstore.properties.template](https://github.com/apache/hugegraph/blob/master/hugegraph-server/hugegraph-dist/src/assembly/static/conf/graphs/hstore.properties.template). @@ -54,11 +53,7 @@ graphs: {} ssl: { enabled: false } ``` -Usually, focus on `channelizer`, `host`, and `port`. Graphs are not loaded from the Gremlin Server `graphs` section. During application initialization, the -REST-side manager scans the `graphs` directory and attempts to load local graph configurations. `graph.load_from_local_config` controls constructor -preloading; its default `false` does not disable local loading during application initialization. Without PD, a reload that passes preflight rescans this -directory. With PD, it restores local graphs previously loaded successfully whose files still exist; `true` also discovers new local files. Local -configurations are loaded before PD metadata. +Usually, focus on `channelizer`, `host`, and `port`. Graphs are not loaded from the Gremlin Server `graphs` section. During application initialization, the REST-side manager scans the `graphs` directory and attempts to load local graph configurations. `graph.load_from_local_config` controls constructor preloading; its default `false` does not disable local loading during application initialization. - `channelizer`: The default `WsAndHttpChannelizer` supports WebSocket and HTTP. Gremlin Console uses WebSocket; HugeGraph Client, Loader, and Hubble use HTTP. @@ -71,10 +66,7 @@ Set the matching `gremlinserver.url=http://host:port` in `rest-server.properties ### 3 rest-server.properties -The following example lists `rest-server.properties` options. The master template omits `graph.load_from_local_config`, whose source-code default is -`false`. Setting it to `true` is optional: it enables constructor preloading and discovery of new local files on reload when PD is enabled. With PD and -`false`, reload still restores local graphs previously loaded successfully whose files still exist. A reload that passes preflight without PD always -rescans locally, regardless of this flag. Application initialization still scans and attempts to load local graph configurations. +The following example lists `rest-server.properties` options. The master template omits `graph.load_from_local_config`, whose source-code default is `false`. Setting it to `true` is optional: it enables constructor preloading. Application initialization still scans and attempts to load local graph configurations. ```properties # bind url @@ -118,31 +110,8 @@ memory_monitor.period=2000 - `restserver.url`: The REST listener URL. Use a specific address for remote access, or `http://0.0.0.0` to listen on every interface while restricting the accessible network. - `graphs`: The graph configuration directory, defaulting to `./conf/graphs`. Both `init-store.sh` and application initialization scan it; initialization attempts to load its properties files. -- `graph.load_from_local_config`: Controls constructor preloading, with source-code default `false`. Without PD, a reload that passes preflight rescans the - startup graph directory. With PD, it restores local graphs previously loaded successfully whose files still exist; `true` also discovers new local files. - Local configurations are loaded before PD metadata. It does not block local loading during application initialization and is not a security isolation - switch. - -A successful reload scan updates local-source tracking; with PD, it also updates local graph deletion protection. -With PD, local graphs successfully loaded in `DEFAULT` reject public deletion while their configuration files remain, regardless of the flag. -With PD and `true`, protection also covers all configuration names from a successful scan, including a graph restored from PD metadata after local loading -fails. -This applies with or without data clearing; a graph with the same name in another graph space is not protected by the local file. -With PD and `false`, a new local file that has never been loaded remains ignored and does not create deletion protection. -After a local file is removed, a successful directory scan during reload clears that source and protection before detachment. -Later reload failures do not roll back this snapshot, even if the request returns HTTP 400. After the old instance closes and detaches, -PD metadata may restore it; otherwise its runtime registration is removed while backend data remains. If closing leaves the graph open, the old -registration is retained for an explicit retry. -A caught close exception after the graph is marked closed is logged and its runtime bindings are removed. A scan failure preserves existing graphs and -protection. -Without PD, public graph deletion still clears data and removes its local configuration. See the graph API below for details. -Only one reload runs at a time per graph manager. Overlapping requests return HTTP 400 before scanning configurations or closing graphs; -retry after the active request finishes, whether it succeeds or fails. - -Reload is rejected with HTTP 400 before any graph is closed when `auth.authenticator` is configured. Restart Server to apply graph configuration changes in that -deployment. See the [graph API](/docs/clients/restful-api/graphs/) for reload failure and recovery behavior. -Registered graph/schema cache-notification RPC services also make reload return HTTP 400 before closing any graph; use Server restart. -Their safe rebinding remains unimplemented and requires repair and validation on a high-performance Linux distributed deployment. +- `graph.load_from_local_config`: Controls constructor preloading, with source-code default `false`. It does not block local loading during application + initialization and is not a security isolation switch. Restart Server to apply graph configuration changes. > The upstream template still uses `arthas.telnet_port`, `arthas.http_port`, and `arthas.disabled_commands`, but `ServerOptions` reads the camelCase names in the example. Use `arthas.telnetPort`, `arthas.httpPort`, and `arthas.disabledCommands` in custom configurations. @@ -177,10 +146,7 @@ A Server can load multiple graphs, each with its own properties file. This examp **[Optional]: Modify rest-server.properties** -Set the graph configuration directory with `graphs` in `rest-server.properties`, defaulting to `graphs=./conf/graphs`. Adjust it for another directory. The -example optionally enables constructor preloading with `graph.load_from_local_config=true`. With PD, the flag also enables discovery of new local files on -reload; `false` still restores local graphs previously loaded successfully whose files still exist. Without PD, a reload that passes preflight rescans this -directory. Application initialization still reads local graph configurations from it: +Set the graph configuration directory with `graphs` in `rest-server.properties`, defaulting to `graphs=./conf/graphs`. Adjust it for another directory. The example optionally enables constructor preloading with `graph.load_from_local_config=true`; application initialization still reads local graph configurations from this directory: ```properties graphs=./conf/graphs diff --git a/content/en/docs/config/config-option.md b/content/en/docs/config/config-option.md index 7f2d2738f..9b855cff2 100644 --- a/content/en/docs/config/config-option.md +++ b/content/en/docs/config/config-option.md @@ -36,7 +36,7 @@ Corresponding configuration file `rest-server.properties` | config option | default value | description | |----------------------------------------|--------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | graphs | ./conf/graphs | Directory containing graph configuration properties files. | -| graph.load_from_local_config | false | Controls constructor preloading. Without PD, reloads that pass preflight rescan configurations. With PD, reload restores successfully loaded local sources whose files remain; `true` also discovers new files. Application initialization still scans and attempts to load local configurations, so `false` does not block local loading. | +| graph.load_from_local_config | false | Controls constructor preloading. Application initialization still scans and attempts to load local configurations, so `false` does not block local loading. Restart Server to apply graph configuration changes. | | graphs.enable_dynamic_create_drop | true | Whether to enable create or drop graph dynamically. | | init_store.enabled | true | Whether init-store initializes the local backend stores and the built-in admin account. Set false in distributed deployments (PD/HStore) where the storage side already owns the metadata. | | server.id | Empty string | The optional legacy id of hugegraph-server. | diff --git a/content/en/docs/guides/faq.md b/content/en/docs/guides/faq.md index 388af8237..7f1a00afd 100644 --- a/content/en/docs/guides/faq.md +++ b/content/en/docs/guides/faq.md @@ -34,28 +34,10 @@ weight: 6 - Two graphs are configured, the names are `hugegraph` and `hugegraph1`, and the command to start the service is `start-hugegraph.sh`. Is only the hugegraph graph opened? - The script name is unrelated to the graph name. Server scans and loads local graph configurations from `conf/graphs` by default; change the directory - with `graphs` in `conf/rest-server.properties`. `graph.load_from_local_config` defaults to `false` and controls constructor preloading, not whether - startup loads local graphs. Without PD, a reload that passes preflight rescans the startup configuration directory. With PD, it restores local graphs - previously loaded successfully whose configuration files still exist; setting the flag to `true` also discovers new local files. Local configurations - take precedence over PD metadata. A configured `auth.authenticator` rejects reload with HTTP 400 before closing any graph; restart Server to apply - configuration changes in that deployment. Give each local graph its own configuration file. See the [Server configuration - guide](/docs/config/config-guide/). - - With PD, local graphs successfully loaded in `DEFAULT` reject public deletion while their configuration files remain, regardless of this flag. - With PD and `true`, protection also covers every name in a successful directory scan, even if local loading fails and PD metadata restores that graph. - With PD and `false`, never-loaded new files remain ignored and unprotected. - Other graph spaces are outside this protection. Remove the file; a successful directory scan during reload releases its protection before detachment. - Later reload failures do not roll back that scan snapshot, even when the request returns HTTP 400. - After the old instance closes and detaches, PD metadata may restore it; otherwise its runtime registration is removed while backend data remains. - If closing leaves the graph open, the old registration is retained for an explicit retry. - A caught close exception after the graph is marked closed is logged and its runtime bindings are removed. - A scan failure preserves existing graphs and protection. Without PD, public graph deletion still clears data and removes its local configuration. - Only one reload runs at a time per graph manager. Overlapping requests return HTTP 400 before scanning configurations or closing graphs; - retry after the active request finishes, whether it succeeds or fails. - - Registered graph/schema cache-notification RPC services also cause reload to return HTTP 400 before closing any graph. Restart Server instead; - safe service rebinding remains unimplemented. See the [graph API](/docs/clients/restful-api/graphs/) for the Linux repair and validation requirement. + The script name is unrelated to the graph name. Server scans and loads local graph configurations from `conf/graphs` by default; change the directory with + `graphs` in `conf/rest-server.properties`. `graph.load_from_local_config` defaults to `false` and controls constructor preloading, not whether startup loads + local graphs. Give each local graph its own configuration file and restart Server after changing it. See the [Server configuration guide](/docs/config/config- + guide/). - After the service starts successfully, garbled characters are returned when using `curl` to query all vertices diff --git a/content/en/docs/quickstart/hugegraph/hugegraph-server.md b/content/en/docs/quickstart/hugegraph/hugegraph-server.md index 5e65d2e8a..bd5b4329b 100644 --- a/content/en/docs/quickstart/hugegraph/hugegraph-server.md +++ b/content/en/docs/quickstart/hugegraph/hugegraph-server.md @@ -226,27 +226,7 @@ mvn package -DskipTests -ntp -Drocksdb-only Server archives include `conf/rest-server.properties`, `conf/gremlin-server.yaml`, and `conf/graphs/hugegraph.properties`; source builds assemble them from `hugegraph-server/hugegraph-dist/src/assembly/static/conf/`. Edit them inside the extracted Server directory without a separate generation step. Defaults vary by release; the following defaults and startup behavior describe master. -For standalone RocksDB, confirm `backend=rocksdb` and `serializer=binary` in `conf/graphs/hugegraph.properties`. Normal Server initialization scans -`conf/graphs/` and loads local graphs without requiring `graph.load_from_local_config=true`. This option defaults to `false` and controls constructor -preloading. Without PD, a reload that passes preflight rescans the startup graph directory. With PD, it restores local graphs previously loaded -successfully whose files still exist; `true` also discovers new local files. Local configurations take precedence over PD metadata. If `auth.authenticator` -is configured, reload returns HTTP 400 before closing graphs; restart Server to apply configuration changes. See the [graph -API](/docs/clients/restful-api/graphs/) for reload behavior. - -With PD, local graphs successfully loaded in `DEFAULT` reject public deletion while their configuration files remain, regardless of this flag. -With PD and `true`, protection also covers every name in a successful directory scan, even if local loading fails and PD metadata restores that graph. -With PD and `false`, never-loaded new files remain ignored and unprotected. -Other graph spaces are outside this protection. Remove the file; a successful directory scan during reload releases its protection before detachment. -Later reload failures do not roll back that scan snapshot, even when the request returns HTTP 400. -After the old instance closes and detaches, PD metadata may restore it; otherwise its runtime registration is removed while backend data remains. -If closing leaves the graph open, the old registration is retained for an explicit retry. -A caught close exception after the graph is marked closed is logged and its runtime bindings are removed. -A scan failure preserves existing graphs and protection. Without PD, public graph deletion still clears data and removes its local configuration. -Only one reload runs at a time per graph manager. Overlapping requests return HTTP 400 before scanning configurations or closing graphs; -retry after the active request finishes, whether it succeeds or fails. - -Registered graph/schema cache-notification RPC services also make reload return HTTP 400 before closing any graph; use Server restart. -Their safe rebinding remains unimplemented; the graph API documents the required repair and validation on a high-performance Linux deployment. +For standalone RocksDB, confirm `backend=rocksdb` and `serializer=binary` in `conf/graphs/hugegraph.properties`. Normal Server initialization scans `conf/graphs/` and loads local graphs without requiring `graph.load_from_local_config=true`. This option defaults to `false` and controls constructor preloading. Restart Server to apply graph configuration changes; do not use hot reload for maintenance. See the [configuration guide](/docs/config/config-guide/) and [option reference](/docs/config/config-option/) for details. From 0919e3c03272deb2bf92731ebe6e098d43e67047 Mon Sep 17 00:00:00 2001 From: imbajin Date: Tue, 13 Oct 2026 11:03:49 +0800 Subject: [PATCH 11/11] docs: clarify graph task admission recovery - retain closed admission after task-drain refusal - wait for all task owners and cancellation cleanup - limit restart recovery to pre-destructive failures --- content/cn/docs/clients/restful-api/graphs.md | 2 ++ content/en/docs/clients/restful-api/graphs.md | 3 ++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md index 28198e29e..23fb4525d 100644 --- a/content/cn/docs/clients/restful-api/graphs.md +++ b/content/cn/docs/clients/restful-api/graphs.md @@ -245,6 +245,8 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx 执行删除的 Server 会关闭新任务准入，并等待实际执行、取消回调和事务清理结束。 配置的任务等待超时（`task.wait_timeout`，单位秒）时，会在移除数据、配置或元数据前拒绝删除；待执行对象退出后再重试。 +因任务未排空而拒绝删除后，任务准入仍保持关闭。若要在破坏性清理前恢复正常用图，保持写入和任务生产者停止， +等待全部已准入任务和取消清理结束后再重启 Server；重启不会恢复已经移除的数据或元数据。 仅关闭调度器时，尚未开始的持久化任务仍保留在存储中。 删图不是事务操作，破坏性清理后的失败不会恢复已移除的数据或元数据。执行对象或原生资源的清理结果不确定时需要人工检查， diff --git a/content/en/docs/clients/restful-api/graphs.md b/content/en/docs/clients/restful-api/graphs.md index af8c93de9..f9c98e385 100644 --- a/content/en/docs/clients/restful-api/graphs.md +++ b/content/en/docs/clients/restful-api/graphs.md @@ -220,7 +220,8 @@ Do not recreate the same graph name until deletion has completed and been confir On the deleting Server, scheduler shutdown fences new task admission and waits for actual executions, cancellation callbacks and transaction cleanup. If the configured task-drain wait times out (`task.wait_timeout`, seconds), deletion is refused before data, configuration or metadata removal; retry after -the owners exit. +the owners exit. Task admission stays closed after this refusal. To resume ordinary graph use before destructive cleanup, keep writes and task producers stopped; +wait for all admitted tasks and cancellation cleanup to finish, then restart Server. A restart does not restore data or metadata already removed. Closing the scheduler alone retains persistent work that has not started. Deletion is not transactional. A failure after destructive cleanup does not restore removed data or metadata. An uncertain owner or native-resource cleanup