You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hugegraph.apache.org by ji...@apache.org on 2026/09/26 14:21:09 UTC
(hugegraph-doc) 07/12: docs(cn): correct auth and Gremlin API examples
This is an automated email from the ASF dual-hosted git repository.
imbajin pushed a commit to branch docs/sync-cn-491
in repository https://gitbox.apache.org/repos/asf/hugegraph-doc.git
commit 1bd09ab544f3452881e0607f91149bbf2eb8b599
Author: imbajin <ji...@apache.org>
AuthorDate: Sat Sep 26 21:31:00 2026 +0800
docs(cn): correct auth and Gremlin API examples
---
content/cn/docs/clients/restful-api/auth.md | 119 +++++++++++----------
content/cn/docs/clients/restful-api/graphs.md | 40 +++++--
content/cn/docs/clients/restful-api/graphspace.md | 12 +--
content/cn/docs/clients/restful-api/gremlin.md | 122 ++++++----------------
content/cn/docs/config/config-authentication.md | 25 +++--
content/cn/docs/guides/backup-restore.md | 8 +-
content/cn/docs/guides/custom-plugin.md | 13 ++-
content/cn/docs/guides/faq.md | 2 +-
content/cn/docs/language/hugegraph-example.md | 10 +-
content/cn/docs/language/hugegraph-gremlin.md | 2 +-
10 files changed, 171 insertions(+), 182 deletions(-)
diff --git a/content/cn/docs/clients/restful-api/auth.md b/content/cn/docs/clients/restful-api/auth.md
index 488ba51a4..10becc637 100644
--- a/content/cn/docs/clients/restful-api/auth.md
+++ b/content/cn/docs/clients/restful-api/auth.md
@@ -6,9 +6,11 @@ description: "Authentication（认证鉴权）REST 接口:管理用户、角色
---
> **版本变更说明**:
-> - 1.7.0+: Auth API 路径使用 GraphSpace 格式，如 `/graphspaces/DEFAULT/auth/users`，且 group/target 等 id 格式与 name 一致（如 `admin`）
+> - 1.7.0 及之后：用户、图空间范围内的用户组、资源、关联和赋权等接口使用 `/graphspaces/{graphspace}/auth/...`。登录、登出和 token 校验仍使用顶层 `/auth/login`、`/auth/logout`、`/auth/verify`；图空间默认角色接口位于 `/graphspaces/{graphspace}/role`。源码还保留顶层 `/auth/groups` 接口；本页组接口示例使用图空间范围接口。
> - 1.5.x 及更早: Auth API 路径包含 graph 名称，group/target 等 id 格式类似 `-69:grant`。参考 [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
+下文 `{group_id}`、`{target_id}`、`{another_target_id}`、`{belong_id}` 和 `{access_id}` 均为占位符，使用前须替换为对应响应中的 `id`。将 ID 放入 URL 路径时，还须按 URL 路径组件规则编码。
+
### 10.1 用户认证与权限控制
> 开启权限及相关配置请先参考 [权限配置](/cn/docs/config/config-authentication/) 文档
@@ -27,7 +29,7 @@ city: Beijing})
##### 接口说明：
用户认证与权限控制的核心接口包括 5 类：UserAPI、GroupAPI、TargetAPI、BelongAPI、AccessAPI。除此之外，ManagerAPI 用于授予图空间级别的管理角色，LoginAPI 用于签发和校验 token，ProjectAPI 用于把多个图归为一组从而一次性授权。
-**注意**: 1.5.0 及之前，group/target 等 id 的格式类似 -69:grant，1.7.0 及之后，id 和 name 一致，如 admin [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)
+**注意**：1.5.x 及更早版本的路径和 ID 规则不同，请参阅 [HugeGraph 1.5.x RESTful API](https://github.com/apache/hugegraph-doc/tree/release-1.5.0)。
### 10.2 用户（User）API
用户接口包括：创建用户，删除用户，修改用户，和查询用户相关信息接口。
@@ -254,7 +256,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
##### Params
-- group_name: 用户组名称
+- group_name: 必填的用户组创建字段；持久化名称由服务端生成
- group_description: 用户组描述
##### Request Body
@@ -266,6 +268,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/users/boss/role
}
```
+`group_name` 为必填字段；图空间范围的用户组持久化名称由服务端生成，不能用此字段自定义。请从创建响应中复制 `id`，用于后续关联、授权、查询、更新或删除。
##### Method & Url
@@ -284,10 +287,10 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/groups
```json
{
"group_creator": "admin",
- "group_name": "all",
+ "group_name": "<服务端生成的图空间范围名称>",
"group_create": "2020-11-11 15:46:08.791",
"group_update": "2020-11-11 15:46:08.791",
- "id": "-69:all",
+ "id": "{group_id}",
"group_description": "group can do anything"
}
```
@@ -302,7 +305,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/groups
##### Method & Url
```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:grant
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/groups/{group_id}
```
##### Response Status
@@ -320,14 +323,13 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:grant
##### Method & Url
```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:grant
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/groups/{group_id}
```
##### Request Body
修改 group_description
```json
{
- "group_name": "grant",
"group_description": "grant"
}
```
@@ -343,10 +345,10 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:grant
```json
{
"group_creator": "admin",
- "group_name": "grant",
+ "group_name": "<服务端生成的图空间范围名称>",
"group_create": "2020-11-12 09:50:58.458",
"group_update": "2020-11-12 09:57:58.155",
- "id": "-69:grant",
+ "id": "{group_id}",
"group_description": "grant"
}
```
@@ -376,10 +378,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/groups
"groups": [
{
"group_creator": "admin",
- "group_name": "all",
+ "group_name": "<服务端生成的图空间范围名称>",
"group_create": "2020-11-11 15:46:08.791",
"group_update": "2020-11-11 15:46:08.791",
- "id": "-69:all",
+ "id": "{group_id}",
"group_description": "group can do anything"
}
]
@@ -395,7 +397,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/groups
##### Method & Url
```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:all
+GET http://localhost:8080/graphspaces/DEFAULT/auth/groups/{group_id}
```
##### Response Status
@@ -409,10 +411,10 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/groups/-69:all
```json
{
"group_creator": "admin",
- "group_name": "all",
+ "group_name": "<服务端生成的图空间范围名称>",
"group_create": "2020-11-11 15:46:08.791",
"group_update": "2020-11-11 15:46:08.791",
- "id": "-69:all",
+ "id": "{group_id}",
"group_description": "group can do anything"
}
```
@@ -483,7 +485,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/targets
"properties": null
}
],
- "id": "-77:all",
+ "id": "{target_id}",
"target_update": "2020-11-11 15:32:01.192"
}
```
@@ -498,7 +500,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/targets
##### Method & Url
```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/targets/{target_id}
```
##### Response Status
@@ -517,16 +519,13 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin
##### Method & Url
```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/targets/{target_id}
```
##### Request Body
修改资源定义中的 type
```json
{
- "target_name": "gremlin",
- "target_graph": "hugegraph",
- "target_url": "127.0.0.1:8080",
"target_resources": [
{
"type": "NONE"
@@ -546,7 +545,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin
```json
{
"target_creator": "admin",
- "target_name": "gremlin",
+ "target_name": "all",
"target_url": "127.0.0.1:8080",
"target_graph": "hugegraph",
"target_create": "2020-11-12 09:34:13.848",
@@ -557,7 +556,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:gremlin
"properties": null
}
],
- "id": "-77:gremlin",
+ "id": "{target_id}",
"target_update": "2020-11-12 09:37:12.780"
}
```
@@ -598,7 +597,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets
"properties": null
}
],
- "id": "-77:all",
+ "id": "{target_id}",
"target_update": "2020-11-11 15:32:01.192"
},
{
@@ -614,7 +613,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets
"properties": null
}
],
- "id": "-77:grant",
+ "id": "{another_target_id}",
"target_update": "2020-11-11 15:43:24.841"
}
]
@@ -630,7 +629,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets
##### Method & Url
```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:grant
+GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/{target_id}
```
##### Response Status
@@ -644,19 +643,19 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:grant
```json
{
"target_creator": "admin",
- "target_name": "grant",
+ "target_name": "all",
"target_url": "127.0.0.1:8080",
"target_graph": "hugegraph",
- "target_create": "2020-11-11 15:43:24.841",
+ "target_create": "2020-11-11 15:32:01.192",
"target_resources": [
{
- "type": "GRANT",
+ "type": "ALL",
"label": "*",
"properties": null
}
],
- "id": "-77:grant",
- "target_update": "2020-11-11 15:43:24.841"
+ "id": "{target_id}",
+ "target_update": "2020-11-11 15:32:01.192"
}
```
@@ -677,7 +676,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/targets/-77:grant
```json
{
"user": "boss",
- "group": "-69:all"
+ "group": "{group_id}"
}
```
@@ -701,9 +700,9 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/belongs
"belong_create": "2020-11-11 16:19:35.422",
"belong_creator": "admin",
"belong_update": "2020-11-11 16:19:35.422",
- "id": "Sboss>-82>>S-69:all",
+ "id": "{belong_id}",
"user": "boss",
- "group": "-69:all"
+ "group": "{group_id}"
}
```
@@ -716,7 +715,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/belongs
##### Method & Url
```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:grant
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
```
##### Response Status
@@ -735,7 +734,7 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:gr
##### Method & Url
```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:grant
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
```
##### Request Body
@@ -760,9 +759,9 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:grant
"belong_create": "2020-11-12 10:40:21.720",
"belong_creator": "admin",
"belong_update": "2020-11-12 10:42:47.265",
- "id": "Sboss>-82>>S-69:grant",
+ "id": "{belong_id}",
"user": "boss",
- "group": "-69:grant"
+ "group": "{group_id}"
}
```
@@ -798,9 +797,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs
"belong_create": "2020-11-11 16:19:35.422",
"belong_creator": "admin",
"belong_update": "2020-11-11 16:19:35.422",
- "id": "Sboss>-82>>S-69:all",
+ "id": "{belong_id}",
"user": "boss",
- "group": "-69:all"
+ "group": "{group_id}"
}
]
}
@@ -815,7 +814,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs
##### Method & Url
```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:all
+GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/{belong_id}
```
##### Response Status
@@ -831,9 +830,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/belongs/Sboss>-82>>S-69:all
"belong_create": "2020-11-11 16:19:35.422",
"belong_creator": "admin",
"belong_update": "2020-11-11 16:19:35.422",
- "id": "Sboss>-82>>S-69:all",
+ "id": "{belong_id}",
"user": "boss",
- "group": "-69:all"
+ "group": "{group_id}"
}
```
@@ -860,8 +859,8 @@ access_permission：
```json
{
- "group": "-69:all",
- "target": "-77:all",
+ "group": "{group_id}",
+ "target": "{target_id}",
"access_permission": "READ"
}
```
@@ -884,11 +883,11 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/accesses
{
"access_permission": "READ",
"access_create": "2020-11-11 15:54:54.008",
- "id": "S-69:all>-88>11>S-77:all",
+ "id": "{access_id}",
"access_update": "2020-11-11 15:54:54.008",
"access_creator": "admin",
- "group": "-69:all",
- "target": "-77:all"
+ "group": "{group_id}",
+ "target": "{target_id}"
}
```
@@ -902,7 +901,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/auth/accesses
##### Method & Url
```
-DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>12>S-77:all
+DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/{access_id}
```
##### Response Status
@@ -921,7 +920,7 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>12>S
##### Method & Url
```
-PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>12>S-77:all
+PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/{access_id}
```
##### Request Body
@@ -945,11 +944,11 @@ PUT http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>12>S-77
"access_description": "test",
"access_permission": "WRITE",
"access_create": "2020-11-12 10:12:03.074",
- "id": "S-69:all>-88>12>S-77:all",
+ "id": "{access_id}",
"access_update": "2020-11-12 10:16:18.637",
"access_creator": "admin",
- "group": "-69:all",
- "target": "-77:all"
+ "group": "{group_id}",
+ "target": "{target_id}"
}
```
@@ -983,11 +982,11 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses
{
"access_permission": "READ",
"access_create": "2020-11-11 15:54:54.008",
- "id": "S-69:all>-88>11>S-77:all",
+ "id": "{access_id}",
"access_update": "2020-11-11 15:54:54.008",
"access_creator": "admin",
- "group": "-69:all",
- "target": "-77:all"
+ "group": "{group_id}",
+ "target": "{target_id}"
}
]
}
@@ -1002,7 +1001,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses
##### Method & Url
```
-GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>11>S-77:all
+GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/{access_id}
```
##### Response Status
@@ -1017,11 +1016,11 @@ GET http://localhost:8080/graphspaces/DEFAULT/auth/accesses/S-69:all>-88>11>S-77
{
"access_permission": "READ",
"access_create": "2020-11-11 15:54:54.008",
- "id": "S-69:all>-88>11>S-77:all",
+ "id": "{access_id}",
"access_update": "2020-11-11 15:54:54.008",
"access_creator": "admin",
- "group": "-69:all",
- "target": "-77:all"
+ "group": "{group_id}",
+ "target": "{target_id}"
}
```
diff --git a/content/cn/docs/clients/restful-api/graphs.md b/content/cn/docs/clients/restful-api/graphs.md
index 437d0f5bc..245825c0d 100644
--- a/content/cn/docs/clients/restful-api/graphs.md
+++ b/content/cn/docs/clients/restful-api/graphs.md
@@ -9,6 +9,8 @@ description: "Graphs（图管理）REST 接口:管理图实例的生命周期,
**重要提醒**：1.7.0 及之后，动态创建图必须开启鉴权模式。非鉴权模式请参考[图配置文件](https://hugegraph.apache.org/cn/docs/config/config-guide/#4-hugegraphproperties)，通过配置文件静态创建图。
+启用鉴权时，创建、克隆、删除、清空、修改图显示名、读取图配置、设置读模式和手动压缩等操作要求图空间管理权限（`space`）；管理员可按权限继承规则满足。创建或恢复快照、设置数据模式允许图空间管理者或该图所有者操作；列表、详情、数据模式读取和读模式读取按图读取权限校验。Raft API 另要求图空间成员权限。
+
#### 6.1.1 列出图空间中全部的图
##### Params
@@ -70,7 +72,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph
}
```
-#### 6.1.3 清空某个图的全部数据，包括 schema、vertex、edge 和 index 等，**该操作需要管理员权限**
+#### 6.1.3 清空某个图的全部数据，包括 schema、vertex、edge 和 index 等
##### Params
@@ -97,7 +99,7 @@ DELETE http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/clear?confirm_
204
```
-#### 6.1.4 克隆一个图 (**管理员权限**)
+#### 6.1.4 克隆一个图
##### Params
@@ -152,7 +154,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/cloneGraph?clone_graph_nam
}
```
-#### 6.1.5 创建一个图，**该操作需要管理员权限**
+#### 6.1.5 创建一个图
##### Params
@@ -234,6 +236,8 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph-xx
#### 6.1.6 删除某个图及其全部数据
+启用鉴权时需要图空间管理权限（`space`）。
+
##### Params
**路径参数说明：**
@@ -307,7 +311,7 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/profile
]
```
-#### 6.1.8 修改某个图的显示名，**该操作需要管理员权限**
+#### 6.1.8 修改某个图的显示名
##### Params
@@ -471,7 +475,7 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/manage
### 6.2 Conf
-#### 6.2.1 查看某个图的配置，**该操作需要管理员权限**
+#### 6.2.1 查看某个图的配置
##### Method & Url
@@ -530,7 +534,9 @@ Restore 时存在两种不同的模式：Restoring 和 Merging
正常情况下，图模式为 None，当需要 Restore 图时，需要根据需要临时修改图模式为 Restoring 模式或者 Merging
模式，并在完成 Restore 时，恢复图模式为 None。
-#### 6.3.1 查看某个图的模式。
+#### 6.3.1 查看某个图的模式
+
+启用鉴权时需要图读取权限（`space_member` 或该图的所有者）。
##### Method & Url
@@ -554,7 +560,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode
> 合法的图模式包括：NONE，RESTORING，MERGING，LOADING
-#### 6.3.2 设置某个图的模式。**该操作需要管理员权限**
+#### 6.3.2 设置某个图的模式
+
+启用鉴权时需要图空间管理权限（`space`）或该图所有者权限；管理员可按权限继承规则满足。
##### Method & Url
@@ -584,7 +592,9 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/mode
}
```
-#### 6.3.3 查看某个图的读模式。
+#### 6.3.3 查看某个图的读模式
+
+启用鉴权时需要图读取权限（`space_member` 或该图的所有者）。
##### Params
@@ -610,7 +620,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode
}
```
-#### 6.3.4 设置某个图的读模式。**该操作需要管理员权限**
+#### 6.3.4 设置某个图的读模式
+
+启用鉴权时需要图空间管理权限（`space`）；管理员可按权限继承规则满足。
##### Params
@@ -648,6 +660,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/graph_read_mode
#### 6.4.1 创建快照
+启用鉴权时需要图空间管理权限（`space`）或该图所有者权限；管理员可按权限继承规则满足。
+
##### Params
- name: 图的名称
@@ -674,6 +688,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/snapshot_create
#### 6.4.2 快照恢复
+启用鉴权时需要图空间管理权限（`space`）或该图所有者权限；管理员可按权限继承规则满足。
+
##### Params
- name: 图的名称
@@ -700,7 +716,9 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/snapshot_resume
### 6.5 Compact
-#### 6.5.1 手动压缩图，**该操作需要管理员权限**
+#### 6.5.1 手动压缩图
+
+启用鉴权时需要图空间管理权限（`space`）；管理员可按权限继承规则满足。
##### Params
@@ -734,6 +752,8 @@ PUT http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/compact
以下接口只在图运行于 raft 模式时可用，参见 [配置项](/cn/docs/config/config-option/) 中的 `raft.mode`。未开启 raft 模式的图会返回 `400` 和 `Allowed <operation> operation only when working on raft mode`。
+启用鉴权时需要图空间成员权限（`space_member`）；管理员可按权限继承规则满足。
+
##### Params
**路径参数说明：**
diff --git a/content/cn/docs/clients/restful-api/graphspace.md b/content/cn/docs/clients/restful-api/graphspace.md
index ac99f0218..cda789a9c 100644
--- a/content/cn/docs/clients/restful-api/graphspace.md
+++ b/content/cn/docs/clients/restful-api/graphspace.md
@@ -14,7 +14,7 @@ description: "Graphspace（图空间）REST 接口：多租户与资源隔离的
1. 目前图空间功能只支持在 hstore 模式下使用。
2. 如果非 hstore 模式，则只能使用默认的图空间 `DEFAULT`，且不支持创建、删除和更新图空间的操作。
3. 注意在 rest-server.properties 中，设置 `usePD=true`，并且 hugegraph.properties 中，设置 `backend=hstore`
-4. 图空间功能必须开启鉴权模式，默认账密为 admin:pa（见 `auth.admin_pa` 配置项），请务必修改默认密码，防止未授权访问。
+4. 生产环境建议启用鉴权，并修改默认管理员密码 `pa`（由 `auth.admin_pa` 配置）。创建、更新、删除图空间及管理角色的接口执行权限校验；列表与详情接口本身没有 `RolesAllowed` 角色注解，仍应结合实际鉴权配置控制暴露范围。
5. 本页所有接口都只在 PD 模式下可用，单机模式下会返回 `400` 和 `GraphSpace management is not supported in standalone mode` 错误信息。
#### 2.0.1 创建一个图空间
@@ -36,7 +36,7 @@ POST http://localhost:8080/graphspaces
| description | 否 | String | | | 图空间的描述信息 |
| cpu_limit | 是 | Int | | > 0 | CPU 核数 |
| memory_limit | 是 | Int | | > 0 | 内存大小，单位 GB |
-| storage_limit | 是 | Int | | > 0 | 图空间的数据占据的磁盘空间上限 |
+| storage_limit | 是 | Int | | > 0 | 图空间的数据占据的磁盘空间上限，单位 GB |
| compute_cpu_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外资源配置，单位 cores。当该字段不配置或者配置为 0 时，会由 cpu_limit 字段的值进行覆盖 |
| compute_memory_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外内存配置，单位 GB。当该字段不配置或者配置为 0 时，会由 memory_limit 字段的值进行覆盖 |
| oltp_namespace | 否 | String | "" | | OLTP 的 k8s 命名空间 |
@@ -175,12 +175,12 @@ GET http://localhost:8080/graphspaces/gs1
"creator": "admin",
"create_time": "2024-05-01 12:00:00",
"update_time": "2024-05-01 12:00:00",
- "dp_username": "gs1_dp",
- "dp_password": "a1b2c3d4e5f60718"
+ "dp_username": "<敏感字段，值已省略>",
+ "dp_password": "<敏感字段，值已省略>"
}
```
-> `dp_username` 和 `dp_password` 由图空间名称推导得到，只有该接口会返回这两个字段。
+> 该详情响应包含 `dp_username` 和 `dp_password`。请按敏感凭据保护，勿公开响应、写入日志或贴入工单。
#### 2.0.4 更新某个图空间
@@ -204,7 +204,7 @@ GET http://localhost:8080/graphspaces/gs1
| description | 否 | String | | | 图空间的描述信息 |
| cpu_limit | 是 | Int | | > 0 | OLTP HugeGraphServer 的 CPU 核数 |
| memory_limit | 是 | Int | | > 0 | OLTP HugeGraphServer 的内存大小，单位 GB |
-| storage_limit | 是 | Int | | > 0 | 图空间的数据占据的磁盘空间上限 |
+| storage_limit | 是 | Int | | > 0 | 图空间的数据占据的磁盘空间上限，单位 GB |
| compute_cpu_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外资源配置，单位 cores。当该字段不配置或者配置为 0 时，会由 cpu_limit 字段的值进行覆盖 |
| compute_memory_limit | 否 | Int | 0 | >= 0 | 针对图计算的额外内存配置，单位 GB。当该字段不配置或者配置为 0 时，会由 memory_limit 字段的值进行覆盖 |
| oltp_namespace | 否 | String | | | OLTP 的 k8s 命名空间 |
diff --git a/content/cn/docs/clients/restful-api/gremlin.md b/content/cn/docs/clients/restful-api/gremlin.md
index 52642f56b..32b91aee5 100644
--- a/content/cn/docs/clients/restful-api/gremlin.md
+++ b/content/cn/docs/clients/restful-api/gremlin.md
@@ -21,12 +21,14 @@ description: "Gremlin（图查询语言）REST 接口:通过 HTTP 接口执行 G
- language: 发送语句的语言类型，默认为`gremlin-groovy`
- aliases: 为存在于图空间的已有变量添加别名
-**查询顶点**
+此 REST 代理的 GET 查询不能可靠地传递含 JSON 花括号的 aliases 参数；当前图绑定名带连字符，也不能直接作为 Groovy 变量。以下用简单表达式示范 GET。需要选择图执行遍历时，请使用下方带 aliases 的 POST 示例。
##### Method & Url
```
-GET http://127.0.0.1:8080/gremlin?gremlin=hugegraph.traversal().V('1:marko')
+curl --compressed --get \
+ --data-urlencode "gremlin=1+1" \
+ http://127.0.0.1:8080/gremlin
```
##### Response Status
@@ -39,58 +41,26 @@ GET http://127.0.0.1:8080/gremlin?gremlin=hugegraph.traversal().V('1:marko')
```json
{
- "requestId": "c6ef47a8-b634-4b07-9d38-6b3b69a3a556",
- "status": {
- "message": "",
- "code": 200,
- "attributes": {}
- },
- "result": {
- "data": [{
- "id": "1:marko",
- "label": "person",
- "type": "vertex",
- "properties": {
- "city": [{
- "id": "1:marko>city",
- "value": "Beijing"
- }],
- "name": [{
- "id": "1:marko>name",
- "value": "marko"
- }],
- "age": [{
- "id": "1:marko>age",
- "value": 29
- }]
- }
- }],
- "meta": {}
- }
+ "requestId": "<request_id>",
+ "status": {"message": "", "code": 200, "attributes": {}},
+ "result": {"data": [2], "meta": {}}
}
```
#### 8.1.2 向 HugeGraphServer 发送 gremlin 语句（POST），同步执行
-##### Method & Url
+**查询顶点数**
-```
-POST http://localhost:8080/gremlin
-```
+##### 可执行请求命令
-**查询顶点**
-
-##### Request Body
-
-```json
-{
- "gremlin": "hugegraph.traversal().V('1:marko')",
- "bindings": {},
- "language": "gremlin-groovy",
- "aliases": {}
-}
+```bash
+curl --compressed -sS -X POST http://127.0.0.1:8080/gremlin \
+ -H 'Content-Type: application/json' \
+ --data-binary '{"gremlin":"g.V().count()","aliases":{"g":"__g_DEFAULT-hugegraph"}}'
```
+`/gremlin` 是顶层接口。图空间 `DEFAULT` 中图 `hugegraph` 对应的 traversal source 名为 `__g_DEFAULT-hugegraph`，请求通过 `aliases` 映射为脚本中的 `g`。若使用不同图空间或图名，应按 Server 绑定名调整 alias。批量结果可能以 gzip 返回，curl 使用 `--compressed` 可自动解压。
+
##### Response Status
```json
@@ -101,43 +71,13 @@ POST http://localhost:8080/gremlin
```json
{
- "requestId": "c6ef47a8-b634-4b07-9d38-6b3b69a3a556",
- "status": {
- "message": "",
- "code": 200,
- "attributes": {}
- },
- "result": {
- "data": [{
- "id": "1:marko",
- "label": "person",
- "type": "vertex",
- "properties": {
- "city": [{
- "id": "1:marko>city",
- "value": "Beijing"
- }],
- "name": [{
- "id": "1:marko>name",
- "value": "marko"
- }],
- "age": [{
- "id": "1:marko>age",
- "value": 29
- }]
- }
- }],
- "meta": {}
- }
+ "requestId": "<request_id>",
+ "status": {"message": "", "code": 200, "attributes": {}},
+ "result": {"data": [6], "meta": {}}
}
```
-注意：
-
-> 这里是直接使用图对象（hugegraph），先获取其遍历器（traversal()），再获取顶点。
-> 不能直接写成`graph.traversal().V()`或`g.V()`，可以通过`"aliases": {"graph": "hugegraph", "g": "__g_hugegraph"}`
-> 为图和遍历器添加别名后使用别名操作。其中，`hugegraph`是原生存在的变量，`__g_hugegraph`是`HugeGraphServer`额外添加的变量，
-> 每个图都会存在一个对应的这样格式（__g_${graph}）的遍历器对象。
+顶点数取决于当前图中的数据；上面的 `6` 仅为示例结果。
> 响应体的结构与其他 Vertex 或 Edge 的 RESTful API 的结构有区别，用户可能需要自行解析。
@@ -147,12 +87,11 @@ POST http://localhost:8080/gremlin
```json
{
- "gremlin": "g.E('S1:marko>2>>S2:lop')",
+ "gremlin": "g.E().hasLabel('created').limit(1)",
"bindings": {},
"language": "gremlin-groovy",
"aliases": {
- "graph": "hugegraph",
- "g": "__g_hugegraph"
+ "g": "__g_DEFAULT-hugegraph"
}
}
```
@@ -167,7 +106,7 @@ POST http://localhost:8080/gremlin
```json
{
- "requestId": "3f117cd4-eedc-4e08-a106-ee01d7bb8249",
+ "requestId": "<request_id>",
"status": {
"message": "",
"code": 200,
@@ -175,16 +114,16 @@ POST http://localhost:8080/gremlin
},
"result": {
"data": [{
- "id": "S1:marko>2>>S2:lop",
+ "id": "<edge_id>",
"label": "created",
"type": "edge",
- "inVLabel": "software",
"outVLabel": "person",
- "inV": "2:lop",
- "outV": "1:marko",
+ "inVLabel": "software",
+ "outV": "<source_vertex_id>",
+ "inV": "<target_vertex_id>",
"properties": {
"weight": 0.4,
- "date": "20171210"
+ "date": "<date>"
}
}],
"meta": {}
@@ -192,6 +131,8 @@ POST http://localhost:8080/gremlin
}
```
+边 ID、端点和属性值取决于当前图中的数据。
+
#### 8.1.3 向 HugeGraphServer 发送 gremlin 语句（POST），异步执行
##### Method & Url
@@ -215,8 +156,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/jobs/gremlin
注意：
-> 异步执行 Gremlin 语句暂不支持 aliases，可以使用 `graph` 代表要操作的图，也可以直接使用图的名字，例如 `hugegraph`;
-> 另外`g`代表 traversal，等价于 `graph.traversal()` 或者 `hugegraph.traversal()`
+> 异步请求不能自行传入 `aliases` 字段；Server 会自动绑定 `graph`（当前图对象）和 `g`（当前遍历源），并把 URL 中的图名作为 `graph` 的别名。因此脚本可以使用 `graph` 或 `g`，也可以使用当前请求路径中的图名。
##### Response Status
@@ -242,7 +182,7 @@ POST http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/jobs/gremlin
```json
{
- "gremlin": "g.E('S1:marko>2>>S2:lop')",
+ "gremlin": "g.E().hasLabel('created').limit(1)",
"bindings": {},
"language": "gremlin-groovy",
"aliases": {}
diff --git a/content/cn/docs/config/config-authentication.md b/content/cn/docs/config/config-authentication.md
index 481edd503..799069cd3 100644
--- a/content/cn/docs/config/config-authentication.md
+++ b/content/cn/docs/config/config-authentication.md
@@ -40,24 +40,34 @@ curl -u 'admin:<password>' \
http://localhost:8080/graphspaces/DEFAULT/graphs/hugegraph/schema/vertexlabels
```
+Basic Authentication 只对 `用户名:密码` 做 Base64 编码，不会加密凭据。通过 HTTP 发送时应使用 HTTPS；相关设置见 [HTTPS 配置](config-https)。
+
**警告**：在 1.5.0 之前版本的 HugeGraph-Server 在鉴权模式下存在 JWT 相关的安全隐患，请务必使用新版本或自行修改 JWT token 的 secretKey。
-修改方式为在配置文件`rest-server.properties`中重写`auth.token_secret`信息：(1.5.0 后会默认生成随机值则无需配置)
+`auth.token_secret` 由认证数据图的配置读取。默认认证图名为 `hugegraph`，因此配置文件通常是
+`conf/graphs/hugegraph.properties`；如果修改了 `auth.graph_store`，应改为对应图的 properties 文件。
+源码默认会生成 32 个随机字节并以 Base64 编码，但该值不会写回配置文件；重启后或多个 Server 节点之间
+无法依赖各自生成的默认值保持一致。若需要令已有 token 在重启后继续有效，或让多个节点验证同一 token，
+请为认证图显式配置同一个强随机密钥：
+
+Server 将配置字符串按 UTF-8 编码后交给 JJWT 的 HS256 签名器，密钥至少需要 32 字节；这是字节长度要求，不代表任意 32 字符串都具有足够随机性。下面的命令在本机生成 32 个随机字节并以 Base64 编码。
```properties
-auth.token_secret=XXXX #这里为 32 位 String，由 a-z，A-Z 和 0-9 组成
+# 在每个 Server 节点的认证图配置中填写同一个值
+auth.token_secret=<本机生成的密钥>
```
-也可以通过下面的命令实现：
+可在本机终端生成密钥，再通过安全方式填入认证图配置；不要把实际密钥提交到代码库或公开日志：
-```shell
-RANDOM_STRING=$(head /dev/urandom | tr -dc A-Za-z0-9 | head -c 32)
-echo "auth.token_secret=${RANDOM_STRING}" >> rest-server.properties
+```bash
+openssl rand -base64 32
```
由于默认值在每次启动时随机生成，当 token 需要在重启后继续有效、或者需要被多个服务节点接受时，必须显式配置该项。token 的有效期由
`auth.token_expire` 决定，默认为 86400 秒。
+`auth.token_expire` 和 `auth.token_secret` 都属于 `auth.graph_store` 指定的认证数据图配置；`rest-server.properties` 中的同名项不会覆盖认证图配置。
+
#### StandardAuthenticator 模式
`StandardAuthenticator`模式是通过在数据库后端存储用户信息来支持用户认证和权限控制，该实现基于数据库存储的用户的名称与密码进行认证（密码已被加密），基于用户的角色来细粒度控制用户权限。下面是具体的配置流程（重启服务生效）：
@@ -76,7 +86,8 @@ authentication: {
```properties
auth.authenticator=org.apache.hugegraph.auth.StandardAuthenticator
auth.graph_store=hugegraph
-# 内置 admin 账号的密码，默认为 pa，在首次启动时生效
+# Server 启动路径首次创建内置 admin 账号时使用，默认值为公开的 pa，生产部署前务必显式设置强密码
+# 本地持久化后端首次启用 StandardAuthenticator 时，init-store.sh 会交互式读取密码
#auth.admin_pa=<your-admin-password>
# auth client config
diff --git a/content/cn/docs/guides/backup-restore.md b/content/cn/docs/guides/backup-restore.md
index f5fb6a074..fc3785b44 100644
--- a/content/cn/docs/guides/backup-restore.md
+++ b/content/cn/docs/guides/backup-restore.md
@@ -100,7 +100,9 @@ Restore 时存在两种不同的模式： Restoring 和 Merging，另外，还
实现的设置图模式的 RESTful API 如下：
-##### 查看某个图的模式. **该操作需要管理员权限**
+##### 查看某个图的模式
+
+启用鉴权时需要图读取权限（`space_member` 或该图的所有者）。
###### Method & Url
@@ -124,7 +126,9 @@ GET http://localhost:8080/graphspaces/DEFAULT/graphs/{graph}/mode
> 合法的图模式包括：NONE，RESTORING，MERGING，LOADING
-##### 设置某个图的模式. **该操作需要管理员权限**
+##### 设置某个图的模式
+
+启用鉴权时需要图空间管理权限（`space`）；管理员可按权限继承规则满足。
###### Method & Url
diff --git a/content/cn/docs/guides/custom-plugin.md b/content/cn/docs/guides/custom-plugin.md
index f098d8c1b..5883f1b6b 100644
--- a/content/cn/docs/guides/custom-plugin.md
+++ b/content/cn/docs/guides/custom-plugin.md
@@ -35,7 +35,7 @@ weight: 3
##### 1.2 添加`hugegraph-core` Jar 包依赖
-maven pom.xml 详细内容如下：
+maven pom.xml 详细内容如下。`hugegraph.version` 应与要兼容的 Server 版本一致；此处以当前主线版本 1.7.0 为例：
```xml
<?xml version="1.0" encoding="UTF-8"?>
@@ -52,11 +52,15 @@ maven pom.xml 详细内容如下：
<name>hugegraph-plugin-demo</name>
+ <properties>
+ <hugegraph.version>1.7.0</hugegraph.version>
+ </properties>
+
<dependencies>
<dependency>
<groupId>org.apache.hugegraph</groupId>
<artifactId>hugegraph-core</artifactId>
- <version>${project.version}</version>
+ <version>${hugegraph.version}</version>
</dependency>
</dependencies>
</project>
@@ -110,7 +114,7 @@ public class RocksDBStoreProvider extends AbstractBackendStoreProvider {
###### 2.1.2 实现接口 BackendStore
-BackendStore 接口定义如下：
+BackendStore 的核心抽象方法如下（接口默认辅助方法略）：
```java
public interface BackendStore {
@@ -150,6 +154,9 @@ public interface BackendStore {
// Query data
Iterator<BackendEntry> query(Query query);
+ Iterator<Iterator<BackendEntry>> query(Iterator<Query> queries,
+ Function<Query, Query> queryWriter,
+ HugeGraph hugeGraph);
Number queryNumber(Query query);
// Transaction
diff --git a/content/cn/docs/guides/faq.md b/content/cn/docs/guides/faq.md
index f592d3f30..6937d9e2d 100644
--- a/content/cn/docs/guides/faq.md
+++ b/content/cn/docs/guides/faq.md
@@ -34,7 +34,7 @@ weight: 6
- 配置了两个图，名字是`hugegraph`和`hugegraph1`，而启动服务的命令是`start-hugegraph.sh`，是只打开了`hugegraph`这个图吗
- 脚本名称与图名无关。需要从 `graphs` 目录加载多个本地图时，在 `rest-server.properties` 中设置 `graph.load_from_local_config=true`；该选项的源码默认值是 `false`。
+ 脚本名称与图名无关。Server 默认从 `conf/graphs` 扫描并加载本地图配置，目录可在 `conf/rest-server.properties` 的 `graphs` 配置项中修改。`graph.load_from_local_config` 的默认值是 `false`，只控制图管理器构造阶段的预加载及 `reload()` 重扫，不能用于禁止启动时加载；需要加载多个本地图时，为每个图准备独立配置文件。详见[服务端配置说明](/cn/docs/config/config-guide/)。
- 服务启动成功后，使用`curl`查询所有顶点时返回乱码
diff --git a/content/cn/docs/language/hugegraph-example.md b/content/cn/docs/language/hugegraph-example.md
index 0835e12ab..923edb13e 100644
--- a/content/cn/docs/language/hugegraph-example.md
+++ b/content/cn/docs/language/hugegraph-example.md
@@ -58,10 +58,16 @@ HugeGraph 相对于 TitanDB 而言，其主要特点如下：
HugeGraph 需要显示创建 Schema，因此需要依次创建 PropertyKey、VertexLabel、EdgeLabel，如果有需要索引还需要创建 IndexLabel。
+以下代码片段假定 Groovy 脚本已打开 HugeGraph 实例并将其绑定为 `graph`，同时设置遍历源 `g = graph.traversal()`。可从 [Gremlin Console 本地模式示例](/cn/docs/clients/gremlin-console/)开始；该页面的 `scripts/example.groovy` 会创建这两个变量。远程 Console 中的 `g` 是 Server 端遍历源别名，客户端本地没有 `graph` 对象；远程建模请使用本页之外的 Schema REST API。
+
#### 2.1 Graph Schema
```groovy
-schema = hugegraph.schema()
+import org.apache.tinkerpop.gremlin.structure.T
+import org.apache.tinkerpop.gremlin.structure.Vertex
+
+schema = graph.schema()
+g = graph.traversal()
schema.propertyKey("name").asText().ifNotExist().create()
schema.propertyKey("age").asInt().ifNotExist().create()
@@ -115,6 +121,8 @@ pluto.addEdge("brother", neptune)
pluto.addEdge("lives", tartarus, "reason", "no fear of death")
pluto.addEdge("pet", cerberus)
cerberus.addEdge("lives", tartarus)
+
+graph.tx().commit()
```
#### 2.3 Indices
diff --git a/content/cn/docs/language/hugegraph-gremlin.md b/content/cn/docs/language/hugegraph-gremlin.md
index 1b5afa7d3..405e31fa9 100644
--- a/content/cn/docs/language/hugegraph-gremlin.md
+++ b/content/cn/docs/language/hugegraph-gremlin.md
@@ -22,7 +22,7 @@ HugeGraph实现了TinkerPop框架，但是并没有实现TinkerPop所有的特
|----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|
| Computer | Determines if the {@code Graph} implementation supports {@link GraphComputer} based processing | false |
| Transactions | Determines if the {@code Graph} implementations supports transactions. | true |
-| Persistence | Determines if the {@code Graph} implementation supports persisting it's contents natively to disk.This feature does not refer to every graph's ability to write to disk via the Gremlin IO packages(.e.g. GraphML), unless the graph natively persists to disk via those options somehow. For example,TinkerGraph does not support this feature as it is a pure in-sideEffects graph. | true |
+| Persistence | Determines if the {@code Graph} implementation supports persisting it's contents natively to disk.This feature does not refer to every graph's ability to write to disk via the Gremlin IO packages(.e.g. GraphML), unless the graph natively persists to disk via those options somehow. For example,TinkerGraph does not support this feature as it is a pure in-sideEffects graph. | 取决于后端 |
| ThreadedTransactions | Determines if the {@code Graph} implementation supports threaded transactions which allow a transaction be executed across multiple threads via {@link Transaction#createThreadedTx()}. | false |
| ConcurrentAccess | Determines if the {@code Graph} implementation supports more than one connection to the same instance at the same time. For example, Neo4j embedded does not support this feature because concurrent access to the same database files by multiple instances is not possible. However, Neo4j HA could support this feature as each new {@code Graph} instance coordinates with the Neo4j cluster allowing multiple instances to operate on the same database. | false |