集成连接器的 Integration Runtime 服务的初始设置
安装 ThingWorx 后，请按照以下步骤下载并配置 ThingWorx 运行时服务。如果您处于 Docker 环境中，则可以使用安装程序为集成连接器设置基本配置。安装程序包括一个日志记录文件，您可以在其中修改某些配置，如下所述。
下载 Integration Runtime
Integration Runtime 服务可在
support.ptc.com 中的如下位置获得：“下载软件”>“订购或下载软件更新”> ThingWorx Foundation >“发行 <版本>”> ThingWorx Integration Runtime >“最近的日期代码”> ThingWorx-Integration-Runtime-<版本>。
配置 Integration Runtime
 |
不能从 IntegrationRuntime 事物模板创建事物。
|
1. 在 ThingWorx 中为 Integration Runtime 创建一个应用程序密钥，用于与 ThingWorx Platform 进行通信。
2. 使用以下选项之一将集成服务作为 Java 进程来启动：
◦ 指定连接参数的外部配置文件。
java -DconfigFile=<path to IntegrationRuntime settings>-jar <path to IntegrationRuntime-x.x.x>.jar，其中 x.x.x 需要替换为所使用的版本。
3. (可选) 创建自定义 logback 设置文件并使用以下命令在命令行上指定其路径：-Dlogs.includedLogback=<path to logback include>
4. 如果要在 integrationRuntime-settings.json 配置文件中
加密条目或
加密整个配置文件，则必须在命令行中通过以下命令指定 security-common 加密配置的路径：
|
|
如果要加密整个配置文件，并且该文件必须指向已加密 Integration Runtime 配置文件，则 -Dencrypted.config.file=true 在以下示例中必不可少。如果仅对文件中的条目进行加密，请忽略此设置或将其设置为 false。
|
java -Dsecret.management.config.file=<encryption.conf 的路径> -Dencrypted.config.file=true -DconfigFile=<加密 integrationRuntime-settings.json.encrypted 的路径>
下面提供了一个示例命令：
java -Dsecret.management.config.file=C:\Integ_runtime\encryption.conf -Dencrypted.config.file=true -DconfigFile=integrationRuntime-settings.json.encrypted -jar C:\Integ_runtime\integration-runtime-x.x.x-bXXX.jar
示例配置文件 (integrationRuntime-settings.json)
{
"traceRoutes": "false",
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"basePath": "/Thingworx",
"sslEnable": "true",
"ignoreSSLErrors": "false"
},
"SSL": {
"verbose": "true",
"Keystore": {
"path": "/usr/security/keystore.jks",
"password": "encrypt.keystore.password"
},
"Truststore": {
"path": "/usr/security/truststore",
"password": "encrypt.truststore.password"
}
},
"RetryPolicy": {
"MaximumRetries": 2,
"RetryDelay": 2000,
"BackoffMultiplier": 1
},
"RedirectPolicy": {
"MaximumRedirects": 3,
"EnableRedirect": true
}
}
"traceRoutes": "false",
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"basePath": "/Thingworx",
"sslEnable": "true",
"ignoreSSLErrors": "false"
},
"SSL": {
"verbose": "true",
"Keystore": {
"path": "/usr/security/keystore.jks",
"password": "encrypt.keystore.password"
},
"Truststore": {
"path": "/usr/security/truststore",
"password": "encrypt.truststore.password"
}
},
"RetryPolicy": {
"MaximumRetries": 2,
"RetryDelay": 2000,
"BackoffMultiplier": 1
},
"RedirectPolicy": {
"MaximumRedirects": 3,
"EnableRedirect": true
}
}
配置文件设置
如说明中所述，可以指定一些配置设置，或使用 Java 系统属性覆盖配置文件设置 (例如 -D<name>=<value>)。
|
设置
|
默认值
|
说明
|
|---|---|---|
|
traceRoute
|
false
|
指定在调用路由中的每个处理器时，路由执行是否应记录消息。
|
|
Thingworx
|
以 JSON 格式指定连接到 ThingWorx Platform 的设置。
|
|
|
SSL
|
以 JSON 格式指定安全套接字层 (SSL) 设置。
|
|
设置
|
默认值
|
说明
|
||
|---|---|---|---|---|
|
appKey
|
指定已配置为供此 Integration Runtime 使用的 ThingWorx Platform 中的应用程序密钥。此设置可由 Java 系统属性覆盖。
|
|||
|
basePath
|
/Thingworx
|
指定 ThingWorx Platform 的 URI 中的基本路径。此设置可由 Java 系统属性覆盖。
|
||
|
主机
|
localhost
|
指定 ThingWorx Platform 的 URI 中的主机。此设置可由 Java 系统属性覆盖。
|
||
|
端口
|
443
|
指定 ThingWorx Platform 的 URI 中的端口。此设置可由 Java 系统属性覆盖。
|
||
|
sslEnable
|
true
|
指定是否应使用 SSL 通过 WebSocket 连接到 ThingWorx Platform。如果为 true，则 URI 使用 "wss" 协议。否则，使用 "ws" 协议。
|
||
|
ignoreSSLErrors
|
false
|
指定是否应忽略 SSL 错误。在生产环境中，此值不应设置为 true。
|
|
设置
|
默认值
|
说明
|
|---|---|---|
|
verbose
|
false
|
指定 Java 握手协议是否输出详细消息。如果为 true，则 Java 系统属性 javax.net.debug 设置为 ssl:handshake:verbose。
|
|
Keystore
|
以 JSON 格式指定 SSL 密钥库设置。
|
|
|
Truststore
|
以 JSON 格式指定 SSL 信任库设置。
|
|
设置
|
说明
|
|---|---|
|
path
|
指定 SSL 密钥库文件的路径。使用此设置相当于设置 Java 系统属性 javax.net.ssl.keyStore。
|
|
password
|
指定 SSL 密钥库文件的密码。使用此设置相当于设置 Java 系统属性 javax.net.ssl.keyStorePassword。要避免以纯文本格式存储密码，请使用值 encrypt.keystore.password。请参阅下面的“加密密码设置”部分。
|
|
设置
|
说明
|
|---|---|
|
path
|
指定 SSL 信任库文件的路径。使用此设置相当于设置 Java 系统属性 javax.net.ssl.trustStore。
|
|
password
|
指定 SSL 信任库文件的密码。使用此设置相当于设置 Java 系统属性 javax.net.ssl.trustStorePassword。要避免以纯文本格式存储密码，请使用值 encrypt.truststore.password。请参阅下面的“加密密码设置”部分。
|
|
设置
|
默认值
|
说明
|
|---|---|---|
|
MaximumRetries
|
2
|
指定由于系统可用性而导致请求失败后重新尝试请求的次数。
在 HTTP 请求的情况下，通过服务器的 503 响应发生重试。
|
|
RetryDelay
|
1000
|
当一个请求失败，但可以重试时，RetryDelay 表示尝试重试之前等待的时长 (以毫秒为单位)。确定后续重试时，RetryDelay 将与 BackoffMultiplier 结合使用。
|
|
BackoffMultiplier
|
1
|
指定在后续重试时成倍增加 RetryDelay 的时长。例如，如果 BackoffMultiplier 设置为 2 且 MaximumRetries 设置为 3，则第一次重试将在 1 秒后发生；第二次重试会在第一次重试之后 2 秒发生；第三次重试会在第二次重试之后 4 秒出现，依此类推。
|
|
UnauthorizedRetries
|
2
|
指定重新尝试由于未经授权的请求而失败的请求的次数。此设置适用于具有来自服务器的 401 响应的 HTTP 请求。
|
|
设置
|
默认值
|
说明
|
|---|---|---|
|
MaximumRedirects
|
3
|
指定重试重定向的次数。
|
|
EnableRedirect
|
true
|
指定是否针对导致重定向状态代码 3xx 的请求启用重定向。
|
加密配置文件
为了提供更高的安全性，您可以加密整个配置文件，也可以对文件中的各个值进行加密。Integration Runtime 8.0.4+ 版本中提供了此功能。Integration Runtime 的安装包括 security-common 库。此库的 JAR 包括在 Integration Runtime 安装中。它可提供对配置文件进行加密和解密的后端工具。
命令行界面 (CLI) 可与安全库进行交互，其中包括对配置文件进行加密。有关此 CLI 的完整信息，请参阅
安全管理工具。本主题将介绍获取工具的位置及其使用方法。为方便起见，以下各部分提供了 Integration Runtime 特定步骤。您可从
PTC 支持网站下载 CLI。
1. security-common 库需要有其自己的配置文件。使用文本编辑器创建以下文件并将其另存为 encryption.conf：
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128
keystore {
password-file-path = "/ThingworxPlatform"
password-file-name = "keystore-password"
path = "/ThingworxStorage"
name = "keystore"
}
}
}
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128
keystore {
password-file-path = "/ThingworxPlatform"
password-file-name = "keystore-password"
path = "/ThingworxStorage"
name = "keystore"
}
}
}
2. 创建在 encryption.conf 文件中指定的 password-file-path 和 path 目录。在上述示例中，password-file-path 目录为 /ThingworxPlatform (Linux)。在 Windows 计算机上，该目录为 C:\\ThingworxPlatform。
|
|
您可以将加密的配置文件存储在任意位置。只需确保加密配置文件和环境变量指向正确的路径即可。
|
3. 假定您已下载并提取了 CLI 分布，则可以对配置文件进行加密。打开命令提示符或 Shell，然后导航至 securitycommon-cli-x.x.x.xx/bin 目录，其中，x.x.x.xx 表示工具的版本。
4. 请根据您的操作系统运行 CLI：
◦ Linux - security-common-cli
◦ Windows - security-common-cli.bat
5. 出现提示时，输入要初始化的安全配置文件的名称。以下是序列的 Linux 示例：
../security-common-cli-1.x.x.xx/bin$ ./security-common-cli
Not initialized, use 'init <config-file>' to initialize
> init [pathTo]encryption.conf
Loading config from file encryption.conf
Secret Provider: com.thingworx.security.provider.keystore.KeyStoreProvider
KeyStore
Path: /ThingworxPlatform/keystore
Password File: /ThingworxStorage/keystore-password
Keystore Password: 336974503775017XXXX
>
Not initialized, use 'init <config-file>' to initialize
> init [pathTo]encryption.conf
Loading config from file encryption.conf
Secret Provider: com.thingworx.security.provider.keystore.KeyStoreProvider
KeyStore
Path: /ThingworxPlatform/keystore
Password File: /ThingworxStorage/keystore-password
Keystore Password: 336974503775017XXXX
>
6. 虽然仍位于安全 CLI 中，但仍需对 Integration Runtime 的配置文件进行加密。如下所示，在本示例中，使用 encryptFile 命令的为 integrationRuntime-settings.json：
encryptFile C:\Integ_runtime\integrationRuntime-settings.json C:\Integ_runtime\integrationRuntime-settings.json.encrypted
integrationRuntime-settings.json.encrypted 为您加密的配置文件。
7. 使用 decryptFile 命令验证加密是否成功：decryptFile C:\Integ_runtime\integrationRuntime-settings.json.encrypted C:\Integ_runtime\integrationRuntime-settings.json.decrypted
|
|
integrationRuntime-settings.json.decrypted 的内容应与原始 integrationRuntime-settings.json 文件的内容相匹配。
|
|
|
移除文件的未加密版本。
|
8. 要关闭 CLI，请在提示符中键入 exit。
对配置文件中的条目进行加密
配置文件中的密码或其他条目可在 Integration Runtime 8.0.4+ 中进行加密。使用与 ThingWorx Platform 相同的加密机制 (用于加密 PostgreSQL 数据库密码)。
请按照
加密密码中的说明进行操作，但需用值 encrypt.app.key 替代 encrypt.db.password 或 encrypt.licensing.password，并用 integrationRuntime-settings.json 替代 platform-settings.json。如果 ThingWorx 系统已经在使用 PostgreSQL 数据库密码加密，则这些新密码会被添加到同一 keystore 文件中；否则，将创建一个新的 keystore 文件。
迁移密钥库和密钥库密码
如果使用 keystore 对值进行加密，并且正在执行迁移，那么请针对 keystore 和密码文件完成下列步骤：
1. 如果 Integration Runtime 仍使用 twx/config 和 /ThingworxStorage/keyStore 作为您的 keystore 文件，则请执行下列步骤：
◦ 将 /twx/config 复制到 /ThingworxPlatform/keystore-password
◦ 将 /ThingworxStorage/keyStore 复制到 /ThingworxStorage/keystore.jks
2. 从 ThingWorx 8.5 开始，keystore 格式从 .jks 更改为 .pfx。您需要迁移 keystore。有关详细信息，请参阅
安全管理工具主题中的“ThingWorx 8.5 中的更改”。
3. 此步骤会有所不同，具体取决于您的集成运行时是否与 8.5+ ThingWorx 服务器的 keystore 共享 keystore 文件：
◦ 如果它与 8.5+ ThingWorx Platform 的 keystore 共享 keystore 文件，请遵循
升级 ThingWorx 指南，以使 ThingWorx 服务器自动将 keystore 文件从旧的 ".jks" 迁移到新的 ".pfx" 格式。
◦ 如果它不与平台共享 keystore 文件，请按以下步骤操作：
2. 启动 CLI，系统将自动迁移 keystore。例如：
./security-common-cli encryption.conf
3. 在您的 encryption.conf 文件中，将 keystore.jks 的所有参考更改为 keystore。不要包括 .pfx 文件扩展名。
4. 将旧的 keystore.jks 备份到安全位置，并将其从 ThingworxStorage 目录中移除。
配置 SSL
默认情况下，Integration Runtime 将使用 SSL 连接到 ThingWorx。下表介绍了成功连接所需的 ThingWorx Platform 配置和相关的 Integration Runtime 配置设置。连接到 ThingWorx Platform 时，keystore 设置并不是必需的；它们通过双向 SSL 协商从 Integration Runtime 提供客户端证书。
|
ThingWorx 配置
|
集成运行时设置
|
|---|---|
|
ThingWorx 未配置为 SSL
|
使用 Java 系统属性指定 thingworxUri，并使用 ws 协议或在 SSL 设置中指定 sslEnable=false。
|
|
ThingWorx 配置为使用自签名证书的 SSL
|
在 SSL 设置中指定 sslEnable=true 和 ignoreSSLErrors=true。
|
|
ThingWorx 使用自签名证书配置为 SSL 且该证书可信。
ThingWorx 使用由证书颁发机构 (CA) 签名的证书配置为 SSL，但未配置为提供整个 CA 证书链。
|
从密钥库文件导出证书，然后将其导入到信任库文件。
在 SSL 设置中指定 enable=true 和 Trustore。
信任库密码可能被加密。
或者，将证书添加到 Integration Runtime JVM 默认信任库 (通常位于：$JAVA_HOME/lib/security/cacerts)。在这种情况下，不需要在 SSL 设置中明确指定信任库。
|
|
ThingWorx 使用由证书颁发机构 (CA) 签名的证书配置为 SSL，且已配置为提供整个 CA 证书链。
|
在 SSL 设置中指定 enable=true。这是默认设置。
|
SSL 配置示例：非生产配置
如果 ThingWorx 使用自签名证书配置为 SSL，请使用以下 integrationRuntime-settings.json：
{
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"sslEnable": "true",
"ignoreSSLErrors": "true"
}
}
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"sslEnable": "true",
"ignoreSSLErrors": "true"
}
}
SSL 配置示例：生产配置
如果 ThingWorx 使用自签名证书配置为 SSL，请使用以下步骤创建信任库：
1. 获取服务器的自签名证书。它用于在下一步中强制 Integration Runtime 信任它。
如果没有本地存储的证书，则这是获取 ThingWorx Platform 的自签名证书的一种方法。
openssl s_client -connect your-ThingWorx-platform:8443< /dev/null| sed -ne'/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'twx-platform-public.crt
2. 创建 Integration Runtime 将用来信任服务器自签名证书的信任库的本地副本。
首先保存副本，然后将缺失的证书添加至该副本，而不是将缺失的证书直接添加至 JVM 库存信任库。
cp $JAVA_HOME/jre/lib/security/cacerts /etc/opt/java/security/cacerts-customized
$JAVA_HOME/bin/keytool -importcert -alias somealias -keystore /etc/opt/java/security/cacerts-customized -file twx-platform-public.crt
$JAVA_HOME/bin/keytool -importcert -alias somealias -keystore /etc/opt/java/security/cacerts-customized -file twx-platform-public.crt
3. 更改信任库的密码。
JVM cacerts 文件的默认密码为 changeit。与更改任何其他密钥库的密码类似，可以通过发出以下命令来更改 cacerts-customized 的密码：
keytool storepasswd keystore /etc/opt/java/security/cacerts-customized
Enter keystore password: changeit
New keystore password: new-password
Re-enter new keystore password: new-password
Enter keystore password: changeit
New keystore password: new-password
Re-enter new keystore password: new-password
4. 使用以下 integrationRuntime-settings.json。
{
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"sslEnable": "true",
"ignoreSSLErrors": "false"
}
"SSL": {
"Truststore": {
"path": "/etc/opt/java/security/cacerts-customized",
"password": "new-password"
}
}
}
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"sslEnable": "true",
"ignoreSSLErrors": "false"
}
"SSL": {
"Truststore": {
"path": "/etc/opt/java/security/cacerts-customized",
"password": "new-password"
}
}
}
示例日志配置文件 (integrationRuntime-logback.xml)
<?xml version="1.0"?>
<included>
<property name="logs.dir" value="/ThingworxStorage/IRlogs" />
<property name="logs.uniqueId" value="${processId}" />
<property name="logs.maxFileSize" value="1MB" />
<property name="logs.maxIndex" value="5" />
<logger name="com.twx.integration" level="DEBUG" />
<logger name="org.apache.camel" level="DEBUG" />
</included>
<included>
<property name="logs.dir" value="/ThingworxStorage/IRlogs" />
<property name="logs.uniqueId" value="${processId}" />
<property name="logs.maxFileSize" value="1MB" />
<property name="logs.maxIndex" value="5" />
<logger name="com.twx.integration" level="DEBUG" />
<logger name="org.apache.camel" level="DEBUG" />
</included>
日志配置文件设置
IntegrationRuntime.jar 中包含标准的 logback.xml 配置文件。有关 logback 配置的详细信息，请参阅
Logback 项目。此文件设置了根记录器，可用于向控制台和滚动日志文件中记录日志。您可使用此 Java 系统属性来指定可选的包含文件：logs.includedLogback。使用包含文件可启用其他记录器并指定属性。滚动日志文件配置了固定的窗口和基于大小的触发策略，且可以通过设置以下属性进行自定义：
|
设置
|
默认值
|
说明
|
|---|---|---|
|
logs.dir
|
指定将生成日志文件的位置。默认值为当前工作目录。
|
|
|
logs.maxFileSize
|
5MB
|
指定触发新日志文件滚动更新的最大日志文件大小。
|
|
logs.maxIndex
|
9
|
指定固定大小滚动更新窗口的最大索引。初始索引从 1 开始。
|
|
logs.timestampPattern
|
yyyy-dd-MM HH:mm:ss.SSS
|
指定要用于每个日志事件的时间戳模式。
|
|
logs.uniqueId
|
<processId>
|
指定附加到日志文件名称的值。这用于生成唯一的文件名称。默认值通过 Java 回调获得，以返回 JVM 的进程 ID。
|