doc: update Log4j2 configuration and gremlin-console guide

content/cn/docs/contribution-guidelines/hugegraph-server-idea-setup.md

@@ -1,6 +1,6 @@
 ---
-title: "在 IDEA 中配置 HugeGraph-Server 开发环境"
-linkTitle: "在 IDEA 中配置 HugeGraph-Server 开发环境"
+title: "在 IDEA 中配置 Server 开发环境"
+linkTitle: "在 IDEA 中配置 Server 开发环境"
 weight: 4
 ---
 
@@ -102,15 +102,29 @@ curl "http://localhost:8080/graphs/hugegraph/graph/vertices" | gunzip
 
 此时，可以在调试器中查看详细的变量信息。
 
+#### 5. Log4j2 日志配置
+
+默认情况下，运行 `InitStore` 和 `HugeGraphServer` 时，读取的 Log4j2 配置文件路径为 `hugegraph-dist/src/main/resources/log4j2.xml`，而不是 `path-to-your-directory/conf/log4j2.xml`，这个配置文件是使用**脚本**启动 HugeGraphServer 时读取的。
+
+为了避免同时维护两份配置文件，可以考虑在 **IntelliJ IDEA** 运行与调试 HugeGraphServer 时，修改读取的 Log4j2 配置文件路径：
+
+1. 打开之前创建的 `Application` 配置
+2. 点击 `Modify options` - `Add VM options`
+3. 设置 VM options 为 `-Dlog4j.configurationFile=conf/log4j2.xml`
+
 ### 可能遇到的问题
 
-*** java: package sun.misc does not exist ***
+#### java: package sun.misc does not exist
 
 原因可能是在使用 Java 11 编译时触发了交叉编译，导致项目中使用的 `sun.misc.Unsafe` 找不到符号。有两种解决方案可供选择：
 
 1. 在 IntelliJ IDEA 的 `Preferences/Settings` 中找到 `Java Compiler` 面板，然后关闭 `--release` 选项 (推荐)
 2. 或者将项目的 SDK 版本设置为 8
 
+#### Log4j2 日志无法打印 %l 等位置信息
+
+这是因为 Log4j2 中使用了 asynchronous loggers，可以参考[官方文档](https://logging.apache.org/log4j/2.x/manual/layouts.html#LocationInformation)进行配置
+
 ##### 参考
 
 1. [HugeGraph-Server Quick Start](/docs/quickstart/hugegraph-server/)

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

@@ -4,47 +4,46 @@ linkTitle: "Install HugeGraph-Server"
 weight: 1
 ---
 
-### 1 HugeGraph-Server概述
+### 1 HugeGraph-Server 概述
 
-HugeGraph-Server 是 HugeGraph 项目的核心部分，包含Core、Backend、API等子模块。
+HugeGraph-Server 是 HugeGraph 项目的核心部分，包含 Core、Backend、API 等子模块。
 
-Core模块是Tinkerpop接口的实现，Backend模块用于管理数据存储，目前支持的后端包括：Memory、Cassandra、ScyllaDB以及RocksDB，API模块提供HTTP Server，将Client的HTTP请求转化为对Core的调用。
+Core 模块是 Tinkerpop 接口的实现，Backend 模块用于管理数据存储，目前支持的后端包括：Memory、Cassandra、ScyllaDB 以及 RocksDB，API 模块提供 HTTP Server，将 Client 的 HTTP 请求转化为对 Core 的调用。
 
-> 文档中会大量出现`HugeGraph-Server`及`HugeGraphServer`这两种写法，其他组件也类似。这两种写法含义上并无大的差异，可以这么区分：`HugeGraph-Server`表示服务端相关组件代码，`HugeGraphServer`表示服务进程。
+> 文档中会大量出现 `HugeGraph-Server` 及 `HugeGraphServer` 这两种写法，其他组件也类似。这两种写法含义上并无大的差异，可以这么区分：`HugeGraph-Server` 表示服务端相关组件代码，`HugeGraphServer` 表示服务进程。
 
 ### 2 依赖
 
 #### 2.1 安装 Java 11 (JDK 11)
 
-请优先考虑在 Java11 的环境上启动 `HugeGraph-Server`, 目前同时保留对 Java8 的兼容 
+请优先考虑在 Java11 的环境上启动 `HugeGraph-Server`，目前同时保留对 Java8 的兼容
 
-**在往下阅读之前务必执行`java -version`命令查看jdk版本**
+**在往下阅读之前务必执行 `java -version` 命令查看 jdk 版本**
 
 ```bash
 java -version
 ```
 
-#### 2.2 安装GCC-4.3.0(GLIBCXX_3.4.10)或更新版本（可选）
+#### 2.2 安装 GCC-4.3.0 (GLIBCXX_3.4.10) 或更新版本（可选）
 
-如果使用的是RocksDB后端，请务必执行`gcc --version`命令查看gcc版本；若使用其他后端，则不需要。
+如果使用的是 RocksDB 后端，请务必执行 `gcc --version` 命令查看 gcc 版本；若使用其他后端，则不需要。
 
 ```bash
 gcc --version
 ```
 
 ### 3 部署
 
-有三种方式可以部署HugeGraph-Server组件：
+有三种方式可以部署 HugeGraph-Server 组件：
 
-- 方式1：一键部署
-- 方式2：下载tar包
-- 方式3：源码编译
-- 方式4：使用Docker容器
+- 方式 1：一键部署
+- 方式 2：下载 tar 包
+- 方式 3：源码编译
+- 方式 4：使用 Docker 容器
 
 #### 3.1 一键部署
 
-HugeGraph-Tools 提供了一键部署的命令行工具，用户可以使用该工具快速地一键下载、解压、配置并启动 HugeGraph-Server 和 HugeGraph-Hubble
-最新的 HugeGraph-Toolchain 中已经包含所有的这些工具, 直接下载它解压就有工具包集合了
+HugeGraph-Tools 提供了一键部署的命令行工具，用户可以使用该工具快速地一键下载、解压、配置并启动 HugeGraph-Server 和 HugeGraph-Hubble，最新的 HugeGraph-Toolchain 中已经包含所有的这些工具，直接下载它解压就有工具包集合了
 
 ```bash
 # download toolchain package, it includes loader + tool + hubble, please check the latest version (here is 1.0.0)
@@ -54,17 +53,17 @@ tar zxf *hugegraph-*.tar.gz
 cd *hugegraph*/*tool* 
 ```
 
-> 注：${version}为版本号，最新版本号可参考[Download页面](/docs/download/download)，或直接从Download页面点击链接下载
+> 注：`${version}` 为版本号，最新版本号可参考 [Download 页面](/docs/download/download)，或直接从 Download 页面点击链接下载
 
-HugeGraph-Tools 的总入口脚本是`bin/hugegraph`，用户可以使用`help`子命令查看其用法，这里只介绍一键部署的命令。
+HugeGraph-Tools 的总入口脚本是 `bin/hugegraph`，用户可以使用 `help` 子命令查看其用法，这里只介绍一键部署的命令。
 
 ```bash
 bin/hugegraph deploy -v {hugegraph-version} -p {install-path} [-u {download-path-prefix}]
 ```
 
-`{hugegraph-version}`表示要部署的HugeGraphServer及HugeGraphStudio的版本，用户可查看`conf/version-mapping.yaml`文件获取版本信息，`{install-path}`指定HugeGraphServer及HugeGraphStudio的安装目录，`{download-path-prefix}`可选，指定HugeGraphServer及HugeGraphStudio tar包的下载地址，不提供时使用默认下载地址，比如要启动 0.6 版本的HugeGraph-Server及HugeGraphStudio将上述命令写为`bin/hugegraph deploy -v 0.6 -p services`即可。
+`{hugegraph-version}` 表示要部署的 HugeGraphServer 及 HugeGraphStudio 的版本，用户可查看 `conf/version-mapping.yaml` 文件获取版本信息，`{install-path}` 指定 HugeGraphServer 及 HugeGraphStudio 的安装目录，`{download-path-prefix}` 可选，指定 HugeGraphServer 及 HugeGraphStudio tar 包的下载地址，不提供时使用默认下载地址，比如要启动 0.6 版本的 HugeGraph-Server 及 HugeGraphStudio 将上述命令写为 `bin/hugegraph deploy -v 0.6 -p services` 即可。
 
-#### 3.2 下载tar包
+#### 3.2 下载 tar 包
 
 ```bash
 # use the latest version, here is 1.0.0 for example
@@ -74,15 +73,15 @@ tar zxf *hugegraph*.tar.gz
 
 #### 3.3 源码编译
 
-源码编译前请确保安装了wget命令
+源码编译前请确保安装了 wget 命令
 
-下载HugeGraph源代码
+下载 HugeGraph 源代码
 
 ```bash
 git clone https://github.com/apache/hugegraph.git
 ```
 
-编译打包生成tar包
+编译打包生成 tar 包
 
 ```bash
 cd hugegraph
@@ -112,26 +111,27 @@ mvn package -DskipTests
 ......
 ```
 
-执行成功后，在hugegraph目录下生成 hugegraph-*.tar.gz 文件，就是编译生成的tar包。
+执行成功后，在 hugegraph 目录下生成 hugegraph-*.tar.gz 文件，就是编译生成的 tar 包。
 
-#### 3.4 使用Docker容器
+#### 3.4 使用 Docker 容器
 
-可参考[Docker部署方式](https://hub.docker.com/r/hugegraph/hugegraph)。
+可参考 [Docker 部署方式](https://hub.docker.com/r/hugegraph/hugegraph)。
 
 ### 4 配置
 
-如果需要快速启动HugeGraph仅用于测试，那么只需要进行少数几个配置项的修改即可（见下一节）。
-详细的配置介绍请参考[配置文档](/docs/config/config-guide)及[配置项介绍](/docs/config/config-option)
+如果需要快速启动 HugeGraph 仅用于测试，那么只需要进行少数几个配置项的修改即可（见下一节）。
+
+详细的配置介绍请参考[配置文档](/docs/config/config-guide)及[配置项介绍](/docs/config/config-option)。
 
 ### 5 启动
 
 启动分为"首次启动"和"非首次启动"，这么区分是因为在第一次启动前需要初始化后端数据库，然后启动服务。
+
 而在人为停掉服务后，或者其他原因需要再次启动服务时，因为后端数据库是持久化存在的，直接启动服务即可。
 
-HugeGraphServer启动时会连接后端存储并尝试检查后端存储版本号，如果未初始化后端或者后端已初始化但版本不匹配时（旧版本数据），HugeGraphServer会启动失败，并给出错误信息。
+HugeGraphServer 启动时会连接后端存储并尝试检查后端存储版本号，如果未初始化后端或者后端已初始化但版本不匹配时（旧版本数据），HugeGraphServer 会启动失败，并给出错误信息。
 
-如果需要外部访问HugeGraphServer，请修改`rest-server.properties`的`restserver.url`配置项
-（默认为`http://127.0.0.1:8080`），修改成机器名或IP地址。
+如果需要外部访问 HugeGraphServer，请修改 `rest-server.properties` 的 `restserver.url` 配置项（默认为 `http://127.0.0.1:8080`），修改成机器名或 IP 地址。
 
 由于各种后端所需的配置（hugegraph.properties）及启动步骤略有不同，下面逐一对各后端的配置及启动做介绍。
 
@@ -144,7 +144,7 @@ backend=memory
 serializer=text
 ```
 
-> Memory后端的数据是保存在内存中无法持久化的，不需要初始化后端，这也是唯一一个不需要初始化的后端。
+> Memory 后端的数据是保存在内存中无法持久化的，不需要初始化后端，这也是唯一一个不需要初始化的后端。
 
 启动 server
 
@@ -158,7 +158,7 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK
 
 #### 5.2 RocksDB
 
-> RocksDB是一个嵌入式的数据库，不需要手动安装部署, 要求 GCC 版本 >= 4.3.0（GLIBCXX_3.4.10），如不满足，需要提前升级 GCC
+> RocksDB 是一个嵌入式的数据库，不需要手动安装部署，要求 GCC 版本 >= 4.3.0（GLIBCXX_3.4.10），如不满足，需要提前升级 GCC
 
 修改 hugegraph.properties
 
@@ -176,7 +176,7 @@ cd hugegraph-${version}
 bin/init-store.sh
 ```
 
-启动server
+启动 server
 
 ```bash
 bin/start-hugegraph.sh
@@ -230,7 +230,7 @@ Initing HugeGraph Store...
 2017-12-01 11:27:00 10413 [pool-3-thread-1] [INFO ] com.baidu.hugegraph.backend.Transaction [] - Clear cache on event 'store.init'
 ```
 
-启动server
+启动 server
 
 ```bash
 bin/start-hugegraph.sh
@@ -260,7 +260,7 @@ cassandra.password=
 #cassandra.keyspace.replication=3
 ```
 
-由于 scylladb 数据库本身就是基于 cassandra 的"优化版"，如果用户未安装 scylladb ，也可以直接使用 cassandra 作为后端存储，只需要把 backend 和 serializer 修改为 scylladb，host 和 post 指向 cassandra 集群的 seeds 和 port 即可，但是并不建议这样做，这样发挥不出 scylladb 本身的优势了。
+由于 scylladb 数据库本身就是基于 cassandra 的"优化版"，如果用户未安装 scylladb，也可以直接使用 cassandra 作为后端存储，只需要把 backend 和 serializer 修改为 scylladb，host 和 post 指向 cassandra 集群的 seeds 和 port 即可，但是并不建议这样做，这样发挥不出 scylladb 本身的优势了。
 
 初始化数据库（仅第一次启动时需要）
 
@@ -269,7 +269,7 @@ cd hugegraph-${version}
 bin/init-store.sh
 ```
 
-启动server
+启动 server
 
 ```bash
 bin/start-hugegraph.sh
@@ -304,7 +304,7 @@ cd hugegraph-${version}
 bin/init-store.sh
 ```
 
-启动server
+启动 server
 
 ```bash
 bin/start-hugegraph.sh
@@ -314,51 +314,50 @@ Connecting to HugeGraphServer (http://127.0.0.1:8080/graphs)....OK
 
 > 更多其它后端配置可参考[配置项介绍](/docs/config/config-option)
 
-### 6 访问Server
+### 6 访问 Server
 
 #### 6.1 服务启动状态校验
 
-`jps`查看服务进程
+`jps` 查看服务进程
 
 ```bash
 jps
 6475 HugeGraphServer
 ```
 
-`curl`请求`RESTfulAPI`
+`curl` 请求 RESTful API
 
 ```bash
 echo `curl -o /dev/null -s -w %{http_code} "http://localhost:8080/graphs/hugegraph/graph/vertices"`
 ```
 
-返回结果200，代表server启动正常
+返回结果 200，代表 server 启动正常
 
-#### 6.2 请求Server
+#### 6.2 请求 Server
 
-HugeGraphServer的RESTful API包括多种类型的资源，典型的包括graph、schema、gremlin、traverser和task，
+HugeGraphServer 的 RESTful API 包括多种类型的资源，典型的包括 graph、schema、gremlin、traverser 和 task
 
-- `graph`包含`vertices`、`edges`
-- `schema` 包含`vertexlabels`、 `propertykeys`、 `edgelabels`、`indexlabels`
-- `gremlin`包含各种`Gremlin`语句，如`g.v()`，可以同步或者异步执行
-- `traverser`包含各种高级查询，包括最短路径、交叉点、N步可达邻居等
-- `task`包含异步任务的查询和删除
+- `graph` 包含 `vertices`、`edges`
+- `schema` 包含 `vertexlabels`、`propertykeys`、`edgelabels`、`indexlabels`
+- `gremlin` 包含各种 `Gremlin` 语句，如 `g.v()`，可以同步或者异步执行
+- `traverser` 包含各种高级查询，包括最短路径、交叉点、N 步可达邻居等
+- `task` 包含异步任务的查询和删除
 
-##### 6.2.1 获取`hugegraph`的顶点及相关属性
+##### 6.2.1 获取 `hugegraph` 的顶点及相关属性
 
 ```bash
 curl http://localhost:8080/graphs/hugegraph/graph/vertices 
 ```
 
 _说明_
 
-1. 由于图的点和边很多，对于 list 型的请求，比如获取所有顶点，获取所有边等，Server 会将数据压缩再返回，
-所以使用 curl 时得到一堆乱码，可以重定向至 `gunzip` 进行解压。推荐使用 Chrome 浏览器 + Restlet 插件发送 HTTP 请求进行测试。
+1. 由于图的点和边很多，对于 list 型的请求，比如获取所有顶点，获取所有边等，Server 会将数据压缩再返回，所以使用 curl 时得到一堆乱码，可以重定向至 `gunzip` 进行解压。推荐使用 Chrome 浏览器 + Restlet 插件发送 HTTP 请求进行测试。
 
     ```
     curl "http://localhost:8080/graphs/hugegraph/graph/vertices" | gunzip
     ```
 
-2. 当前HugeGraphServer的默认配置只能是本机访问，可以修改配置，使其能在其他机器访问。
+2. 当前 HugeGraphServer 的默认配置只能是本机访问，可以修改配置，使其能在其他机器访问。
 
     ```
     vim conf/rest-server.properties
@@ -420,9 +419,9 @@ _说明_
 }
 ```
 
-详细的API请参考[RESTful-API](/docs/clients/restful-api)文档
+详细的 API 请参考 [RESTful-API](/docs/clients/restful-api) 文档
 
-### 7 停止Server
+### 7 停止 Server
 
 ```bash
 $cd hugegraph-${version}
@@ -431,4 +430,61 @@ $bin/stop-hugegraph.sh
 
 ### 8 使用 IntelliJ IDEA 调试 Server
 
-请参考[如何在 IDEA 中搭建 HugeGraph-Server 开发环境](/docs/contribution-guidelines/hugegraph-server-idea-setup)
+请参考[在 IDEA 中配置 Server 开发环境](/docs/contribution-guidelines/hugegraph-server-idea-setup)
+
+### 9 在启动 Server 时创建示例图
+
+修改 `conf/gremlin-server.yaml`，将 `empty-sample.groovy` 修改为 `example.groovy`：
+
+```yaml
+org.apache.tinkerpop.gremlin.jsr223.ScriptFileGremlinPlugin: {
+    files: [scripts/example.groovy]
+}
+```
+
+修改 `scripts/example.groovy`，将：
+
+```groovy
+RegisterUtil.registerRocksDB()
+conf = "conf/graphs/hugegraph.properties"
+graph = HugeFactory.open(conf)
+graph.serverStarted(IdGenerator.of("server-tinkerpop"), NodeRole.MASTER)
+schema = graph.schema()
+```
+
+修改为：
+
+```groovy
+conf = "conf/graphs/hugegraph.properties"
+graph = HugeFactory.open(conf)
+schema = graph.schema()
+```
+
+然后使用脚本启动 HugeGraph-Server，如果打印出类似日志：
+
+```java
+2023-06-10 19:41:14 [main] [INFO] o.a.h.d.HugeGremlinServer [org.apache.hugegraph.dist.HugeGremlinServer.start(HugeGremlinServer.java:38)] - 3.5.1
+         \,,,/
+         (o o)
+-----oOOo-(3)-oOOo-----
+
+2023-06-10 19:41:14 [main] [INFO] o.a.h.u.ConfigUtil [org.apache.hugegraph.util.ConfigUtil.scanGraphsDir(ConfigUtil.java:88)] - Scanning option 'graphs' directory './conf/graphs'
+2023-06-10 19:41:14 [main] [INFO] o.a.h.d.HugeGremlinServer [org.apache.hugegraph.dist.HugeGremlinServer.start(HugeGremlinServer.java:52)] - Configuring Gremlin Server from /Users/dingyuchen/Desktop/hugegraph/apache-hugegraph-incubating-1.0.0/conf/gremlin-server.yaml
+>>>> query all vertices: size=6
+>>>> query all edges: size=6
+```
+
+并且使用 RESTful API 请求 `HugeGraphServer` 得到如下结果：
+
+```javascript
+> curl "http://localhost:8080/graphs/hugegraph/graph/vertices" | gunzip
+
+  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
+                                 Dload  Upload   Total   Spent    Left  Speed
+100   222  100   222    0     0   3163      0 --:--:-- --:--:-- --:--:--  3964
+{"vertices":[{"id":"2:lop","label":"software","type":"vertex","properties":{"name":"lop","lang":"java","price":328}},{"id":"1:josh","label":"person","type":"vertex","properties":{"name":"josh","age":32,"city":"Beijing"}},{"id":"1:marko","label":"person","type":"vertex","properties":{"name":"marko","age":29,"city":"Beijing"}},{"id":"1:peter","label":"person","type":"vertex","properties":{"name":"peter","age":35,"city":"Shanghai"}},{"id":"1:vadas","label":"person","type":"vertex","properties":{"name":"vadas","age":27,"city":"Hongkong"}},{"id":"2:ripple","label":"software","type":"vertex","properties":{"name":"ripple","lang":"java","price":199}}]}
+```
+
+代表创建示例图成功。
+
+> 使用 IntelliJ IDEA 在启动 Server 时创建示例图的流程类似，不再赘述。