diff --git a/docs-en/27-train-faq/01-faq.md b/docs-en/27-train-faq/01-faq.md index fac12cb44eaff68ec74d3019e537aecb0291410f..bd93c18ae8e80a1d45369722df1f0659b8124969 100644 --- a/docs-en/27-train-faq/01-faq.md +++ b/docs-en/27-train-faq/01-faq.md @@ -1,224 +1,115 @@ --- -title: 常见问题及反馈 +sidebar_label: FAQ +title: Frequently Asked Questions --- -## 问题反馈 +## Submit an Issue -如果 FAQ 中的信息不能够帮到您，需要 TDengine 技术团队的技术支持与协助，请将以下两个目录中内容打包： +If the tips in FAQ don't help much, please submit an issue on [GitHub](https://github.com/taosdata/TDengine) to describe your problem description, including TDengine version, hardware and OS information, the steps to reproduce the problem, etc. It would be very helpful if you package the contents in `/var/log/taos` and `/etc/taos` and upload. These two are the default directories used by TDengine, if they have been changed in your configuration, please use according to the actual configuration. It's recommended to firstly set `debugFlag` to 135 in `taos.cfg`, restart `taosd`, then reproduce the problem and collect logs. If you don't want to restart, an alternative way of setting `debugFlag` is executing `alter dnode debugFlag 135` command in TDengine CLI `taos`. During normal running, however, please make sure `debugFlag` is set to 131. -1. /var/log/taos （如果没有修改过默认路径） -2. /etc/taos +## Frequently Asked Questions -附上必要的问题描述，包括使用的 TDengine 版本信息、平台环境信息、发生该问题的执行操作、出现问题的表征及大概的时间，在 [GitHub](https://github.com/taosdata/TDengine) 提交 issue。 +**1. How to upgrade to TDengine 2.0 from older version? ☆☆☆** -为了保证有足够的 debug 信息，如果问题能够重复，请修改/etc/taos/taos.cfg 文件，最后面添加一行“debugFlag 135"(不带引号本身），然后重启 taosd, 重复问题，然后再递交。也可以通过如下 SQL 语句，临时设置 taosd 的日志级别。 + version 2.x is not compatible with version 1.x regarding configuration file and data file, please do following before upgrading: -``` - alter dnode debugFlag 135; -``` + 1. Delete configuration files: `sudo rm -rf /etc/taos/taos.cfg` + 2. Delete log files: `sudo rm -rf /var/log/taos/` + 3. Delete data files if the data doesn't need to be kept: `sudo rm -rf /var/lib/taos/` + 4. Install latests 2.x version + 5. If the data needs to be kept and migrated to newer version, please contact professional service of TDengine for assistance -但系统正常运行时，请一定将 debugFlag 设置为 131，否则会产生大量的日志信息，降低系统效率。 +**2. How to handle "Unable to establish connection"** -## 常见问题列表 + When the client is unable to connect to the server, you can try following ways to find out why. -**1. TDengine2.0 之前的版本升级到 2.0 及以上的版本应该注意什么？☆☆☆** + 1. Check the network - 2.0 版在之前版本的基础上，进行了完全的重构，配置文件和数据文件是不兼容的。在升级之前务必进行如下操作： + - Check if the hosts where the client and server are running can be accessible to each other, for example by `ping` command. + - Check if the TCP/UDP on port 6030-6042 are open for access if firewall is enabled. It's better to firstly disable firewall for diagnostics. + - Check if the FQDN and serverPort are configured correctly in `taos.cfg` used by the server side + - Check if the `firstEp` is set properly in the `taos.cfg` used by the client side - 1. 删除配置文件，执行 `sudo rm -rf /etc/taos/taos.cfg` - 2. 删除日志文件，执行 `sudo rm -rf /var/log/taos/` - 3. 确保数据已经不再需要的前提下，删除数据文件，执行 `sudo rm -rf /var/lib/taos/` - 4. 安装最新稳定版本的 TDengine - 5. 如果需要迁移数据或者数据文件损坏，请联系涛思数据官方技术支持团队，进行协助解决 + 2. Make sure the client version and server version are same. -**2. Windows 平台下 JDBCDriver 找不到动态链接库，怎么办？** + 3. On server side, check the running status of `taosd` by executing `systemctl status taosd` . If your server is started using another way instead of `systemctl`, use the proper method to check whether the server process is running normally. - 请看为此问题撰写的[技术博客](https://www.taosdata.com/blog/2019/12/03/950.html)。 + 4. If using connector of Python, Java, Go, Rust, C#, node.JS on Linux to connect toe the server, please make sure `libtaos.so` is in directory `/usr/local/taos/driver` and `/usr/local/taos/driver` is in system lib search environment variable `LD_LIBRARY_PATH`. -**3. 创建数据表时提示 more dnodes are needed** + 5. If using connector on Windows, please make sure `C:\TDengine\driver\taos.dll` is in your system lib search path, it's suggested to put `taos.dll` under `C:\Windows\System32`. - 请看为此问题撰写的[技术博客](https://www.taosdata.com/blog/2019/12/03/965.html)。 + 6. Some advanced network diagnostics tools -**4. 如何让 TDengine crash 时生成 core 文件？** + - On Linux system tool `nc` can be used to check whether the TCP/UDP can be accessible on a specified port + Check whether a UDP port is open: `nc -vuz {hostIP} {port} ` + Check whether a TCP port on server side is open: `nc -l {port}` + Check whether a TCP port on client side is open: `nc {hostIP} {port}` - 请看为此问题撰写的[技术博客](https://www.taosdata.com/blog/2019/12/06/974.html)。 + - On Windows system `Net-TestConnection -ComputerName {fqdn} -Port {port}` on PowerShell can be used to check whether the port on serer side is open for access. -**5. 遇到错误“Unable to establish connection”, 我怎么办？** + 7. TDengine CLI `taos` can also be used to check network, please refer to [TDengine CLI](/reference/taos-shell). - 客户端遇到连接故障，请按照下面的步骤进行检查： +**3. How to handle "Unexpected generic error in RPC" or "Unable to resolve FQDN" ?** - 1. 检查网络环境 + This error is caused because the FQDN can't be resolved. Please try following ways: - - 云服务器：检查云服务器的安全组是否打开 TCP/UDP 端口 6030-6042 的访问权限 - - 本地虚拟机：检查网络能否 ping 通，尽量避免使用`localhost` 作为 hostname - - 公司服务器：如果为 NAT 网络环境，请务必检查服务器能否将消息返回值客户端 + 1. Check whether the FQDN is configured properly on the server side + 2. If DSN server is configured in the network, please check whether it works; otherwise, check `/etc/hosts` to see whether the FQDN is configured with correct IP + 3. If the network configuration on the server side is OK, try to ping the server from the client side. + 4. If TDengine has been used before with an old hostname then the hostname has been changed, please check `/var/lib/taos/taos/dnode/dnodeEps.json`. Before setting up a new TDengine cluster, it's better to cleanup the directories configured. - 2. 确保客户端与服务端版本号是完全一致的，开源社区版和企业版也不能混用 +**4. "Invalid SQL" is returned even though the Syntax is correct** - 3. 在服务器，执行 `systemctl status taosd` 检查*taosd*运行状态。如果没有运行，启动*taosd* + "Invalid SQL" is returned when the length of SQL statement exceeds maximum allowed length or the syntax is not correct. - 4. 确认客户端连接时指定了正确的服务器 FQDN (Fully Qualified Domain Name —— 可在服务器上执行 Linux 命令 hostname -f 获得），FQDN 配置参考：[一篇文章说清楚 TDengine 的 FQDN](https://www.taosdata.com/blog/2020/09/11/1824.html)。 +**5. Whether validation queries are supported?** - 5. ping 服务器 FQDN，如果没有反应，请检查你的网络，DNS 设置，或客户端所在计算机的系统 hosts 文件。如果部署的是 TDengine 集群，客户端需要能 ping 通所有集群节点的 FQDN。 - - 6. 检查防火墙设置（Ubuntu 使用 ufw status，CentOS 使用 firewall-cmd --list-port），确认 TCP/UDP 端口 6030-6042 是打开的 - - 7. 对于 Linux 上的 JDBC（ODBC, Python, Go 等接口类似）连接, 确保*libtaos.so*在目录*/usr/local/taos/driver*里, 并且*/usr/local/taos/driver*在系统库函数搜索路径*LD_LIBRARY_PATH*里 - - 8. 对于 Windows 上的 JDBC, ODBC, Python, Go 等连接，确保*C:\TDengine\driver\taos.dll*在你的系统库函数搜索目录里 (建议*taos.dll*放在目录 _C:\Windows\System32_) - - 9. 如果仍不能排除连接故障 - - - Linux 系统请使用命令行工具 nc 来分别判断指定端口的 TCP 和 UDP 连接是否通畅 - 检查 UDP 端口连接是否工作：`nc -vuz {hostIP} {port} ` - 检查服务器侧 TCP 端口连接是否工作：`nc -l {port}` - 检查客户端侧 TCP 端口连接是否工作：`nc {hostIP} {port}` - - - Windows 系统请使用 PowerShell 命令 Net-TestConnection -ComputerName {fqdn} -Port {port} 检测服务段端口是否访问 - - 10. 也可以使用 taos 程序内嵌的网络连通检测功能，来验证服务器和客户端之间指定的端口连接是否通畅（包括 TCP 和 UDP）：[TDengine 内嵌网络检测工具使用指南](https://www.taosdata.com/blog/2020/09/08/1816.html)。 - -**6. 遇到错误“Unexpected generic error in RPC”或者“Unable to resolve FQDN”，我怎么办？** - - 产生这个错误，是由于客户端或数据节点无法解析 FQDN(Fully Qualified Domain Name)导致。对于 TAOS Shell 或客户端应用，请做如下检查： - - 1. 请检查连接的服务器的 FQDN 是否正确，FQDN 配置参考：[一篇文章说清楚 TDengine 的 FQDN](https://www.taosdata.com/blog/2020/09/11/1824.html) - 2. 如果网络配置有 DNS server，请检查是否正常工作 - 3. 如果网络没有配置 DNS server，请检查客户端所在机器的 hosts 文件，查看该 FQDN 是否配置，并是否有正确的 IP 地址 - 4. 如果网络配置 OK，从客户端所在机器，你需要能 Ping 该连接的 FQDN，否则客户端是无法连接服务器的 - 5. 如果服务器曾经使用过 TDengine，且更改过 hostname，建议检查 data 目录的 dnodeEps.json 是否符合当前配置的 EP，路径默认为/var/lib/taos/dnode。正常情况下，建议更换新的数据目录或者备份后删除以前的数据目录，这样可以避免该问题。 - 6. 检查/etc/hosts 和/etc/hostname 是否是预配置的 FQDN - -**7. 虽然语法正确，为什么我还是得到 "Invalid SQL" 错误** - - 如果你确认语法正确，2.0 之前版本，请检查 SQL 语句长度是否超过 64K。如果超过，也会返回这个错误。 - -**8. 是否支持 validation queries？** - - TDengine 还没有一组专用的 validation queries。然而建议你使用系统监测的数据库”log"来做。 + It's suggested to use a builtin database named as `log` to monitor. -**9. 我可以删除或更新一条记录吗？** - - TDengine 目前尚不支持删除功能，未来根据用户需求可能会支持。 - - 从 2.0.8.0 开始，TDengine 支持更新已经写入数据的功能。使用更新功能需要在创建数据库时使用 UPDATE 1 参数，之后可以使用 INSERT INTO 命令更新已经写入的相同时间戳数据。UPDATE 参数不支持 ALTER DATABASE 命令修改。没有使用 UPDATE 1 参数创建的数据库，写入相同时间戳的数据不会修改之前的数据，也不会报错。 +**6. Can I delete a record?** - 另需注意，在 UPDATE 设置为 0 时，后发送的相同时间戳的数据会被直接丢弃，但并不会报错，而且仍然会被计入 affected rows （所以不能利用 INSERT 指令的返回信息进行时间戳查重）。这样设计的主要原因是，TDengine 把写入的数据看做一个数据流，无论时间戳是否出现冲突，TDengine 都认为产生数据的原始设备真实地产生了这样的数据。UPDATE 参数只是控制这样的流数据在进行持久化时要怎样处理——UPDATE 为 0 时，表示先写入的数据覆盖后写入的数据；而 UPDATE 为 1 时，表示后写入的数据覆盖先写入的数据。这种覆盖关系如何选择，取决于对数据的后续使用和统计中，希望以先还是后生成的数据为准。 + From version 2.6.0.0 Enterprise version, deleting data can be supported. - 此外，从 2.1.7.0 版本开始，支持将 UPDATE 参数设为 2，表示“支持部分列更新”。也即，当 UPDATE 设为 1 时，如果更新一个数据行，其中某些列没有提供取值，那么这些列会被设为 NULL；而当 UPDATE 设为 2 时，如果更新一个数据行，其中某些列没有提供取值，那么这些列会保持原有数据行中的对应值。 +**7. How to create a table of over 1024 columns?** -**10. 我怎么创建超过 1024 列的表？** + From version 2.1.7.0, at most 4096 columns can be defined for a table. - 使用 2.0 及其以上版本，默认支持 1024 列；2.0 之前的版本，TDengine 最大允许创建 250 列的表。但是如果确实超过限值，建议按照数据特性，逻辑地将这个宽表分解成几个小表。（从 2.1.7.0 版本开始，表的最大列数增加到了 4096 列。） +**8. How to improve the efficiency of inserting data?** -**11. 最有效的写入数据的方法是什么？** + Inserting data in batch is a good practice. Single SQL statement can insert data for one or multiple tables in batch. - 批量插入。每条写入语句可以一张表同时插入多条记录，也可以同时插入多张表的多条记录。 +**9. JDBC Error： the excuted SQL is not a DML or a DDL？** -**12. Windows 系统下插入的 nchar 类数据中的汉字被解析成了乱码如何解决？** + Please upgrade to latest JDBC driver, for details please refer to [Java Connector](/reference/connector/java) - Windows 下插入 nchar 类的数据中如果有中文，请先确认系统的地区设置成了中国（在 Control Panel 里可以设置），这时 cmd 中的`taos`客户端应该已经可以正常工作了；如果是在 IDE 里开发 Java 应用，比如 Eclipse， Intellij，请确认 IDE 里的文件编码为 GBK（这是 Java 默认的编码类型），然后在生成 Connection 时，初始化客户端的配置，具体语句如下： +**10. Failed to connect with error "invalid timestamp"** - ```JAVA - Class.forName("com.taosdata.jdbc.TSDBDriver"); - Properties properties = new Properties(); - properties.setProperty(TSDBDriver.LOCALE_KEY, "UTF-8"); - Connection = DriverManager.getConnection(url, properties); - ``` - -**13.JDBC 报错： the excuted SQL is not a DML or a DDL？** - - 请更新至最新的 JDBC 驱动 - - ```xml - - com.taosdata.jdbc - taos-jdbcdriver - 2.0.27 - - ``` + The most common reason is that the time setting is not aligned on the client side and the server side. On Linux system, please use `ntpdate` command. On Windows system, please enable automatic sync in system time setting. -**14. taos connect failed, reason: invalid timestamp** +**11. Table name is not shown in full** - 常见原因是服务器和客户端时间没有校准，可以通过和时间服务器同步的方式（Linux 下使用 ntpdate 命令，Windows 在系统时间设置中选择自动同步）校准。 + There is a display width setting in TDengine CLI `taos`. It can be controlled by configuration parameter `maxBinaryDisplayWidth`, or can be set using SQL command `set max_binary_display_width`. A more convenient way is to append `\G` in a SQL command to bypass this limitation. -**15. 表名显示不全** +**12. How to change log level temporarily?** - 由于 taos shell 在终端中显示宽度有限，有可能比较长的表名显示不全，如果按照显示的不全的表名进行相关操作会发生 Table does not exist 错误。解决方法可以是通过修改 taos.cfg 文件中的设置项 maxBinaryDisplayWidth， 或者直接输入命令 set max_binary_display_width 100。或者在命令结尾使用 \G 参数来调整结果的显示方式。 - -**16. 如何进行数据迁移？** - - TDengine 是根据 hostname 唯一标志一台机器的，在数据文件从机器 A 移动机器 B 时，注意如下两件事： - - - 2.0.0.0 至 2.0.6.x 的版本，重新配置机器 B 的 hostname 为机器 A 的 hostname。 - - 2.0.7.0 及以后的版本，到/var/lib/taos/dnode 下，修复 dnodeEps.json 的 dnodeId 对应的 FQDN，重启。确保机器内所有机器的此文件是完全相同的。 - - 1.x 和 2.x 版本的存储结构不兼容，需要使用迁移工具或者自己开发应用导出导入数据。 - -**17. 如何在命令行程序 taos 中临时调整日志级别** - - 为了调试方便，从 2.0.16 版本开始，命令行程序 taos 新增了与日志记录相关的两条指令： + Below SQL command can be used to adjust log level temporarily ```sql ALTER LOCAL flag_name flag_value; ``` - - 其含义是，在当前的命令行程序下，修改一个特定模块的日志记录级别（只对当前命令行程序有效，如果 taos 命令行程序重启，则需要重新设置）： - - - flag_name 的取值可以是：debugFlag，cDebugFlag，tmrDebugFlag，uDebugFlag，rpcDebugFlag - - flag_value 的取值可以是：131（输出错误和警告日志），135（ 输出错误、警告和调试日志），143（ 输出错误、警告、调试和跟踪日志） - - ```sql - ALTER LOCAL RESETLOG; - ``` - - 其含义是，清空本机所有由客户端生成的日志文件。 + - flag_name can be: debugFlag，cDebugFlag，tmrDebugFlag，uDebugFlag，rpcDebugFlag + - flag_value can be: 131 (INFO/WARNING/ERROR), 135 (plus DEBUG), 143 (plus TRACE) -**18. 时间戳的时区信息是怎样处理的？** - - TDengine 中时间戳的时区总是由客户端进行处理，而与服务端无关。具体来说，客户端会对 SQL 语句中的时间戳进行时区转换，转为 UTC 时区（即 Unix 时间戳——Unix Timestamp）再交由服务端进行写入和查询；在读取数据时，服务端也是采用 UTC 时区提供原始数据，客户端收到后再根据本地设置，把时间戳转换为本地系统所要求的时区进行显示。 - - 客户端在处理时间戳字符串时，会采取如下逻辑： - - 1. 在未做特殊设置的情况下，客户端默认使用所在操作系统的时区设置。 - 2. 如果在 taos.cfg 中设置了 timezone 参数，则客户端会以这个配置文件中的设置为准。 - 3. 如果在 C/C++/Java/Python 等各种编程语言的 Connector Driver 中，在建立数据库连接时显式指定了 timezone，那么会以这个指定的时区设置为准。例如 Java Connector 的 JDBC URL 中就有 timezone 参数。 - 4. 在书写 SQL 语句时，也可以直接使用 Unix 时间戳（例如 `1554984068000`）或带有时区的时间戳字符串，也即以 RFC 3339 格式（例如 `2013-04-12T15:52:01.123+08:00`）或 ISO-8601 格式（例如 `2013-04-12T15:52:01.123+0800`）来书写时间戳，此时这些时间戳的取值将不再受其他时区设置的影响。 - - -**19. TDengine 都会用到哪些网络端口？** +**13. Hhat to do if go compilation fails?** - 在 TDengine 2.0 版本中，会用到以下这些网络端口（以默认端口 6030 为前提进行说明，如果修改了配置文件中的设置，那么这里列举的端口都会出现变化），管理员可以参考这里的信息调整防火墙设置： - -| 协议 | 默认端口 | 用途说明 | 修改方法 | -| :--- | :-------- | :---------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------- | -| TCP | 6030 | 客户端与服务端之间通讯。 | 由配置文件设置 serverPort 决定。 | -| TCP | 6035 | 多节点集群的节点间通讯。 | 随 serverPort 端口变化。 | -| TCP | 6040 | 多节点集群的节点间数据同步。 | 随 serverPort 端口变化。 | -| TCP | 6041 | 客户端与服务端之间的 RESTful 通讯。 | 随 serverPort 端口变化。注意 taosAdapter 配置或有不同，请参考相应[文档](/reference/taosadapter/)。 | -| TCP | 6042 | Arbitrator 的服务端口。 | 随 Arbitrator 启动参数设置变化。 | -| TCP | 6043 | TaosKeeper 监控服务端口。 | 随 TaosKeeper 启动参数设置变化。 | -| TCP | 6044 | 支持 StatsD 的数据接入端口。 | 随 taosAdapter 启动参数设置变化（2.3.0.1+以上版本）。 | -| TCP | 6045 | 支持 collectd 数据接入端口。 | 随 taosAdapter 启动参数设置变化（2.3.0.1+以上版本）。 | -| TCP | 6060 | 企业版内 Monitor 服务的网络端口。 | | -| UDP | 6030-6034 | 客户端与服务端之间通讯。 | 随 serverPort 端口变化。 | -| UDP | 6035-6039 | 多节点集群的节点间通讯。 | 随 serverPort 端口变化。 | - -**20. go 语言编写组件编译失败怎样解决？** - - 新版本 TDengine 2.3.0.0 包含一个使用 go 语言开发的 taosAdapter 独立组件，需要单独运行，取代之前 taosd 内置的 httpd ，提供包含原 httpd 功能以及支持多种其他软件（Prometheus、Telegraf、collectd、StatsD 等）的数据接入功能。 - 使用最新 develop 分支代码编译需要先 `git submodule update --init --recursive` 下载 taosAdapter 仓库代码后再编译。 - - 目前编译方式默认自动编译 taosAdapter。go 语言版本要求 1.14 以上，如果发生 go 编译错误，往往是国内访问 go mod 问题，可以通过设置 go 环境变量来解决： + From version 2.3.0.0, a new component named `taosAdapter` is introduced. Its' developed in Go. If you want to compile from source code and meet go compilation problems, try to do below steps to resolve Go environment problems. ```sh go env -w GO111MODULE=on go env -w GOPROXY=https://goproxy.cn,direct ``` - - 如果希望继续使用之前的内置 httpd，可以关闭 taosAdapter 编译，使用 - `cmake .. -DBUILD_HTTP=true` 使用原来内置的 httpd。 diff --git a/docs-en/27-train-faq/02-video.mdx b/docs-en/27-train-faq/02-video.mdx deleted file mode 100644 index b644412332fe817ea7fdc2c9ddc176ecc9858c56..0000000000000000000000000000000000000000 --- a/docs-en/27-train-faq/02-video.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: 视频教程 ---- - -## 技术公开课 - -- [技术公开课：开源、高效的物联网大数据平台，TDengine 内核技术剖析](https://www.taosdata.com/blog/2020/12/25/2126.html) - -## 视频教程 - -- [TDengine 视频教程 - 快速上手](https://www.taosdata.com/blog/2020/11/11/1941.html) -- [TDengine 视频教程 - 数据建模](https://www.taosdata.com/blog/2020/11/11/1945.html) -- [TDengine 视频教程 - 集群搭建](https://www.taosdata.com/blog/2020/11/11/1961.html) -- [TDengine 视频教程 - Go Connector](https://www.taosdata.com/blog/2020/11/11/1951.html) -- [TDengine 视频教程 - JDBC Connector](https://www.taosdata.com/blog/2020/11/11/1955.html) -- [TDengine 视频教程 - Node.js Connector](https://www.taosdata.com/blog/2020/11/11/1957.html) -- [TDengine 视频教程 - Python Connector](https://www.taosdata.com/blog/2020/11/11/1963.html) -- [TDengine 视频教程 - RESTful Connector](https://www.taosdata.com/blog/2020/11/11/1965.html) -- [TDengine 视频教程 - “零”代码运维监控](https://www.taosdata.com/blog/2020/11/11/1959.html) - -## 微课堂 - -关注 TDengine 视频号， 有精心制作的微课堂。 - - diff --git a/docs-en/27-train-faq/03-docker.md b/docs-en/27-train-faq/03-docker.md index 845a8751846c0995a43fb1c01e6ace3080176838..0bcc39f903c635aed7fe8c850d8b706f6ba92293 100644 --- a/docs-en/27-train-faq/03-docker.md +++ b/docs-en/27-train-faq/03-docker.md @@ -1,83 +1,84 @@ --- -title: 通过 Docker 快速体验 TDengine +sidebar_label: TDengine in Docker +title: Deploy TDengine in Docker --- -虽然并不推荐在生产环境中通过 Docker 来部署 TDengine 服务，但 Docker 工具能够很好地屏蔽底层操作系统的环境差异，很适合在开发测试或初次体验时用于安装运行 TDengine 的工具集。特别是，借助 Docker，能够比较方便地在 macOS 和 Windows 系统上尝试 TDengine，而无需安装虚拟机或额外租用 Linux 服务器。另外，从 2.0.14.0 版本开始，TDengine 提供的镜像已经可以同时支持 X86-64、X86、arm64、arm32 平台，像 NAS、树莓派、嵌入式开发板之类可以运行 docker 的非主流计算机也可以基于本文档轻松体验 TDengine。 +Even though it's not recommended to deploy TDengine using docker in production system, docker is still very useful in development environment, especially when your host is not Linux. From version 2.0.14.0, the official image of TDengine can support X86-64, X86, arm64, and rm32 . -下文通过 Step by Step 风格的介绍，讲解如何通过 Docker 快速建立 TDengine 的单节点运行环境，以支持开发和测试。 +In this chapter a simple step by step guide of using TDengine in docker is introduced. -## 下载 Docker +## Install Docker -Docker 工具自身的下载请参考 [Docker 官网文档](https://docs.docker.com/get-docker/)。 +The installation of docker please refer to [Get Docker](https://docs.docker.com/get-docker/). -安装完毕后可以在命令行终端查看 Docker 版本。如果版本号正常输出，则说明 Docker 环境已经安装成功。 +After docker is installed, you can check whether Docker is installed properly by displaying Docker version. ```bash $ docker -v Docker version 20.10.3, build 48d30b5 ``` -## 使用 Docker 在容器中运行 TDengine +## Launch TDengine in Docker -### 在 Docker 容器中运行 TDengine server +### Launch TDengine Server ```bash $ docker run -d -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine 526aa188da767ae94b244226a2b2eec2b5f17dd8eff592893d9ec0cd0f3a1ccd ``` -这条命令，启动一个运行了 TDengine server 的 docker 容器，并且将容器的 6030 到 6049 端口映射到宿主机的 6030 到 6049 端口上。如果宿主机已经运行了 TDengine server 并占用了相同端口，需要映射容器的端口到不同的未使用端口段。（详情参见 [TDengine 2.0 端口说明](/train-faq/faq#port）。为了支持 TDengine 客户端操作 TDengine server 服务， TCP 和 UDP 端口都需要打开。 +In the above command, a docker container is started to run TDengine server, the port range 6030-6049 of the container is mapped to host port range 6030-6049. If port range 6030-6049 has been occupied on the host, please change to an available host port range. Regarding the requirements about ports on the host, please refer to [Port Configuration](/reference/config/#serverport). -- **docker run**：通过 Docker 运行一个容器 -- **-d**：让容器在后台运行 -- **-p**：指定映射端口。注意：如果不是用端口映射，依然可以进入 Docker 容器内部使用 TDengine 服务或进行应用开发，只是不能对容器外部提供服务 -- **tdengine/tdengine**：拉取的 TDengine 官方发布的应用镜像 -- **526aa188da767ae94b244226a2b2eec2b5f17dd8eff592893d9ec0cd0f3a1ccd**：这个返回的长字符是容器 ID，我们也可以通过容器 ID 来查看对应的容器 +- **docker run**: Launch a docker container +- **-d**: the container will run in background mode +- **-p**: port mapping +- **tdengine/tdengine**: The image from which to launch the container +- **526aa188da767ae94b244226a2b2eec2b5f17dd8eff592893d9ec0cd0f3a1ccd**: the container ID if successfully launched. -进一步，还可以使用 docker run 命令启动运行 TDengine server 的 docker 容器，并使用 `--name` 命令行参数将容器命名为 `tdengine`，使用 `--hostname` 指定 hostname 为 `tdengine-server`，通过 `-v` 挂载本地目录到容器，实现宿主机与容器内部的数据同步，防止容器删除后，数据丢失。 +Furthermore, `--name` can be used with `docker run` to specify name for the container, `--hostname` can be used to specify hostname for the container, `-v` can be used to mount local volumes to the container so that the data generated inside the container can be persisted to disk on the host. ```bash docker run -d --name tdengine --hostname="tdengine-server" -v ~/work/taos/log:/var/log/taos -v ~/work/taos/data:/var/lib/taos -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine ``` -- **--name tdengine**：设置容器名称，我们可以通过容器名称来访问对应的容器 -- **--hostname=tdengine-server**：设置容器内 Linux 系统的 hostname，我们可以通过映射 hostname 和 IP 来解决容器 IP 可能变化的问题。 -- **-v**：设置宿主机文件目录映射到容器内目录，避免容器删除后数据丢失。 +- **--name tdengine**: specify the name of the container, the name can be used to specify the container later +- **--hostname=tdengine-server**: specify the hostname inside the container, the hostname can be used inside the container without worrying the container IP may vary +- **-v**: volume mapping between host and container -### 使用 docker ps 命令确认容器是否已经正确运行 +### Check the container ```bash docker ps ``` -输出示例如下： +The output is like below: ``` CONTAINER ID IMAGE COMMAND CREATED STATUS ··· c452519b0f9b tdengine/tdengine "taosd" 14 minutes ago Up 14 minutes ··· ``` -- **docker ps**：列出所有正在运行状态的容器信息。 -- **CONTAINER ID**：容器 ID。 -- **IMAGE**：使用的镜像。 -- **COMMAND**：启动容器时运行的命令。 -- **CREATED**：容器创建时间。 -- **STATUS**：容器状态。UP 表示运行中。 +- **docker ps**: List all the containers +- **CONTAINER ID**: Container ID +- **IMAGE**: The image used for the container +- **COMMAND**: The command used when launching the container +- **CREATED**: When the container was created +- **STATUS**: Status of the container -### 通过 docker exec 命令，进入到 docker 容器中去做开发 +### Access TDengine inside container ```bash $ docker exec -it tdengine /bin/bash root@tdengine-server:~/TDengine-server-2.4.0.4# ``` -- **docker exec**：通过 docker exec 命令进入容器，如果退出，容器不会停止。 -- **-i**：进入交互模式。 -- **-t**：指定一个终端。 -- **tdengine**：容器名称，需要根据 docker ps 指令返回的值进行修改。 -- **/bin/bash**：载入容器后运行 bash 来进行交互。 +- **docker exec**: Attach to the continaer +- **-i**: Interactive mode +- **-t**: Use terminal +- **tdengine**: Container name, up to the output of `docker ps` +- **/bin/bash**: The command to execute once the container is attached -进入容器后，执行 taos shell 客户端程序。 +Inside the container, start TDengine CLI `taos` ```bash root@tdengine-server:~/TDengine-server-2.4.0.4# taos @@ -88,13 +89,13 @@ Copyright (c) 2020 by TAOS Data, Inc. All rights reserved. taos> ``` -TDengine 终端成功连接服务端，打印出了欢迎消息和版本信息。如果失败，会有错误信息打印出来。 +The above example is for a successful connection. If `taos` fails to connect to the server side, error information would be shown. -在 TDengine 终端中，可以通过 SQL 命令来创建/删除数据库、表、超级表等，并可以进行插入和查询操作。具体可以参考 [TAOS SQL 说明文档](/taos-sql/)。 +In TDengine CLI, SQL commands can be executed to create/drop databases, tables, STables, and insert or query data. For details please refer to [TAOS SQL](/taos-sql/). -### 在宿主机访问 Docker 容器中的 TDengine server +### Access TDengine from host -在使用了 -p 命令行参数映射了正确的端口启动了 TDengine Docker 容器后，就在宿主机使用 taos shell 命令即可访问运行在 Docker 容器中的 TDengine。 +If `-p` used to map ports properly between host and container, it's also able to access TDengine in container from the host as long as `firstEp` is configured correctly for the client on host. ``` $ taos @@ -105,61 +106,59 @@ Copyright (c) 2020 by TAOS Data, Inc. All rights reserved. taos> ``` -也可以在宿主机使用 curl 通过 RESTful 端口访问 Docker 容器内的 TDengine server。 +It's also able to access the REST interface provided by TDengine in container from the host. ``` curl -u root:taosdata -d 'show databases' 127.0.0.1:6041/rest/sql ``` -输出示例如下： +Output is like below: ``` {"status":"succ","head":["name","created_time","ntables","vgroups","replica","quorum","days","keep0,keep1,keep(D)","cache(MB)","blocks","minrows","maxrows","wallevel","fsync","comp","cachelast","precision","update","status"],"column_meta":[["name",8,32],["created_time",9,8],["ntables",4,4],["vgroups",4,4],["replica",3,2],["quorum",3,2],["days",3,2],["keep0,keep1,keep(D)",8,24],["cache(MB)",4,4],["blocks",4,4],["minrows",4,4],["maxrows",4,4],["wallevel",2,1],["fsync",4,4],["comp",2,1],["cachelast",2,1],["precision",8,3],["update",2,1],["status",8,10]],"data":[["test","2021-08-18 06:01:11.021",10000,4,1,1,10,"3650,3650,3650",16,6,100,4096,1,3000,2,0,"ms",0,"ready"],["log","2021-08-18 05:51:51.065",4,1,1,1,10,"30,30,30",1,3,100,4096,1,3000,2,0,"us",0,"ready"]],"rows":2} ``` -这条命令，通过 REST API 访问 TDengine server，这时连接的是本机的 6041 端口，可见连接成功。 +For details of REST API please refer to [REST API]](/reference/rest-api/). -TDengine REST API 详情请参考[官方文档](/reference/rest-api/)。 +### Run TDengine server and taosAdapter inside container -### 使用 Docker 容器运行 TDengine server 和 taosAdapter +From version 2.4.0.0, in the TDengine Docker image, `taosAdapter` is enabled by default, but can be disabled using environment variable `TAOS_DISABLE_ADAPTER=true` . `taosAdapter` can also be run alone without `taosd` when launching a container. -在 TDengine 2.4.0.0 之后版本的 Docker 容器，开始提供一个独立运行的组件 taosAdapter，代替之前版本 TDengine 中 taosd 进程中内置的 http server。taosAdapter 支持通过 RESTful 接口对 TDengine server 的数据写入和查询能力，并提供和 InfluxDB/OpenTSDB 兼容的数据摄取接口，允许 InfluxDB/OpenTSDB 应用程序无缝移植到 TDengine。在新版本 Docker 镜像中，默认启用了 taosAdapter，也可以使用 docker run 命令中设置 TAOS_DISABLE_ADAPTER=true 来禁用 taosAdapter；也可以在 docker run 命令中单独使用 taosAdapter，而不运行 taosd 。 +For the port mapping of `taosAdapter`, please refer to [taosAdapter](/reference/taosadapter/). -注意：如果容器中运行 taosAdapter，需要根据需要映射其他端口，具体端口默认配置和修改方法请参考[taosAdapter 文档](/reference/taosadapter/)。 - -使用 docker 运行 TDengine 2.4.0.4 版本镜像（taosd + taosAdapter）： +- Run both `taosd` and `taosAdapter` (by default) in docker container: ```bash docker run -d --name tdengine-all -p 6030-6049:6030-6049 -p 6030-6049:6030-6049/udp tdengine/tdengine:2.4.0.4 ``` -使用 docker 运行 TDengine 2.4.0.4 版本镜像（仅 taosAdapter，需要设置 firstEp 配置项 或 TAOS_FIRST_EP 环境变量）： +- Run `taosAdapter` only in docker container, `TAOS_FIRST_EP` environment variable needs to be used to specify the container name in which `taosd` is running: ```bash docker run -d --name tdengine-taosa -p 6041-6049:6041-6049 -p 6041-6049:6041-6049/udp -e TAOS_FIRST_EP=tdengine-all tdengine/tdengine:2.4.0.4 taosadapter ``` -使用 docker 运行 TDengine 2.4.0.4 版本镜像（仅 taosd）： +- Run `taosd` only in docker container: ```bash docker run -d --name tdengine-taosd -p 6030-6042:6030-6042 -p 6030-6042:6030-6042/udp -e TAOS_DISABLE_ADAPTER=true tdengine/tdengine:2.4.0.4 ``` -使用 curl 命令验证 RESTful 接口可以正常工作： +- Verify the REST interface: ```bash curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' 127.0.0.1:6041/rest/sql ``` -输出示例如下： +Below is an example output: ``` {"status":"succ","head":["name","created_time","ntables","vgroups","replica","quorum","days","keep","cache(MB)","blocks","minrows","maxrows","wallevel","fsync","comp","cachelast","precision","update","status"],"column_meta":[["name",8,32],["created_time",9,8],["ntables",4,4],["vgroups",4,4],["replica",3,2],["quorum",3,2],["days",3,2],["keep",8,24],["cache(MB)",4,4],["blocks",4,4],["minrows",4,4],["maxrows",4,4],["wallevel",2,1],["fsync",4,4],["comp",2,1],["cachelast",2,1],["precision",8,3],["update",2,1],["status",8,10]],"data":[["log","2021-12-28 09:18:55.765",10,1,1,1,10,"30",1,3,100,4096,1,3000,2,0,"us",0,"ready"]],"rows":1} ``` -### 应用示例：在宿主机使用 taosBenchmark 写入数据到 Docker 容器中的 TDengine server +### Use taosBenchmark on host to access TDenginer server in container -1. 在宿主机命令行界面执行 taosBenchmark （曾命名为 taosdemo）写入数据到 Docker 容器中的 TDengine server +1. Run `taosBenchmark`, named as `taosdemo` previously, on the host: ```bash $ taosBenchmark @@ -209,24 +208,11 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' 127.0.0 Press enter key to continue or Ctrl-C to stop ``` - 回车后，该命令将在数据库 test 下面自动创建一张超级表 meters，该超级表下有 1 万张表，表名为 "d0" 到 "d9999"，每张表有 1 万条记录，每条记录有 (ts, current, voltage, phase) 四个字段，时间戳从 "2017-07-14 10:40:00 000" 到 "2017-07-14 10:40:09 999"，每张表带有标签 location 和 groupId，groupId 被设置为 1 到 10， location 被设置为 "beijing" 或者 "shanghai"。 - - 最后共插入 1 亿条记录。 + Once the execution is finished, a database `test` is created, a STable `meters` is created in database `test`, 10,000 sub tables are created using `meters` as template, named as "d0" to "d9999", while 10,000 rows are inserted into each table, so totally 100,000,000 rows are inserted. -2. 进入 TDengine 终端，查看 taosBenchmark 生成的数据。 +2. Check the data - - **进入命令行。** - - ```bash - $ root@c452519b0f9b:~/TDengine-server-2.4.0.4# taos - - Welcome to the TDengine shell from Linux, Client Version:2.4.0.4 - Copyright (c) 2020 by TAOS Data, Inc. All rights reserved. - - taos> - ``` - - - **查看数据库。** + - **Check database** ```bash $ taos> show databases; @@ -236,7 +222,7 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' 127.0.0 ``` - - **查看超级表。** + - **Check STable** ```bash $ taos> use test; @@ -250,7 +236,7 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' 127.0.0 ``` - - **查看表，限制输出十条。** + - **Check Tables** ```bash $ taos> select * from test.t0 limit 10; @@ -273,7 +259,7 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' 127.0.0 ``` - - **查看 d0 表的标签值。** + - **Check tag values of table d0** ```bash $ taos> select groupid, location from test.d0; @@ -283,48 +269,17 @@ curl -H 'Authorization: Basic cm9vdDp0YW9zZGF0YQ==' -d 'show databases;' 127.0.0 Query OK, 1 row(s) in set (0.003490s) ``` -### 应用示例：使用数据收集代理软件写入 TDengine - -taosAdapter 支持多个数据收集代理软件（如 Telegraf、StatsD、collectd 等），这里仅模拟 StasD 写入数据，在宿主机执行命令如下： +### Access TDengine from 3rd party tools -``` -echo "foo:1|c" | nc -u -w0 127.0.0.1 6044 -``` - -然后可以使用 taos shell 查询 taosAdapter 自动创建的数据库 statsd 和 超级表 foo 中的内容： - -``` -taos> show databases; - name | created_time | ntables | vgroups | replica | quorum | days | keep | cache(MB) | blocks | minrows | maxrows | wallevel | fsync | comp | cachelast | precision | update | status | -==================================================================================================================================================================================================================================================================================== - log | 2021-12-28 09:18:55.765 | 12 | 1 | 1 | 1 | 10 | 30 | 1 | 3 | 100 | 4096 | 1 | 3000 | 2 | 0 | us | 0 | ready | - statsd | 2021-12-28 09:21:48.841 | 1 | 1 | 1 | 1 | 10 | 3650 | 16 | 6 | 100 | 4096 | 1 | 3000 | 2 | 0 | ns | 2 | ready | -Query OK, 2 row(s) in set (0.002112s) - -taos> use statsd; -Database changed. - -taos> show stables; - name | created_time | columns | tags | tables | -============================================================================================ - foo | 2021-12-28 09:21:48.894 | 2 | 1 | 1 | -Query OK, 1 row(s) in set (0.001160s) - -taos> select * from foo; - ts | value | metric_type | -======================================================================================= - 2021-12-28 09:21:48.840820836 | 1 | counter | -Query OK, 1 row(s) in set (0.001639s) - -taos> -``` +A lot of 3rd party tools can be used to write data into TDengine through `taosAdapter` , for details please refer to [3rd party tools](/third-party/). -可以看到模拟数据已经被写入到 TDengine 中。 +There is nothing different from the 3rd party side to access TDengine server inside a container, as long as the end point is specified correctly, the end point should be the FQDN and the mapped port of the host. -## 停止正在 Docker 中运行的 TDengine 服务 +## Stop TDengine inside container ```bash docker stop tdengine ``` -- **docker stop**：通过 docker stop 停止指定的正在运行中的 docker 镜像。 +- **docker stop**: stop a container +- **tdengine**: container name