diff --git a/src/UserGuide/Master/Table/API/Programming-Cpp-Native-API_apache.md b/src/UserGuide/Master/Table/API/Programming-Cpp-Native-API_apache.md index 933248646..402f913bd 100644 --- a/src/UserGuide/Master/Table/API/Programming-Cpp-Native-API_apache.md +++ b/src/UserGuide/Master/Table/API/Programming-Cpp-Native-API_apache.md @@ -210,11 +210,13 @@ session = (new TableSessionBuilder()) ->build(); ``` +`host()` also accepts an unbracketed IPv6 address; `rpcPort()` still sets the port separately. + #### 3.2.2 Configurable Parameter List | **Parameter Name** | **Description** | **Default Value** | | :---: | :---: | :---: | -| host | Set the connected node IP | "127.0.0.1" ("localhost") | +| host | IP address of the node to connect to; supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname. Omit brackets for IPv6. IPv6 is supported from V2.0.12. | "127.0.0.1" ("localhost") | | rpcPort | Set the connected node port | 6667 | | username | Set the connection username | "root" | | password | Set the connection password | "root" | @@ -451,4 +453,3 @@ Failed to delete cached file C:\Users\Administrator\.m2\repository\.cache\downlo Possible fixes: - Try to delete the ".m2\repository\\.cache\" directory and try again. - Add "\true\" configuration to the download-maven-plugin maven phase that complains this error. - diff --git a/src/UserGuide/Master/Table/API/Programming-JDBC_apache.md b/src/UserGuide/Master/Table/API/Programming-JDBC_apache.md index f1a062d37..26f3b2ced 100644 --- a/src/UserGuide/Master/Table/API/Programming-JDBC_apache.md +++ b/src/UserGuide/Master/Table/API/Programming-JDBC_apache.md @@ -186,4 +186,13 @@ public class TableModelJDBCExample { } } } + +```java +// IPv6 + Table model +String url = "jdbc:iotdb://[DN_IPV6_ADDRESS]:6667?sql_dialect=table"; +// IPv6 + Table model + SSL +String sslUrl = "jdbc:iotdb://[DN_IPV6_ADDRESS]:6667?sql_dialect=table&use_ssl=true"; +``` + +Starting with V2.0.12, table-model JDBC URLs also support `[ipv6]:port`. Replace `DN_IPV6_ADDRESS` with the DataNode’s actual reachable address. For SSL over IPv6, the server certificate SAN uses the unbracketed IPv6 address without a port. Retain the existing table-model URL examples. ``` \ No newline at end of file diff --git a/src/UserGuide/Master/Table/API/Programming-Java-Native-API_apache.md b/src/UserGuide/Master/Table/API/Programming-Java-Native-API_apache.md index 9ae21c644..1f2aa7a50 100644 --- a/src/UserGuide/Master/Table/API/Programming-Java-Native-API_apache.md +++ b/src/UserGuide/Master/Table/API/Programming-Java-Native-API_apache.md @@ -151,7 +151,7 @@ Since V2.0.11, `TableSessionBuilder` supports configuring the RPC compression me | **Parameter** | **Description** | **Default Value** | |-----------------------------------------------------| ------------------------------------------------------------ | ------------------------------------------------- | -| nodeUrls(List\ nodeUrls) | Sets the list of IoTDB cluster node URLs. | `Collections.singletonList("``localhost:6667``")` | +| nodeUrls(List\ nodeUrls) | Sets the IoTDB cluster node URL list; IPv6 endpoints use `[ipv6]:port`, for example `[DN_IPV6_ADDRESS]:6667`. IPv6 is supported from V2.0.12. | `Collections.singletonList("``localhost:6667``")` | | username(String username) | Sets the username for the connection. | `"root"` | | password(String password) | Sets the password for the connection. | `"TimechoDB@2021"` (the default password is `root` before V2.0.6.x) | | database(String database) | Sets the target database name. | `null` | @@ -182,6 +182,8 @@ Since V2.0.11, `TableSessionBuilder` supports configuring the RPC compression me | withDateEncoding(TSEncoding tsEncoding) | Sets the encoding for DATE values. | `TSEncoding.TS_2DIFF` | | connectionTimeoutInMs(int connectionTimeoutInMs) | Sets the connection timeout in milliseconds. | `0` (no timeout) | +Starting with V2.0.12, table-model `nodeUrls` also supports IPv6 endpoints. `DN_IPV6_ADDRESS` in the table is a DataNode address placeholder; replace it with an actual reachable address. Existing defaults remain unchanged. When configuring `TableSessionBuilder` with separate `host`/`rpcPort` settings, use an unbracketed IPv6 host; only node URL strings use brackets. + #### 3.2.3 Sample Code ```Java @@ -520,7 +522,7 @@ The `TableSessionPoolBuilder` class is a builder for configuring and creating `I | **Parameter** | **Description** | **Default Value** | |---------------------------------------------------------------| ------------------------------------------------------------ | --------------------------------------------- | -| nodeUrls(List\ nodeUrls) | Sets the list of IoTDB cluster node URLs. | `Collections.singletonList("localhost:6667")` | +| nodeUrls(List\ nodeUrls) | Sets the IoTDB cluster node URL list; IPv6 endpoints use `[ipv6]:port`, for example `[DN_IPV6_ADDRESS]:6667`. IPv6 is supported from V2.0.12. | `Collections.singletonList("localhost:6667")` | | maxSize(int maxSize) | Sets the maximum size of the session pool, i.e., the maximum number of sessions allowed in the pool. | `5` | | user(String user) | Sets the username for the connection. | `"root"` | | password(String password) | Sets the password for the connection. | `"root"` | @@ -944,4 +946,6 @@ public class TableModelSessionPoolExample { } } } + +To connect to IPv6 nodes in the Chapter 5 example, `LOCAL_URL` can use `[ipv6]:port`; retain the existing address and initialization code. ``` \ No newline at end of file diff --git a/src/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md b/src/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md index 98227e15e..d1bd7a2c4 100644 --- a/src/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md +++ b/src/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md @@ -132,7 +132,7 @@ def close(self): | **Parameter** | **Description** | **Type** | **Default Value** | | ------------------ | ------------------------------------- | -------- | ------------------------- | -| node_urls | List of database node URLs. | `list` | `["localhost:6667"]` | +| node_urls | List of database connection node URLs; IPv6 endpoints use `[ipv6]:port`, for example `[DN_IPV6_ADDRESS]:6667`. IPv6 is supported from V2.0.12. | `list` | `["localhost:6667"]` | | username | Username for the database connection. | `str` | `"root"` | | password | Password for the database connection. | `str` | `"root"` | | database | Target database to connect to. | `str` | `None` | @@ -140,6 +140,8 @@ def close(self): | time_zone | Default session time zone. | `str` | `Session.DEFAULT_ZONE_ID` | | enable_compression | Enable data compression. | `bool` | `False` | +Starting with V2.0.12, table-model `node_urls` supports IPv6 endpoints. `DN_IPV6_ADDRESS` in the table is a DataNode address placeholder; retain existing defaults and examples. When `TableSession`/`TableSessionPool` take host and port separately, use an unbracketed IPv6 host; node URL lists use `[ipv6]:port`. + #### Sample Code ```Python @@ -231,7 +233,7 @@ def close(self): | **Paramater** | **Description** | **Type** | **Default Value** | | ------------------ | ------------------------------------------------------------ | -------- | -------------------------- | -| node_urls | List of IoTDB cluster node URLs. | `list` | None | +| node_urls | List of database connection node URLs; IPv6 endpoints use `[ipv6]:port`, for example `[DN_IPV6_ADDRESS]:6667`. IPv6 is supported from V2.0.12. | `list` | None | | max_pool_size | Maximum size of the session pool, i.e., the maximum number of sessions allowed in the pool. | `int` | `5` | | username | Username for the connection. | `str` | `Session.DEFAULT_USER` | | password | Password for the connection. | `str` | `Session.DEFAULT_PASSWORD` | @@ -395,6 +397,8 @@ if __name__ == "__main__": df = get_data() ``` +Use an unbracketed IPv6 host for SSL connections. The CA specified by `ca_certs` must validate the server certificate, and the server certificate SAN must contain the actual unbracketed IPv6 `IP Address` used by the client. TLS server identity verification fails if the SAN does not contain that address. + ## 4. Sample Code **Session** Example: You can find the full example code at [Session Example](https://github.com/apache/iotdb/blob/master/iotdb-client/client-py/table_model_session_example.py). @@ -570,4 +574,3 @@ delete_data() session_pool.close() print("example is finished!") ``` - diff --git a/src/UserGuide/Master/Table/Deployment-and-Maintenance/AINode_Deployment_apache.md b/src/UserGuide/Master/Table/Deployment-and-Maintenance/AINode_Deployment_apache.md index 4b1fc637c..f283760a1 100644 --- a/src/UserGuide/Master/Table/Deployment-and-Maintenance/AINode_Deployment_apache.md +++ b/src/UserGuide/Master/Table/Deployment-and-Maintenance/AINode_Deployment_apache.md @@ -113,18 +113,26 @@ AINode supports modifying some necessary parameters. You can find the following | **Name** | **Description** | **Type** | **Default Value** | | ------------------------------ | ------------------------------------------------------------ | -------- | ------------------ | | cluster_name | Identifier of the cluster AINode joins | string | defaultCluster | -| ain_seed_config_node | Address of the ConfigNode registered when AINode starts | String | 127.0.0.1:10710 | -| ain_cluster_ingress_address | RPC address of the DataNode for AINode to pull data | String | 127.0.0.1 | +| ain_seed_config_node | ConfigNode endpoint used for AINode registration at startup. Supports `ipv4:port`, `hostname:port`, or `[ipv6]:port`, for example `[CN_IPV6_ADDRESS]:10710`. IPv6 is supported from V2.0.12. | String | 127.0.0.1:10710 | +| ain_cluster_ingress_address | DataNode RPC address from which AINode pulls data. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | String | 127.0.0.1 | | ain_cluster_ingress_port | RPC port of the DataNode for AINode to pull data | Integer | 6667 | | ain_cluster_ingress_username | Client username for AINode to pull data from the DataNode | String | root | | ain_cluster_ingress_password | Client password for AINode to pull data from the DataNode | String | root | | ain_cluster_ingress_time_zone | Client time zone for AINode to pull data from the DataNode | String | UTC+8 | -| ain_inference_rpc_address | Address for AINode to provide services and communication (internal interface) | String | 127.0.0.1 | +| ain_inference_rpc_address | Address used for AINode services and internal communication. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | String | 127.0.0.1 | | ain_inference_rpc_port | Port for AINode to provide services and communication | String | 10810 | | ain_system_dir | Metadata storage path for AINode (relative path starts from OS-dependent directory; absolute path is recommended) | String | data/AINode/system | | ain_models_dir | Path to store model files for AINode (relative path starts from OS-dependent directory; absolute path is recommended) | String | data/AINode/models | | ain_thrift_compression_enabled | Whether to enable Thrift compression for AINode (0=disabled, 1=enabled) | Boolean | 0 | +```properties +ain_seed_config_node=[CN_IPV6_ADDRESS]:10710 +ain_cluster_ingress_address=DN_IPV6_ADDRESS +ain_inference_rpc_address=AINODE_IPV6_ADDRESS +``` + +`ain_seed_config_node` includes both an address and port and uses `[ipv6]:port` for IPv6. `ain_cluster_ingress_address` and `ain_inference_rpc_address` contain addresses only and use unbracketed IPv6. Replace `CN_IPV6_ADDRESS`, `DN_IPV6_ADDRESS`, and `AINODE_IPV6_ADDRESS` with the actual reachable addresses of the ConfigNode, DataNode, and AINode. After startup, verify that AINode is registered with ConfigNode and can access DataNode. + ### 3.3 Importing Weight Files > Offline environment only (Online environments can skip this step) diff --git a/src/UserGuide/Master/Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md b/src/UserGuide/Master/Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md index 8ea2a50ac..f54604cdd 100644 --- a/src/UserGuide/Master/Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md +++ b/src/UserGuide/Master/Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md @@ -41,6 +41,7 @@ Use the hostname for `cn_internal_address` and `dn_internal_address` in IoTDB co 3. **Unmodifiable Parameters**: Some parameters cannot be changed after the first startup. Refer to the [Parameter Configuration](#22-parameters-configuration) section. +4. **Unmodifiable Parameters**: Some parameters cannot be changed after the first startup. Refer to the [Parameter Configuration](#22-parameters-configuration) section. 4. **Installation Path**: Ensure the installation path contains no spaces or non-ASCII characters to prevent runtime issues. 5. **User Permissions**: Choose one of the following permissions during installation and deployment: @@ -51,6 +52,8 @@ Use the hostname for `cn_internal_address` and `dn_internal_address` in IoTDB co 6. **Health Check Tool**: Before installation, the health check tool can help inspect the operating environment of IoTDB nodes and obtain detailed inspection results. The usage method of the IoTDB health check tool can be found in:[Health Check Tool](../Tools-System/Health-Check-Tool.md). +For dual-stack or IPv6-only deployment, verify before startup that IPv6 is enabled in the operating system and the configured addresses are assigned to the appropriate network interfaces and can be bound by the services; that IPv6 routing between ConfigNodes, DataNodes, and AINodes is reachable and the required RPC, consensus, and client ports are allowed through the firewall; and that DNS or `/etc/hosts` resolution is consistent across nodes when hostnames are used. `0.0.0.0` and `::` are wildcard listening addresses only and cannot be used for node registration, node discovery, client redirection, or other remote connection targets. + ## 2. Preparation 1. Prepare the IoTDB database installation package:：apache-iotdb-{version}-all-bin.zip（Please refer to the installation package for details：[IoTDB-Package](../Deployment-and-Maintenance/IoTDB-Package_apache.md)） @@ -154,23 +157,33 @@ Set the following parameters in `./conf/iotdb-system.properties`. Refer to `./co | **Parameter** | **Description** | **Default** | **Recommended** | **11.101.17.224** | **11.101.17.225** | **11.101.17.226** | **Notes** | | :------------------ | :----------------------------------------------------------- | :-------------- | :----------------------------------------------------------- | :---------------- | :---------------- | :---------------- | :--------------------------------------------------------- | -| cn_internal_address | Address used for internal communication within the cluster | 127.0.0.1 | Server's IPv4 address or hostname. Use hostname to avoid issues when the IP changes. | iotdb-1 | iotdb-2 | iotdb-3 | This parameter cannot be modified after the first startup. | +| cn_internal_address | Address used for ConfigNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | iotdb-1 | iotdb-2 | iotdb-3 | This parameter cannot be modified after the first startup. | | cn_internal_port | Port used for internal communication within the cluster | 10710 | 10710 | 10710 | 10710 | 10710 | This parameter cannot be modified after the first startup. | | cn_consensus_port | Port used for consensus protocol communication among ConfigNode replicas | 10720 | 10720 | 10720 | 10720 | 10720 | This parameter cannot be modified after the first startup. | -| cn_seed_config_node | Address of the ConfigNode for registering and joining the cluster. (e.g.,`cn_internal_address:cn_internal_port`) | 127.0.0.1:10710 | Address and port of the seed ConfigNode (e.g., `cn_internal_address:cn_internal_port`) | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | This parameter cannot be modified after the first startup. | +| cn_seed_config_node | ConfigNode endpoint used for node registration and joining the cluster, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | Address and port of the seed ConfigNode (e.g., `cn_internal_address:cn_internal_port`) | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | This parameter cannot be modified after the first startup. | **DataNode Parameters**: | **Parameter** | **Description** | **Default** | **Recommended** | **11.101.17.224** | **11.101.17.225** | **11.101.17.226** | **Notes** | | :------------------------------ | :----------------------------------------------------------- |:----------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| :---------------- | :---------------- | :---------------- | :--------------------------------------------------------- | -| dn_rpc_address | Address for the client RPC service | 127.0.0.1 | By default, the local machine can directly access it. For non-local access, please modify this configuration item to the IPv4 address or hostname of the server where it is located. It is recommended to use the IPv4 address of the server where it is located. | iotdb-1 | iotdb-2 | iotdb-3 | Effective after restarting the service. | +| dn_rpc_address | Client RPC listening address. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | Local access only by default; for remote access, specify the server’s routable IPv4 address, unbracketed IPv6 address, or hostname | iotdb-1 | iotdb-2 | iotdb-3 | Effective after restarting the service. | | dn_rpc_port | Port for the client RPC service | 6667 | 6667 | 6667 | 6667 | 6667 | Effective after restarting the service. | -| dn_internal_address | Address used for internal communication within the cluster | 127.0.0.1 | Server's IPv4 address or hostname. Use hostname to avoid issues when the IP changes. | iotdb-1 | iotdb-2 | iotdb-3 | This parameter cannot be modified after the first startup. | +| dn_internal_address | Address used for DataNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | iotdb-1 | iotdb-2 | iotdb-3 | This parameter cannot be modified after the first startup. | | dn_internal_port | Port used for internal communication within the cluster | 10730 | 10730 | 10730 | 10730 | 10730 | This parameter cannot be modified after the first startup. | | dn_mpp_data_exchange_port | Port used for receiving data streams | 10740 | 10740 | 10740 | 10740 | 10740 | This parameter cannot be modified after the first startup. | | dn_data_region_consensus_port | Port used for data replica consensus protocol communication | 10750 | 10750 | 10750 | 10750 | 10750 | This parameter cannot be modified after the first startup. | | dn_schema_region_consensus_port | Port used for metadata replica consensus protocol communication | 10760 | 10760 | 10760 | 10760 | 10760 | This parameter cannot be modified after the first startup. | -| dn_seed_config_node | Address of the ConfigNode for registering and joining the cluster.(e.g.,`cn_internal_address:cn_internal_port`) | 127.0.0.1:10710 | Address of the first ConfigNode | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | This parameter cannot be modified after the first startup. | +| dn_seed_config_node | ConfigNode endpoint used for node registration and joining the cluster, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | Address of the first ConfigNode | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | This parameter cannot be modified after the first startup. | + +Replace `CN_IPV6_ADDRESS` and `DN_IPV6_ADDRESS` with the nodes’ actual reachable IPv6 addresses before deployment. + +```properties +cn_internal_address=CN_IPV6_ADDRESS +cn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +dn_internal_address=DN_IPV6_ADDRESS +dn_rpc_address=DN_IPV6_ADDRESS +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +``` **Note:** Ensure files are saved after editing. Tools like VSCode Remote do not save changes automatically. @@ -195,6 +208,8 @@ Set the following parameters in `./conf/iotdb-system.properties`. Refer to `./co If the startup fails, refer to the [Common Issues](#5-common-issues) section below for troubleshooting. +After startup, run `show cluster` in the CLI to verify that ConfigNodes and DataNodes are registered. In an IPv6-only environment, node address fields should display the configured unbracketed IPv6 addresses; addresses with ports in logs or errors should use `[ipv6]:port`. If `::` is returned as a node address, configure an actual routable IPv6 address for the node’s published address. + ### 3.5 Start DataNode Instances On each server, navigate to the `sbin` directory and start the DataNode: @@ -212,6 +227,13 @@ On each server, navigate to the `sbin` directory and start the DataNode: .\windows\start-datanode.bat ``` +When passing an IPv6 address separately with `-h`, omit brackets and specify the port with `-p`. For example: + +```shell +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' -sql_dialect table +``` + + ### 3.6 Start CLI Enter the IoTDB CLI. diff --git a/src/UserGuide/Master/Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md b/src/UserGuide/Master/Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md index 2cef73eaf..d852daf39 100644 --- a/src/UserGuide/Master/Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md +++ b/src/UserGuide/Master/Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md @@ -128,23 +128,35 @@ Set the following parameters in `conf/iotdb-system.properties`. Refer to `conf/i | **Parameter** | **Description** | **Default** | **Recommended** | **Notes** | | :------------------ | :----------------------------------------------------------- | :-------------- | :----------------------------------------------------------- | :--------------------------------------------------------- | -| cn_internal_address | Address used for internal communication within the cluster | 127.0.0.1 | Server's IPv4 address or hostname. Use hostname to avoid issues when the IP changes. | This parameter cannot be modified after the first startup. | +| cn_internal_address | Address used for ConfigNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | This parameter cannot be modified after the first startup. | | cn_internal_port | Port used for internal communication within the cluster | 10710 | 10710 | This parameter cannot be modified after the first startup. | | cn_consensus_port | Port used for consensus protocol communication among ConfigNode replicas | 10720 | 10720 | This parameter cannot be modified after the first startup. | -| cn_seed_config_node | Address of the ConfigNode for registering and joining the cluster. (e.g.,`cn_internal_address:cn_internal_port`) | 127.0.0.1:10710 | Use `cn_internal_address:cn_internal_port` | This parameter cannot be modified after the first startup. | +| cn_seed_config_node | ConfigNode endpoint used for node registration, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | Use `cn_internal_address:cn_internal_port` | This parameter cannot be modified after the first startup. | **DataNode Parameters**: | **Parameter** | **Description** | **Default** | **Recommended** | **Notes** | | :------------------------------ | :----------------------------------------------------------- | :-------------- |:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| :--------------------------------------------------------- | -| dn_rpc_address | Address for the client RPC service | 127.0.0.1 | By default, the local machine can directly access it. For non-local access, please modify this configuration item to the IPv4 address or hostname of the server where it is located. It is recommended to use the IPv4 address of the server where it is located. | Effective after restarting the service. | +| dn_rpc_address | Client RPC listening address. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | Local access only by default; for remote access, specify the server’s routable IPv4 address, unbracketed IPv6 address, or hostname | Effective after restarting the service. | | dn_rpc_port | Port for the client RPC service | 6667 | 6667 | Effective after restarting the service. | -| dn_internal_address | Address used for internal communication within the cluster | 127.0.0.1 | Server's IPv4 address or hostname. Use hostname to avoid issues when the IP changes. | This parameter cannot be modified after the first startup. | +| dn_internal_address | Address used for DataNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | This parameter cannot be modified after the first startup. | | dn_internal_port | Port used for internal communication within the cluster | 10730 | 10730 | This parameter cannot be modified after the first startup. | | dn_mpp_data_exchange_port | Port used for receiving data streams | 10740 | 10740 | This parameter cannot be modified after the first startup. | | dn_data_region_consensus_port | Port used for data replica consensus protocol communication | 10750 | 10750 | This parameter cannot be modified after the first startup. | | dn_schema_region_consensus_port | Port used for metadata replica consensus protocol communication | 10760 | 10760 | This parameter cannot be modified after the first startup. | -| dn_seed_config_node | Address of the ConfigNode for registering and joining the cluster. (e.g.,`cn_internal_address:cn_internal_port`) | 127.0.0.1:10710 | Use `cn_internal_address:cn_internal_port` | This parameter cannot be modified after the first startup. | +| dn_seed_config_node | ConfigNode endpoint used for node registration, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | Use `cn_internal_address:cn_internal_port` | This parameter cannot be modified after the first startup. | + +Standalone instances accessed only from the local host can use the IPv6 loopback address: + +```properties +cn_internal_address=::1 +cn_seed_config_node=[::1]:10710 +dn_internal_address=::1 +dn_rpc_address=::1 +dn_seed_config_node=[::1]:10710 +``` + +`::1` is the IPv6 loopback address and is for local access or testing only. For access from other hosts, use the local host’s actual routable IPv6 address. `::` listens on all IPv6 interfaces and cannot be used as a remote target, node discovery result, or client redirection address. ### 2.4 Start and Stop the Edge Edition diff --git a/src/UserGuide/Master/Table/FAQ/Frequently-asked-questions.md b/src/UserGuide/Master/Table/FAQ/Frequently-asked-questions.md index 8b3bd70db..d42693677 100644 --- a/src/UserGuide/Master/Table/FAQ/Frequently-asked-questions.md +++ b/src/UserGuide/Master/Table/FAQ/Frequently-asked-questions.md @@ -284,3 +284,33 @@ Notes: #### How to decrease the memory usage of ConfigNode/DataNode? - Adjust the ON_HEAP_MEMORY、OFF_HEAP_MEMORY options in conf/confignode-env.sh and conf/datanode-env.sh. + +## 3. IPv6 Connection FAQ + +### 3.1 Why is `[::1]:6667` valid while `::1:6667` should not be used as an endpoint? + +Starting with V2.0.12, IoTDB supports IPv6 connections. IPv6 addresses contain multiple colons. Address and port combinations must use `[ipv6]:port` to distinguish them. The address and port in JDBC URLs, Session node URLs, and Pipe `node-urls` must use `[ipv6]:port`. + +### 3.2 Why do address parameters use unbracketed IPv6 while JDBC and Pipe use `[ipv6]:port`? + +Parameters such as `cn_internal_address`, `dn_internal_address`, and `dn_rpc_address` contain addresses only and use unbracketed IPv6. JDBC URLs, seed endpoints, Session node URLs, and Pipe `node-urls` include both addresses and ports and use `[ipv6]:port`. + +### 3.3 Why does listening on `::` succeed while clients still cannot connect? + +`::` listens on all IPv6 interfaces and is not a routable remote address. Node registration, node discovery, client redirection, Pipe destinations, and Prometheus targets must use actual reachable IPv6 addresses. + +### 3.4 How do I resolve hostname or IP verification failures in IPv6 TLS connections? + +Check that the server certificate SAN contains the actual unbracketed IPv6 `IP Address` used by the client, without brackets or a port. Also verify that the client TrustStore contains the CA that issued the certificate. + +### 3.5 How do I troubleshoot connection failures in an IPv6-only environment? + +Check, in order, that IPv6 is enabled in the operating system, addresses are bound, inter-node routes and ports are reachable, firewalls allow traffic, DNS or `/etc/hosts` resolution is consistent, and the client runtime and underlying socket support IPv6. + +### 3.6 What if IPv4 works but IPv6 connections fail in a dual-stack environment? + +First connect directly with the actual IPv6 address and port using the required syntax, and verify that the destination service is bound to an IPv6 address and routing and firewall rules allow access to the port. Then check that DNS AAAA records or IPv6 mappings in `/etc/hosts` point to the destination. Verify IPv4 and IPv6 paths separately; successful IPv4 connections do not confirm IPv6 connectivity. Do not publish `::` as a node address. + +### 3.7 How do I resolve IPv6 endpoint parsing errors in Pipe? + +Check that every IPv6 endpoint uses `[ipv6]:port`, that multiple endpoints are separated by commas, and that `::` or `0.0.0.0` has not been used as a destination. For SSL Pipe, also check the TrustStore, KeyStore, and destination certificate SAN. diff --git a/src/UserGuide/Master/Table/Reference/System-Config-Manual_apache.md b/src/UserGuide/Master/Table/Reference/System-Config-Manual_apache.md index 78ccdc0b0..0dcc02938 100644 --- a/src/UserGuide/Master/Table/Reference/System-Config-Manual_apache.md +++ b/src/UserGuide/Master/Table/Reference/System-Config-Manual_apache.md @@ -144,11 +144,15 @@ The `iotdb-system.properties` file contains various configurations for managing ### 4.2 Seed ConfigNode +> Address-only parameters use unbracketed IPv6 addresses; endpoints containing both an address and a port use `[ipv6]:port`. + +`CN_IPV6_ADDRESS` below marks the ConfigNode IPv6 address field. Use an actual resolvable, routable address. Existing IPv4/hostname examples and default values remain unchanged. + - cn_seed_config_node | Name | cn_seed_config_node | | ----------- | ------------------------------------------------------------ | -| Description | Address of the seed ConfigNode for Confignode to join the cluster. | +| Description | Endpoint of the target ConfigNode through which a ConfigNode joins the cluster; a SeedConfigNode is recommended. Supports `ipv4:port`, `hostname:port`, or `[ipv6]:port`, for example `[CN_IPV6_ADDRESS]:10710`. Previously named cn_target_config_node_list in V1.2.2 and earlier. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1:10710 | | Effective | Modify before the first startup. | @@ -157,7 +161,7 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | dn_seed_config_node | | ----------- | ------------------------------------------------------------ | -| Description | Address of the seed ConfigNode for Datanode to join the cluster. | +| Description | Endpoint of the ConfigNode through which a DataNode joins the cluster at startup; a SeedConfigNode is recommended. Supports `ipv4:port`, `hostname:port`, or `[ipv6]:port`, for example `[CN_IPV6_ADDRESS]:10710`. Previously named dn_target_config_node_list in V1.2.2 and earlier. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1:10710 | | Effective | Modify before the first startup. | @@ -168,7 +172,7 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | cn_internal_address | | ----------- | ---------------------------------------------- | -| Description | Internal address for ConfigNode communication. | +| Description | ConfigNode internal cluster communication address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port, for example `192.168.1.10`, `CN_IPV6_ADDRESS`, or `iotdb-cn-1`. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1 | | Effective | Modify before the first startup. | @@ -195,7 +199,7 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | dn_rpc_address | | ----------- |---------------------------------| -| Description | Address for client RPC service. | +| Description | Listening address for the client RPC service. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port, for example `192.168.1.20`, `DN_IPV6_ADDRESS`, or `iotdb-dn-1`. `::` listens on all IPv6 interfaces, but cannot be returned as a remote address for client redirection or node discovery. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1 | | Effective | Restart required. | @@ -213,11 +217,15 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | dn_internal_address | | ----------- | -------------------------------------------- | -| Description | Internal address for DataNode communication. | +| Description | DataNode internal communication address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port, for example `192.168.1.20`, `DN_IPV6_ADDRESS`, or `iotdb-dn-1`. IPv6 is supported from V2.0.12. | | Type | string | | Default | 127.0.0.1 | | Effective | Modify before the first startup. | +> Use unbracketed IPv6 for address-only parameters, such as `DN_IPV6_ADDRESS`; use `[ipv6]:port` for endpoints containing both an address and port, such as `[DN_IPV6_ADDRESS]:10730`. `0.0.0.0` and `::` are wildcard listening addresses only; do not use them as remote connection targets. + +`DN_IPV6_ADDRESS` below marks the DataNode IPv6 address field. Replace it with an address bound to and reachable on the corresponding node. + - dn_internal_port | Name | dn_internal_port | @@ -523,6 +531,8 @@ The `iotdb-system.properties` file contains various configurations for managing ### 4.7 SSL Configuration +> IPv6 uses the existing SSL/TLS switches, protocols, KeyStore, and TrustStore settings. For TLS server identity verification over IPv6, the server certificate SAN must contain the actual IPv6 address used by the client as an unbracketed `IP Address`, without a port. For example, when connecting to `[DN_IPV6_ADDRESS]:6667`, the SAN must contain `DN_IPV6_ADDRESS`. + - enable_thrift_ssl | Name | enable_thrift_ssl | diff --git a/src/UserGuide/Master/Table/Tools-System/CLI_apache.md b/src/UserGuide/Master/Table/Tools-System/CLI_apache.md index f2128b7ef..bdf7e95ec 100644 --- a/src/UserGuide/Master/Table/Tools-System/CLI_apache.md +++ b/src/UserGuide/Master/Table/Tools-System/CLI_apache.md @@ -55,7 +55,7 @@ Shell> sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -sql_dia | **Parameter** | **Type** | **Required** | **Description** | **Example** | | -------------------------- | -------- | ------------ |-----------------------------------------------------------------------------------| ------------------- | -| -h `` | string | No | The IP address of the IoTDB server. (Default: 127.0.0.1) | -h 127.0.0.1 | +| -h `` | string | No | IoTDB server IPv4 address, unbracketed IPv6 address, or hostname. IPv6 is supported from V2.0.12; omit brackets. | -h 127.0.0.1 | | -p `` | int | No | The RPC port of the IoTDB server. (Default: 6667) | -p 6667 | | -u `` | string | No | The username to connect to the IoTDB server. (Default: root) | -u root | | -pw `` | string | No | The password to connect to the IoTDB server. (Default: root) | -pw root | @@ -73,6 +73,15 @@ The figure below indicates a successful startup: ![](/img/Cli-01.png) +Starting with V2.0.12, pass an IPv6 address to `-h` without brackets and specify the port separately with `-p`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with an actual reachable IPv6 address before running the command. Retain the existing IPv4 startup examples. For example: + +```shell +# Linux/macOS +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' -sql_dialect table + +# Windows (V2.0.4.x and later) +sbin\windows\start-cli.bat -h DN_IPV6_ADDRESS -p 6667 -u root -pw "" -sql_dialect table +``` ## 2. Example Commands diff --git a/src/UserGuide/Master/Table/Tools-System/Data-Export-Tool_apache.md b/src/UserGuide/Master/Table/Tools-System/Data-Export-Tool_apache.md index 410ae5f86..aa4247976 100644 --- a/src/UserGuide/Master/Table/Tools-System/Data-Export-Tool_apache.md +++ b/src/UserGuide/Master/Table/Tools-System/Data-Export-Tool_apache.md @@ -38,7 +38,7 @@ IoTDB supports two methods for data export: | Short | Full Parameter | Description | Required | Default | |----------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------- |----------------------------------------------| | `-ft` | `--file_type` | Export file type: `csv`, `sql`, `tsfile`. | ​**Yes** | - | -| `-h` | `--host` | Hostname of the IoTDB server. | No | `127.0.0.1` | +| `-h` | `--host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | `127.0.0.1` | | `-p` | `--port` | Port number of the IoTDB server. | No | `6667` | | `-u` | `--username` | Username for authentication. | No | `root` | | `-pw` | `--password` | Password for authentication. Supported for hidden input since V2.0.10 | No | `root` | @@ -56,6 +56,8 @@ IoTDB supports two methods for data export: | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with the actual reachable unbracketed IPv6 address before running the command. Do not pass brackets to `-h`. For SSL, retain the existing `-usessl`, `-ts`, and `-tpw` parameters; the server certificate SAN must contain the actual unbracketed IPv6 address accessed by the client. + ### 2.2 CSV Format #### 2.2.1 Command diff --git a/src/UserGuide/Master/Table/Tools-System/Data-Import-Tool_apache.md b/src/UserGuide/Master/Table/Tools-System/Data-Import-Tool_apache.md index 786074b67..f46f88eed 100644 --- a/src/UserGuide/Master/Table/Tools-System/Data-Import-Tool_apache.md +++ b/src/UserGuide/Master/Table/Tools-System/Data-Import-Tool_apache.md @@ -44,7 +44,7 @@ IoTDB supports three methods for data import: | Short | Full Parameter | Description | Required | Default | |----------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------- |---------------------------------------------| | `-ft` | `--file_type` | File type: `csv`, `sql`, `tsfile`. | ​**Yes** | - | -| `-h` | `--host` | IoTDB server hostname. | No | `127.0.0.1` | +| `-h` | `--host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | `127.0.0.1` | | `-p` | `--port` | IoTDB server port. | No | `6667` | | `-u` | `--username` | Username. | No | `root` | | `-pw` | `--password` | Password. Supported for hidden input since V2.0.10 | No | `root` | @@ -59,6 +59,8 @@ IoTDB supports three methods for data import: | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with the actual reachable unbracketed IPv6 address before running the command. Do not pass brackets to `-h`. For SSL, retain the existing `-usessl`, `-ts`, and `-tpw` parameters; the server certificate SAN must contain the actual unbracketed IPv6 address accessed by the client. + ### 2.2 CSV Format #### 2.2.1 Command diff --git a/src/UserGuide/Master/Table/Tools-System/Monitor-Tool_apache.md b/src/UserGuide/Master/Table/Tools-System/Monitor-Tool_apache.md index 406cdbb39..39ebd0246 100644 --- a/src/UserGuide/Master/Table/Tools-System/Monitor-Tool_apache.md +++ b/src/UserGuide/Master/Table/Tools-System/Monitor-Tool_apache.md @@ -88,6 +88,7 @@ follow_redirects: true static_configs: - targets: - localhost:9091 + - '[IPV6_ADDRESS]:9091' ``` For more details, refer to the following documents: @@ -96,3 +97,10 @@ For more details, refer to the following documents: - [Prometheus Configuration for Pulling Metrics from HTTP Interface](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) - [Grafana Installation and Usage Documentation](https://grafana.com/docs/grafana/latest/getting-started/getting-started/) - [Grafana Querying Data from Prometheus and Plotting Documentation](https://prometheus.io/docs/visualization/grafana/#grafana-support-for-prometheus) +Prometheus targets include both an IPv6 address and a port and must use `[ipv6]:port`. Even if the service listens on `::`, use an actual routable IPv6 address for the target, never `[::]:9091`. + +Starting with V2.0.12, the metrics endpoint supports access over IPv6. Use brackets to distinguish the address from the port in an IPv6 metrics URL. Replace the placeholder below with the actual reachable IPv6 address: + +```shell +curl 'http://[IPV6_ADDRESS]:9091/metrics' +``` diff --git a/src/UserGuide/Master/Table/Tools-System/Schema-Export-Tool_apache.md b/src/UserGuide/Master/Table/Tools-System/Schema-Export-Tool_apache.md index 90f40296d..febb8c202 100644 --- a/src/UserGuide/Master/Table/Tools-System/Schema-Export-Tool_apache.md +++ b/src/UserGuide/Master/Table/Tools-System/Schema-Export-Tool_apache.md @@ -31,7 +31,7 @@ The schema export tool `export-schema.sh/bat` is located in the `tools` director | **Short Param** | **Full Param** | **Description** | Required | Default | |-----------------|--------------------------|--------------------------------------------------------------------------| ------------------------------------- |---------------------------------------------| -| `-h` | `-- host` | Hostname | No | 127.0.0.1 | +| `-h` | `-- host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | 127.0.0.1 | | `-p` | `--port` | Port number | No | 6667 | | `-u` | `--username` | Username | No | root | | `-pw` | `--password` | Password. Supported for hidden input since V2.0.10 | No | root | @@ -48,6 +48,8 @@ The schema export tool `export-schema.sh/bat` is located in the `tools` director | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. Replace `DN_IPV6_ADDRESS` with the actual reachable DataNode IPv6 address before running the command. For SSL, retain the existing parameters and ensure the certificate SAN contains the actual IPv6 address. + ### 2.2 Command ```Bash @@ -109,3 +111,5 @@ CREATE TABLE table2( arrival_time TIMESTAMP FIELD ); ``` + +Starting with V2.0.12, `-h` accepts an actual unbracketed IPv6 address and `-p` still takes the port separately. The other export parameters do not need to change for IPv6. diff --git a/src/UserGuide/Master/Table/Tools-System/Schema-Import-Tool_apache.md b/src/UserGuide/Master/Table/Tools-System/Schema-Import-Tool_apache.md index e5da8a906..d257730d0 100644 --- a/src/UserGuide/Master/Table/Tools-System/Schema-Import-Tool_apache.md +++ b/src/UserGuide/Master/Table/Tools-System/Schema-Import-Tool_apache.md @@ -31,7 +31,7 @@ The schema import tool `import-schema.sh/bat` is located in `tools` directory. | **Short Param** | **Full Param** | **Description** | Required | Default | |-----------------|---------------------------|--------------------------------------------------------------------------| ---------- |-------------------------------------------| -| `-h` | `-- host` | Hostname | No | 127.0.0.1 | +| `-h` | `-- host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | 127.0.0.1 | | `-p` | `--port` | Port number | No | 6667 | | `-u` | `--username` | Username | No | root | | `-pw` | `--password` | Password. Supported for hidden input since V2.0.10 | No | root | @@ -46,6 +46,8 @@ The schema import tool `import-schema.sh/bat` is located in `tools` directory. | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. Replace `DN_IPV6_ADDRESS` with the actual reachable DataNode IPv6 address before running the command. For SSL, retain the existing parameters and ensure the certificate SAN contains the actual IPv6 address. + ### 2.2 Command ```Bash @@ -164,3 +166,5 @@ IoTDB:database2> desc table2 |arrival_time|TIMESTAMP| FIELD| +------------+---------+---------+ ``` + +Starting with V2.0.12, `-h` accepts an actual unbracketed IPv6 address and `-p` still takes the port separately. The other import parameters do not need to change for IPv6. diff --git a/src/UserGuide/Master/Table/User-Manual/Data-Sync_apache.md b/src/UserGuide/Master/Table/User-Manual/Data-Sync_apache.md index b05adcd81..53a84a7b5 100644 --- a/src/UserGuide/Master/Table/User-Manual/Data-Sync_apache.md +++ b/src/UserGuide/Master/Table/User-Manual/Data-Sync_apache.md @@ -343,6 +343,16 @@ WITH SINK ( ) ``` +```sql +create pipe A2B_IPV6 +with sink ( + 'sink'='iotdb-thrift-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667' +) +``` + +Starting with V2.0.12, Pipe supports IPv6 endpoints for connecting to the destination IoTDB. `node-urls` includes both an address and port and uses `[ipv6]:port` for IPv6; separate multiple endpoints with commas. `DN_IPV6_ADDRESS` and `DN_IPV6_ADDRESS_2` in the independent example above represent the actual reachable IPv6 addresses of two destination DataNodes. Replace them before use; retain the existing Pipe examples. + ### 3.2 Partial Data Synchronization This example demonstrates synchronizing data within a specific historical time range (from August 23, 2023, 8:00 to October 23, 2023, 8:00) to another IoTDB. The data pipeline is shown below: @@ -504,6 +514,18 @@ Where: - `ssl.trust-store-path`: The trust store certificate path required to connect to the target DataNode - `ssl.trust-store-pwd`: The trust store certificate password required to connect to the target DataNode +```sql +create pipe A2B_SSL_IPV6 +with sink ( + 'sink'='iotdb-thrift-ssl-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667', + 'ssl.trust-store-path'='pki/trusted', + 'ssl.trust-store-pwd'='' +) +``` + +For TLS server identity verification over IPv6, the server certificate SAN must contain the actual IPv6 address used by the client as an unbracketed `IP Address`, without a port. + ## Reference: Notes You can adjust the parameters for data synchronization by modifying the IoTDB configuration file (`iotdb-system.properties`), such as the directory for storing synchronized data. The complete configuration is as follows: @@ -598,7 +620,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **Parameter** | **Description** | Value Range | Required | Default Value | |:--------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| :----------------------------------------------------------- | :------- | :------------ | | sink | iotdb-thrift-sink or iotdb-thrift-async-sink | String: iotdb-thrift-sink or iotdb-thrift-async-sink | Yes | - | -| node-urls | URLs of the DataNode service ports on the target IoTDB. (please note that the synchronization task does not support forwarding to its own service). | String. Example：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | Yes | - | +| node-urls | Data service endpoints of multiple DataNodes on the destination IoTDB (synchronization tasks cannot forward to their own service). IPv6 uses `[ipv6]:port`; separate multiple endpoints with commas. IPv6 is supported from V2.0.12. | String. Examples: `'127.0.0.1:6667,127.0.0.1:6668'`, `'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | Yes | - | | user/username | Username for connecting to the target IoTDB. Must have appropriate permissions. | String | No | root | | password | Password for the username. | String | No | root | | batch.enable | Enables batch mode for log transmission to improve throughput and reduce IOPS. | Boolean: true, false | No | true | @@ -618,7 +640,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **Parameter** | **Description** | Value Range | Required | Default Value | |:-------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------|:---------| :------------ | | sink | iotdb-thrift-ssl-sink | String: iotdb-thrift-ssl-sink | Yes | - | -| node-urls | URLs of the DataNode service ports on the target IoTDB. (please note that the synchronization task does not support forwarding to its own service). | String. Example：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | Yes | - | +| node-urls | Data service endpoints of multiple DataNodes on the destination IoTDB (synchronization tasks cannot forward to their own service). IPv6 uses `[ipv6]:port`; separate multiple endpoints with commas; the destination certificate SAN must cover the actual connection address. IPv6 is supported from V2.0.12. | String. Examples: `'127.0.0.1:6667,127.0.0.1:6668'`, `'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | Yes | - | | user/username | Username for connecting to the target IoTDB. Must have appropriate permissions. | String | No | root | | password | Password for the username. | String | No | root | | batch.enable | Enables batch mode for log transmission to improve throughput and reduce IOPS. | Boolean: true, false | No | true | diff --git a/src/UserGuide/Master/Table/User-Manual/Load-Balance_apache.md b/src/UserGuide/Master/Table/User-Manual/Load-Balance_apache.md index b1b760005..343c8d267 100644 --- a/src/UserGuide/Master/Table/User-Manual/Load-Balance_apache.md +++ b/src/UserGuide/Master/Table/User-Manual/Load-Balance_apache.md @@ -110,6 +110,8 @@ If you want to further balance historical data after scale-out, you can execute echo "192.168.1.3 iotdb-1" >> /etc/hosts ``` +7. IPv6 network checks: when expanding in a dual-stack or IPv6-only network, verify IPv6 routing and required ports between existing and new nodes, consistent DNS or `/etc/hosts` resolution, and that the configured IPv6 addresses are bound to the appropriate network interfaces. `0.0.0.0` and `::` are listening addresses only and cannot be used as remote targets for a new node to register with the cluster. + #### 2.2.2 Scaling Operation 1. To ensure the IoTDB installation package you obtained is complete and correct, it is recommended to perform an SHA512 checksum before installation and deployment. @@ -129,15 +131,25 @@ vim iotdb-system.properties | Configuration Item | Description | Default | Remarks | |-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|-------------------| ---------------------------------------------------------------------------------------------------------------------------------- | -| `dn_seed_config_node` | The ConfigNode address (format:`cn_internal_address:cn_internal_port`) that a node connects to when registering to join the cluster. | 127.0.0.1:10710 | Extremely important. You must modify this item to the address of the primary ConfigNode in the original cluster. | -| `dn_rpc_address` | Address for the client RPC service. | 0.0.0.0 | Modify as needed; restart service to take effect. | +| `dn_seed_config_node` | ConfigNode endpoint used for node registration and joining the cluster, namely `cn_internal_address:cn_internal_port`. IPv6 uses `[ipv6]:port`. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | Extremely important. You must modify this item to the address of the primary ConfigNode in the original cluster. | +| `dn_rpc_address` | Client RPC listening address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | 0.0.0.0 | Modify as needed; restart service to take effect. | | `dn_rpc_port` | Port for the client RPC service. | 6667 | Modify as needed; restart service to take effect. | -| `dn_internal_address` | Address used by the DataNode for internal cluster communication. | 127.0.0.1 | Modify as needed; cannot be changed after the first startup. | +| `dn_internal_address` | DataNode internal cluster communication address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | Modify as needed; cannot be changed after the first startup. | | `dn_internal_port` | Port used by the DataNode for internal cluster communication. | 10730 | Modify as needed; cannot be changed after the first startup. | | `dn_mpp_data_exchange_port` | Port used by the DataNode for receiving data streams. | 10740 | Modify as needed; restart service to take effect. | | `dn_data_region_consensus_port` | Port used by the DataNode for consensus protocol communication of data replicas. | 10750 | Modify as needed; restart service to take effect. | | `dn_schema_region_consensus_port` | Port used by the DataNode for consensus protocol communication of metadata replicas. | 10760 | Modify as needed; restart service to take effect. | +IPv6-only expansion example: + +```properties +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +dn_rpc_address=NEW_DN_IPV6_ADDRESS +dn_internal_address=NEW_DN_IPV6_ADDRESS +``` + +`CN_IPV6_ADDRESS` is the reachable IPv6 address of a ConfigNode in the existing cluster. `NEW_DN_IPV6_ADDRESS` is an IPv6 address bound to and routable on the new node. Replace both before applying the configuration. After startup, run `show datanodes` and verify that the new node is `Running` and its address field displays the configured unbracketed IPv6 address. If `::` is returned, configure an actual routable IPv6 address for the node’s published address. + 4. Start the DataNode. Navigate to the `sbin`directory under IoTDB and start the datanode: diff --git a/src/UserGuide/Master/Tree/API/Programming-Cpp-Native-API.md b/src/UserGuide/Master/Tree/API/Programming-Cpp-Native-API.md index 607719617..3f6ffb26e 100644 --- a/src/UserGuide/Master/Tree/API/Programming-Cpp-Native-API.md +++ b/src/UserGuide/Master/Tree/API/Programming-Cpp-Native-API.md @@ -188,6 +188,8 @@ Notice: this RPC compression status of client must comply with that of IoTDB ser void close(); ``` +Starting with V2.0.12, C++ Session supports IPv6 connections to IoTDB. When initializing a client with IPv6, use an unbracketed IPv6 host and a separate port if the API takes them separately; if it takes a node URL, use `[ipv6]:port`. Replace `DN_IPV6_ADDRESS` with the destination DataNode’s actual reachable IPv6 address. Clients must not use `0.0.0.0`, `::`, or equivalent addresses as remote targets during node discovery or redirection. For SSL, the server certificate SAN must contain the actual unbracketed IPv6 `IP Address` used by the client; see the communication encryption chapter for SSL settings and certificate requirements. + ### 3.2 Data Definition Interface (DDL) #### Database Management @@ -447,4 +449,3 @@ Failed to delete cached file C:\Users\Administrator\.m2\repository\.cache\downlo Possible fixes: - Try to delete the ".m2\repository\\.cache\" directory and try again. - Add "\true\" configuration to the download-maven-plugin maven phase that complains this error. - diff --git a/src/UserGuide/Master/Tree/API/Programming-JDBC_apache.md b/src/UserGuide/Master/Tree/API/Programming-JDBC_apache.md index 3ad8bdb19..23eafb93b 100644 --- a/src/UserGuide/Master/Tree/API/Programming-JDBC_apache.md +++ b/src/UserGuide/Master/Tree/API/Programming-JDBC_apache.md @@ -293,4 +293,13 @@ public class JDBCCharsetExample { } } } + +```java +// Starting with V2.0.12, use [ipv6]:port in IPv6 URLs +// String ipv6Url = "jdbc:iotdb://[IPV6_ADDRESS]:6667/"; +// Retain the existing SSL parameters: +// String ipv6SslUrl = "jdbc:iotdb://[IPV6_ADDRESS]:6667?use_ssl=true"; +``` + +JDBC URLs include both an address and port and use `jdbc:iotdb://[ipv6]:port/` for IPv6; brackets around the address are required. Replace `IPV6_ADDRESS` in the comments with an actual reachable IPv6 address; retain the existing IPv4 URL. For SSL, retain the existing connection parameters; the server certificate SAN must include the actual unbracketed IPv6 `IP Address` accessed by the client. ``` \ No newline at end of file diff --git a/src/UserGuide/Master/Tree/API/Programming-Java-Native-API_apache.md b/src/UserGuide/Master/Tree/API/Programming-Java-Native-API_apache.md index b53401425..925d4b828 100644 --- a/src/UserGuide/Master/Tree/API/Programming-Java-Native-API_apache.md +++ b/src/UserGuide/Master/Tree/API/Programming-Java-Native-API_apache.md @@ -77,6 +77,13 @@ public class IoTDBSessionPoolExample { } ``` +```java +// An IPv6 node URL includes both an address and port: +// nodeUrls.add("[IPV6_ADDRESS]:6667"); +``` + +Starting with V2.0.12, Java Session and SessionPool support IPv6 connections to IoTDB. Each `nodeUrls` entry combines an address and port and uses `[ipv6]:port` for IPv6. `IPV6_ADDRESS` in the comment marks the actual node address to supply; retain the existing `nodeUrls.add` calls. When an API takes host and port separately, use an unbracketed IPv6 host and pass the port separately. Pool retries and node refreshes use the same endpoint rules. + ### 2.3 Performing Database Operations #### 2.3.1 Data Insertion @@ -495,7 +502,7 @@ The Session class has the following fields, which can be set through the constru | **Field Name** | **Type** | **Description** | | -------------------------------- | ----------------------------------- | ------------------------------------------------------------ | -| `nodeUrls` | `List` | List of URLs for database nodes, supporting multiple node connections | +| `nodeUrls` | `List` | List of database node URLs for multi-node connections; IPv6 endpoints use `[ipv6]:port`, for example `[DN_IPV6_ADDRESS]:6667`. IPv6 is supported from V2.0.12. | | `username` | `String` | Username | | `password` | `String` | Password | | `fetchSize` | `int` | Default batch size for query results | diff --git a/src/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md b/src/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md index b77fe093d..d1c72dd1d 100644 --- a/src/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md +++ b/src/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md @@ -97,6 +97,25 @@ Notice: this RPC compression status of client must comply with that of IoTDB ser session.close() ``` +```python +# Use an unbracketed IPv6 host when host and port are separate +session = Session( + ip="DN_IPV6_ADDRESS", + port="6667", + user="root", + password="", +) + +# Node URLs include both an address and port and use [ipv6]:port for IPv6 +session = Session.init_from_node_urls( + node_urls=["[DN_IPV6_ADDRESS]:6667", "[DN_IPV6_ADDRESS_2]:6667"], + user="root", + password="", +) +``` + +Starting with V2.0.12, Python Session and SessionPool support IPv6 connections to IoTDB. Use an unbracketed IPv6 address for a separate `ip` argument; do not pass a bracketed address to the underlying socket. `node_urls` entries contain both an address and port and use `[ipv6]:port`. Replace `DN_IPV6_ADDRESS` and `DN_IPV6_ADDRESS_2` with the actual reachable IPv6 addresses of the two nodes. Retain the existing IPv4 examples. + ## 4. Managing Session through SessionPool Utilizing SessionPool to manage sessions eliminates the need to worry about session reuse. When the number of session connections reaches the maximum capacity of the pool, requests for acquiring a session will be blocked, and you can set the blocking wait time through parameters. After using a session, it should be returned to the SessionPool using the `putBack` method for proper management. @@ -228,6 +247,8 @@ if __name__ == "__main__": df = get_data() ``` +Use an unbracketed IPv6 host for SSL connections. The CA specified by `ca_certs` must validate the server certificate, and the server certificate SAN must contain the actual unbracketed IPv6 `IP Address` used by the client. TLS server identity verification fails if the SAN does not contain that address. + ## 5. Data Definition Interface (DDL Interface) ### 5.1 Database Management @@ -870,4 +891,3 @@ Namely, these are * Run Tests via pytest * Build * Release to pypi - diff --git a/src/UserGuide/Master/Tree/Deployment-and-Maintenance/AINode_Deployment_apache.md b/src/UserGuide/Master/Tree/Deployment-and-Maintenance/AINode_Deployment_apache.md index 3a462bf66..283556201 100644 --- a/src/UserGuide/Master/Tree/Deployment-and-Maintenance/AINode_Deployment_apache.md +++ b/src/UserGuide/Master/Tree/Deployment-and-Maintenance/AINode_Deployment_apache.md @@ -113,18 +113,26 @@ AINode supports modifying some necessary parameters. You can find the following | **Name** | **Description** | **Type** | **Default Value** | | ------------------------------ | ------------------------------------------------------------ | -------- | ------------------ | | cluster_name | Identifier of the cluster AINode joins | string | defaultCluster | -| ain_seed_config_node | Address of the ConfigNode registered when AINode starts | String | 127.0.0.1:10710 | -| ain_cluster_ingress_address | RPC address of the DataNode for AINode to pull data | String | 127.0.0.1 | +| ain_seed_config_node | ConfigNode endpoint used for AINode registration at startup. Supports `ipv4:port`, `hostname:port`, or `[ipv6]:port`, for example `[CN_IPV6_ADDRESS]:10710`. IPv6 is supported from V2.0.12. | String | 127.0.0.1:10710 | +| ain_cluster_ingress_address | DataNode RPC address from which AINode pulls data. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | String | 127.0.0.1 | | ain_cluster_ingress_port | RPC port of the DataNode for AINode to pull data | Integer | 6667 | | ain_cluster_ingress_username | Client username for AINode to pull data from the DataNode | String | root | | ain_cluster_ingress_password | Client password for AINode to pull data from the DataNode | String | root | | ain_cluster_ingress_time_zone | Client time zone for AINode to pull data from the DataNode | String | UTC+8 | -| ain_inference_rpc_address | Address for AINode to provide services and communication (internal interface) | String | 127.0.0.1 | +| ain_inference_rpc_address | Address used for AINode services and internal communication. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | String | 127.0.0.1 | | ain_inference_rpc_port | Port for AINode to provide services and communication | String | 10810 | | ain_system_dir | Metadata storage path for AINode (relative path starts from OS-dependent directory; absolute path is recommended) | String | data/AINode/system | | ain_models_dir | Path to store model files for AINode (relative path starts from OS-dependent directory; absolute path is recommended) | String | data/AINode/models | | ain_thrift_compression_enabled | Whether to enable Thrift compression for AINode (0=disabled, 1=enabled) | Boolean | 0 | +```properties +ain_seed_config_node=[CN_IPV6_ADDRESS]:10710 +ain_cluster_ingress_address=DN_IPV6_ADDRESS +ain_inference_rpc_address=AINODE_IPV6_ADDRESS +``` + +`ain_seed_config_node` includes both an address and port and uses `[ipv6]:port` for IPv6. `ain_cluster_ingress_address` and `ain_inference_rpc_address` contain addresses only and use unbracketed IPv6. Replace `CN_IPV6_ADDRESS`, `DN_IPV6_ADDRESS`, and `AINODE_IPV6_ADDRESS` with the actual reachable addresses of the ConfigNode, DataNode, and AINode. After startup, verify that AINode is registered with ConfigNode and can access DataNode. + ### 3.3 Importing Weight Files > Offline environment only (Online environments can skip this step) diff --git a/src/UserGuide/Master/Tree/Deployment-and-Maintenance/Cluster-Deployment_apache.md b/src/UserGuide/Master/Tree/Deployment-and-Maintenance/Cluster-Deployment_apache.md index 045e71a7e..3de92c130 100644 --- a/src/UserGuide/Master/Tree/Deployment-and-Maintenance/Cluster-Deployment_apache.md +++ b/src/UserGuide/Master/Tree/Deployment-and-Maintenance/Cluster-Deployment_apache.md @@ -49,6 +49,8 @@ This section will take the IoTDB classic cluster deployment architecture 3C3D (3 6. Before installation, the health check tool can help inspect the operating environment of IoTDB nodes and obtain detailed inspection results. The usage method of the IoTDB health check tool can be found in:[Health Check Tool](../Tools-System/Health-Check-Tool.md). +For dual-stack or IPv6-only deployment, verify before startup that IPv6 is enabled in the operating system and the configured addresses are assigned to the appropriate network interfaces and can be bound by the services; that IPv6 routing between ConfigNodes, DataNodes, and AINodes is reachable and the required RPC, consensus, and client ports are allowed through the firewall; and that DNS or `/etc/hosts` resolution is consistent across nodes when hostnames are used. `0.0.0.0` and `::` are wildcard listening addresses only and cannot be used for node registration, node discovery, client redirection, or other remote connection targets. + ## 2. Preparation Steps 1. Prepare the IoTDB database installation package:：apache-iotdb-{version}-all-bin.zip（Please refer to the installation package for details：[IoTDB-Package](../Deployment-and-Maintenance/IoTDB-Package_apache.md)） @@ -146,10 +148,10 @@ Open the ConfigNode configuration file `./conf/iotdb-system.properties`， Set t | **Configuration** | **Description** | **Default** | **Recommended value** | 192.168.1.3 | 192.168.1.4 | 192.168.1.5 | Note | | ------------------- | ------------------------------------------------------------ | --------------- | ------------------------------------------------------------ | ------------- | ------------- | ------------- | ---------------------------------------- | -| cn_internal_address | The address used by ConfigNode for communication within the cluster | 127.0.0.1 | The IPV4 address or host name of the server where it is located, and it is recommended to use host name | iotdb-1 | iotdb-2 | iotdb-3 | Cannot be modified after initial startup | +| cn_internal_address | Address used for ConfigNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | iotdb-1 | iotdb-2 | iotdb-3 | Cannot be modified after initial startup | | cn_internal_port | The port used by ConfigNode for communication within the cluster | 10710 | 10710 | 10710 | 10710 | 10710 | Cannot be modified after initial startup | | cn_consensus_port | The port used for ConfigNode replica group consensus protocol communication | 10720 | 10720 | 10720 | 10720 | 10720 | Cannot be modified after initial startup | -| cn_seed_config_node | The address of the ConfigNode that the node connects to when registering to join the cluster, `cn_internal_address:cn_internal_port` | 127.0.0.1:10710 | The first CongfigNode's `cn_internal-address: cn_internal_port` | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | Cannot be modified after initial startup | +| cn_seed_config_node | ConfigNode endpoint used for node registration and joining the cluster, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | The first CongfigNode's `cn_internal-address: cn_internal_port` | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | Cannot be modified after initial startup | #### DataNode Configuration @@ -157,14 +159,31 @@ Open DataNode Configuration File `./conf/iotdb-system.properties`,Set the follow | **Configuration** | **Description** | **Default** | **Recommended value** | 192.168.1.3 | 192.168.1.4 | 192.168.1.5 | Note | | ------------------------------- | ------------------------------------------------------------ |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------- | ------------- | ------------- | ---------------------------------------- | -| dn_rpc_address | The address of the client RPC service | 127.0.0.1 | By default, the local machine can directly access it. For non-local access, please modify this configuration item to the IPv4 address or hostname of the server where it is located. It is recommended to use the IPv4 address of the server where it is located. | iotdb-1 |iotdb-2 | iotdb-3 | Restarting the service takes effect | +| dn_rpc_address | Client RPC listening address. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | Local access only by default; for remote access, specify the server’s routable IPv4 address, unbracketed IPv6 address, or hostname | iotdb-1 |iotdb-2 | iotdb-3 | Restarting the service takes effect | | dn_rpc_port | The port of the client RPC service | 6667 | 6667 | 6667 | 6667 | 6667 | Restarting the service takes effect | -| dn_internal_address | The address used by DataNode for communication within the cluster | 127.0.0.1 | The IPV4 address or host name of the server where it is located, and it is recommended to use host name | iotdb-1 | iotdb-2 | iotdb-3 | Cannot be modified after initial startup | +| dn_internal_address | Address used for DataNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | iotdb-1 | iotdb-2 | iotdb-3 | Cannot be modified after initial startup | | dn_internal_port | The port used by DataNode for communication within the cluster | 10730 | 10730 | 10730 | 10730 | 10730 | Cannot be modified after initial startup | | dn_mpp_data_exchange_port | The port used by DataNode to receive data streams | 10740 | 10740 | 10740 | 10740 | 10740 | Cannot be modified after initial startup | | dn_data_region_consensus_port | The port used by DataNode for data replica consensus protocol communication | 10750 | 10750 | 10750 | 10750 | 10750 | Cannot be modified after initial startup | | dn_schema_region_consensus_port | The port used by DataNode for metadata replica consensus protocol communication | 10760 | 10760 | 10760 | 10760 | 10760 | Cannot be modified after initial startup | -| dn_seed_config_node | The address of the ConfigNode that the node connects to when registering to join the cluster, i.e. `cn_internal-address: cn_internal_port` | 127.0.0.1:10710 | The first CongfigNode's cn_internal-address: cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | Cannot be modified after initial startup | +| dn_seed_config_node | ConfigNode endpoint used for node registration and joining the cluster, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | The first CongfigNode's cn_internal-address: cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | Cannot be modified after initial startup | + +The following IPv6-only example shows one ConfigNode and one DataNode in addition to the existing IPv4/hostname examples. Replace `CN_IPV6_ADDRESS` and `DN_IPV6_ADDRESS` with the nodes’ actual reachable IPv6 addresses before deployment. + +```properties +# ConfigNode +cn_internal_address=CN_IPV6_ADDRESS +cn_seed_config_node=[CN_IPV6_ADDRESS]:10710 + +# DataNode +dn_internal_address=DN_IPV6_ADDRESS +dn_rpc_address=DN_IPV6_ADDRESS +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +``` + +`cn_internal_address`, `dn_internal_address`, and `dn_rpc_address` take addresses only and use unbracketed IPv6. `cn_seed_config_node` and `dn_seed_config_node` include addresses and ports and use `[ipv6]:port`. + +After startup, verify that the DataNode has registered with the ConfigNode. Cluster IP fields may show unbracketed IPv6; endpoints in logs, errors, and other output must use `[ipv6]:port`. If the service listens on `::`, the node must still publish an actual routable IPv6 address. > ❗️Attention: Editors such as VSCode Remote do not have automatic configuration saving function. Please ensure that the modified files are saved persistently, otherwise the configuration items will not take effect @@ -205,6 +224,8 @@ cd sbin .\windows\start-datanode.bat ``` +After startup, run `show cluster` in the CLI to verify that ConfigNodes and DataNodes are registered. In an IPv6-only environment, node address fields should display the configured unbracketed IPv6 addresses; addresses with ports in logs or errors should use `[ipv6]:port`. If `::` is returned as a node address, configure an actual routable IPv6 address for the node’s published address. + ### 3.5 Verify Deployment Can be executed directly Cli startup script in `./sbin` directory: @@ -221,6 +242,12 @@ Can be executed directly Cli startup script in `./sbin` directory: .\windows\start-cli.bat -h ip -p 6667 ``` +When passing an IPv6 address separately with `-h`, omit brackets and specify the port with `-p`. For example: + +```shell +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' +``` + After successful startup, the following interface will appear displaying successful installation of IOTDB. ![](/img/%E5%BC%80%E6%BA%90%E6%88%90%E5%8A%9F.png) diff --git a/src/UserGuide/Master/Tree/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md b/src/UserGuide/Master/Tree/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md index 96d024467..cff297a8e 100644 --- a/src/UserGuide/Master/Tree/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md +++ b/src/UserGuide/Master/Tree/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md @@ -115,10 +115,10 @@ Open the ConfigNode configuration file (./conf/iotdb-system. properties file) an | **Configuration** | **Description** | **Default** | **Recommended value** | Note | | :-----------------: | :----------------------------------------------------------: | :-------------: | :----------------------------------------------------------: | :--------------------------------------: | -| cn_internal_address | The address used by ConfigNode for communication within the cluster | 127.0.0.1 | The IPV4 address or host name of the server where it is located, and it is recommended to use host name | Cannot be modified after initial startup | +| cn_internal_address | Address used for ConfigNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | Cannot be modified after initial startup | | cn_internal_port | The port used by ConfigNode for communication within the cluster | 10710 | 10710 | Cannot be modified after initial startup | | cn_consensus_port | The port used for ConfigNode replica group consensus protocol communication | 10720 | 10720 | Cannot be modified after initial startup | -| cn_seed_config_node | The address of the ConfigNode that the node connects to when registering to join the cluster, cn_internal_address:cn_internal_port | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | Cannot be modified after initial startup | +| cn_seed_config_node | ConfigNode endpoint used for node registration, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | Cannot be modified after initial startup | #### DataNode Configuration @@ -126,14 +126,26 @@ Open the DataNode configuration file (./conf/iotdb-system. properties file) and | **Configuration** | **Description** | **Default** | **Recommended value** | **Note** | | :-----------------------------: | :----------------------------------------------------------: | :-------------: |:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| :--------------------------------------- | -| dn_rpc_address | The address of the client RPC service | 127.0.0.1 | By default, the local machine can directly access it. For non-local access, please modify this configuration item to the IPv4 address or hostname of the server where it is located. It is recommended to use the IPv4 address of the server where it is located. | Restarting the service takes effect | +| dn_rpc_address | Client RPC listening address. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | Local access only by default; for remote access, specify the server’s routable IPv4 address, unbracketed IPv6 address, or hostname | Restarting the service takes effect | | dn_rpc_port | The port of the client RPC service | 6667 | 6667 | Restarting the service takes effect | -| dn_internal_address | The address used by DataNode for communication within the cluster | 127.0.0.1 | The IPV4 address or host name of the server where it is located, and it is recommended to use host name | Cannot be modified after initial startup | +| dn_internal_address | Address used for DataNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | Cannot be modified after initial startup | | dn_internal_port | The port used by DataNode for communication within the cluster | 10730 | 10730 | Cannot be modified after initial startup | | dn_mpp_data_exchange_port | The port used by DataNode to receive data streams | 10740 | 10740 | Cannot be modified after initial startup | | dn_data_region_consensus_port | The port used by DataNode for data replica consensus protocol communication | 10750 | 10750 | Cannot be modified after initial startup | | dn_schema_region_consensus_port | The port used by DataNode for metadata replica consensus protocol communication | 10760 | 10760 | Cannot be modified after initial startup | -| dn_seed_config_node | The ConfigNode address that the node connects to when registering to join the cluster, i.e. cn_internal-address: cn_internal_port | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | Cannot be modified after initial startup | +| dn_seed_config_node | ConfigNode endpoint used for node registration, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | Cannot be modified after initial startup | + +Standalone instances accessed only from the local host can use the IPv6 loopback address: + +```properties +cn_internal_address=::1 +cn_seed_config_node=[::1]:10710 +dn_internal_address=::1 +dn_rpc_address=::1 +dn_seed_config_node=[::1]:10710 +``` + +`::1` is the IPv6 loopback address and is for local access or testing only. For access from other hosts, use the local host’s actual routable IPv6 address. `::` listens on all IPv6 interfaces and cannot be used as a remote target, node discovery result, or client redirection address. > ❗️Attention: Editors such as VSCode Remote do not have automatic configuration saving function. Please ensure that the modified files are saved persistently, otherwise the configuration items will not take effect diff --git a/src/UserGuide/Master/Tree/FAQ/Frequently-asked-questions.md b/src/UserGuide/Master/Tree/FAQ/Frequently-asked-questions.md index 6f70b4992..b629c1ef9 100644 --- a/src/UserGuide/Master/Tree/FAQ/Frequently-asked-questions.md +++ b/src/UserGuide/Master/Tree/FAQ/Frequently-asked-questions.md @@ -332,3 +332,33 @@ Notes: #### How to decrease the memory usage of ConfigNode/DataNode? - Adjust the ON_HEAP_MEMORY、OFF_HEAP_MEMORY options in conf/confignode-env.sh and conf/datanode-env.sh. + +## 3. IPv6 Connection FAQ + +### 3.1 Why is `[::1]:6667` valid while `::1:6667` should not be used as an endpoint? + +Starting with V2.0.12, IoTDB supports IPv6 connections. IPv6 addresses contain multiple colons. Address and port combinations must use `[ipv6]:port` to distinguish them. The address and port in JDBC URLs, Session node URLs, and Pipe `node-urls` must use `[ipv6]:port`. + +### 3.2 Why do address parameters use unbracketed IPv6 while JDBC and Pipe use `[ipv6]:port`? + +Parameters such as `cn_internal_address`, `dn_internal_address`, and `dn_rpc_address` contain addresses only and use unbracketed IPv6. JDBC URLs, seed endpoints, Session node URLs, and Pipe `node-urls` include both addresses and ports and use `[ipv6]:port`. + +### 3.3 Why does listening on `::` succeed while clients still cannot connect? + +`::` listens on all IPv6 interfaces and is not a routable remote address. Node registration, node discovery, client redirection, Pipe destinations, and Prometheus targets must use actual reachable IPv6 addresses. + +### 3.4 How do I resolve hostname or IP verification failures in IPv6 TLS connections? + +Check that the server certificate SAN contains the actual unbracketed IPv6 `IP Address` used by the client, without brackets or a port. Also verify that the client TrustStore contains the CA that issued the certificate. + +### 3.5 How do I troubleshoot connection failures in an IPv6-only environment? + +Check, in order, that IPv6 is enabled in the operating system, addresses are bound, inter-node routes and ports are reachable, firewalls allow traffic, DNS or `/etc/hosts` resolution is consistent, and the client runtime and underlying socket support IPv6. + +### 3.6 What if IPv4 works but IPv6 connections fail in a dual-stack environment? + +First connect directly with the actual IPv6 address and port using the required syntax, and verify that the destination service is bound to an IPv6 address and routing and firewall rules allow access to the port. Then check that DNS AAAA records or IPv6 mappings in `/etc/hosts` point to the destination. Verify IPv4 and IPv6 paths separately; successful IPv4 connections do not confirm IPv6 connectivity. Do not publish `::` as a node address. + +### 3.7 How do I resolve IPv6 endpoint parsing errors in Pipe? + +Check that every IPv6 endpoint uses `[ipv6]:port`, that multiple endpoints are separated by commas, and that `::` or `0.0.0.0` has not been used as a destination. For SSL Pipe, also check the TrustStore, KeyStore, and destination certificate SAN. diff --git a/src/UserGuide/Master/Tree/Reference/System-Config-Manual_apache.md b/src/UserGuide/Master/Tree/Reference/System-Config-Manual_apache.md index a34c65b21..380ca970f 100644 --- a/src/UserGuide/Master/Tree/Reference/System-Config-Manual_apache.md +++ b/src/UserGuide/Master/Tree/Reference/System-Config-Manual_apache.md @@ -144,11 +144,15 @@ The `iotdb-system.properties` file contains various configurations for managing ### 4.2 Seed ConfigNode +> Address-only parameters use unbracketed IPv6 addresses; endpoints containing both an address and a port use `[ipv6]:port`. + +`CN_IPV6_ADDRESS` below marks the ConfigNode IPv6 address field. Use an actual resolvable, routable address. Existing IPv4/hostname examples and default values remain unchanged. + - cn_seed_config_node | Name | cn_seed_config_node | | ----------- | ------------------------------------------------------------ | -| Description | Address of the seed ConfigNode for Confignode to join the cluster. | +| Description | Endpoint of the target ConfigNode through which a ConfigNode joins the cluster; a SeedConfigNode is recommended. Supports `ipv4:port`, `hostname:port`, or `[ipv6]:port`, for example `[CN_IPV6_ADDRESS]:10710`. Previously named cn_target_config_node_list in V1.2.2 and earlier. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1:10710 | | Effective | Modify before the first startup. | @@ -157,7 +161,7 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | dn_seed_config_node | | ----------- | ------------------------------------------------------------ | -| Description | Address of the seed ConfigNode for Datanode to join the cluster. | +| Description | Endpoint of the ConfigNode through which a DataNode joins the cluster at startup; a SeedConfigNode is recommended. Supports `ipv4:port`, `hostname:port`, or `[ipv6]:port`, for example `[CN_IPV6_ADDRESS]:10710`. Previously named dn_target_config_node_list in V1.2.2 and earlier. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1:10710 | | Effective | Modify before the first startup. | @@ -168,7 +172,7 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | cn_internal_address | | ----------- | ---------------------------------------------- | -| Description | Internal address for ConfigNode communication. | +| Description | ConfigNode internal cluster communication address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port, for example `192.168.1.10`, `CN_IPV6_ADDRESS`, or `iotdb-cn-1`. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1 | | Effective | Modify before the first startup. | @@ -195,7 +199,7 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | dn_rpc_address | | ----------- |---------------------------------| -| Description | Address for client RPC service. | +| Description | Listening address for the client RPC service. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port, for example `192.168.1.20`, `DN_IPV6_ADDRESS`, or `iotdb-dn-1`. `::` listens on all IPv6 interfaces, but cannot be returned as a remote address for client redirection or node discovery. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1 | | Effective | Restart required. | @@ -213,11 +217,15 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | dn_internal_address | | ----------- | -------------------------------------------- | -| Description | Internal address for DataNode communication. | +| Description | DataNode internal communication address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port, for example `192.168.1.20`, `DN_IPV6_ADDRESS`, or `iotdb-dn-1`. IPv6 is supported from V2.0.12. | | Type | string | | Default | 127.0.0.1 | | Effective | Modify before the first startup. | +> Use unbracketed IPv6 for address-only parameters, such as `DN_IPV6_ADDRESS`; use `[ipv6]:port` for endpoints containing both an address and port, such as `[DN_IPV6_ADDRESS]:10730`. `0.0.0.0` and `::` are wildcard listening addresses only; do not use them as remote connection targets. + +`DN_IPV6_ADDRESS` below marks the DataNode IPv6 address field. Replace it with an address bound to and reachable on the corresponding node. + - dn_internal_port | Name | dn_internal_port | @@ -523,6 +531,8 @@ The `iotdb-system.properties` file contains various configurations for managing ### 4.7 SSL Configuration +> IPv6 uses the existing SSL/TLS switches, protocols, KeyStore, and TrustStore settings. For TLS server identity verification over IPv6, the server certificate SAN must contain the actual IPv6 address used by the client as an unbracketed `IP Address`, without a port. For example, when connecting to `[DN_IPV6_ADDRESS]:6667`, the SAN must contain `DN_IPV6_ADDRESS`. + - enable_thrift_ssl | Name | enable_thrift_ssl | diff --git a/src/UserGuide/Master/Tree/Tools-System/CLI_apache.md b/src/UserGuide/Master/Tree/Tools-System/CLI_apache.md index d05045fe0..582bbd8e6 100644 --- a/src/UserGuide/Master/Tree/Tools-System/CLI_apache.md +++ b/src/UserGuide/Master/Tree/Tools-System/CLI_apache.md @@ -84,11 +84,21 @@ IoTDB> Enter ```quit``` or `exit` can exit Cli. +Starting with V2.0.12, pass an IPv6 address to `-h` without brackets and specify the port separately with `-p`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with an actual reachable IPv6 address before running the command. Retain the existing IPv4 startup examples. For example: + +```shell +# Linux/macOS +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' + +# Windows (V2.0.4.x and later) +sbin\windows\start-cli.bat -h DN_IPV6_ADDRESS -p 6667 -u root -pw "" +``` + ### 2.2 Cli Parameters | **Parameter** | **Type** | **Required** | **Description** | **Example** | | -------------------------- | -------- | ------------ |-----------------------------------------------------------------------------------| ------------------- | -| -h `` | string | No | The IP address of the IoTDB server. (Default: 127.0.0.1) | -h 127.0.0.1 | +| -h `` | string | No | IPv4 address, unbracketed IPv6 address, or hostname of the IoTDB server to connect to; omit brackets for IPv6. Defaults to `127.0.0.1`. IPv6 is supported from V2.0.12. | -h 127.0.0.1 | | -p `` | int | No | The RPC port of the IoTDB server. (Default: 6667) | -p 6667 | | -u `` | string | No | The username to connect to the IoTDB server. (Default: root) | -u root | | -pw `` | string | No | The password to connect to the IoTDB server. (Default: root) | -pw root | diff --git a/src/UserGuide/Master/Tree/Tools-System/Data-Export-Tool_apache.md b/src/UserGuide/Master/Tree/Tools-System/Data-Export-Tool_apache.md index 1dfb92eac..d0f2c33f1 100644 --- a/src/UserGuide/Master/Tree/Tools-System/Data-Export-Tool_apache.md +++ b/src/UserGuide/Master/Tree/Tools-System/Data-Export-Tool_apache.md @@ -31,7 +31,7 @@ The data export tool, export-data.sh (Unix/OS X) or export-data.bat (Windows), l | Short | Full Parameter | Description | Required | Default | |-----------------|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|------------|---------------------------------------------------------------------------------------------| | `-ft` | `--file_type` | Export file type: `csv`, `sql`, `tsfile`. | ​**Yes** | - | -| `-h` | `--host` | Hostname of the IoTDB server. | No | `127.0.0.1` | +| `-h` | `--host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | `127.0.0.1` | | `-p` | `--port` | Port number of the IoTDB server. | No | `6667` | | `-u` | `--username` | Username for authentication. | No | `root` | | `-pw` | `--password` | Password for authentication. Supported for hidden input since V2.0.10 | No | `root` | @@ -44,6 +44,8 @@ The data export tool, export-data.sh (Unix/OS X) or export-data.bat (Windows), l | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with the actual reachable unbracketed IPv6 address before running the command. Do not pass brackets to `-h`. For SSL, retain the existing `-usessl`, `-ts`, and `-tpw` parameters; the server certificate SAN must contain the actual unbracketed IPv6 address accessed by the client. + ### 2.2 CSV Format #### 2.2.1 Command diff --git a/src/UserGuide/Master/Tree/Tools-System/Data-Import-Tool_apache.md b/src/UserGuide/Master/Tree/Tools-System/Data-Import-Tool_apache.md index e0995b18d..feb323224 100644 --- a/src/UserGuide/Master/Tree/Tools-System/Data-Import-Tool_apache.md +++ b/src/UserGuide/Master/Tree/Tools-System/Data-Import-Tool_apache.md @@ -42,7 +42,7 @@ IoTDB supports three methods for data import: | Short | Full Parameter | Description | Required | Default | |-----------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------- |-----------------------------------------------| | `-ft` | `--file_type` | File type: `csv`, `sql`, `tsfile`. | ​**Yes** | - | -| `-h` | `--host` | IoTDB server hostname. | No | `127.0.0.1` | +| `-h` | `--host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | `127.0.0.1` | | `-p` | `--port` | IoTDB server port. | No | `6667` | | `-u` | `--username` | Username. | No | `root` | | `-pw` | `--password` | Password. Supported for hidden input since V2.0.10 | No | `root` | @@ -54,6 +54,8 @@ IoTDB supports three methods for data import: | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with the actual reachable unbracketed IPv6 address before running the command. Do not pass brackets to `-h`. For SSL, retain the existing `-usessl`, `-ts`, and `-tpw` parameters; the server certificate SAN must contain the actual unbracketed IPv6 address accessed by the client. + ### 2.2 CSV Format #### 2.2.1 Command diff --git a/src/UserGuide/Master/Tree/Tools-System/Monitor-Tool_apache.md b/src/UserGuide/Master/Tree/Tools-System/Monitor-Tool_apache.md index b7107644b..7807a5a69 100644 --- a/src/UserGuide/Master/Tree/Tools-System/Monitor-Tool_apache.md +++ b/src/UserGuide/Master/Tree/Tools-System/Monitor-Tool_apache.md @@ -64,6 +64,12 @@ file_count{name="seq",} 2.0 ... ``` +Starting with V2.0.12, the metrics endpoint supports access over IPv6. Use brackets to distinguish the address from the port in an IPv6 metrics URL. Replace the placeholder below with the actual reachable IPv6 address: + +```shell +curl 'http://[IPV6_ADDRESS]:9091/metrics' +``` + ### 1.3 Prometheus + Grafana As shown above, IoTDB exposes monitoring metrics data in the standard Prometheus format to the outside world. Prometheus @@ -95,6 +101,7 @@ follow_redirects: true static_configs: - targets: - localhost:9091 + - '[IPV6_ADDRESS]:9091' ``` The following documents may help you have a good journey with Prometheus and Grafana. @@ -106,3 +113,4 @@ The following documents may help you have a good journey with Prometheus and Gra [Grafana getting_started](https://grafana.com/docs/grafana/latest/getting-started/getting-started/) [Grafana query metrics from Prometheus](https://prometheus.io/docs/visualization/grafana/#grafana-support-for-prometheus) +Prometheus targets include both an IPv6 address and a port and must use `[ipv6]:port`. Even if the service listens on `::`, use an actual routable IPv6 address for the target, never `[::]:9091`. diff --git a/src/UserGuide/Master/Tree/Tools-System/Schema-Export-Tool_apache.md b/src/UserGuide/Master/Tree/Tools-System/Schema-Export-Tool_apache.md index 4e34ab3de..3cf8f5bdf 100644 --- a/src/UserGuide/Master/Tree/Tools-System/Schema-Export-Tool_apache.md +++ b/src/UserGuide/Master/Tree/Tools-System/Schema-Export-Tool_apache.md @@ -31,7 +31,7 @@ The schema export tool `export-schema.sh/bat` is located in the `tools` director | **Short Param** | **Full Param** | **Description** | Required | Default | |------------------|---------------------------|--------------------------------------------------------------------------| ------------------------------------- |-----------------------------------------------| -| `-h` | `-- host` | Hostname | No | 127.0.0.1 | +| `-h` | `-- host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | 127.0.0.1 | | `-p` | `--port` | Port number | No | 6667 | | `-u` | `--username` | Username | No | root | | `-pw` | `--password` | Password. Supported for hidden input since V2.0.10 | No | root | @@ -48,6 +48,8 @@ The schema export tool `export-schema.sh/bat` is located in the `tools` director | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. Replace `DN_IPV6_ADDRESS` with the actual reachable DataNode IPv6 address before running the command. For SSL, retain the existing parameters and ensure the certificate SAN contains the actual IPv6 address. + ### 2.2 Command ```Bash @@ -82,4 +84,6 @@ Shell Timeseries,Alias,DataType,Encoding,Compression root.treedb.device.temperature,,DOUBLE,GORILLA,LZ4 root.treedb.device.humidity,,DOUBLE,GORILLA,LZ4 -``` \ No newline at end of file +``` + +Starting with V2.0.12, `-h` accepts an actual unbracketed IPv6 address and `-p` still takes the port separately. The other export parameters do not need to change for IPv6. \ No newline at end of file diff --git a/src/UserGuide/Master/Tree/Tools-System/Schema-Import-Tool_apache.md b/src/UserGuide/Master/Tree/Tools-System/Schema-Import-Tool_apache.md index ae755ef13..cfbd347ac 100644 --- a/src/UserGuide/Master/Tree/Tools-System/Schema-Import-Tool_apache.md +++ b/src/UserGuide/Master/Tree/Tools-System/Schema-Import-Tool_apache.md @@ -31,7 +31,7 @@ The schema import tool `import-schema.sh/bat` is located in `tools` directory. | **Short Param** | **Full Param** | **Description** | Required | Default | |-----------------|---------------------------|--------------------------------------------------------------------------| ---------- |-------------------------------------------| -| `-h` | `-- host` | Hostname | No | 127.0.0.1 | +| `-h` | `-- host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | 127.0.0.1 | | `-p` | `--port` | Port number | No | 6667 | | `-u` | `--username` | Username | No | root | | `-pw` | `--password` | Password. Supported for hidden input since V2.0.10 | No | root | @@ -46,6 +46,8 @@ The schema import tool `import-schema.sh/bat` is located in `tools` directory. | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. Replace `DN_IPV6_ADDRESS` with the actual reachable DataNode IPv6 address before running the command. For SSL, retain the existing parameters and ensure the certificate SAN contains the actual IPv6 address. + ### 2.2 Command ```Bash @@ -88,3 +90,5 @@ IoTDB> show timeseries root.treedb.** | root.treedb.device.humidity| null|root.treedb| DOUBLE| GORILLA| LZ4|null| null| null| null| BASE| +------------------------------+-----+-----------+--------+--------+-----------+----+----------+--------+------------------+--------+ ``` + +Starting with V2.0.12, `-h` accepts an actual unbracketed IPv6 address and `-p` still takes the port separately. The other import parameters do not need to change for IPv6. diff --git a/src/UserGuide/Master/Tree/User-Manual/Data-Sync_apache.md b/src/UserGuide/Master/Tree/User-Manual/Data-Sync_apache.md index 06bcfaea6..44dc1e0b6 100644 --- a/src/UserGuide/Master/Tree/User-Manual/Data-Sync_apache.md +++ b/src/UserGuide/Master/Tree/User-Manual/Data-Sync_apache.md @@ -368,6 +368,16 @@ with sink ( 'node-urls' = '127.0.0.1:6668', ``` +```sql +create pipe A2B_IPV6 +with sink ( + 'sink'='iotdb-thrift-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667' +) +``` + +Starting with V2.0.12, Pipe supports IPv6 endpoints for connecting to the destination IoTDB. `node-urls` includes both an address and port and uses `[ipv6]:port` for IPv6; separate multiple endpoints with commas. `DN_IPV6_ADDRESS` and `DN_IPV6_ADDRESS_2` in the independent example above represent the actual reachable IPv6 addresses of two destination DataNodes. Replace them before use; retain the existing Pipe examples. + ### 3.2 Partial data synchronization This example is used to demonstrate the synchronisation of data from a certain historical time range (8:00pm 23 August 2023 to 8:00pm 23 October 2023) to another IoTDB, the data link is shown below: @@ -536,6 +546,18 @@ Where: - `ssl.trust-store-path`: The trust store certificate path required to connect to the target DataNode - `ssl.trust-store-pwd`: The trust store certificate password required to connect to the target DataNode +```sql +create pipe A2B_SSL_IPV6 +with sink ( + 'sink'='iotdb-thrift-ssl-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667', + 'ssl.trust-store-path'='pki/trusted', + 'ssl.trust-store-pwd'='' +) +``` + +For TLS server identity verification over IPv6, the server certificate SAN must contain the actual IPv6 address used by the client as an unbracketed `IP Address`, without a port. + ## 4. Reference: Notes You can adjust the parameters for data synchronization by modifying the IoTDB configuration file （`iotdb-system.properties`）, such as the directory for storing synchronized data. The complete configuration is as follows: @@ -632,7 +654,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **Parameter** | **Description** | Value Range | Required | Default Value | |:-----------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| :----------------------------------------------------------- | :------- | :------------ | | sink | iotdb-thrift-sink or iotdb-thrift-async-sink | String: iotdb-thrift-sink or iotdb-thrift-async-sink | Yes | - | -| node-urls | URLs of the DataNode service ports on the target IoTDB. (please note that the synchronization task does not support forwarding to its own service). | String. Example：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | Yes | - | +| node-urls | Data service endpoints of multiple DataNodes on the destination IoTDB (synchronization tasks cannot forward to their own service). IPv6 uses `[ipv6]:port`; separate multiple endpoints with commas. IPv6 is supported from V2.0.12. | String. Examples: `'127.0.0.1:6667,127.0.0.1:6668'`, `'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | Yes | - | | user/username | Username for connecting to the target IoTDB. Must have appropriate permissions. | String | No | root | | password | Password for the username. | String | No | root | | batch.enable | Enables batch mode for log transmission to improve throughput and reduce IOPS. | Boolean: true, false | No | true | @@ -651,7 +673,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **Parameter** | **Description** | Value Range | Required | Default Value | |:-----------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------|:---------| :------------ | | sink | iotdb-thrift-ssl-sink | String: iotdb-thrift-ssl-sink | Yes | - | -| node-urls | URLs of the DataNode service ports on the target IoTDB. (please note that the synchronization task does not support forwarding to its own service). | String. Example：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | Yes | - | +| node-urls | Data service endpoints of multiple DataNodes on the destination IoTDB (synchronization tasks cannot forward to their own service). IPv6 uses `[ipv6]:port`; separate multiple endpoints with commas; the destination certificate SAN must cover the actual connection address. IPv6 is supported from V2.0.12. | String. Examples: `'127.0.0.1:6667,127.0.0.1:6668'`, `'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | Yes | - | | user/username | Username for connecting to the target IoTDB. Must have appropriate permissions. | String | No | root | | password | Password for the username. | String | No | root | | batch.enable | Enables batch mode for log transmission to improve throughput and reduce IOPS. | Boolean: true, false | No | true | @@ -666,4 +688,3 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | ssl.trust-store-pwd | Password for the trust store certificate. | String: 'root' | Yes | - | | format | The payload formats for data transmission include the following options:
- hybrid: The format depends on what is passed from the processor (either tsfile or tablet), and the sink performs no conversion.
- tsfile: Data is forcibly converted to tsfile format before transmission. This is suitable for scenarios like data file backup.
- tablet: Data is forcibly converted to tsfile format before transmission. This is useful for data synchronization when the sender and receiver have incompatible data types (to minimize errors). | String: hybrid / tsfile / tablet | No | hybrid | | exception.data.convert-on-type-mismatch | Whether to enable automatic conversion when data types mismatch on the sink side | Boolean: true / false | No | true | - diff --git a/src/UserGuide/Master/Tree/User-Manual/Load-Balance_apache.md b/src/UserGuide/Master/Tree/User-Manual/Load-Balance_apache.md index b1b760005..343c8d267 100644 --- a/src/UserGuide/Master/Tree/User-Manual/Load-Balance_apache.md +++ b/src/UserGuide/Master/Tree/User-Manual/Load-Balance_apache.md @@ -110,6 +110,8 @@ If you want to further balance historical data after scale-out, you can execute echo "192.168.1.3 iotdb-1" >> /etc/hosts ``` +7. IPv6 network checks: when expanding in a dual-stack or IPv6-only network, verify IPv6 routing and required ports between existing and new nodes, consistent DNS or `/etc/hosts` resolution, and that the configured IPv6 addresses are bound to the appropriate network interfaces. `0.0.0.0` and `::` are listening addresses only and cannot be used as remote targets for a new node to register with the cluster. + #### 2.2.2 Scaling Operation 1. To ensure the IoTDB installation package you obtained is complete and correct, it is recommended to perform an SHA512 checksum before installation and deployment. @@ -129,15 +131,25 @@ vim iotdb-system.properties | Configuration Item | Description | Default | Remarks | |-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|-------------------| ---------------------------------------------------------------------------------------------------------------------------------- | -| `dn_seed_config_node` | The ConfigNode address (format:`cn_internal_address:cn_internal_port`) that a node connects to when registering to join the cluster. | 127.0.0.1:10710 | Extremely important. You must modify this item to the address of the primary ConfigNode in the original cluster. | -| `dn_rpc_address` | Address for the client RPC service. | 0.0.0.0 | Modify as needed; restart service to take effect. | +| `dn_seed_config_node` | ConfigNode endpoint used for node registration and joining the cluster, namely `cn_internal_address:cn_internal_port`. IPv6 uses `[ipv6]:port`. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | Extremely important. You must modify this item to the address of the primary ConfigNode in the original cluster. | +| `dn_rpc_address` | Client RPC listening address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | 0.0.0.0 | Modify as needed; restart service to take effect. | | `dn_rpc_port` | Port for the client RPC service. | 6667 | Modify as needed; restart service to take effect. | -| `dn_internal_address` | Address used by the DataNode for internal cluster communication. | 127.0.0.1 | Modify as needed; cannot be changed after the first startup. | +| `dn_internal_address` | DataNode internal cluster communication address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | Modify as needed; cannot be changed after the first startup. | | `dn_internal_port` | Port used by the DataNode for internal cluster communication. | 10730 | Modify as needed; cannot be changed after the first startup. | | `dn_mpp_data_exchange_port` | Port used by the DataNode for receiving data streams. | 10740 | Modify as needed; restart service to take effect. | | `dn_data_region_consensus_port` | Port used by the DataNode for consensus protocol communication of data replicas. | 10750 | Modify as needed; restart service to take effect. | | `dn_schema_region_consensus_port` | Port used by the DataNode for consensus protocol communication of metadata replicas. | 10760 | Modify as needed; restart service to take effect. | +IPv6-only expansion example: + +```properties +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +dn_rpc_address=NEW_DN_IPV6_ADDRESS +dn_internal_address=NEW_DN_IPV6_ADDRESS +``` + +`CN_IPV6_ADDRESS` is the reachable IPv6 address of a ConfigNode in the existing cluster. `NEW_DN_IPV6_ADDRESS` is an IPv6 address bound to and routable on the new node. Replace both before applying the configuration. After startup, run `show datanodes` and verify that the new node is `Running` and its address field displays the configured unbracketed IPv6 address. If `::` is returned, configure an actual routable IPv6 address for the node’s published address. + 4. Start the DataNode. Navigate to the `sbin`directory under IoTDB and start the datanode: diff --git a/src/UserGuide/latest-Table/API/Programming-Cpp-Native-API_apache.md b/src/UserGuide/latest-Table/API/Programming-Cpp-Native-API_apache.md index cea01bfcd..82822a06a 100644 --- a/src/UserGuide/latest-Table/API/Programming-Cpp-Native-API_apache.md +++ b/src/UserGuide/latest-Table/API/Programming-Cpp-Native-API_apache.md @@ -210,11 +210,13 @@ session = (new TableSessionBuilder()) ->build(); ``` +`host()` also accepts an unbracketed IPv6 address; `rpcPort()` still sets the port separately. + #### 3.2.2 Configurable Parameter List | **Parameter Name** | **Description** | **Default Value** | | :---: | :---: | :---: | -| host | Set the connected node IP | "127.0.0.1" ("localhost") | +| host | IP address of the node to connect to; supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname. Omit brackets for IPv6. IPv6 is supported from V2.0.12. | "127.0.0.1" ("localhost") | | rpcPort | Set the connected node port | 6667 | | username | Set the connection username | "root" | | password | Set the connection password | "root" | @@ -451,4 +453,3 @@ Failed to delete cached file C:\Users\Administrator\.m2\repository\.cache\downlo Possible fixes: - Try to delete the ".m2\repository\\.cache\" directory and try again. - Add "\true\" configuration to the download-maven-plugin maven phase that complains this error. - diff --git a/src/UserGuide/latest-Table/API/Programming-JDBC_apache.md b/src/UserGuide/latest-Table/API/Programming-JDBC_apache.md index 067b2598e..7b6f13042 100644 --- a/src/UserGuide/latest-Table/API/Programming-JDBC_apache.md +++ b/src/UserGuide/latest-Table/API/Programming-JDBC_apache.md @@ -187,3 +187,12 @@ public class TableModelJDBCExample { } } ``` + +```java +// IPv6 + Table model +String url = "jdbc:iotdb://[DN_IPV6_ADDRESS]:6667?sql_dialect=table"; +// IPv6 + Table model + SSL +String sslUrl = "jdbc:iotdb://[DN_IPV6_ADDRESS]:6667?sql_dialect=table&use_ssl=true"; +``` + +Starting with V2.0.12, table-model JDBC URLs also support `[ipv6]:port`. Replace `DN_IPV6_ADDRESS` with the DataNode’s actual reachable address. For SSL over IPv6, the server certificate SAN uses the unbracketed IPv6 address without a port. Retain the existing table-model URL examples. diff --git a/src/UserGuide/latest-Table/API/Programming-Java-Native-API_apache.md b/src/UserGuide/latest-Table/API/Programming-Java-Native-API_apache.md index ec07f4422..50cfd6be3 100644 --- a/src/UserGuide/latest-Table/API/Programming-Java-Native-API_apache.md +++ b/src/UserGuide/latest-Table/API/Programming-Java-Native-API_apache.md @@ -151,7 +151,7 @@ Since V2.0.11, `TableSessionBuilder` supports configuring the RPC compression me | **Parameter** | **Description** | **Default Value** | |-----------------------------------------------------| ------------------------------------------------------------ | ------------------------------------------------- | -| nodeUrls(List\ nodeUrls) | Sets the list of IoTDB cluster node URLs. | `Collections.singletonList("``localhost:6667``")` | +| nodeUrls(List\ nodeUrls) | Sets the IoTDB cluster node URL list; IPv6 endpoints use `[ipv6]:port`, for example `[DN_IPV6_ADDRESS]:6667`. IPv6 is supported from V2.0.12. | `Collections.singletonList("``localhost:6667``")` | | username(String username) | Sets the username for the connection. | `"root"` | | password(String password) | Sets the password for the connection. | `"TimechoDB@2021"` (the default password is `root` before V2.0.6.x) | | database(String database) | Sets the target database name. | `null` | @@ -182,6 +182,8 @@ Since V2.0.11, `TableSessionBuilder` supports configuring the RPC compression me | withDateEncoding(TSEncoding tsEncoding) | Sets the encoding for DATE values. | `TSEncoding.TS_2DIFF` | | connectionTimeoutInMs(int connectionTimeoutInMs) | Sets the connection timeout in milliseconds. | `0` (no timeout) | +Starting with V2.0.12, table-model `nodeUrls` also supports IPv6 endpoints. `DN_IPV6_ADDRESS` in the table is a DataNode address placeholder; replace it with an actual reachable address. Existing defaults remain unchanged. When configuring `TableSessionBuilder` with separate `host`/`rpcPort` settings, use an unbracketed IPv6 host; only node URL strings use brackets. + #### 3.2.3 Sample Code ```Java @@ -520,7 +522,7 @@ The `TableSessionPoolBuilder` class is a builder for configuring and creating `I | **Parameter** | **Description** | **Default Value** | |---------------------------------------------------------------| ------------------------------------------------------------ | --------------------------------------------- | -| nodeUrls(List\ nodeUrls) | Sets the list of IoTDB cluster node URLs. | `Collections.singletonList("localhost:6667")` | +| nodeUrls(List\ nodeUrls) | Sets the IoTDB cluster node URL list; IPv6 endpoints use `[ipv6]:port`, for example `[DN_IPV6_ADDRESS]:6667`. IPv6 is supported from V2.0.12. | `Collections.singletonList("localhost:6667")` | | maxSize(int maxSize) | Sets the maximum size of the session pool, i.e., the maximum number of sessions allowed in the pool. | `5` | | user(String user) | Sets the username for the connection. | `"root"` | | password(String password) | Sets the password for the connection. | `"root"` | @@ -945,3 +947,5 @@ public class TableModelSessionPoolExample { } } ``` + +To connect to IPv6 nodes in the Chapter 5 example, `LOCAL_URL` can use `[ipv6]:port`; retain the existing address and initialization code. diff --git a/src/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md b/src/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md index fdf0a6c20..b9cabd903 100644 --- a/src/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md +++ b/src/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md @@ -132,7 +132,7 @@ def close(self): | **Parameter** | **Description** | **Type** | **Default Value** | | ------------------ | ------------------------------------- | -------- | ------------------------- | -| node_urls | List of database node URLs. | `list` | `["localhost:6667"]` | +| node_urls | List of database connection node URLs; IPv6 endpoints use `[ipv6]:port`, for example `[DN_IPV6_ADDRESS]:6667`. IPv6 is supported from V2.0.12. | `list` | `["localhost:6667"]` | | username | Username for the database connection. | `str` | `"root"` | | password | Password for the database connection. | `str` | `"root"` | | database | Target database to connect to. | `str` | `None` | @@ -140,6 +140,8 @@ def close(self): | time_zone | Default session time zone. | `str` | `Session.DEFAULT_ZONE_ID` | | enable_compression | Enable data compression. | `bool` | `False` | +Starting with V2.0.12, table-model `node_urls` supports IPv6 endpoints. `DN_IPV6_ADDRESS` in the table is a DataNode address placeholder; retain existing defaults and examples. When `TableSession`/`TableSessionPool` take host and port separately, use an unbracketed IPv6 host; node URL lists use `[ipv6]:port`. + #### Sample Code ```Python @@ -231,7 +233,7 @@ def close(self): | **Paramater** | **Description** | **Type** | **Default Value** | | ------------------ | ------------------------------------------------------------ | -------- | -------------------------- | -| node_urls | List of IoTDB cluster node URLs. | `list` | None | +| node_urls | List of database connection node URLs; IPv6 endpoints use `[ipv6]:port`, for example `[DN_IPV6_ADDRESS]:6667`. IPv6 is supported from V2.0.12. | `list` | None | | max_pool_size | Maximum size of the session pool, i.e., the maximum number of sessions allowed in the pool. | `int` | `5` | | username | Username for the connection. | `str` | `Session.DEFAULT_USER` | | password | Password for the connection. | `str` | `Session.DEFAULT_PASSWORD` | @@ -395,6 +397,8 @@ if __name__ == "__main__": df = get_data() ``` +Use an unbracketed IPv6 host for SSL connections. The CA specified by `ca_certs` must validate the server certificate, and the server certificate SAN must contain the actual unbracketed IPv6 `IP Address` used by the client. TLS server identity verification fails if the SAN does not contain that address. + ## 4. Sample Code **Session** Example: You can find the full example code at [Session Example](https://github.com/apache/iotdb/blob/master/iotdb-client/client-py/table_model_session_example.py). @@ -570,4 +574,3 @@ delete_data() session_pool.close() print("example is finished!") ``` - diff --git a/src/UserGuide/latest-Table/Deployment-and-Maintenance/AINode_Deployment_apache.md b/src/UserGuide/latest-Table/Deployment-and-Maintenance/AINode_Deployment_apache.md index 4b1fc637c..f283760a1 100644 --- a/src/UserGuide/latest-Table/Deployment-and-Maintenance/AINode_Deployment_apache.md +++ b/src/UserGuide/latest-Table/Deployment-and-Maintenance/AINode_Deployment_apache.md @@ -113,18 +113,26 @@ AINode supports modifying some necessary parameters. You can find the following | **Name** | **Description** | **Type** | **Default Value** | | ------------------------------ | ------------------------------------------------------------ | -------- | ------------------ | | cluster_name | Identifier of the cluster AINode joins | string | defaultCluster | -| ain_seed_config_node | Address of the ConfigNode registered when AINode starts | String | 127.0.0.1:10710 | -| ain_cluster_ingress_address | RPC address of the DataNode for AINode to pull data | String | 127.0.0.1 | +| ain_seed_config_node | ConfigNode endpoint used for AINode registration at startup. Supports `ipv4:port`, `hostname:port`, or `[ipv6]:port`, for example `[CN_IPV6_ADDRESS]:10710`. IPv6 is supported from V2.0.12. | String | 127.0.0.1:10710 | +| ain_cluster_ingress_address | DataNode RPC address from which AINode pulls data. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | String | 127.0.0.1 | | ain_cluster_ingress_port | RPC port of the DataNode for AINode to pull data | Integer | 6667 | | ain_cluster_ingress_username | Client username for AINode to pull data from the DataNode | String | root | | ain_cluster_ingress_password | Client password for AINode to pull data from the DataNode | String | root | | ain_cluster_ingress_time_zone | Client time zone for AINode to pull data from the DataNode | String | UTC+8 | -| ain_inference_rpc_address | Address for AINode to provide services and communication (internal interface) | String | 127.0.0.1 | +| ain_inference_rpc_address | Address used for AINode services and internal communication. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | String | 127.0.0.1 | | ain_inference_rpc_port | Port for AINode to provide services and communication | String | 10810 | | ain_system_dir | Metadata storage path for AINode (relative path starts from OS-dependent directory; absolute path is recommended) | String | data/AINode/system | | ain_models_dir | Path to store model files for AINode (relative path starts from OS-dependent directory; absolute path is recommended) | String | data/AINode/models | | ain_thrift_compression_enabled | Whether to enable Thrift compression for AINode (0=disabled, 1=enabled) | Boolean | 0 | +```properties +ain_seed_config_node=[CN_IPV6_ADDRESS]:10710 +ain_cluster_ingress_address=DN_IPV6_ADDRESS +ain_inference_rpc_address=AINODE_IPV6_ADDRESS +``` + +`ain_seed_config_node` includes both an address and port and uses `[ipv6]:port` for IPv6. `ain_cluster_ingress_address` and `ain_inference_rpc_address` contain addresses only and use unbracketed IPv6. Replace `CN_IPV6_ADDRESS`, `DN_IPV6_ADDRESS`, and `AINODE_IPV6_ADDRESS` with the actual reachable addresses of the ConfigNode, DataNode, and AINode. After startup, verify that AINode is registered with ConfigNode and can access DataNode. + ### 3.3 Importing Weight Files > Offline environment only (Online environments can skip this step) diff --git a/src/UserGuide/latest-Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md b/src/UserGuide/latest-Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md index 0ee6fc154..c35ecd881 100644 --- a/src/UserGuide/latest-Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md +++ b/src/UserGuide/latest-Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md @@ -41,6 +41,7 @@ Use the hostname for `cn_internal_address` and `dn_internal_address` in IoTDB co 3. **Unmodifiable Parameters**: Some parameters cannot be changed after the first startup. Refer to the [Parameter Configuration](#22-parameters-configuration) section. +4. **Unmodifiable Parameters**: Some parameters cannot be changed after the first startup. Refer to the [Parameter Configuration](#22-parameters-configuration) section. 4. **Installation Path**: Ensure the installation path contains no spaces or non-ASCII characters to prevent runtime issues. 5. **User Permissions**: Choose one of the following permissions during installation and deployment: @@ -51,6 +52,8 @@ Use the hostname for `cn_internal_address` and `dn_internal_address` in IoTDB co 6. **Health Check Tool**: Before installation, the health check tool can help inspect the operating environment of IoTDB nodes and obtain detailed inspection results. The usage method of the IoTDB health check tool can be found in:[Health Check Tool](../Tools-System/Health-Check-Tool.md). +For dual-stack or IPv6-only deployment, verify before startup that IPv6 is enabled in the operating system and the configured addresses are assigned to the appropriate network interfaces and can be bound by the services; that IPv6 routing between ConfigNodes, DataNodes, and AINodes is reachable and the required RPC, consensus, and client ports are allowed through the firewall; and that DNS or `/etc/hosts` resolution is consistent across nodes when hostnames are used. `0.0.0.0` and `::` are wildcard listening addresses only and cannot be used for node registration, node discovery, client redirection, or other remote connection targets. + ## 2. Preparation 1. Prepare the IoTDB database installation package:：apache-iotdb-{version}-all-bin.zip（Please refer to the installation package for details：[IoTDB-Package](../Deployment-and-Maintenance/IoTDB-Package_apache.md)） @@ -154,23 +157,33 @@ Set the following parameters in `./conf/iotdb-system.properties`. Refer to `./co | **Parameter** | **Description** | **Default** | **Recommended** | **11.101.17.224** | **11.101.17.225** | **11.101.17.226** | **Notes** | | :------------------ | :----------------------------------------------------------- | :-------------- | :----------------------------------------------------------- | :---------------- | :---------------- | :---------------- | :--------------------------------------------------------- | -| cn_internal_address | Address used for internal communication within the cluster | 127.0.0.1 | Server's IPv4 address or hostname. Use hostname to avoid issues when the IP changes. | iotdb-1 | iotdb-2 | iotdb-3 | This parameter cannot be modified after the first startup. | +| cn_internal_address | Address used for ConfigNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | iotdb-1 | iotdb-2 | iotdb-3 | This parameter cannot be modified after the first startup. | | cn_internal_port | Port used for internal communication within the cluster | 10710 | 10710 | 10710 | 10710 | 10710 | This parameter cannot be modified after the first startup. | | cn_consensus_port | Port used for consensus protocol communication among ConfigNode replicas | 10720 | 10720 | 10720 | 10720 | 10720 | This parameter cannot be modified after the first startup. | -| cn_seed_config_node | Address of the ConfigNode for registering and joining the cluster. (e.g.,`cn_internal_address:cn_internal_port`) | 127.0.0.1:10710 | Address and port of the seed ConfigNode (e.g., `cn_internal_address:cn_internal_port`) | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | This parameter cannot be modified after the first startup. | +| cn_seed_config_node | ConfigNode endpoint used for node registration and joining the cluster, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | Address and port of the seed ConfigNode (e.g., `cn_internal_address:cn_internal_port`) | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | This parameter cannot be modified after the first startup. | **DataNode Parameters**: | **Parameter** | **Description** | **Default** | **Recommended** | **11.101.17.224** | **11.101.17.225** | **11.101.17.226** | **Notes** | | :------------------------------ | :----------------------------------------------------------- |:----------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| :---------------- | :---------------- | :---------------- | :--------------------------------------------------------- | -| dn_rpc_address | Address for the client RPC service | 127.0.0.1 | By default, the local machine can directly access it. For non-local access, please modify this configuration item to the IPv4 address or hostname of the server where it is located. It is recommended to use the IPv4 address of the server where it is located. | iotdb-1 | iotdb-2 | iotdb-3 | Effective after restarting the service. | +| dn_rpc_address | Client RPC listening address. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | Local access only by default; for remote access, specify the server’s routable IPv4 address, unbracketed IPv6 address, or hostname | iotdb-1 | iotdb-2 | iotdb-3 | Effective after restarting the service. | | dn_rpc_port | Port for the client RPC service | 6667 | 6667 | 6667 | 6667 | 6667 | Effective after restarting the service. | -| dn_internal_address | Address used for internal communication within the cluster | 127.0.0.1 | Server's IPv4 address or hostname. Use hostname to avoid issues when the IP changes. | iotdb-1 | iotdb-2 | iotdb-3 | This parameter cannot be modified after the first startup. | +| dn_internal_address | Address used for DataNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | iotdb-1 | iotdb-2 | iotdb-3 | This parameter cannot be modified after the first startup. | | dn_internal_port | Port used for internal communication within the cluster | 10730 | 10730 | 10730 | 10730 | 10730 | This parameter cannot be modified after the first startup. | | dn_mpp_data_exchange_port | Port used for receiving data streams | 10740 | 10740 | 10740 | 10740 | 10740 | This parameter cannot be modified after the first startup. | | dn_data_region_consensus_port | Port used for data replica consensus protocol communication | 10750 | 10750 | 10750 | 10750 | 10750 | This parameter cannot be modified after the first startup. | | dn_schema_region_consensus_port | Port used for metadata replica consensus protocol communication | 10760 | 10760 | 10760 | 10760 | 10760 | This parameter cannot be modified after the first startup. | -| dn_seed_config_node | Address of the ConfigNode for registering and joining the cluster.(e.g.,`cn_internal_address:cn_internal_port`) | 127.0.0.1:10710 | Address of the first ConfigNode | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | This parameter cannot be modified after the first startup. | +| dn_seed_config_node | ConfigNode endpoint used for node registration and joining the cluster, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | Address of the first ConfigNode | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | This parameter cannot be modified after the first startup. | + +Replace `CN_IPV6_ADDRESS` and `DN_IPV6_ADDRESS` with the nodes’ actual reachable IPv6 addresses before deployment. + +```properties +cn_internal_address=CN_IPV6_ADDRESS +cn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +dn_internal_address=DN_IPV6_ADDRESS +dn_rpc_address=DN_IPV6_ADDRESS +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +``` **Note:** Ensure files are saved after editing. Tools like VSCode Remote do not save changes automatically. @@ -195,6 +208,8 @@ Set the following parameters in `./conf/iotdb-system.properties`. Refer to `./co If the startup fails, refer to the [Common Issues](#5-common-issues) section below for troubleshooting. +After startup, run `show cluster` in the CLI to verify that ConfigNodes and DataNodes are registered. In an IPv6-only environment, node address fields should display the configured unbracketed IPv6 addresses; addresses with ports in logs or errors should use `[ipv6]:port`. If `::` is returned as a node address, configure an actual routable IPv6 address for the node’s published address. + ### 3.5 Start DataNode Instances On each server, navigate to the `sbin` directory and start the DataNode: @@ -212,6 +227,13 @@ On each server, navigate to the `sbin` directory and start the DataNode: .\windows\start-datanode.bat ``` +When passing an IPv6 address separately with `-h`, omit brackets and specify the port with `-p`. For example: + +```shell +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' -sql_dialect table +``` + + ### 3.6 Start CLI Enter the IoTDB CLI. diff --git a/src/UserGuide/latest-Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md b/src/UserGuide/latest-Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md index db1dbf9bd..66931ce07 100644 --- a/src/UserGuide/latest-Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md +++ b/src/UserGuide/latest-Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md @@ -128,23 +128,35 @@ Set the following parameters in `conf/iotdb-system.properties`. Refer to `conf/i | **Parameter** | **Description** | **Default** | **Recommended** | **Notes** | | :------------------ | :----------------------------------------------------------- | :-------------- | :----------------------------------------------------------- | :--------------------------------------------------------- | -| cn_internal_address | Address used for internal communication within the cluster | 127.0.0.1 | Server's IPv4 address or hostname. Use hostname to avoid issues when the IP changes. | This parameter cannot be modified after the first startup. | +| cn_internal_address | Address used for ConfigNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | This parameter cannot be modified after the first startup. | | cn_internal_port | Port used for internal communication within the cluster | 10710 | 10710 | This parameter cannot be modified after the first startup. | | cn_consensus_port | Port used for consensus protocol communication among ConfigNode replicas | 10720 | 10720 | This parameter cannot be modified after the first startup. | -| cn_seed_config_node | Address of the ConfigNode for registering and joining the cluster. (e.g.,`cn_internal_address:cn_internal_port`) | 127.0.0.1:10710 | Use `cn_internal_address:cn_internal_port` | This parameter cannot be modified after the first startup. | +| cn_seed_config_node | ConfigNode endpoint used for node registration, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | Use `cn_internal_address:cn_internal_port` | This parameter cannot be modified after the first startup. | **DataNode Parameters**: | **Parameter** | **Description** | **Default** | **Recommended** | **Notes** | | :------------------------------ | :----------------------------------------------------------- | :-------------- |:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| :--------------------------------------------------------- | -| dn_rpc_address | Address for the client RPC service | 127.0.0.1 | By default, the local machine can directly access it. For non-local access, please modify this configuration item to the IPv4 address or hostname of the server where it is located. It is recommended to use the IPv4 address of the server where it is located. | Effective after restarting the service. | +| dn_rpc_address | Client RPC listening address. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | Local access only by default; for remote access, specify the server’s routable IPv4 address, unbracketed IPv6 address, or hostname | Effective after restarting the service. | | dn_rpc_port | Port for the client RPC service | 6667 | 6667 | Effective after restarting the service. | -| dn_internal_address | Address used for internal communication within the cluster | 127.0.0.1 | Server's IPv4 address or hostname. Use hostname to avoid issues when the IP changes. | This parameter cannot be modified after the first startup. | +| dn_internal_address | Address used for DataNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | This parameter cannot be modified after the first startup. | | dn_internal_port | Port used for internal communication within the cluster | 10730 | 10730 | This parameter cannot be modified after the first startup. | | dn_mpp_data_exchange_port | Port used for receiving data streams | 10740 | 10740 | This parameter cannot be modified after the first startup. | | dn_data_region_consensus_port | Port used for data replica consensus protocol communication | 10750 | 10750 | This parameter cannot be modified after the first startup. | | dn_schema_region_consensus_port | Port used for metadata replica consensus protocol communication | 10760 | 10760 | This parameter cannot be modified after the first startup. | -| dn_seed_config_node | Address of the ConfigNode for registering and joining the cluster. (e.g.,`cn_internal_address:cn_internal_port`) | 127.0.0.1:10710 | Use `cn_internal_address:cn_internal_port` | This parameter cannot be modified after the first startup. | +| dn_seed_config_node | ConfigNode endpoint used for node registration, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | Use `cn_internal_address:cn_internal_port` | This parameter cannot be modified after the first startup. | + +Standalone instances accessed only from the local host can use the IPv6 loopback address: + +```properties +cn_internal_address=::1 +cn_seed_config_node=[::1]:10710 +dn_internal_address=::1 +dn_rpc_address=::1 +dn_seed_config_node=[::1]:10710 +``` + +`::1` is the IPv6 loopback address and is for local access or testing only. For access from other hosts, use the local host’s actual routable IPv6 address. `::` listens on all IPv6 interfaces and cannot be used as a remote target, node discovery result, or client redirection address. ### 2.4 Start and Stop the Edge Edition diff --git a/src/UserGuide/latest-Table/FAQ/Frequently-asked-questions.md b/src/UserGuide/latest-Table/FAQ/Frequently-asked-questions.md index 8b3bd70db..d42693677 100644 --- a/src/UserGuide/latest-Table/FAQ/Frequently-asked-questions.md +++ b/src/UserGuide/latest-Table/FAQ/Frequently-asked-questions.md @@ -284,3 +284,33 @@ Notes: #### How to decrease the memory usage of ConfigNode/DataNode? - Adjust the ON_HEAP_MEMORY、OFF_HEAP_MEMORY options in conf/confignode-env.sh and conf/datanode-env.sh. + +## 3. IPv6 Connection FAQ + +### 3.1 Why is `[::1]:6667` valid while `::1:6667` should not be used as an endpoint? + +Starting with V2.0.12, IoTDB supports IPv6 connections. IPv6 addresses contain multiple colons. Address and port combinations must use `[ipv6]:port` to distinguish them. The address and port in JDBC URLs, Session node URLs, and Pipe `node-urls` must use `[ipv6]:port`. + +### 3.2 Why do address parameters use unbracketed IPv6 while JDBC and Pipe use `[ipv6]:port`? + +Parameters such as `cn_internal_address`, `dn_internal_address`, and `dn_rpc_address` contain addresses only and use unbracketed IPv6. JDBC URLs, seed endpoints, Session node URLs, and Pipe `node-urls` include both addresses and ports and use `[ipv6]:port`. + +### 3.3 Why does listening on `::` succeed while clients still cannot connect? + +`::` listens on all IPv6 interfaces and is not a routable remote address. Node registration, node discovery, client redirection, Pipe destinations, and Prometheus targets must use actual reachable IPv6 addresses. + +### 3.4 How do I resolve hostname or IP verification failures in IPv6 TLS connections? + +Check that the server certificate SAN contains the actual unbracketed IPv6 `IP Address` used by the client, without brackets or a port. Also verify that the client TrustStore contains the CA that issued the certificate. + +### 3.5 How do I troubleshoot connection failures in an IPv6-only environment? + +Check, in order, that IPv6 is enabled in the operating system, addresses are bound, inter-node routes and ports are reachable, firewalls allow traffic, DNS or `/etc/hosts` resolution is consistent, and the client runtime and underlying socket support IPv6. + +### 3.6 What if IPv4 works but IPv6 connections fail in a dual-stack environment? + +First connect directly with the actual IPv6 address and port using the required syntax, and verify that the destination service is bound to an IPv6 address and routing and firewall rules allow access to the port. Then check that DNS AAAA records or IPv6 mappings in `/etc/hosts` point to the destination. Verify IPv4 and IPv6 paths separately; successful IPv4 connections do not confirm IPv6 connectivity. Do not publish `::` as a node address. + +### 3.7 How do I resolve IPv6 endpoint parsing errors in Pipe? + +Check that every IPv6 endpoint uses `[ipv6]:port`, that multiple endpoints are separated by commas, and that `::` or `0.0.0.0` has not been used as a destination. For SSL Pipe, also check the TrustStore, KeyStore, and destination certificate SAN. diff --git a/src/UserGuide/latest-Table/Reference/System-Config-Manual_apache.md b/src/UserGuide/latest-Table/Reference/System-Config-Manual_apache.md index 78ccdc0b0..0dcc02938 100644 --- a/src/UserGuide/latest-Table/Reference/System-Config-Manual_apache.md +++ b/src/UserGuide/latest-Table/Reference/System-Config-Manual_apache.md @@ -144,11 +144,15 @@ The `iotdb-system.properties` file contains various configurations for managing ### 4.2 Seed ConfigNode +> Address-only parameters use unbracketed IPv6 addresses; endpoints containing both an address and a port use `[ipv6]:port`. + +`CN_IPV6_ADDRESS` below marks the ConfigNode IPv6 address field. Use an actual resolvable, routable address. Existing IPv4/hostname examples and default values remain unchanged. + - cn_seed_config_node | Name | cn_seed_config_node | | ----------- | ------------------------------------------------------------ | -| Description | Address of the seed ConfigNode for Confignode to join the cluster. | +| Description | Endpoint of the target ConfigNode through which a ConfigNode joins the cluster; a SeedConfigNode is recommended. Supports `ipv4:port`, `hostname:port`, or `[ipv6]:port`, for example `[CN_IPV6_ADDRESS]:10710`. Previously named cn_target_config_node_list in V1.2.2 and earlier. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1:10710 | | Effective | Modify before the first startup. | @@ -157,7 +161,7 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | dn_seed_config_node | | ----------- | ------------------------------------------------------------ | -| Description | Address of the seed ConfigNode for Datanode to join the cluster. | +| Description | Endpoint of the ConfigNode through which a DataNode joins the cluster at startup; a SeedConfigNode is recommended. Supports `ipv4:port`, `hostname:port`, or `[ipv6]:port`, for example `[CN_IPV6_ADDRESS]:10710`. Previously named dn_target_config_node_list in V1.2.2 and earlier. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1:10710 | | Effective | Modify before the first startup. | @@ -168,7 +172,7 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | cn_internal_address | | ----------- | ---------------------------------------------- | -| Description | Internal address for ConfigNode communication. | +| Description | ConfigNode internal cluster communication address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port, for example `192.168.1.10`, `CN_IPV6_ADDRESS`, or `iotdb-cn-1`. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1 | | Effective | Modify before the first startup. | @@ -195,7 +199,7 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | dn_rpc_address | | ----------- |---------------------------------| -| Description | Address for client RPC service. | +| Description | Listening address for the client RPC service. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port, for example `192.168.1.20`, `DN_IPV6_ADDRESS`, or `iotdb-dn-1`. `::` listens on all IPv6 interfaces, but cannot be returned as a remote address for client redirection or node discovery. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1 | | Effective | Restart required. | @@ -213,11 +217,15 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | dn_internal_address | | ----------- | -------------------------------------------- | -| Description | Internal address for DataNode communication. | +| Description | DataNode internal communication address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port, for example `192.168.1.20`, `DN_IPV6_ADDRESS`, or `iotdb-dn-1`. IPv6 is supported from V2.0.12. | | Type | string | | Default | 127.0.0.1 | | Effective | Modify before the first startup. | +> Use unbracketed IPv6 for address-only parameters, such as `DN_IPV6_ADDRESS`; use `[ipv6]:port` for endpoints containing both an address and port, such as `[DN_IPV6_ADDRESS]:10730`. `0.0.0.0` and `::` are wildcard listening addresses only; do not use them as remote connection targets. + +`DN_IPV6_ADDRESS` below marks the DataNode IPv6 address field. Replace it with an address bound to and reachable on the corresponding node. + - dn_internal_port | Name | dn_internal_port | @@ -523,6 +531,8 @@ The `iotdb-system.properties` file contains various configurations for managing ### 4.7 SSL Configuration +> IPv6 uses the existing SSL/TLS switches, protocols, KeyStore, and TrustStore settings. For TLS server identity verification over IPv6, the server certificate SAN must contain the actual IPv6 address used by the client as an unbracketed `IP Address`, without a port. For example, when connecting to `[DN_IPV6_ADDRESS]:6667`, the SAN must contain `DN_IPV6_ADDRESS`. + - enable_thrift_ssl | Name | enable_thrift_ssl | diff --git a/src/UserGuide/latest-Table/Tools-System/CLI_apache.md b/src/UserGuide/latest-Table/Tools-System/CLI_apache.md index f2128b7ef..bdf7e95ec 100644 --- a/src/UserGuide/latest-Table/Tools-System/CLI_apache.md +++ b/src/UserGuide/latest-Table/Tools-System/CLI_apache.md @@ -55,7 +55,7 @@ Shell> sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -sql_dia | **Parameter** | **Type** | **Required** | **Description** | **Example** | | -------------------------- | -------- | ------------ |-----------------------------------------------------------------------------------| ------------------- | -| -h `` | string | No | The IP address of the IoTDB server. (Default: 127.0.0.1) | -h 127.0.0.1 | +| -h `` | string | No | IoTDB server IPv4 address, unbracketed IPv6 address, or hostname. IPv6 is supported from V2.0.12; omit brackets. | -h 127.0.0.1 | | -p `` | int | No | The RPC port of the IoTDB server. (Default: 6667) | -p 6667 | | -u `` | string | No | The username to connect to the IoTDB server. (Default: root) | -u root | | -pw `` | string | No | The password to connect to the IoTDB server. (Default: root) | -pw root | @@ -73,6 +73,15 @@ The figure below indicates a successful startup: ![](/img/Cli-01.png) +Starting with V2.0.12, pass an IPv6 address to `-h` without brackets and specify the port separately with `-p`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with an actual reachable IPv6 address before running the command. Retain the existing IPv4 startup examples. For example: + +```shell +# Linux/macOS +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' -sql_dialect table + +# Windows (V2.0.4.x and later) +sbin\windows\start-cli.bat -h DN_IPV6_ADDRESS -p 6667 -u root -pw "" -sql_dialect table +``` ## 2. Example Commands diff --git a/src/UserGuide/latest-Table/Tools-System/Data-Export-Tool_apache.md b/src/UserGuide/latest-Table/Tools-System/Data-Export-Tool_apache.md index 410ae5f86..aa4247976 100644 --- a/src/UserGuide/latest-Table/Tools-System/Data-Export-Tool_apache.md +++ b/src/UserGuide/latest-Table/Tools-System/Data-Export-Tool_apache.md @@ -38,7 +38,7 @@ IoTDB supports two methods for data export: | Short | Full Parameter | Description | Required | Default | |----------------|--------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------- |----------------------------------------------| | `-ft` | `--file_type` | Export file type: `csv`, `sql`, `tsfile`. | ​**Yes** | - | -| `-h` | `--host` | Hostname of the IoTDB server. | No | `127.0.0.1` | +| `-h` | `--host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | `127.0.0.1` | | `-p` | `--port` | Port number of the IoTDB server. | No | `6667` | | `-u` | `--username` | Username for authentication. | No | `root` | | `-pw` | `--password` | Password for authentication. Supported for hidden input since V2.0.10 | No | `root` | @@ -56,6 +56,8 @@ IoTDB supports two methods for data export: | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with the actual reachable unbracketed IPv6 address before running the command. Do not pass brackets to `-h`. For SSL, retain the existing `-usessl`, `-ts`, and `-tpw` parameters; the server certificate SAN must contain the actual unbracketed IPv6 address accessed by the client. + ### 2.2 CSV Format #### 2.2.1 Command diff --git a/src/UserGuide/latest-Table/Tools-System/Data-Import-Tool_apache.md b/src/UserGuide/latest-Table/Tools-System/Data-Import-Tool_apache.md index 786074b67..a883bd53e 100644 --- a/src/UserGuide/latest-Table/Tools-System/Data-Import-Tool_apache.md +++ b/src/UserGuide/latest-Table/Tools-System/Data-Import-Tool_apache.md @@ -44,7 +44,7 @@ IoTDB supports three methods for data import: | Short | Full Parameter | Description | Required | Default | |----------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------- |---------------------------------------------| | `-ft` | `--file_type` | File type: `csv`, `sql`, `tsfile`. | ​**Yes** | - | -| `-h` | `--host` | IoTDB server hostname. | No | `127.0.0.1` | +| `-h` | `--host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | `127.0.0.1` | | `-p` | `--port` | IoTDB server port. | No | `6667` | | `-u` | `--username` | Username. | No | `root` | | `-pw` | `--password` | Password. Supported for hidden input since V2.0.10 | No | `root` | @@ -58,6 +58,7 @@ IoTDB supports three methods for data import: | `-usessl` | `--use_ssl` | Use SSL protocol. Supported since V2.0.10 | No | - | | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with the actual reachable unbracketed IPv6 address before running the command. Do not pass brackets to `-h`. For SSL, retain the existing `-usessl`, `-ts`, and `-tpw` parameters; the server certificate SAN must contain the actual unbracketed IPv6 address accessed by the client. ### 2.2 CSV Format diff --git a/src/UserGuide/latest-Table/Tools-System/Monitor-Tool_apache.md b/src/UserGuide/latest-Table/Tools-System/Monitor-Tool_apache.md index db25ef205..3eecdc0ad 100644 --- a/src/UserGuide/latest-Table/Tools-System/Monitor-Tool_apache.md +++ b/src/UserGuide/latest-Table/Tools-System/Monitor-Tool_apache.md @@ -87,6 +87,7 @@ follow_redirects: true static_configs: - targets: - localhost:9091 + - '[IPV6_ADDRESS]:9091' ``` For more details, refer to the following documents: @@ -95,3 +96,10 @@ For more details, refer to the following documents: - [Prometheus Configuration for Pulling Metrics from HTTP Interface](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) - [Grafana Installation and Usage Documentation](https://grafana.com/docs/grafana/latest/getting-started/getting-started/) - [Grafana Querying Data from Prometheus and Plotting Documentation](https://prometheus.io/docs/visualization/grafana/#grafana-support-for-prometheus) +Prometheus targets include both an IPv6 address and a port and must use `[ipv6]:port`. Even if the service listens on `::`, use an actual routable IPv6 address for the target, never `[::]:9091`. + +Starting with V2.0.12, the metrics endpoint supports access over IPv6. Use brackets to distinguish the address from the port in an IPv6 metrics URL. Replace the placeholder below with the actual reachable IPv6 address: + +```shell +curl 'http://[IPV6_ADDRESS]:9091/metrics' +``` diff --git a/src/UserGuide/latest-Table/Tools-System/Schema-Export-Tool_apache.md b/src/UserGuide/latest-Table/Tools-System/Schema-Export-Tool_apache.md index f69597a55..5909dc05f 100644 --- a/src/UserGuide/latest-Table/Tools-System/Schema-Export-Tool_apache.md +++ b/src/UserGuide/latest-Table/Tools-System/Schema-Export-Tool_apache.md @@ -31,7 +31,7 @@ The schema export tool `export-schema.sh/bat` is located in the `tools` director | **Short Param** | **Full Param** | **Description** | Required | Default | |-----------------|--------------------------|--------------------------------------------------------------------------| ------------------------------------- |---------------------------------------------| -| `-h` | `--host` | Hostname | No | 127.0.0.1 | +| `-h` | `--host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | 127.0.0.1 | | `-p` | `--port` | Port number | No | 6667 | | `-u` | `--username` | Username | No | root | | `-pw` | `--password` | Password. Supported for hidden input since V2.0.10 | No | root | @@ -48,6 +48,8 @@ The schema export tool `export-schema.sh/bat` is located in the `tools` director | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with the actual reachable unbracketed IPv6 address before running the command. Do not pass brackets to `-h`. For SSL, retain the existing `-usessl`, `-ts`, and `-tpw` parameters; verify that the certificate SAN contains the actual IPv6 address accessed by the client. + ### 2.2 Command ```Bash @@ -109,3 +111,5 @@ CREATE TABLE table2( arrival_time TIMESTAMP FIELD ); ``` + +Starting with V2.0.12, `-h` accepts an actual unbracketed IPv6 address and `-p` still takes the port separately. Parameters such as `-sql_dialect`, `-db`, `-s`, `-t`, and `-path` do not need to change for IPv6. diff --git a/src/UserGuide/latest-Table/Tools-System/Schema-Import-Tool_apache.md b/src/UserGuide/latest-Table/Tools-System/Schema-Import-Tool_apache.md index f0f18b632..3ea27f14d 100644 --- a/src/UserGuide/latest-Table/Tools-System/Schema-Import-Tool_apache.md +++ b/src/UserGuide/latest-Table/Tools-System/Schema-Import-Tool_apache.md @@ -31,7 +31,7 @@ The schema import tool `import-schema.sh/bat` is located in `tools` directory. | **Short Param** | **Full Param** | **Description** | Required | Default | |-----------------|---------------------------|--------------------------------------------------------------------------| ---------- |-------------------------------------------| -| `-h` | `--host` | Hostname | No | 127.0.0.1 | +| `-h` | `--host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | 127.0.0.1 | | `-p` | `--port` | Port number | No | 6667 | | `-u` | `--username` | Username | No | root | | `-pw` | `--password` | Password. Supported for hidden input since V2.0.10 | No | root | @@ -46,6 +46,8 @@ The schema import tool `import-schema.sh/bat` is located in `tools` directory. | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with the actual reachable unbracketed IPv6 address before running the command. Do not pass brackets to `-h`. For SSL, retain the existing `-usessl`, `-ts`, and `-tpw` parameters; verify that the certificate SAN contains the actual IPv6 address accessed by the client. + ### 2.2 Command ```Bash @@ -164,3 +166,5 @@ IoTDB:database2> desc table2 |arrival_time|TIMESTAMP| FIELD| +------------+---------+---------+ ``` + +Starting with V2.0.12, `-h` accepts an actual unbracketed IPv6 address and `-p` still takes the port separately. Parameters such as `-sql_dialect`, `-db`, `-s`, `-t`, and `-path` do not need to change for IPv6. diff --git a/src/UserGuide/latest-Table/User-Manual/Data-Sync_apache.md b/src/UserGuide/latest-Table/User-Manual/Data-Sync_apache.md index 2650b2779..4e10b43a3 100644 --- a/src/UserGuide/latest-Table/User-Manual/Data-Sync_apache.md +++ b/src/UserGuide/latest-Table/User-Manual/Data-Sync_apache.md @@ -343,6 +343,16 @@ WITH SINK ( ) ``` +```sql +create pipe A2B_IPV6 +with sink ( + 'sink'='iotdb-thrift-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667' +) +``` + +Starting with V2.0.12, Pipe supports IPv6 endpoints for connecting to the destination IoTDB. `node-urls` includes both an address and port and uses `[ipv6]:port` for IPv6; separate multiple endpoints with commas. `DN_IPV6_ADDRESS` and `DN_IPV6_ADDRESS_2` in the independent example above represent the actual reachable IPv6 addresses of two destination DataNodes. Replace them before use; retain the existing Pipe examples. + ### 3.2 Partial Data Synchronization This example demonstrates synchronizing data within a specific historical time range (from August 23, 2023, 8:00 to October 23, 2023, 8:00) to another IoTDB. The data pipeline is shown below: @@ -504,6 +514,18 @@ Where: - `ssl.trust-store-path`: The trust store certificate path required to connect to the target DataNode - `ssl.trust-store-pwd`: The trust store certificate password required to connect to the target DataNode +```sql +create pipe A2B_SSL_IPV6 +with sink ( + 'sink'='iotdb-thrift-ssl-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667', + 'ssl.trust-store-path'='pki/trusted', + 'ssl.trust-store-pwd'='' +) +``` + +For TLS server identity verification over IPv6, the server certificate SAN must contain the actual IPv6 address used by the client as an unbracketed `IP Address`, without a port. + ## Reference: Notes You can adjust the parameters for data synchronization by modifying the IoTDB configuration file (`iotdb-system.properties`), such as the directory for storing synchronized data. The complete configuration is as follows: @@ -598,7 +620,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **Parameter** | **Description** | Value Range | Required | Default Value | |:--------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| :----------------------------------------------------------- | :------- | :------------ | | sink | iotdb-thrift-sink or iotdb-thrift-async-sink | String: iotdb-thrift-sink or iotdb-thrift-async-sink | Yes | - | -| node-urls | URLs of the DataNode service ports on the target IoTDB. (please note that the synchronization task does not support forwarding to its own service). | String. Example：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | Yes | - | +| node-urls | Data service endpoints of multiple DataNodes on the destination IoTDB (synchronization tasks cannot forward to their own service). IPv6 uses `[ipv6]:port`; separate multiple endpoints with commas. IPv6 is supported from V2.0.12. | String. Examples: `'127.0.0.1:6667,127.0.0.1:6668'`, `'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | Yes | - | | user/username | Username for connecting to the target IoTDB. Must have appropriate permissions. | String | No | root | | password | Password for the username. | String | No | root | | batch.enable | Enables batch mode for log transmission to improve throughput and reduce IOPS. | Boolean: true, false | No | true | @@ -618,7 +640,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **Parameter** | **Description** | Value Range | Required | Default Value | |:-------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------|:---------| :------------ | | sink | iotdb-thrift-ssl-sink | String: iotdb-thrift-ssl-sink | Yes | - | -| node-urls | URLs of the DataNode service ports on the target IoTDB. (please note that the synchronization task does not support forwarding to its own service). | String. Example：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | Yes | - | +| node-urls | Data service endpoints of multiple DataNodes on the destination IoTDB (synchronization tasks cannot forward to their own service). IPv6 uses `[ipv6]:port`; separate multiple endpoints with commas; the destination certificate SAN must cover the actual connection address. IPv6 is supported from V2.0.12. | String. Examples: `'127.0.0.1:6667,127.0.0.1:6668'`, `'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | Yes | - | | user/username | Username for connecting to the target IoTDB. Must have appropriate permissions. | String | No | root | | password | Password for the username. | String | No | root | | batch.enable | Enables batch mode for log transmission to improve throughput and reduce IOPS. | Boolean: true, false | No | true | diff --git a/src/UserGuide/latest-Table/User-Manual/Load-Balance_apache.md b/src/UserGuide/latest-Table/User-Manual/Load-Balance_apache.md index b1b760005..343c8d267 100644 --- a/src/UserGuide/latest-Table/User-Manual/Load-Balance_apache.md +++ b/src/UserGuide/latest-Table/User-Manual/Load-Balance_apache.md @@ -110,6 +110,8 @@ If you want to further balance historical data after scale-out, you can execute echo "192.168.1.3 iotdb-1" >> /etc/hosts ``` +7. IPv6 network checks: when expanding in a dual-stack or IPv6-only network, verify IPv6 routing and required ports between existing and new nodes, consistent DNS or `/etc/hosts` resolution, and that the configured IPv6 addresses are bound to the appropriate network interfaces. `0.0.0.0` and `::` are listening addresses only and cannot be used as remote targets for a new node to register with the cluster. + #### 2.2.2 Scaling Operation 1. To ensure the IoTDB installation package you obtained is complete and correct, it is recommended to perform an SHA512 checksum before installation and deployment. @@ -129,15 +131,25 @@ vim iotdb-system.properties | Configuration Item | Description | Default | Remarks | |-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|-------------------| ---------------------------------------------------------------------------------------------------------------------------------- | -| `dn_seed_config_node` | The ConfigNode address (format:`cn_internal_address:cn_internal_port`) that a node connects to when registering to join the cluster. | 127.0.0.1:10710 | Extremely important. You must modify this item to the address of the primary ConfigNode in the original cluster. | -| `dn_rpc_address` | Address for the client RPC service. | 0.0.0.0 | Modify as needed; restart service to take effect. | +| `dn_seed_config_node` | ConfigNode endpoint used for node registration and joining the cluster, namely `cn_internal_address:cn_internal_port`. IPv6 uses `[ipv6]:port`. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | Extremely important. You must modify this item to the address of the primary ConfigNode in the original cluster. | +| `dn_rpc_address` | Client RPC listening address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | 0.0.0.0 | Modify as needed; restart service to take effect. | | `dn_rpc_port` | Port for the client RPC service. | 6667 | Modify as needed; restart service to take effect. | -| `dn_internal_address` | Address used by the DataNode for internal cluster communication. | 127.0.0.1 | Modify as needed; cannot be changed after the first startup. | +| `dn_internal_address` | DataNode internal cluster communication address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | Modify as needed; cannot be changed after the first startup. | | `dn_internal_port` | Port used by the DataNode for internal cluster communication. | 10730 | Modify as needed; cannot be changed after the first startup. | | `dn_mpp_data_exchange_port` | Port used by the DataNode for receiving data streams. | 10740 | Modify as needed; restart service to take effect. | | `dn_data_region_consensus_port` | Port used by the DataNode for consensus protocol communication of data replicas. | 10750 | Modify as needed; restart service to take effect. | | `dn_schema_region_consensus_port` | Port used by the DataNode for consensus protocol communication of metadata replicas. | 10760 | Modify as needed; restart service to take effect. | +IPv6-only expansion example: + +```properties +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +dn_rpc_address=NEW_DN_IPV6_ADDRESS +dn_internal_address=NEW_DN_IPV6_ADDRESS +``` + +`CN_IPV6_ADDRESS` is the reachable IPv6 address of a ConfigNode in the existing cluster. `NEW_DN_IPV6_ADDRESS` is an IPv6 address bound to and routable on the new node. Replace both before applying the configuration. After startup, run `show datanodes` and verify that the new node is `Running` and its address field displays the configured unbracketed IPv6 address. If `::` is returned, configure an actual routable IPv6 address for the node’s published address. + 4. Start the DataNode. Navigate to the `sbin`directory under IoTDB and start the datanode: diff --git a/src/UserGuide/latest/API/Programming-Cpp-Native-API_apache.md b/src/UserGuide/latest/API/Programming-Cpp-Native-API_apache.md index 609ee8202..6b9cbbcdc 100644 --- a/src/UserGuide/latest/API/Programming-Cpp-Native-API_apache.md +++ b/src/UserGuide/latest/API/Programming-Cpp-Native-API_apache.md @@ -188,6 +188,8 @@ Notice: this RPC compression status of client must comply with that of IoTDB ser void close(); ``` +Starting with V2.0.12, C++ Session supports IPv6 connections to IoTDB. When initializing a client with IPv6, use an unbracketed IPv6 host and a separate port if the API takes them separately; if it takes a node URL, use `[ipv6]:port`. Replace `DN_IPV6_ADDRESS` with the destination DataNode’s actual reachable IPv6 address. Clients must not use `0.0.0.0`, `::`, or equivalent addresses as remote targets during node discovery or redirection. For SSL, the server certificate SAN must contain the actual unbracketed IPv6 `IP Address` used by the client; see the communication encryption chapter for SSL settings and certificate requirements. + ### 3.2 Data Definition Interface (DDL) #### Database Management @@ -447,4 +449,3 @@ Failed to delete cached file C:\Users\Administrator\.m2\repository\.cache\downlo Possible fixes: - Try to delete the ".m2\repository\\.cache\" directory and try again. - Add "\true\" configuration to the download-maven-plugin maven phase that complains this error. - diff --git a/src/UserGuide/latest/API/Programming-JDBC_apache.md b/src/UserGuide/latest/API/Programming-JDBC_apache.md index 89ccc1e44..c9e08e1c8 100644 --- a/src/UserGuide/latest/API/Programming-JDBC_apache.md +++ b/src/UserGuide/latest/API/Programming-JDBC_apache.md @@ -294,3 +294,12 @@ public class JDBCCharsetExample { } } ``` + +```java +// Starting with V2.0.12, use [ipv6]:port in IPv6 URLs +// String ipv6Url = "jdbc:iotdb://[IPV6_ADDRESS]:6667/"; +// Retain the existing SSL parameters: +// String ipv6SslUrl = "jdbc:iotdb://[IPV6_ADDRESS]:6667?use_ssl=true"; +``` + +JDBC URLs include both an address and port and use `jdbc:iotdb://[ipv6]:port/` for IPv6; brackets around the address are required. Replace `IPV6_ADDRESS` in the comments with an actual reachable IPv6 address; retain the existing IPv4 URL. For SSL, retain the existing connection parameters; the server certificate SAN must include the actual unbracketed IPv6 `IP Address` accessed by the client. diff --git a/src/UserGuide/latest/API/Programming-Java-Native-API_apache.md b/src/UserGuide/latest/API/Programming-Java-Native-API_apache.md index 5d54d0fab..dc5a458d6 100644 --- a/src/UserGuide/latest/API/Programming-Java-Native-API_apache.md +++ b/src/UserGuide/latest/API/Programming-Java-Native-API_apache.md @@ -77,6 +77,13 @@ public class IoTDBSessionPoolExample { } ``` +```java +// An IPv6 node URL includes both an address and port: +// nodeUrls.add("[IPV6_ADDRESS]:6667"); +``` + +Starting with V2.0.12, Java Session and SessionPool support IPv6 connections to IoTDB. Each `nodeUrls` entry combines an address and port and uses `[ipv6]:port` for IPv6. `IPV6_ADDRESS` in the comment marks the actual node address to supply; retain the existing `nodeUrls.add` calls. When an API takes host and port separately, use an unbracketed IPv6 host and pass the port separately. Pool retries and node refreshes use the same endpoint rules. + ### 2.3 Performing Database Operations #### 2.3.1 Data Insertion @@ -495,7 +502,7 @@ The Session class has the following fields, which can be set through the constru | **Field Name** | **Type** | **Description** | | -------------------------------- | ----------------------------------- | ------------------------------------------------------------ | -| `nodeUrls` | `List` | List of URLs for database nodes, supporting multiple node connections | +| `nodeUrls` | `List` | List of database node URLs for multi-node connections; IPv6 endpoints use `[ipv6]:port`, for example `[DN_IPV6_ADDRESS]:6667`. IPv6 is supported from V2.0.12. | | `username` | `String` | Username | | `password` | `String` | Password | | `fetchSize` | `int` | Default batch size for query results | diff --git a/src/UserGuide/latest/API/Programming-Python-Native-API_apache.md b/src/UserGuide/latest/API/Programming-Python-Native-API_apache.md index b77fe093d..d1c72dd1d 100644 --- a/src/UserGuide/latest/API/Programming-Python-Native-API_apache.md +++ b/src/UserGuide/latest/API/Programming-Python-Native-API_apache.md @@ -97,6 +97,25 @@ Notice: this RPC compression status of client must comply with that of IoTDB ser session.close() ``` +```python +# Use an unbracketed IPv6 host when host and port are separate +session = Session( + ip="DN_IPV6_ADDRESS", + port="6667", + user="root", + password="", +) + +# Node URLs include both an address and port and use [ipv6]:port for IPv6 +session = Session.init_from_node_urls( + node_urls=["[DN_IPV6_ADDRESS]:6667", "[DN_IPV6_ADDRESS_2]:6667"], + user="root", + password="", +) +``` + +Starting with V2.0.12, Python Session and SessionPool support IPv6 connections to IoTDB. Use an unbracketed IPv6 address for a separate `ip` argument; do not pass a bracketed address to the underlying socket. `node_urls` entries contain both an address and port and use `[ipv6]:port`. Replace `DN_IPV6_ADDRESS` and `DN_IPV6_ADDRESS_2` with the actual reachable IPv6 addresses of the two nodes. Retain the existing IPv4 examples. + ## 4. Managing Session through SessionPool Utilizing SessionPool to manage sessions eliminates the need to worry about session reuse. When the number of session connections reaches the maximum capacity of the pool, requests for acquiring a session will be blocked, and you can set the blocking wait time through parameters. After using a session, it should be returned to the SessionPool using the `putBack` method for proper management. @@ -228,6 +247,8 @@ if __name__ == "__main__": df = get_data() ``` +Use an unbracketed IPv6 host for SSL connections. The CA specified by `ca_certs` must validate the server certificate, and the server certificate SAN must contain the actual unbracketed IPv6 `IP Address` used by the client. TLS server identity verification fails if the SAN does not contain that address. + ## 5. Data Definition Interface (DDL Interface) ### 5.1 Database Management @@ -870,4 +891,3 @@ Namely, these are * Run Tests via pytest * Build * Release to pypi - diff --git a/src/UserGuide/latest/Deployment-and-Maintenance/AINode_Deployment_apache.md b/src/UserGuide/latest/Deployment-and-Maintenance/AINode_Deployment_apache.md index 3a462bf66..283556201 100644 --- a/src/UserGuide/latest/Deployment-and-Maintenance/AINode_Deployment_apache.md +++ b/src/UserGuide/latest/Deployment-and-Maintenance/AINode_Deployment_apache.md @@ -113,18 +113,26 @@ AINode supports modifying some necessary parameters. You can find the following | **Name** | **Description** | **Type** | **Default Value** | | ------------------------------ | ------------------------------------------------------------ | -------- | ------------------ | | cluster_name | Identifier of the cluster AINode joins | string | defaultCluster | -| ain_seed_config_node | Address of the ConfigNode registered when AINode starts | String | 127.0.0.1:10710 | -| ain_cluster_ingress_address | RPC address of the DataNode for AINode to pull data | String | 127.0.0.1 | +| ain_seed_config_node | ConfigNode endpoint used for AINode registration at startup. Supports `ipv4:port`, `hostname:port`, or `[ipv6]:port`, for example `[CN_IPV6_ADDRESS]:10710`. IPv6 is supported from V2.0.12. | String | 127.0.0.1:10710 | +| ain_cluster_ingress_address | DataNode RPC address from which AINode pulls data. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | String | 127.0.0.1 | | ain_cluster_ingress_port | RPC port of the DataNode for AINode to pull data | Integer | 6667 | | ain_cluster_ingress_username | Client username for AINode to pull data from the DataNode | String | root | | ain_cluster_ingress_password | Client password for AINode to pull data from the DataNode | String | root | | ain_cluster_ingress_time_zone | Client time zone for AINode to pull data from the DataNode | String | UTC+8 | -| ain_inference_rpc_address | Address for AINode to provide services and communication (internal interface) | String | 127.0.0.1 | +| ain_inference_rpc_address | Address used for AINode services and internal communication. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | String | 127.0.0.1 | | ain_inference_rpc_port | Port for AINode to provide services and communication | String | 10810 | | ain_system_dir | Metadata storage path for AINode (relative path starts from OS-dependent directory; absolute path is recommended) | String | data/AINode/system | | ain_models_dir | Path to store model files for AINode (relative path starts from OS-dependent directory; absolute path is recommended) | String | data/AINode/models | | ain_thrift_compression_enabled | Whether to enable Thrift compression for AINode (0=disabled, 1=enabled) | Boolean | 0 | +```properties +ain_seed_config_node=[CN_IPV6_ADDRESS]:10710 +ain_cluster_ingress_address=DN_IPV6_ADDRESS +ain_inference_rpc_address=AINODE_IPV6_ADDRESS +``` + +`ain_seed_config_node` includes both an address and port and uses `[ipv6]:port` for IPv6. `ain_cluster_ingress_address` and `ain_inference_rpc_address` contain addresses only and use unbracketed IPv6. Replace `CN_IPV6_ADDRESS`, `DN_IPV6_ADDRESS`, and `AINODE_IPV6_ADDRESS` with the actual reachable addresses of the ConfigNode, DataNode, and AINode. After startup, verify that AINode is registered with ConfigNode and can access DataNode. + ### 3.3 Importing Weight Files > Offline environment only (Online environments can skip this step) diff --git a/src/UserGuide/latest/Deployment-and-Maintenance/Cluster-Deployment_apache.md b/src/UserGuide/latest/Deployment-and-Maintenance/Cluster-Deployment_apache.md index cd38d324e..5b40d1d06 100644 --- a/src/UserGuide/latest/Deployment-and-Maintenance/Cluster-Deployment_apache.md +++ b/src/UserGuide/latest/Deployment-and-Maintenance/Cluster-Deployment_apache.md @@ -49,6 +49,8 @@ This section will take the IoTDB classic cluster deployment architecture 3C3D (3 6. Before installation, the health check tool can help inspect the operating environment of IoTDB nodes and obtain detailed inspection results. The usage method of the IoTDB health check tool can be found in:[Health Check Tool](../Tools-System/Health-Check-Tool.md). +For dual-stack or IPv6-only deployment, verify before startup that IPv6 is enabled in the operating system and the configured addresses are assigned to the appropriate network interfaces and can be bound by the services; that IPv6 routing between ConfigNodes, DataNodes, and AINodes is reachable and the required RPC, consensus, and client ports are allowed through the firewall; and that DNS or `/etc/hosts` resolution is consistent across nodes when hostnames are used. `0.0.0.0` and `::` are wildcard listening addresses only and cannot be used for node registration, node discovery, client redirection, or other remote connection targets. + ## 2. Preparation Steps 1. Prepare the IoTDB database installation package:：apache-iotdb-{version}-all-bin.zip（Please refer to the installation package for details：[IoTDB-Package](../Deployment-and-Maintenance/IoTDB-Package_apache.md)） @@ -146,10 +148,10 @@ Open the ConfigNode configuration file `./conf/iotdb-system.properties`， Set t | **Configuration** | **Description** | **Default** | **Recommended value** | 192.168.1.3 | 192.168.1.4 | 192.168.1.5 | Note | | ------------------- | ------------------------------------------------------------ | --------------- | ------------------------------------------------------------ | ------------- | ------------- | ------------- | ---------------------------------------- | -| cn_internal_address | The address used by ConfigNode for communication within the cluster | 127.0.0.1 | The IPV4 address or host name of the server where it is located, and it is recommended to use host name | iotdb-1 | iotdb-2 | iotdb-3 | Cannot be modified after initial startup | +| cn_internal_address | Address used for ConfigNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | iotdb-1 | iotdb-2 | iotdb-3 | Cannot be modified after initial startup | | cn_internal_port | The port used by ConfigNode for communication within the cluster | 10710 | 10710 | 10710 | 10710 | 10710 | Cannot be modified after initial startup | | cn_consensus_port | The port used for ConfigNode replica group consensus protocol communication | 10720 | 10720 | 10720 | 10720 | 10720 | Cannot be modified after initial startup | -| cn_seed_config_node | The address of the ConfigNode that the node connects to when registering to join the cluster, `cn_internal_address:cn_internal_port` | 127.0.0.1:10710 | The first CongfigNode's `cn_internal-address: cn_internal_port` | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | Cannot be modified after initial startup | +| cn_seed_config_node | ConfigNode endpoint used for node registration and joining the cluster, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | The first CongfigNode's `cn_internal-address: cn_internal_port` | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | Cannot be modified after initial startup | #### DataNode Configuration @@ -157,14 +159,31 @@ Open DataNode Configuration File `./conf/iotdb-system.properties`,Set the follow | **Configuration** | **Description** | **Default** | **Recommended value** | 192.168.1.3 | 192.168.1.4 | 192.168.1.5 | Note | | ------------------------------- | ------------------------------------------------------------ |-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ------------- | ------------- | ------------- | ---------------------------------------- | -| dn_rpc_address | The address of the client RPC service | 127.0.0.1 | By default, the local machine can directly access it. For non-local access, please modify this configuration item to the IPv4 address or hostname of the server where it is located. It is recommended to use the IPv4 address of the server where it is located. | iotdb-1 |iotdb-2 | iotdb-3 | Restarting the service takes effect | +| dn_rpc_address | Client RPC listening address. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | Local access only by default; for remote access, specify the server’s routable IPv4 address, unbracketed IPv6 address, or hostname | iotdb-1 |iotdb-2 | iotdb-3 | Restarting the service takes effect | | dn_rpc_port | The port of the client RPC service | 6667 | 6667 | 6667 | 6667 | 6667 | Restarting the service takes effect | -| dn_internal_address | The address used by DataNode for communication within the cluster | 127.0.0.1 | The IPV4 address or host name of the server where it is located, and it is recommended to use host name | iotdb-1 | iotdb-2 | iotdb-3 | Cannot be modified after initial startup | +| dn_internal_address | Address used for DataNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | iotdb-1 | iotdb-2 | iotdb-3 | Cannot be modified after initial startup | | dn_internal_port | The port used by DataNode for communication within the cluster | 10730 | 10730 | 10730 | 10730 | 10730 | Cannot be modified after initial startup | | dn_mpp_data_exchange_port | The port used by DataNode to receive data streams | 10740 | 10740 | 10740 | 10740 | 10740 | Cannot be modified after initial startup | | dn_data_region_consensus_port | The port used by DataNode for data replica consensus protocol communication | 10750 | 10750 | 10750 | 10750 | 10750 | Cannot be modified after initial startup | | dn_schema_region_consensus_port | The port used by DataNode for metadata replica consensus protocol communication | 10760 | 10760 | 10760 | 10760 | 10760 | Cannot be modified after initial startup | -| dn_seed_config_node | The address of the ConfigNode that the node connects to when registering to join the cluster, i.e. `cn_internal-address: cn_internal_port` | 127.0.0.1:10710 | The first CongfigNode's cn_internal-address: cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | Cannot be modified after initial startup | +| dn_seed_config_node | ConfigNode endpoint used for node registration and joining the cluster, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | The first CongfigNode's cn_internal-address: cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | Cannot be modified after initial startup | + +The following IPv6-only example shows one ConfigNode and one DataNode in addition to the existing IPv4/hostname examples. Replace `CN_IPV6_ADDRESS` and `DN_IPV6_ADDRESS` with the nodes’ actual reachable IPv6 addresses before deployment. + +```properties +# ConfigNode +cn_internal_address=CN_IPV6_ADDRESS +cn_seed_config_node=[CN_IPV6_ADDRESS]:10710 + +# DataNode +dn_internal_address=DN_IPV6_ADDRESS +dn_rpc_address=DN_IPV6_ADDRESS +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +``` + +`cn_internal_address`, `dn_internal_address`, and `dn_rpc_address` take addresses only and use unbracketed IPv6. `cn_seed_config_node` and `dn_seed_config_node` include addresses and ports and use `[ipv6]:port`. + +After startup, verify that the DataNode has registered with the ConfigNode. Cluster IP fields may show unbracketed IPv6; endpoints in logs, errors, and other output must use `[ipv6]:port`. If the service listens on `::`, the node must still publish an actual routable IPv6 address. > ❗️Attention: Editors such as VSCode Remote do not have automatic configuration saving function. Please ensure that the modified files are saved persistently, otherwise the configuration items will not take effect @@ -205,6 +224,8 @@ cd sbin .\windows\start-datanode.bat ``` +After startup, run `show cluster` in the CLI to verify that ConfigNodes and DataNodes are registered. In an IPv6-only environment, node address fields should display the configured unbracketed IPv6 addresses; addresses with ports in logs or errors should use `[ipv6]:port`. If `::` is returned as a node address, configure an actual routable IPv6 address for the node’s published address. + ### 3.5 Verify Deployment Can be executed directly Cli startup script in `./sbin` directory: @@ -221,6 +242,12 @@ Can be executed directly Cli startup script in `./sbin` directory: .\windows\start-cli.bat -h ip -p 6667 ``` +When passing an IPv6 address separately with `-h`, omit brackets and specify the port with `-p`. For example: + +```shell +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' +``` + After successful startup, the following interface will appear displaying successful installation of IOTDB. ![](/img/%E5%BC%80%E6%BA%90%E6%88%90%E5%8A%9F.png) diff --git a/src/UserGuide/latest/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md b/src/UserGuide/latest/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md index bc1f40303..e7bd5ec9c 100644 --- a/src/UserGuide/latest/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md +++ b/src/UserGuide/latest/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md @@ -115,10 +115,10 @@ Open the ConfigNode configuration file (./conf/iotdb-system. properties file) an | **Configuration** | **Description** | **Default** | **Recommended value** | Note | | :-----------------: | :----------------------------------------------------------: | :-------------: | :----------------------------------------------------------: | :--------------------------------------: | -| cn_internal_address | The address used by ConfigNode for communication within the cluster | 127.0.0.1 | The IPV4 address or host name of the server where it is located, and it is recommended to use host name | Cannot be modified after initial startup | +| cn_internal_address | Address used for ConfigNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | Cannot be modified after initial startup | | cn_internal_port | The port used by ConfigNode for communication within the cluster | 10710 | 10710 | Cannot be modified after initial startup | | cn_consensus_port | The port used for ConfigNode replica group consensus protocol communication | 10720 | 10720 | Cannot be modified after initial startup | -| cn_seed_config_node | The address of the ConfigNode that the node connects to when registering to join the cluster, cn_internal_address:cn_internal_port | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | Cannot be modified after initial startup | +| cn_seed_config_node | ConfigNode endpoint used for node registration, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | Cannot be modified after initial startup | #### DataNode Configuration @@ -126,14 +126,26 @@ Open the DataNode configuration file (./conf/iotdb-system. properties file) and | **Configuration** | **Description** | **Default** | **Recommended value** | **Note** | | :-----------------------------: | :----------------------------------------------------------: | :-------------: |:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:| :--------------------------------------- | -| dn_rpc_address | The address of the client RPC service | 127.0.0.1 | By default, the local machine can directly access it. For non-local access, please modify this configuration item to the IPv4 address or hostname of the server where it is located. It is recommended to use the IPv4 address of the server where it is located. | Restarting the service takes effect | +| dn_rpc_address | Client RPC listening address. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | Local access only by default; for remote access, specify the server’s routable IPv4 address, unbracketed IPv6 address, or hostname | Restarting the service takes effect | | dn_rpc_port | The port of the client RPC service | 6667 | 6667 | Restarting the service takes effect | -| dn_internal_address | The address used by DataNode for communication within the cluster | 127.0.0.1 | The IPV4 address or host name of the server where it is located, and it is recommended to use host name | Cannot be modified after initial startup | +| dn_internal_address | Address used for DataNode internal communication. IPv6 uses an unbracketed address without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | The server’s IPv4 address, unbracketed IPv6 address, or hostname; a hostname is recommended | Cannot be modified after initial startup | | dn_internal_port | The port used by DataNode for communication within the cluster | 10730 | 10730 | Cannot be modified after initial startup | | dn_mpp_data_exchange_port | The port used by DataNode to receive data streams | 10740 | 10740 | Cannot be modified after initial startup | | dn_data_region_consensus_port | The port used by DataNode for data replica consensus protocol communication | 10750 | 10750 | Cannot be modified after initial startup | | dn_schema_region_consensus_port | The port used by DataNode for metadata replica consensus protocol communication | 10760 | 10760 | Cannot be modified after initial startup | -| dn_seed_config_node | The ConfigNode address that the node connects to when registering to join the cluster, i.e. cn_internal-address: cn_internal_port | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | Cannot be modified after initial startup | +| dn_seed_config_node | ConfigNode endpoint used for node registration, namely `cn_internal_address:cn_internal_port`; use `[ipv6]:port` for IPv6. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | Cannot be modified after initial startup | + +Standalone instances accessed only from the local host can use the IPv6 loopback address: + +```properties +cn_internal_address=::1 +cn_seed_config_node=[::1]:10710 +dn_internal_address=::1 +dn_rpc_address=::1 +dn_seed_config_node=[::1]:10710 +``` + +`::1` is the IPv6 loopback address and is for local access or testing only. For access from other hosts, use the local host’s actual routable IPv6 address. `::` listens on all IPv6 interfaces and cannot be used as a remote target, node discovery result, or client redirection address. > ❗️Attention: Editors such as VSCode Remote do not have automatic configuration saving function. Please ensure that the modified files are saved persistently, otherwise the configuration items will not take effect diff --git a/src/UserGuide/latest/FAQ/Frequently-asked-questions.md b/src/UserGuide/latest/FAQ/Frequently-asked-questions.md index 6f70b4992..b629c1ef9 100644 --- a/src/UserGuide/latest/FAQ/Frequently-asked-questions.md +++ b/src/UserGuide/latest/FAQ/Frequently-asked-questions.md @@ -332,3 +332,33 @@ Notes: #### How to decrease the memory usage of ConfigNode/DataNode? - Adjust the ON_HEAP_MEMORY、OFF_HEAP_MEMORY options in conf/confignode-env.sh and conf/datanode-env.sh. + +## 3. IPv6 Connection FAQ + +### 3.1 Why is `[::1]:6667` valid while `::1:6667` should not be used as an endpoint? + +Starting with V2.0.12, IoTDB supports IPv6 connections. IPv6 addresses contain multiple colons. Address and port combinations must use `[ipv6]:port` to distinguish them. The address and port in JDBC URLs, Session node URLs, and Pipe `node-urls` must use `[ipv6]:port`. + +### 3.2 Why do address parameters use unbracketed IPv6 while JDBC and Pipe use `[ipv6]:port`? + +Parameters such as `cn_internal_address`, `dn_internal_address`, and `dn_rpc_address` contain addresses only and use unbracketed IPv6. JDBC URLs, seed endpoints, Session node URLs, and Pipe `node-urls` include both addresses and ports and use `[ipv6]:port`. + +### 3.3 Why does listening on `::` succeed while clients still cannot connect? + +`::` listens on all IPv6 interfaces and is not a routable remote address. Node registration, node discovery, client redirection, Pipe destinations, and Prometheus targets must use actual reachable IPv6 addresses. + +### 3.4 How do I resolve hostname or IP verification failures in IPv6 TLS connections? + +Check that the server certificate SAN contains the actual unbracketed IPv6 `IP Address` used by the client, without brackets or a port. Also verify that the client TrustStore contains the CA that issued the certificate. + +### 3.5 How do I troubleshoot connection failures in an IPv6-only environment? + +Check, in order, that IPv6 is enabled in the operating system, addresses are bound, inter-node routes and ports are reachable, firewalls allow traffic, DNS or `/etc/hosts` resolution is consistent, and the client runtime and underlying socket support IPv6. + +### 3.6 What if IPv4 works but IPv6 connections fail in a dual-stack environment? + +First connect directly with the actual IPv6 address and port using the required syntax, and verify that the destination service is bound to an IPv6 address and routing and firewall rules allow access to the port. Then check that DNS AAAA records or IPv6 mappings in `/etc/hosts` point to the destination. Verify IPv4 and IPv6 paths separately; successful IPv4 connections do not confirm IPv6 connectivity. Do not publish `::` as a node address. + +### 3.7 How do I resolve IPv6 endpoint parsing errors in Pipe? + +Check that every IPv6 endpoint uses `[ipv6]:port`, that multiple endpoints are separated by commas, and that `::` or `0.0.0.0` has not been used as a destination. For SSL Pipe, also check the TrustStore, KeyStore, and destination certificate SAN. diff --git a/src/UserGuide/latest/Reference/System-Config-Manual_apache.md b/src/UserGuide/latest/Reference/System-Config-Manual_apache.md index a34c65b21..380ca970f 100644 --- a/src/UserGuide/latest/Reference/System-Config-Manual_apache.md +++ b/src/UserGuide/latest/Reference/System-Config-Manual_apache.md @@ -144,11 +144,15 @@ The `iotdb-system.properties` file contains various configurations for managing ### 4.2 Seed ConfigNode +> Address-only parameters use unbracketed IPv6 addresses; endpoints containing both an address and a port use `[ipv6]:port`. + +`CN_IPV6_ADDRESS` below marks the ConfigNode IPv6 address field. Use an actual resolvable, routable address. Existing IPv4/hostname examples and default values remain unchanged. + - cn_seed_config_node | Name | cn_seed_config_node | | ----------- | ------------------------------------------------------------ | -| Description | Address of the seed ConfigNode for Confignode to join the cluster. | +| Description | Endpoint of the target ConfigNode through which a ConfigNode joins the cluster; a SeedConfigNode is recommended. Supports `ipv4:port`, `hostname:port`, or `[ipv6]:port`, for example `[CN_IPV6_ADDRESS]:10710`. Previously named cn_target_config_node_list in V1.2.2 and earlier. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1:10710 | | Effective | Modify before the first startup. | @@ -157,7 +161,7 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | dn_seed_config_node | | ----------- | ------------------------------------------------------------ | -| Description | Address of the seed ConfigNode for Datanode to join the cluster. | +| Description | Endpoint of the ConfigNode through which a DataNode joins the cluster at startup; a SeedConfigNode is recommended. Supports `ipv4:port`, `hostname:port`, or `[ipv6]:port`, for example `[CN_IPV6_ADDRESS]:10710`. Previously named dn_target_config_node_list in V1.2.2 and earlier. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1:10710 | | Effective | Modify before the first startup. | @@ -168,7 +172,7 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | cn_internal_address | | ----------- | ---------------------------------------------- | -| Description | Internal address for ConfigNode communication. | +| Description | ConfigNode internal cluster communication address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port, for example `192.168.1.10`, `CN_IPV6_ADDRESS`, or `iotdb-cn-1`. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1 | | Effective | Modify before the first startup. | @@ -195,7 +199,7 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | dn_rpc_address | | ----------- |---------------------------------| -| Description | Address for client RPC service. | +| Description | Listening address for the client RPC service. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port, for example `192.168.1.20`, `DN_IPV6_ADDRESS`, or `iotdb-dn-1`. `::` listens on all IPv6 interfaces, but cannot be returned as a remote address for client redirection or node discovery. IPv6 is supported from V2.0.12. | | Type | String | | Default | 127.0.0.1 | | Effective | Restart required. | @@ -213,11 +217,15 @@ The `iotdb-system.properties` file contains various configurations for managing | Name | dn_internal_address | | ----------- | -------------------------------------------- | -| Description | Internal address for DataNode communication. | +| Description | DataNode internal communication address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port, for example `192.168.1.20`, `DN_IPV6_ADDRESS`, or `iotdb-dn-1`. IPv6 is supported from V2.0.12. | | Type | string | | Default | 127.0.0.1 | | Effective | Modify before the first startup. | +> Use unbracketed IPv6 for address-only parameters, such as `DN_IPV6_ADDRESS`; use `[ipv6]:port` for endpoints containing both an address and port, such as `[DN_IPV6_ADDRESS]:10730`. `0.0.0.0` and `::` are wildcard listening addresses only; do not use them as remote connection targets. + +`DN_IPV6_ADDRESS` below marks the DataNode IPv6 address field. Replace it with an address bound to and reachable on the corresponding node. + - dn_internal_port | Name | dn_internal_port | @@ -523,6 +531,8 @@ The `iotdb-system.properties` file contains various configurations for managing ### 4.7 SSL Configuration +> IPv6 uses the existing SSL/TLS switches, protocols, KeyStore, and TrustStore settings. For TLS server identity verification over IPv6, the server certificate SAN must contain the actual IPv6 address used by the client as an unbracketed `IP Address`, without a port. For example, when connecting to `[DN_IPV6_ADDRESS]:6667`, the SAN must contain `DN_IPV6_ADDRESS`. + - enable_thrift_ssl | Name | enable_thrift_ssl | diff --git a/src/UserGuide/latest/Tools-System/CLI_apache.md b/src/UserGuide/latest/Tools-System/CLI_apache.md index d05045fe0..582bbd8e6 100644 --- a/src/UserGuide/latest/Tools-System/CLI_apache.md +++ b/src/UserGuide/latest/Tools-System/CLI_apache.md @@ -84,11 +84,21 @@ IoTDB> Enter ```quit``` or `exit` can exit Cli. +Starting with V2.0.12, pass an IPv6 address to `-h` without brackets and specify the port separately with `-p`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with an actual reachable IPv6 address before running the command. Retain the existing IPv4 startup examples. For example: + +```shell +# Linux/macOS +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' + +# Windows (V2.0.4.x and later) +sbin\windows\start-cli.bat -h DN_IPV6_ADDRESS -p 6667 -u root -pw "" +``` + ### 2.2 Cli Parameters | **Parameter** | **Type** | **Required** | **Description** | **Example** | | -------------------------- | -------- | ------------ |-----------------------------------------------------------------------------------| ------------------- | -| -h `` | string | No | The IP address of the IoTDB server. (Default: 127.0.0.1) | -h 127.0.0.1 | +| -h `` | string | No | IPv4 address, unbracketed IPv6 address, or hostname of the IoTDB server to connect to; omit brackets for IPv6. Defaults to `127.0.0.1`. IPv6 is supported from V2.0.12. | -h 127.0.0.1 | | -p `` | int | No | The RPC port of the IoTDB server. (Default: 6667) | -p 6667 | | -u `` | string | No | The username to connect to the IoTDB server. (Default: root) | -u root | | -pw `` | string | No | The password to connect to the IoTDB server. (Default: root) | -pw root | diff --git a/src/UserGuide/latest/Tools-System/Data-Export-Tool_apache.md b/src/UserGuide/latest/Tools-System/Data-Export-Tool_apache.md index 1dfb92eac..d0f2c33f1 100644 --- a/src/UserGuide/latest/Tools-System/Data-Export-Tool_apache.md +++ b/src/UserGuide/latest/Tools-System/Data-Export-Tool_apache.md @@ -31,7 +31,7 @@ The data export tool, export-data.sh (Unix/OS X) or export-data.bat (Windows), l | Short | Full Parameter | Description | Required | Default | |-----------------|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------|------------|---------------------------------------------------------------------------------------------| | `-ft` | `--file_type` | Export file type: `csv`, `sql`, `tsfile`. | ​**Yes** | - | -| `-h` | `--host` | Hostname of the IoTDB server. | No | `127.0.0.1` | +| `-h` | `--host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | `127.0.0.1` | | `-p` | `--port` | Port number of the IoTDB server. | No | `6667` | | `-u` | `--username` | Username for authentication. | No | `root` | | `-pw` | `--password` | Password for authentication. Supported for hidden input since V2.0.10 | No | `root` | @@ -44,6 +44,8 @@ The data export tool, export-data.sh (Unix/OS X) or export-data.bat (Windows), l | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with the actual reachable unbracketed IPv6 address before running the command. Do not pass brackets to `-h`. For SSL, retain the existing `-usessl`, `-ts`, and `-tpw` parameters; the server certificate SAN must contain the actual unbracketed IPv6 address accessed by the client. + ### 2.2 CSV Format #### 2.2.1 Command diff --git a/src/UserGuide/latest/Tools-System/Data-Import-Tool_apache.md b/src/UserGuide/latest/Tools-System/Data-Import-Tool_apache.md index e0995b18d..feb323224 100644 --- a/src/UserGuide/latest/Tools-System/Data-Import-Tool_apache.md +++ b/src/UserGuide/latest/Tools-System/Data-Import-Tool_apache.md @@ -42,7 +42,7 @@ IoTDB supports three methods for data import: | Short | Full Parameter | Description | Required | Default | |-----------------|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------- |-----------------------------------------------| | `-ft` | `--file_type` | File type: `csv`, `sql`, `tsfile`. | ​**Yes** | - | -| `-h` | `--host` | IoTDB server hostname. | No | `127.0.0.1` | +| `-h` | `--host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | `127.0.0.1` | | `-p` | `--port` | IoTDB server port. | No | `6667` | | `-u` | `--username` | Username. | No | `root` | | `-pw` | `--password` | Password. Supported for hidden input since V2.0.10 | No | `root` | @@ -54,6 +54,8 @@ IoTDB supports three methods for data import: | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with the actual reachable unbracketed IPv6 address before running the command. Do not pass brackets to `-h`. For SSL, retain the existing `-usessl`, `-ts`, and `-tpw` parameters; the server certificate SAN must contain the actual unbracketed IPv6 address accessed by the client. + ### 2.2 CSV Format #### 2.2.1 Command diff --git a/src/UserGuide/latest/Tools-System/Monitor-Tool_apache.md b/src/UserGuide/latest/Tools-System/Monitor-Tool_apache.md index b7107644b..7807a5a69 100644 --- a/src/UserGuide/latest/Tools-System/Monitor-Tool_apache.md +++ b/src/UserGuide/latest/Tools-System/Monitor-Tool_apache.md @@ -64,6 +64,12 @@ file_count{name="seq",} 2.0 ... ``` +Starting with V2.0.12, the metrics endpoint supports access over IPv6. Use brackets to distinguish the address from the port in an IPv6 metrics URL. Replace the placeholder below with the actual reachable IPv6 address: + +```shell +curl 'http://[IPV6_ADDRESS]:9091/metrics' +``` + ### 1.3 Prometheus + Grafana As shown above, IoTDB exposes monitoring metrics data in the standard Prometheus format to the outside world. Prometheus @@ -95,6 +101,7 @@ follow_redirects: true static_configs: - targets: - localhost:9091 + - '[IPV6_ADDRESS]:9091' ``` The following documents may help you have a good journey with Prometheus and Grafana. @@ -106,3 +113,4 @@ The following documents may help you have a good journey with Prometheus and Gra [Grafana getting_started](https://grafana.com/docs/grafana/latest/getting-started/getting-started/) [Grafana query metrics from Prometheus](https://prometheus.io/docs/visualization/grafana/#grafana-support-for-prometheus) +Prometheus targets include both an IPv6 address and a port and must use `[ipv6]:port`. Even if the service listens on `::`, use an actual routable IPv6 address for the target, never `[::]:9091`. diff --git a/src/UserGuide/latest/Tools-System/Schema-Export-Tool_apache.md b/src/UserGuide/latest/Tools-System/Schema-Export-Tool_apache.md index 02f45ecd4..47ddea2aa 100644 --- a/src/UserGuide/latest/Tools-System/Schema-Export-Tool_apache.md +++ b/src/UserGuide/latest/Tools-System/Schema-Export-Tool_apache.md @@ -31,7 +31,7 @@ The schema export tool `export-schema.sh/bat` is located in the `tools` director | **Short Param** | **Full Param** | **Description** | Required | Default | |------------------|---------------------------|--------------------------------------------------------------------------| ------------------------------------- |-----------------------------------------------| -| `-h` | `--host` | Hostname | No | 127.0.0.1 | +| `-h` | `--host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | 127.0.0.1 | | `-p` | `--port` | Port number | No | 6667 | | `-u` | `--username` | Username | No | root | | `-pw` | `--password` | Password. Supported for hidden input since V2.0.10 | No | root | @@ -48,6 +48,8 @@ The schema export tool `export-schema.sh/bat` is located in the `tools` director | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with the actual reachable unbracketed IPv6 address before running the command. Do not pass brackets to `-h`. For SSL, retain the existing `-usessl`, `-ts`, and `-tpw` parameters; verify that the certificate SAN contains the actual IPv6 address accessed by the client. + ### 2.2 Command ```Bash @@ -82,4 +84,6 @@ Shell Timeseries,Alias,DataType,Encoding,Compression root.treedb.device.temperature,,DOUBLE,GORILLA,LZ4 root.treedb.device.humidity,,DOUBLE,GORILLA,LZ4 -``` \ No newline at end of file +``` + +Starting with V2.0.12, `-h` accepts an actual unbracketed IPv6 address and `-p` still takes the port separately. Parameters such as `-sql_dialect`, `-db`, `-s`, `-t`, and `-path` do not need to change for IPv6. \ No newline at end of file diff --git a/src/UserGuide/latest/Tools-System/Schema-Import-Tool_apache.md b/src/UserGuide/latest/Tools-System/Schema-Import-Tool_apache.md index 7f58e997a..4a0b9fddf 100644 --- a/src/UserGuide/latest/Tools-System/Schema-Import-Tool_apache.md +++ b/src/UserGuide/latest/Tools-System/Schema-Import-Tool_apache.md @@ -31,7 +31,7 @@ The schema import tool `import-schema.sh/bat` is located in `tools` directory. | **Short Param** | **Full Param** | **Description** | Required | Default | |-----------------|---------------------------|--------------------------------------------------------------------------| ---------- |-------------------------------------------| -| `-h` | `--host` | Hostname | No | 127.0.0.1 | +| `-h` | `--host` | Database server IPv4 address, unbracketed IPv6 address, or hostname; omit brackets for IPv6. IPv6 is supported from V2.0.12. | No | 127.0.0.1 | | `-p` | `--port` | Port number | No | 6667 | | `-u` | `--username` | Username | No | root | | `-pw` | `--password` | Password. Supported for hidden input since V2.0.10 | No | root | @@ -46,6 +46,8 @@ The schema import tool `import-schema.sh/bat` is located in `tools` directory. | `-ts` | `--trust_store` | Trust store. Supports hidden input. Supported since V2.0.10 | No | - | | `-tpw` | `--trust_store_password` | Trust store password. Supports hidden input. Supported since V2.0.10 | No | - | +`-h` and `-p` take host and port separately, so use an unbracketed IPv6 host, for example `-h DN_IPV6_ADDRESS -p 6667`. `DN_IPV6_ADDRESS` is a destination DataNode address placeholder; replace it with the actual reachable unbracketed IPv6 address before running the command. Do not pass brackets to `-h`. For SSL, retain the existing `-usessl`, `-ts`, and `-tpw` parameters; verify that the certificate SAN contains the actual IPv6 address accessed by the client. + ### 2.2 Command ```Bash @@ -88,3 +90,5 @@ IoTDB> show timeseries root.treedb.** | root.treedb.device.humidity| null|root.treedb| DOUBLE| GORILLA| LZ4|null| null| null| null| BASE| +------------------------------+-----+-----------+--------+--------+-----------+----+----------+--------+------------------+--------+ ``` + +Starting with V2.0.12, `-h` accepts an actual unbracketed IPv6 address and `-p` still takes the port separately. Parameters such as `-sql_dialect`, `-db`, `-s`, `-t`, and `-path` do not need to change for IPv6. diff --git a/src/UserGuide/latest/User-Manual/Data-Sync_apache.md b/src/UserGuide/latest/User-Manual/Data-Sync_apache.md index 06bcfaea6..44dc1e0b6 100644 --- a/src/UserGuide/latest/User-Manual/Data-Sync_apache.md +++ b/src/UserGuide/latest/User-Manual/Data-Sync_apache.md @@ -368,6 +368,16 @@ with sink ( 'node-urls' = '127.0.0.1:6668', ``` +```sql +create pipe A2B_IPV6 +with sink ( + 'sink'='iotdb-thrift-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667' +) +``` + +Starting with V2.0.12, Pipe supports IPv6 endpoints for connecting to the destination IoTDB. `node-urls` includes both an address and port and uses `[ipv6]:port` for IPv6; separate multiple endpoints with commas. `DN_IPV6_ADDRESS` and `DN_IPV6_ADDRESS_2` in the independent example above represent the actual reachable IPv6 addresses of two destination DataNodes. Replace them before use; retain the existing Pipe examples. + ### 3.2 Partial data synchronization This example is used to demonstrate the synchronisation of data from a certain historical time range (8:00pm 23 August 2023 to 8:00pm 23 October 2023) to another IoTDB, the data link is shown below: @@ -536,6 +546,18 @@ Where: - `ssl.trust-store-path`: The trust store certificate path required to connect to the target DataNode - `ssl.trust-store-pwd`: The trust store certificate password required to connect to the target DataNode +```sql +create pipe A2B_SSL_IPV6 +with sink ( + 'sink'='iotdb-thrift-ssl-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667', + 'ssl.trust-store-path'='pki/trusted', + 'ssl.trust-store-pwd'='' +) +``` + +For TLS server identity verification over IPv6, the server certificate SAN must contain the actual IPv6 address used by the client as an unbracketed `IP Address`, without a port. + ## 4. Reference: Notes You can adjust the parameters for data synchronization by modifying the IoTDB configuration file （`iotdb-system.properties`）, such as the directory for storing synchronized data. The complete configuration is as follows: @@ -632,7 +654,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **Parameter** | **Description** | Value Range | Required | Default Value | |:-----------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| :----------------------------------------------------------- | :------- | :------------ | | sink | iotdb-thrift-sink or iotdb-thrift-async-sink | String: iotdb-thrift-sink or iotdb-thrift-async-sink | Yes | - | -| node-urls | URLs of the DataNode service ports on the target IoTDB. (please note that the synchronization task does not support forwarding to its own service). | String. Example：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | Yes | - | +| node-urls | Data service endpoints of multiple DataNodes on the destination IoTDB (synchronization tasks cannot forward to their own service). IPv6 uses `[ipv6]:port`; separate multiple endpoints with commas. IPv6 is supported from V2.0.12. | String. Examples: `'127.0.0.1:6667,127.0.0.1:6668'`, `'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | Yes | - | | user/username | Username for connecting to the target IoTDB. Must have appropriate permissions. | String | No | root | | password | Password for the username. | String | No | root | | batch.enable | Enables batch mode for log transmission to improve throughput and reduce IOPS. | Boolean: true, false | No | true | @@ -651,7 +673,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **Parameter** | **Description** | Value Range | Required | Default Value | |:-----------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------|:---------| :------------ | | sink | iotdb-thrift-ssl-sink | String: iotdb-thrift-ssl-sink | Yes | - | -| node-urls | URLs of the DataNode service ports on the target IoTDB. (please note that the synchronization task does not support forwarding to its own service). | String. Example：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | Yes | - | +| node-urls | Data service endpoints of multiple DataNodes on the destination IoTDB (synchronization tasks cannot forward to their own service). IPv6 uses `[ipv6]:port`; separate multiple endpoints with commas; the destination certificate SAN must cover the actual connection address. IPv6 is supported from V2.0.12. | String. Examples: `'127.0.0.1:6667,127.0.0.1:6668'`, `'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | Yes | - | | user/username | Username for connecting to the target IoTDB. Must have appropriate permissions. | String | No | root | | password | Password for the username. | String | No | root | | batch.enable | Enables batch mode for log transmission to improve throughput and reduce IOPS. | Boolean: true, false | No | true | @@ -666,4 +688,3 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | ssl.trust-store-pwd | Password for the trust store certificate. | String: 'root' | Yes | - | | format | The payload formats for data transmission include the following options:
- hybrid: The format depends on what is passed from the processor (either tsfile or tablet), and the sink performs no conversion.
- tsfile: Data is forcibly converted to tsfile format before transmission. This is suitable for scenarios like data file backup.
- tablet: Data is forcibly converted to tsfile format before transmission. This is useful for data synchronization when the sender and receiver have incompatible data types (to minimize errors). | String: hybrid / tsfile / tablet | No | hybrid | | exception.data.convert-on-type-mismatch | Whether to enable automatic conversion when data types mismatch on the sink side | Boolean: true / false | No | true | - diff --git a/src/UserGuide/latest/User-Manual/Load-Balance_apache.md b/src/UserGuide/latest/User-Manual/Load-Balance_apache.md index b1b760005..343c8d267 100644 --- a/src/UserGuide/latest/User-Manual/Load-Balance_apache.md +++ b/src/UserGuide/latest/User-Manual/Load-Balance_apache.md @@ -110,6 +110,8 @@ If you want to further balance historical data after scale-out, you can execute echo "192.168.1.3 iotdb-1" >> /etc/hosts ``` +7. IPv6 network checks: when expanding in a dual-stack or IPv6-only network, verify IPv6 routing and required ports between existing and new nodes, consistent DNS or `/etc/hosts` resolution, and that the configured IPv6 addresses are bound to the appropriate network interfaces. `0.0.0.0` and `::` are listening addresses only and cannot be used as remote targets for a new node to register with the cluster. + #### 2.2.2 Scaling Operation 1. To ensure the IoTDB installation package you obtained is complete and correct, it is recommended to perform an SHA512 checksum before installation and deployment. @@ -129,15 +131,25 @@ vim iotdb-system.properties | Configuration Item | Description | Default | Remarks | |-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|-------------------| ---------------------------------------------------------------------------------------------------------------------------------- | -| `dn_seed_config_node` | The ConfigNode address (format:`cn_internal_address:cn_internal_port`) that a node connects to when registering to join the cluster. | 127.0.0.1:10710 | Extremely important. You must modify this item to the address of the primary ConfigNode in the original cluster. | -| `dn_rpc_address` | Address for the client RPC service. | 0.0.0.0 | Modify as needed; restart service to take effect. | +| `dn_seed_config_node` | ConfigNode endpoint used for node registration and joining the cluster, namely `cn_internal_address:cn_internal_port`. IPv6 uses `[ipv6]:port`. IPv6 is supported from V2.0.12. | 127.0.0.1:10710 | Extremely important. You must modify this item to the address of the primary ConfigNode in the original cluster. | +| `dn_rpc_address` | Client RPC listening address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | 0.0.0.0 | Modify as needed; restart service to take effect. | | `dn_rpc_port` | Port for the client RPC service. | 6667 | Modify as needed; restart service to take effect. | -| `dn_internal_address` | Address used by the DataNode for internal cluster communication. | 127.0.0.1 | Modify as needed; cannot be changed after the first startup. | +| `dn_internal_address` | DataNode internal cluster communication address. Supports an unbracketed IPv4 address, an unbracketed IPv6 address, or a hostname, without a port. IPv6 is supported from V2.0.12. | 127.0.0.1 | Modify as needed; cannot be changed after the first startup. | | `dn_internal_port` | Port used by the DataNode for internal cluster communication. | 10730 | Modify as needed; cannot be changed after the first startup. | | `dn_mpp_data_exchange_port` | Port used by the DataNode for receiving data streams. | 10740 | Modify as needed; restart service to take effect. | | `dn_data_region_consensus_port` | Port used by the DataNode for consensus protocol communication of data replicas. | 10750 | Modify as needed; restart service to take effect. | | `dn_schema_region_consensus_port` | Port used by the DataNode for consensus protocol communication of metadata replicas. | 10760 | Modify as needed; restart service to take effect. | +IPv6-only expansion example: + +```properties +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +dn_rpc_address=NEW_DN_IPV6_ADDRESS +dn_internal_address=NEW_DN_IPV6_ADDRESS +``` + +`CN_IPV6_ADDRESS` is the reachable IPv6 address of a ConfigNode in the existing cluster. `NEW_DN_IPV6_ADDRESS` is an IPv6 address bound to and routable on the new node. Replace both before applying the configuration. After startup, run `show datanodes` and verify that the new node is `Running` and its address field displays the configured unbracketed IPv6 address. If `::` is returned, configure an actual routable IPv6 address for the node’s published address. + 4. Start the DataNode. Navigate to the `sbin`directory under IoTDB and start the datanode: diff --git a/src/zh/UserGuide/Master/Table/API/Programming-Cpp-Native-API_apache.md b/src/zh/UserGuide/Master/Table/API/Programming-Cpp-Native-API_apache.md index 1d37b4f12..3bbbe9314 100644 --- a/src/zh/UserGuide/Master/Table/API/Programming-Cpp-Native-API_apache.md +++ b/src/zh/UserGuide/Master/Table/API/Programming-Cpp-Native-API_apache.md @@ -223,11 +223,13 @@ session = (new TableSessionBuilder()) ->build(); ``` +`host()` 也可传入裸 IPv6 地址，`rpcPort()` 仍单独设置端口。 + #### 3.2.2 可设置的参数列表 | **参数名** | **描述** | **默认值** | | :---: | :---: | :---: | -| host | 设置连接的节点IP | "127.0.0.1" ("localhost") | +| host | 设置连接的节点 IP，支持裸 IPv4、裸 IPv6 或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | "127.0.0.1" ("localhost") | | rpcPort | 设置连接的节点端口 | 6667 | | username | 设置连接的用户名 | "root" | | password | 设置连接密码 | "root" | diff --git a/src/zh/UserGuide/Master/Table/API/Programming-JDBC_apache.md b/src/zh/UserGuide/Master/Table/API/Programming-JDBC_apache.md index f9ae1e4b7..861116f39 100644 --- a/src/zh/UserGuide/Master/Table/API/Programming-JDBC_apache.md +++ b/src/zh/UserGuide/Master/Table/API/Programming-JDBC_apache.md @@ -189,4 +189,13 @@ public class TableModelJDBCExample { } } } + +```java +// IPv6 + Table 模型 +String url = "jdbc:iotdb://[DN_IPV6_ADDRESS]:6667?sql_dialect=table"; +// IPv6 + Table 模型 + SSL +String sslUrl = "jdbc:iotdb://[DN_IPV6_ADDRESS]:6667?sql_dialect=table&use_ssl=true"; +``` + +自 V2.0.12 起，表模型 JDBC URL 也可使用 `[ipv6]:port`；示例中的 `DN_IPV6_ADDRESS` 仅为 DataNode 地址占位符，使用前须替换为实际可达地址。通过 IPv6 地址启用 SSL 时，服务端证书 SAN 使用不带方括号和端口的裸 IPv6 地址。原有表模型 URL 示例继续保留。 ``` \ No newline at end of file diff --git a/src/zh/UserGuide/Master/Table/API/Programming-Java-Native-API_apache.md b/src/zh/UserGuide/Master/Table/API/Programming-Java-Native-API_apache.md index 4919b16c2..653a6183d 100644 --- a/src/zh/UserGuide/Master/Table/API/Programming-Java-Native-API_apache.md +++ b/src/zh/UserGuide/Master/Table/API/Programming-Java-Native-API_apache.md @@ -154,7 +154,7 @@ TableSessionBuilder类是一个构建器，用于配置和创建ITableSession接 | **配置项** | **描述** | **默认值** | | ---------------------------------------------------- | ---------------------------------------- | ------------------------------------------- | -| nodeUrls(List`` nodeUrls) | 设置IoTDB集群的节点URL列表 | Collections.singletonList("localhost:6667") | +| nodeUrls(List`` nodeUrls) | 设置 IoTDB 集群的节点 URL 列表；IPv6 endpoint 使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:6667`。IPv6 自 V2.0.12 起支持。 | Collections.singletonList("localhost:6667") | | username(String username) | 设置连接的用户名 | "root" | | password(String password) | 设置连接的密码 | "TimechoDB@2021"（V2.0.6.x 之前默认密码是 root） | | database(String database) | 设置目标数据库名称 | null | @@ -185,6 +185,8 @@ TableSessionBuilder类是一个构建器，用于配置和创建ITableSession接 | withDateEncoding(TSEncoding tsEncoding) | 设置DATE类型的编码方式 | TSEncoding.TS_2DIFF | | connectionTimeoutInMs(int connectionTimeoutInMs) | 设置连接超时时间（毫秒） | 0（无超时） | +自 V2.0.12 起，表模型 `nodeUrls` 也支持 IPv6 endpoint。表格示意值中的 `DN_IPV6_ADDRESS` 为 DataNode 地址占位符，配置时替换为实际可达地址，原默认值不变。`TableSessionBuilder` 的 `host`/`rpcPort` 分开配置时，host 使用裸 IPv6；只有 node URL 字符串才使用方括号。 + #### 3.2.3 接口展示 ``` java @@ -524,7 +526,7 @@ TableSessionPool 的构造器，用于配置和创建 ITableSessionPool 的实 | **配置项** | **描述** | **默认值** | | ------------------------------------------------------------ | -------------------------------------------- | ------------------------------------------- | -| nodeUrls(List`` nodeUrls) | 设置IoTDB集群的节点URL列表 | Collections.singletonList("localhost:6667") | +| nodeUrls(List`` nodeUrls) | 设置 IoTDB 集群的节点 URL 列表；IPv6 endpoint 使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:6667`。IPv6 自 V2.0.12 起支持。 | Collections.singletonList("localhost:6667") | | maxSize(int maxSize) | 设置会话池的最大大小，即池中允许的最大会话数 | 5 | | user(String user) | 设置连接的用户名 | "root" | | password(String password) | 设置连接的密码 | "root" | @@ -948,4 +950,6 @@ public class TableModelSessionPoolExample { } } } + +若第 5 章示例需要连接 IPv6 节点，`LOCAL_URL` 的值可使用 `[ipv6]:port`；原示例的地址和初始化代码均不必替换。 ``` \ No newline at end of file diff --git a/src/zh/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md b/src/zh/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md index dd527d31c..8bbd43517 100644 --- a/src/zh/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md +++ b/src/zh/UserGuide/Master/Table/API/Programming-Python-Native-API_apache.md @@ -137,7 +137,7 @@ TableSessionConfig是一个配置类，用于设置和创建TableSession 实例 | **配置项** | **描述** | **类型** | **默认值** | | ------------------ | ------------------------- | -------- | ----------------------- | -| node_urls | 数据库连接的节点 URL 列表 | list | ["localhost:6667"] | +| node_urls | 数据库连接的节点 URL 列表；IPv6 endpoint 使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:6667`。IPv6 自 V2.0.12 起支持。 | list | ["localhost:6667"] | | username | 数据库连接用户名 | str | "root" | | password | 数据库连接密码 | str | "root" | | database | 要连接的目标数据库 | str | None | @@ -145,6 +145,8 @@ TableSessionConfig是一个配置类，用于设置和创建TableSession 实例 | time_zone | 会话的默认时区 | str | Session.DEFAULT_ZONE_ID | | enable_compression | 是否启用数据压缩 | bool | False | +自 V2.0.12 起，表模型 `node_urls` 支持 IPv6 endpoint。表格示意值中的 `DN_IPV6_ADDRESS` 是待填写的 DataNode 地址，原默认值与示例保留。`TableSession`/`TableSessionPool` 分开接收 host 和 port 时，host 使用裸 IPv6；node URL 列表使用 `[ipv6]:port`。 + #### 2.2.3 接口展示 ```Python @@ -244,7 +246,7 @@ TableSessionPoolConfig是一个配置类，用于设置和创建 TableSessionPoo | **配置项** | **描述** | **类型** | **默认值** | | ------------------ | ------------------------------ | -------- | ------------------------ | -| node_urls | 数据库连接的节点 URL 列表 | list | None | +| node_urls | 数据库连接的节点 URL 列表；IPv6 endpoint 使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:6667`。IPv6 自 V2.0.12 起支持。 | list | None | | max_pool_size | 会话池中的最大会话数 | int | 5 | | username | 数据库连接用户名 | str | Session.DEFAULT_USER | | password | 数据库连接密码 | str | Session.DEFAULT_PASSWORD | @@ -403,6 +405,8 @@ if __name__ == "__main__": df = get_data() ``` +IPv6 SSL 连接中的 host 使用裸 IPv6。`ca_certs` 指定的 CA 必须能够验证服务端证书，且服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`。如果 SAN 不包含该地址，TLS 主机身份校验将失败。 + ## 4. 示例代码 Session示例代码:[Session Example](https://github.com/apache/iotdb/blob/master/iotdb-client/client-py/table_model_session_example.py) @@ -576,4 +580,3 @@ delete_data() session_pool.close() print("example is finished!") ``` - diff --git a/src/zh/UserGuide/Master/Table/Deployment-and-Maintenance/AINode_Deployment_apache.md b/src/zh/UserGuide/Master/Table/Deployment-and-Maintenance/AINode_Deployment_apache.md index 211e499d2..f61fa0c56 100644 --- a/src/zh/UserGuide/Master/Table/Deployment-and-Maintenance/AINode_Deployment_apache.md +++ b/src/zh/UserGuide/Master/Table/Deployment-and-Maintenance/AINode_Deployment_apache.md @@ -106,23 +106,32 @@ python3 --version ``` ### 3.2 配置项修改 + AINode 支持修改一些必要的参数。可以在 `conf/iotdb-ainode.properties` 文件中找到下列参数并进行持久化的修改： | **名称** | **描述** | **类型** | **默认值** | | ------------------------------ | ------------------------------------------------------------ | -------- | ------------------ | | cluster_name | AINode 要加入集群的标识 | string | defaultCluster | -| ain_seed_config_node | AINode 启动时注册的 ConfigNode 地址 | String | 127.0.0.1:10710 | -| ain_cluster_ingress_address | AINode 拉取数据的 DataNode 的 rpc 地址 | String | 127.0.0.1 | +| ain_seed_config_node | AINode 启动时注册的 ConfigNode endpoint。支持 `ipv4:port`、`hostname:port` 或 `[ipv6]:port`，例如 `[CN_IPV6_ADDRESS]:10710`。IPv6 自 V2.0.12 起支持。 | String | 127.0.0.1:10710 | +| ain_cluster_ingress_address | AINode 拉取数据的 DataNode RPC 地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 | String | 127.0.0.1 | | ain_cluster_ingress_port | AINode 拉取数据的 DataNode 的 rpc 端口 | Integer | 6667 | | ain_cluster_ingress_username | AINode 拉取数据的 DataNode 的客户端用户名 | String | root | | ain_cluster_ingress_password | AINode 拉取数据的 DataNode 的客户端密码 | String | root | | ain_cluster_ingress_time_zone | AINode 拉取数据的 DataNode 的客户端时区 | String | UTC+8 | -| ain_inference_rpc_address | AINode 提供服务与通信的地址 ，内部服务通讯接口 | String | 127.0.0.1 | +| ain_inference_rpc_address | AINode 提供服务与内部通信的地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 | String | 127.0.0.1 | | ain_inference_rpc_port | AINode 提供服务与通信的端口 | String | 10810 | | ain_system_dir | AINode 元数据存储路径，相对路径的起始目录与操作系统相关，建议使用绝对路径 | String | data/AINode/system | | ain_models_dir | AINode 存储模型文件的路径，相对路径的起始目录与操作系统相关，建议使用绝对路径 | String | data/AINode/models | | ain_thrift_compression_enabled | AINode 是否启用 thrift 的压缩机制，0-不启动、1-启动 | Boolean | 0 | +```properties +ain_seed_config_node=[CN_IPV6_ADDRESS]:10710 +ain_cluster_ingress_address=DN_IPV6_ADDRESS +ain_inference_rpc_address=AINODE_IPV6_ADDRESS +``` + +`ain_seed_config_node` 同时包含地址和端口，因此 IPv6 使用 `[ipv6]:port`；`ain_cluster_ingress_address` 和 `ain_inference_rpc_address` 只填写地址，使用裸 IPv6。示例中的 `CN_IPV6_ADDRESS`、`DN_IPV6_ADDRESS` 和 `AINODE_IPV6_ADDRESS` 分别表示 ConfigNode、DataNode 和 AINode 实际可达的地址，应用配置前须替换。AINode 启动后应确认已注册到 ConfigNode，并能够访问 DataNode。 + ### 3.3 导入权重文件 > 仅离线环境，在线环境可忽略本步骤 diff --git a/src/zh/UserGuide/Master/Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md b/src/zh/UserGuide/Master/Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md index efb60ba20..925381d73 100644 --- a/src/zh/UserGuide/Master/Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md +++ b/src/zh/UserGuide/Master/Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md @@ -53,6 +53,8 @@ 6. 在安装部署数据库前，可以使用健康检查工具检测 IoTDB 节点运行环境，并获取详细的检查结果。 IoTDB 健康检查工具使用方法可以参考：[健康检查工具](../Tools-System/Health-Check-Tool.md)。 +使用 IPv4/IPv6 双栈或纯 IPv6 网络部署时，请在启动前确认：操作系统已启用 IPv6，配置的地址已分配到对应网卡并可被服务绑定；ConfigNode、DataNode 和 AINode 之间的 IPv6 路由可达，相关 RPC、共识和客户端端口已在防火墙中放行；使用 hostname 时，各节点的 DNS 或 `/etc/hosts` 解析结果一致。`0.0.0.0` 和 `::` 仅用于监听全部接口，不能作为节点注册、节点发现、客户端重定向或其他远端连接目标。 + ## 2. 准备步骤 1. 准备IoTDB数据库安装包 ：apache-iotdb-{version}-all-bin.zip（安装包获取见：[链接](../Deployment-and-Maintenance/IoTDB-Package_apache.md)） @@ -145,23 +147,33 @@ cd apache-iotdb-{version}-all-bin | 配置项 | 说明 | 默认 | 推荐值 | 11.101.17.224 | 11.101.17.225 | 11.101.17.226 | 备注 | | ------------------- | ------------------------------------------------------------ | --------------- | ------------------------------------------------------- | ------------- | ------------- | ------------- | ------------------ | -| cn_internal_address | ConfigNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | +| cn_internal_address | ConfigNode 在集群内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | | cn_internal_port | ConfigNode在集群内部通讯使用的端口 | 10710 | 10710 | 10710 | 10710 | 10710 | 首次启动后不能修改 | | cn_consensus_port | ConfigNode副本组共识协议通信使用的端口 | 10720 | 10720 | 10720 | 10720 | 10720 | 首次启动后不能修改 | -| cn_seed_config_node | 节点注册加入集群时连接的ConfigNode 的地址，cn_internal_address:cn_internal_port | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | +| cn_seed_config_node | 节点注册加入集群时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | #### 3.2.4 DataNode 配置 | 配置项 | 说明 | 默认 | 推荐值 | 11.101.17.224 | 11.101.17.225 | 11.101.17.226 | 备注 | | ------------------------------- | ------------------------------------------------------------ | --------------- | ------------------------------------------------------- | ------------- | ------------- | ------------- | ------------------ | -| dn_rpc_address | 客户端 RPC 服务的地址 | 127.0.0.1 | 默认本机可直接访问。非本机访问，请修改此配置项为所在服务器的IPV4地址或hostname，推荐使用所在服务器的IPV4地址。 | iotdb-1 |iotdb-2 | iotdb-3 | 重启服务生效 | +| dn_rpc_address | 客户端 RPC 服务监听地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 默认仅本机可访问；非本机访问时填写实际可路由的 IPv4 地址、裸 IPv6 地址或 hostname | iotdb-1 |iotdb-2 | iotdb-3 | 重启服务生效 | | dn_rpc_port | 客户端 RPC 服务的端口 | 6667 | 6667 | 6667 | 6667 | 6667 | 重启服务生效 | -| dn_internal_address | DataNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | +| dn_internal_address | DataNode 在集群内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | | dn_internal_port | DataNode在集群内部通信使用的端口 | 10730 | 10730 | 10730 | 10730 | 10730 | 首次启动后不能修改 | | dn_mpp_data_exchange_port | DataNode用于接收数据流使用的端口 | 10740 | 10740 | 10740 | 10740 | 10740 | 首次启动后不能修改 | | dn_data_region_consensus_port | DataNode用于数据副本共识协议通信使用的端口 | 10750 | 10750 | 10750 | 10750 | 10750 | 首次启动后不能修改 | | dn_schema_region_consensus_port | DataNode用于元数据副本共识协议通信使用的端口 | 10760 | 10760 | 10760 | 10760 | 10760 | 首次启动后不能修改 | -| dn_seed_config_node | 节点注册加入集群时连接的ConfigNode地址,即cn_internal_address:cn_internal_port | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | +| dn_seed_config_node | 节点注册加入集群时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | + +```properties +cn_internal_address=CN_IPV6_ADDRESS +cn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +dn_internal_address=DN_IPV6_ADDRESS +dn_rpc_address=DN_IPV6_ADDRESS +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +``` + +表模型示例中的 `CN_IPV6_ADDRESS` 和 `DN_IPV6_ADDRESS` 也仅表示对应节点的 IPv6 地址填写位置，实际部署前须替换为已绑定且网络可达的地址。 > ❗️注意：VSCode Remote等编辑器无自动保存配置功能，请确保修改的文件被持久化保存，否则配置项无法生效 @@ -201,6 +213,8 @@ cd sbin .\windows\start-datanode.bat ``` +启动完成后，通过 CLI 执行 `show cluster` 检查 ConfigNode 和 DataNode 是否均已注册。纯 IPv6 环境中，节点地址字段应显示配置的裸 IPv6；日志或错误信息中同时包含地址和端口时，应显示为 `[ipv6]:port`。如果发现 `::` 被返回为节点地址，请将对外发布地址改为实际可路由的 IPv6 地址。 + ### 3.5 启动 CLI 表模型 CLI 进入命令： @@ -217,6 +231,12 @@ cd sbin .\windows\start-cli-table.bat ``` +IPv6 地址通过 `-h` 单独传入时不使用方括号，端口通过 `-p` 传入，例如： + +```shell +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' -sql_dialect table +``` + ### 3.6 一键启停集群 #### 3.6.1 概述 @@ -494,4 +514,3 @@ remove datanode [datanode_id] | -D | 定义系统属性，格式为 key=value | 否 | | -X | 直接传递 -XX 参数给 JVM | 否 | | -h | 帮助指令 | 否 | - diff --git a/src/zh/UserGuide/Master/Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md b/src/zh/UserGuide/Master/Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md index 35df6803b..6ea27c2be 100644 --- a/src/zh/UserGuide/Master/Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md +++ b/src/zh/UserGuide/Master/Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md @@ -112,23 +112,35 @@ ConfigNode 配置 | **配置项** | **说明** | **默认** | 推荐值 | **备注** | | :------------------ | :----------------------------------------------------------- | :-------------- | :----------------------------------------------- | :----------------- | -| cn_internal_address | ConfigNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | 首次启动后不能修改 | +| cn_internal_address | ConfigNode 在集群内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | 首次启动后不能修改 | | cn_internal_port | ConfigNode在集群内部通讯使用的端口 | 10710 | 10710 | 首次启动后不能修改 | | cn_consensus_port | ConfigNode副本组共识协议通信使用的端口 | 10720 | 10720 | 首次启动后不能修改 | -| cn_seed_config_node | 节点注册加入集群时连接的ConfigNode 的地址，cn_internal_address:cn_internal_port | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | +| cn_seed_config_node | 节点注册时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | DataNode 配置 | **配置项** | **说明** | **默认** | 推荐值 | **备注** | | :------------------------------ | :----------------------------------------------------------- | :-------------- |:----------------------------------------| :----------------- | -| dn_rpc_address | 客户端 RPC 服务的地址 | 127.0.0.1 | 默认本机可直接访问。非本机访问，请修改此配置项为所在服务器的IPV4地址或hostname，推荐使用所在服务器的IPV4地址。 | 重启服务生效 | +| dn_rpc_address | 客户端 RPC 服务监听地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 默认仅本机可访问；非本机访问时填写实际可路由的 IPv4 地址、裸 IPv6 地址或 hostname | 重启服务生效 | | dn_rpc_port | 客户端 RPC 服务的端口 | 6667 | 6667 | 重启服务生效 | -| dn_internal_address | DataNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | 首次启动后不能修改 | +| dn_internal_address | DataNode 在集群内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | 首次启动后不能修改 | | dn_internal_port | DataNode在集群内部通信使用的端口 | 10730 | 10730 | 首次启动后不能修改 | | dn_mpp_data_exchange_port | DataNode用于接收数据流使用的端口 | 10740 | 10740 | 首次启动后不能修改 | | dn_data_region_consensus_port | DataNode用于数据副本共识协议通信使用的端口 | 10750 | 10750 | 首次启动后不能修改 | | dn_schema_region_consensus_port | DataNode用于元数据副本共识协议通信使用的端口 | 10760 | 10760 | 首次启动后不能修改 | -| dn_seed_config_node | 节点注册加入集群时连接的ConfigNode地址,即cn_internal_address:cn_internal_port | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | +| dn_seed_config_node | 节点注册时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | + +仅在本机访问的单机实例可使用 IPv6 回环地址： + +```properties +cn_internal_address=::1 +cn_seed_config_node=[::1]:10710 +dn_internal_address=::1 +dn_rpc_address=::1 +dn_seed_config_node=[::1]:10710 +``` + +`::1` 是 IPv6 回环地址，只适用于本机访问或测试。需要由其他主机访问时，请改用本机实际可路由的 IPv6 地址。`::` 表示监听全部 IPv6 接口，不能作为远程连接目标、节点发现结果或客户端重定向地址。 ### 2.4 Edge 版启动与停止 @@ -261,4 +273,3 @@ DataNode 配置 | -D | 定义系统属性，格式为 key=value | 否 | | -X | 直接传递 -XX 参数给 JVM | 否 | | -h | 帮助指令 | 否 | - diff --git a/src/zh/UserGuide/Master/Table/FAQ/Frequently-asked-questions.md b/src/zh/UserGuide/Master/Table/FAQ/Frequently-asked-questions.md index 06eb3f261..9df8df192 100644 --- a/src/zh/UserGuide/Master/Table/FAQ/Frequently-asked-questions.md +++ b/src/zh/UserGuide/Master/Table/FAQ/Frequently-asked-questions.md @@ -285,3 +285,33 @@ sudo ln -sf $(which lsof) /bin/lsof # 自动创建软链接至标准路径 - 在conf/confignode-env.sh、conf/datanode-env.sh文件可通过调整ON_HEAP_MEMORY、OFF_HEAP_MEMORY等选项可以调整ConfigNode、DataNode使用的最大堆内、堆外内存 + +## 3. IPv6 连接 FAQ + +### 3.1 为什么 `[::1]:6667` 合法，而 `::1:6667` 不应作为 endpoint 使用？ + +自 V2.0.12 起，IoTDB 支持 IPv6 连接。IPv6 地址本身包含多个冒号。地址与端口组合时必须使用 `[ipv6]:port`，这样才能明确区分地址和端口。JDBC URL、Session node URL 和 Pipe `node-urls` 中的地址与端口部分应使用 `[ipv6]:port`。 + +### 3.2 为什么地址参数使用裸 IPv6，而 JDBC 和 Pipe 使用 `[ipv6]:port`？ + +`cn_internal_address`、`dn_internal_address`、`dn_rpc_address` 等参数只填写地址，因此使用裸 IPv6；JDBC URL、seed endpoint、Session node URL 和 Pipe `node-urls` 同时包含地址和端口，因此使用 `[ipv6]:port`。 + +### 3.3 为什么服务监听 `::` 成功，但客户端仍然无法连接？ + +`::` 表示监听全部 IPv6 接口，不是可路由的远端地址。节点注册、节点发现、客户端重定向、Pipe 目标和 Prometheus target 均应使用实际可达的 IPv6 地址。 + +### 3.4 IPv6 TLS 连接提示证书主机名或 IP 校验失败怎么办？ + +检查服务端证书 SAN 是否包含客户端实际访问的裸 IPv6 `IP Address`。SAN 中不能包含方括号或端口；同时确认客户端 TrustStore 包含签发该证书的 CA。 + +### 3.5 纯 IPv6 环境连接失败如何排查？ + +依次检查操作系统 IPv6 是否启用、地址是否已绑定、节点间路由和端口是否可达、防火墙是否放行、DNS 或 `/etc/hosts` 解析是否一致，以及客户端运行时和底层 socket 是否支持 IPv6。 + +### 3.6 双栈环境中 IPv4 可用、IPv6 连接失败怎么办？ + +先使用实际的 IPv6 地址与端口按当前入口要求的格式直接连接，确认目标服务已绑定 IPv6 地址，路由和防火墙允许该端口访问；再检查 DNS 的 AAAA 记录或 `/etc/hosts` 中的 IPv6 映射是否指向目标地址。分别验证 IPv4 与 IPv6 链路，不要将 IPv4 连接成功当作 IPv6 已连通；节点对外发布地址不能使用 `::`。 + +### 3.7 Pipe 报 IPv6 endpoint 解析错误怎么办？ + +检查每个 IPv6 endpoint 是否使用 `[ipv6]:port`，多个 endpoint 是否使用英文逗号分隔，是否误将 `::` 或 `0.0.0.0` 作为目标。SSL Pipe 还需检查 TrustStore、KeyStore 和目标证书 SAN。 diff --git a/src/zh/UserGuide/Master/Table/Reference/System-Config-Manual_apache.md b/src/zh/UserGuide/Master/Table/Reference/System-Config-Manual_apache.md index 80f842a42..10d157b65 100644 --- a/src/zh/UserGuide/Master/Table/Reference/System-Config-Manual_apache.md +++ b/src/zh/UserGuide/Master/Table/Reference/System-Config-Manual_apache.md @@ -121,11 +121,15 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 ### 3.2 SeedConfigNode 配置 +> 只填写地址的参数使用裸 IPv6；同时包含地址和端口的 endpoint 使用 `[ipv6]:port`。 + +下文的 `CN_IPV6_ADDRESS` 仅用于标示 ConfigNode 的 IPv6 地址填写位置；实际配置时应填写可解析、可路由的地址。原有 IPv4/主机名示例及默认值保持不变。 + - cn_seed_config_node | 名字 | cn_seed_config_node | | ------------ | ------------------------------------------------------------ | -| 描述 | 目标 ConfigNode 地址，ConfigNode 通过此地址加入集群，推荐使用 SeedConfigNode。V1.2.2 及以前曾用名是 cn_target_config_node_list | +| 描述 | 目标 ConfigNode 的 endpoint，ConfigNode 通过此地址加入集群，推荐使用 SeedConfigNode。支持 `ipv4:port`、`hostname:port` 或 `[ipv6]:port`，例如 `[CN_IPV6_ADDRESS]:10710`。V1.2.2 及以前曾用名是 cn_target_config_node_list。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1:10710 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | @@ -134,7 +138,7 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | dn_seed_config_node | | ------------ | ------------------------------------------------------------ | -| 描述 | ConfigNode 地址，DataNode 启动时通过此地址加入集群，推荐使用 SeedConfigNode。V1.2.2 及以前曾用名是 dn_target_config_node_list | +| 描述 | ConfigNode 的 endpoint，DataNode 启动时通过此地址加入集群，推荐使用 SeedConfigNode。支持 `ipv4:port`、`hostname:port` 或 `[ipv6]:port`，例如 `[CN_IPV6_ADDRESS]:10710`。V1.2.2 及以前曾用名是 dn_target_config_node_list。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1:10710 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | @@ -145,7 +149,7 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | cn_internal_address | | ------------ | ---------------------------- | -| 描述 | ConfigNode 集群内部地址 | +| 描述 | ConfigNode 集群内部通信地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口，不使用方括号，例如 `192.168.1.10`、`CN_IPV6_ADDRESS` 或 `iotdb-cn-1`。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | @@ -172,7 +176,7 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | dn_rpc_address | | ------------ |----------------| -| 描述 | 客户端 RPC 服务监听地址 | +| 描述 | 客户端 RPC 服务监听地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口，不使用方括号，例如 `192.168.1.20`、`DN_IPV6_ADDRESS` 或 `iotdb-dn-1`。使用 `::` 可监听全部 IPv6 接口，但 `::` 不能作为客户端重定向或节点发现返回的远端连接地址。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1 | | 改后生效方式 | 重启服务生效 | @@ -190,11 +194,15 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | dn_internal_address | | ------------ | ---------------------------- | -| 描述 | DataNode 内网通信地址 | +| 描述 | DataNode 内部通信地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口，不使用方括号，例如 `192.168.1.20`、`DN_IPV6_ADDRESS` 或 `iotdb-dn-1`。IPv6 自 V2.0.12 起支持。 | | 类型 | string | | 默认值 | 127.0.0.1 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | +> 当地址参数只填写 IPv6 地址时，应使用裸 IPv6，例如 `DN_IPV6_ADDRESS`；当地址和端口组合为 endpoint 时，应使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:10730`。`0.0.0.0` 和 `::` 仅用于监听全部接口，不能作为远端连接目标。 + +下文的 `DN_IPV6_ADDRESS` 仅用于标示 DataNode 的 IPv6 地址填写位置，实际配置时应替换为相应节点已绑定且可达的地址。 + - dn_internal_port | 名字 | dn_internal_port | @@ -500,6 +508,8 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 ### 3.7 SSL 配置 +> IPv6 不改变现有 SSL/TLS 开关、协议、KeyStore 和 TrustStore 配置。通过 IPv6 地址访问 DataNode 并启用主机身份校验时，服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`，不包含方括号和端口。例如，客户端连接 `[DN_IPV6_ADDRESS]:6667` 时，证书 SAN 中应包含 `DN_IPV6_ADDRESS`。 + - enable_thrift_ssl | 名字 | enable_thrift_ssl | diff --git a/src/zh/UserGuide/Master/Table/Tools-System/CLI_apache.md b/src/zh/UserGuide/Master/Table/Tools-System/CLI_apache.md index 37ab9452d..5e8b688a9 100644 --- a/src/zh/UserGuide/Master/Table/Tools-System/CLI_apache.md +++ b/src/zh/UserGuide/Master/Table/Tools-System/CLI_apache.md @@ -58,11 +58,21 @@ Shell> sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -sql_dia - -u 和-pw 是 IoTDB 登录的用户名密码（安装后IoTDB有一个默认用户，用户名为`root`,密码为`root`） - -sql_dialect 是登录的数据模型（表模型或树模型），此处指定为 table 代表进入表模型模式 +自 V2.0.12 起，IPv6 地址通过 `-h` 单独传入时使用裸地址，不加方括号；端口通过 `-p` 单独传入。示例中的 `DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前应替换为实际可达的 IPv6 地址；原 IPv4 启动示例保留。例如： + +```shell +# Linux/macOS +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' -sql_dialect table + +# Windows（V2.0.4.x 及之后） +sbin\windows\start-cli.bat -h DN_IPV6_ADDRESS -p 6667 -u root -pw "" -sql_dialect table +``` + 更多参数见： | **参数名** | **参数类型** | **是否为必需参数** | **说明** | **示例** | |:-----------------------------|:-----------|:------------|:-----------------------------------------------------------|:---------------------| -| -h `` | string 类型 | 否 | IoTDB 客户端连接 IoTDB 服务器的 IP 地址， 默认使用：127.0.0.1。 | -h 127.0.0.1 | +| -h `` | string 类型 | 否 | IoTDB 服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号，自 V2.0.12 起支持。 | -h 127.0.0.1 | | -p `` | int 类型 | 否 | IoTDB 客户端连接服务器的端口号，IoTDB 默认使用 6667。 | -p 6667 | | -u `` | string 类型 | 否 | IoTDB 客户端连接服务器所使用的用户名，默认使用 root。 | -u root | | -pw `` | string 类型 | 否 | IoTDB 客户端连接服务器所使用的密码，默认使用 root。 | -pw root | diff --git a/src/zh/UserGuide/Master/Table/Tools-System/Data-Export-Tool_apache.md b/src/zh/UserGuide/Master/Table/Tools-System/Data-Export-Tool_apache.md index 688ce13f3..beef69017 100644 --- a/src/zh/UserGuide/Master/Table/Tools-System/Data-Export-Tool_apache.md +++ b/src/zh/UserGuide/Master/Table/Tools-System/Data-Export-Tool_apache.md @@ -40,7 +40,7 @@ IoTDB 支持两种方式进行数据导出： | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | |--------------|------------------------| ----------------------------------------------------------------- | -------------- |---------------------------------------------------------------------------| | -ft | --file\_type | 导出文件的类型，可以选择：csv、sql、tsfile | √ | | -| -h | -- host | 主机名 | 否 | 127.0.0.1 | +| -h | -- host | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | -p | --port | 端口号 | 否 | 6667 | | -u | --username | 用户名 | 否 | root | | -pw | --password | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -58,6 +58,8 @@ IoTDB 支持两种方式进行数据导出： | -ts | --trust_store | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | -tpw | --trust_store_password | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。`DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前须替换为实际可达的裸 IPv6；不要把带方括号的地址作为 `-h` 的值。启用 SSL 时，继续使用本页现有的 `-usessl`、`-ts` 和 `-tpw` 参数；服务端证书 SAN 必须包含实际访问的裸 IPv6 地址。 + ### 2.2 CSV 格式 #### 2.2.1 运行命令 diff --git a/src/zh/UserGuide/Master/Table/Tools-System/Data-Import-Tool_apache.md b/src/zh/UserGuide/Master/Table/Tools-System/Data-Import-Tool_apache.md index 508a05d99..6dbff733b 100644 --- a/src/zh/UserGuide/Master/Table/Tools-System/Data-Import-Tool_apache.md +++ b/src/zh/UserGuide/Master/Table/Tools-System/Data-Import-Tool_apache.md @@ -46,7 +46,7 @@ IoTDB 支持三种方式进行数据导入： | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | |--------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------| -------------- |----------------------------------| | -ft | --file\_type | 导入文件的类型，可以选择：csv、sql、tsfile | √ | -| -h | -- host | 主机名 | 否 | 127.0.0.1 | +| -h | -- host | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | -p | --port | 端口号 | 否 | 6667 | | -u | --username | 用户名 | 否 | root | | -pw | --password | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -60,6 +60,8 @@ IoTDB 支持三种方式进行数据导入： | -usessl | --use_ssl | 使用 SSL 协议，自 V2.0.10 起支持 | 否 | - | | -ts | --trust_store | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | -tpw | --trust_store_password | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。`DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前须替换为实际可达的裸 IPv6；不要把带方括号的地址作为 `-h` 的值。启用 SSL 时，继续使用本页现有的 `-usessl`、`-ts` 和 `-tpw` 参数；服务端证书 SAN 必须包含实际访问的裸 IPv6 地址。 + ### 2.2 CSV 格式 diff --git a/src/zh/UserGuide/Master/Table/Tools-System/Monitor-Tool_apache.md b/src/zh/UserGuide/Master/Table/Tools-System/Monitor-Tool_apache.md index ae9294857..f10aaa5d0 100644 --- a/src/zh/UserGuide/Master/Table/Tools-System/Monitor-Tool_apache.md +++ b/src/zh/UserGuide/Master/Table/Tools-System/Monitor-Tool_apache.md @@ -60,6 +60,12 @@ file_count{name="seq",} 2.0 ... ``` +自 V2.0.12 起，监控 metrics 接口支持通过 IPv6 地址访问。访问 IPv6 metrics URL 时，地址和端口之间应使用方括号区分；将下方占位符替换为实际可达的 IPv6 地址： + +```shell +curl 'http://[IPV6_ADDRESS]:9091/metrics' +``` + ## 3. Prometheus + Grafana 如上所示，IoTDB 对外暴露出标准的 Prometheus 格式的监控指标数据，可以使用 Prometheus 采集并存储监控指标，使用 Grafana @@ -90,6 +96,7 @@ follow_redirects: true static_configs: - targets: - localhost:9091 + - '[IPV6_ADDRESS]:9091' ``` 更多细节可以参考下面的文档： @@ -101,3 +108,4 @@ static_configs: [Grafana安装使用文档](https://grafana.com/docs/grafana/latest/getting-started/getting-started/) [Grafana从Prometheus查询数据并绘图的文档](https://prometheus.io/docs/visualization/grafana/#grafana-support-for-prometheus) +Prometheus target 同时包含 IPv6 地址和端口，应使用 `[ipv6]:port`。即使服务监听地址配置为 `::`，target 也应填写实际可路由的 IPv6 地址，不能填写 `[::]:9091`。 diff --git a/src/zh/UserGuide/Master/Table/Tools-System/Schema-Export-Tool_apache.md b/src/zh/UserGuide/Master/Table/Tools-System/Schema-Export-Tool_apache.md index 17462344e..2346ae472 100644 --- a/src/zh/UserGuide/Master/Table/Tools-System/Schema-Export-Tool_apache.md +++ b/src/zh/UserGuide/Master/Table/Tools-System/Schema-Export-Tool_apache.md @@ -31,7 +31,7 @@ | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | |----------------|----------------------------|-----------------------------------------------| ----------------------------------- |---------------------------------------| -| `-h` | `-- host` | 主机名 | 否 | 127.0.0.1 | +| `-h` | `-- host` | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | `-p` | `--port` | 端口号 | 否 | 6667 | | `-u` | `--username` | 用户名 | 否 | root | | `-pw` | `--password` | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -48,6 +48,8 @@ | `-ts` | `--trust_store` | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | `-tpw` | `--trust_store_password` | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。运行前将 `DN_IPV6_ADDRESS` 替换为实际可达的 DataNode IPv6 地址。启用 SSL 时沿用原参数，并确保证书 SAN 包含实际访问的 IPv6 地址。 + ### 2.2 运行命令 ```Bash @@ -109,3 +111,5 @@ CREATE TABLE table2( arrival_time TIMESTAMP FIELD ); ``` + +自 V2.0.12 起，`-h` 可填写实际的裸 IPv6 地址，`-p` 继续单独传入端口；其他导出参数无需为 IPv6 改动。 diff --git a/src/zh/UserGuide/Master/Table/Tools-System/Schema-Import-Tool_apache.md b/src/zh/UserGuide/Master/Table/Tools-System/Schema-Import-Tool_apache.md index 451f82733..2303f831c 100644 --- a/src/zh/UserGuide/Master/Table/Tools-System/Schema-Import-Tool_apache.md +++ b/src/zh/UserGuide/Master/Table/Tools-System/Schema-Import-Tool_apache.md @@ -31,7 +31,7 @@ | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | | --------------------- | ------------------------------- |------------------------------------------------| -------------- |-----------------------------------| -| `-h` | `-- host` | 主机名 | 否 | 127.0.0.1 | +| `-h` | `-- host` | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | `-p` | `--port` | 端口号 | 否 | 6667 | | `-u` | `--username` | 用户名 | 否 | root | | `-pw` | `--password` | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -46,6 +46,8 @@ | `-ts` | `--trust_store` | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | `-tpw` | `--trust_store_password` | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。运行前将 `DN_IPV6_ADDRESS` 替换为实际可达的 DataNode IPv6 地址。启用 SSL 时沿用原参数，并确保证书 SAN 包含实际访问的 IPv6 地址。 + ### 2.2 运行命令 ```Bash @@ -164,3 +166,5 @@ IoTDB:database2> desc table2 |arrival_time|TIMESTAMP| FIELD| +------------+---------+---------+ ``` + +自 V2.0.12 起，`-h` 可填写实际的裸 IPv6 地址，`-p` 继续单独传入端口；其他导入参数无需为 IPv6 改动。 diff --git a/src/zh/UserGuide/Master/Table/User-Manual/Data-Sync_apache.md b/src/zh/UserGuide/Master/Table/User-Manual/Data-Sync_apache.md index 262ef66f7..a4f4bdbfd 100644 --- a/src/zh/UserGuide/Master/Table/User-Manual/Data-Sync_apache.md +++ b/src/zh/UserGuide/Master/Table/User-Manual/Data-Sync_apache.md @@ -338,6 +338,16 @@ with sink ( ) ``` +```sql +create pipe A2B_IPV6 +with sink ( + 'sink'='iotdb-thrift-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667' +) +``` + +自 V2.0.12 起，Pipe 支持使用 IPv6 endpoint 连接目标端 IoTDB。`node-urls` 同时包含地址和端口，IPv6 使用 `[ipv6]:port`；多个 endpoint 使用英文逗号分隔。上方独立示例中的 `DN_IPV6_ADDRESS` 和 `DN_IPV6_ADDRESS_2` 分别表示目标端两个 DataNode 的实际可达 IPv6 地址，使用前须替换；原有 Pipe 示例不变。 + ### 3.2 部分数据同步 本例子用来演示同步某个历史时间范围（ 2023 年 8 月 23 日 8 点到 2023 年 10 月 23 日 8 点）的数据至另一个 IoTDB，数据链路如下图所示： @@ -499,6 +509,18 @@ with sink ( - `ssl.trust-store-path`: 连接目标端 DataNode 所需的 trust store 证书路径 - `ssl.trust-store-pwd`: 连接目标端 DataNode 所需的 trust store 证书密码 +```sql +create pipe A2B_SSL_IPV6 +with sink ( + 'sink'='iotdb-thrift-ssl-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667', + 'ssl.trust-store-path'='pki/trusted', + 'ssl.trust-store-pwd'='' +) +``` + +通过 IPv6 地址进行 TLS 主机身份校验时，目标 DataNode 的服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`，不包含方括号和端口。 + ## 参考：注意事项 可通过修改 IoTDB 配置文件（`iotdb-system.properties`）以调整数据同步的参数，如同步数据存储目录等。完整配置如下：： @@ -591,7 +613,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **参数** | **描述** | **value 取值范围** | **是否必填** | **默认取值** | |--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|----------|--------------| | sink | iotdb-thrift-sink 或 iotdb-thrift-async-sink | String: iotdb-thrift-sink 或 iotdb-thrift-async-sink | 必填 | - | -| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务端口的 url（请注意同步任务不支持向自身服务进行转发） | String. 例：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | 必填 | - | +| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务 endpoint（同步任务不支持向自身服务转发）。IPv6 使用 `[ipv6]:port`，多个 endpoint 使用英文逗号分隔。IPv6 自 V2.0.12 起支持。 | String。示例：`'127.0.0.1:6667,127.0.0.1:6668'`、`'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | 必填 | - | | user/username | 连接接收端使用的用户名，同步要求该用户具备相应的操作权限 | String | 选填 | root | | password | 连接接收端使用的用户名对应的密码，同步要求该用户具备相应的操作权限 | String | 选填 | root | | batch.enable | 是否开启日志攒批发送模式，用于提高传输吞吐，降低 IOPS | Boolean: true, false | 选填 | true | @@ -611,7 +633,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **参数** | **描述** | **value 取值范围** | **是否必填** | **默认取值** | |--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| -------- | ------------ | | sink | iotdb-thrift-ssl-sink | String: iotdb-thrift-ssl-sink | 必填 | - | -| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务端口的 url（请注意同步任务不支持向自身服务进行转发） | String. 例：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | 必填 | - | +| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务 endpoint（同步任务不支持向自身服务转发）。IPv6 使用 `[ipv6]:port`，多个 endpoint 使用英文逗号分隔；目标证书 SAN 必须覆盖实际连接地址。IPv6 自 V2.0.12 起支持。 | String。示例：`'127.0.0.1:6667,127.0.0.1:6668'`、`'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | 必填 | - | | user/username | 连接接收端使用的用户名，同步要求该用户具备相应的操作权限 | String | 选填 | root | | password | 连接接收端使用的用户名对应的密码，同步要求该用户具备相应的操作权限 | String | 选填 | root | | batch.enable | 是否开启日志攒批发送模式，用于提高传输吞吐，降低 IOPS | Boolean: true, false | 选填 | true | diff --git a/src/zh/UserGuide/Master/Table/User-Manual/Load-Balance_apache.md b/src/zh/UserGuide/Master/Table/User-Manual/Load-Balance_apache.md index 0580404da..cbae6dd68 100644 --- a/src/zh/UserGuide/Master/Table/User-Manual/Load-Balance_apache.md +++ b/src/zh/UserGuide/Master/Table/User-Manual/Load-Balance_apache.md @@ -116,6 +116,8 @@ IoTDB 集群扩容的核心是增加 DataNode 节点，因为 DataNode 是处理 echo "192.168.1.3 iotdb-1" >> /etc/hosts ``` +7. IPv6 网络检查：使用双栈或纯 IPv6 网络扩容时，确认新旧节点之间的 IPv6 路由和所需端口可达，DNS 或 `/etc/hosts` 解析一致，配置的 IPv6 地址已绑定到对应网卡。`0.0.0.0` 和 `::` 仅用于监听，不能作为新节点注册到集群时使用的远端地址。 + #### 2.2.2 扩容操作 1. 为确保您获取的 IoTDB 安装包完整且正确，在执行安装部署前建议您进行 SHA512 校验。 @@ -136,15 +138,25 @@ vim iotdb-system.properies |配置项|说明|默认|备注| |---|---|---|---| -|dn\_seed\_config\_node|节点注册加入集群时连接的 ConfigNode 地址,即 cn\_internal\_address:cn\_internal\_port|127\.0\.0\.1:10710
|非常重要，强制修改此项，将其改为原集群 ConfigNode 主节点的地址
| -|dn\_rpc\_address|客户端 RPC 服务的地址|0\.0\.0\.0|按需修改，重启服务生效| +|dn\_seed\_config\_node| 节点注册加入集群时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`。IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 |127\.0\.0\.1:10710
|非常重要，强制修改此项，将其改为原集群 ConfigNode 主节点的地址
| +|dn\_rpc\_address| 客户端 RPC 服务监听地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 |0\.0\.0\.0|按需修改，重启服务生效| |dn\_rpc\_port|客户端 RPC 服务的端口|6667|按需修改，重启服务生效| -|dn\_internal\_address|DataNode 在集群内部通讯使用的地址|127\.0\.0\.1|按需修改，首次启动后不能修改| +|dn\_internal\_address| DataNode 集群内部通信地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 |127\.0\.0\.1|按需修改，首次启动后不能修改| |dn\_internal\_port|DataNode 在集群内部通信使用的端口|10730|按需修改，首次启动后不能修改| |dn\_mpp\_data\_exchange\_port|DataNode 用于接收数据流使用的端口|10740|按需修改，首次启动后不能修改| |dn\_data\_region\_consensus\_port|DataNode 用于数据副本共识协议通信使用的端口|10750|按需修改，首次启动后不能修改| |dn\_schema\_region\_consensus\_port|DataNode 用于元数据副本共识协议通信使用的端口|10760|按需修改，首次启动后不能修改| +纯 IPv6 扩容示例： + +```properties +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +dn_rpc_address=NEW_DN_IPV6_ADDRESS +dn_internal_address=NEW_DN_IPV6_ADDRESS +``` + +其中 `CN_IPV6_ADDRESS` 为原集群 ConfigNode 的可达 IPv6 地址，`NEW_DN_IPV6_ADDRESS` 为新节点已绑定且可路由的 IPv6 地址；应用配置前须替换。新节点启动后执行 `show datanodes`，确认新节点状态为 `Running`，地址字段显示配置的裸 IPv6。若返回 `::`，应将对外发布地址改为实际可路由的 IPv6 地址。 + 4. 启动 DataNode 节点 进入 IoTDB 的 sbin 目录下，启动 Datanode： diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-Cpp-Native-API.md b/src/zh/UserGuide/Master/Tree/API/Programming-Cpp-Native-API.md index ace2fe347..e0c4d9242 100644 --- a/src/zh/UserGuide/Master/Tree/API/Programming-Cpp-Native-API.md +++ b/src/zh/UserGuide/Master/Tree/API/Programming-Cpp-Native-API.md @@ -191,6 +191,8 @@ void open(bool enableRPCCompression); void close(); ``` +自 V2.0.12 起，C++ Session 支持使用 IPv6 地址连接 IoTDB。使用 IPv6 地址初始化客户端时，如果接口分别接收 host 和 port，host 使用裸 IPv6，port 单独传入；如果接口接收 node URL，则使用 `[ipv6]:port`。示意写法中的 `DN_IPV6_ADDRESS` 仅表示待填写的目标 DataNode 地址，使用前须替换为实际可达的 IPv6 地址。客户端获取节点列表或处理重定向时，不应将 `0.0.0.0`、`::` 或其等价表示作为远端连接目标。启用 SSL 时，服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`。 + ### 3.2 数据定义接口（DDL） #### Database 管理 diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-JDBC_apache.md b/src/zh/UserGuide/Master/Tree/API/Programming-JDBC_apache.md index 09f93865b..b0a8f01ae 100644 --- a/src/zh/UserGuide/Master/Tree/API/Programming-JDBC_apache.md +++ b/src/zh/UserGuide/Master/Tree/API/Programming-JDBC_apache.md @@ -291,4 +291,13 @@ public class JDBCCharsetExample { } } } + +```java +// 自 V2.0.12 起，IPv6 URL 的地址与端口使用 [ipv6]:port +// String ipv6Url = "jdbc:iotdb://[IPV6_ADDRESS]:6667/"; +// SSL 连接沿用原有参数： +// String ipv6SslUrl = "jdbc:iotdb://[IPV6_ADDRESS]:6667?use_ssl=true"; +``` + +JDBC URL 同时包含地址和端口，IPv6 格式为 `jdbc:iotdb://[ipv6]:port/`，不能省去地址两侧的方括号。注释示例中的 `IPV6_ADDRESS` 是地址占位符，应替换为实际可达的 IPv6 地址；原有 IPv4 URL 保留。启用 SSL 时沿用原连接参数，服务端证书 SAN 须包含实际访问的裸 IPv6 `IP Address`。 ``` \ No newline at end of file diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-Java-Native-API_apache.md b/src/zh/UserGuide/Master/Tree/API/Programming-Java-Native-API_apache.md index 9230fdd92..cda76df69 100644 --- a/src/zh/UserGuide/Master/Tree/API/Programming-Java-Native-API_apache.md +++ b/src/zh/UserGuide/Master/Tree/API/Programming-Java-Native-API_apache.md @@ -73,7 +73,14 @@ public class IoTDBSessionPoolExample { .build(); } } -``` +``` + +```java +// IPv6 node URL 同时包含地址和端口： +// nodeUrls.add("[IPV6_ADDRESS]:6667"); +``` + +自 V2.0.12 起，Java Session 和 SessionPool 支持使用 IPv6 地址连接 IoTDB。`nodeUrls` 中的每个元素都是地址与端口组合，IPv6 使用 `[ipv6]:port`；注释中的 `IPV6_ADDRESS` 仅表示待填写的实际节点地址，原有 `nodeUrls.add` 保留。如果 API 分别接收 host 和 port，host 使用裸 IPv6，port 单独传入。连接池重试与节点刷新使用同一 endpoint 规则。 ### 2.3 执行数据库操作 @@ -494,7 +501,7 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式 | 字段名 | 类型 | 说明 | | -------------------------------- | ----------------------------------- | ---------------------------------------- | -| `nodeUrls` | `List` | 数据库节点的 URL 列表，支持多节点连接 | +| `nodeUrls` | `List` | 数据库节点的 URL 列表，支持多节点连接；IPv6 endpoint 使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:6667`。IPv6 自 V2.0.12 起支持。 | | `username` | `String` | 用户名 | | `password` | `String` | 密码 | | `fetchSize` | `int` | 查询结果的默认批量返回大小 | @@ -620,6 +627,3 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式 | `getBackupConfiguration()` | 获取备份配置信息 | 无参数 | | `fetchAllConnections()` | 获取所有活动的连接信息 | 无参数 | | `getSystemStatus()` | 获取系统状态 | 已废弃，默认返回 `SystemStatus.NORMAL` | - - - diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md b/src/zh/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md index d29f2f00f..efb70cd5b 100644 --- a/src/zh/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md +++ b/src/zh/UserGuide/Master/Tree/API/Programming-Python-Native-API_apache.md @@ -99,6 +99,26 @@ session.open(enable_rpc_compression=False) ```python session.close() ``` + +```python +# host 和 port 分开传入时，host 使用裸 IPv6 +session = Session( + ip="DN_IPV6_ADDRESS", + port="6667", + user="root", + password="", +) + +# node URL 同时包含地址和端口时，IPv6 使用 [ipv6]:port +session = Session.init_from_node_urls( + node_urls=["[DN_IPV6_ADDRESS]:6667", "[DN_IPV6_ADDRESS_2]:6667"], + user="root", + password="", +) +``` + +自 V2.0.12 起，Python Session 和 SessionPool 支持使用 IPv6 地址连接 IoTDB。单独传入 `ip` 时使用裸 IPv6，不要将带方括号的地址传给底层 socket；`node_urls` 中的元素同时包含地址和端口，使用 `[ipv6]:port`。示例中的 `DN_IPV6_ADDRESS` 与 `DN_IPV6_ADDRESS_2` 是两个节点的地址占位符，使用前须替换为实际可达的 IPv6 地址。原 IPv4 示例保留。 + ### 3.2 通过SessionPool管理session连接 利用SessionPool管理session，不需要再考虑如何重用session。当session连接到达pool的最大值时，获取session的请求会被阻塞，可以通过参数设置阻塞等待时间。每次session使用完需要使用putBack方法将session归还到SessionPool中管理。 @@ -232,6 +252,8 @@ if __name__ == "__main__": df = get_data() ``` +IPv6 SSL 连接中的 host 使用裸 IPv6。`ca_certs` 指定的 CA 必须能够验证服务端证书，且服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`。如果 SAN 不包含该地址，TLS 主机身份校验将失败。 + ## 4. 数据定义接口 DDL ### 4.1 Database 管理 diff --git a/src/zh/UserGuide/Master/Tree/Deployment-and-Maintenance/AINode_Deployment_apache.md b/src/zh/UserGuide/Master/Tree/Deployment-and-Maintenance/AINode_Deployment_apache.md index ec1d7fe80..b2353b0d0 100644 --- a/src/zh/UserGuide/Master/Tree/Deployment-and-Maintenance/AINode_Deployment_apache.md +++ b/src/zh/UserGuide/Master/Tree/Deployment-and-Maintenance/AINode_Deployment_apache.md @@ -106,23 +106,32 @@ python3 --version ``` ### 3.2 配置项修改 + AINode 支持修改一些必要的参数。可以在 `conf/iotdb-ainode.properties` 文件中找到下列参数并进行持久化的修改： | **名称** | **描述** | **类型** | **默认值** | | ------------------------------ | ------------------------------------------------------------ | -------- | ------------------ | | cluster_name | AINode 要加入集群的标识 | string | defaultCluster | -| ain_seed_config_node | AINode 启动时注册的 ConfigNode 地址 | String | 127.0.0.1:10710 | -| ain_cluster_ingress_address | AINode 拉取数据的 DataNode 的 rpc 地址 | String | 127.0.0.1 | +| ain_seed_config_node | AINode 启动时注册的 ConfigNode endpoint。支持 `ipv4:port`、`hostname:port` 或 `[ipv6]:port`，例如 `[CN_IPV6_ADDRESS]:10710`。IPv6 自 V2.0.12 起支持。 | String | 127.0.0.1:10710 | +| ain_cluster_ingress_address | AINode 拉取数据的 DataNode RPC 地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 | String | 127.0.0.1 | | ain_cluster_ingress_port | AINode 拉取数据的 DataNode 的 rpc 端口 | Integer | 6667 | | ain_cluster_ingress_username | AINode 拉取数据的 DataNode 的客户端用户名 | String | root | | ain_cluster_ingress_password | AINode 拉取数据的 DataNode 的客户端密码 | String | root | | ain_cluster_ingress_time_zone | AINode 拉取数据的 DataNode 的客户端时区 | String | UTC+8 | -| ain_inference_rpc_address | AINode 提供服务与通信的地址 ，内部服务通讯接口 | String | 127.0.0.1 | +| ain_inference_rpc_address | AINode 提供服务与内部通信的地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 | String | 127.0.0.1 | | ain_inference_rpc_port | AINode 提供服务与通信的端口 | String | 10810 | | ain_system_dir | AINode 元数据存储路径，相对路径的起始目录与操作系统相关，建议使用绝对路径 | String | data/AINode/system | | ain_models_dir | AINode 存储模型文件的路径，相对路径的起始目录与操作系统相关，建议使用绝对路径 | String | data/AINode/models | | ain_thrift_compression_enabled | AINode 是否启用 thrift 的压缩机制，0-不启动、1-启动 | Boolean | 0 | +```properties +ain_seed_config_node=[CN_IPV6_ADDRESS]:10710 +ain_cluster_ingress_address=DN_IPV6_ADDRESS +ain_inference_rpc_address=AINODE_IPV6_ADDRESS +``` + +`ain_seed_config_node` 同时包含地址和端口，因此 IPv6 使用 `[ipv6]:port`；`ain_cluster_ingress_address` 和 `ain_inference_rpc_address` 只填写地址，使用裸 IPv6。示例中的 `CN_IPV6_ADDRESS`、`DN_IPV6_ADDRESS` 和 `AINODE_IPV6_ADDRESS` 分别表示 ConfigNode、DataNode 和 AINode 实际可达的地址，应用配置前须替换。AINode 启动后应确认已注册到 ConfigNode，并能够访问 DataNode。 + ### 3.3 导入权重文件 > 仅离线环境，在线环境可忽略本步骤 diff --git a/src/zh/UserGuide/Master/Tree/Deployment-and-Maintenance/Cluster-Deployment_apache.md b/src/zh/UserGuide/Master/Tree/Deployment-and-Maintenance/Cluster-Deployment_apache.md index 84a555776..58e5baf10 100644 --- a/src/zh/UserGuide/Master/Tree/Deployment-and-Maintenance/Cluster-Deployment_apache.md +++ b/src/zh/UserGuide/Master/Tree/Deployment-and-Maintenance/Cluster-Deployment_apache.md @@ -48,6 +48,8 @@ 6. 在安装部署数据库前，可以使用健康检查工具检测 IoTDB 节点运行环境，并获取详细的检查结果。 IoTDB 健康检查工具使用方法可以参考：[健康检查工具](../Tools-System/Health-Check-Tool.md)。 +使用 IPv4/IPv6 双栈或纯 IPv6 网络部署时，请在启动前确认：操作系统已启用 IPv6，配置的地址已分配到对应网卡并可被服务绑定；ConfigNode、DataNode 和 AINode 之间的 IPv6 路由可达，相关 RPC、共识和客户端端口已在防火墙中放行；使用 hostname 时，各节点的 DNS 或 `/etc/hosts` 解析结果一致。`0.0.0.0` 和 `::` 仅用于监听全部接口，不能作为节点注册、节点发现、客户端重定向或其他远端连接目标。 + ## 2. 准备步骤 1. 准备IoTDB数据库安装包 ：apache-iotdb-{version}-all-bin.zip（安装包获取见：[链接](../Deployment-and-Maintenance/IoTDB-Package_apache.md)） @@ -142,10 +144,10 @@ cd apache-iotdb-{version}-all-bin | 配置项 | 说明 | 默认 | 推荐值 | 192.168.1.3 | 192.168.1.4 | 192.168.1.5 | 备注 | | ------------------- | ------------------------------------------------------------ | --------------- | ------------------------------------------------------- | ------------- | ------------- | ------------- | ------------------ | -| cn_internal_address | ConfigNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | +| cn_internal_address | ConfigNode 在集群内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | | cn_internal_port | ConfigNode在集群内部通讯使用的端口 | 10710 | 10710 | 10710 | 10710 | 10710 | 首次启动后不能修改 | | cn_consensus_port | ConfigNode副本组共识协议通信使用的端口 | 10720 | 10720 | 10720 | 10720 | 10720 | 首次启动后不能修改 | -| cn_seed_config_node | 节点注册加入集群时连接的ConfigNode 的地址，cn_internal_address:cn_internal_port | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | +| cn_seed_config_node | 节点注册加入集群时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | #### DataNode 配置 @@ -153,14 +155,31 @@ cd apache-iotdb-{version}-all-bin | 配置项 | 说明 | 默认 | 推荐值 | 192.168.1.3 | 192.168.1.4 | 192.168.1.5 | 备注 | | ------------------------------- | ------------------------------------------------------------ | --------------- | ------------------------------------------------------- | ------------- | ------------- | ------------- | ------------------ | -| dn_rpc_address | 客户端 RPC 服务的地址 | 127.0.0.1 | 默认本机可直接访问。非本机访问，请修改此配置项为所在服务器的IPV4地址或hostname，推荐使用所在服务器的IPV4地址。 | iotdb-1 |iotdb-2 | iotdb-3 | 重启服务生效 | +| dn_rpc_address | 客户端 RPC 服务监听地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 默认仅本机可访问；非本机访问时填写所在服务器可路由的 IPv4 地址、裸 IPv6 地址或 hostname | iotdb-1 |iotdb-2 | iotdb-3 | 重启服务生效 | | dn_rpc_port | 客户端 RPC 服务的端口 | 6667 | 6667 | 6667 | 6667 | 6667 | 重启服务生效 | -| dn_internal_address | DataNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | +| dn_internal_address | DataNode 在集群内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | | dn_internal_port | DataNode在集群内部通信使用的端口 | 10730 | 10730 | 10730 | 10730 | 10730 | 首次启动后不能修改 | | dn_mpp_data_exchange_port | DataNode用于接收数据流使用的端口 | 10740 | 10740 | 10740 | 10740 | 10740 | 首次启动后不能修改 | | dn_data_region_consensus_port | DataNode用于数据副本共识协议通信使用的端口 | 10750 | 10750 | 10750 | 10750 | 10750 | 首次启动后不能修改 | | dn_schema_region_consensus_port | DataNode用于元数据副本共识协议通信使用的端口 | 10760 | 10760 | 10760 | 10760 | 10760 | 首次启动后不能修改 | -| dn_seed_config_node | 节点注册加入集群时连接的ConfigNode地址,即cn_internal_address:cn_internal_port | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | +| dn_seed_config_node | 节点注册加入集群时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | + +以下示例在保留原有 IPv4/主机名配置示例的基础上，展示一台 ConfigNode 和一台 DataNode 的纯 IPv6 地址写法。`CN_IPV6_ADDRESS` 与 `DN_IPV6_ADDRESS` 分别表示两台节点实际可达的 IPv6 地址，部署时须按实际环境替换： + +```properties +# ConfigNode +cn_internal_address=CN_IPV6_ADDRESS +cn_seed_config_node=[CN_IPV6_ADDRESS]:10710 + +# DataNode +dn_internal_address=DN_IPV6_ADDRESS +dn_rpc_address=DN_IPV6_ADDRESS +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +``` + +`cn_internal_address`、`dn_internal_address` 和 `dn_rpc_address` 只填写地址，因此使用裸 IPv6。`cn_seed_config_node` 和 `dn_seed_config_node` 同时包含地址和端口，因此使用 `[ipv6]:port`。 + +节点启动后，应确认 DataNode 已成功注册到 ConfigNode。集群展示中的 IP 字段可以显示裸 IPv6；日志、错误信息和其他带端口的 endpoint 应显示为 `[ipv6]:port`。如果服务监听地址为 `::`，节点对外发布时仍必须使用实际可路由的 IPv6 地址。 > ❗️注意：VSCode Remote等编辑器无自动保存配置功能，请确保修改的文件被持久化保存，否则配置项无法生效 @@ -199,6 +218,8 @@ cd sbin .\windows\start-datanode.bat ``` +启动完成后，通过 CLI 执行 `show cluster` 检查 ConfigNode 和 DataNode 是否均已注册。纯 IPv6 环境中，节点地址字段应显示配置的裸 IPv6；日志或错误信息中同时包含地址和端口时，应显示为 `[ipv6]:port`。如果发现 `::` 被返回为节点地址，请将对外发布地址改为实际可路由的 IPv6 地址。 + ### 3.5 验证部署 可直接执行`./sbin`目录下的Cli启动脚本： @@ -213,6 +234,12 @@ cd sbin # V2.0.4.x 版本及之后 .\windows\start-cli.bat -h ip -p 6667 +``` + +IPv6 地址通过 `-h` 单独传入时不使用方括号，端口通过 `-p` 传入，例如： + +```shell +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' ``` 成功启动后，出现如下界面显示IOTDB安装成功。 diff --git a/src/zh/UserGuide/Master/Tree/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md b/src/zh/UserGuide/Master/Tree/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md index c8ecb4a08..1679a2448 100644 --- a/src/zh/UserGuide/Master/Tree/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md +++ b/src/zh/UserGuide/Master/Tree/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md @@ -112,10 +112,10 @@ cd apache-iotdb-{version}-all-bin | **配置项** | **说明** | **默认** | 推荐值 | **备注** | | :-----------------: | :----------------------------------------------------------: | :-------------: | :----------------------------------------------: | :----------------: | -| cn_internal_address | ConfigNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | 首次启动后不能修改 | +| cn_internal_address | ConfigNode 在内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | 首次启动后不能修改 | | cn_internal_port | ConfigNode在集群内部通讯使用的端口 | 10710 | 10710 | 首次启动后不能修改 | | cn_consensus_port | ConfigNode副本组共识协议通信使用的端口 | 10720 | 10720 | 首次启动后不能修改 | -| cn_seed_config_node | 节点注册加入集群时连接的ConfigNode 的地址，cn_internal_address:cn_internal_port | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | +| cn_seed_config_node | 节点注册时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | #### DataNode 配置 @@ -123,14 +123,26 @@ cd apache-iotdb-{version}-all-bin | **配置项** | **说明** | **默认** | 推荐值 | **备注** | | :-----------------------------: | :----------------------------------------------------------: |:---------------:|:----------------------------------------------------------------------------:| :----------------- | -| dn_rpc_address | 客户端 RPC 服务的地址 | 127.0.0.1 | 默认本机可直接访问。非本机访问，请修改此配置项为所在服务器的IPV4地址或hostname，推荐使用所在服务器的IPV4地址。 | 重启服务生效 | +| dn_rpc_address | 客户端 RPC 服务监听地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 默认仅本机可访问；非本机访问时填写实际可路由的 IPv4 地址、裸 IPv6 地址或 hostname | 重启服务生效 | | dn_rpc_port | 客户端 RPC 服务的端口 | 6667 | 6667 | 重启服务生效 | -| dn_internal_address | DataNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | 首次启动后不能修改 | +| dn_internal_address | DataNode 在内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | 首次启动后不能修改 | | dn_internal_port | DataNode在集群内部通信使用的端口 | 10730 | 10730 | 首次启动后不能修改 | | dn_mpp_data_exchange_port | DataNode用于接收数据流使用的端口 | 10740 | 10740 | 首次启动后不能修改 | | dn_data_region_consensus_port | DataNode用于数据副本共识协议通信使用的端口 | 10750 | 10750 | 首次启动后不能修改 | | dn_schema_region_consensus_port | DataNode用于元数据副本共识协议通信使用的端口 | 10760 | 10760 | 首次启动后不能修改 | -| dn_seed_config_node | 节点注册加入集群时连接的ConfigNode地址,即cn_internal_address:cn_internal_port | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | +| dn_seed_config_node | 节点注册时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | + +仅在本机访问的单机实例可使用 IPv6 回环地址： + +```properties +cn_internal_address=::1 +cn_seed_config_node=[::1]:10710 +dn_internal_address=::1 +dn_rpc_address=::1 +dn_seed_config_node=[::1]:10710 +``` + +`::1` 是 IPv6 回环地址，只适用于本机访问或测试。需要由其他主机访问时，请改用本机实际可路由的 IPv6 地址。`::` 表示监听全部 IPv6 接口，不能作为远程连接目标、节点发现结果或客户端重定向地址。 > ❗️注意：VSCode Remote等编辑器无自动保存配置功能，请确保修改的文件被持久化保存，否则配置项无法生效 diff --git a/src/zh/UserGuide/Master/Tree/FAQ/Frequently-asked-questions.md b/src/zh/UserGuide/Master/Tree/FAQ/Frequently-asked-questions.md index f2c453202..88883b7d4 100644 --- a/src/zh/UserGuide/Master/Tree/FAQ/Frequently-asked-questions.md +++ b/src/zh/UserGuide/Master/Tree/FAQ/Frequently-asked-questions.md @@ -332,3 +332,33 @@ sudo ln -sf $(which lsof) /bin/lsof # 自动创建软链接至标准路径 - 在conf/confignode-env.sh、conf/datanode-env.sh文件可通过调整ON_HEAP_MEMORY、OFF_HEAP_MEMORY等选项可以调整ConfigNode、DataNode使用的最大堆内、堆外内存 + +## 3. IPv6 连接 FAQ + +### 3.1 为什么 `[::1]:6667` 合法，而 `::1:6667` 不应作为 endpoint 使用？ + +自 V2.0.12 起，IoTDB 支持 IPv6 连接。IPv6 地址本身包含多个冒号。地址与端口组合时必须使用 `[ipv6]:port`，这样才能明确区分地址和端口。JDBC URL、Session node URL 和 Pipe `node-urls` 中的地址与端口部分应使用 `[ipv6]:port`。 + +### 3.2 为什么地址参数使用裸 IPv6，而 JDBC 和 Pipe 使用 `[ipv6]:port`？ + +`cn_internal_address`、`dn_internal_address`、`dn_rpc_address` 等参数只填写地址，因此使用裸 IPv6；JDBC URL、seed endpoint、Session node URL 和 Pipe `node-urls` 同时包含地址和端口，因此使用 `[ipv6]:port`。 + +### 3.3 为什么服务监听 `::` 成功，但客户端仍然无法连接？ + +`::` 表示监听全部 IPv6 接口，不是可路由的远端地址。节点注册、节点发现、客户端重定向、Pipe 目标和 Prometheus target 均应使用实际可达的 IPv6 地址。 + +### 3.4 IPv6 TLS 连接提示证书主机名或 IP 校验失败怎么办？ + +检查服务端证书 SAN 是否包含客户端实际访问的裸 IPv6 `IP Address`。SAN 中不能包含方括号或端口；同时确认客户端 TrustStore 包含签发该证书的 CA。 + +### 3.5 纯 IPv6 环境连接失败如何排查？ + +依次检查操作系统 IPv6 是否启用、地址是否已绑定、节点间路由和端口是否可达、防火墙是否放行、DNS 或 `/etc/hosts` 解析是否一致，以及客户端运行时和底层 socket 是否支持 IPv6。 + +### 3.6 双栈环境中 IPv4 可用、IPv6 连接失败怎么办？ + +先使用实际的 IPv6 地址与端口按当前入口要求的格式直接连接，确认目标服务已绑定 IPv6 地址，路由和防火墙允许该端口访问；再检查 DNS 的 AAAA 记录或 `/etc/hosts` 中的 IPv6 映射是否指向目标地址。分别验证 IPv4 与 IPv6 链路，不要将 IPv4 连接成功当作 IPv6 已连通；节点对外发布地址不能使用 `::`。 + +### 3.7 Pipe 报 IPv6 endpoint 解析错误怎么办？ + +检查每个 IPv6 endpoint 是否使用 `[ipv6]:port`，多个 endpoint 是否使用英文逗号分隔，是否误将 `::` 或 `0.0.0.0` 作为目标。SSL Pipe 还需检查 TrustStore、KeyStore 和目标证书 SAN。 diff --git a/src/zh/UserGuide/Master/Tree/Reference/System-Config-Manual_apache.md b/src/zh/UserGuide/Master/Tree/Reference/System-Config-Manual_apache.md index 01d5a7e7b..20c30ecbb 100644 --- a/src/zh/UserGuide/Master/Tree/Reference/System-Config-Manual_apache.md +++ b/src/zh/UserGuide/Master/Tree/Reference/System-Config-Manual_apache.md @@ -121,11 +121,15 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 ### 3.2 SeedConfigNode 配置 +> 只填写地址的参数使用裸 IPv6；同时包含地址和端口的 endpoint 使用 `[ipv6]:port`。 + +下文的 `CN_IPV6_ADDRESS` 仅用于标示 ConfigNode 的 IPv6 地址填写位置；实际配置时应填写可解析、可路由的地址。原有 IPv4/主机名示例及默认值保持不变。 + - cn_seed_config_node | 名字 | cn_seed_config_node | | ------------ | ------------------------------------------------------------ | -| 描述 | 目标 ConfigNode 地址，ConfigNode 通过此地址加入集群，推荐使用 SeedConfigNode。V1.2.2 及以前曾用名是 cn_target_config_node_list | +| 描述 | 目标 ConfigNode 的 endpoint，ConfigNode 通过此地址加入集群，推荐使用 SeedConfigNode。支持 `ipv4:port`、`hostname:port` 或 `[ipv6]:port`，例如 `[CN_IPV6_ADDRESS]:10710`。V1.2.2 及以前曾用名是 cn_target_config_node_list。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1:10710 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | @@ -134,7 +138,7 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | dn_seed_config_node | | ------------ | ------------------------------------------------------------ | -| 描述 | ConfigNode 地址，DataNode 启动时通过此地址加入集群，推荐使用 SeedConfigNode。V1.2.2 及以前曾用名是 dn_target_config_node_list | +| 描述 | ConfigNode 的 endpoint，DataNode 启动时通过此地址加入集群，推荐使用 SeedConfigNode。支持 `ipv4:port`、`hostname:port` 或 `[ipv6]:port`，例如 `[CN_IPV6_ADDRESS]:10710`。V1.2.2 及以前曾用名是 dn_target_config_node_list。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1:10710 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | @@ -145,7 +149,7 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | cn_internal_address | | ------------ | ---------------------------- | -| 描述 | ConfigNode 集群内部地址 | +| 描述 | ConfigNode 集群内部通信地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口，不使用方括号，例如 `192.168.1.10`、`CN_IPV6_ADDRESS` 或 `iotdb-cn-1`。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | @@ -172,7 +176,7 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | dn_rpc_address | | ------------ |----------------| -| 描述 | 客户端 RPC 服务监听地址 | +| 描述 | 客户端 RPC 服务监听地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口，不使用方括号，例如 `192.168.1.20`、`DN_IPV6_ADDRESS` 或 `iotdb-dn-1`。使用 `::` 可监听全部 IPv6 接口，但 `::` 不能作为客户端重定向或节点发现返回的远端连接地址。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1 | | 改后生效方式 | 重启服务生效 | @@ -190,11 +194,15 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | dn_internal_address | | ------------ | ---------------------------- | -| 描述 | DataNode 内网通信地址 | +| 描述 | DataNode 内部通信地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口，不使用方括号，例如 `192.168.1.20`、`DN_IPV6_ADDRESS` 或 `iotdb-dn-1`。IPv6 自 V2.0.12 起支持。 | | 类型 | string | | 默认值 | 127.0.0.1 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | +> 当地址参数只填写 IPv6 地址时，应使用裸 IPv6，例如 `DN_IPV6_ADDRESS`；当地址和端口组合为 endpoint 时，应使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:10730`。`0.0.0.0` 和 `::` 仅用于监听全部接口，不能作为远端连接目标。 + +下文的 `DN_IPV6_ADDRESS` 仅用于标示 DataNode 的 IPv6 地址填写位置，实际配置时应替换为相应节点已绑定且可达的地址。 + - dn_internal_port | 名字 | dn_internal_port | @@ -500,6 +508,8 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 ### 3.7 SSL 配置 +> IPv6 不改变现有 SSL/TLS 开关、协议、KeyStore 和 TrustStore 配置。通过 IPv6 地址访问 DataNode 并启用主机身份校验时，服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`，不包含方括号和端口。例如，客户端连接 `[DN_IPV6_ADDRESS]:6667` 时，证书 SAN 中应包含 `DN_IPV6_ADDRESS`。 + - enable_thrift_ssl | 名字 | enable_thrift_ssl | diff --git a/src/zh/UserGuide/Master/Tree/Tools-System/CLI_apache.md b/src/zh/UserGuide/Master/Tree/Tools-System/CLI_apache.md index 606db20a2..a32826147 100644 --- a/src/zh/UserGuide/Master/Tree/Tools-System/CLI_apache.md +++ b/src/zh/UserGuide/Master/Tree/Tools-System/CLI_apache.md @@ -69,11 +69,21 @@ Successfully login at 127.0.0.1:6667 ``` 输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 +自 V2.0.12 起，IPv6 地址通过 `-h` 单独传入时使用裸地址，不加方括号；端口通过 `-p` 单独传入。示例中的 `DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前应替换为实际可达的 IPv6 地址；原 IPv4 启动示例保留。例如： + +```shell +# Linux/macOS +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' + +# Windows（V2.0.4.x 及之后） +sbin\windows\start-cli.bat -h DN_IPV6_ADDRESS -p 6667 -u root -pw "" +``` + ### 2.2 Cli 运行参数 | **参数名** | **参数类型** | **是否为必需参数** | **说明** | **示例** | |:-----------------------------|:-----------|:------------|:-----------------------------------------------------------|:---------------------| -| -h `` | string 类型 | 否 | IoTDB 客户端连接 IoTDB 服务器的 IP 地址， 默认使用：127.0.0.1。 | -h 127.0.0.1 | +| -h `` | string 类型 | 否 | IoTDB 客户端连接服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号，默认使用 `127.0.0.1`。IPv6 自 V2.0.12 起支持。 | -h 127.0.0.1 | | -p `` | int 类型 | 否 | IoTDB 客户端连接服务器的端口号，IoTDB 默认使用 6667。 | -p 6667 | | -u `` | string 类型 | 否 | IoTDB 客户端连接服务器所使用的用户名，默认使用 root。 | -u root | | -pw `` | string 类型 | 否 | IoTDB 客户端连接服务器所使用的密码，默认使用 IoTDB@2021（V2.0.6版本之前为root）。 | -pw root | @@ -191,4 +201,3 @@ It costs 0.267s ``` 需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 - diff --git a/src/zh/UserGuide/Master/Tree/Tools-System/Data-Export-Tool_apache.md b/src/zh/UserGuide/Master/Tree/Tools-System/Data-Export-Tool_apache.md index 9181b7fbc..cbd65a2cc 100644 --- a/src/zh/UserGuide/Master/Tree/Tools-System/Data-Export-Tool_apache.md +++ b/src/zh/UserGuide/Master/Tree/Tools-System/Data-Export-Tool_apache.md @@ -34,7 +34,7 @@ | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | |----------|-------------------------|----------------------------------------------------| -------------- |---------------------------------------------------------------------------| | -ft | --file\_type | 导出文件的类型，可以选择：csv、sql、tsfile | √ | | -| -h | -- host | 主机名 | 否 | 127.0.0.1 | +| -h | -- host | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | -p | --port | 端口号 | 否 | 6667 | | -u | --username | 用户名 | 否 | root | | -pw | --password | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -47,6 +47,8 @@ | -ts | --trust_store | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | -tpw | --trust_store_password | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。`DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前须替换为实际可达的裸 IPv6；不要把带方括号的地址作为 `-h` 的值。启用 SSL 时，继续使用本页现有的 `-usessl`、`-ts` 和 `-tpw` 参数；服务端证书 SAN 必须包含实际访问的裸 IPv6 地址。 + ### 2.2 Csv 格式 #### 2.2.1 运行命令 diff --git a/src/zh/UserGuide/Master/Tree/Tools-System/Data-Import-Tool_apache.md b/src/zh/UserGuide/Master/Tree/Tools-System/Data-Import-Tool_apache.md index 9ebac05e5..845bda2bf 100644 --- a/src/zh/UserGuide/Master/Tree/Tools-System/Data-Import-Tool_apache.md +++ b/src/zh/UserGuide/Master/Tree/Tools-System/Data-Import-Tool_apache.md @@ -44,7 +44,7 @@ IoTDB 支持三种方式进行数据导入： | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | | ---------- |---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| -------------- |---------------------------| | -ft | --file\_type | 导入文件的类型，可以选择：csv、sql、tsfile | √ | -| -h | -- host | 主机名 | 否 | 127.0.0.1 | +| -h | -- host | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | -p | --port | 端口号 | 否 | 6667 | | -u | --username | 用户名 | 否 | root | | -pw | --password | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -56,6 +56,8 @@ IoTDB 支持三种方式进行数据导入： | -ts | --trust_store | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | -tpw | --trust_store_password | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。`DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前须替换为实际可达的裸 IPv6；不要把带方括号的地址作为 `-h` 的值。启用 SSL 时，继续使用本页现有的 `-usessl`、`-ts` 和 `-tpw` 参数；服务端证书 SAN 必须包含实际访问的裸 IPv6 地址。 + ### 2.2 CSV 格式 diff --git a/src/zh/UserGuide/Master/Tree/Tools-System/Monitor-Tool_apache.md b/src/zh/UserGuide/Master/Tree/Tools-System/Monitor-Tool_apache.md index 42211f004..ed57ae0c2 100644 --- a/src/zh/UserGuide/Master/Tree/Tools-System/Monitor-Tool_apache.md +++ b/src/zh/UserGuide/Master/Tree/Tools-System/Monitor-Tool_apache.md @@ -60,6 +60,12 @@ file_count{name="seq",} 2.0 ... ``` +自 V2.0.12 起，监控 metrics 接口支持通过 IPv6 地址访问。访问 IPv6 metrics URL 时，地址和端口之间应使用方括号区分；将下方占位符替换为实际可达的 IPv6 地址： + +```shell +curl 'http://[IPV6_ADDRESS]:9091/metrics' +``` + ## 3. Prometheus + Grafana 如上所示，IoTDB 对外暴露出标准的 Prometheus 格式的监控指标数据，可以使用 Prometheus 采集并存储监控指标，使用 Grafana @@ -90,6 +96,7 @@ follow_redirects: true static_configs: - targets: - localhost:9091 + - '[IPV6_ADDRESS]:9091' ``` 更多细节可以参考下面的文档： @@ -101,3 +108,4 @@ static_configs: [Grafana安装使用文档](https://grafana.com/docs/grafana/latest/getting-started/getting-started/) [Grafana从Prometheus查询数据并绘图的文档](https://prometheus.io/docs/visualization/grafana/#grafana-support-for-prometheus) +Prometheus target 同时包含 IPv6 地址和端口，应使用 `[ipv6]:port`。即使服务监听地址配置为 `::`，target 也应填写实际可路由的 IPv6 地址，不能填写 `[::]:9091`。 diff --git a/src/zh/UserGuide/Master/Tree/Tools-System/Schema-Export-Tool_apache.md b/src/zh/UserGuide/Master/Tree/Tools-System/Schema-Export-Tool_apache.md index 807951a13..b1492c90c 100644 --- a/src/zh/UserGuide/Master/Tree/Tools-System/Schema-Export-Tool_apache.md +++ b/src/zh/UserGuide/Master/Tree/Tools-System/Schema-Export-Tool_apache.md @@ -31,7 +31,7 @@ | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | | --------------------- |---------------------------| ------------------------------------------------------------------------ | ----------------------------------- |---------------------------------------| -| `-h` | `-- host` | 主机名 | 否 | 127.0.0.1 | +| `-h` | `-- host` | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | `-p` | `--port` | 端口号 | 否 | 6667 | | `-u` | `--username` | 用户名 | 否 | root | | `-pw` | `--password` | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -48,6 +48,8 @@ | `-ts` | `--trust_store` | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | `-tpw` | `--trust_store_password ` | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。运行前将 `DN_IPV6_ADDRESS` 替换为实际可达的 DataNode IPv6 地址。启用 SSL 时沿用原参数，并确保证书 SAN 包含实际访问的 IPv6 地址。 + ### 2.2 运行命令 ```Bash @@ -82,3 +84,5 @@ Timeseries,Alias,DataType,Encoding,Compression root.treedb.device.temperature,,DOUBLE,GORILLA,LZ4 root.treedb.device.humidity,,DOUBLE,GORILLA,LZ4 ``` + +自 V2.0.12 起，`-h` 可填写实际的裸 IPv6 地址，`-p` 继续单独传入端口；其他导出参数无需为 IPv6 改动。 diff --git a/src/zh/UserGuide/Master/Tree/Tools-System/Schema-Import-Tool_apache.md b/src/zh/UserGuide/Master/Tree/Tools-System/Schema-Import-Tool_apache.md index 8e73c3e89..ce82f80e6 100644 --- a/src/zh/UserGuide/Master/Tree/Tools-System/Schema-Import-Tool_apache.md +++ b/src/zh/UserGuide/Master/Tree/Tools-System/Schema-Import-Tool_apache.md @@ -31,7 +31,7 @@ | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | | --------------------- |-----------------------------| ----------------------------------------------------------------------------- | -------------- |-----------------------------------| -| `-h` | `-- host` | 主机名 | 否 | 127.0.0.1 | +| `-h` | `-- host` | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | `-p` | `--port` | 端口号 | 否 | 6667 | | `-u` | `--username` | 用户名 | 否 | root | | `-pw` | `--password` | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -46,6 +46,8 @@ | `-ts` | `--trust_store` | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | `-tpw` | `--trust_store_password` | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。运行前将 `DN_IPV6_ADDRESS` 替换为实际可达的 DataNode IPv6 地址。启用 SSL 时沿用原参数，并确保证书 SAN 包含实际访问的 IPv6 地址。 + ### 2.2 运行命令 ```Bash @@ -88,3 +90,5 @@ IoTDB> show timeseries root.treedb.** | root.treedb.device.humidity| null|root.treedb| DOUBLE| GORILLA| LZ4|null| null| null| null| BASE| +------------------------------+-----+-----------+--------+--------+-----------+----+----------+--------+------------------+--------+ ``` + +自 V2.0.12 起，`-h` 可填写实际的裸 IPv6 地址，`-p` 继续单独传入端口；其他导入参数无需为 IPv6 改动。 diff --git a/src/zh/UserGuide/Master/Tree/User-Manual/Data-Sync_apache.md b/src/zh/UserGuide/Master/Tree/User-Manual/Data-Sync_apache.md index 0da6bb54c..f7f2f54b0 100644 --- a/src/zh/UserGuide/Master/Tree/User-Manual/Data-Sync_apache.md +++ b/src/zh/UserGuide/Master/Tree/User-Manual/Data-Sync_apache.md @@ -372,6 +372,16 @@ with sink ( ) ``` +```sql +create pipe A2B_IPV6 +with sink ( + 'sink'='iotdb-thrift-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667' +) +``` + +自 V2.0.12 起，Pipe 支持使用 IPv6 endpoint 连接目标端 IoTDB。`node-urls` 同时包含地址和端口，IPv6 使用 `[ipv6]:port`；多个 endpoint 使用英文逗号分隔。上方独立示例中的 `DN_IPV6_ADDRESS` 和 `DN_IPV6_ADDRESS_2` 分别表示目标端两个 DataNode 的实际可达 IPv6 地址，使用前须替换；原有 Pipe 示例不变。 + ### 3.2 部分数据同步 本例子用来演示同步某个历史时间范围（ 2023 年 8 月 23 日 8 点到 2023 年 10 月 23 日 8 点）的数据至另一个 IoTDB，数据链路如下图所示： @@ -536,6 +546,18 @@ with sink ( - `ssl.trust-store-path`: 连接目标端 DataNode 所需的 trust store 证书路径 - `ssl.trust-store-pwd`: 连接目标端 DataNode 所需的 trust store 证书密码 +```sql +create pipe A2B_SSL_IPV6 +with sink ( + 'sink'='iotdb-thrift-ssl-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667', + 'ssl.trust-store-path'='pki/trusted', + 'ssl.trust-store-pwd'='' +) +``` + +通过 IPv6 地址进行 TLS 主机身份校验时，目标 DataNode 的服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`，不包含方括号和端口。 + ## 4. 参考：注意事项 可通过修改 IoTDB 配置文件（`iotdb-system.properties`）以调整数据同步的参数，如同步数据存储目录等。完整配置如下：： @@ -631,7 +653,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **参数** | **描述** | **value 取值范围** | **是否必填** | **默认取值** | |------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|----------|--------------| | sink | iotdb-thrift-sink 或 iotdb-thrift-async-sink | String: iotdb-thrift-sink 或 iotdb-thrift-async-sink | 必填 | - | -| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务端口的 url（请注意同步任务不支持向自身服务进行转发） | String. 例：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | 必填 | - | +| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务 endpoint（同步任务不支持向自身服务转发）。IPv6 使用 `[ipv6]:port`，多个 endpoint 使用英文逗号分隔。IPv6 自 V2.0.12 起支持。 | String。示例：`'127.0.0.1:6667,127.0.0.1:6668'`、`'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | 必填 | - | | user/username | 连接接收端使用的用户名，同步要求该用户具备相应的操作权限 | String | 选填 | root | | password | 连接接收端使用的用户名对应的密码，同步要求该用户具备相应的操作权限 | String | 选填 | root | | batch.enable | 是否开启日志攒批发送模式，用于提高传输吞吐，降低 IOPS | Boolean: true, false | 选填 | true | @@ -650,7 +672,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **参数** | **描述** | **value 取值范围** | **是否必填** | **默认取值** | |------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| -------- | ------------ | | sink | iotdb-thrift-ssl-sink | String: iotdb-thrift-ssl-sink | 必填 | - | -| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务端口的 url（请注意同步任务不支持向自身服务进行转发） | String. 例：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | 必填 | - | +| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务 endpoint（同步任务不支持向自身服务转发）。IPv6 使用 `[ipv6]:port`，多个 endpoint 使用英文逗号分隔；目标证书 SAN 必须覆盖实际连接地址。IPv6 自 V2.0.12 起支持。 | String。示例：`'127.0.0.1:6667,127.0.0.1:6668'`、`'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | 必填 | - | | user/username | 连接接收端使用的用户名，同步要求该用户具备相应的操作权限 | String | 选填 | root | | password | 连接接收端使用的用户名对应的密码，同步要求该用户具备相应的操作权限 | String | 选填 | root | | batch.enable | 是否开启日志攒批发送模式，用于提高传输吞吐，降低 IOPS | Boolean: true, false | 选填 | true | @@ -665,4 +687,3 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | ssl.trust-store-pwd | 连接目标端 DataNode 所需的 trust store 证书密码 | String: 'root' | 必填 | - | | format | 数据传输的payload格式， 可选项包括：
- hybrid： 取决于 processor 传递过来的格式（tsfile或tablet），sink不做任何转换。
- tsfile：强制转换成tsfile发送，可用于数据文件备份等场景。
- tablet：强制转换成tsfile发送，可用于发送端/接收端数据类型不完全兼容时的数据同步（以减少报错）。 | String: hybrid / tsfile / tablet | 选填 | hybrid | | exception.data.convert-on-type-mismatch | 接收端类型不同时是否转换 | Boolean: true / false | 选填 | true | - diff --git a/src/zh/UserGuide/Master/Tree/User-Manual/Load-Balance_apache.md b/src/zh/UserGuide/Master/Tree/User-Manual/Load-Balance_apache.md index 0580404da..cbae6dd68 100644 --- a/src/zh/UserGuide/Master/Tree/User-Manual/Load-Balance_apache.md +++ b/src/zh/UserGuide/Master/Tree/User-Manual/Load-Balance_apache.md @@ -116,6 +116,8 @@ IoTDB 集群扩容的核心是增加 DataNode 节点，因为 DataNode 是处理 echo "192.168.1.3 iotdb-1" >> /etc/hosts ``` +7. IPv6 网络检查：使用双栈或纯 IPv6 网络扩容时，确认新旧节点之间的 IPv6 路由和所需端口可达，DNS 或 `/etc/hosts` 解析一致，配置的 IPv6 地址已绑定到对应网卡。`0.0.0.0` 和 `::` 仅用于监听，不能作为新节点注册到集群时使用的远端地址。 + #### 2.2.2 扩容操作 1. 为确保您获取的 IoTDB 安装包完整且正确，在执行安装部署前建议您进行 SHA512 校验。 @@ -136,15 +138,25 @@ vim iotdb-system.properies |配置项|说明|默认|备注| |---|---|---|---| -|dn\_seed\_config\_node|节点注册加入集群时连接的 ConfigNode 地址,即 cn\_internal\_address:cn\_internal\_port|127\.0\.0\.1:10710
|非常重要，强制修改此项，将其改为原集群 ConfigNode 主节点的地址
| -|dn\_rpc\_address|客户端 RPC 服务的地址|0\.0\.0\.0|按需修改，重启服务生效| +|dn\_seed\_config\_node| 节点注册加入集群时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`。IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 |127\.0\.0\.1:10710
|非常重要，强制修改此项，将其改为原集群 ConfigNode 主节点的地址
| +|dn\_rpc\_address| 客户端 RPC 服务监听地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 |0\.0\.0\.0|按需修改，重启服务生效| |dn\_rpc\_port|客户端 RPC 服务的端口|6667|按需修改，重启服务生效| -|dn\_internal\_address|DataNode 在集群内部通讯使用的地址|127\.0\.0\.1|按需修改，首次启动后不能修改| +|dn\_internal\_address| DataNode 集群内部通信地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 |127\.0\.0\.1|按需修改，首次启动后不能修改| |dn\_internal\_port|DataNode 在集群内部通信使用的端口|10730|按需修改，首次启动后不能修改| |dn\_mpp\_data\_exchange\_port|DataNode 用于接收数据流使用的端口|10740|按需修改，首次启动后不能修改| |dn\_data\_region\_consensus\_port|DataNode 用于数据副本共识协议通信使用的端口|10750|按需修改，首次启动后不能修改| |dn\_schema\_region\_consensus\_port|DataNode 用于元数据副本共识协议通信使用的端口|10760|按需修改，首次启动后不能修改| +纯 IPv6 扩容示例： + +```properties +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +dn_rpc_address=NEW_DN_IPV6_ADDRESS +dn_internal_address=NEW_DN_IPV6_ADDRESS +``` + +其中 `CN_IPV6_ADDRESS` 为原集群 ConfigNode 的可达 IPv6 地址，`NEW_DN_IPV6_ADDRESS` 为新节点已绑定且可路由的 IPv6 地址；应用配置前须替换。新节点启动后执行 `show datanodes`，确认新节点状态为 `Running`，地址字段显示配置的裸 IPv6。若返回 `::`，应将对外发布地址改为实际可路由的 IPv6 地址。 + 4. 启动 DataNode 节点 进入 IoTDB 的 sbin 目录下，启动 Datanode： diff --git a/src/zh/UserGuide/latest-Table/API/Programming-Cpp-Native-API_apache.md b/src/zh/UserGuide/latest-Table/API/Programming-Cpp-Native-API_apache.md index 9e459f691..3b36b5c17 100644 --- a/src/zh/UserGuide/latest-Table/API/Programming-Cpp-Native-API_apache.md +++ b/src/zh/UserGuide/latest-Table/API/Programming-Cpp-Native-API_apache.md @@ -223,11 +223,13 @@ session = (new TableSessionBuilder()) ->build(); ``` +`host()` 也可传入裸 IPv6 地址，`rpcPort()` 仍单独设置端口。 + #### 3.2.2 可设置的参数列表 | **参数名** | **描述** | **默认值** | | :---: | :---: | :---: | -| host | 设置连接的节点IP | "127.0.0.1" ("localhost") | +| host | 设置连接的节点 IP，支持裸 IPv4、裸 IPv6 或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | "127.0.0.1" ("localhost") | | rpcPort | 设置连接的节点端口 | 6667 | | username | 设置连接的用户名 | "root" | | password | 设置连接密码 | "root" | diff --git a/src/zh/UserGuide/latest-Table/API/Programming-JDBC_apache.md b/src/zh/UserGuide/latest-Table/API/Programming-JDBC_apache.md index 8d476e258..3fac37fd3 100644 --- a/src/zh/UserGuide/latest-Table/API/Programming-JDBC_apache.md +++ b/src/zh/UserGuide/latest-Table/API/Programming-JDBC_apache.md @@ -190,3 +190,12 @@ public class TableModelJDBCExample { } } ``` + +```java +// IPv6 + Table 模型 +String url = "jdbc:iotdb://[DN_IPV6_ADDRESS]:6667?sql_dialect=table"; +// IPv6 + Table 模型 + SSL +String sslUrl = "jdbc:iotdb://[DN_IPV6_ADDRESS]:6667?sql_dialect=table&use_ssl=true"; +``` + +自 V2.0.12 起，表模型 JDBC URL 也可使用 `[ipv6]:port`；示例中的 `DN_IPV6_ADDRESS` 仅为 DataNode 地址占位符，使用前须替换为实际可达地址。通过 IPv6 地址启用 SSL 时，服务端证书 SAN 使用不带方括号和端口的裸 IPv6 地址。原有表模型 URL 示例继续保留。 diff --git a/src/zh/UserGuide/latest-Table/API/Programming-Java-Native-API_apache.md b/src/zh/UserGuide/latest-Table/API/Programming-Java-Native-API_apache.md index 82eb5bff4..f6556413c 100644 --- a/src/zh/UserGuide/latest-Table/API/Programming-Java-Native-API_apache.md +++ b/src/zh/UserGuide/latest-Table/API/Programming-Java-Native-API_apache.md @@ -154,7 +154,7 @@ TableSessionBuilder类是一个构建器，用于配置和创建ITableSession接 | **配置项** | **描述** | **默认值** | | ---------------------------------------------------- | ---------------------------------------- | ------------------------------------------- | -| nodeUrls(List`` nodeUrls) | 设置IoTDB集群的节点URL列表 | Collections.singletonList("localhost:6667") | +| nodeUrls(List`` nodeUrls) | 设置 IoTDB 集群的节点 URL 列表；IPv6 endpoint 使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:6667`。IPv6 自 V2.0.12 起支持。 | Collections.singletonList("localhost:6667") | | username(String username) | 设置连接的用户名 | "root" | | password(String password) | 设置连接的密码 | "TimechoDB@2021"（V2.0.6.x 之前默认密码是 root） | | database(String database) | 设置目标数据库名称 | null | @@ -185,6 +185,8 @@ TableSessionBuilder类是一个构建器，用于配置和创建ITableSession接 | withDateEncoding(TSEncoding tsEncoding) | 设置DATE类型的编码方式 | TSEncoding.TS_2DIFF | | connectionTimeoutInMs(int connectionTimeoutInMs) | 设置连接超时时间（毫秒） | 0（无超时） | +自 V2.0.12 起，表模型 `nodeUrls` 也支持 IPv6 endpoint。表格示意值中的 `DN_IPV6_ADDRESS` 为 DataNode 地址占位符，配置时替换为实际可达地址，原默认值不变。`TableSessionBuilder` 的 `host`/`rpcPort` 分开配置时，host 使用裸 IPv6；只有 node URL 字符串才使用方括号。 + #### 3.2.3 接口展示 ``` java @@ -524,7 +526,7 @@ TableSessionPool 的构造器，用于配置和创建 ITableSessionPool 的实 | **配置项** | **描述** | **默认值** | | ------------------------------------------------------------ | -------------------------------------------- | ------------------------------------------- | -| nodeUrls(List`` nodeUrls) | 设置IoTDB集群的节点URL列表 | Collections.singletonList("localhost:6667") | +| nodeUrls(List`` nodeUrls) | 设置 IoTDB 集群的节点 URL 列表；IPv6 endpoint 使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:6667`。IPv6 自 V2.0.12 起支持。 | Collections.singletonList("localhost:6667") | | maxSize(int maxSize) | 设置会话池的最大大小，即池中允许的最大会话数 | 5 | | user(String user) | 设置连接的用户名 | "root" | | password(String password) | 设置连接的密码 | "root" | @@ -949,3 +951,5 @@ public class TableModelSessionPoolExample { } } ``` + +若第 5 章示例需要连接 IPv6 节点，`LOCAL_URL` 的值可使用 `[ipv6]:port`；原示例的地址和初始化代码均不必替换。 diff --git a/src/zh/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md b/src/zh/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md index c2fe3336c..8fc8cfe90 100644 --- a/src/zh/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md +++ b/src/zh/UserGuide/latest-Table/API/Programming-Python-Native-API_apache.md @@ -137,7 +137,7 @@ TableSessionConfig是一个配置类，用于设置和创建TableSession 实例 | **配置项** | **描述** | **类型** | **默认值** | | ------------------ | ------------------------- | -------- | ----------------------- | -| node_urls | 数据库连接的节点 URL 列表 | list | ["localhost:6667"] | +| node_urls | 数据库连接的节点 URL 列表；IPv6 endpoint 使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:6667`。IPv6 自 V2.0.12 起支持。 | list | ["localhost:6667"] | | username | 数据库连接用户名 | str | "root" | | password | 数据库连接密码 | str | "root" | | database | 要连接的目标数据库 | str | None | @@ -145,6 +145,8 @@ TableSessionConfig是一个配置类，用于设置和创建TableSession 实例 | time_zone | 会话的默认时区 | str | Session.DEFAULT_ZONE_ID | | enable_compression | 是否启用数据压缩 | bool | False | +自 V2.0.12 起，表模型 `node_urls` 支持 IPv6 endpoint。表格示意值中的 `DN_IPV6_ADDRESS` 是待填写的 DataNode 地址，原默认值与示例保留。`TableSession`/`TableSessionPool` 分开接收 host 和 port 时，host 使用裸 IPv6；node URL 列表使用 `[ipv6]:port`。 + #### 2.2.3 接口展示 ```Python @@ -244,7 +246,7 @@ TableSessionPoolConfig是一个配置类，用于设置和创建 TableSessionPoo | **配置项** | **描述** | **类型** | **默认值** | | ------------------ | ------------------------------ | -------- | ------------------------ | -| node_urls | 数据库连接的节点 URL 列表 | list | None | +| node_urls | 数据库连接的节点 URL 列表；IPv6 endpoint 使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:6667`。IPv6 自 V2.0.12 起支持。 | list | None | | max_pool_size | 会话池中的最大会话数 | int | 5 | | username | 数据库连接用户名 | str | Session.DEFAULT_USER | | password | 数据库连接密码 | str | Session.DEFAULT_PASSWORD | @@ -403,6 +405,8 @@ if __name__ == "__main__": df = get_data() ``` +IPv6 SSL 连接中的 host 使用裸 IPv6。`ca_certs` 指定的 CA 必须能够验证服务端证书，且服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`。如果 SAN 不包含该地址，TLS 主机身份校验将失败。 + ## 4. 示例代码 Session示例代码:[Session Example](https://github.com/apache/iotdb/blob/master/iotdb-client/client-py/table_model_session_example.py) @@ -575,4 +579,3 @@ delete_data() session_pool.close() print("example is finished!") ``` - diff --git a/src/zh/UserGuide/latest-Table/Deployment-and-Maintenance/AINode_Deployment_apache.md b/src/zh/UserGuide/latest-Table/Deployment-and-Maintenance/AINode_Deployment_apache.md index 211e499d2..f61fa0c56 100644 --- a/src/zh/UserGuide/latest-Table/Deployment-and-Maintenance/AINode_Deployment_apache.md +++ b/src/zh/UserGuide/latest-Table/Deployment-and-Maintenance/AINode_Deployment_apache.md @@ -106,23 +106,32 @@ python3 --version ``` ### 3.2 配置项修改 + AINode 支持修改一些必要的参数。可以在 `conf/iotdb-ainode.properties` 文件中找到下列参数并进行持久化的修改： | **名称** | **描述** | **类型** | **默认值** | | ------------------------------ | ------------------------------------------------------------ | -------- | ------------------ | | cluster_name | AINode 要加入集群的标识 | string | defaultCluster | -| ain_seed_config_node | AINode 启动时注册的 ConfigNode 地址 | String | 127.0.0.1:10710 | -| ain_cluster_ingress_address | AINode 拉取数据的 DataNode 的 rpc 地址 | String | 127.0.0.1 | +| ain_seed_config_node | AINode 启动时注册的 ConfigNode endpoint。支持 `ipv4:port`、`hostname:port` 或 `[ipv6]:port`，例如 `[CN_IPV6_ADDRESS]:10710`。IPv6 自 V2.0.12 起支持。 | String | 127.0.0.1:10710 | +| ain_cluster_ingress_address | AINode 拉取数据的 DataNode RPC 地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 | String | 127.0.0.1 | | ain_cluster_ingress_port | AINode 拉取数据的 DataNode 的 rpc 端口 | Integer | 6667 | | ain_cluster_ingress_username | AINode 拉取数据的 DataNode 的客户端用户名 | String | root | | ain_cluster_ingress_password | AINode 拉取数据的 DataNode 的客户端密码 | String | root | | ain_cluster_ingress_time_zone | AINode 拉取数据的 DataNode 的客户端时区 | String | UTC+8 | -| ain_inference_rpc_address | AINode 提供服务与通信的地址 ，内部服务通讯接口 | String | 127.0.0.1 | +| ain_inference_rpc_address | AINode 提供服务与内部通信的地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 | String | 127.0.0.1 | | ain_inference_rpc_port | AINode 提供服务与通信的端口 | String | 10810 | | ain_system_dir | AINode 元数据存储路径，相对路径的起始目录与操作系统相关，建议使用绝对路径 | String | data/AINode/system | | ain_models_dir | AINode 存储模型文件的路径，相对路径的起始目录与操作系统相关，建议使用绝对路径 | String | data/AINode/models | | ain_thrift_compression_enabled | AINode 是否启用 thrift 的压缩机制，0-不启动、1-启动 | Boolean | 0 | +```properties +ain_seed_config_node=[CN_IPV6_ADDRESS]:10710 +ain_cluster_ingress_address=DN_IPV6_ADDRESS +ain_inference_rpc_address=AINODE_IPV6_ADDRESS +``` + +`ain_seed_config_node` 同时包含地址和端口，因此 IPv6 使用 `[ipv6]:port`；`ain_cluster_ingress_address` 和 `ain_inference_rpc_address` 只填写地址，使用裸 IPv6。示例中的 `CN_IPV6_ADDRESS`、`DN_IPV6_ADDRESS` 和 `AINODE_IPV6_ADDRESS` 分别表示 ConfigNode、DataNode 和 AINode 实际可达的地址，应用配置前须替换。AINode 启动后应确认已注册到 ConfigNode，并能够访问 DataNode。 + ### 3.3 导入权重文件 > 仅离线环境，在线环境可忽略本步骤 diff --git a/src/zh/UserGuide/latest-Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md b/src/zh/UserGuide/latest-Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md index 8eb3afdf6..efe6b96e6 100644 --- a/src/zh/UserGuide/latest-Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md +++ b/src/zh/UserGuide/latest-Table/Deployment-and-Maintenance/Cluster-Deployment_apache.md @@ -53,6 +53,8 @@ 6. 在安装部署数据库前，可以使用健康检查工具检测 IoTDB 节点运行环境，并获取详细的检查结果。 IoTDB 健康检查工具使用方法可以参考：[健康检查工具](../Tools-System/Health-Check-Tool.md)。 +使用 IPv4/IPv6 双栈或纯 IPv6 网络部署时，请在启动前确认：操作系统已启用 IPv6，配置的地址已分配到对应网卡并可被服务绑定；ConfigNode、DataNode 和 AINode 之间的 IPv6 路由可达，相关 RPC、共识和客户端端口已在防火墙中放行；使用 hostname 时，各节点的 DNS 或 `/etc/hosts` 解析结果一致。`0.0.0.0` 和 `::` 仅用于监听全部接口，不能作为节点注册、节点发现、客户端重定向或其他远端连接目标。 + ## 2. 准备步骤 1. 准备IoTDB数据库安装包 ：apache-iotdb-{version}-all-bin.zip（安装包获取见：[链接](../Deployment-and-Maintenance/IoTDB-Package_apache.md)） @@ -145,23 +147,33 @@ cd apache-iotdb-{version}-all-bin | 配置项 | 说明 | 默认 | 推荐值 | 11.101.17.224 | 11.101.17.225 | 11.101.17.226 | 备注 | | ------------------- | ------------------------------------------------------------ | --------------- | ------------------------------------------------------- | ------------- | ------------- | ------------- | ------------------ | -| cn_internal_address | ConfigNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | +| cn_internal_address | ConfigNode 在集群内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | | cn_internal_port | ConfigNode在集群内部通讯使用的端口 | 10710 | 10710 | 10710 | 10710 | 10710 | 首次启动后不能修改 | | cn_consensus_port | ConfigNode副本组共识协议通信使用的端口 | 10720 | 10720 | 10720 | 10720 | 10720 | 首次启动后不能修改 | -| cn_seed_config_node | 节点注册加入集群时连接的ConfigNode 的地址，cn_internal_address:cn_internal_port | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | +| cn_seed_config_node | 节点注册加入集群时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | #### 3.2.4 DataNode 配置 | 配置项 | 说明 | 默认 | 推荐值 | 11.101.17.224 | 11.101.17.225 | 11.101.17.226 | 备注 | | ------------------------------- | ------------------------------------------------------------ | --------------- | ------------------------------------------------------- | ------------- | ------------- | ------------- | ------------------ | -| dn_rpc_address | 客户端 RPC 服务的地址 | 127.0.0.1 | 默认本机可直接访问。非本机访问，请修改此配置项为所在服务器的IPV4地址或hostname，推荐使用所在服务器的IPV4地址。 | iotdb-1 |iotdb-2 | iotdb-3 | 重启服务生效 | +| dn_rpc_address | 客户端 RPC 服务监听地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 默认仅本机可访问；非本机访问时填写实际可路由的 IPv4 地址、裸 IPv6 地址或 hostname | iotdb-1 |iotdb-2 | iotdb-3 | 重启服务生效 | | dn_rpc_port | 客户端 RPC 服务的端口 | 6667 | 6667 | 6667 | 6667 | 6667 | 重启服务生效 | -| dn_internal_address | DataNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | +| dn_internal_address | DataNode 在集群内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | | dn_internal_port | DataNode在集群内部通信使用的端口 | 10730 | 10730 | 10730 | 10730 | 10730 | 首次启动后不能修改 | | dn_mpp_data_exchange_port | DataNode用于接收数据流使用的端口 | 10740 | 10740 | 10740 | 10740 | 10740 | 首次启动后不能修改 | | dn_data_region_consensus_port | DataNode用于数据副本共识协议通信使用的端口 | 10750 | 10750 | 10750 | 10750 | 10750 | 首次启动后不能修改 | | dn_schema_region_consensus_port | DataNode用于元数据副本共识协议通信使用的端口 | 10760 | 10760 | 10760 | 10760 | 10760 | 首次启动后不能修改 | -| dn_seed_config_node | 节点注册加入集群时连接的ConfigNode地址,即cn_internal_address:cn_internal_port | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | +| dn_seed_config_node | 节点注册加入集群时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | + +```properties +cn_internal_address=CN_IPV6_ADDRESS +cn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +dn_internal_address=DN_IPV6_ADDRESS +dn_rpc_address=DN_IPV6_ADDRESS +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +``` + +表模型示例中的 `CN_IPV6_ADDRESS` 和 `DN_IPV6_ADDRESS` 也仅表示对应节点的 IPv6 地址填写位置，实际部署前须替换为已绑定且网络可达的地址。 > ❗️注意：VSCode Remote等编辑器无自动保存配置功能，请确保修改的文件被持久化保存，否则配置项无法生效 @@ -201,6 +213,8 @@ cd sbin .\windows\start-datanode.bat ``` +启动完成后，通过 CLI 执行 `show cluster` 检查 ConfigNode 和 DataNode 是否均已注册。纯 IPv6 环境中，节点地址字段应显示配置的裸 IPv6；日志或错误信息中同时包含地址和端口时，应显示为 `[ipv6]:port`。如果发现 `::` 被返回为节点地址，请将对外发布地址改为实际可路由的 IPv6 地址。 + ### 3.5 启动 CLI 表模型 CLI 进入命令： @@ -217,6 +231,12 @@ cd sbin .\windows\start-cli-table.bat ``` +IPv6 地址通过 `-h` 单独传入时不使用方括号，端口通过 `-p` 传入，例如： + +```shell +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' -sql_dialect table +``` + ### 3.6 一键启停集群 #### 3.6.1 概述 @@ -494,4 +514,3 @@ remove datanode [datanode_id] | -D | 定义系统属性，格式为 key=value | 否 | | -X | 直接传递 -XX 参数给 JVM | 否 | | -h | 帮助指令 | 否 | - diff --git a/src/zh/UserGuide/latest-Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md b/src/zh/UserGuide/latest-Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md index d80483d67..c1fc4f1ed 100644 --- a/src/zh/UserGuide/latest-Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md +++ b/src/zh/UserGuide/latest-Table/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md @@ -112,23 +112,35 @@ ConfigNode 配置 | **配置项** | **说明** | **默认** | 推荐值 | **备注** | | :------------------ | :----------------------------------------------------------- | :-------------- | :----------------------------------------------- | :----------------- | -| cn_internal_address | ConfigNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | 首次启动后不能修改 | +| cn_internal_address | ConfigNode 在集群内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | 首次启动后不能修改 | | cn_internal_port | ConfigNode在集群内部通讯使用的端口 | 10710 | 10710 | 首次启动后不能修改 | | cn_consensus_port | ConfigNode副本组共识协议通信使用的端口 | 10720 | 10720 | 首次启动后不能修改 | -| cn_seed_config_node | 节点注册加入集群时连接的ConfigNode 的地址，cn_internal_address:cn_internal_port | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | +| cn_seed_config_node | 节点注册时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | DataNode 配置 | **配置项** | **说明** | **默认** | 推荐值 | **备注** | | :------------------------------ | :----------------------------------------------------------- | :-------------- |:----------------------------------------| :----------------- | -| dn_rpc_address | 客户端 RPC 服务的地址 | 127.0.0.1 | 默认本机可直接访问。非本机访问，请修改此配置项为所在服务器的IPV4地址或hostname，推荐使用所在服务器的IPV4地址。 | 重启服务生效 | +| dn_rpc_address | 客户端 RPC 服务监听地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 默认仅本机可访问；非本机访问时填写实际可路由的 IPv4 地址、裸 IPv6 地址或 hostname | 重启服务生效 | | dn_rpc_port | 客户端 RPC 服务的端口 | 6667 | 6667 | 重启服务生效 | -| dn_internal_address | DataNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | 首次启动后不能修改 | +| dn_internal_address | DataNode 在集群内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | 首次启动后不能修改 | | dn_internal_port | DataNode在集群内部通信使用的端口 | 10730 | 10730 | 首次启动后不能修改 | | dn_mpp_data_exchange_port | DataNode用于接收数据流使用的端口 | 10740 | 10740 | 首次启动后不能修改 | | dn_data_region_consensus_port | DataNode用于数据副本共识协议通信使用的端口 | 10750 | 10750 | 首次启动后不能修改 | | dn_schema_region_consensus_port | DataNode用于元数据副本共识协议通信使用的端口 | 10760 | 10760 | 首次启动后不能修改 | -| dn_seed_config_node | 节点注册加入集群时连接的ConfigNode地址,即cn_internal_address:cn_internal_port | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | +| dn_seed_config_node | 节点注册时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | + +仅在本机访问的单机实例可使用 IPv6 回环地址： + +```properties +cn_internal_address=::1 +cn_seed_config_node=[::1]:10710 +dn_internal_address=::1 +dn_rpc_address=::1 +dn_seed_config_node=[::1]:10710 +``` + +`::1` 是 IPv6 回环地址，只适用于本机访问或测试。需要由其他主机访问时，请改用本机实际可路由的 IPv6 地址。`::` 表示监听全部 IPv6 接口，不能作为远程连接目标、节点发现结果或客户端重定向地址。 ### 2.4 Edge 版启动与停止 @@ -261,4 +273,3 @@ DataNode 配置 | -D | 定义系统属性，格式为 key=value | 否 | | -X | 直接传递 -XX 参数给 JVM | 否 | | -h | 帮助指令 | 否 | - diff --git a/src/zh/UserGuide/latest-Table/FAQ/Frequently-asked-questions.md b/src/zh/UserGuide/latest-Table/FAQ/Frequently-asked-questions.md index 06eb3f261..9df8df192 100644 --- a/src/zh/UserGuide/latest-Table/FAQ/Frequently-asked-questions.md +++ b/src/zh/UserGuide/latest-Table/FAQ/Frequently-asked-questions.md @@ -285,3 +285,33 @@ sudo ln -sf $(which lsof) /bin/lsof # 自动创建软链接至标准路径 - 在conf/confignode-env.sh、conf/datanode-env.sh文件可通过调整ON_HEAP_MEMORY、OFF_HEAP_MEMORY等选项可以调整ConfigNode、DataNode使用的最大堆内、堆外内存 + +## 3. IPv6 连接 FAQ + +### 3.1 为什么 `[::1]:6667` 合法，而 `::1:6667` 不应作为 endpoint 使用？ + +自 V2.0.12 起，IoTDB 支持 IPv6 连接。IPv6 地址本身包含多个冒号。地址与端口组合时必须使用 `[ipv6]:port`，这样才能明确区分地址和端口。JDBC URL、Session node URL 和 Pipe `node-urls` 中的地址与端口部分应使用 `[ipv6]:port`。 + +### 3.2 为什么地址参数使用裸 IPv6，而 JDBC 和 Pipe 使用 `[ipv6]:port`？ + +`cn_internal_address`、`dn_internal_address`、`dn_rpc_address` 等参数只填写地址，因此使用裸 IPv6；JDBC URL、seed endpoint、Session node URL 和 Pipe `node-urls` 同时包含地址和端口，因此使用 `[ipv6]:port`。 + +### 3.3 为什么服务监听 `::` 成功，但客户端仍然无法连接？ + +`::` 表示监听全部 IPv6 接口，不是可路由的远端地址。节点注册、节点发现、客户端重定向、Pipe 目标和 Prometheus target 均应使用实际可达的 IPv6 地址。 + +### 3.4 IPv6 TLS 连接提示证书主机名或 IP 校验失败怎么办？ + +检查服务端证书 SAN 是否包含客户端实际访问的裸 IPv6 `IP Address`。SAN 中不能包含方括号或端口；同时确认客户端 TrustStore 包含签发该证书的 CA。 + +### 3.5 纯 IPv6 环境连接失败如何排查？ + +依次检查操作系统 IPv6 是否启用、地址是否已绑定、节点间路由和端口是否可达、防火墙是否放行、DNS 或 `/etc/hosts` 解析是否一致，以及客户端运行时和底层 socket 是否支持 IPv6。 + +### 3.6 双栈环境中 IPv4 可用、IPv6 连接失败怎么办？ + +先使用实际的 IPv6 地址与端口按当前入口要求的格式直接连接，确认目标服务已绑定 IPv6 地址，路由和防火墙允许该端口访问；再检查 DNS 的 AAAA 记录或 `/etc/hosts` 中的 IPv6 映射是否指向目标地址。分别验证 IPv4 与 IPv6 链路，不要将 IPv4 连接成功当作 IPv6 已连通；节点对外发布地址不能使用 `::`。 + +### 3.7 Pipe 报 IPv6 endpoint 解析错误怎么办？ + +检查每个 IPv6 endpoint 是否使用 `[ipv6]:port`，多个 endpoint 是否使用英文逗号分隔，是否误将 `::` 或 `0.0.0.0` 作为目标。SSL Pipe 还需检查 TrustStore、KeyStore 和目标证书 SAN。 diff --git a/src/zh/UserGuide/latest-Table/Reference/System-Config-Manual_apache.md b/src/zh/UserGuide/latest-Table/Reference/System-Config-Manual_apache.md index 80f842a42..10d157b65 100644 --- a/src/zh/UserGuide/latest-Table/Reference/System-Config-Manual_apache.md +++ b/src/zh/UserGuide/latest-Table/Reference/System-Config-Manual_apache.md @@ -121,11 +121,15 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 ### 3.2 SeedConfigNode 配置 +> 只填写地址的参数使用裸 IPv6；同时包含地址和端口的 endpoint 使用 `[ipv6]:port`。 + +下文的 `CN_IPV6_ADDRESS` 仅用于标示 ConfigNode 的 IPv6 地址填写位置；实际配置时应填写可解析、可路由的地址。原有 IPv4/主机名示例及默认值保持不变。 + - cn_seed_config_node | 名字 | cn_seed_config_node | | ------------ | ------------------------------------------------------------ | -| 描述 | 目标 ConfigNode 地址，ConfigNode 通过此地址加入集群，推荐使用 SeedConfigNode。V1.2.2 及以前曾用名是 cn_target_config_node_list | +| 描述 | 目标 ConfigNode 的 endpoint，ConfigNode 通过此地址加入集群，推荐使用 SeedConfigNode。支持 `ipv4:port`、`hostname:port` 或 `[ipv6]:port`，例如 `[CN_IPV6_ADDRESS]:10710`。V1.2.2 及以前曾用名是 cn_target_config_node_list。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1:10710 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | @@ -134,7 +138,7 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | dn_seed_config_node | | ------------ | ------------------------------------------------------------ | -| 描述 | ConfigNode 地址，DataNode 启动时通过此地址加入集群，推荐使用 SeedConfigNode。V1.2.2 及以前曾用名是 dn_target_config_node_list | +| 描述 | ConfigNode 的 endpoint，DataNode 启动时通过此地址加入集群，推荐使用 SeedConfigNode。支持 `ipv4:port`、`hostname:port` 或 `[ipv6]:port`，例如 `[CN_IPV6_ADDRESS]:10710`。V1.2.2 及以前曾用名是 dn_target_config_node_list。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1:10710 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | @@ -145,7 +149,7 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | cn_internal_address | | ------------ | ---------------------------- | -| 描述 | ConfigNode 集群内部地址 | +| 描述 | ConfigNode 集群内部通信地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口，不使用方括号，例如 `192.168.1.10`、`CN_IPV6_ADDRESS` 或 `iotdb-cn-1`。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | @@ -172,7 +176,7 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | dn_rpc_address | | ------------ |----------------| -| 描述 | 客户端 RPC 服务监听地址 | +| 描述 | 客户端 RPC 服务监听地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口，不使用方括号，例如 `192.168.1.20`、`DN_IPV6_ADDRESS` 或 `iotdb-dn-1`。使用 `::` 可监听全部 IPv6 接口，但 `::` 不能作为客户端重定向或节点发现返回的远端连接地址。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1 | | 改后生效方式 | 重启服务生效 | @@ -190,11 +194,15 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | dn_internal_address | | ------------ | ---------------------------- | -| 描述 | DataNode 内网通信地址 | +| 描述 | DataNode 内部通信地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口，不使用方括号，例如 `192.168.1.20`、`DN_IPV6_ADDRESS` 或 `iotdb-dn-1`。IPv6 自 V2.0.12 起支持。 | | 类型 | string | | 默认值 | 127.0.0.1 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | +> 当地址参数只填写 IPv6 地址时，应使用裸 IPv6，例如 `DN_IPV6_ADDRESS`；当地址和端口组合为 endpoint 时，应使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:10730`。`0.0.0.0` 和 `::` 仅用于监听全部接口，不能作为远端连接目标。 + +下文的 `DN_IPV6_ADDRESS` 仅用于标示 DataNode 的 IPv6 地址填写位置，实际配置时应替换为相应节点已绑定且可达的地址。 + - dn_internal_port | 名字 | dn_internal_port | @@ -500,6 +508,8 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 ### 3.7 SSL 配置 +> IPv6 不改变现有 SSL/TLS 开关、协议、KeyStore 和 TrustStore 配置。通过 IPv6 地址访问 DataNode 并启用主机身份校验时，服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`，不包含方括号和端口。例如，客户端连接 `[DN_IPV6_ADDRESS]:6667` 时，证书 SAN 中应包含 `DN_IPV6_ADDRESS`。 + - enable_thrift_ssl | 名字 | enable_thrift_ssl | diff --git a/src/zh/UserGuide/latest-Table/Tools-System/CLI_apache.md b/src/zh/UserGuide/latest-Table/Tools-System/CLI_apache.md index 37ab9452d..5e8b688a9 100644 --- a/src/zh/UserGuide/latest-Table/Tools-System/CLI_apache.md +++ b/src/zh/UserGuide/latest-Table/Tools-System/CLI_apache.md @@ -58,11 +58,21 @@ Shell> sbin\windows\start-cli.bat -h 127.0.0.1 -p 6667 -u root -pw root -sql_dia - -u 和-pw 是 IoTDB 登录的用户名密码（安装后IoTDB有一个默认用户，用户名为`root`,密码为`root`） - -sql_dialect 是登录的数据模型（表模型或树模型），此处指定为 table 代表进入表模型模式 +自 V2.0.12 起，IPv6 地址通过 `-h` 单独传入时使用裸地址，不加方括号；端口通过 `-p` 单独传入。示例中的 `DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前应替换为实际可达的 IPv6 地址；原 IPv4 启动示例保留。例如： + +```shell +# Linux/macOS +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' -sql_dialect table + +# Windows（V2.0.4.x 及之后） +sbin\windows\start-cli.bat -h DN_IPV6_ADDRESS -p 6667 -u root -pw "" -sql_dialect table +``` + 更多参数见： | **参数名** | **参数类型** | **是否为必需参数** | **说明** | **示例** | |:-----------------------------|:-----------|:------------|:-----------------------------------------------------------|:---------------------| -| -h `` | string 类型 | 否 | IoTDB 客户端连接 IoTDB 服务器的 IP 地址， 默认使用：127.0.0.1。 | -h 127.0.0.1 | +| -h `` | string 类型 | 否 | IoTDB 服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号，自 V2.0.12 起支持。 | -h 127.0.0.1 | | -p `` | int 类型 | 否 | IoTDB 客户端连接服务器的端口号，IoTDB 默认使用 6667。 | -p 6667 | | -u `` | string 类型 | 否 | IoTDB 客户端连接服务器所使用的用户名，默认使用 root。 | -u root | | -pw `` | string 类型 | 否 | IoTDB 客户端连接服务器所使用的密码，默认使用 root。 | -pw root | diff --git a/src/zh/UserGuide/latest-Table/Tools-System/Data-Export-Tool_apache.md b/src/zh/UserGuide/latest-Table/Tools-System/Data-Export-Tool_apache.md index b88ee0f38..8faeb9e60 100644 --- a/src/zh/UserGuide/latest-Table/Tools-System/Data-Export-Tool_apache.md +++ b/src/zh/UserGuide/latest-Table/Tools-System/Data-Export-Tool_apache.md @@ -40,7 +40,7 @@ IoTDB 支持两种方式进行数据导出： | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | |--------------|------------------------| ----------------------------------------------------------------- | -------------- |---------------------------------------------------------------------------| | -ft | --file\_type | 导出文件的类型，可以选择：csv、sql、tsfile | √ | | -| -h | --host | 主机名 | 否 | 127.0.0.1 | +| -h | --host | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | -p | --port | 端口号 | 否 | 6667 | | -u | --username | 用户名 | 否 | root | | -pw | --password | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -58,6 +58,8 @@ IoTDB 支持两种方式进行数据导出： | -ts | --trust_store | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | -tpw | --trust_store_password | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。`DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前须替换为实际可达的裸 IPv6；不要把带方括号的地址作为 `-h` 的值。启用 SSL 时，继续使用本页现有的 `-usessl`、`-ts` 和 `-tpw` 参数；服务端证书 SAN 必须包含实际访问的裸 IPv6 地址。 + ### 2.2 CSV 格式 #### 2.2.1 运行命令 diff --git a/src/zh/UserGuide/latest-Table/Tools-System/Data-Import-Tool_apache.md b/src/zh/UserGuide/latest-Table/Tools-System/Data-Import-Tool_apache.md index 589707812..6753526b9 100644 --- a/src/zh/UserGuide/latest-Table/Tools-System/Data-Import-Tool_apache.md +++ b/src/zh/UserGuide/latest-Table/Tools-System/Data-Import-Tool_apache.md @@ -46,7 +46,7 @@ IoTDB 支持三种方式进行数据导入： | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | |--------------|------------------------|-------------------------------------------------------------------------------------------------------------------------------| -------------- |----------------------------------| | -ft | --file\_type | 导入文件的类型，可以选择：csv、sql、tsfile | √ | | -| -h | --host | 主机名 | 否 | 127.0.0.1 | +| -h | --host | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | -p | --port | 端口号 | 否 | 6667 | | -u | --username | 用户名 | 否 | root | | -pw | --password | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -61,6 +61,7 @@ IoTDB 支持三种方式进行数据导入： | -ts | --trust_store | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | -tpw | --trust_store_password | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。`DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前须替换为实际可达的裸 IPv6；不要把带方括号的地址作为 `-h` 的值。启用 SSL 时，继续使用本页现有的 `-usessl`、`-ts` 和 `-tpw` 参数；服务端证书 SAN 必须包含实际访问的裸 IPv6 地址。 ### 2.2 CSV 格式 diff --git a/src/zh/UserGuide/latest-Table/Tools-System/Monitor-Tool_apache.md b/src/zh/UserGuide/latest-Table/Tools-System/Monitor-Tool_apache.md index 42211f004..ed57ae0c2 100644 --- a/src/zh/UserGuide/latest-Table/Tools-System/Monitor-Tool_apache.md +++ b/src/zh/UserGuide/latest-Table/Tools-System/Monitor-Tool_apache.md @@ -60,6 +60,12 @@ file_count{name="seq",} 2.0 ... ``` +自 V2.0.12 起，监控 metrics 接口支持通过 IPv6 地址访问。访问 IPv6 metrics URL 时，地址和端口之间应使用方括号区分；将下方占位符替换为实际可达的 IPv6 地址： + +```shell +curl 'http://[IPV6_ADDRESS]:9091/metrics' +``` + ## 3. Prometheus + Grafana 如上所示，IoTDB 对外暴露出标准的 Prometheus 格式的监控指标数据，可以使用 Prometheus 采集并存储监控指标，使用 Grafana @@ -90,6 +96,7 @@ follow_redirects: true static_configs: - targets: - localhost:9091 + - '[IPV6_ADDRESS]:9091' ``` 更多细节可以参考下面的文档： @@ -101,3 +108,4 @@ static_configs: [Grafana安装使用文档](https://grafana.com/docs/grafana/latest/getting-started/getting-started/) [Grafana从Prometheus查询数据并绘图的文档](https://prometheus.io/docs/visualization/grafana/#grafana-support-for-prometheus) +Prometheus target 同时包含 IPv6 地址和端口，应使用 `[ipv6]:port`。即使服务监听地址配置为 `::`，target 也应填写实际可路由的 IPv6 地址，不能填写 `[::]:9091`。 diff --git a/src/zh/UserGuide/latest-Table/Tools-System/Schema-Export-Tool_apache.md b/src/zh/UserGuide/latest-Table/Tools-System/Schema-Export-Tool_apache.md index 8cada37ee..73ee8b6bd 100644 --- a/src/zh/UserGuide/latest-Table/Tools-System/Schema-Export-Tool_apache.md +++ b/src/zh/UserGuide/latest-Table/Tools-System/Schema-Export-Tool_apache.md @@ -31,7 +31,7 @@ | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | |----------------|----------------------------|-----------------------------------------------| ----------------------------------- |---------------------------------------| -| `-h` | `--host` | 主机名 | 否 | 127.0.0.1 | +| `-h` | `--host` | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | `-p` | `--port` | 端口号 | 否 | 6667 | | `-u` | `--username` | 用户名 | 否 | root | | `-pw` | `--password` | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -48,6 +48,8 @@ | `-ts` | `--trust_store` | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | `-tpw` | `--trust_store_password` | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。`DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前须替换为实际可达的裸 IPv6；不要把带方括号的地址作为 `-h` 的值。启用 SSL 时，继续使用本页现有的 `-usessl`、`-ts` 和 `-tpw` 参数，并确认证书 SAN 包含实际访问的 IPv6 地址。 + ### 2.2 运行命令 ```Bash @@ -109,3 +111,5 @@ CREATE TABLE table2( arrival_time TIMESTAMP FIELD ); ``` + +自 V2.0.12 起，`-h` 可填写实际的裸 IPv6 地址，`-p` 继续单独传入端口；原命令中的 `-sql_dialect`、`-db`、`-s`、`-t`、`-path` 等参数无需为 IPv6 改动。 diff --git a/src/zh/UserGuide/latest-Table/Tools-System/Schema-Import-Tool_apache.md b/src/zh/UserGuide/latest-Table/Tools-System/Schema-Import-Tool_apache.md index cc03098e0..d2f6cfaea 100644 --- a/src/zh/UserGuide/latest-Table/Tools-System/Schema-Import-Tool_apache.md +++ b/src/zh/UserGuide/latest-Table/Tools-System/Schema-Import-Tool_apache.md @@ -31,7 +31,7 @@ | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | | --------------------- | ------------------------------- |------------------------------------------------| -------------- |-----------------------------------| -| `-h` | `--host` | 主机名 | 否 | 127.0.0.1 | +| `-h` | `--host` | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | `-p` | `--port` | 端口号 | 否 | 6667 | | `-u` | `--username` | 用户名 | 否 | root | | `-pw` | `--password` | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -46,6 +46,8 @@ | `-ts` | `--trust_store` | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | `-tpw` | `--trust_store_password` | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。`DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前须替换为实际可达的裸 IPv6；不要把带方括号的地址作为 `-h` 的值。启用 SSL 时，继续使用本页现有的 `-usessl`、`-ts` 和 `-tpw` 参数，并确认证书 SAN 包含实际访问的 IPv6 地址。 + ### 2.2 运行命令 ```Bash @@ -164,3 +166,5 @@ IoTDB:database2> desc table2 |arrival_time|TIMESTAMP| FIELD| +------------+---------+---------+ ``` + +自 V2.0.12 起，`-h` 可填写实际的裸 IPv6 地址，`-p` 继续单独传入端口；原命令中的 `-sql_dialect`、`-db`、`-s`、`-t`、`-path` 等参数无需为 IPv6 改动。 diff --git a/src/zh/UserGuide/latest-Table/User-Manual/Data-Sync_apache.md b/src/zh/UserGuide/latest-Table/User-Manual/Data-Sync_apache.md index 1fa296f7d..a450ea422 100644 --- a/src/zh/UserGuide/latest-Table/User-Manual/Data-Sync_apache.md +++ b/src/zh/UserGuide/latest-Table/User-Manual/Data-Sync_apache.md @@ -338,6 +338,16 @@ with sink ( ) ``` +```sql +create pipe A2B_IPV6 +with sink ( + 'sink'='iotdb-thrift-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667' +) +``` + +自 V2.0.12 起，Pipe 支持使用 IPv6 endpoint 连接目标端 IoTDB。`node-urls` 同时包含地址和端口，IPv6 使用 `[ipv6]:port`；多个 endpoint 使用英文逗号分隔。上方独立示例中的 `DN_IPV6_ADDRESS` 和 `DN_IPV6_ADDRESS_2` 分别表示目标端两个 DataNode 的实际可达 IPv6 地址，使用前须替换；原有 Pipe 示例不变。 + ### 3.2 部分数据同步 本例子用来演示同步某个历史时间范围（ 2023 年 8 月 23 日 8 点到 2023 年 10 月 23 日 8 点）的数据至另一个 IoTDB，数据链路如下图所示： @@ -499,6 +509,18 @@ with sink ( - `ssl.trust-store-path`: 连接目标端 DataNode 所需的 trust store 证书路径 - `ssl.trust-store-pwd`: 连接目标端 DataNode 所需的 trust store 证书密码 +```sql +create pipe A2B_SSL_IPV6 +with sink ( + 'sink'='iotdb-thrift-ssl-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667', + 'ssl.trust-store-path'='pki/trusted', + 'ssl.trust-store-pwd'='' +) +``` + +通过 IPv6 地址进行 TLS 主机身份校验时，目标 DataNode 的服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`，不包含方括号和端口。 + ## 参考：注意事项 可通过修改 IoTDB 配置文件（`iotdb-system.properties`）以调整数据同步的参数，如同步数据存储目录等。完整配置如下：： @@ -591,7 +613,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **参数** | **描述** | **value 取值范围** | **是否必填** | **默认取值** | |--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|----------|--------------| | sink | iotdb-thrift-sink 或 iotdb-thrift-async-sink | String: iotdb-thrift-sink 或 iotdb-thrift-async-sink | 必填 | - | -| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务端口的 url（请注意同步任务不支持向自身服务进行转发） | String. 例：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | 必填 | - | +| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务 endpoint（同步任务不支持向自身服务转发）。IPv6 使用 `[ipv6]:port`，多个 endpoint 使用英文逗号分隔。IPv6 自 V2.0.12 起支持。 | String。示例：`'127.0.0.1:6667,127.0.0.1:6668'`、`'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | 必填 | - | | user/username | 连接接收端使用的用户名，同步要求该用户具备相应的操作权限 | String | 选填 | root | | password | 连接接收端使用的用户名对应的密码，同步要求该用户具备相应的操作权限 | String | 选填 | root | | batch.enable | 是否开启日志攒批发送模式，用于提高传输吞吐，降低 IOPS | Boolean: true, false | 选填 | true | @@ -611,7 +633,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **参数** | **描述** | **value 取值范围** | **是否必填** | **默认取值** | |--------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| -------- | ------------ | | sink | iotdb-thrift-ssl-sink | String: iotdb-thrift-ssl-sink | 必填 | - | -| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务端口的 url（请注意同步任务不支持向自身服务进行转发） | String. 例：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | 必填 | - | +| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务 endpoint（同步任务不支持向自身服务转发）。IPv6 使用 `[ipv6]:port`，多个 endpoint 使用英文逗号分隔；目标证书 SAN 必须覆盖实际连接地址。IPv6 自 V2.0.12 起支持。 | String。示例：`'127.0.0.1:6667,127.0.0.1:6668'`、`'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | 必填 | - | | user/username | 连接接收端使用的用户名，同步要求该用户具备相应的操作权限 | String | 选填 | root | | password | 连接接收端使用的用户名对应的密码，同步要求该用户具备相应的操作权限 | String | 选填 | root | | batch.enable | 是否开启日志攒批发送模式，用于提高传输吞吐，降低 IOPS | Boolean: true, false | 选填 | true | diff --git a/src/zh/UserGuide/latest-Table/User-Manual/Load-Balance_apache.md b/src/zh/UserGuide/latest-Table/User-Manual/Load-Balance_apache.md index 0580404da..cbae6dd68 100644 --- a/src/zh/UserGuide/latest-Table/User-Manual/Load-Balance_apache.md +++ b/src/zh/UserGuide/latest-Table/User-Manual/Load-Balance_apache.md @@ -116,6 +116,8 @@ IoTDB 集群扩容的核心是增加 DataNode 节点，因为 DataNode 是处理 echo "192.168.1.3 iotdb-1" >> /etc/hosts ``` +7. IPv6 网络检查：使用双栈或纯 IPv6 网络扩容时，确认新旧节点之间的 IPv6 路由和所需端口可达，DNS 或 `/etc/hosts` 解析一致，配置的 IPv6 地址已绑定到对应网卡。`0.0.0.0` 和 `::` 仅用于监听，不能作为新节点注册到集群时使用的远端地址。 + #### 2.2.2 扩容操作 1. 为确保您获取的 IoTDB 安装包完整且正确，在执行安装部署前建议您进行 SHA512 校验。 @@ -136,15 +138,25 @@ vim iotdb-system.properies |配置项|说明|默认|备注| |---|---|---|---| -|dn\_seed\_config\_node|节点注册加入集群时连接的 ConfigNode 地址,即 cn\_internal\_address:cn\_internal\_port|127\.0\.0\.1:10710
|非常重要，强制修改此项，将其改为原集群 ConfigNode 主节点的地址
| -|dn\_rpc\_address|客户端 RPC 服务的地址|0\.0\.0\.0|按需修改，重启服务生效| +|dn\_seed\_config\_node| 节点注册加入集群时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`。IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 |127\.0\.0\.1:10710
|非常重要，强制修改此项，将其改为原集群 ConfigNode 主节点的地址
| +|dn\_rpc\_address| 客户端 RPC 服务监听地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 |0\.0\.0\.0|按需修改，重启服务生效| |dn\_rpc\_port|客户端 RPC 服务的端口|6667|按需修改，重启服务生效| -|dn\_internal\_address|DataNode 在集群内部通讯使用的地址|127\.0\.0\.1|按需修改，首次启动后不能修改| +|dn\_internal\_address| DataNode 集群内部通信地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 |127\.0\.0\.1|按需修改，首次启动后不能修改| |dn\_internal\_port|DataNode 在集群内部通信使用的端口|10730|按需修改，首次启动后不能修改| |dn\_mpp\_data\_exchange\_port|DataNode 用于接收数据流使用的端口|10740|按需修改，首次启动后不能修改| |dn\_data\_region\_consensus\_port|DataNode 用于数据副本共识协议通信使用的端口|10750|按需修改，首次启动后不能修改| |dn\_schema\_region\_consensus\_port|DataNode 用于元数据副本共识协议通信使用的端口|10760|按需修改，首次启动后不能修改| +纯 IPv6 扩容示例： + +```properties +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +dn_rpc_address=NEW_DN_IPV6_ADDRESS +dn_internal_address=NEW_DN_IPV6_ADDRESS +``` + +其中 `CN_IPV6_ADDRESS` 为原集群 ConfigNode 的可达 IPv6 地址，`NEW_DN_IPV6_ADDRESS` 为新节点已绑定且可路由的 IPv6 地址；应用配置前须替换。新节点启动后执行 `show datanodes`，确认新节点状态为 `Running`，地址字段显示配置的裸 IPv6。若返回 `::`，应将对外发布地址改为实际可路由的 IPv6 地址。 + 4. 启动 DataNode 节点 进入 IoTDB 的 sbin 目录下，启动 Datanode： diff --git a/src/zh/UserGuide/latest/API/Programming-Cpp-Native-API_apache.md b/src/zh/UserGuide/latest/API/Programming-Cpp-Native-API_apache.md index b8a8aa961..ba548fea2 100644 --- a/src/zh/UserGuide/latest/API/Programming-Cpp-Native-API_apache.md +++ b/src/zh/UserGuide/latest/API/Programming-Cpp-Native-API_apache.md @@ -191,6 +191,8 @@ void open(bool enableRPCCompression); void close(); ``` +自 V2.0.12 起，C++ Session 支持使用 IPv6 地址连接 IoTDB。使用 IPv6 地址初始化客户端时，如果接口分别接收 host 和 port，host 使用裸 IPv6，port 单独传入；如果接口接收 node URL，则使用 `[ipv6]:port`。示意写法中的 `DN_IPV6_ADDRESS` 仅表示待填写的目标 DataNode 地址，使用前须替换为实际可达的 IPv6 地址。客户端获取节点列表或处理重定向时，不应将 `0.0.0.0`、`::` 或其等价表示作为远端连接目标。启用 SSL 时，服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`。 + ### 3.2 数据定义接口（DDL） #### Database 管理 diff --git a/src/zh/UserGuide/latest/API/Programming-JDBC_apache.md b/src/zh/UserGuide/latest/API/Programming-JDBC_apache.md index 4fdad23e5..516f87e25 100644 --- a/src/zh/UserGuide/latest/API/Programming-JDBC_apache.md +++ b/src/zh/UserGuide/latest/API/Programming-JDBC_apache.md @@ -292,3 +292,12 @@ public class JDBCCharsetExample { } } ``` + +```java +// 自 V2.0.12 起，IPv6 URL 的地址与端口使用 [ipv6]:port +// String ipv6Url = "jdbc:iotdb://[IPV6_ADDRESS]:6667/"; +// SSL 连接沿用原有参数： +// String ipv6SslUrl = "jdbc:iotdb://[IPV6_ADDRESS]:6667?use_ssl=true"; +``` + +JDBC URL 同时包含地址和端口，IPv6 格式为 `jdbc:iotdb://[ipv6]:port/`，不能省去地址两侧的方括号。注释示例中的 `IPV6_ADDRESS` 是地址占位符，应替换为实际可达的 IPv6 地址；原有 IPv4 URL 保留。启用 SSL 时沿用原连接参数，服务端证书 SAN 须包含实际访问的裸 IPv6 `IP Address`。 diff --git a/src/zh/UserGuide/latest/API/Programming-Java-Native-API_apache.md b/src/zh/UserGuide/latest/API/Programming-Java-Native-API_apache.md index bafad4551..8c5b9a2fa 100644 --- a/src/zh/UserGuide/latest/API/Programming-Java-Native-API_apache.md +++ b/src/zh/UserGuide/latest/API/Programming-Java-Native-API_apache.md @@ -73,7 +73,14 @@ public class IoTDBSessionPoolExample { .build(); } } -``` +``` + +```java +// IPv6 node URL 同时包含地址和端口： +// nodeUrls.add("[IPV6_ADDRESS]:6667"); +``` + +自 V2.0.12 起，Java Session 和 SessionPool 支持使用 IPv6 地址连接 IoTDB。`nodeUrls` 中的每个元素都是地址与端口组合，IPv6 使用 `[ipv6]:port`；注释中的 `IPV6_ADDRESS` 仅表示待填写的实际节点地址，原有 `nodeUrls.add` 保留。如果 API 分别接收 host 和 port，host 使用裸 IPv6，port 单独传入。连接池重试与节点刷新使用同一 endpoint 规则。 ### 2.3 执行数据库操作 @@ -494,7 +501,7 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式 | 字段名 | 类型 | 说明 | | -------------------------------- | ----------------------------------- | ---------------------------------------- | -| `nodeUrls` | `List` | 数据库节点的 URL 列表，支持多节点连接 | +| `nodeUrls` | `List` | 数据库节点的 URL 列表，支持多节点连接；IPv6 endpoint 使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:6667`。IPv6 自 V2.0.12 起支持。 | | `username` | `String` | 用户名 | | `password` | `String` | 密码 | | `fetchSize` | `int` | 查询结果的默认批量返回大小 | @@ -620,6 +627,3 @@ Session具有如下的字段，可以通过构造函数或Session.Builder方式 | `getBackupConfiguration()` | 获取备份配置信息 | 无参数 | | `fetchAllConnections()` | 获取所有活动的连接信息 | 无参数 | | `getSystemStatus()` | 获取系统状态 | 已废弃，默认返回 `SystemStatus.NORMAL` | - - - diff --git a/src/zh/UserGuide/latest/API/Programming-Python-Native-API_apache.md b/src/zh/UserGuide/latest/API/Programming-Python-Native-API_apache.md index d29f2f00f..efb70cd5b 100644 --- a/src/zh/UserGuide/latest/API/Programming-Python-Native-API_apache.md +++ b/src/zh/UserGuide/latest/API/Programming-Python-Native-API_apache.md @@ -99,6 +99,26 @@ session.open(enable_rpc_compression=False) ```python session.close() ``` + +```python +# host 和 port 分开传入时，host 使用裸 IPv6 +session = Session( + ip="DN_IPV6_ADDRESS", + port="6667", + user="root", + password="", +) + +# node URL 同时包含地址和端口时，IPv6 使用 [ipv6]:port +session = Session.init_from_node_urls( + node_urls=["[DN_IPV6_ADDRESS]:6667", "[DN_IPV6_ADDRESS_2]:6667"], + user="root", + password="", +) +``` + +自 V2.0.12 起，Python Session 和 SessionPool 支持使用 IPv6 地址连接 IoTDB。单独传入 `ip` 时使用裸 IPv6，不要将带方括号的地址传给底层 socket；`node_urls` 中的元素同时包含地址和端口，使用 `[ipv6]:port`。示例中的 `DN_IPV6_ADDRESS` 与 `DN_IPV6_ADDRESS_2` 是两个节点的地址占位符，使用前须替换为实际可达的 IPv6 地址。原 IPv4 示例保留。 + ### 3.2 通过SessionPool管理session连接 利用SessionPool管理session，不需要再考虑如何重用session。当session连接到达pool的最大值时，获取session的请求会被阻塞，可以通过参数设置阻塞等待时间。每次session使用完需要使用putBack方法将session归还到SessionPool中管理。 @@ -232,6 +252,8 @@ if __name__ == "__main__": df = get_data() ``` +IPv6 SSL 连接中的 host 使用裸 IPv6。`ca_certs` 指定的 CA 必须能够验证服务端证书，且服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`。如果 SAN 不包含该地址，TLS 主机身份校验将失败。 + ## 4. 数据定义接口 DDL ### 4.1 Database 管理 diff --git a/src/zh/UserGuide/latest/Deployment-and-Maintenance/AINode_Deployment_apache.md b/src/zh/UserGuide/latest/Deployment-and-Maintenance/AINode_Deployment_apache.md index 66a3c03ed..e2e32cbac 100644 --- a/src/zh/UserGuide/latest/Deployment-and-Maintenance/AINode_Deployment_apache.md +++ b/src/zh/UserGuide/latest/Deployment-and-Maintenance/AINode_Deployment_apache.md @@ -105,23 +105,32 @@ python3 --version ``` ### 3.2 配置项修改 + AINode 支持修改一些必要的参数。可以在 `conf/iotdb-ainode.properties` 文件中找到下列参数并进行持久化的修改： | **名称** | **描述** | **类型** | **默认值** | | ------------------------------ | ------------------------------------------------------------ | -------- | ------------------ | | cluster_name | AINode 要加入集群的标识 | string | defaultCluster | -| ain_seed_config_node | AINode 启动时注册的 ConfigNode 地址 | String | 127.0.0.1:10710 | -| ain_cluster_ingress_address | AINode 拉取数据的 DataNode 的 rpc 地址 | String | 127.0.0.1 | +| ain_seed_config_node | AINode 启动时注册的 ConfigNode endpoint。支持 `ipv4:port`、`hostname:port` 或 `[ipv6]:port`，例如 `[CN_IPV6_ADDRESS]:10710`。IPv6 自 V2.0.12 起支持。 | String | 127.0.0.1:10710 | +| ain_cluster_ingress_address | AINode 拉取数据的 DataNode RPC 地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 | String | 127.0.0.1 | | ain_cluster_ingress_port | AINode 拉取数据的 DataNode 的 rpc 端口 | Integer | 6667 | | ain_cluster_ingress_username | AINode 拉取数据的 DataNode 的客户端用户名 | String | root | | ain_cluster_ingress_password | AINode 拉取数据的 DataNode 的客户端密码 | String | root | | ain_cluster_ingress_time_zone | AINode 拉取数据的 DataNode 的客户端时区 | String | UTC+8 | -| ain_inference_rpc_address | AINode 提供服务与通信的地址 ，内部服务通讯接口 | String | 127.0.0.1 | +| ain_inference_rpc_address | AINode 提供服务与内部通信的地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 | String | 127.0.0.1 | | ain_inference_rpc_port | AINode 提供服务与通信的端口 | String | 10810 | | ain_system_dir | AINode 元数据存储路径，相对路径的起始目录与操作系统相关，建议使用绝对路径 | String | data/AINode/system | | ain_models_dir | AINode 存储模型文件的路径，相对路径的起始目录与操作系统相关，建议使用绝对路径 | String | data/AINode/models | | ain_thrift_compression_enabled | AINode 是否启用 thrift 的压缩机制，0-不启动、1-启动 | Boolean | 0 | +```properties +ain_seed_config_node=[CN_IPV6_ADDRESS]:10710 +ain_cluster_ingress_address=DN_IPV6_ADDRESS +ain_inference_rpc_address=AINODE_IPV6_ADDRESS +``` + +`ain_seed_config_node` 同时包含地址和端口，因此 IPv6 使用 `[ipv6]:port`；`ain_cluster_ingress_address` 和 `ain_inference_rpc_address` 只填写地址，使用裸 IPv6。示例中的 `CN_IPV6_ADDRESS`、`DN_IPV6_ADDRESS` 和 `AINODE_IPV6_ADDRESS` 分别表示 ConfigNode、DataNode 和 AINode 实际可达的地址，应用配置前须替换。AINode 启动后应确认已注册到 ConfigNode，并能够访问 DataNode。 + ### 3.3 导入权重文件 > 仅离线环境，在线环境可忽略本步骤 diff --git a/src/zh/UserGuide/latest/Deployment-and-Maintenance/Cluster-Deployment_apache.md b/src/zh/UserGuide/latest/Deployment-and-Maintenance/Cluster-Deployment_apache.md index 39dd0874c..2b23605a3 100644 --- a/src/zh/UserGuide/latest/Deployment-and-Maintenance/Cluster-Deployment_apache.md +++ b/src/zh/UserGuide/latest/Deployment-and-Maintenance/Cluster-Deployment_apache.md @@ -48,6 +48,8 @@ 6. 在安装部署数据库前，可以使用健康检查工具检测 IoTDB 节点运行环境，并获取详细的检查结果。 IoTDB 健康检查工具使用方法可以参考：[健康检查工具](../Tools-System/Health-Check-Tool.md)。 +使用 IPv4/IPv6 双栈或纯 IPv6 网络部署时，请在启动前确认：操作系统已启用 IPv6，配置的地址已分配到对应网卡并可被服务绑定；ConfigNode、DataNode 和 AINode 之间的 IPv6 路由可达，相关 RPC、共识和客户端端口已在防火墙中放行；使用 hostname 时，各节点的 DNS 或 `/etc/hosts` 解析结果一致。`0.0.0.0` 和 `::` 仅用于监听全部接口，不能作为节点注册、节点发现、客户端重定向或其他远端连接目标。 + ## 2. 准备步骤 1. 准备IoTDB数据库安装包 ：apache-iotdb-{version}-all-bin.zip（安装包获取见：[链接](../Deployment-and-Maintenance/IoTDB-Package_apache.md)） @@ -142,10 +144,10 @@ cd apache-iotdb-{version}-all-bin | 配置项 | 说明 | 默认 | 推荐值 | 192.168.1.3 | 192.168.1.4 | 192.168.1.5 | 备注 | | ------------------- | ------------------------------------------------------------ | --------------- | ------------------------------------------------------- | ------------- | ------------- | ------------- | ------------------ | -| cn_internal_address | ConfigNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | +| cn_internal_address | ConfigNode 在集群内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | | cn_internal_port | ConfigNode在集群内部通讯使用的端口 | 10710 | 10710 | 10710 | 10710 | 10710 | 首次启动后不能修改 | | cn_consensus_port | ConfigNode副本组共识协议通信使用的端口 | 10720 | 10720 | 10720 | 10720 | 10720 | 首次启动后不能修改 | -| cn_seed_config_node | 节点注册加入集群时连接的ConfigNode 的地址，cn_internal_address:cn_internal_port | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | +| cn_seed_config_node | 节点注册加入集群时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | #### DataNode 配置 @@ -153,14 +155,31 @@ cd apache-iotdb-{version}-all-bin | 配置项 | 说明 | 默认 | 推荐值 | 192.168.1.3 | 192.168.1.4 | 192.168.1.5 | 备注 | | ------------------------------- | ------------------------------------------------------------ | --------------- | ------------------------------------------------------- | ------------- | ------------- | ------------- | ------------------ | -| dn_rpc_address | 客户端 RPC 服务的地址 | 127.0.0.1 | 默认本机可直接访问。非本机访问，请修改此配置项为所在服务器的IPV4地址或hostname，推荐使用所在服务器的IPV4地址。 | iotdb-1 |iotdb-2 | iotdb-3 | 重启服务生效 | +| dn_rpc_address | 客户端 RPC 服务监听地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 默认仅本机可访问；非本机访问时填写所在服务器可路由的 IPv4 地址、裸 IPv6 地址或 hostname | iotdb-1 |iotdb-2 | iotdb-3 | 重启服务生效 | | dn_rpc_port | 客户端 RPC 服务的端口 | 6667 | 6667 | 6667 | 6667 | 6667 | 重启服务生效 | -| dn_internal_address | DataNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | +| dn_internal_address | DataNode 在集群内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | iotdb-1 | iotdb-2 | iotdb-3 | 首次启动后不能修改 | | dn_internal_port | DataNode在集群内部通信使用的端口 | 10730 | 10730 | 10730 | 10730 | 10730 | 首次启动后不能修改 | | dn_mpp_data_exchange_port | DataNode用于接收数据流使用的端口 | 10740 | 10740 | 10740 | 10740 | 10740 | 首次启动后不能修改 | | dn_data_region_consensus_port | DataNode用于数据副本共识协议通信使用的端口 | 10750 | 10750 | 10750 | 10750 | 10750 | 首次启动后不能修改 | | dn_schema_region_consensus_port | DataNode用于元数据副本共识协议通信使用的端口 | 10760 | 10760 | 10760 | 10760 | 10760 | 首次启动后不能修改 | -| dn_seed_config_node | 节点注册加入集群时连接的ConfigNode地址,即cn_internal_address:cn_internal_port | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | +| dn_seed_config_node | 节点注册加入集群时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | 第一个CongfigNode的cn_internal_address:cn_internal_port | iotdb-1:10710 | iotdb-1:10710 | iotdb-1:10710 | 首次启动后不能修改 | + +以下示例在保留原有 IPv4/主机名配置示例的基础上，展示一台 ConfigNode 和一台 DataNode 的纯 IPv6 地址写法。`CN_IPV6_ADDRESS` 与 `DN_IPV6_ADDRESS` 分别表示两台节点实际可达的 IPv6 地址，部署时须按实际环境替换： + +```properties +# ConfigNode +cn_internal_address=CN_IPV6_ADDRESS +cn_seed_config_node=[CN_IPV6_ADDRESS]:10710 + +# DataNode +dn_internal_address=DN_IPV6_ADDRESS +dn_rpc_address=DN_IPV6_ADDRESS +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +``` + +`cn_internal_address`、`dn_internal_address` 和 `dn_rpc_address` 只填写地址，因此使用裸 IPv6。`cn_seed_config_node` 和 `dn_seed_config_node` 同时包含地址和端口，因此使用 `[ipv6]:port`。 + +节点启动后，应确认 DataNode 已成功注册到 ConfigNode。集群展示中的 IP 字段可以显示裸 IPv6；日志、错误信息和其他带端口的 endpoint 应显示为 `[ipv6]:port`。如果服务监听地址为 `::`，节点对外发布时仍必须使用实际可路由的 IPv6 地址。 > ❗️注意：VSCode Remote等编辑器无自动保存配置功能，请确保修改的文件被持久化保存，否则配置项无法生效 @@ -199,6 +218,8 @@ cd sbin .\windows\start-datanode.bat ``` +启动完成后，通过 CLI 执行 `show cluster` 检查 ConfigNode 和 DataNode 是否均已注册。纯 IPv6 环境中，节点地址字段应显示配置的裸 IPv6；日志或错误信息中同时包含地址和端口时，应显示为 `[ipv6]:port`。如果发现 `::` 被返回为节点地址，请将对外发布地址改为实际可路由的 IPv6 地址。 + ### 3.5 验证部署 可直接执行`./sbin`目录下的Cli启动脚本： @@ -213,6 +234,12 @@ cd sbin # V2.0.4.x 版本及之后 .\windows\start-cli.bat -h ip -p 6667 +``` + +IPv6 地址通过 `-h` 单独传入时不使用方括号，端口通过 `-p` 传入，例如： + +```shell +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' ``` 成功启动后，出现如下界面显示IOTDB安装成功。 diff --git a/src/zh/UserGuide/latest/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md b/src/zh/UserGuide/latest/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md index f0ace3f05..1d7142952 100644 --- a/src/zh/UserGuide/latest/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md +++ b/src/zh/UserGuide/latest/Deployment-and-Maintenance/Stand-Alone-Deployment_apache.md @@ -112,10 +112,10 @@ cd apache-iotdb-{version}-all-bin | **配置项** | **说明** | **默认** | 推荐值 | **备注** | | :-----------------: | :----------------------------------------------------------: | :-------------: | :----------------------------------------------: | :----------------: | -| cn_internal_address | ConfigNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | 首次启动后不能修改 | +| cn_internal_address | ConfigNode 在内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | 首次启动后不能修改 | | cn_internal_port | ConfigNode在集群内部通讯使用的端口 | 10710 | 10710 | 首次启动后不能修改 | | cn_consensus_port | ConfigNode副本组共识协议通信使用的端口 | 10720 | 10720 | 首次启动后不能修改 | -| cn_seed_config_node | 节点注册加入集群时连接的ConfigNode 的地址，cn_internal_address:cn_internal_port | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | +| cn_seed_config_node | 节点注册时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | #### DataNode 配置 @@ -123,14 +123,26 @@ cd apache-iotdb-{version}-all-bin | **配置项** | **说明** | **默认** | 推荐值 | **备注** | | :-----------------------------: | :----------------------------------------------------------: |:---------------:|:----------------------------------------------------------------------------:| :----------------- | -| dn_rpc_address | 客户端 RPC 服务的地址 | 127.0.0.1 | 默认本机可直接访问。非本机访问，请修改此配置项为所在服务器的IPV4地址或hostname，推荐使用所在服务器的IPV4地址。 | 重启服务生效 | +| dn_rpc_address | 客户端 RPC 服务监听地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 默认仅本机可访问；非本机访问时填写实际可路由的 IPv4 地址、裸 IPv6 地址或 hostname | 重启服务生效 | | dn_rpc_port | 客户端 RPC 服务的端口 | 6667 | 6667 | 重启服务生效 | -| dn_internal_address | DataNode在集群内部通讯使用的地址 | 127.0.0.1 | 所在服务器的IPV4地址或hostname，推荐使用hostname | 首次启动后不能修改 | +| dn_internal_address | DataNode 在内部通信使用的地址。IPv6 使用裸地址，不加方括号、不填写端口。IPv6 自 V2.0.12 起支持。 | 127.0.0.1 | 所在服务器的 IPv4 地址、裸 IPv6 地址或 hostname，推荐使用 hostname | 首次启动后不能修改 | | dn_internal_port | DataNode在集群内部通信使用的端口 | 10730 | 10730 | 首次启动后不能修改 | | dn_mpp_data_exchange_port | DataNode用于接收数据流使用的端口 | 10740 | 10740 | 首次启动后不能修改 | | dn_data_region_consensus_port | DataNode用于数据副本共识协议通信使用的端口 | 10750 | 10750 | 首次启动后不能修改 | | dn_schema_region_consensus_port | DataNode用于元数据副本共识协议通信使用的端口 | 10760 | 10760 | 首次启动后不能修改 | -| dn_seed_config_node | 节点注册加入集群时连接的ConfigNode地址,即cn_internal_address:cn_internal_port | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | +| dn_seed_config_node | 节点注册时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`；IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 | 127.0.0.1:10710 | cn_internal_address:cn_internal_port | 首次启动后不能修改 | + +仅在本机访问的单机实例可使用 IPv6 回环地址： + +```properties +cn_internal_address=::1 +cn_seed_config_node=[::1]:10710 +dn_internal_address=::1 +dn_rpc_address=::1 +dn_seed_config_node=[::1]:10710 +``` + +`::1` 是 IPv6 回环地址，只适用于本机访问或测试。需要由其他主机访问时，请改用本机实际可路由的 IPv6 地址。`::` 表示监听全部 IPv6 接口，不能作为远程连接目标、节点发现结果或客户端重定向地址。 > ❗️注意：VSCode Remote等编辑器无自动保存配置功能，请确保修改的文件被持久化保存，否则配置项无法生效 diff --git a/src/zh/UserGuide/latest/FAQ/Frequently-asked-questions.md b/src/zh/UserGuide/latest/FAQ/Frequently-asked-questions.md index f2c453202..88883b7d4 100644 --- a/src/zh/UserGuide/latest/FAQ/Frequently-asked-questions.md +++ b/src/zh/UserGuide/latest/FAQ/Frequently-asked-questions.md @@ -332,3 +332,33 @@ sudo ln -sf $(which lsof) /bin/lsof # 自动创建软链接至标准路径 - 在conf/confignode-env.sh、conf/datanode-env.sh文件可通过调整ON_HEAP_MEMORY、OFF_HEAP_MEMORY等选项可以调整ConfigNode、DataNode使用的最大堆内、堆外内存 + +## 3. IPv6 连接 FAQ + +### 3.1 为什么 `[::1]:6667` 合法，而 `::1:6667` 不应作为 endpoint 使用？ + +自 V2.0.12 起，IoTDB 支持 IPv6 连接。IPv6 地址本身包含多个冒号。地址与端口组合时必须使用 `[ipv6]:port`，这样才能明确区分地址和端口。JDBC URL、Session node URL 和 Pipe `node-urls` 中的地址与端口部分应使用 `[ipv6]:port`。 + +### 3.2 为什么地址参数使用裸 IPv6，而 JDBC 和 Pipe 使用 `[ipv6]:port`？ + +`cn_internal_address`、`dn_internal_address`、`dn_rpc_address` 等参数只填写地址，因此使用裸 IPv6；JDBC URL、seed endpoint、Session node URL 和 Pipe `node-urls` 同时包含地址和端口，因此使用 `[ipv6]:port`。 + +### 3.3 为什么服务监听 `::` 成功，但客户端仍然无法连接？ + +`::` 表示监听全部 IPv6 接口，不是可路由的远端地址。节点注册、节点发现、客户端重定向、Pipe 目标和 Prometheus target 均应使用实际可达的 IPv6 地址。 + +### 3.4 IPv6 TLS 连接提示证书主机名或 IP 校验失败怎么办？ + +检查服务端证书 SAN 是否包含客户端实际访问的裸 IPv6 `IP Address`。SAN 中不能包含方括号或端口；同时确认客户端 TrustStore 包含签发该证书的 CA。 + +### 3.5 纯 IPv6 环境连接失败如何排查？ + +依次检查操作系统 IPv6 是否启用、地址是否已绑定、节点间路由和端口是否可达、防火墙是否放行、DNS 或 `/etc/hosts` 解析是否一致，以及客户端运行时和底层 socket 是否支持 IPv6。 + +### 3.6 双栈环境中 IPv4 可用、IPv6 连接失败怎么办？ + +先使用实际的 IPv6 地址与端口按当前入口要求的格式直接连接，确认目标服务已绑定 IPv6 地址，路由和防火墙允许该端口访问；再检查 DNS 的 AAAA 记录或 `/etc/hosts` 中的 IPv6 映射是否指向目标地址。分别验证 IPv4 与 IPv6 链路，不要将 IPv4 连接成功当作 IPv6 已连通；节点对外发布地址不能使用 `::`。 + +### 3.7 Pipe 报 IPv6 endpoint 解析错误怎么办？ + +检查每个 IPv6 endpoint 是否使用 `[ipv6]:port`，多个 endpoint 是否使用英文逗号分隔，是否误将 `::` 或 `0.0.0.0` 作为目标。SSL Pipe 还需检查 TrustStore、KeyStore 和目标证书 SAN。 diff --git a/src/zh/UserGuide/latest/Reference/System-Config-Manual_apache.md b/src/zh/UserGuide/latest/Reference/System-Config-Manual_apache.md index 01d5a7e7b..20c30ecbb 100644 --- a/src/zh/UserGuide/latest/Reference/System-Config-Manual_apache.md +++ b/src/zh/UserGuide/latest/Reference/System-Config-Manual_apache.md @@ -121,11 +121,15 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 ### 3.2 SeedConfigNode 配置 +> 只填写地址的参数使用裸 IPv6；同时包含地址和端口的 endpoint 使用 `[ipv6]:port`。 + +下文的 `CN_IPV6_ADDRESS` 仅用于标示 ConfigNode 的 IPv6 地址填写位置；实际配置时应填写可解析、可路由的地址。原有 IPv4/主机名示例及默认值保持不变。 + - cn_seed_config_node | 名字 | cn_seed_config_node | | ------------ | ------------------------------------------------------------ | -| 描述 | 目标 ConfigNode 地址，ConfigNode 通过此地址加入集群，推荐使用 SeedConfigNode。V1.2.2 及以前曾用名是 cn_target_config_node_list | +| 描述 | 目标 ConfigNode 的 endpoint，ConfigNode 通过此地址加入集群，推荐使用 SeedConfigNode。支持 `ipv4:port`、`hostname:port` 或 `[ipv6]:port`，例如 `[CN_IPV6_ADDRESS]:10710`。V1.2.2 及以前曾用名是 cn_target_config_node_list。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1:10710 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | @@ -134,7 +138,7 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | dn_seed_config_node | | ------------ | ------------------------------------------------------------ | -| 描述 | ConfigNode 地址，DataNode 启动时通过此地址加入集群，推荐使用 SeedConfigNode。V1.2.2 及以前曾用名是 dn_target_config_node_list | +| 描述 | ConfigNode 的 endpoint，DataNode 启动时通过此地址加入集群，推荐使用 SeedConfigNode。支持 `ipv4:port`、`hostname:port` 或 `[ipv6]:port`，例如 `[CN_IPV6_ADDRESS]:10710`。V1.2.2 及以前曾用名是 dn_target_config_node_list。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1:10710 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | @@ -145,7 +149,7 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | cn_internal_address | | ------------ | ---------------------------- | -| 描述 | ConfigNode 集群内部地址 | +| 描述 | ConfigNode 集群内部通信地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口，不使用方括号，例如 `192.168.1.10`、`CN_IPV6_ADDRESS` 或 `iotdb-cn-1`。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | @@ -172,7 +176,7 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | dn_rpc_address | | ------------ |----------------| -| 描述 | 客户端 RPC 服务监听地址 | +| 描述 | 客户端 RPC 服务监听地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口，不使用方括号，例如 `192.168.1.20`、`DN_IPV6_ADDRESS` 或 `iotdb-dn-1`。使用 `::` 可监听全部 IPv6 接口，但 `::` 不能作为客户端重定向或节点发现返回的远端连接地址。IPv6 自 V2.0.12 起支持。 | | 类型 | String | | 默认值 | 127.0.0.1 | | 改后生效方式 | 重启服务生效 | @@ -190,11 +194,15 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 | 名字 | dn_internal_address | | ------------ | ---------------------------- | -| 描述 | DataNode 内网通信地址 | +| 描述 | DataNode 内部通信地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口，不使用方括号，例如 `192.168.1.20`、`DN_IPV6_ADDRESS` 或 `iotdb-dn-1`。IPv6 自 V2.0.12 起支持。 | | 类型 | string | | 默认值 | 127.0.0.1 | | 改后生效方式 | 仅允许在第一次启动服务前修改 | +> 当地址参数只填写 IPv6 地址时，应使用裸 IPv6，例如 `DN_IPV6_ADDRESS`；当地址和端口组合为 endpoint 时，应使用 `[ipv6]:port`，例如 `[DN_IPV6_ADDRESS]:10730`。`0.0.0.0` 和 `::` 仅用于监听全部接口，不能作为远端连接目标。 + +下文的 `DN_IPV6_ADDRESS` 仅用于标示 DataNode 的 IPv6 地址填写位置，实际配置时应替换为相应节点已绑定且可达的地址。 + - dn_internal_port | 名字 | dn_internal_port | @@ -500,6 +508,8 @@ IoTDB 配置文件位于 IoTDB 安装目录：`conf`文件夹下。 ### 3.7 SSL 配置 +> IPv6 不改变现有 SSL/TLS 开关、协议、KeyStore 和 TrustStore 配置。通过 IPv6 地址访问 DataNode 并启用主机身份校验时，服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`，不包含方括号和端口。例如，客户端连接 `[DN_IPV6_ADDRESS]:6667` 时，证书 SAN 中应包含 `DN_IPV6_ADDRESS`。 + - enable_thrift_ssl | 名字 | enable_thrift_ssl | diff --git a/src/zh/UserGuide/latest/Tools-System/CLI_apache.md b/src/zh/UserGuide/latest/Tools-System/CLI_apache.md index 7f85819a8..a4a588b8d 100644 --- a/src/zh/UserGuide/latest/Tools-System/CLI_apache.md +++ b/src/zh/UserGuide/latest/Tools-System/CLI_apache.md @@ -69,11 +69,21 @@ Successfully login at 127.0.0.1:6667 ``` 输入`quit`或`exit`可退出 cli 结束本次会话，cli 输出`quit normally`表示退出成功。 +自 V2.0.12 起，IPv6 地址通过 `-h` 单独传入时使用裸地址，不加方括号；端口通过 `-p` 单独传入。示例中的 `DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前应替换为实际可达的 IPv6 地址；原 IPv4 启动示例保留。例如： + +```shell +# Linux/macOS +bash sbin/start-cli.sh -h DN_IPV6_ADDRESS -p 6667 -u root -pw '' + +# Windows（V2.0.4.x 及之后） +sbin\windows\start-cli.bat -h DN_IPV6_ADDRESS -p 6667 -u root -pw "" +``` + ### 2.2 Cli 运行参数 | **参数名** | **参数类型** | **是否为必需参数** | **说明** | **示例** | |:-----------------------------|:-----------|:------------|:-----------------------------------------------------------|:---------------------| -| -h `` | string 类型 | 否 | IoTDB 客户端连接 IoTDB 服务器的 IP 地址， 默认使用：127.0.0.1。 | -h 127.0.0.1 | +| -h `` | string 类型 | 否 | IoTDB 客户端连接服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号，默认使用 `127.0.0.1`。IPv6 自 V2.0.12 起支持。 | -h 127.0.0.1 | | -p `` | int 类型 | 否 | IoTDB 客户端连接服务器的端口号，IoTDB 默认使用 6667。 | -p 6667 | | -u `` | string 类型 | 否 | IoTDB 客户端连接服务器所使用的用户名，默认使用 root。 | -u root | | -pw `` | string 类型 | 否 | IoTDB 客户端连接服务器所使用的密码，默认使用 root。 | -pw root | @@ -191,4 +201,3 @@ It costs 0.267s ``` 需要特别注意的是，在脚本中使用 -e 参数时要对特殊字符进行转义。 - diff --git a/src/zh/UserGuide/latest/Tools-System/Data-Export-Tool_apache.md b/src/zh/UserGuide/latest/Tools-System/Data-Export-Tool_apache.md index d7beab7ff..511ca48ca 100644 --- a/src/zh/UserGuide/latest/Tools-System/Data-Export-Tool_apache.md +++ b/src/zh/UserGuide/latest/Tools-System/Data-Export-Tool_apache.md @@ -34,7 +34,7 @@ | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | |----------|-------------------------|----------------------------------------------------| -------------- |---------------------------------------------------------------------------| | -ft | --file\_type | 导出文件的类型，可以选择：csv、sql、tsfile | √ | | -| -h | --host | 主机名 | 否 | 127.0.0.1 | +| -h | --host | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | -p | --port | 端口号 | 否 | 6667 | | -u | --username | 用户名 | 否 | root | | -pw | --password | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -47,6 +47,8 @@ | -ts | --trust_store | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | -tpw | --trust_store_password | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。`DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前须替换为实际可达的裸 IPv6；不要把带方括号的地址作为 `-h` 的值。启用 SSL 时，继续使用本页现有的 `-usessl`、`-ts` 和 `-tpw` 参数；服务端证书 SAN 必须包含实际访问的裸 IPv6 地址。 + ### 2.2 Csv 格式 #### 2.2.1 运行命令 diff --git a/src/zh/UserGuide/latest/Tools-System/Data-Import-Tool_apache.md b/src/zh/UserGuide/latest/Tools-System/Data-Import-Tool_apache.md index f4682a46b..7ef75e32f 100644 --- a/src/zh/UserGuide/latest/Tools-System/Data-Import-Tool_apache.md +++ b/src/zh/UserGuide/latest/Tools-System/Data-Import-Tool_apache.md @@ -44,7 +44,7 @@ IoTDB 支持三种方式进行数据导入： | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | | ---------- |---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| -------------- |---------------------------| | -ft | --file\_type | 导入文件的类型，可以选择：csv、sql、tsfile | √ | | -| -h | --host | 主机名 | 否 | 127.0.0.1 | +| -h | --host | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | -p | --port | 端口号 | 否 | 6667 | | -u | --username | 用户名 | 否 | root | | -pw | --password | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -56,6 +56,7 @@ IoTDB 支持三种方式进行数据导入： | -ts | --trust_store | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | -tpw | --trust_store_password | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。`DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前须替换为实际可达的裸 IPv6；不要把带方括号的地址作为 `-h` 的值。启用 SSL 时，继续使用本页现有的 `-usessl`、`-ts` 和 `-tpw` 参数；服务端证书 SAN 必须包含实际访问的裸 IPv6 地址。 ### 2.2 CSV 格式 diff --git a/src/zh/UserGuide/latest/Tools-System/Monitor-Tool_apache.md b/src/zh/UserGuide/latest/Tools-System/Monitor-Tool_apache.md index 28ce6587d..e3cfaeecc 100644 --- a/src/zh/UserGuide/latest/Tools-System/Monitor-Tool_apache.md +++ b/src/zh/UserGuide/latest/Tools-System/Monitor-Tool_apache.md @@ -60,6 +60,12 @@ file_count{name="seq",} 2.0 ... ``` +自 V2.0.12 起，监控 metrics 接口支持通过 IPv6 地址访问。访问 IPv6 metrics URL 时，地址和端口之间应使用方括号区分；将下方占位符替换为实际可达的 IPv6 地址： + +```shell +curl 'http://[IPV6_ADDRESS]:9091/metrics' +``` + ## 3. Prometheus + Grafana 如上所示，IoTDB 对外暴露出标准的 Prometheus 格式的监控指标数据，可以使用 Prometheus 采集并存储监控指标，使用 Grafana @@ -90,6 +96,7 @@ follow_redirects: true static_configs: - targets: - localhost:9091 + - '[IPV6_ADDRESS]:9091' ``` 更多细节可以参考下面的文档： @@ -101,3 +108,4 @@ static_configs: [Grafana安装使用文档](https://grafana.com/docs/grafana/latest/getting-started/getting-started/) [Grafana从Prometheus查询数据并绘图的文档](https://prometheus.io/docs/visualization/grafana/#grafana-support-for-prometheus) +Prometheus target 同时包含 IPv6 地址和端口，应使用 `[ipv6]:port`。即使服务监听地址配置为 `::`，target 也应填写实际可路由的 IPv6 地址，不能填写 `[::]:9091`。 diff --git a/src/zh/UserGuide/latest/Tools-System/Schema-Export-Tool_apache.md b/src/zh/UserGuide/latest/Tools-System/Schema-Export-Tool_apache.md index 84608543f..73b5b9f63 100644 --- a/src/zh/UserGuide/latest/Tools-System/Schema-Export-Tool_apache.md +++ b/src/zh/UserGuide/latest/Tools-System/Schema-Export-Tool_apache.md @@ -31,7 +31,7 @@ | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | | --------------------- |---------------------------| ------------------------------------------------------------------------ | ----------------------------------- |---------------------------------------| -| `-h` | `--host` | 主机名 | 否 | 127.0.0.1 | +| `-h` | `--host` | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | `-p` | `--port` | 端口号 | 否 | 6667 | | `-u` | `--username` | 用户名 | 否 | root | | `-pw` | `--password` | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -48,6 +48,8 @@ | `-ts` | `--trust_store` | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | `-tpw` | `--trust_store_password ` | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。`DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前须替换为实际可达的裸 IPv6；不要把带方括号的地址作为 `-h` 的值。启用 SSL 时，继续使用本页现有的 `-usessl`、`-ts` 和 `-tpw` 参数，并确认证书 SAN 包含实际访问的 IPv6 地址。 + ### 2.2 运行命令 ```Bash @@ -82,3 +84,5 @@ Timeseries,Alias,DataType,Encoding,Compression root.treedb.device.temperature,,DOUBLE,GORILLA,LZ4 root.treedb.device.humidity,,DOUBLE,GORILLA,LZ4 ``` + +自 V2.0.12 起，`-h` 可填写实际的裸 IPv6 地址，`-p` 继续单独传入端口；原命令中的 `-sql_dialect`、`-db`、`-s`、`-t`、`-path` 等参数无需为 IPv6 改动。 diff --git a/src/zh/UserGuide/latest/Tools-System/Schema-Import-Tool_apache.md b/src/zh/UserGuide/latest/Tools-System/Schema-Import-Tool_apache.md index 681dbf816..c6fa02277 100644 --- a/src/zh/UserGuide/latest/Tools-System/Schema-Import-Tool_apache.md +++ b/src/zh/UserGuide/latest/Tools-System/Schema-Import-Tool_apache.md @@ -31,7 +31,7 @@ | 参数缩写 | 参数全称 | 参数含义 | 是否为必填项 | 默认值 | | --------------------- |-----------------------------| ----------------------------------------------------------------------------- | -------------- |-----------------------------------| -| `-h` | `--host` | 主机名 | 否 | 127.0.0.1 | +| `-h` | `--host` | 数据库服务器的 IPv4 地址、裸 IPv6 地址或主机名；IPv6 不加方括号。IPv6 自 V2.0.12 起支持。 | 否 | 127.0.0.1 | | `-p` | `--port` | 端口号 | 否 | 6667 | | `-u` | `--username` | 用户名 | 否 | root | | `-pw` | `--password` | 密码，自 V2.0.10 起支持隐藏输入 | 否 | root | @@ -46,6 +46,8 @@ | `-ts` | `--trust_store` | 信任库。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | | `-tpw` | `--trust_store_password` | 信任库密码。支持隐藏输入，自 V2.0.10 起支持 | 否 | - | +`-h` 和 `-p` 分别接收 host 和 port，因此 IPv6 host 使用裸地址，例如 `-h DN_IPV6_ADDRESS -p 6667`。`DN_IPV6_ADDRESS` 是目标 DataNode 的地址占位符，运行前须替换为实际可达的裸 IPv6；不要把带方括号的地址作为 `-h` 的值。启用 SSL 时，继续使用本页现有的 `-usessl`、`-ts` 和 `-tpw` 参数，并确认证书 SAN 包含实际访问的 IPv6 地址。 + ### 2.2 运行命令 ```Bash @@ -88,3 +90,5 @@ IoTDB> show timeseries root.treedb.** | root.treedb.device.humidity| null|root.treedb| DOUBLE| GORILLA| LZ4|null| null| null| null| BASE| +------------------------------+-----+-----------+--------+--------+-----------+----+----------+--------+------------------+--------+ ``` + +自 V2.0.12 起，`-h` 可填写实际的裸 IPv6 地址，`-p` 继续单独传入端口；原命令中的 `-sql_dialect`、`-db`、`-s`、`-t`、`-path` 等参数无需为 IPv6 改动。 diff --git a/src/zh/UserGuide/latest/User-Manual/Data-Sync_apache.md b/src/zh/UserGuide/latest/User-Manual/Data-Sync_apache.md index 0da6bb54c..f7f2f54b0 100644 --- a/src/zh/UserGuide/latest/User-Manual/Data-Sync_apache.md +++ b/src/zh/UserGuide/latest/User-Manual/Data-Sync_apache.md @@ -372,6 +372,16 @@ with sink ( ) ``` +```sql +create pipe A2B_IPV6 +with sink ( + 'sink'='iotdb-thrift-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667' +) +``` + +自 V2.0.12 起，Pipe 支持使用 IPv6 endpoint 连接目标端 IoTDB。`node-urls` 同时包含地址和端口，IPv6 使用 `[ipv6]:port`；多个 endpoint 使用英文逗号分隔。上方独立示例中的 `DN_IPV6_ADDRESS` 和 `DN_IPV6_ADDRESS_2` 分别表示目标端两个 DataNode 的实际可达 IPv6 地址，使用前须替换；原有 Pipe 示例不变。 + ### 3.2 部分数据同步 本例子用来演示同步某个历史时间范围（ 2023 年 8 月 23 日 8 点到 2023 年 10 月 23 日 8 点）的数据至另一个 IoTDB，数据链路如下图所示： @@ -536,6 +546,18 @@ with sink ( - `ssl.trust-store-path`: 连接目标端 DataNode 所需的 trust store 证书路径 - `ssl.trust-store-pwd`: 连接目标端 DataNode 所需的 trust store 证书密码 +```sql +create pipe A2B_SSL_IPV6 +with sink ( + 'sink'='iotdb-thrift-ssl-sink', + 'node-urls'='[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667', + 'ssl.trust-store-path'='pki/trusted', + 'ssl.trust-store-pwd'='' +) +``` + +通过 IPv6 地址进行 TLS 主机身份校验时，目标 DataNode 的服务端证书 SAN 必须包含客户端实际访问的裸 IPv6 `IP Address`，不包含方括号和端口。 + ## 4. 参考：注意事项 可通过修改 IoTDB 配置文件（`iotdb-system.properties`）以调整数据同步的参数，如同步数据存储目录等。完整配置如下：： @@ -631,7 +653,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **参数** | **描述** | **value 取值范围** | **是否必填** | **默认取值** | |------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|----------|--------------| | sink | iotdb-thrift-sink 或 iotdb-thrift-async-sink | String: iotdb-thrift-sink 或 iotdb-thrift-async-sink | 必填 | - | -| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务端口的 url（请注意同步任务不支持向自身服务进行转发） | String. 例：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | 必填 | - | +| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务 endpoint（同步任务不支持向自身服务转发）。IPv6 使用 `[ipv6]:port`，多个 endpoint 使用英文逗号分隔。IPv6 自 V2.0.12 起支持。 | String。示例：`'127.0.0.1:6667,127.0.0.1:6668'`、`'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | 必填 | - | | user/username | 连接接收端使用的用户名，同步要求该用户具备相应的操作权限 | String | 选填 | root | | password | 连接接收端使用的用户名对应的密码，同步要求该用户具备相应的操作权限 | String | 选填 | root | | batch.enable | 是否开启日志攒批发送模式，用于提高传输吞吐，降低 IOPS | Boolean: true, false | 选填 | true | @@ -650,7 +672,7 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | **参数** | **描述** | **value 取值范围** | **是否必填** | **默认取值** | |------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| -------- | ------------ | | sink | iotdb-thrift-ssl-sink | String: iotdb-thrift-ssl-sink | 必填 | - | -| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务端口的 url（请注意同步任务不支持向自身服务进行转发） | String. 例：'127.0.0.1：6667，127.0.0.1：6668，127.0.0.1：6669'， '127.0.0.1：6667' | 必填 | - | +| node-urls | 目标端 IoTDB 任意多个 DataNode 节点的数据服务 endpoint（同步任务不支持向自身服务转发）。IPv6 使用 `[ipv6]:port`，多个 endpoint 使用英文逗号分隔；目标证书 SAN 必须覆盖实际连接地址。IPv6 自 V2.0.12 起支持。 | String。示例：`'127.0.0.1:6667,127.0.0.1:6668'`、`'[DN_IPV6_ADDRESS]:6667,[DN_IPV6_ADDRESS_2]:6667'` | 必填 | - | | user/username | 连接接收端使用的用户名，同步要求该用户具备相应的操作权限 | String | 选填 | root | | password | 连接接收端使用的用户名对应的密码，同步要求该用户具备相应的操作权限 | String | 选填 | root | | batch.enable | 是否开启日志攒批发送模式，用于提高传输吞吐，降低 IOPS | Boolean: true, false | 选填 | true | @@ -665,4 +687,3 @@ pipe_all_sinks_rate_limit_bytes_per_second=-1 | ssl.trust-store-pwd | 连接目标端 DataNode 所需的 trust store 证书密码 | String: 'root' | 必填 | - | | format | 数据传输的payload格式， 可选项包括：
- hybrid： 取决于 processor 传递过来的格式（tsfile或tablet），sink不做任何转换。
- tsfile：强制转换成tsfile发送，可用于数据文件备份等场景。
- tablet：强制转换成tsfile发送，可用于发送端/接收端数据类型不完全兼容时的数据同步（以减少报错）。 | String: hybrid / tsfile / tablet | 选填 | hybrid | | exception.data.convert-on-type-mismatch | 接收端类型不同时是否转换 | Boolean: true / false | 选填 | true | - diff --git a/src/zh/UserGuide/latest/User-Manual/Load-Balance_apache.md b/src/zh/UserGuide/latest/User-Manual/Load-Balance_apache.md index 0580404da..cbae6dd68 100644 --- a/src/zh/UserGuide/latest/User-Manual/Load-Balance_apache.md +++ b/src/zh/UserGuide/latest/User-Manual/Load-Balance_apache.md @@ -116,6 +116,8 @@ IoTDB 集群扩容的核心是增加 DataNode 节点，因为 DataNode 是处理 echo "192.168.1.3 iotdb-1" >> /etc/hosts ``` +7. IPv6 网络检查：使用双栈或纯 IPv6 网络扩容时，确认新旧节点之间的 IPv6 路由和所需端口可达，DNS 或 `/etc/hosts` 解析一致，配置的 IPv6 地址已绑定到对应网卡。`0.0.0.0` 和 `::` 仅用于监听，不能作为新节点注册到集群时使用的远端地址。 + #### 2.2.2 扩容操作 1. 为确保您获取的 IoTDB 安装包完整且正确，在执行安装部署前建议您进行 SHA512 校验。 @@ -136,15 +138,25 @@ vim iotdb-system.properies |配置项|说明|默认|备注| |---|---|---|---| -|dn\_seed\_config\_node|节点注册加入集群时连接的 ConfigNode 地址,即 cn\_internal\_address:cn\_internal\_port|127\.0\.0\.1:10710
|非常重要，强制修改此项，将其改为原集群 ConfigNode 主节点的地址
| -|dn\_rpc\_address|客户端 RPC 服务的地址|0\.0\.0\.0|按需修改，重启服务生效| +|dn\_seed\_config\_node| 节点注册加入集群时连接的 ConfigNode endpoint，即 `cn_internal_address:cn_internal_port`。IPv6 使用 `[ipv6]:port`。IPv6 自 V2.0.12 起支持。 |127\.0\.0\.1:10710
|非常重要，强制修改此项，将其改为原集群 ConfigNode 主节点的地址
| +|dn\_rpc\_address| 客户端 RPC 服务监听地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 |0\.0\.0\.0|按需修改，重启服务生效| |dn\_rpc\_port|客户端 RPC 服务的端口|6667|按需修改，重启服务生效| -|dn\_internal\_address|DataNode 在集群内部通讯使用的地址|127\.0\.0\.1|按需修改，首次启动后不能修改| +|dn\_internal\_address| DataNode 集群内部通信地址。支持裸 IPv4、裸 IPv6 或主机名，不填写端口、不使用方括号。IPv6 自 V2.0.12 起支持。 |127\.0\.0\.1|按需修改，首次启动后不能修改| |dn\_internal\_port|DataNode 在集群内部通信使用的端口|10730|按需修改，首次启动后不能修改| |dn\_mpp\_data\_exchange\_port|DataNode 用于接收数据流使用的端口|10740|按需修改，首次启动后不能修改| |dn\_data\_region\_consensus\_port|DataNode 用于数据副本共识协议通信使用的端口|10750|按需修改，首次启动后不能修改| |dn\_schema\_region\_consensus\_port|DataNode 用于元数据副本共识协议通信使用的端口|10760|按需修改，首次启动后不能修改| +纯 IPv6 扩容示例： + +```properties +dn_seed_config_node=[CN_IPV6_ADDRESS]:10710 +dn_rpc_address=NEW_DN_IPV6_ADDRESS +dn_internal_address=NEW_DN_IPV6_ADDRESS +``` + +其中 `CN_IPV6_ADDRESS` 为原集群 ConfigNode 的可达 IPv6 地址，`NEW_DN_IPV6_ADDRESS` 为新节点已绑定且可路由的 IPv6 地址；应用配置前须替换。新节点启动后执行 `show datanodes`，确认新节点状态为 `Running`，地址字段显示配置的裸 IPv6。若返回 `::`，应将对外发布地址改为实际可路由的 IPv6 地址。 + 4. 启动 DataNode 节点 进入 IoTDB 的 sbin 目录下，启动 Datanode：