Начальная настройка сервиса Integration Runtime для соединителей интеграции
После установки ThingWorx выполните следующие шаги, чтобы загрузить и настроить сервис времени выполнения ThingWorx. Если вы находитесь в среде Docker, можно использовать установщик, чтобы установить базовую конфигурацию для соединителей интеграции. Установщик включает файл регистрации, в котором можно изменить некоторую конфигурацию, как описано ниже.
Загрузка сервиса Integration Runtime
Сервис Integration Runtime доступен на сайте support.ptc.com в разделе Download Software (Загрузить ПО) > Order or Download Software Updates (Заказать или загрузить ПО) > ThingWorx Foundation > Release (Выпуск) <версия> > ThingWorx Integration Runtime > Most Recent Datecode (Самый последний код даты) > ThingWorx-Integration-Runtime-<версия>.
Конфигурирование сервиса Integration Runtime
* 
Не создавайте вещь из шаблона вещи IntegrationRuntime.
1. Создайте ключ приложения в ThingWorx для сервиса Integration Runtime, используемый для связи с платформой ThingWorx.
2. Запустите сервис интеграции как Java-процесс с помощью одной из следующих опций:
* 
Не включайте настройки -Dorg.apache.camel.jmx.createRmiConnector.
Внешний файл конфигурации, указывающий параметры соединения.
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 требуется в приведенных ниже примерах, если выполняется шифрование всего файла конфигурации, а опция должна указывать на зашифрованный файл конфигурации IntegrationRuntime. Если шифруются только записи в файле, опустите эту настройку или задайте для нее значение ложь.
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
5. При выполнении кластеризации ThingWorx высокой доступности (HA) все соединения WebSocket должны маршрутизироваться через сервер соединений ThingWorx.
Соединитель интеграции использует соединения WebSocket для взаимодействия с ThingWorx. Типичная структура высокой доступности использует несколько серверов соединений с балансировщиком нагрузки перед серверами соединений. В среде высокой доступности среда времени выполнения интеграции должна выполнять маршрутизацию через сконфигурированный балансировщик нагрузки на сервер соединений.
Пример файла конфигурации (integrationRuntime-settings.json)
{
"traceRoutes": "false",
"OutboundTimeout": "1",
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"basePath": "/Thingworx",
"sslEnable": "true",
"ignoreSSLErrors": "false"
},
"Performance": {
"minPoolSize":"4",
"maxPoolSize":"10",
"maxThreadLife":"10000",
"maxQueueSize":"1000"
},
"Proxy": {
"host":"localhost",
"port":"8888",
"user":"<proxy username>",
"pass":"<proxy password>"
},
"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>).
Настройки сервиса Integration Runtime
Настройка
По умолчанию
Описание
traceRoutes
false
Указывает, следует ли при выполнении маршрутизации записывать сообщения в журнал при вызове каждого процессора в маршруте.
Thingworx
Указывает в формате JSON настройки, необходимые для соединения с ThingWorx Platform (односерверный режим) или балансировщиком нагрузки сервера соединений (кластерный режим).
SSL
Указывает настройки протокола защищенных сокетов (SSL) в формате JSON.
Настройки ThingWorx
Настройка
По умолчанию
Описание
appKey
Указывает ключ приложения из ThingWorx Platform, которое было настроено для использования сервиса Integration Runtime. Эта настройка может быть переопределена системным свойством Java.
* 
Описание шагов шифрования см. в разделе ниже.
basePath
/Thingworx
Указывает базовый путь в URI для ThingWorx Platform (односерверный режим) или балансировщика нагрузки сервера соединений (кластерный режим). Эта настройка может быть переопределена системным свойством Java.
OutboundTimeout
Тайм-аут соединения в простое WSCommnucationSubsystem
Указывает тайм-аут Integration Runtime для любого запроса стороннего производителя в состоянии ожидания. Если значение не задано, integration Runtime будет принимать значение тайм-аута соединения для WSCommunicationSubsytem.
При запуске Integration Runtime выполняется сравнение значения, указанного в файле integrationRuntime-settings.json, и тайм-аута простоя соединения WSCommunictaionSubsystem. Минимальное из этих двух значений будет передано в Integration Runtime.
Значение по умолчанию равно 30 и может быть задано по мере необходимости.
host
localhost
Указывает хост-компьютер в URI для ThingWorx Platform (односерверный режим) или балансировщика нагрузки сервера соединений (кластерный режим). Эта настройка может быть переопределена системным свойством Java.
port
443
Указывает порт в URI для ThingWorx Platform (односерверный режим) или балансировщика нагрузки сервера соединений (кластерный режим). Эта настройка может быть переопределена системным свойством Java.
sslEnable
true
Указывает, следует ли использовать SSL для соединения с ThingWorx Platform через веб-сокет. Если задано true, для URI используется протокол wss. В противном случае используется протокол ws.
ignoreSSLErrors
false
Указывает, должны ли игнорироваться ошибки SSL. В производственной среде для этой настройки не следует задавать значение истина
Настройки производительности
Настройка
По умолчанию
Описание
minPoolSize
4
Минимальное число потоков, выделенных пулу обработки событий.
maxPoolSize
10
Максимальное число потоков, выделенных пулу обработки событий.
maxThreadLife
10000
Максимальное время ожидания отклика для потока.
maxQueueSize
1000
Максимум записей очереди перед добавлением нового рабочего потока.
[Необязательно] Настройки прокси
Настройка
По умолчанию
Описание
host
Н/Д
Наименование хост-компьютера прокси.
port
Н/Д
Номер порта хост-компьютера прокси.
User
Н/Д
Имя пользователя хост-компьютера прокси.
Pass
Н/Д
Пароль хост-компьютера прокси.
Настройки SSL
Настройка
По умолчанию
Описание
verbose
false
Указывает, будет ли протокол квитирования Java выводить подробные сообщения. Если задано true, системное свойство Java javax.net.debug получает значение ssl:handshake:verbose.
Keystore
Указывает настройки keystore SSL в формате JSON.
Truststore
Указывает настройки truststore SSL в формате JSON.
Настройки keystore
Настройка
Описание
path
Указывает путь к файлу keystore SSL. Использование этой настройки эквивалентно заданию системного свойства Java javax.net.ssl.keyStore.
password
Указывает пароль для файла keystore SSL. Использование этой настройки эквивалентно заданию системного свойства Java javax.net.ssl.keyStorePassword. Во избежание сохранения пароля в виде простого текста используйте значение encrypt.keystore.password. См. ниже раздел "Настройки шифрования паролей".
Настройки truststore
Настройка
Описание
path
Указывает путь к файлу truststore SSL. Использование этой настройки эквивалентно заданию системного свойства Java javax.net.ssl.trustStore.
password
Указывает пароль для файла truststore 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
Указывает число повторных попыток запроса для возможных отказов для неавторизованного запроса. Эта настройка применяется к HTTP-запросу с ответом 401 от сервера.
Настройки политики перенаправления
Настройка
По умолчанию
Описание
MaximumRedirects
3
Указывает число повторных попыток перенаправления.
EnableRedirect
true
Указывает, включается ли перенаправление для запросов, результатом которых является код состояния перенаправления.
Шифрование файла конфигурации
Чтобы обеспечить большую безопасность, можно зашифровать весь файл конфигурации и дополнительно отдельные значения в файле. Эта функция предоставляется в версии Integration Runtime 8.0.4+. В процессе установки Integration Runtime включается библиотека security-common. JAR для этой библиотеки включен в установку Integration Runtime. Он предоставляет серверный инструмент, который выполняет шифрование и расшифровку файла конфигурации.
Для взаимодействия с библиотекой безопасности, включающей шифрование файла конфигурации, доступен интерфейс командной строки (CLI). Полную информацию об интерфейсе командной строки см. в разделе Инструмент управления безопасностью. В этом разделе объясняется, где можно получить инструмент и как его использовать. Для удобства в следующих разделах представлены шаги, специфичные для Integration Runtime. CLI можно загрузить с сайта поддержки PTC.
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"
}
}
}
2. Создайте каталоги password-file-path и path, указанные в файле encryption.conf. В приведенном выше примере каталог password-file-path называется /ThingworxPlatform (Linux). На компьютере с Windows это будет C:\\ThingworxPlatform.
* 
Можно сохранить зашифрованный файл конфигурации в любом месте. Просто убедитесь, что файл конфигурации шифрования и переменные среды указывают правильный путь.
3. В предположении, что вы загрузили и извлекли дистрибутив CLI, можно зашифровать файл конфигурации. Откройте командную строку или оболочку и перейдите к каталогу 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
>
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 - ваш зашифрованный файл конфигурации.
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.
Миграция хранилища ключей и пароля хранилища ключей
Если для шифрования значений использовалось хранилище ключей и выполняется перенос, необходимо выполнить следующие шаги в файлах хранилища ключей и паролей:
1. Если среда Integration Runtime все еще использует в качестве файлов ключей twx/config и /ThingworxStorage/keyStore, выполните следующие действия:
Скопируйте /twx/config в /ThingworxPlatform/keystore-password
Скопируйте /ThingworxStorage/keyStore в /ThingworxStorage/keystore.jks
2. Начиная с ThingWorx 8.5, формат хранилища ключей изменился с .jks на .pfx. Необходимо перенести хранилище ключей. Дополнительные сведения см.в подразделе "Изменения в ThingWorx 8.5" раздела Инструмент управления безопасностью.
3. Этот шаг изменяется в зависимости от того, использует ли среда времени выполнения интеграции файлы хранилища ключей с хранилищем ключей сервера ThingWorx 8.5+:
Если файл хранилища ключей открыт для совместного использования с хранилищем ключей сервера ThingWorx Platform 8.5+, следуйте руководству Upgrading ThingWorx (Обновление ThingWorx) (на английском языке), чтобы сервер ThingWorx автоматически переносил файл хранилища ключей из старого формата .jks в новый формат .pfx.
Если файл хранилища ключей не используется совместно с платформой, выполните следующие действия.
a. Загрузите последнюю версию security-common-cli. Для получения помощи см. подраздел "Использование" раздела Инструмент управления безопасностью.
b. Запустите CLI, и хранилище ключей будет автоматически перенесено. Например:

./security-common-cli encryption.conf
c. В файле security-common-cli измените все ссылки на keystore.jks на keystore. Не включайте расширение файла .pfx.
d. Создайте резервную копию старого файла keystore.jks в безопасном расположении и удалите его из каталога ThingworxStorage.
Конфигурирование для SSL
По умолчанию сервис Integration Runtime соединяется с ThingWorx с помощью SSL. В следующей таблице описаны конфигурации ThingWorx Platform и соответствующие настройки конфигурации сервиса Integration Runtime, необходимые для успешного соединения. Настройки keystore не являются необходимыми для соединения с ThingWorx Platform; они предоставляют сертификат клиента от сервиса Integration Runtime в двухстороннем согласовании SSL.
Конфигурация ThingWorx
Настройки сервиса Integration Runtime
ThingWorx не конфигурируется для SSL
Задайте thingworxUri с помощью свойства системы Java и используйте протокол ws или задайте sslEnable=false в настройках SSL.
ThingWorx конфигурируется для SSL с помощью самоподписанного сертификата
Задайте sslEnable=true и ignoreSSLErrors=true в настройках SSL.
ThingWorx конфигурируется для SSL с самоподписанным сертификатом, и сертификат является доверенным.
ThingWorx конфигурируется для SSL с сертификатом, подписанным центром сертификации (CA), но не конфигурируется для предоставления всей цепочки сертификатов CA.
Экспортируйте сертификат из файла keystore и импортируйте его в файл truststore.
Задайте enable=true и Trustore в настройках SSL.
Пароль truststore может быть зашифрован.
Можно также добавить сертификат в JVM-файл Integration Runtime truststore по умолчанию (обычно размещается здесь: $JAVA_HOME//lib/security/cacerts). В этом случае нет необходимости явно определять Truststore в настройках SSL.
ThingWorx конфигурируется для SSL с сертификатом, подписанным Центром сертификации (CA), и конфигурируется для предоставления всей цепочки сертификатов CA.
Задайте enable=true в настройках SSL. Это настройка по умолчанию.
Пример конфигурации SSL: непроизводственная конфигурация
Если ThingWorx конфигурируется для SSL с помощью самоподписанного сертификата, используйте следующий файл: integrationRuntime-settings.json.
{
"Thingworx": {
"appKey": "1234abcd-xxxx-yyyy-zzzz-5678efgh",
"host": "localhost",
"port": "8443",
"sslEnable": "true",
"ignoreSSLErrors": "true"
}
}
Пример конфигурации SSL - производственная конфигурация
Если ThingWorx конфигурируется для SSL с помощью самоподписанного сертификата, используйте следующие шаги, чтобы создать truststore.
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. Создайте локальную копию сертификата truststore, который будет использоваться в Integration Runtime для доверия самоподписанному сертификату сервера.
Вместо добавления недостающего сертификата непосредственно в перечень JVM в truststore, мы сначала создадим его копию и добавим недостающий сертификат в копию.
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
3. Измените пароль truststore.
Паролем по умолчанию для JVM-файла cacerts является changeit. Аналогично изменению пароля любого другого keystore мы можем изменить пароль 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
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"
}
}
}
Пример файла журнала конфигурации (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>
Настройки файла журнала конфигурации
Стандартный файл конфигурации 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 для возврата ID процесса JVM.
Было ли это полезно?