Merge branch 'develop' into xiaoping/cases

docs-cn/13-operation/01-pkg-install.md

 ---
-title: 安装、卸载、启动和停止
+title: 安装和卸载
+description: 安装、卸载、启动、停止和升级
 ---
 
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
 TDengine 开源版本提供 deb 和 rpm 格式安装包，用户可以根据自己的运行环境选择合适的安装包。其中 deb 支持 Debian/Ubuntu 及衍生系统，rpm 支持 CentOS/RHEL/SUSE 及衍生系统。同时我们也为企业用户提供 tar.gz 格式安装包。
 
-## deb 包的安装和卸载
+## 安装
 
-### 安装 deb
+<Tabs>
+<TabItem label="Deb 安装" value="debinst">
 
 1、从官网下载获得 deb 安装包，例如 TDengine-server-2.4.0.7-Linux-x64.deb；
 2、进入到 TDengine-server-2.4.0.7-Linux-x64.deb 安装包所在目录，执行如下的安装命令：
@@ -36,24 +41,9 @@ To access TDengine    : taos -h ubuntu-1804 to login into TDengine server
 TDengine is installed successfully!
 ```
 
-注：当安装第一个节点时，出现 Enter FQDN：提示的时候，不需要输入任何内容。只有当安装第二个或以后更多的节点时，才需要输入已有集群中任何一个可用节点的 FQDN，支持该新节点加入集群。当然也可以不输入，而是在新节点启动前，配置到新节点的配置文件中。
-
-后续两种安装包也是同样的操作。
-
-### 卸载 deb
+</TabItem>
 
-卸载命令如下:
-
-```
-$ sudo dpkg -r tdengine
-(Reading database ... 137504 files and directories currently installed.)
-Removing tdengine (2.4.0.7) ...
-TDengine is removed successfully!
-```
-
-## rpm 包的安装和卸载
-
-### 安装 rpm
+<TabItem label="RPM 安装" value="rpminst">
 
 1、从官网下载获得 rpm 安装包，例如 TDengine-server-2.4.0.7-Linux-x64.rpm；
 2、进入到 TDengine-server-2.4.0.7-Linux-x64.rpm 安装包所在目录，执行如下的安装命令：
@@ -82,18 +72,9 @@ To access TDengine    : taos -h centos7 to login into TDengine server
 TDengine is installed successfully!
 ```
 
-### 卸载 rpm
-
-卸载命令如下:
-
-```
-$ sudo rpm -e tdengine
-TDengine is removed successfully!
-```
-
-## tar.gz 格式安装包的安装和卸载
+</TabItem>
 
-### 安装 tar.gz 安装包
+<TabItem label="tar.gz 安装" value="tarinst">
 
 1、从官网下载获得 tar.gz 安装包，例如 TDengine-server-2.4.0.7-Linux-x64.tar.gz；
 2、进入到 TDengine-server-2.4.0.7-Linux-x64.tar.gz 安装包所在目录，先解压文件后，进入子目录，执行其中的 install.sh 安装脚本：
@@ -142,9 +123,48 @@ Install taoskeeper as a standalone service
 taoskeeper is installed, enable it by `systemctl enable taoskeeper`
 ```
 
-说明：install.sh 安装脚本在执行过程中，会通过命令行交互界面询问一些配置信息。如果希望采取无交互安装方式，那么可以用 -e no 参数来执行 install.sh 脚本。运行 `./install.sh -h` 指令可以查看所有参数的详细说明信息。
+:::info
+install.sh 安装脚本在执行过程中，会通过命令行交互界面询问一些配置信息。如果希望采取无交互安装方式，那么可以用 -e no 参数来执行 install.sh 脚本。运行 `./install.sh -h` 指令可以查看所有参数的详细说明信息。
 
-### tar.gz 安装后的卸载
+:::
+
+</TabItem>
+</Tabs>
+
+:::note
+当安装第一个节点时，出现 Enter FQDN：提示的时候，不需要输入任何内容。只有当安装第二个或以后更多的节点时，才需要输入已有集群中任何一个可用节点的 FQDN，支持该新节点加入集群。当然也可以不输入，而是在新节点启动前，配置到新节点的配置文件中。
+
+:::
+
+## 卸载
+
+<Tabs>
+<TabItem label="Deb 卸载" value="debuninst">
+
+卸载命令如下:
+
+```
+$ sudo dpkg -r tdengine
+(Reading database ... 137504 files and directories currently installed.)
+Removing tdengine (2.4.0.7) ...
+TDengine is removed successfully!
+
+```
+
+</TabItem>
+
+<TabItem label="RPM 卸载" value="rpmuninst">
+
+卸载命令如下:
+
+```
+$ sudo rpm -e tdengine
+TDengine is removed successfully!
+```
+
+</TabItem>
+
+<TabItem label="tar.gz 卸载" value="taruninst">
 
 卸载命令如下:
 
@@ -156,6 +176,30 @@ TDengine is removed successfully!
 taosKeeper is removed successfully!
 ```
 
+</TabItem>
+</Tabs>
+
+:::info
+- TDengine 提供了多种安装包，但最好不要在一个系统上同时使用 tar.gz 安装包和 deb 或 rpm 安装包。否则会相互影响，导致在使用时出现问题。
+
+- 对于 deb 包安装后，如果安装目录被手工误删了部分，出现卸载、或重新安装不能成功。此时，需要清除 TDengine 包的安装信息，执行如下命令：
+
+   ```
+   $ sudo rm -f /var/lib/dpkg/info/tdengine*
+   ```
+
+然后再重新进行安装就可以了。
+
+- 对于 rpm 包安装后，如果安装目录被手工误删了部分，出现卸载、或重新安装不能成功。此时，需要清除 TDengine 包的安装信息，执行如下命令：
+
+   ```
+   $ sudo rpm -e --noscripts tdengine
+   ```
+
+然后再重新进行安装就可以了。
+
+:::
+
 ## 安装目录说明
 
 TDengine 成功安装后，主安装目录是 /usr/local/taos，目录内容如下：
@@ -190,7 +234,7 @@ lrwxrwxrwx  1 root root   13 Feb 22 09:34 log -> /var/log/taos/
 
 如果是更新安装，当缺省配置文件（ /etc/taos/taos.cfg ）存在时，仍然使用已有的配置文件，安装包中携带的配置文件修改为 taos.cfg.orig 保存在 /usr/local/taos/cfg/ 目录，可以作为设置配置参数的参考样例；如果不存在配置文件，就使用安装包中自带的配置文件。
 
-## TDengine 的启动、停止、卸载
+## 启动和停止
 
 TDengine 使用 Linux 系统的 systemd/systemctl/service 来管理系统的启动和、停止、重启操作。TDengine 的服务进程是 taosd，默认情况下 TDengine 在系统启动后将自动启动。DBA 可以通过 systemd/systemctl/service 手动操作停止、启动、重新启动服务。
 
@@ -208,40 +252,32 @@ TDengine 使用 Linux 系统的 systemd/systemctl/service 来管理系统的启
 
 如果服务进程处于活动状态，则 status 指令会显示如下的相关信息：
 
-```
-......
-
-Active: active (running)
-
-......
-```
+   ```
+   Active: active (running)
+   ```
 
 如果后台服务进程处于停止状态，则 status 指令会显示如下的相关信息：
 
-```
-......
-
-Active: inactive (dead)
-
-......
-```
-
-## 注意事项
-
-- TDengine 提供了多种安装包，但最好不要在一个系统上同时使用 tar.gz 安装包和 deb 或 rpm 安装包。否则会相互影响，导致在使用时出现问题。
-
-- 对于 deb 包安装后，如果安装目录被手工误删了部分，出现卸载、或重新安装不能成功。此时，需要清除 TDengine 包的安装信息，执行如下命令：
+   ```
+   Active: inactive (dead)
+   ```
 
-```
-$ sudo rm -f /var/lib/dpkg/info/tdengine*
-```
+## 升级
+升级分为两个层面：升级安装包 和 升级运行中的实例。
 
-然后再重新进行安装就可以了。
+升级安装包请遵循前述安装和卸载的步骤先卸载旧版本再安装新版本。
 
-- 对于 rpm 包安装后，如果安装目录被手工误删了部分，出现卸载、或重新安装不能成功。此时，需要清除 TDengine 包的安装信息，执行如下命令：
+升级运行中的实例则要复杂得多，首先请注意版本号，TDengine 的版本号目前分为四段，如 2.4.0.14 和 2.4.0.16，只有前三段版本号一致（即只有第四段版本号不同）才能把一个运行中的实例进行升级。升级步骤如下：
+- 停止数据写入
+- 确保所有数据落盘，即写入时序数据库
+- 停止 TDengine 集群
+- 卸载旧版本并安装新版本
+- 重新启动 TDengine 集群
+- 进行简单的查询操作确认旧数据没有丢失 
+- 进行简单的写入操作确认 TDengine 集群可用
+- 重新恢复业务数据的写入
 
-```
-$ sudo rpm -e --noscripts tdengine
-```
+:::warning
+TDengine 不保证低版本能够兼容高版本的数据，所以任何时候都不推荐降级
 
-然后再重新进行安装就可以了。
+:::
\ No newline at end of file

docs-cn/14-reference/03-connector/java.mdx

@@ -2,24 +2,24 @@
 toc_max_heading_level: 4
 sidebar_position: 2
 sidebar_label: Java
-title: Java Connector
-description: 此连接器基于标准 JDBC API 实现。
+title: TDengine Java Connector
+description: TDengine Java 连接器基于标准 JDBC API 实现, 并提供原生连接与 REST连接两种连接器。
 ---
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 
-`taos-jdbcdriver` 是 TDengine 的官方 Java 语言连接器。Java 开发人员可以通过它开发存取 TDengine 数据库的应用软件。
-
-`taos-jdbcdriver` 实现了 JDBC driver 标准的接口。支持通过客户端驱动程序（taosc）原生连接 TDengine 集群，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能。`taos-jdbcdriver`（2.0.18 及更高版本）也支持使用 REST 连接 TDengine 集群。REST 连接实现的功能集合和原生连接有少量不同。
+`taos-jdbcdriver` 是 TDengine 的官方 Java 语言连接器, Java 开发人员可以通过它开发存取 TDengine 数据库的应用软件。`taos-jdbcdriver` 实现了 JDBC driver 标准的接口，并提供两种形式的连接器。一种是通过 TDengine 客户端驱动程序（taosc）原生连接 TDengine 实例，支持数据写入、查询、订阅、schemaless 接口和参数绑定接口等功能，一种是通过 taosAdapter 提供的 REST 接口连接 TDengine 实例（2.0.18 及更高版本）。REST 连接实现的功能集合和原生连接有少量不同。
 
 ![tdengine-connector](tdengine-jdbc-connector.png)
 
-上图显示了两种 Java 应用使用连接器访问 TDengine 的方式：
+上图显示了两种 Java 应用使用连接器访问 TDengine 的两种方式：
 
 - JDBC 原生连接：Java 应用在物理节点 1（pnode1）上使用 TSDBDriver 直接调用客户端驱动（libtaos.so 或 taos.dll）的 API 将写入和查询请求发送到位于物理节点 2（pnode2）上的 taosd 实例。
 - JDBC REST 连接：Java 应用通过 RestfulDriver 将 SQL 封装成一个 REST 请求，发送给物理节点 2 的 REST 服务器（taosAdapter），通过 REST 服务器请求 taosd 并返回结果。
 
+使用 REST 连接器，不依赖 TDengine 客户端驱动，可以跨平台，更加方便灵活，但性能比原生连接器低约30%。
+
 :::info
 TDengine 的 JDBC 驱动实现尽可能与关系型数据库驱动保持一致，但 TDengine 与关系对象型数据库的使用场景和技术特征存在差异，所以`taos-jdbcdriver` 与传统的 JDBC driver 也存在一定差异。在使用时需要注意以下几点：
 
@@ -63,7 +63,9 @@ TDengine 目前支持时间戳、数字、字符、布尔类型，与 Java 对
 使用 Java Connector 连接数据库前，需要具备以下条件：
 
 - 已安装 Java 1.8 或以上版本运行时环境和 Maven 3.6 或以上版本
-- 已安装客户端驱动（使用原生连接必须安装，使用 REST 连接无需安装），具体步骤请参考[安装客户端驱动](/reference/connector#安装客户端驱动)
+- 已安装 TDengine 客户端驱动（使用原生连接必须安装，使用 REST 连接无需安装），具体步骤请参考[安装客户端驱动](/reference/connector#安装客户端驱动)
+
+### 安装连接器
 
 <Tabs defaultValue="maven">
 <TabItem value="maven" label="使用 Maven 安装">
@@ -105,8 +107,10 @@ mvn clean install -Dmaven.test.skip=true
 TDengine 的 JDBC URL 规范格式为：
 `jdbc:[TAOS|TAOS-RS]://[host_name]:[port]/[database_name]?[user={user}|&password={password}|&charset={charset}|&cfgdir={config_dir}|&locale={locale}|&timezone={timezone}]`
 
+对于建立连接，原生连接器与 REST 连接器有细微不同。
+
 <Tabs defaultValue="native">
-<TabItem value="native" label="建立原生连接">
+<TabItem value="native" label="原生连接器">
 
 ```java
 Class.forName("com.taosdata.jdbc.TSDBDriver");
@@ -131,9 +135,9 @@ url 中的配置参数如下：
 
 JDBC 原生连接的使用请参见[视频教程](https://www.taosdata.com/blog/2020/11/11/1955.html)。
 
-#### 使用客户端配置文件建立连接
+**使用 TDengine 客户端驱动配置文件建立连接 **
 
-当使用 JDBC 原生连接连接 TDengine 集群时，可以使用客户端配置文件，在客户端配置文件中指定集群的 firstEp、secondEp 参数。如下所示：
+当使用 JDBC 原生连接连接 TDengine 集群时，可以使用 TDengine 客户端驱动配置文件，在配置文件中指定集群的 firstEp、secondEp 等参数。如下所示：
 
 1. 在 Java 应用中不指定 hostname 和 port
 
@@ -173,7 +177,7 @@ TDengine 中，只要保证 firstEp 和 secondEp 中一个节点有效，就可
 > **注意**：这里的配置文件指的是调用 JDBC Connector 的应用程序所在机器上的配置文件，Linux OS 上默认值 /etc/taos/taos.cfg ，Windows OS 上默认值 C://TDengine/cfg/taos.cfg。
 
 </TabItem>
-<TabItem value="rest" label="建立 REST 连接">
+<TabItem value="rest" label="REST 连接器">
 
 ```java
 Class.forName("com.taosdata.jdbc.rs.RestfulDriver");
@@ -266,7 +270,7 @@ properties 中的配置参数如下：
 
 1. JDBC URL 参数，如上所述，可以在 JDBC URL 的参数中指定。
 2. Properties connProps
-3. 客户端配置文件 taos.cfg
+3. 使用原生连接时，TDengine 客户端驱动的配置文件 taos.cfg
 
 例如：在 url 中指定了 password 为 taosdata，在 Properties 中指定了 password 为 taosdemo，那么，JDBC 会使用 url 中的 password 建立连接。
 
@@ -652,7 +656,11 @@ public class SchemalessInsertTest {
 }
 ```
 
-### 创建订阅
+### 订阅
+
+TDengine Java 连机器支持订阅功能，应用 API 如下：
+
+#### 创建订阅
 
 ```java
 TSDBSubscribe sub = ((TSDBConnection)conn).subscribe("topic", "select * from meters", false);
@@ -666,7 +674,7 @@ TSDBSubscribe sub = ((TSDBConnection)conn).subscribe("topic", "select * from met
 
 如上面的例子将使用 SQL 语句 `select * from meters` 创建一个名为 `topic` 的订阅，如果这个订阅已经存在，将继续之前的查询进度，而不是从头开始消费所有的数据。
 
-### 订阅消费数据
+#### 订阅消费数据
 
 ```java
 int total = 0;
@@ -684,7 +692,7 @@ while(true) {
 
 `consume` 方法返回一个结果集，其中包含从上次 `consume` 到目前为止的所有新数据。请务必按需选择合理的调用 `consume` 的频率（如例子中的 `Thread.sleep(1000)`），否则会给服务端造成不必要的压力。
 
-### 关闭订阅
+#### 关闭订阅
 
 ```java
 sub.close(true);