安装程序升级
如果使用 ThingWorx Foundation 安装程序安装 ThingWorx Foundation 8.5.0 或更高版本，那么也可使用此安装程序来升级 ThingWorx Foundation，包括维护版本升级。有关每个 ThingWorx 版本所支持的升级一览表的链接，请参阅升级 ThingWorx。
 |
从 ThingWorx 9.4 开始，客户无法直接从 ThingWorx 8.5 或 ThingWorx 9.0 升级到 ThingWorx 9.4.0。客户如需从 ThingWorx 8.5 或 ThingWorx 9.0 升级到 9.4.0 及更高版本，需要先升级到中间版本，然后再升级到 ThingWorx 9.4.0 及更高版本。ThingWorx 建议使用最新 ThingWorx 9.3.x 作为中间升级路径。
|
|
|
如果要升级至 ThingWorx 9.2 和 PostgreSQL 13，则升级 PostgreSQL 将是整个升级过程的最后一步。
|
|
|
执行升级的用户与执行应用程序原始安装的用户必须为同一用户。
|
A.) 先决条件
• Java 要求 (安装程序不会在安装过程中打包或安装 Java)：
◦ 最初安装 ThingWorx 的用户应运行升级。在初始安装期间，安装程序会生成 ThingWorxFoundation.xml 文件，其中包括有关安装以及升级所需内容的信息。此文件位于运行安装的用户配置文件下。例如，在 C:\Users\Administrator\.ptc_cci 中。
◦ ThingWorx Foundation 9.2 需要用到 Java 11，此外还必须安装 Java 8。在运行安装程序前，请验证是否已安装受支持的 Java 8 和 11 版本。将 Java 11 添加至 PATH 环境变量。
◦ 如果要在 Java 8 上运行 ThingWorx 9.0 或更低版本，并升级至 ThingWorx 9.2，则必须预先安装 Java 11，但不要将 ThingWorx 切换为指向新的 jvm。JAVA_HOME 仍应设置为 Java 8 文件夹。两个 Java 目录均应位于 PATH 环境变量中，但 java8/bin 应在 PATH 变量中列于 java11/bin 前。在升级至 9.2 期间，安装程序还会将正在使用的 Java 版本切换至 Java 11，因为 ThingWorx 9.2 不支持 Java 8。
◦ 如果要运行 ThingWorx 9.1，由于其支持 Java 8 和 Java 11，因此可遵循上述建议 (同时安装两者，并将两者包括在路径中)，也可在开始升级前将 ThingWorx 9.1 实例迁移至 Java 11。
• 备份您的数据库。在升级过程中，安装程序不会运行数据库备份。
• 必须使用以下其中一个具有这些数据库组合的操作系统：
◦ 带有 PostgreSQL 的 Windows
◦ 带有 Microsoft SQL Server 的 Windows
◦ Red Hat Enterprise Linux 与 PostgreSQL
◦ Red Hat Enterprise Linux 与 Microsoft SQL Server
有关版本信息，请参阅系统要求。
• 如果数据表中缺少任何自定义索引字段值，升级将失败。在开始升级过程之前，请验证是否所有自定义索引字段均具有值。
B.) 运行 ThingWorx 升级就绪实用程序
如果已安装了 ThingWorx Foundation 8.5.3 或更低版本，则应首先运行 ThingWorx 升级就绪实用程序，该程序位于 > > > > > 。
ThingWorx 升级就绪实用程序可创建支持自动升级 ThingWorx Foundation 和 ThingWorx Flow (若安装) 所需的 XML 文件。该实用程序会提示您查找系统上的 ThingWorx Foundation 和 ThingWorx Flow (若安装)，然后配置所选安装。它会在用户配置文件中创建 ThingWorxFoundation.xml 和 ThingWorxFlow 文件 (如果已安装 ThingWorx Flow)。文件将保存在用户配置文件中的 .ptc_ccif 文件夹内 (例如在 Windows 中为：C:\Users\Administrator\.ptc_ccif；在 Linux 中为：~/.ptc_ccif/)。
如果已使用安装程序安装了 ThingWorx 8.5.4 或更高版本，则必要的 XML 文件已在安装期间创建完毕；因此，无需运行 ThingWorx 升级就绪实用程序。
故障排除
• 如果已使用安装程序安装了 ThingWorx Foundation 8.5.3 或更早版本，然后手动升级到了较高的 8.5.x 版本，且现在正准备通过运行 ThingWorx 升级就绪实用程序升级至 9.x，请执行以下操作：
◦ 运行 ThingWorx 升级就绪实用程序。
◦ 验证用户配置文件中 ThingWorxFoundation.xml 文件内的 <applicationVersion> 属性值是否为当前版本。
• 如果在运行 ThingWorx 升级就绪实用程序时遇到问题且需要手动创建或编辑 ThingWorxFoundation 文件，可以使用以下示例并根据您的升级路径对其进行更新：
<?xml version="1.0" encoding='utf-8'?>
<installationInfo>
<projectFlavor>PostgreSQL</projectFlavor>
<applicationName>ThingWorxFoundation</applicationName>
<applicationVersion>9.0.1</applicationVersion>
<applicationInstallDir>C:\Program Files
(x86)\ThingWorxFoundation</applicationInstallDir>
</installationInfo>
<installationInfo>
<projectFlavor>PostgreSQL</projectFlavor>
<applicationName>ThingWorxFoundation</applicationName>
<applicationVersion>9.0.1</applicationVersion>
<applicationInstallDir>C:\Program Files
(x86)\ThingWorxFoundation</applicationInstallDir>
</installationInfo>
C.) 升级
1. 确保满足上述各部分中所述的先决条件。
2. 请前往 support.ptc.com 的“下载软件”>“订购或下载软件更新”> ThingWorx Foundation >“版本 x.x”> ThingWorx PostgreSQL 或 ThingWorx Mssql 下获取和下载最新 ThingWorx Foundation 本地安装的安装程序文件。
3. 安装程序会列出现有的安装信息，其中包括：
◦ 安装目录
◦ 端口
◦ SSL 配置设置
◦ SSO 配置设置
4. 系统向您显示 PTC 许可协议。在继续升级之前，您必须接受协议条款。
5. 您必须输入 ThingWorx Foundation 管理员密码，或者，如果配置了 SSO，则输入您的应用程序密钥。
6. 您可以查看并确认您的安装配置信息。
7. 安装程序将完成升级。
现在，您可以将扩展和应用程序升级到兼容的版本。
D.) 迁移时区数据
| | 更新到 ThingWorx 9.4.0 及更高版本时，不需要迁移时区数据。不支持从 ThingWorx 8.5 或 ThingWorx 9.0 直接升级到 ThingWorx 9.4。在迁移到中间版本的过程中，将执行迁移时区操作。 |
如果存在下列情况之一，则必须执行本部分的重要数据迁移步骤：
• 已安装 ThingWorx 8.5.x 并使用安装程序升级到了 ThingWorx 9.0.x 或 9.1。
• 已安装 ThingWorx 9.0.x 并使用安装程序升级到了 ThingWorx 9.0.3.x 或更高版本。
要执行此数据迁移，请执行以下操作：
1. 成功升级后，请立即停止 ThingWorx 和 Apache Tomcat。
2. 基于您的操作系统，使用以下步骤手动设置时区参数 -Duser.timezone=UTC。
在 Windows 上配置时区设置
1. 停止 ThingWorx-Foundation 服务。
2. 以管理员身份运行 CMD。
3. 转至 ThingWorx Foundation 安装目录下的 Tomcat /bin 目录。
例如：cd C:\Program Files (x86)\ThingWorxFoundation\tomcat\apache-tomcat-9.0.37\bin。
4. 通过执行以下操作来编辑 ThingWorx-Foundation 服务配置以打开 GUI 应用程序：
tomcat9w.exe //ES//ThingWorx-Foundation
5. 转至 GUI 应用程序上的 java 选项卡。
a. 为“Java 选项”添加以下内容：-Duser.timezone=UTC。
b. 选取“应用”。
6. 选取“确定”以关闭 GUI。
7. 使用 tomcat9.exe 更新服务参数。
8. 以管理员身份运行 CMD 并执行以下操作：
tomcat9.exe //US//ThingWorx-Foundation
在 Linux 上配置时区设置
1. 使用 systemctl stop ThingWorx-Foundation.service 停止 ThingWorx-Foundation 服务。
2. 在 /etc/systemd/system/ThingWorx-Foundation.service.backup 中备份 ThingWorx-Foundation.service。
3. 通过更改 JVM 选项的 ThingWorx-Foundation.service 来编辑服务配置：
a. 为 CATALINA_OPTS 附加以下内容：-Duser.timezone=UTC
4. 执行以下命令：systemctl daemon-reload。
运行脚本
• 安装程序升级至 9.3.x 及更高版本
1. 获取所有数据库特定时区名称的列表。要执行此操作，可手动连接到数据库并运行此查询，以获取数据库当前支持的所有时区名称的列表：
SELECT name, utc_offset, is_dst FROM pg_timezone_names ORDER BY name
| | 保留此列表以供日后参考。 |
2. 确定所有现有 ThingWorx 数据当前与之关联的时区的名称 (您的“自”时区)：
▪ 获取您在上面的“设置 ThingWorx 服务器时区”部分中所记录的时区值。
▪ 此值是所有现有 ThingWorx 数据当前关联的时区。
▪ 该值特定于 JVM 或操作系统，并且可能不会与数据库特定列表 (在步骤 1 中查询) 内的任何时区名称精确匹配。
▪ 手动检查从数据库查询的时区列表，以确定与“设置 ThingWorx 服务器时区”部分中的值最相符的时区名称。
▪ 找到最相符的值后，该时区名称将变为后续步骤中所需的 "自" 时区 (相对于 "至" 时区)。
3. 确定所有现有 ThingWorx 数据应迁移至的时区 (您的“至”时区)：
▪ 在上面的“设置 ThingWorx 服务器时区”部分中，您已将 Tomcat 的 -Duser.timezone 配置设置设为 UTC。确定所有现有 ThingWorx 数据应迁移至的时区。但是，该值特定于 JVM，并且可能不会与已查询的数据库列表 (在步骤 1 中查询) 内的任何时区名称精确匹配。
▪ 手动检查从数据库查询的时区列表，以确定与 UTC 值最相符的时区名称。
▪ 找到最相符的值后，该时区名称将变为后续步骤中所需的 "至" 时区 (相对于 "自" 时区)。
| | "自" 和 "至" 时区名称可以相同。 |
4. 运行 BigInt/Timezone 架构脚本以准备迁移所有数据表、流和值流数据：
update_bigint_timezone_schema_postgres.ps1
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: update_bigint_timezone_schema_postgres.ps1 -h <host> -p <port> -d <database> -s <schema> -u <user> [--managed_instance <name>] --from_timezone <timezone> --to_timezone <timezone> [-y] Supported Options: -h host The host name of the machine on which the database is running. -p port The port on which the database server is listening for connections. -d database The name of the database to connect to. -s schema The name of the database schema to update. -u user Connect to the database as this user. --managed_instance name To be specified only when the database is deployed within a Managed Instance (e.g. Azure, etc). --system_version_override version Forces the upgrade to assume the database schema is currently of this version (i.e. "n.n.n"), rather than of the actual, persisted version. --from_timezone timezone The name of the timezone for all existing data. --to_timezone timezone The name of the timezone to which all existing data will be updated. -y Suppress all non-required prompts, such as "Are you sure?" |
| | 尽管此脚本会直接迁移某些数据，但不会迁移任何数据表、流或值流数据。相反，此脚本会创建所有数据表、流和值流数据的备份，以便之后进行迁移。出于性能方面的原因，此脚本实际上不会在现有数据表、流和值流表中创建数据的备份副本，而是会将现有表从 "foo" 重命名为 "foo_backup"。由此可避免复制大量数据的过程，因为这一过程可能会比较耗时。对这些现有的表 (进而成为其自己的备份表) 进行重命名后，即会以原始名称创建新表。这些新表为空，并且与原始表具有相同的作用 (因为它们的名称与原始表相同)。 |
5. 完成上一步骤后，如有必要，可重新启动平台。但是，请注意，数据表、流和值流数据尚未迁移。因此，在进行数据迁移之前，针对该数据的查询所接收到的结果集可能会减少。
6. 运行 BigInt/Timezone 数据架构脚本以迁移数据表、流和值流数据：
update_bigint_timezone_data_postgres.ps1
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: update_bigint_timezone_data_postgres.ps1 -h <host> -p <port> -d <database> -s <schema> -u <user> [--managed_instance <name>] --from_timezone <timezone> --to_timezone <timezone> --chunk_size <chunk_size> ( --update_data_table | --update_stream | --update_value_stream ) [-y] Supported Options: -h host The host name of the machine on which the database is running. -p port The port on which the database server is listening for connections. -d database The name of the database to connect to. -s schema The name of the database schema to update. -u user Connect to the database as this user. --managed_instance name To be specified only when the database is deployed within a Managed Instance (e.g. Azure, etc). --system_version_override version Forces the upgrade to assume the database schema is currently of this version (i.e. "n.n.n"), rather than of the actual, persisted version. --from_timezone timezone The name of the timezone for all existing data. --to_timezone timezone The name of the timezone to which all existing data will be updated. --chunk_size chunk_size The number of records to update per transaction. Must be greater than 0. --update_data_table Update "data_table" information. Cannot be specified with any other "--update_..." flag. --update_stream Update "stream" information. Cannot be specified with any other "--update_..." flag. --update_value_stream Update "data_table" information. Cannot be specified with any other "--update_..." flag. -y Suppress all non-required prompts, such as "Are you sure?" |
| | • 根据上述使用声明，一次只能指定一个 "--update…" 选项。因此，要迁移所有数据表、流和值流数据，此脚本必须运行三次 (每个数据集一次)。由于这些数据集彼此独立，因此，一个数据集的迁移可以与另一个数据集的迁移并行完成。例如，如果打开三个单独的命令窗口，则可以在第一个窗口中运行数据表迁移、在第二个窗口中运行流迁移、在第三个窗口中运行值流迁移，三者同时进行。但是，请勿尝试使用多个进程来同时迁移某个数据集。例如，请勿尝试使用两个并发进程来迁移值流数据。此操作方式未经定义，将导致数据损坏。 • 对于典型环境，建议将 chunk_size 设为 10000。 • 由于可以在完成所有数据迁移之前重新启动平台，因此数据迁移会按照从最新数据到最旧数据的顺序进行。这是预期行为，允许该数据的任何查询首先接收最相关的数据。 • 数据集大小对迁移所有数据所需的时间影响非常大。例如，如果要迁移的行数多达数十亿，则该数据的迁移可能需要几天时间才能完成。 |
7. 完成所有 BigInt/Timezone 数据的迁移并手动校验和验证所有经迁移的 BigInt/Timezone 数据后，运行 BigInt/Timezone 清理脚本以清理由 BigInt/Timezone 架构脚本创建的任何临时数据库构件：
cleanup_bigint_timezone_data_update_postgres.ps1
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: cleanup_bigint_timezone_data_update_postgres.ps1 -h <host> -p <port> -d <database> -s <schema> -u <user> [--managed_instance <name>] [-y] Supported Options: -h host The host name of the machine on which the database is running. -p port The port on which the database server is listening for connections. -d database The name of the database to connect to. -s schema The name of the database schema to update. -u user Connect to the database as this user. --managed_instance name To be specified only when the database is deployed within a Managed Instance (e.g. Azure, etc). -y Suppress all non-required prompts, such as "Are you sure?" |
| | 尽管此脚本会对升级过程中创建的临时数据库对象执行一些清理操作，但此脚本并不会删除在上述步骤中创建的任何备份表，也不会修改这些备份表中的任何数据。此行为是有意而为之的，可确保数据不会遭到意外删除。如果要删除这些备份表，则必须手动将其删除。 |
8. 在所有数据的迁移均完成、校验和验证后，运行主清理脚本。
所有 BigInt/Timezone 数据的迁移均完成且进行验证和验证后，运行此脚本以清理由主 ThingWorx 更新脚本创建的任何临时数据库构件：
cleanup_update_postgres.ps1
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: cleanup_update_postgres.ps1 -h <host> -p <port> -d <database> -s <schema> -u <user> [--managed_instance <name>] [-y] Supported Options: -h host The host name of the machine on which the database is running. -p port The port on which the database server is listening for connections. -d database The name of the database to connect to. -s schema The name of the database schema to update. -u user Connect to the database as this user. --managed_instance name To be specified only when the database is deployed within a Managed Instance (e.g. Azure, etc). -y Suppress all non-required prompts, such as "Are you sure?" |
• 安装程序升级至 9.0.x、9.1.x、9.2.x
设置时区后，转至 <InstallLocation>/schema/update 并按以下顺序运行适用于您操作系统和数据库组合的脚本 (例如，对于 Windows，为如下所列的 .bat 文件；对于 RHEL 安装，为 .sh 文件)：
a. thingworxPostgresDBSetupBigIntTimezoneDataUpdate.bat
b. thingworxPostgresModelTablesDataUpdate.bat
c. thingworxPostgresDataTableSchemaUpdate.bat
d. thingworxPostgresValueStreamSchemaUpdate.bat
e. thingworxPostgresStreamSchemaUpdate.bat
f. thingworxPostgresDataTableDataUpdate.bat
g. thingworxPostgresStreamDataUpdate.bat
h. thingworxPostgresValueStreamDataUpdate.bat
脚本需用到参数，例如：
-h <server>
-p <port>
-d <thingworx database name>
-l <thingworx database username> for MSSQL
-u <thingworx database username> for PostgreSQL
-i <SQL server instance name> (optional, for MSSQL installations only)
-p <port>
-d <thingworx database name>
-l <thingworx database username> for MSSQL
-u <thingworx database username> for PostgreSQL
-i <SQL server instance name> (optional, for MSSQL installations only)
有关这些参数及其预期输入的详细信息，请参阅手动就地升级：Windows 或手动就地升级： Linux。
系统将提示您输入数据库用户密码，该密码通过 -u 或 -l 参数传递。
| | StreamDataUpdate 和 ValueStreamDataUpdate 脚本 (例如 thingworxPostgresStreamDataUpdate.bat 和 thingworxPostgresValueStreamDataUpdate.bat) 被设计为异步运行。上述脚本经设计后可从中断位置继续并批量操作，以便在 ThingWorx 实例运行时迁移数据。根据数据量的不同，运行这些脚本可能会花费很长时间。 |
DataTableDataUpdate 脚本 (例如 thingworxPostgresDataTableDataUpdate.bat) 将在执行过程中显示以下消息：Essential System Data Has Been Migrated. It Is Now Safe To Restart Tomcat Server。
DataTableDataUpdate 脚本发布此消息后，可重新启动 ThingWorx 实例并继续余下的数据迁移脚本。余下的脚本可在 ThingWorx 运行时执行，并会完成流数据和值流数据的迁移。
迁移完成后，应运行清理脚本 (例如 "thingworxPostgresDBCleanupBigIntTimezoneDataUpdate.sh") 以清理 migration_log 表格和迁移功能。
E.) 运行 9.2 + 的清理脚本
如果要升级至 ThingWorx 9.2 或更高版本，则必须运行清理脚本以移除在升级过程中创建的临时表格。
运行位于 <installDir>/schema/update 中的 thingworx<database_name>DBCleanupPermissionTempTableUpdate.bat(Windows) 或 thingworx<database_name>DBCleanupPermissionTempTableUpdate.sh (Linux) 清理脚本。
脚本需用到参数，例如：
-h <server>
-p <port>
-d <thingworx database name>
-l <thingworx database username> for MSSQL
-u <thingworx database username> for PostgreSQL
-i <SQL server instance name> (optional, for MSSQL installations only)
-p <port>
-d <thingworx database name>
-l <thingworx database username> for MSSQL
-u <thingworx database username> for PostgreSQL
-i <SQL server instance name> (optional, for MSSQL installations only)
系统将提示您输入数据库用户密码，该密码通过 -u 或 -l 参数传递。
F.) 9.3+ 的其他可选清理
如果从 ThingWorx 9.2.x 或更早版本进行升级，并且已启用使用访问令牌加密的单点登录，则可能需要执行一个可选清理步骤。在 9.3 以前的版本中，在将访问令牌保存到数据库之前会使用 KeyCzar 工具对其进行加密。KeyCzar 需要在 ThingWorx 安装目录的 ThingworxPlatform\ssoSecurityConfig 文件夹中创建 symmetric 文件夹。
KeyCzar 工具现已弃用。在 ThingWorx 9.3 及更高版本中，已改为使用 Tink 对访问令牌进行加密。Tink 不需要 symmetric 文件夹或 ThingWorx sso-settings.json 文件中的 keyczarKeyFolderPath 参数。您可以按原样保留这些文件和设置，ThingWorx 9.3 及更高版本会忽略它们。但是，如果决定将其移除，则必须等待升级过程完成。
G.) (可选) 升级至 PostgreSQL 13
对于 ThingWorx 9.2.0 和更高版本，可选择从较低版本的 PostgreSQL 升级至 PostgreSQL 13。
1. 备份数据库。这是您所执行的第二次备份，因为该操作将在升级 ThingWorx 后备份数据库。
2. 下载 PostgreSQL 13。
3. 通过将 PostgreSQL 文档用作参考来升级至 PostgreSQL 13。
H.) 故障排除
• 如果升级失败并显示以下错误，请执行以下步骤。如果任何自定义索引值大于或等于 64 个字符，则会出现此错误。
Unable to Invoke Service Reindex on Data Table : com.microsoft.sqlserver.jdbc.SQLServerException: String or binary data would be truncated in table 'thingworx.thingworx.data_table_indexes', column 'mskey'. Truncated value: '<with_actual_field_Value_from_mskey_field>'.
a. 执行 thingworxMssqlSchemaUpdate<priorVersion>-to-<currentVersion>.bat/.sh 或 SQL 脚本：
sqlcmd -S server\\serverinstance,port -U db_user -P password -d databaseName -i <schemaUpdateFile.sql>
运行此脚本将增加 mskey 列的长度并更新索引。
b. 启动 Tomcat。
• 如果已安装 ThingWorx 8.5.3 或更早版本，但安装程序未找到它，请运行 ThingWorx 升级就绪实用程序。
• 如果安装程序无法完成升级，请执行以下操作：
1. 检查安装目录中 /installer/logs 下的日志文件。
2. 还原到升级前的安装：
a. 将数据库恢复到其备份中。
b. 启动 ThingWorx-Foundation 服务。
• 如果安装程序运行成功，则表明 ThingWorx Foundation 升级完成。但是，ThingWorx Foundation 安装位置的名称可能不是最新的。您可以在 Composer > 下验证 ThingWorx 版本。
• 如果您的操作系统是 RHEL 8.2 且正在从 ThingWorx 8.5.7 进行升级，则应首先手动卸载 Chef 基础客户端，以确保安装程序能够进行设置且使用受支持的 Chef 版本。要卸载 Chef，请执行以下操作：
a. 要查找 Chef 基础客户端安装程序的包名称，请执行以下命令：$ rpm -qa chef。
输出应如下所示：chef-14.10.9-1.el7.x86_64.rpm
b. 从上面找到的输出中复制包名称。
c. 使用复制的包名称执行以下命令：$ sudo yum remove <copied_package_name>。
例如：$ sudo yum remove chef-14.10.9-1.el7.x86_64.rpm。
d. 转至 /opt 目录，通过删除安装目录 $ sudo rm -rf /opt/chef 来移除所有 Chef 基础客户端文件。