整合連接器的整合執行時間服務的初始設定
ThingWorx 安裝完成後，請遵循下列步驟來下載及配置 ThingWorx 執行時間服務。如果您是在 Docker 環境中，您可以使用安裝程式來設定整合連接器的基本組態。安裝程式包括記錄檔案，您可在其中修改某些組態，如接下來的內容所述。
下載整合執行時間
您可在
support.ptc.com 的「下載軟體」>「訂購或下載軟體更新」> ThingWorx Foundation >「<版本> 發行版本」> ThingWorx Integration Runtime >「最新日期代碼」> ThingWorx-Integration-Runtime-<版本> 下，取得 Integration Runtime 服務。
配置整合執行時間
 |
不會從 IntegrationRuntime 物範本建立物件。
|
1. 在 ThingWorx 中建立 Integration Runtime 的應用程式金鑰，以便與 ThingWorx Platform 進行通訊。
2. 使用下列其中一個選項，將整合服務啟動為 Java 流程：
◦ 指定連線參數的外部組態檔案。
java -DconfigFile=<IntegrationRuntime 設定的路徑>-jar <IntegrationRuntime-x.x.x 的路徑>.jar，其中 x.x.x 會取代為您使用的版本。
3. (選用) 建立自訂 logback 設定檔案，並以下列指令在指令行上指定連至該檔案的路徑：-Dlogs.includedLogback=<path to logback include>
4. 如果您在 integrationRuntime-settings.json 組態檔案中
加密項目，或
加密整個組態檔案，您必須在指令行使用下列指令指定 security-common 加密組態的路徑：
|
|
在下述範例中，如果您加密整個組態檔案，必須設定為 -Dencrypted.config.file=true，而且它必須指向加密的 Integration Runtime 組態檔案。如果您只加密檔案中的項目，請省略設定或將其設定為 false。
|
java -Dsecret.management.config.file=<Path to encryption.conf> -Dencrypted.config.file=true -DconfigFile=<path to encrypted 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>)。
|
設定
|
預設值
|
描述
|
|---|---|---|
|
traceRoutes
|
false
|
指定呼叫路由中的各個處理器時，路由執行是否應記錄訊息。
|
|
Thingworx
|
以 JSON 格式指定用於連線至 ThingWorx Platform 的設定。
|
|
|
SSL
|
以 JSON 格式指定「安全通訊端層 (SSL)」設定。
|
|
設定
|
預設值
|
描述
|
||
|---|---|---|---|---|
|
appKey
|
從 ThingWorx Platform 指定已配置的應用程式金鑰，以供此 Integration Runtime 使用。可用 Java 系統內容取代此設定。
|
|||
|
basePath
|
/Thingworx
|
在 URI 中指定連往 ThingWorx Platform 的基礎路徑。可用 Java 系統內容取代此設定。
|
||
|
主機
|
localhost
|
在 URI 中指定連往 ThingWorx Platform 的主機。可用 Java 系統內容取代此設定。
|
||
|
埠
|
443
|
在 URI 中指定連往 ThingWorx Platform 的埠。可用 Java 系統內容取代此設定。
|
||
|
sslEnable
|
true
|
指定是否應使用 SSL 透過 WebSocket 連接至 ThingWorx Platform。若為 true，則 "wss" 通訊協定會用於 URI。否則，會使用 "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 的組態檔案。在此範例中，該組態檔案為 integrationRuntime-settings.json，其使用 encryptFile 指令加密，如下所示：
encryptFile C:\Integ_runtime\integrationRuntime-settings.json C:\Integ_runtime\integrationRuntime-settings.json.encrypted
integrationRuntime-settings.json.encrypted is your encrypted configuration file.
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. 在提示中鍵入 exit，以關閉 CLI。
加密組態檔案中的項目
在 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 與密碼檔案執行下列步驟：
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. 視您的 Integration Runtime 是否與 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 組態設定。keystore 設定並非連線至 ThingWorx Platform 所必需；它們以雙向 SSL 協商從 Integration Runtime 提供用戶端憑證。
|
ThingWorx 組態
|
整合執行時間設定
|
|---|---|
|
並未針對 SSL 配置 ThingWorx
|
使用 Java 系統內容指定 thingworxUri，並使用 ws 通訊協定或在 SSL 設定中指定 sslEnable=false。
|
|
使用自我簽署憑證針對 SSL 配置 ThingWorx
|
在 SSL 設定中指定 sslEnable=true 和 ignoreSSLErrors=true。
|
|
用自我簽署憑證針對 SSL 配置 ThingWorx，而且該憑證受信任。
用獲得憑證授權單位 (CA) 簽署的憑證針對 SSL 配置 ThingWorx，且並未為了提供整個「CA 憑證鏈」而配置該憑證。
|
從金鑰倉庫檔案匯出憑證，然後將之匯入信任倉庫檔案。
在 SSL 設定中指定 enable=true 和 Trustore。
信任倉庫密碼可能可加密。
或者，將憑證新增至 Integration Runtime JVM 預設信任倉庫 (通常位於此處：$JAVA_HOME/lib/security/cacerts)。在此情況下，不需在 SSL 設定中明確指定信任倉庫。
|
|
用獲得憑證授權單位 (CA) 簽署的憑證針對 SSL 配置 ThingWorx，且已為了提供整個「CA 憑證鏈」而配置該憑證。
|
在 SSL 設定中指定 enable=true。這是預設設定。
|
SSL 組態範例：非生產組態
如果針對 SSL 使用自我簽署憑證配置 ThingWorx，請使用下列 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 組態範例：生產組態
如果針對 SSL 使用自我簽署憑證配置 ThingWorx，請使用下列步驟來建立信任倉庫：
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>
記錄檔組態檔案設定
標準 logback.xml 組態檔案內含在 IntegrationRuntime.jar·當中。如需 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。
|