This is an automated email from the ASF dual-hosted git repository.
critas pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/iotdb-docs.git
The following commit(s) were added to refs/heads/main by this push:
new 5366abe5 opc ua upgrade from 208 (#991)
5366abe5 is described below
commit 5366abe577db0edd4691ee02b4eac65aacc6fa69
Author: leto-b <[email protected]>
AuthorDate: Wed Feb 4 12:00:28 2026 +0800
opc ua upgrade from 208 (#991)
---
src/.vuepress/public/img/opc-ua-data-push-en.png | Bin 0 -> 84975 bytes
.../public/img/opc-ua-data-push-example-en.png | Bin 0 -> 263961 bytes
.../public/img/opc-ua-data-push-example.png | Bin 0 -> 247269 bytes
src/.vuepress/public/img/opc-ua-data-push.png | Bin 0 -> 80088 bytes
.../Master/Tree/API/Programming-OPC-UA_timecho.md | 348 ++++++++++++---------
.../latest/API/Programming-OPC-UA_timecho.md | 348 ++++++++++++---------
.../Master/Tree/API/Programming-OPC-UA_timecho.md | 199 ++++++++++--
.../latest/API/Programming-OPC-UA_timecho.md | 199 ++++++++++--
8 files changed, 756 insertions(+), 338 deletions(-)
diff --git a/src/.vuepress/public/img/opc-ua-data-push-en.png
b/src/.vuepress/public/img/opc-ua-data-push-en.png
new file mode 100644
index 00000000..ab8c4ec5
Binary files /dev/null and b/src/.vuepress/public/img/opc-ua-data-push-en.png
differ
diff --git a/src/.vuepress/public/img/opc-ua-data-push-example-en.png
b/src/.vuepress/public/img/opc-ua-data-push-example-en.png
new file mode 100644
index 00000000..16c587c5
Binary files /dev/null and
b/src/.vuepress/public/img/opc-ua-data-push-example-en.png differ
diff --git a/src/.vuepress/public/img/opc-ua-data-push-example.png
b/src/.vuepress/public/img/opc-ua-data-push-example.png
new file mode 100644
index 00000000..5be0f41e
Binary files /dev/null and
b/src/.vuepress/public/img/opc-ua-data-push-example.png differ
diff --git a/src/.vuepress/public/img/opc-ua-data-push.png
b/src/.vuepress/public/img/opc-ua-data-push.png
new file mode 100644
index 00000000..e95d72b8
Binary files /dev/null and b/src/.vuepress/public/img/opc-ua-data-push.png
differ
diff --git a/src/UserGuide/Master/Tree/API/Programming-OPC-UA_timecho.md
b/src/UserGuide/Master/Tree/API/Programming-OPC-UA_timecho.md
index 47a6ce5b..80b5446b 100644
--- a/src/UserGuide/Master/Tree/API/Programming-OPC-UA_timecho.md
+++ b/src/UserGuide/Master/Tree/API/Programming-OPC-UA_timecho.md
@@ -21,223 +21,291 @@
# OPC UA Protocol
-## 1. OPC UA Subscription Data
+## 1. Overview
-This feature allows users to subscribe to data from IoTDB using the OPC UA
protocol. The communication modes for subscription data support both
Client/Server and Pub/Sub.
+This document describes two independent operational modes for IoTDB's
integration with the OPC UA protocol. Choose the mode based on your business
scenario:
-Note: This feature is not about collecting data from external OPC Servers and
writing it into IoTDB.
+* **Mode 1: Data Subscription Service (IoTDB as OPC UA Server)**: IoTDB starts
an embedded OPC UA server to passively allow external clients (e.g., UAExpert)
to connect and subscribe to its internal data. This is the traditional usage.
+* **Mode 2: Data Push (IoTDB as OPC UA Client)**: IoTDB acts as a client to
actively synchronize data and metadata to one or more independently deployed
external OPC UA servers.
+ > Note: This mode is supported starting from V2.0.8.
-
+**Note: Modes are mutually exclusive**
+When the Pipe configuration specifies the `node-urls` parameter (Mode 2),
IoTDB will **not** start the embedded OPC UA server (Mode 1). These two modes
**cannot be used simultaneously** within the same Pipe.
+
+## 2. Data Subscription
+
+This mode supports users subscribing to data from IoTDB using the OPC UA
protocol, with communication modes supporting both Client/Server and Pub/Sub.
+
+Note: This feature does **not** involve collecting data from external OPC
Servers into IoTDB.
-## 2. OPC Service Startup Method
+
-### 2.1 Syntax
+### 2.1 OPC Service Startup
-The syntax to start the OPC UA protocol:
+#### 2.1.1 Syntax
+Syntax for starting OPC UA protocol:
```SQL
-create pipe p1
- with source (...)
- with processor (...)
- with sink ('sink' = 'opc-ua-sink',
+CREATE PIPE p1
+ WITH SOURCE (...)
+ WITH PROCESSOR (...)
+ WITH SINK ('sink' = 'opc-ua-sink',
'sink.opcua.tcp.port' = '12686',
'sink.opcua.https.port' = '8443',
'sink.user' = 'root',
- 'sink.password' = 'TimechoDB@2021', //Before V2.0.6.x the
default password is root
+ 'sink.password' = 'TimechoDB@2021', // Default password was
'root' before V2.0.6.x
'sink.opcua.security.dir' = '...'
)
```
-### 2.2 Parameters
-
-| key | value
| value range | required or not
| default value
|
-| :------------------------------ |
:----------------------------------------------------------- |
:------------------------------------- | :-------
|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| sink | OPC UA SINK |
String: opc-ua-sink | Required |
|
-| sink.opcua.model | OPC UA model used |
String: client-server / pub-sub | Optional | pub-sub
|
-| sink.opcua.tcp.port | OPC UA's TCP port |
Integer: [0, 65536] | Optional | 12686
|
-| sink.opcua.https.port | OPC UA's HTTPS port |
Integer: [0, 65536] | Optional | 8443
|
-| sink.opcua.security.dir | Directory for OPC UA's keys and
certificates | String: Path, supports absolute and relative
directories | Optional | Opc_security folder/<httpsPort: tcpPort>in the
conf directory of the DataNode related to iotdb <br> If there is no conf
directory for iotdb (such as launching DataNode in IDEA), it will be the
iotdb_opc_Security folder/<httpsPort: tcpPort>in the user's home directory |
-| sink.opcua.enable-anonymous-access | Whether OPC UA allows anonymous access
| Boolean | Optional | true
|
-| sink.user | User for OPC UA, specified in the
configuration | String | Optional | root
|
-| sink.password | Password for OPC UA, specified in the
configuration | String | Optional |
TimechoDB@2021 //Before V2.0.6.x the default password is root
|
-
-### 2.3 Example
+#### 2.1.2 Parameters
+
+| **Parameter** | **Description**
[...]
+| ------------------------------------ |
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| sink | OPC UA SINK
[...]
+| sink.opcua.model | OPC UA operational mode
[...]
+| sink.opcua.tcp.port | OPC UA TCP port
[...]
+| sink.opcua.https.port | OPC UA HTTPS port
[...]
+| sink.opcua.security.dir | OPC UA key and certificate directory
[...]
+| opcua.security-policy | Security policy used for OPC UA
connections (case-insensitive). Multiple policies can be configured and
separated by commas. After configuring one policy, clients can only connect
using that policy. Default implementation supports `None` and `Basic256Sha256`.
Should be set to a non-`None` policy by default. `None` policy is only for
debugging (convenient but insecure; not recommended for production). Note:
Supported since V2.0.8, only for client-ser [...]
+| sink.opcua.enable-anonymous-access | Whether OPC UA allows anonymous access
[...]
+| sink.user | User (OPC UA allowed user)
[...]
+| sink.password | Password (OPC UA allowed password)
[...]
+| opcua.with-quality | Whether OPC UA publishes data in value
+ quality mode. When enabled, system processes data as follows:1. Both value
and quality present → Push directly to OPC UA Server.2. Only value present →
Quality automatically filled as UNCERTAIN (default, configurable).3. Only
quality present → Ignore write (no processing).4. Non-value/quality fields
present → Ignore data and log warning (configurable log frequency to avoid
high-frequency interference).5. Qual [...]
+| opcua.value-name | Effective when `with-quality` = true,
specifies the name of the value point. **Note**: Supported since V2.0.8, only
for client-server mode
[...]
+| opcua.quality-name | Effective when `with-quality` = true,
specifies the name of the quality point. **Note**: Supported since V2.0.8, only
for client-server mode
[...]
+| opcua.default-quality | When no quality is provided, specify
`GOOD`/`UNCERTAIN`/`BAD` via SQL parameter. **Note**: Supported since V2.0.8,
only for client-server mode
[...]
+| opcua.timeout-seconds | Client connection timeout in seconds
(effective only when IoTDB acts as client). **Note**: Supported since V2.0.8,
only for client-server mode
[...]
+
+#### 2.1.3 Example
```Bash
-create pipe p1
- with sink ('sink' = 'opc-ua-sink'，
+CREATE PIPE p1
+ WITH SINK ('sink' = 'opc-ua-sink',
'sink.user' = 'root',
- 'sink.password' = 'TimechoDB@2021' //Before V2.0.6.x the
default password is root
-start pipe p1;
+ 'sink.password' = 'TimechoDB@2021'); // Default password was
'root' before V2.0.6.x
+START PIPE p1;
```
-### 2.4 Usage Limitations
-
-1. After starting the protocol, data needs to be written to establish a
connection. Only data after the connection is established can be subscribed to.
-2. Recommended for use in standalone mode. In distributed mode, each IoTDB
DataNode acts as an independent OPC Server providing data and requires separate
subscription.
+#### 2.1.4 Usage Restrictions
-## 3. Examples of Two Communication Modes
+1. Data must be written after protocol startup to establish connection. Only
data written *after* connection can be subscribed.
+2. Recommended for single-node mode. In distributed mode, each IoTDB DataNode
acts as an independent OPC Server; separate subscriptions are required for each.
-### 3.1 Client / Server Mode
+### 2.2 Example of Two Communication Modes
-In this mode, IoTDB's stream processing engine establishes a connection with
the OPC UA Server via an OPC UA Sink. The OPC UA Server maintains data within
its Address Space, from which IoTDB can request and retrieve data.
Additionally, other OPC UA Clients can access the data on the server.
+#### 2.2.1 Client/Server Mode
-* Features:
- * OPC UA organizes device information received from the Sink into folders
under the Objects folder according to a tree model.
- * Each measurement point is recorded as a variable node, storing the latest
value from the current database.
- * OPC UA cannot delete data or change data type settings.
+In this mode, IoTDB's stream processing engine establishes a connection with
the OPC UA Server (Server) via OPC UA Sink. The OPC UA Server maintains data in
its address space (Address Space), and IoTDB can request and retrieve this
data. Other OPC UA clients (Clients) can also access the server's data.
-#### 3.1.1 Preparation Work
+* **Features**:
+ * OPC UA organizes device information received from Sink into folders
under Objects folder in tree structure.
+ * Each point is recorded as a variable node with the latest value in the
current database.
+ * OPC UA cannot delete data or change data type settings.
-1. Take UAExpert client as an example, download the UAExpert client:
https://www.unified-automation.com/downloads/opc-ua-clients.html
+##### 2.2.1.1 Preparation
-2. Install UAExpert and fill in your own certificate information.
+1. Example using UAExpert client: Download UAExpert client from
https://www.unified-automation.com/downloads/opc-ua-clients.html
+2. Install UAExpert and configure certificate information.
-#### 3.1.2 Quick Start
+##### 2.2.1.2 Quick Start
-1. Use the following SQL to create and start the OPC UA Sink in client-server
mode. For detailed syntax, please refer to: [IoTDB OPC Server
Syntax](./Programming-OPC-UA_timecho.md#_2-1-syntax)
+1. Start OPC UA service using SQL (detailed syntax see [IoTDB OPC Server
Syntax](./Programming-OPC-UA_timecho.md#_2-1-语法)):
```SQL
-create pipe p1 with sink ('sink'='opc-ua-sink');
+CREATE PIPE p1 WITH SINK ('sink'='opc-ua-sink');
```
-2. Write some data.
+2. Write some data:
```SQL
-insert into root.test.db(time, s2) values(now(), 2)
+INSERT INTO root.test.db(time, s2) VALUES(NOW(), 2);
```
- The metadata is automatically created and enabled here.
+3. Configure UAExpert to connect to IoTDB (password matches `sink.password`
configured above, e.g., root/TimechoDB@2021):
+4. Trust the server certificate, then view written data under Objects folder
on the left:
+5. Drag left nodes to the middle to display latest value:
-3. Configure the connection to IoTDB in UAExpert, where the password should be
set to the one defined in the sink.password parameter (using the default
password "root" as an example):
+#### 2.2.2 Pub/Sub Mode
-<div align="center">
- <img src="/img/OPCUA18.png" alt="" style="width: 60%;"/>
-</div>
+In this mode, IoTDB's stream processing engine sends data change events to the
OPC UA Server (Server) via OPC UA Sink. These events are published to the
server's message queue and managed via Event Nodes. Other OPC UA clients
(Clients) can subscribe to these Event Nodes to receive notifications when data
changes.
-<div align="center">
- <img src="/img/OPCUA04.png" alt="" style="width: 60%;"/>
-</div>
+* **Features**:
-4. After trusting the server's certificate, you can see the written data in
the Objects folder on the left.
+ * Each point is packaged as an Event Node (EventNode) by OPC UA.
+ * Related fields and meanings:
-<div align="center">
- <img src="/img/OPCUA05.png" alt="" style="width: 60%;"/>
-</div>
-
-<div align="center">
- <img src="/img/OPCUA17.png" alt="" style="width: 60%;"/>
-</div>
-
-5. You can drag the node on the left to the center and display the latest
value of that node:
-
-<div align="center">
- <img src="/img/OPCUA07.png" alt="" style="width: 60%;"/>
-</div>
+ | Field | Meaning | Type (Milo) | Example
|
+ | ------------ | ------------------ | -------------- |
----------------------- |
+ | Time | Timestamp | DateTime | 1698907326198
|
+ | SourceName | Full path of point | String |
root.test.opc.sensor0 |
+ | SourceNode | Data type of point | NodeId | Int32
|
+ | Message | Data | LocalizedText | 3.0
|
-### 3.2 Pub / Sub Mode
-In this mode, IoTDB's stream processing engine sends data change events to the
OPC UA Server through an OPC UA Sink. These events are published to the
server's message queue and managed through Event Nodes. Other OPC UA Clients
can subscribe to these Event Nodes to receive notifications upon data changes.
-- Features：
+- Events are sent only to currently subscribed clients. Unconnected clients
ignore events.
+- Deleted data cannot be pushed to clients.
- - Each measurement point is wrapped as an Event Node in OPC UA.
+##### 2.2.2.1 Preparation
- - The relevant fields and their meanings are as follows:
-
- | Field | Meaning | Type (Milo) | Example
|
- | :--------- | :--------------- | :------------ | :-------------------- |
- | Time | Timestamp | DateTime | 1698907326198
|
- | SourceName | Full path of the measurement point | String
| root.test.opc.sensor0 |
- | SourceNode | Data type of the measurement point | NodeId
| Int32 |
- | Message | Data | LocalizedText | 3.0 |
-
- - Events are only sent to clients that are already listening; if a
client is not connected, the Event will be ignored.
- - If data is deleted, the information cannot be pushed to clients.
+Code located in
`example/pipe-opc-ua-sink/src/main/java/org/apache/iotdb/opcua` of
iotdb-example package.
+Contains:
-#### 3.2.1 Preparation Work
+- Main class (`ClientTest`)
+- Client certificate logic (`IoTDBKeyStoreLoaderClient`)
+- Client configuration and startup logic (`ClientExampleRunner`)
+- Parent class for `ClientTest` (`ClientExample`)
-The code is located in the [opc-ua-sink
package](https://github.com/apache/iotdb/tree/rc/2.0.1/example/pipe-opc-ua-sink/src/main/java/org/apache/iotdb/opcua)under
the iotdb-example package.
+##### 2.2.2.2 Quick Start
-The code includes:
+1. Open IoTDB and write some data:
-- The main class （ClientTest）
-- Client certificate-related logic（IoTDBKeyStoreLoaderClient）
-- Client configuration and startup logic（ClientExampleRunner）
-- The parent class of ClientTest（ClientExample）
-
-#### 3.2.2 Quick Start
-
-The steps are as follows:
+```SQL
+INSERT INTO root.a.b(time, c, d) VALUES(NOW(), 1, 2); // Auto-creates metadata
+```
-1. Start IoTDB and write some data.
+2. Create and start Pub/Sub mode OPC UA Sink:
```SQL
-insert into root.a.b(time, c, d) values(now(), 1, 2);
+CREATE PIPE p1 WITH SINK ('sink'='opc-ua-sink', 'sink.opcua.model'='pub-sub');
+START PIPE p1;
```
- The metadata is automatically created and enabled here.
+3. Observe server creates OPC certificate directory under conf:
+4. Run Client to connect, but server rejects Client certificate:
+5. Enter server's `sink.opcua.security.dir` → `pki` → `rejected` directory,
find Client's certificate:
+6. Move Client's certificate (not copy) to `trusted/certs` directory:
+7. Reopen Client → server certificate rejected by Client:
+8. Enter client's `<java.io.tmpdir>/client/security` → `pki` → `rejected` →
move server's certificate (not copy) to `trusted`:
+9. Open Client → successful bidirectional trust, connection established.
+10. Write data to server → Client prints received data:
-2. Use the following SQL to create and start the OPC UA Sink in Pub-Sub mode.
For detailed syntax, please refer to: [IoTDB OPC Server
Syntax](./Programming-OPC-UA_timecho.md#_2-1-syntax)
+#### 2.2.3 Notes
-```SQL
-create pipe p1 with sink ('sink'='opc-ua-sink',
- 'sink.opcua.model'='pub-sub');
-start pipe p1;
-```
+1. **Single-node vs Cluster**: Recommend single-node (1C1D). In cluster with
multiple DataNodes, data may be distributed across nodes, preventing full data
subscription.
+2. **No root certificate operations**: No need to handle IoTDB's root security
directory `iotdb-server.pfx` or client security directory `example-client.pfx`.
During bidirectional connection, root certificates are exchanged. New
certificates are placed in `rejected` directory; if in `trusted/certs`, they're
trusted.
+3. **Recommended Java 17+**: JDK 8 may have key size restrictions causing
"Illegal key size" errors. For specific versions (e.g., jdk.1.8u151+), add
`Security.setProperty("crypto.policy", "unlimited");` in
`ClientExampleRunner.createClient()`, or replace
`JDK/jre/lib/security/local_policy.jar` and `US_export_policy.jar` with
unlimited versions from
https://www.oracle.com/java/technologies/javase-jce8-downloads.html.
+4. **Connection issues**: If error is "Unknown host", modify `/etc/hosts` on
IoTDB DataNode machine to add target machine's URL and hostname.
- At this point, you can see that the opc certificate-related directory
has been created under the server's conf directory.
+## 3. Data Push
-<div align="center">
- <img src="/img/OPCUA08.png" alt="" style="width: 60%;"/>
-</div>
+In this mode, IoTDB acts as an OPC UA client via Pipe to actively push
selected data (including quality code) to one or more external OPC UA servers.
External servers automatically create directory trees and nodes based on
IoTDB's metadata.
-3. Run the Client connection directly; the Client's certificate will be
rejected by the server.
+
-<div align="center">
- <img src="/img/OPCUA09.png" alt="" style="width: 60%;"/>
-</div>
+### 3.1 OPC Service Startup
-4. Go to the server's sink.opcua.security.dir directory, then to the pki's
rejected directory, where the Client's certificate should have been generated.
+#### 3.1.1 Syntax
-<div align="center">
- <img src="/img/OPCUA10.png" alt="" style="width: 60%;"/>
-</div>
+Syntax for starting OPC UA protocol:
-5. Move (not copy) the client's certificate into (not into a subdirectory of)
the trusted directory's certs folder in the same directory.
+```SQL
+CREATE PIPE p1
+ WITH SOURCE (...)
+ WITH PROCESSOR (...)
+ WITH SINK ('sink' = 'opc-ua-sink',
+ 'opcua.node-url' = '127.0.0.1:12686',
+ 'opcua.historizing' = 'true',
+ 'opcua.with-quality' = 'true'
+ )
+```
-<div align="center">
- <img src="/img/OPCUA11.png" alt="" style="width: 60%;"/>
-</div>
+#### 3.1.2 Parameters
-6. Open the Client connection again; the server's certificate should now be
rejected by the Client.
+| **Parameter** | **Description**
[...]
+|-----------------------|
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| sink | OPC UA SINK
| [...]
+| opcua.node-url | Comma-separated OPC UA TCP ports. When specified,
IoTDB **does not** start local server but sends data to configured OPC UA
Server.
[...]
+| opcua.historizing | When automatically creating directories and leaf
nodes, whether to store historical data in new nodes.
[...]
+| opcua.with-quality | Whether OPC UA publishes data in value + quality
mode. When enabled, system processes data as follows:1. Both value and quality
present → Push directly to OPC UA Server.2. Only value present → Quality
automatically filled as UNCERTAIN (default, configurable).3. Only quality
present → Ignore write (no processing).4. Non-value/quality fields present →
Ignore data and log warning (configurable log frequency).5. Quality type
restriction: Only boolean type supported [...]
+| opcua.value-name | Effective when `with-quality` = true, specifies the
name of the value point.
[...]
+| opcua.quality-name | Effective when `with-quality` = true, specifies the
name of the quality point.
[...]
+| opcua.default-quality | When no quality is provided, specify
`GOOD`/`UNCERTAIN`/`BAD` via SQL parameter.
[...]
+| opcua.security-policy | OPC UA client security policy (case-insensitive),
URL format: `http://opcfoundation.org/UA/SecurityPolicy#`, e.g.,
`http://opcfoundation.org/UA/SecurityPolicy#Aes128_Sha256_RsaOaep`
| String (security level
increases):`None`,`Basic128Rsa15`,`Basic256`,`Basic256Sha256`,`Aes128_Sha256_RsaOaep`,`Aes256_Sha256_RsaPss`
| Optional | `Basic256Sha [...]
+| opcua.timeout-seconds | Client connection timeout in seconds (effective only
when IoTDB acts as client)
[...]
-<div align="center">
- <img src="/img/OPCUA12.png" alt="" style="width: 60%;"/>
-</div>
+> **Parameter Naming Note**: All parameters support omitting `opcua.` prefix
(e.g., `node-urls` and `opcua.node-urls` are equivalent).
+>
+> **Support Note**: All `opcua.` parameters are supported starting from
V2.0.8, and only for `client-server` mode.
-7. Go to the client's <java.io.tmpdir>/client/security directory, then to the
pki's rejected directory, and move the server's certificate into (not into a
subdirectory of) the trusted directory.
+#### 3.1.3 Example
-<div align="center">
- <img src="/img/OPCUA13.png" alt="" style="width: 60%;"/>
-</div>
+```Bash
+CREATE PIPE p1
+ WITH SOURCE (...)
+ WITH PROCESSOR (...)
+ WITH SINK ('sink' = 'opc-ua-sink',
+ 'node-urls' = '127.0.0.1:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ )
+```
-8. Open the Client, and now the two-way trust is successful, and the Client
can connect to the server.
+#### 3.1.4 Usage Restrictions
-9. Write data to the server, and the Client will print out the received data.
+1. Current mode **only supports `client-server` mode and tree model data**.
+2. Do not configure multiple DataNodes on one machine to avoid port conflicts.
+3. **Does not support** `OBJECT` type data push.
+4. When a time series is renamed, OPC UA Sink automatically deletes the old
path and pushes data to the new path.
+5. **Strongly recommended** to use non-`None` security policy (e.g.,
`Basic256Sha256`) with proper bidirectional certificate trust in production.
-<div align="center">
- <img src="/img/OPCUA14.png" alt="" style="width: 60%;"/>
-</div>
+### 3.2 External OPC UA Server Project
+IoTDB supports a standalone external Server project. This Server implements
the same configuration as IoTDB's embedded Server but requires additional
support for dynamically creating directories and leaf nodes based on IoTDB's
metadata.
-### 3.4 Notes
+Configuration is injected via command-line args when starting the Server (no
YAML/XML support). Parameter keys match IoTDB OPC Server configuration items,
with dots (`.`) and hyphens (`-`) replaced by underscores (`_`).
-1. **stand alone and cluster:** It is recommended to use a 1C1D (one
coordinator and one data node) single machine version. If there are multiple
DataNodes in the cluster, data may be sent in a scattered manner across various
DataNodes, and it may not be possible to listen to all the data.
+Example:
-2. **No Need to Operate Root Directory Certificates:** During the certificate
operation process, there is no need to operate the `iotdb-server.pfx`
certificate under the IoTDB security root directory and the
`example-client.pfx` directory under the client security directory. When the
Client and Server connect bidirectionally, they will send the root directory
certificate to each other. If it is the first time the other party sees this
certificate, it will be placed in the reject dir. If [...]
+```SQL
+./start-IoTDB-opc-server.sh -enable_anonymous_access true -u root -pw root
-https_port 8443
+```
-3. **It is Recommended to Use Java 17+:**
-In JVM 8 versions, there may be a key length restriction, resulting in an
"Illegal key size" error. For specific versions (such as jdk.1.8u151+), you can
add `Security.`*`setProperty`*`("crypto.policy", "unlimited");`; in the create
client of ClientExampleRunner to solve this, or you can download the unlimited
package `local_policy.jar` and `US_export_policy ` to replace the packages in
the `JDK/jre/lib/security `. Download
link:https://www.oracle.com/java/technologies/javase-jce8-downlo [...]
+Where `user` and `password` can be abbreviated as `-u` and `-p`. All other
parameter keys match configuration items. Note: `userName` is **not** a valid
parameter key; only `user` is supported.
+
+### 3.3 Scenario Example
+
+**Goal**: Aggregate data from multiple sources to 3 external OPC Servers for
unified monitoring center access.
+
+
+
+1. **Preparation**: Start external OPC UA Server (port 12686) on three servers
(`ip1`, `ip2`, `ip3`).
+2. **Configure Pipes**: Create 3 Pipes in IoTDB, using `processor` or `source`
path patterns to filter data by region and push to corresponding Servers.
+ ```SQL
+ -- Start IoTDB
+ ./start-standalone.sh
+
+ -- Start three OPC UA Servers (on ip1, ip2, ip3)
+ ./start-IoTDB-external-opc-server.sh -enable-anonymous-access true -u root
-pw root
+
+ -- Create three Pipes
+ ./start-cli.sh
+ CREATE PIPE p1
+ WITH SOURCE (<ip1 credentials>)
+ WITH PROCESSOR (...)
+ WITH SINK ('sink' = 'opc-ua-sink',
+ 'node-urls' = 'ip1:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ );
+ CREATE PIPE p2
+ WITH SOURCE (<ip2 credentials>)
+ WITH PROCESSOR (...)
+ WITH SINK ('sink' = 'opc-ua-sink',
+ 'node-urls' = 'ip2:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ );
+ CREATE PIPE p3
+ WITH SOURCE (<ip3 credentials>)
+ WITH PROCESSOR (...)
+ WITH SINK ('sink' = 'opc-ua-sink',
+ 'node-urls' = 'ip3:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ );
+ ```
+3. **Result**: The monitoring center only needs to connect to `ip1`, `ip2`,
and `ip3` to access the complete data view from all regions, with quality
information attached.
diff --git a/src/UserGuide/latest/API/Programming-OPC-UA_timecho.md
b/src/UserGuide/latest/API/Programming-OPC-UA_timecho.md
index 47a6ce5b..80b5446b 100644
--- a/src/UserGuide/latest/API/Programming-OPC-UA_timecho.md
+++ b/src/UserGuide/latest/API/Programming-OPC-UA_timecho.md
@@ -21,223 +21,291 @@
# OPC UA Protocol
-## 1. OPC UA Subscription Data
+## 1. Overview
-This feature allows users to subscribe to data from IoTDB using the OPC UA
protocol. The communication modes for subscription data support both
Client/Server and Pub/Sub.
+This document describes two independent operational modes for IoTDB's
integration with the OPC UA protocol. Choose the mode based on your business
scenario:
-Note: This feature is not about collecting data from external OPC Servers and
writing it into IoTDB.
+* **Mode 1: Data Subscription Service (IoTDB as OPC UA Server)**: IoTDB starts
an embedded OPC UA server to passively allow external clients (e.g., UAExpert)
to connect and subscribe to its internal data. This is the traditional usage.
+* **Mode 2: Data Push (IoTDB as OPC UA Client)**: IoTDB acts as a client to
actively synchronize data and metadata to one or more independently deployed
external OPC UA servers.
+ > Note: This mode is supported starting from V2.0.8.
-
+**Note: Modes are mutually exclusive**
+When the Pipe configuration specifies the `node-urls` parameter (Mode 2),
IoTDB will **not** start the embedded OPC UA server (Mode 1). These two modes
**cannot be used simultaneously** within the same Pipe.
+
+## 2. Data Subscription
+
+This mode supports users subscribing to data from IoTDB using the OPC UA
protocol, with communication modes supporting both Client/Server and Pub/Sub.
+
+Note: This feature does **not** involve collecting data from external OPC
Servers into IoTDB.
-## 2. OPC Service Startup Method
+
-### 2.1 Syntax
+### 2.1 OPC Service Startup
-The syntax to start the OPC UA protocol:
+#### 2.1.1 Syntax
+Syntax for starting OPC UA protocol:
```SQL
-create pipe p1
- with source (...)
- with processor (...)
- with sink ('sink' = 'opc-ua-sink',
+CREATE PIPE p1
+ WITH SOURCE (...)
+ WITH PROCESSOR (...)
+ WITH SINK ('sink' = 'opc-ua-sink',
'sink.opcua.tcp.port' = '12686',
'sink.opcua.https.port' = '8443',
'sink.user' = 'root',
- 'sink.password' = 'TimechoDB@2021', //Before V2.0.6.x the
default password is root
+ 'sink.password' = 'TimechoDB@2021', // Default password was
'root' before V2.0.6.x
'sink.opcua.security.dir' = '...'
)
```
-### 2.2 Parameters
-
-| key | value
| value range | required or not
| default value
|
-| :------------------------------ |
:----------------------------------------------------------- |
:------------------------------------- | :-------
|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| sink | OPC UA SINK |
String: opc-ua-sink | Required |
|
-| sink.opcua.model | OPC UA model used |
String: client-server / pub-sub | Optional | pub-sub
|
-| sink.opcua.tcp.port | OPC UA's TCP port |
Integer: [0, 65536] | Optional | 12686
|
-| sink.opcua.https.port | OPC UA's HTTPS port |
Integer: [0, 65536] | Optional | 8443
|
-| sink.opcua.security.dir | Directory for OPC UA's keys and
certificates | String: Path, supports absolute and relative
directories | Optional | Opc_security folder/<httpsPort: tcpPort>in the
conf directory of the DataNode related to iotdb <br> If there is no conf
directory for iotdb (such as launching DataNode in IDEA), it will be the
iotdb_opc_Security folder/<httpsPort: tcpPort>in the user's home directory |
-| sink.opcua.enable-anonymous-access | Whether OPC UA allows anonymous access
| Boolean | Optional | true
|
-| sink.user | User for OPC UA, specified in the
configuration | String | Optional | root
|
-| sink.password | Password for OPC UA, specified in the
configuration | String | Optional |
TimechoDB@2021 //Before V2.0.6.x the default password is root
|
-
-### 2.3 Example
+#### 2.1.2 Parameters
+
+| **Parameter** | **Description**
[...]
+| ------------------------------------ |
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| sink | OPC UA SINK
[...]
+| sink.opcua.model | OPC UA operational mode
[...]
+| sink.opcua.tcp.port | OPC UA TCP port
[...]
+| sink.opcua.https.port | OPC UA HTTPS port
[...]
+| sink.opcua.security.dir | OPC UA key and certificate directory
[...]
+| opcua.security-policy | Security policy used for OPC UA
connections (case-insensitive). Multiple policies can be configured and
separated by commas. After configuring one policy, clients can only connect
using that policy. Default implementation supports `None` and `Basic256Sha256`.
Should be set to a non-`None` policy by default. `None` policy is only for
debugging (convenient but insecure; not recommended for production). Note:
Supported since V2.0.8, only for client-ser [...]
+| sink.opcua.enable-anonymous-access | Whether OPC UA allows anonymous access
[...]
+| sink.user | User (OPC UA allowed user)
[...]
+| sink.password | Password (OPC UA allowed password)
[...]
+| opcua.with-quality | Whether OPC UA publishes data in value
+ quality mode. When enabled, system processes data as follows:1. Both value
and quality present → Push directly to OPC UA Server.2. Only value present →
Quality automatically filled as UNCERTAIN (default, configurable).3. Only
quality present → Ignore write (no processing).4. Non-value/quality fields
present → Ignore data and log warning (configurable log frequency to avoid
high-frequency interference).5. Qual [...]
+| opcua.value-name | Effective when `with-quality` = true,
specifies the name of the value point. **Note**: Supported since V2.0.8, only
for client-server mode
[...]
+| opcua.quality-name | Effective when `with-quality` = true,
specifies the name of the quality point. **Note**: Supported since V2.0.8, only
for client-server mode
[...]
+| opcua.default-quality | When no quality is provided, specify
`GOOD`/`UNCERTAIN`/`BAD` via SQL parameter. **Note**: Supported since V2.0.8,
only for client-server mode
[...]
+| opcua.timeout-seconds | Client connection timeout in seconds
(effective only when IoTDB acts as client). **Note**: Supported since V2.0.8,
only for client-server mode
[...]
+
+#### 2.1.3 Example
```Bash
-create pipe p1
- with sink ('sink' = 'opc-ua-sink'，
+CREATE PIPE p1
+ WITH SINK ('sink' = 'opc-ua-sink',
'sink.user' = 'root',
- 'sink.password' = 'TimechoDB@2021' //Before V2.0.6.x the
default password is root
-start pipe p1;
+ 'sink.password' = 'TimechoDB@2021'); // Default password was
'root' before V2.0.6.x
+START PIPE p1;
```
-### 2.4 Usage Limitations
-
-1. After starting the protocol, data needs to be written to establish a
connection. Only data after the connection is established can be subscribed to.
-2. Recommended for use in standalone mode. In distributed mode, each IoTDB
DataNode acts as an independent OPC Server providing data and requires separate
subscription.
+#### 2.1.4 Usage Restrictions
-## 3. Examples of Two Communication Modes
+1. Data must be written after protocol startup to establish connection. Only
data written *after* connection can be subscribed.
+2. Recommended for single-node mode. In distributed mode, each IoTDB DataNode
acts as an independent OPC Server; separate subscriptions are required for each.
-### 3.1 Client / Server Mode
+### 2.2 Example of Two Communication Modes
-In this mode, IoTDB's stream processing engine establishes a connection with
the OPC UA Server via an OPC UA Sink. The OPC UA Server maintains data within
its Address Space, from which IoTDB can request and retrieve data.
Additionally, other OPC UA Clients can access the data on the server.
+#### 2.2.1 Client/Server Mode
-* Features:
- * OPC UA organizes device information received from the Sink into folders
under the Objects folder according to a tree model.
- * Each measurement point is recorded as a variable node, storing the latest
value from the current database.
- * OPC UA cannot delete data or change data type settings.
+In this mode, IoTDB's stream processing engine establishes a connection with
the OPC UA Server (Server) via OPC UA Sink. The OPC UA Server maintains data in
its address space (Address Space), and IoTDB can request and retrieve this
data. Other OPC UA clients (Clients) can also access the server's data.
-#### 3.1.1 Preparation Work
+* **Features**:
+ * OPC UA organizes device information received from Sink into folders
under Objects folder in tree structure.
+ * Each point is recorded as a variable node with the latest value in the
current database.
+ * OPC UA cannot delete data or change data type settings.
-1. Take UAExpert client as an example, download the UAExpert client:
https://www.unified-automation.com/downloads/opc-ua-clients.html
+##### 2.2.1.1 Preparation
-2. Install UAExpert and fill in your own certificate information.
+1. Example using UAExpert client: Download UAExpert client from
https://www.unified-automation.com/downloads/opc-ua-clients.html
+2. Install UAExpert and configure certificate information.
-#### 3.1.2 Quick Start
+##### 2.2.1.2 Quick Start
-1. Use the following SQL to create and start the OPC UA Sink in client-server
mode. For detailed syntax, please refer to: [IoTDB OPC Server
Syntax](./Programming-OPC-UA_timecho.md#_2-1-syntax)
+1. Start OPC UA service using SQL (detailed syntax see [IoTDB OPC Server
Syntax](./Programming-OPC-UA_timecho.md#_2-1-语法)):
```SQL
-create pipe p1 with sink ('sink'='opc-ua-sink');
+CREATE PIPE p1 WITH SINK ('sink'='opc-ua-sink');
```
-2. Write some data.
+2. Write some data:
```SQL
-insert into root.test.db(time, s2) values(now(), 2)
+INSERT INTO root.test.db(time, s2) VALUES(NOW(), 2);
```
- The metadata is automatically created and enabled here.
+3. Configure UAExpert to connect to IoTDB (password matches `sink.password`
configured above, e.g., root/TimechoDB@2021):
+4. Trust the server certificate, then view written data under Objects folder
on the left:
+5. Drag left nodes to the middle to display latest value:
-3. Configure the connection to IoTDB in UAExpert, where the password should be
set to the one defined in the sink.password parameter (using the default
password "root" as an example):
+#### 2.2.2 Pub/Sub Mode
-<div align="center">
- <img src="/img/OPCUA18.png" alt="" style="width: 60%;"/>
-</div>
+In this mode, IoTDB's stream processing engine sends data change events to the
OPC UA Server (Server) via OPC UA Sink. These events are published to the
server's message queue and managed via Event Nodes. Other OPC UA clients
(Clients) can subscribe to these Event Nodes to receive notifications when data
changes.
-<div align="center">
- <img src="/img/OPCUA04.png" alt="" style="width: 60%;"/>
-</div>
+* **Features**:
-4. After trusting the server's certificate, you can see the written data in
the Objects folder on the left.
+ * Each point is packaged as an Event Node (EventNode) by OPC UA.
+ * Related fields and meanings:
-<div align="center">
- <img src="/img/OPCUA05.png" alt="" style="width: 60%;"/>
-</div>
-
-<div align="center">
- <img src="/img/OPCUA17.png" alt="" style="width: 60%;"/>
-</div>
-
-5. You can drag the node on the left to the center and display the latest
value of that node:
-
-<div align="center">
- <img src="/img/OPCUA07.png" alt="" style="width: 60%;"/>
-</div>
+ | Field | Meaning | Type (Milo) | Example
|
+ | ------------ | ------------------ | -------------- |
----------------------- |
+ | Time | Timestamp | DateTime | 1698907326198
|
+ | SourceName | Full path of point | String |
root.test.opc.sensor0 |
+ | SourceNode | Data type of point | NodeId | Int32
|
+ | Message | Data | LocalizedText | 3.0
|
-### 3.2 Pub / Sub Mode
-In this mode, IoTDB's stream processing engine sends data change events to the
OPC UA Server through an OPC UA Sink. These events are published to the
server's message queue and managed through Event Nodes. Other OPC UA Clients
can subscribe to these Event Nodes to receive notifications upon data changes.
-- Features：
+- Events are sent only to currently subscribed clients. Unconnected clients
ignore events.
+- Deleted data cannot be pushed to clients.
- - Each measurement point is wrapped as an Event Node in OPC UA.
+##### 2.2.2.1 Preparation
- - The relevant fields and their meanings are as follows:
-
- | Field | Meaning | Type (Milo) | Example
|
- | :--------- | :--------------- | :------------ | :-------------------- |
- | Time | Timestamp | DateTime | 1698907326198
|
- | SourceName | Full path of the measurement point | String
| root.test.opc.sensor0 |
- | SourceNode | Data type of the measurement point | NodeId
| Int32 |
- | Message | Data | LocalizedText | 3.0 |
-
- - Events are only sent to clients that are already listening; if a
client is not connected, the Event will be ignored.
- - If data is deleted, the information cannot be pushed to clients.
+Code located in
`example/pipe-opc-ua-sink/src/main/java/org/apache/iotdb/opcua` of
iotdb-example package.
+Contains:
-#### 3.2.1 Preparation Work
+- Main class (`ClientTest`)
+- Client certificate logic (`IoTDBKeyStoreLoaderClient`)
+- Client configuration and startup logic (`ClientExampleRunner`)
+- Parent class for `ClientTest` (`ClientExample`)
-The code is located in the [opc-ua-sink
package](https://github.com/apache/iotdb/tree/rc/2.0.1/example/pipe-opc-ua-sink/src/main/java/org/apache/iotdb/opcua)under
the iotdb-example package.
+##### 2.2.2.2 Quick Start
-The code includes:
+1. Open IoTDB and write some data:
-- The main class （ClientTest）
-- Client certificate-related logic（IoTDBKeyStoreLoaderClient）
-- Client configuration and startup logic（ClientExampleRunner）
-- The parent class of ClientTest（ClientExample）
-
-#### 3.2.2 Quick Start
-
-The steps are as follows:
+```SQL
+INSERT INTO root.a.b(time, c, d) VALUES(NOW(), 1, 2); // Auto-creates metadata
+```
-1. Start IoTDB and write some data.
+2. Create and start Pub/Sub mode OPC UA Sink:
```SQL
-insert into root.a.b(time, c, d) values(now(), 1, 2);
+CREATE PIPE p1 WITH SINK ('sink'='opc-ua-sink', 'sink.opcua.model'='pub-sub');
+START PIPE p1;
```
- The metadata is automatically created and enabled here.
+3. Observe server creates OPC certificate directory under conf:
+4. Run Client to connect, but server rejects Client certificate:
+5. Enter server's `sink.opcua.security.dir` → `pki` → `rejected` directory,
find Client's certificate:
+6. Move Client's certificate (not copy) to `trusted/certs` directory:
+7. Reopen Client → server certificate rejected by Client:
+8. Enter client's `<java.io.tmpdir>/client/security` → `pki` → `rejected` →
move server's certificate (not copy) to `trusted`:
+9. Open Client → successful bidirectional trust, connection established.
+10. Write data to server → Client prints received data:
-2. Use the following SQL to create and start the OPC UA Sink in Pub-Sub mode.
For detailed syntax, please refer to: [IoTDB OPC Server
Syntax](./Programming-OPC-UA_timecho.md#_2-1-syntax)
+#### 2.2.3 Notes
-```SQL
-create pipe p1 with sink ('sink'='opc-ua-sink',
- 'sink.opcua.model'='pub-sub');
-start pipe p1;
-```
+1. **Single-node vs Cluster**: Recommend single-node (1C1D). In cluster with
multiple DataNodes, data may be distributed across nodes, preventing full data
subscription.
+2. **No root certificate operations**: No need to handle IoTDB's root security
directory `iotdb-server.pfx` or client security directory `example-client.pfx`.
During bidirectional connection, root certificates are exchanged. New
certificates are placed in `rejected` directory; if in `trusted/certs`, they're
trusted.
+3. **Recommended Java 17+**: JDK 8 may have key size restrictions causing
"Illegal key size" errors. For specific versions (e.g., jdk.1.8u151+), add
`Security.setProperty("crypto.policy", "unlimited");` in
`ClientExampleRunner.createClient()`, or replace
`JDK/jre/lib/security/local_policy.jar` and `US_export_policy.jar` with
unlimited versions from
https://www.oracle.com/java/technologies/javase-jce8-downloads.html.
+4. **Connection issues**: If error is "Unknown host", modify `/etc/hosts` on
IoTDB DataNode machine to add target machine's URL and hostname.
- At this point, you can see that the opc certificate-related directory
has been created under the server's conf directory.
+## 3. Data Push
-<div align="center">
- <img src="/img/OPCUA08.png" alt="" style="width: 60%;"/>
-</div>
+In this mode, IoTDB acts as an OPC UA client via Pipe to actively push
selected data (including quality code) to one or more external OPC UA servers.
External servers automatically create directory trees and nodes based on
IoTDB's metadata.
-3. Run the Client connection directly; the Client's certificate will be
rejected by the server.
+
-<div align="center">
- <img src="/img/OPCUA09.png" alt="" style="width: 60%;"/>
-</div>
+### 3.1 OPC Service Startup
-4. Go to the server's sink.opcua.security.dir directory, then to the pki's
rejected directory, where the Client's certificate should have been generated.
+#### 3.1.1 Syntax
-<div align="center">
- <img src="/img/OPCUA10.png" alt="" style="width: 60%;"/>
-</div>
+Syntax for starting OPC UA protocol:
-5. Move (not copy) the client's certificate into (not into a subdirectory of)
the trusted directory's certs folder in the same directory.
+```SQL
+CREATE PIPE p1
+ WITH SOURCE (...)
+ WITH PROCESSOR (...)
+ WITH SINK ('sink' = 'opc-ua-sink',
+ 'opcua.node-url' = '127.0.0.1:12686',
+ 'opcua.historizing' = 'true',
+ 'opcua.with-quality' = 'true'
+ )
+```
-<div align="center">
- <img src="/img/OPCUA11.png" alt="" style="width: 60%;"/>
-</div>
+#### 3.1.2 Parameters
-6. Open the Client connection again; the server's certificate should now be
rejected by the Client.
+| **Parameter** | **Description**
[...]
+|-----------------------|
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| sink | OPC UA SINK
| [...]
+| opcua.node-url | Comma-separated OPC UA TCP ports. When specified,
IoTDB **does not** start local server but sends data to configured OPC UA
Server.
[...]
+| opcua.historizing | When automatically creating directories and leaf
nodes, whether to store historical data in new nodes.
[...]
+| opcua.with-quality | Whether OPC UA publishes data in value + quality
mode. When enabled, system processes data as follows:1. Both value and quality
present → Push directly to OPC UA Server.2. Only value present → Quality
automatically filled as UNCERTAIN (default, configurable).3. Only quality
present → Ignore write (no processing).4. Non-value/quality fields present →
Ignore data and log warning (configurable log frequency).5. Quality type
restriction: Only boolean type supported [...]
+| opcua.value-name | Effective when `with-quality` = true, specifies the
name of the value point.
[...]
+| opcua.quality-name | Effective when `with-quality` = true, specifies the
name of the quality point.
[...]
+| opcua.default-quality | When no quality is provided, specify
`GOOD`/`UNCERTAIN`/`BAD` via SQL parameter.
[...]
+| opcua.security-policy | OPC UA client security policy (case-insensitive),
URL format: `http://opcfoundation.org/UA/SecurityPolicy#`, e.g.,
`http://opcfoundation.org/UA/SecurityPolicy#Aes128_Sha256_RsaOaep`
| String (security level
increases):`None`,`Basic128Rsa15`,`Basic256`,`Basic256Sha256`,`Aes128_Sha256_RsaOaep`,`Aes256_Sha256_RsaPss`
| Optional | `Basic256Sha [...]
+| opcua.timeout-seconds | Client connection timeout in seconds (effective only
when IoTDB acts as client)
[...]
-<div align="center">
- <img src="/img/OPCUA12.png" alt="" style="width: 60%;"/>
-</div>
+> **Parameter Naming Note**: All parameters support omitting `opcua.` prefix
(e.g., `node-urls` and `opcua.node-urls` are equivalent).
+>
+> **Support Note**: All `opcua.` parameters are supported starting from
V2.0.8, and only for `client-server` mode.
-7. Go to the client's <java.io.tmpdir>/client/security directory, then to the
pki's rejected directory, and move the server's certificate into (not into a
subdirectory of) the trusted directory.
+#### 3.1.3 Example
-<div align="center">
- <img src="/img/OPCUA13.png" alt="" style="width: 60%;"/>
-</div>
+```Bash
+CREATE PIPE p1
+ WITH SOURCE (...)
+ WITH PROCESSOR (...)
+ WITH SINK ('sink' = 'opc-ua-sink',
+ 'node-urls' = '127.0.0.1:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ )
+```
-8. Open the Client, and now the two-way trust is successful, and the Client
can connect to the server.
+#### 3.1.4 Usage Restrictions
-9. Write data to the server, and the Client will print out the received data.
+1. Current mode **only supports `client-server` mode and tree model data**.
+2. Do not configure multiple DataNodes on one machine to avoid port conflicts.
+3. **Does not support** `OBJECT` type data push.
+4. When a time series is renamed, OPC UA Sink automatically deletes the old
path and pushes data to the new path.
+5. **Strongly recommended** to use non-`None` security policy (e.g.,
`Basic256Sha256`) with proper bidirectional certificate trust in production.
-<div align="center">
- <img src="/img/OPCUA14.png" alt="" style="width: 60%;"/>
-</div>
+### 3.2 External OPC UA Server Project
+IoTDB supports a standalone external Server project. This Server implements
the same configuration as IoTDB's embedded Server but requires additional
support for dynamically creating directories and leaf nodes based on IoTDB's
metadata.
-### 3.4 Notes
+Configuration is injected via command-line args when starting the Server (no
YAML/XML support). Parameter keys match IoTDB OPC Server configuration items,
with dots (`.`) and hyphens (`-`) replaced by underscores (`_`).
-1. **stand alone and cluster:** It is recommended to use a 1C1D (one
coordinator and one data node) single machine version. If there are multiple
DataNodes in the cluster, data may be sent in a scattered manner across various
DataNodes, and it may not be possible to listen to all the data.
+Example:
-2. **No Need to Operate Root Directory Certificates:** During the certificate
operation process, there is no need to operate the `iotdb-server.pfx`
certificate under the IoTDB security root directory and the
`example-client.pfx` directory under the client security directory. When the
Client and Server connect bidirectionally, they will send the root directory
certificate to each other. If it is the first time the other party sees this
certificate, it will be placed in the reject dir. If [...]
+```SQL
+./start-IoTDB-opc-server.sh -enable_anonymous_access true -u root -pw root
-https_port 8443
+```
-3. **It is Recommended to Use Java 17+:**
-In JVM 8 versions, there may be a key length restriction, resulting in an
"Illegal key size" error. For specific versions (such as jdk.1.8u151+), you can
add `Security.`*`setProperty`*`("crypto.policy", "unlimited");`; in the create
client of ClientExampleRunner to solve this, or you can download the unlimited
package `local_policy.jar` and `US_export_policy ` to replace the packages in
the `JDK/jre/lib/security `. Download
link:https://www.oracle.com/java/technologies/javase-jce8-downlo [...]
+Where `user` and `password` can be abbreviated as `-u` and `-p`. All other
parameter keys match configuration items. Note: `userName` is **not** a valid
parameter key; only `user` is supported.
+
+### 3.3 Scenario Example
+
+**Goal**: Aggregate data from multiple sources to 3 external OPC Servers for
unified monitoring center access.
+
+
+
+1. **Preparation**: Start external OPC UA Server (port 12686) on three servers
(`ip1`, `ip2`, `ip3`).
+2. **Configure Pipes**: Create 3 Pipes in IoTDB, using `processor` or `source`
path patterns to filter data by region and push to corresponding Servers.
+ ```SQL
+ -- Start IoTDB
+ ./start-standalone.sh
+
+ -- Start three OPC UA Servers (on ip1, ip2, ip3)
+ ./start-IoTDB-external-opc-server.sh -enable-anonymous-access true -u root
-pw root
+
+ -- Create three Pipes
+ ./start-cli.sh
+ CREATE PIPE p1
+ WITH SOURCE (<ip1 credentials>)
+ WITH PROCESSOR (...)
+ WITH SINK ('sink' = 'opc-ua-sink',
+ 'node-urls' = 'ip1:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ );
+ CREATE PIPE p2
+ WITH SOURCE (<ip2 credentials>)
+ WITH PROCESSOR (...)
+ WITH SINK ('sink' = 'opc-ua-sink',
+ 'node-urls' = 'ip2:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ );
+ CREATE PIPE p3
+ WITH SOURCE (<ip3 credentials>)
+ WITH PROCESSOR (...)
+ WITH SINK ('sink' = 'opc-ua-sink',
+ 'node-urls' = 'ip3:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ );
+ ```
+3. **Result**: The monitoring center only needs to connect to `ip1`, `ip2`,
and `ip3` to access the complete data view from all regions, with quality
information attached.
diff --git a/src/zh/UserGuide/Master/Tree/API/Programming-OPC-UA_timecho.md
b/src/zh/UserGuide/Master/Tree/API/Programming-OPC-UA_timecho.md
index eea7e97f..cb545a4d 100644
--- a/src/zh/UserGuide/Master/Tree/API/Programming-OPC-UA_timecho.md
+++ b/src/zh/UserGuide/Master/Tree/API/Programming-OPC-UA_timecho.md
@@ -21,16 +21,28 @@
# OPC UA 协议
-## 1. OPC UA 订阅数据
+## 1. 功能概述
-本功能支持用户以 OPC UA 协议从 IoTDB 中订阅数据，订阅数据的通信模式支持 Client/Server 和 Pub/Sub 两种。
+本文档介绍了 IoTDB 与 OPC UA 协议集成的两种独立工作模式，请根据您的业务场景进行选择：
+
+* **模式一：数据订阅服务 (IoTDB 作为 OPC UA 服务器)**：IoTDB 启动内置的 OPC UA 服务器，被动地允许外部客户端（如
UAExpert）连接并订阅其内部数据。这是传统用法。
+* **模式二：数据主动推送 (IoTDB 作为 OPC UA 客户端)**：IoTDB 作为客户端，主动将数据和元数据同步到一个或多个独立部署的外部
OPC UA 服务器。
+ > 注意：该模式从 V2.0.8 起支持。
+
+**注意：模式互斥**
+
+当 Pipe 配置中指定了 `node-urls` 参数（模式二），IoTDB 将不会启动内置的 OPC UA 服务器（模式一）。两种模式在同一 Pipe
中**不可同时使用**。
+
+## 2. 数据订阅
+
+本模式支持用户以 OPC UA 协议从 IoTDB 中订阅数据，订阅数据的通信模式支持 Client/Server 和 Pub/Sub 两种。
注意：本功能并非从外部 OPC Server 中采集数据写入 IoTDB
-## 2. OPC 服务启动方式
-### 2.1 语法
+### 2.1 OPC 服务启动方式
+#### 2.1.1 语法
启动 OPC UA 协议的语法：
@@ -47,20 +59,26 @@ create pipe p1
)
```
-### 2.2 参数
-
-| **参数** | **描述** | ** 取值范围 ** |
**是否必填** | **默认值**
|
-| ------------------------------------ | -------------------------------- |
---------------------------------- | --------------------
|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| sink | OPC UA SINK |
String: opc-ua-sink | 必填 |
|
-| sink.opcua.model | OPC UA 使用的模式 | String:
client-server / pub-sub | 选填 | client-server
|
-| sink.opcua.tcp.port | OPC UA 的 TCP 端口 | Integer:
[0, 65536] | 选填 | 12686
|
-| sink.opcua.https.port | OPC UA 的 HTTPS 端口 | Integer:
[0, 65536] | 选填 | 8443
|
-| sink.opcua.security.dir | OPC UA 的密钥及证书目录 | String:
Path，支持绝对及相对目录 | 选填 | 1. iotdb 相关 DataNode 的 conf 目录下的
opc\_security 文件夹 / `<httpsPort:tcpPort>`。2. 如无 iotdb 的 conf 目录（例如 IDEA 中启动
DataNode），则为用户主目录下的 iotdb\_opc\_security 文件夹 /`<httpsPort:tcpPort>`|
-| sink.opcua.enable-anonymous-access | OPC UA 是否允许匿名访问 | Boolean
| 选填 | true
|
-| sink.user | 用户，这里指 OPC UA 的允许用户 | String
| 选填 | root
|
-| sink.password | 密码，这里指 OPC UA 的允许密码 | String
| 选填 | TimechoDB@2021 （V2.0.6.x 之前默认密码为root ）
|
-
-### 2.3 示例
+#### 2.1.2 参数
+
+| **参数** | **描述**
[...]
+| ------------------------------------ |
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| sink | OPC UA SINK
[...]
+| sink.opcua.model | OPC UA 使用的模式
[...]
+| sink.opcua.tcp.port | OPC UA 的 TCP 端口
[...]
+| sink.opcua.https.port | OPC UA 的 HTTPS 端口
[...]
+| sink.opcua.security.dir | OPC UA 的密钥及证书目录
[...]
+| opcua.security-policy | OPC UA
连接使用的安全策略，不区分大小写。可以配置多个，用`,`连接。配置一个安全策略后，client
才能用对应的策略连接。当前实现默认支持`None`和`Basic256Sha256`策略，应该默认改为任意的非`None`策略，`None`策略在调试环境中单独配置，因为`None`策略虽然不需移动证书，操作方便，但是不安全，生产环境的
server 不建议支持该策略。注意：V2.0.8 起支持该参数，且仅支持 client-server 模式
|
String（安全性依次递增）:<br>`None`<br>`Basic128Rsa15`<br>`Basic256`<br>`Basic256Sha256`<br>`Aes128_Sha256
[...]
+| sink.opcua.enable-anonymous-access | OPC UA 是否允许匿名访问
[...]
+| sink.user | 用户，这里指 OPC UA 的允许用户
[...]
+| sink.password | 密码，这里指 OPC UA 的允许密码
[...]
+| opcua.with-quality | OPC UA 的测点发布是否为 value + quality
模式。启用配置后，系统将按以下规则处理写入数据：<br>1. 同时包含 value 和 quality，则直接推送至 OPC UA Server。<br>2.
仅包含 value，则 quality 自动填充为 UNCERTAIN（默认值，支持自定义配置）。<br>3. 仅包含
quality，则该写入被忽略，不进行任何处理。<br>4. 包含非 value/quality
字段，则忽略该数据，并记录警告日志（日志频率可配置，避免高频干扰）。<br>5. quality 类型限制：目前仅支持布尔类型（true 表示
GOOD，false 表示 BAD）； 注意：V2.0.8 起支持该参数，且仅支持 client-server 模式 | Boolean
[...]
+| opcua.value-name | With-quality 为 true 时生效，表示 value 测点的名字。
注意：V2.0.8 起支持该参数，且仅支持 client-server 模式
[...]
+| opcua.quality-name | With-quality 为 true 时生效，表示 quality
测点的名字。 注意：V2.0.8 起支持该参数，且仅支持 client-server 模式
[...]
+| opcua.default-quality | 没有 quality 时，可以通过 SQL
参数指定`GOOD`/`UNCERTAIN`/`BAD`。 注意：V2.0.8 起支持该参数，且仅支持 client-server 模式
[...]
+| opcua.timeout-seconds | Client 连接 server 的超时秒数，仅在 IoTDB 为
client 时生效 注意：V2.0.8 起支持该参数，且仅支持 client-server 模式
[...]
+
+#### 2.1.3 示例
```Bash
create pipe p1
@@ -70,12 +88,12 @@ create pipe p1
start pipe p1;
```
-### 2.4 使用限制
+#### 2.1.4 使用限制
1. 启动协议之后需要写入数据，才能建立连接，且仅能订阅建立连接之后的数据。
2. 推荐在单机模式下使用。在分布式模式下，每一个 IoTDB DataNode 都作为一个独立的 OPC Server 提供数据，需要单独订阅。
-## 3. 两种通信模式示例
-### 3.1 Client / Server 模式
+### 2.2 两种通信模式示例
+#### 2.2.1 Client / Server 模式
在这种模式下，IoTDB 的流处理引擎通过 OPC UA Sink 与 OPC UA 服务器（Server）建立连接。OPC UA
服务器在其地址空间(Address Space) 中维护数据，IoTDB可以请求并获取这些数据。同时，其他OPC
UA客户端（Client）也能访问服务器上的数据。
@@ -84,11 +102,11 @@ start pipe p1;
* 每个测点都被记录为一个变量节点，并记录当前数据库中的最新值。
* OPC UA 无法删除数据或者改变数据类型的设置
-#### 3.1.1 准备工作
+##### 2.2.1.1 准备工作
1. 此处以UAExpert客户端为例，下载 UAExpert
客户端：https://www.unified-automation.com/downloads/opc-ua-clients.html
2. 安装 UAExpert，填写自身的证书等信息。
-#### 3.1.2 快速开始
+##### 2.2.1.2 快速开始
1. 使用如下 sql，启动 OPC UA 服务。详细语法参见上文：[IoTDB OPC
Server语法](./Programming-OPC-UA_timecho.md#_2-1-语法)
```SQL
@@ -127,7 +145,7 @@ insert into root.test.db(time, s2) values(now(), 2)
<img src="/img/OPCUA07.png" alt="" style="width: 60%;"/>
</div>
-### 3.2 Pub / Sub 模式
+#### 2.2.2 Pub / Sub 模式
在这种模式下，IoTDB的流处理引擎通过 OPC UA Sink 向OPC UA
服务器（Server）发送数据变更事件。这些事件被发布到服务器的消息队列中，并通过事件节点 (Event Node) 进行管理。其他OPC
UA客户端（Client）可以订阅这些事件节点，以便在数据变更时接收通知。
@@ -146,7 +164,7 @@ insert into root.test.db(time, s2) values(now(), 2)
- 如果数据被删除，信息则无法推送给客户端。
-#### 3.2.1 准备工作
+##### 2.2.2.1 准备工作
该代码位于 iotdb-example 包下的 [opc-ua-sink
文件夹](https://github.com/apache/iotdb/tree/master/example/pipe-opc-ua-sink/src/main/java/org/apache/iotdb/opcua)中
@@ -157,7 +175,7 @@ insert into root.test.db(time, s2) values(now(), 2)
- Client 的配置及启动逻辑（ClientExampleRunner）
- ClientTest 的父类（ClientExample）
-#### 3.2.2 快速开始
+##### 2.2.2.2 快速开始
使用步骤为：
@@ -167,7 +185,7 @@ insert into root.test.db(time, s2) values(now(), 2)
insert into root.a.b(time, c, d) values(now(), 1, 2);
```
- 此处自动创建元数据开启。
+ 此处自动创建元数据开启。
2. 使用如下 sql，创建并启动 Pub-Sub 模式的 OPC UA Sink。详细语法参见上文：[IoTDB OPC
Server语法](./Programming-OPC-UA_timecho.md#_2-1-语法)
@@ -176,7 +194,7 @@ create pipe p1 with sink ('sink'='opc-ua-sink',
'sink.opcua.model'='pub-sub');
start pipe p1;
```
- 此时能看到服务器的 conf 目录下创建了 opc 证书相关的目录。
+ 此时能看到服务器的 conf 目录下创建了 opc 证书相关的目录。
<div align="center">
<img src="/img/OPCUA08.png" alt="" style="width: 60%;"/>
@@ -221,10 +239,133 @@ start pipe p1;
</div>
-### 3.4 注意事项
+#### 2.2.3 注意事项
1. **单机与集群**：建议使用1C1D单机版，如果集群中有多个 DataNode，可能数据会分散发送在各个 DataNode 上，无法收听到全量数据。
2. **无需操作根目录下证书**：在证书操作过程中，无需操作 IoTDB security 根目录下的 `iotdb-server.pfx` 证书和
client security 目录下的 `example-client.pfx` 目录。Client 和 Server
双向连接时，会将根目录下的证书发给对方，对方如果第一次看见此证书，就会放入 reject dir，如果该证书在 trusted/certs
里面，则能够信任对方。
3. **建议使用** **Java 17+**：在 JVM 8 的版本中，可能会存在密钥长度限制，报 Illegal key size
错误。对于特定版本（如 jdk.1.8u151+），可以在 ClientExampleRunner 的 create client 里加入
`Security.`*`setProperty`*`("crypto.policy", "unlimited");` 解决，也可以下载无限制的包
`local_policy.jar` 与 `US_export_policy `解决替换 `JDK/jre/lib/security
`目录下的包解决，下载网址：https://www.oracle.com/java/technologies/javase-jce8-downloads.html。
+
+4. **连接问题**：如果报错为 Unknown host，需要修改 IoTDB DataNode 所在机器的 etc/hosts 文件，加入目标端机器的
url 和 hostName。
+
+## 3. 数据推送
+
+在此模式下，IoTDB 通过 Pipe 扮演 OPC UA 客户端角色，主动将选定的数据连同质量码(`quality`)一并推送到一个或多个外部 OPC
UA 服务器。外部服务器会自动按 IoTDB 的元数据动态创建目录树和节点。
+
+
+
+### 3.1 OPC 服务启动方式
+
+#### 3.1.1语法
+
+启动 OPC UA 协议的语法：
+
+```SQL
+create pipe p1
+ with source (...)
+ with processor (...)
+ with sink ('sink' = 'opc-ua-sink',
+ 'opcua.node-url' = '127.0.0.1:12686',
+ 'opcua.historizing' = 'true',
+ 'opcua.with-quality' = 'true'
+ )
+```
+
+#### 3.1.2 参数
+
+| **参数** | **描述**
| ** 取值范围 [...]
+|-----------------------|
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| sink | OPC UA SINK
| [...]
+| opcua.node-url | 逗号分隔，可以配置单个 OPC UA 的 tcp port，当存在该参数时，不会启动本机
server，而是发送到配置的 OPC UA Server。
| String
[...]
+| opcua.historizing | 自动创建目录及叶子节点时，新节点是否存变量的历史数据。
| Boolean
[...]
+| opcua.with-quality | OPC UA 的测点发布是否为 value + quality
模式。启用配置后，系统将按以下规则处理写入数据：<br>1. 同时包含 value 和 quality，则直接推送至 OPC UA Server。<br>2.
仅包含 value，则 quality 自动填充为 UNCERTAIN（默认值，支持自定义配置）。<br>3. 仅包含
quality，则该写入被忽略，不进行任何处理。<br>4. 包含非 value/quality
字段，则忽略该数据，并记录警告日志（日志频率可配置，避免高频干扰）。<br>5. quality 类型限制：目前仅支持布尔类型（true 表示
GOOD，false 表示 BAD）； | Boolean
| 选填 [...]
+| opcua.value-name | With-quality 为 true 时生效，表示 value 测点的名字。
| String [...]
+| opcua.quality-name | With-quality 为 true 时生效，表示 quality 测点的名字。
| String [...]
+| opcua.default-quality | 没有 quality 时，可以通过 SQL 参数指定`GOOD`/`UNCERTAIN`/`BAD`。
|
String:`GOOD`/`UNCERTAIN`/ [...]
+| opcua.security-policy | OPC UA client
连接使用的安全策略，不区分大小写，网址为：`http://opcfoundation.org/UA/SecurityPolicy#<policy_name>`，例如http://opcfoundation.org/UA/SecurityPolicy#Aes128_Sha256_RsaOaep
|
String（安全性依次递增）:<br>`None`<br>`Basic128Rsa15`<br>`Basic256`<br>`Basic256Sha256`<br>`Aes128_Sha256_RsaOaep`<br>`Aes256_Sha256_RsaPss`
| 选填| `Basic256Sha256` [...]
+| opcua.timeout-seconds | Client 连接 server 的超时秒数，仅在 IoTDB 为 client 时生效
| Long [...]
+
+> **参数命名注意**：以上参数均支持省略 `opcua.` 前缀，例如 `node-urls` 和 `opcua.node-urls` 等价。
+>
+> **参数支持说明**：V2.0.8 起支持以上`opcua. `相关参数，且仅支持` client-server` 模式
+
+#### 3.1.3 示例
+
+```Bash
+create pipe p1
+ with source (...)
+ with processor (...)
+ with sink ('sink' = 'opc-ua-sink',
+ 'node-urls' = '127.0.0.1:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ )
+```
+
+#### 3.1.4 使用限制
+
+1. 当前模式**仅支持`client-server`****模式和树模型数据**。
+2. 不支持一台机器上配置多个 DataNode，避免抢占相同的端口。
+3. 不支持`OBJECT` 类型的数据推送。
+4. 当某条时间序列改名后，将会联动修改 OPC UA Sink 删除对应的老路径，向新路径推送数据。
+5. 生产环境强烈建议使用非`None`的安全策略（如`Basic256Sha256`），并正确配置证书双向信任。
+
+### 3.2 外置 OPC UA 服务器项目
+
+IoTDB 支持单独的外部 Server 项目。该 Server 的实现及配置项与 IoTDB 目前的内置 Server
相同，但是需要额外支持新增目录及叶子节点，保证可以自动按照 IoTDB 写入中的元数据创建目录及叶子节点。
+
+该 Server 的相关配置在启动 Server 时，需通过命令行的 args 注入，暂不支持 yml、xml 等配置文件。启动参数的键名与 IoTDB
OPC Server 配置项对应，其中配置项中的点（.）和短划线（-）需替换为下划线（\_）。
+
+例如：
+
+```SQL
+.\start-IoTDB-opc-server.sh -enable_anonymous_access true -u root -pw root
-https_port 8443
+```
+
+其中，`user` 和 `password` 可简写为 `-u`、`-p`，其余参数键名均与配置项保持一致。请注意，`userName`
不能作为参数键名，仅支持 `user`。
+
+### 3.3 场景示例
+
+**目标**：将多个数据源的数据，按区域汇聚到3个外部OPC Server，供监控中心统一访问。
+
+
+
+1. **准备**：在三台服务器 (`ip1`, `ip2`, `ip3`) 上分别启动外部 OPC UA Server（端口12686）。
+2. **配置Pipe**：在 IoTDB 中创建3个 Pipe，使用`processor`或`source`中的路径模式过滤，将不同区域的数据推送到对应的
Server。
+ ```SQL
+ -- 启动和连接 IoTDB
+ .\start-standalone.sh
+
+ -- 启动三个 OPC UA Server
+ -- ip1、ip2、ip3 执行三次，端口为默认，12686
+ .\start-IoTDB-external-opc-server.sh -enable-anonymous-access true -u root
-pw root
+
+ -- 创建三个 Pipe
+ .\start-cli.sh
+ create pipe p1
+ with source (<ip1相关的用户名和密码>)
+ with processor (...)
+ with sink ('sink' = 'opc-ua-sink',
+ 'node-urls' = 'ip1:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ );
+ create pipe p1
+ with source (<ip2相关的用户名和密码>)
+ with processor (...)
+ with sink ('sink' = 'opc-ua-sink',
+ 'node-urls' = 'ip2:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ );
+ create pipe p1
+ with source (<ip3相关的用户名和密码>)
+ with processor (...)
+ with sink ('sink' = 'opc-ua-sink',
+ 'node-urls' = 'ip3:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ );
+ ```
+3. **效果**：监控中心只需连接 `ip1`, `ip2`, `ip3` 这三个Server，即可获取所有区域的完整数据视图，且数据附带质量信息。
diff --git a/src/zh/UserGuide/latest/API/Programming-OPC-UA_timecho.md
b/src/zh/UserGuide/latest/API/Programming-OPC-UA_timecho.md
index eea7e97f..cb545a4d 100644
--- a/src/zh/UserGuide/latest/API/Programming-OPC-UA_timecho.md
+++ b/src/zh/UserGuide/latest/API/Programming-OPC-UA_timecho.md
@@ -21,16 +21,28 @@
# OPC UA 协议
-## 1. OPC UA 订阅数据
+## 1. 功能概述
-本功能支持用户以 OPC UA 协议从 IoTDB 中订阅数据，订阅数据的通信模式支持 Client/Server 和 Pub/Sub 两种。
+本文档介绍了 IoTDB 与 OPC UA 协议集成的两种独立工作模式，请根据您的业务场景进行选择：
+
+* **模式一：数据订阅服务 (IoTDB 作为 OPC UA 服务器)**：IoTDB 启动内置的 OPC UA 服务器，被动地允许外部客户端（如
UAExpert）连接并订阅其内部数据。这是传统用法。
+* **模式二：数据主动推送 (IoTDB 作为 OPC UA 客户端)**：IoTDB 作为客户端，主动将数据和元数据同步到一个或多个独立部署的外部
OPC UA 服务器。
+ > 注意：该模式从 V2.0.8 起支持。
+
+**注意：模式互斥**
+
+当 Pipe 配置中指定了 `node-urls` 参数（模式二），IoTDB 将不会启动内置的 OPC UA 服务器（模式一）。两种模式在同一 Pipe
中**不可同时使用**。
+
+## 2. 数据订阅
+
+本模式支持用户以 OPC UA 协议从 IoTDB 中订阅数据，订阅数据的通信模式支持 Client/Server 和 Pub/Sub 两种。
注意：本功能并非从外部 OPC Server 中采集数据写入 IoTDB
-## 2. OPC 服务启动方式
-### 2.1 语法
+### 2.1 OPC 服务启动方式
+#### 2.1.1 语法
启动 OPC UA 协议的语法：
@@ -47,20 +59,26 @@ create pipe p1
)
```
-### 2.2 参数
-
-| **参数** | **描述** | ** 取值范围 ** |
**是否必填** | **默认值**
|
-| ------------------------------------ | -------------------------------- |
---------------------------------- | --------------------
|-----------------------------------------------------------------------------------------------------------------------------------------------------------|
-| sink | OPC UA SINK |
String: opc-ua-sink | 必填 |
|
-| sink.opcua.model | OPC UA 使用的模式 | String:
client-server / pub-sub | 选填 | client-server
|
-| sink.opcua.tcp.port | OPC UA 的 TCP 端口 | Integer:
[0, 65536] | 选填 | 12686
|
-| sink.opcua.https.port | OPC UA 的 HTTPS 端口 | Integer:
[0, 65536] | 选填 | 8443
|
-| sink.opcua.security.dir | OPC UA 的密钥及证书目录 | String:
Path，支持绝对及相对目录 | 选填 | 1. iotdb 相关 DataNode 的 conf 目录下的
opc\_security 文件夹 / `<httpsPort:tcpPort>`。2. 如无 iotdb 的 conf 目录（例如 IDEA 中启动
DataNode），则为用户主目录下的 iotdb\_opc\_security 文件夹 /`<httpsPort:tcpPort>`|
-| sink.opcua.enable-anonymous-access | OPC UA 是否允许匿名访问 | Boolean
| 选填 | true
|
-| sink.user | 用户，这里指 OPC UA 的允许用户 | String
| 选填 | root
|
-| sink.password | 密码，这里指 OPC UA 的允许密码 | String
| 选填 | TimechoDB@2021 （V2.0.6.x 之前默认密码为root ）
|
-
-### 2.3 示例
+#### 2.1.2 参数
+
+| **参数** | **描述**
[...]
+| ------------------------------------ |
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| sink | OPC UA SINK
[...]
+| sink.opcua.model | OPC UA 使用的模式
[...]
+| sink.opcua.tcp.port | OPC UA 的 TCP 端口
[...]
+| sink.opcua.https.port | OPC UA 的 HTTPS 端口
[...]
+| sink.opcua.security.dir | OPC UA 的密钥及证书目录
[...]
+| opcua.security-policy | OPC UA
连接使用的安全策略，不区分大小写。可以配置多个，用`,`连接。配置一个安全策略后，client
才能用对应的策略连接。当前实现默认支持`None`和`Basic256Sha256`策略，应该默认改为任意的非`None`策略，`None`策略在调试环境中单独配置，因为`None`策略虽然不需移动证书，操作方便，但是不安全，生产环境的
server 不建议支持该策略。注意：V2.0.8 起支持该参数，且仅支持 client-server 模式
|
String（安全性依次递增）:<br>`None`<br>`Basic128Rsa15`<br>`Basic256`<br>`Basic256Sha256`<br>`Aes128_Sha256
[...]
+| sink.opcua.enable-anonymous-access | OPC UA 是否允许匿名访问
[...]
+| sink.user | 用户，这里指 OPC UA 的允许用户
[...]
+| sink.password | 密码，这里指 OPC UA 的允许密码
[...]
+| opcua.with-quality | OPC UA 的测点发布是否为 value + quality
模式。启用配置后，系统将按以下规则处理写入数据：<br>1. 同时包含 value 和 quality，则直接推送至 OPC UA Server。<br>2.
仅包含 value，则 quality 自动填充为 UNCERTAIN（默认值，支持自定义配置）。<br>3. 仅包含
quality，则该写入被忽略，不进行任何处理。<br>4. 包含非 value/quality
字段，则忽略该数据，并记录警告日志（日志频率可配置，避免高频干扰）。<br>5. quality 类型限制：目前仅支持布尔类型（true 表示
GOOD，false 表示 BAD）； 注意：V2.0.8 起支持该参数，且仅支持 client-server 模式 | Boolean
[...]
+| opcua.value-name | With-quality 为 true 时生效，表示 value 测点的名字。
注意：V2.0.8 起支持该参数，且仅支持 client-server 模式
[...]
+| opcua.quality-name | With-quality 为 true 时生效，表示 quality
测点的名字。 注意：V2.0.8 起支持该参数，且仅支持 client-server 模式
[...]
+| opcua.default-quality | 没有 quality 时，可以通过 SQL
参数指定`GOOD`/`UNCERTAIN`/`BAD`。 注意：V2.0.8 起支持该参数，且仅支持 client-server 模式
[...]
+| opcua.timeout-seconds | Client 连接 server 的超时秒数，仅在 IoTDB 为
client 时生效 注意：V2.0.8 起支持该参数，且仅支持 client-server 模式
[...]
+
+#### 2.1.3 示例
```Bash
create pipe p1
@@ -70,12 +88,12 @@ create pipe p1
start pipe p1;
```
-### 2.4 使用限制
+#### 2.1.4 使用限制
1. 启动协议之后需要写入数据，才能建立连接，且仅能订阅建立连接之后的数据。
2. 推荐在单机模式下使用。在分布式模式下，每一个 IoTDB DataNode 都作为一个独立的 OPC Server 提供数据，需要单独订阅。
-## 3. 两种通信模式示例
-### 3.1 Client / Server 模式
+### 2.2 两种通信模式示例
+#### 2.2.1 Client / Server 模式
在这种模式下，IoTDB 的流处理引擎通过 OPC UA Sink 与 OPC UA 服务器（Server）建立连接。OPC UA
服务器在其地址空间(Address Space) 中维护数据，IoTDB可以请求并获取这些数据。同时，其他OPC
UA客户端（Client）也能访问服务器上的数据。
@@ -84,11 +102,11 @@ start pipe p1;
* 每个测点都被记录为一个变量节点，并记录当前数据库中的最新值。
* OPC UA 无法删除数据或者改变数据类型的设置
-#### 3.1.1 准备工作
+##### 2.2.1.1 准备工作
1. 此处以UAExpert客户端为例，下载 UAExpert
客户端：https://www.unified-automation.com/downloads/opc-ua-clients.html
2. 安装 UAExpert，填写自身的证书等信息。
-#### 3.1.2 快速开始
+##### 2.2.1.2 快速开始
1. 使用如下 sql，启动 OPC UA 服务。详细语法参见上文：[IoTDB OPC
Server语法](./Programming-OPC-UA_timecho.md#_2-1-语法)
```SQL
@@ -127,7 +145,7 @@ insert into root.test.db(time, s2) values(now(), 2)
<img src="/img/OPCUA07.png" alt="" style="width: 60%;"/>
</div>
-### 3.2 Pub / Sub 模式
+#### 2.2.2 Pub / Sub 模式
在这种模式下，IoTDB的流处理引擎通过 OPC UA Sink 向OPC UA
服务器（Server）发送数据变更事件。这些事件被发布到服务器的消息队列中，并通过事件节点 (Event Node) 进行管理。其他OPC
UA客户端（Client）可以订阅这些事件节点，以便在数据变更时接收通知。
@@ -146,7 +164,7 @@ insert into root.test.db(time, s2) values(now(), 2)
- 如果数据被删除，信息则无法推送给客户端。
-#### 3.2.1 准备工作
+##### 2.2.2.1 准备工作
该代码位于 iotdb-example 包下的 [opc-ua-sink
文件夹](https://github.com/apache/iotdb/tree/master/example/pipe-opc-ua-sink/src/main/java/org/apache/iotdb/opcua)中
@@ -157,7 +175,7 @@ insert into root.test.db(time, s2) values(now(), 2)
- Client 的配置及启动逻辑（ClientExampleRunner）
- ClientTest 的父类（ClientExample）
-#### 3.2.2 快速开始
+##### 2.2.2.2 快速开始
使用步骤为：
@@ -167,7 +185,7 @@ insert into root.test.db(time, s2) values(now(), 2)
insert into root.a.b(time, c, d) values(now(), 1, 2);
```
- 此处自动创建元数据开启。
+ 此处自动创建元数据开启。
2. 使用如下 sql，创建并启动 Pub-Sub 模式的 OPC UA Sink。详细语法参见上文：[IoTDB OPC
Server语法](./Programming-OPC-UA_timecho.md#_2-1-语法)
@@ -176,7 +194,7 @@ create pipe p1 with sink ('sink'='opc-ua-sink',
'sink.opcua.model'='pub-sub');
start pipe p1;
```
- 此时能看到服务器的 conf 目录下创建了 opc 证书相关的目录。
+ 此时能看到服务器的 conf 目录下创建了 opc 证书相关的目录。
<div align="center">
<img src="/img/OPCUA08.png" alt="" style="width: 60%;"/>
@@ -221,10 +239,133 @@ start pipe p1;
</div>
-### 3.4 注意事项
+#### 2.2.3 注意事项
1. **单机与集群**：建议使用1C1D单机版，如果集群中有多个 DataNode，可能数据会分散发送在各个 DataNode 上，无法收听到全量数据。
2. **无需操作根目录下证书**：在证书操作过程中，无需操作 IoTDB security 根目录下的 `iotdb-server.pfx` 证书和
client security 目录下的 `example-client.pfx` 目录。Client 和 Server
双向连接时，会将根目录下的证书发给对方，对方如果第一次看见此证书，就会放入 reject dir，如果该证书在 trusted/certs
里面，则能够信任对方。
3. **建议使用** **Java 17+**：在 JVM 8 的版本中，可能会存在密钥长度限制，报 Illegal key size
错误。对于特定版本（如 jdk.1.8u151+），可以在 ClientExampleRunner 的 create client 里加入
`Security.`*`setProperty`*`("crypto.policy", "unlimited");` 解决，也可以下载无限制的包
`local_policy.jar` 与 `US_export_policy `解决替换 `JDK/jre/lib/security
`目录下的包解决，下载网址：https://www.oracle.com/java/technologies/javase-jce8-downloads.html。
+
+4. **连接问题**：如果报错为 Unknown host，需要修改 IoTDB DataNode 所在机器的 etc/hosts 文件，加入目标端机器的
url 和 hostName。
+
+## 3. 数据推送
+
+在此模式下，IoTDB 通过 Pipe 扮演 OPC UA 客户端角色，主动将选定的数据连同质量码(`quality`)一并推送到一个或多个外部 OPC
UA 服务器。外部服务器会自动按 IoTDB 的元数据动态创建目录树和节点。
+
+
+
+### 3.1 OPC 服务启动方式
+
+#### 3.1.1语法
+
+启动 OPC UA 协议的语法：
+
+```SQL
+create pipe p1
+ with source (...)
+ with processor (...)
+ with sink ('sink' = 'opc-ua-sink',
+ 'opcua.node-url' = '127.0.0.1:12686',
+ 'opcua.historizing' = 'true',
+ 'opcua.with-quality' = 'true'
+ )
+```
+
+#### 3.1.2 参数
+
+| **参数** | **描述**
| ** 取值范围 [...]
+|-----------------------|
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
[...]
+| sink | OPC UA SINK
| [...]
+| opcua.node-url | 逗号分隔，可以配置单个 OPC UA 的 tcp port，当存在该参数时，不会启动本机
server，而是发送到配置的 OPC UA Server。
| String
[...]
+| opcua.historizing | 自动创建目录及叶子节点时，新节点是否存变量的历史数据。
| Boolean
[...]
+| opcua.with-quality | OPC UA 的测点发布是否为 value + quality
模式。启用配置后，系统将按以下规则处理写入数据：<br>1. 同时包含 value 和 quality，则直接推送至 OPC UA Server。<br>2.
仅包含 value，则 quality 自动填充为 UNCERTAIN（默认值，支持自定义配置）。<br>3. 仅包含
quality，则该写入被忽略，不进行任何处理。<br>4. 包含非 value/quality
字段，则忽略该数据，并记录警告日志（日志频率可配置，避免高频干扰）。<br>5. quality 类型限制：目前仅支持布尔类型（true 表示
GOOD，false 表示 BAD）； | Boolean
| 选填 [...]
+| opcua.value-name | With-quality 为 true 时生效，表示 value 测点的名字。
| String [...]
+| opcua.quality-name | With-quality 为 true 时生效，表示 quality 测点的名字。
| String [...]
+| opcua.default-quality | 没有 quality 时，可以通过 SQL 参数指定`GOOD`/`UNCERTAIN`/`BAD`。
|
String:`GOOD`/`UNCERTAIN`/ [...]
+| opcua.security-policy | OPC UA client
连接使用的安全策略，不区分大小写，网址为：`http://opcfoundation.org/UA/SecurityPolicy#<policy_name>`，例如http://opcfoundation.org/UA/SecurityPolicy#Aes128_Sha256_RsaOaep
|
String（安全性依次递增）:<br>`None`<br>`Basic128Rsa15`<br>`Basic256`<br>`Basic256Sha256`<br>`Aes128_Sha256_RsaOaep`<br>`Aes256_Sha256_RsaPss`
| 选填| `Basic256Sha256` [...]
+| opcua.timeout-seconds | Client 连接 server 的超时秒数，仅在 IoTDB 为 client 时生效
| Long [...]
+
+> **参数命名注意**：以上参数均支持省略 `opcua.` 前缀，例如 `node-urls` 和 `opcua.node-urls` 等价。
+>
+> **参数支持说明**：V2.0.8 起支持以上`opcua. `相关参数，且仅支持` client-server` 模式
+
+#### 3.1.3 示例
+
+```Bash
+create pipe p1
+ with source (...)
+ with processor (...)
+ with sink ('sink' = 'opc-ua-sink',
+ 'node-urls' = '127.0.0.1:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ )
+```
+
+#### 3.1.4 使用限制
+
+1. 当前模式**仅支持`client-server`****模式和树模型数据**。
+2. 不支持一台机器上配置多个 DataNode，避免抢占相同的端口。
+3. 不支持`OBJECT` 类型的数据推送。
+4. 当某条时间序列改名后，将会联动修改 OPC UA Sink 删除对应的老路径，向新路径推送数据。
+5. 生产环境强烈建议使用非`None`的安全策略（如`Basic256Sha256`），并正确配置证书双向信任。
+
+### 3.2 外置 OPC UA 服务器项目
+
+IoTDB 支持单独的外部 Server 项目。该 Server 的实现及配置项与 IoTDB 目前的内置 Server
相同，但是需要额外支持新增目录及叶子节点，保证可以自动按照 IoTDB 写入中的元数据创建目录及叶子节点。
+
+该 Server 的相关配置在启动 Server 时，需通过命令行的 args 注入，暂不支持 yml、xml 等配置文件。启动参数的键名与 IoTDB
OPC Server 配置项对应，其中配置项中的点（.）和短划线（-）需替换为下划线（\_）。
+
+例如：
+
+```SQL
+.\start-IoTDB-opc-server.sh -enable_anonymous_access true -u root -pw root
-https_port 8443
+```
+
+其中，`user` 和 `password` 可简写为 `-u`、`-p`，其余参数键名均与配置项保持一致。请注意，`userName`
不能作为参数键名，仅支持 `user`。
+
+### 3.3 场景示例
+
+**目标**：将多个数据源的数据，按区域汇聚到3个外部OPC Server，供监控中心统一访问。
+
+
+
+1. **准备**：在三台服务器 (`ip1`, `ip2`, `ip3`) 上分别启动外部 OPC UA Server（端口12686）。
+2. **配置Pipe**：在 IoTDB 中创建3个 Pipe，使用`processor`或`source`中的路径模式过滤，将不同区域的数据推送到对应的
Server。
+ ```SQL
+ -- 启动和连接 IoTDB
+ .\start-standalone.sh
+
+ -- 启动三个 OPC UA Server
+ -- ip1、ip2、ip3 执行三次，端口为默认，12686
+ .\start-IoTDB-external-opc-server.sh -enable-anonymous-access true -u root
-pw root
+
+ -- 创建三个 Pipe
+ .\start-cli.sh
+ create pipe p1
+ with source (<ip1相关的用户名和密码>)
+ with processor (...)
+ with sink ('sink' = 'opc-ua-sink',
+ 'node-urls' = 'ip1:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ );
+ create pipe p1
+ with source (<ip2相关的用户名和密码>)
+ with processor (...)
+ with sink ('sink' = 'opc-ua-sink',
+ 'node-urls' = 'ip2:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ );
+ create pipe p1
+ with source (<ip3相关的用户名和密码>)
+ with processor (...)
+ with sink ('sink' = 'opc-ua-sink',
+ 'node-urls' = 'ip3:12686',
+ 'historizing' = 'true',
+ 'with-quality' = 'true'
+ );
+ ```
+3. **效果**：监控中心只需连接 `ip1`, `ip2`, `ip3` 这三个Server，即可获取所有区域的完整数据视图，且数据附带质量信息。
