docs: clarify graph maintenance and client routing

content/cn/docs/clients/restful-api/graphs.md

@@ -240,6 +240,17 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx
 
 启用鉴权时需要图空间管理权限（`space`）。
 
+删图前停止所有使用该图的 Server 的写入和任务，并在失败及重试期间持续保持停止状态。
+所有 Server 上的删除完成且经确认前，不得重建同名图。通知送达不构成集群范围的屏障。
+
+执行删除的 Server 会关闭新任务准入，并等待实际执行、取消回调和事务清理结束。
+配置的任务等待超时（`task.wait_timeout`，单位秒）时，会在移除数据、配置或元数据前拒绝删除；待执行对象退出后再重试。
+仅关闭调度器时，尚未开始的持久化任务仍保留在存储中。
+
+删图不是事务操作，破坏性清理后的失败不会恢复已移除的数据或元数据。执行对象或原生资源的清理结果不确定时需要人工检查，
+不能强制移除调度器，也不能仅凭任务 Future 已完成就恢复写入。
+若因本地配置保护而拒绝删除，先移除对应配置文件并重启 Server，再重试。
+
 ##### Params
 
 **路径参数说明：**
@@ -433,7 +444,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/default
 
 #### 6.1.10 重新加载图空间中的图
 
-重新加载服务中的图，适用于图配置在服务外部被改动之后。
+图配置变化通过重启 Server 应用。热重载恢复尚未实现，不要使用此接口进行配置维护。
+当前未启用 PD 的执行路径中，reload 会调用删图流程，可能清空后端数据。重启完成并确认加载了预期图之前，持续停止写入和任务。
+下方请求及响应仅说明 API 格式，不代表维护或恢复保障。
 
 ##### Params
 

content/cn/docs/clients/restful-api/task.md

@@ -90,6 +90,8 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2
 
 - force: 任务仍在运行时是否强制删除，默认为 false
 
+任务记录删除与删图是不同操作。图维护须遵守[图 API](/cn/docs/clients/restful-api/graphs/)中的停写和任务清理要求。
+
 ##### Method & Url
 
 ```text

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          | 控制构造阶段预加载。应用初始化仍扫描并尝试加载本地配置，`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`   |
 

content/cn/docs/config/config-guide.md

@@ -31,7 +31,7 @@ HugeGraphServer 内部集成了 GremlinServer 和 RestServer，而 gremlin-serve
 |------|------------|----------|
 | `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`，控制管理器构造阶段预加载。 |
 | `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` 不会关闭应用初始化阶段的本地加载。
 
 - 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` 是可选的：它开启管理器构造阶段预加载；Server 应用初始化阶段仍会扫描并尝试加载本地图配置。
 
 ```properties
 # bind url
@@ -110,7 +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：是否在管理器构造阶段预加载本地图配置，以及在 `reload()` 时重新扫描；源码默认值为 `false`。它不会禁止 Server 应用初始化阶段的本地加载，也不是安全隔离开关；
+- 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`。
 
@@ -145,7 +145,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`，作为管理器构造阶段预加载的可选设置；应用初始化仍会读取该目录中的本地图配置：
 
 ```properties
 graphs=./conf/graphs

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                                            | 控制构造阶段预加载。应用初始化仍扫描并尝试加载本地配置，`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.                                                                                                                                                                   |

content/cn/docs/guides/faq.md

@@ -34,7 +34,8 @@ 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`，控制构造阶段预加载，不能用于禁止启动时加载。每个本地图使用独立配置文件，配置变化后重启 Server。详见[服务端配置说明](/cn/docs/config/config-guide/)。
 
 - 服务启动成功后，使用`curl`查询所有顶点时返回乱码
 

content/cn/docs/quickstart/client/hugegraph-client-go.md

@@ -25,7 +25,9 @@ go get github.com/apache/hugegraph-toolchain/hugegraph-client-go
 
 `NewCommonClient` 要求 `Host` 是 IP 地址，`Port` 在 1 到 65535 之间；客户端始终使用明文 HTTP 连接。未启用认证时，用户名和密码留空；只有两者都设置时才会发送 Basic Auth。
 
-`GraphSpace` 只在 `Vertex` API（此时请求路径为 `/graphspaces/{space}/graphs/{graph}/...`）和 Gremlin 默认 aliases 中生效（空值按 `DEFAULT` 处理）。Schema 相关入口和 `Version()` 始终请求 `/graphs/{graph}/...` 和 `/versions`，与 `GraphSpace` 无关。默认图空间填写 `DEFAULT`；将 `GraphSpace` 留空时，`Vertex` API 会回退到旧版 Server 使用的 `/graphs/{graph}` 路径。
+`GraphSpace` 非空时，`Vertex` 和 Schema API（`Schema()`、`Propertykey`、`VertexLabel`、`EdgeLabel`）使用
+`/graphspaces/{space}/graphs/{graph}/...` 路径；留空时使用旧版 `/graphs/{graph}/...` 路径。默认图空间填写 `DEFAULT`。
+Gremlin 默认 aliases 也使用 `GraphSpace`，空值按 `DEFAULT` 处理。`Version()` 始终请求 `/versions`，不依赖图空间。
 
 ```go
 package main
@@ -70,7 +72,7 @@ func main() {
 |---|---|---|
 | `Host` | `string` | HugeGraph Server 的 IP 地址，不支持主机名 |
 | `Port` | `int` | HugeGraph Server 的 REST 端口，取值 1 到 65535 |
-| `GraphSpace` | `string` | 图空间，仅 `Vertex` API 和 Gremlin 默认 aliases 使用；不需要时填空字符串 |
+| `GraphSpace` | `string` | `Vertex`、Schema API 和 Gremlin 默认 aliases 使用的图空间；默认空间填写 `DEFAULT` |
 | `Graph` | `string` | Server 上配置的图名 |
 | `Username` | `string` | Server 用户名，未启用认证时填空字符串 |
 | `Password` | `string` | Server 密码，未启用认证时填空字符串 |

content/cn/docs/quickstart/hugegraph/hugegraph-server.md

@@ -221,7 +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`，控制构造阶段的提前加载和 `reload()` 时是否重新扫描本地配置。
+单机 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)。
 

content/en/docs/clients/restful-api/graphs.md

@@ -215,6 +215,18 @@ Create a graph (set `Content-Type: application/json`)
 
 Graph-space management permission (`space`) is required when authentication is enabled.
 
+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
 
 **Path parameters**
@@ -409,7 +421,9 @@ 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.
+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
 

content/en/docs/clients/restful-api/task.md

@@ -90,6 +90,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/tasks/2
 
 - force: whether to delete the task even when it is still running, default is false
 
+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
 
 ```text