Linux 手动升级
手动就地升级到 9.3.x 及更高版本：Linux
 |
从 ThingWorx 9.4.0 开始，客户无法直接从 ThingWorx 8.5 或 ThingWorx 9.0 升级到 ThingWorx 9.4.0。如果客户希望从 ThingWorx 8.5 或 ThingWorx 9.0 升级到 ThingWorx 9.4.0 及更高版本，则需要升级到中间版本，然后再升级到 ThingWorx 9.4.0 及更高版本。ThingWorx 建议使用最新 ThingWorx 9.3.x 作为中间升级路径。
|
要确定升级路径，请参阅升级表格。下列步骤仅适用于就地升级。要进行迁移升级，请参阅手动迁移至 ThingWorx 9.x：Linux。
|
|
目前，不支持 H2 的大整数/时区数据库迁移脚本。这些迁移脚本针对其他受支持的数据库进行了详细说明。如果存在现有 H2 数据库且需要进行时区修正，则必须迁移至受支持的数据库，例如 PostgreSQL 或 MS SQL。如果应用程序将在未进行时区修正的情况下运行，则可在 H2 上升级至 ThingWorx 的最新版本。请注意，您将跳过前面提到的设置 ThingWorx 服务器时区部分。
|
A.) 升级前
1. 如果您使用的是 RHEL 操作系统，请先验证是否已升级至支持的版本，然后再升级 ThingWorx。有关详细信息，请参阅系统要求。
| | 仅 RHEL 8.2 支持 ThingWorx 9.1。 |
2. 在开始升级之前，建议执行以下操作：
◦ 数据库转储
◦ 备份 ThingworxStorage 和 ThingworxPlatform 文件夹中的所有数据。
◦ 备份 Tomcat_home 文件夹。这包括 bin、conf、lib、temp、webapps 和 work 文件夹。
3. 如果除 ThingWorx 平台外，还使用 ThingWorx Apps：
a. 请验证 ThingWorx Apps 版本是否支持要升级到的 ThingWorx 版本。请参阅 ThingWorx Apps Upgrade Support Matrix (ThingWorx Apps 升级支持一览表)。
b. 进行平台升级之前，必须先执行一些步骤。在继续下一步骤之前，请参阅升级 ThingWorx Apps。
4. 如果还安装了 Navigate，请在 ThingWorx Navigate 兼容性一览表处验证兼容性。
5. 通过 PTC 软件下载网站下载最新版本的 ThingWorx。
| | 在当前用户具有写入权限的文件夹中下载并提取 ThingWorx 内容。需要具有写入权限，因为更新脚本会在此过程中创建一些文件。 |
6. 验证您是否正在运行所需版本的 Tomcat 和 Java。有关版本要求的信息，请参阅系统要求。
| | 如果必须升级 Java 版本，请在升级 Java 前先升级 ThingWorx。 |
7. 当您升级 MSSQL、Azure SQL 或 H2 时，如果数据表中缺少任何自定义索引字段值，升级将失败。在开始升级过程之前，请验证是否所有自定义索引字段均具有值。
| | 如果不能执行此操作，则升级将失败，您必须再次部署较旧版本 (如果进行了架构更新，则需要回滚/恢复数据库)，并添加缺失的索引值或从数据表中移除自定义索引，然后再执行升级。 |
8. 将以下内容添加到 Apache Tomcat Java 选项中：
-Dlog4j2.formatMsgNoLookups=true
B.) 导出流和值流数据 (仅适用于 InfluxDB)
| | 使用 InfluxDB v2 升级到 ThingWorx 9.3.9 及更高版本或 ThingWorx 9.4.0 及更高版本时，需要导出存储在 InfluxDB 中的数据并将其导入 ThingWorx 9.3.9 或 ThingWorx 9.4.0。但是，由于 ThingWorx 9.3.0 到 9.3.7 版本的已知问题，Influx 数据导出会中断。在 ThingWorx 9.3.0 到 ThingWorx 9.3.7 版本中，无法从 InfluxDB v2 导出数据。此问题已在 ThingWorx 9.3.8 中修复。因此，要更新到 ThingWorx 9.3.9 及更高版本，或更新到 ThingWorx 9.4.0 及更高版本，必须先升级到 ThingWorx 9.3.8。升级到 ThingWorx 9.3.8 后，可以升级到 ThingWorx 9.3.9 或 ThingWorx 9.4.0。可按照以下说明升级 InfluxDB。如果从 ThingWorx 9.3.7 或更早版本升级到 ThingWorx 9.3.8，则无需按照以下步骤操作。 如果使用 InfluxDB 1.x 从 ThingWorx 升级到 ThingWorx 9.3.9 或更高版本，或升级到 ThingWorx 9.4.0 及更高版本，请按照以下步骤操作。无需升级到 ThingWorx 9.3.8，因为 InfluxDB 1.x 导出工作正常。 如果使用 InfluxDB 1.7.x (ThingWorx 8.5.x、9.0.x) 将 ThingWorx 升级到 InfluxDB 1.8.x (ThingWorx 9.1.x 或 9.2.x)，请按照以下步骤操作。 |
1. 从 InfluxDB MS SQL/PostgreSQL 中导出数据
a. 以管理员身份登录到 ThingWorx。
b. 单击“导入/导出”>“导出”。
c. 使用下列选项：
▪ 对于“导出选项”，请选择“至文件”。
▪ 对于“导出类型”，请选择“数据集合”。
▪ 对于“集合”，请选择“流”。
▪ 单击“导出”。
d. 对于值流数据，请重复步骤 a-c。
e. 将从系统信息库创建的流数据和值流数据的导出文件夹移动到安全位置作为备份。
C.) 停止并删除 ThingWorx Web 应用程序
1. 停止 Tomcat。
2. 强烈建议您先备份以下两个文件夹，然后再继续操作：
◦ Apache Software Foundation/Tomcat x.x/webapps/Thingworx
◦ /ThingworxStorage
| | 要保留现有安装的 SSO 配置，请在升级完成后，将 SSOSecurityContextFilter 参数添加到重新创建的 web.xml 文件。 |
3. 如果当前 Tomcat 版本较旧，且不受目标 ThingWorx 版本支持，则需要更新为受支持的 Tomcat 版本。
4. 要保留现有安装的 SSO 配置，请备份 <Tomcat 安装目录>\webapps\Thingworx\WEB-INF 文件夹中的 web.xml。
5. 备份 /ThingworxStorage/esapi 目录中的 validation.properties 文件，然后将其删除。
| | validation.properties 文件将在启动 ThingWorx 时创建。如果要保留所做的任何更改，请将此文件保存在 ThingworxStorage 目录之外的位置，然后继续移除 esapi 目录。启动时，ThingWorx 将重新创建该文件，您可以将自定义正则表达式重新添加到自动生成的 validation.properties 文件中。 有关其他信息，请参阅本主题。 |
6. 转至 /Apache Software Foundation/Tomcat x.x/webapps 下的 Tomcat 安装，然后删除 Thingworx.war 文件和 Thingworx 文件夹。
D.) 设置 ThingWorx 服务器时区
如果要在 H2 上进行升级，请跳过此部分。
1. 对于所有其他数据库，请检查有关时区配置设置的 Tomcat Java 选项。如果将此设置配置为 UTC (-Duser.timezone=UTC)，请跳过此处的其余步骤，并转至数据库的“更新架构和迁移数据”部分。
2. 如果此设置未配置为 UTC，请确定当前时区值以供日后使用：
◦ 如果已将此设置配置为 UTC 以外的时区，请记下该时区值以供日后使用。
◦ 如果未在 Tomcat 中配置此设置，请确定安装 Tomcat 所在操作系统的时区值。
3. 记下上述某个时区值及其源于的位置 (Tomcat 或操作系统) 后，即可将该信息放在一边，但保持其可访问，因为后续步骤中会用到。
4. 将此配置设置为 UTC:
-Duser.timezone=UTC
E.) 更新架构并迁移数据 (仅适用于 PostgreSQL)
| | 以下所参考的全部脚本均位于 ThingWorx 软件下载的 update 文件夹中。 |
| | 以下所参考的全部脚本都需要数据库访问权限。如果定义了 PGPASSWORD 环境变量，则脚本将使用其值作为数据库密码。否则，脚本将提示您输入数据库密码。有关详细信息，请参阅 Postgres 官方文档。 |
1. 运行主更新脚本以执行 ThingWorx 架构迁移：
update_postgres.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： update_postgres.sh -h <host> -p <port> -d <database> -s <schema> -u <user> [--managed_instance <name>] ( --update_all | [--update_data] [--update_model] [--update_property] [--update_system] ) [-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. --update_all Update all information (i.e. Data, Model, Property, etc). Same as specifying all other "--update_..." flags. --update_data Update only Data information. Can be specified with any other "--update_..." flags, except "--update_all". --update_model Update only Model information. Can be specified with any other "--update_..." flags, except "--update_all". --update_property Update only Property information. Can be specified with any other "--update_..." flags, except "--update_all". --update_system Update only System information. Can be specified with any other "--update_..." flags, except "--update_all". -y Suppress all non-required prompts, such as "Are you sure?" |
运行 ThingWorx 服务器时区脚本
| | 仅当从 ThingWorx 8.5 或 ThingWorx 9.0.0、9.0.1 或 9.0.2 升级到新的 ThingWorx 版本时，才需要运行 ThingWorx 时区脚本。ThingWorx 9.4.0 及更高版本不支持从 ThingWorx 8.5 或 ThingWorx 9.0.0、9.0.1 或 9.0.2 直接升级。相反，客户必须升级到中间 ThingWorx 版本，如 ThingWorx 9.3。从 ThingWorx 8.5 或 ThingWorx 9.0.0、9.0.1 或 9.0.2 升级到 ThingWorx 9.3.x 时，请运行以下脚本。ThingWorx 建议使用最新 ThingWorx 9.3.x 版本作为中间版本。 |
仅以下情况需要执行此部分的步骤：未在“设置 ThingWorx 服务器时区”部分的步骤 1 中设置 -Duser.timezone=UTC 时；或者，从 ThingWorx 8.5.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.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: update_bigint_timezone_schema_postgres.sh -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.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: update_bigint_timezone_data_postgres.sh -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.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: cleanup_bigint_timezone_data_update_postgres.sh -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.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: cleanup_update_postgres.sh -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?" |
F.) 更新架构并迁移数据 (仅适用于 MSSQL)
| | 以下所参考的全部脚本均位于 ThingWorx 软件下载的 update 文件夹中。 |
| | 以下所参考的全部脚本都需要数据库访问权限。如果定义了 SQLCMDPASSWORD 环境变量，则脚本将使用其值作为数据库密码。否则，脚本将提示您输入数据库密码。有关详细信息，请参阅 MSSQL 官方文档。 |
1. 运行主更新脚本以执行 ThingWorx 架构迁移：
update_mssql.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: update_mssql.sh -h <host> -p <port> -d <database> -u <user> [--managed_instance <name>] ( --update_all | [--update_data] [--update_grants] [--update_model] [--update_property] ) [-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. -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. --update_all Update all information (i.e. Data, Model, Property, etc). Same as specifying all other "--update_..." flags. --update_data Update only Data information. Can be specified with any other "--update_..." flags, except "--update_all". --update_grants Update only Grants information. Can be specified with any other "--update_..." flags, except "--update_all". --update_model Update only Model information. Can be specified with any other "--update_..." flags, except "--update_all". --update_property Update only Property information. Can be specified with any other "--update_..." flags, except "--update_all". -y Suppress all non-required prompts, such as "Are you sure?" |
运行 ThingWorx 服务器时区脚本
| | 仅当从 ThingWorx 8.5 或 ThingWorx 9.0.0、9.0.1 或 9.0.2 升级到新的 ThingWorx 版本时，才需要运行 ThingWorx 时区脚本。ThingWorx 9.4.0 及更高版本不支持从 ThingWorx 8.5 或 ThingWorx 9.0.0、9.0.1 或 9.0.2 直接升级。相反，客户必须升级到中间 ThingWorx 版本，如 ThingWorx 9.3。从 ThingWorx 8.5 或 ThingWorx 9.0.0、9.0.1 或 9.0.2 升级到 ThingWorx 9.3.x 时，请运行以下脚本。ThingWorx 建议使用最新 ThingWorx 9.3.x 版本作为中间版本。 |
仅以下情况需要执行此部分的步骤：未在“设置 ThingWorx 服务器时区”部分的步骤 1 中设置 -Duser.timezone=UTC 时；或者，从 ThingWorx 8.5.x 或更早版本进行升级时。
1. 获取所有数据库特定时区名称的列表。要执行此操作，可手动连接到数据库并运行此查询，以获取数据库当前支持的所有时区名称的列表：
SELECT name, current_utc_offset, is_currently_dst FROM sys.time_zone_info 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_mssql.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: update_bigint_timezone_schema_mssql.sh -h <host> -p <port> -d <database> -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. -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?"
|
5. 完成上一步骤后，如有必要，可重新启动平台。但是，请注意，数据表、流和值流数据尚未迁移。因此，在进行数据迁移之前，针对该数据的查询所接收到的结果集可能会减少。
6. 运行 BigInt/Timezone 数据架构脚本以迁移数据表、流和值流数据：
update_bigint_timezone_data_msssql.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: update_bigint_timezone_data_mssql.sh -h <host> -p <port> -d <database> -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. -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_mssql.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: cleanup_bigint_timezone_data_update_mssql.sh -h <host> -p <port> -d <database> -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. -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_mssql.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: cleanup_update_mssql.sh -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 connect to. -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?" |
G.) 更新架构和迁移数据 (仅适用于 Azure SQL)
| | 以下所参考的全部脚本均位于 ThingWorx 软件下载的 update 文件夹中。 |
| | 以下所参考的全部脚本都需要数据库访问权限。如果定义了 SQLCMDPASSWORD 环境变量，则脚本将使用其值作为数据库密码。否则，脚本将提示您输入数据库密码。有关详细信息，请参阅 MSSQL 官方文档。 |
1. 运行主更新脚本以执行 ThingWorx 架构迁移：
update_mssql.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: update_mssql.sh -h <host> -p <port> -d <database> -u <user> [--managed_instance <name>] ( --update_all | [--update_data] [--update_grants] [--update_model] [--update_property] ) [-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. -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. --update_all Update all information (i.e. Data, Model, Property, etc). Same as specifying all other "--update_..." flags. --update_data Update only Data information. Can be specified with any other "--update_..." flags, except "--update_all". --update_grants Update only Grants information. Can be specified with any other "--update_..." flags, except "--update_all". --update_model Update only Model information. Can be specified with any other "--update_..." flags, except "--update_all". --update_property Update only Property information. Can be specified with any other "--update_..." flags, except "--update_all". -y Suppress all non-required prompts, such as "Are you sure?" |
运行 ThingWorx 服务器时区脚本
| | 仅当从 ThingWorx 8.5 或 ThingWorx 9.0.0、9.0.1 或 9.0.2 升级到新的 ThingWorx 版本时，才需要运行 ThingWorx 时区脚本。ThingWorx 9.4.0 及更高版本不支持从 ThingWorx 8.5 或 ThingWorx 9.0.0、9.0.1 或 9.0.2 直接升级。相反，客户必须升级到中间 ThingWorx 版本，如 ThingWorx 9.3。从 ThingWorx 8.5 或 ThingWorx 9.0.0、9.0.1 或 9.0.2 升级到 ThingWorx 9.3.x 时，请运行以下脚本。ThingWorx 建议使用最新 ThingWorx 9.3.x 版本作为中间版本。 |
仅以下情况需要执行此部分的步骤：未在“设置 ThingWorx 服务器时区”部分的步骤 1 中设置 -Duser.timezone=UTC 时；或者，从 ThingWorx 8.5.x 或更早版本进行升级时。
1. 获取所有数据库特定时区名称的列表。要执行此操作，可手动连接到数据库并运行此查询，以获取数据库当前支持的所有时区名称的列表：
SELECT name, current_utc_offset, is_currently_dst FROM sys.time_zone_info 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_mssql.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: update_bigint_timezone_schema_mssql.sh -h <host> -p <port> -d <database> -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. -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?"
|
5. 完成上一步骤后，如有必要，可重新启动平台。但是，请注意，数据表、流和值流数据尚未迁移。因此，在进行数据迁移之前，针对该数据的查询所接收到的结果集可能会减少。
6. 运行 BigInt/Timezone 数据架构脚本以迁移数据表、流和值流数据：
update_bigint_timezone_data_msssql.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: update_bigint_timezone_data_mssql.sh -h <host> -p <port> -d <database> -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. -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_mssql.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: cleanup_bigint_timezone_data_update_mssql.sh -h <host> -p <port> -d <database> -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. -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_mssql.sh
| | 在不使用任何参数的情况下运行此脚本会输出其使用语句： Usage: cleanup_update_mssql.sh -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 connect to. -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?" |
H.) 升级至 Java 11
| | Java 11 对于 ThingWorx 9.2.0 及更高版本而言必不可少。有关详细信息，请参阅系统要求。 |
1. 若要升级至 Java 11，则需执行以下步骤。如果已安装了 Java 11，请跳过此部分。
b. 在 Linux 上安装 jEnv：
i. Git 复制 jEnv 信息库：
git clone https://github.com/jenv/jenv.git ~/.jenv
ii. 将 jEnv 添加至 $PATH：
echo 'export PATH="$HOME/.jenv/bin:$PATH"' >> ~/.bash_profile
iii. 初始化 jEnv：
echo 'eval "$(jenv init -)"' >> ~/.bash_profile
iv. 更新于 ~/.bash_profile 中所作的更改：
source ~/.bash_profile
v. 设置 JAVA_HOME 环境变量：
jenv enable-plugin export
vi. 重新启动当前 shell 壳会话：
exec $SHELL -l
vii. 运行以下命令后，JAVA_HOME 变量将由 jEnv 自动设置，具体取决于当前使用的 Java 环境：
jenv doctor
c. 添加 Java 环境：
i. 添加任意环境。所有 Java 安装均位于 /usr/lib/jvm/ 中。使用 jenv add 命令。以下示例：
jenv add /usr/lib/jvm/java-11-amazon-corretto
jenv add /usr/lib/jvm/jdk-11.0.7
ii. 检查 jenv 的所有可用 Java 版本：
jenv versions
iii. 设置全局 Java 环境：
jenv global <version>
iv. 设置特定于壳的 Java 环境：
jenv shell <version>
v. 验证由 jenv 设置的当前版本：
jenv versions
vi. 更新 Tomcat Java 设置中的路径。
I.) 部署 ThingWorx.war 文件并重新启动
1. 复制新的 Thingworx.war 文件，然后将其置于以下 Tomcat 安装位置：/Apache Software Foundation/Tomcat x.x/webapps。
2. 启用扩展导入。默认情况下，所有用户的扩展导入均处于禁用状态。将以下内容添加至 platform-settings.json 文件。添加下列 ExtensionPackageImportPolicy 参数或将其更新为 true，以允许导入扩展。
"ExtensionPackageImportPolicy": {
"importEnabled": <true or false>,
"allowJarResources": <true or false>,
"allowJavascriptResources": <true or false>,
"allowCSSResources": <true or false>,
"allowJSONResources": <true or false>,
"allowWebAppResources": <true or false>,
"allowEntities": <true or false>,
"allowExtensibleEntities": <true or false>
},
"importEnabled": <true or false>,
"allowJarResources": <true or false>,
"allowJavascriptResources": <true or false>,
"allowCSSResources": <true or false>,
"allowJSONResources": <true or false>,
"allowWebAppResources": <true or false>,
"allowEntities": <true or false>,
"allowExtensibleEntities": <true or false>
},
3. 如果使用 H2 作为 ThingWorx 的数据库，则必须将用户名和密码添加到 platform-settings.json 文件中。
},
"PersistenceProviderPackageConfigs":{
"H2PersistenceProviderPackage":{
"ConnectionInformation":
{
"password": "<changeme>",
"username": "twadmin"
}
},
"PersistenceProviderPackageConfigs":{
"H2PersistenceProviderPackage":{
"ConnectionInformation":
{
"password": "<changeme>",
"username": "twadmin"
}
},
4. 启动 Tomcat。
5. 要恢复 SSO 配置：
a. 从备份 web.xml 文件中复制 SSOSecurityContextFilter 块。
b. 在新创建的 web.xml 文件中，将 SSOSecurityContextFilter 块粘贴到最后一个 AuthenticationFilter 块的后面。
6. 要启动 ThingWorx，请在 Web 浏览器中转至 <servername>\Thingworx。使用以下登录信息：
◦ 登录名：Administrator
◦ 密码：<源服务器管理员密码>
J.) 导入流和值流数据 (仅适用于 InfluxDB)
| | 如果正在执行的升级需要导出存储在 InfluxDB 中的数据，然后再导入到新版本 ThingWorx，请执行本部分所述步骤。有关确定是否需要执行导出-导入升级的信息，请参阅 B 部分。 |
1. 为 InfluxDB 创建新的持久化方案提供工具，或提供现有持久化方案提供工具的新连接信息。
2. 将流数据和值流数据导入到服务器。针对流数据和值流数据执行以下步骤。
a. 以管理员身份登录到 ThingWorx 9.x。
b. 单击“导入/导出”>“导入”。
c. 使用下列选项：
i. 对于“导入选项”，请选择“自文件”。
ii. 对于“导入类型”，请选择“数据”。
iii. 对于“导入源”，请选择“文件信息库”。
iv. 对于“文件信息库”，请选择“系统”。
v. 对于“路径”，请提供一个有效的系统信息库路径。
K.) 升级其他组件
• 如果要使用“集成连接器”，则必须获取并安装最新版本的 Integration Runtime。有关详细信息，请参阅集成连接器的集成运行时服务的初始设置。
• 如果从 8.x 升级至 9.x 且具有 Java 扩展，则请参阅将 Java 扩展从 8.x 迁移至 9.x。
• 如果将 ThingWorx Analytics 用作解决方案的一部分，则可以使用两个安装程序来处理组件升级：
◦ Analytics Server - 安装或升级 Analytics Server 和 Analytics Extension
◦ Platform Analytics - 安装或升级 Descriptive Analytics 和 Property Transforms
有关升级过程的详细信息，请参阅升级、修改和修复 ThingWorx Analytics
L.) 适用于 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 及更高版本会忽略它们。但是，如果决定将其移除，则必须等待升级过程完成。
M.) 故障排除
• 如果由于自定义索引字段缺少值而导致升级失败，则必须再次部署较旧版本 (如果进行了架构更新，则必须回滚/恢复数据库)，并添加缺失的索引值或从数据表中移除自定义索引，然后再执行升级。
启动 ThingWorx 平台后，检查平台的应用程序日志。如果您使用的是 MSSQL、PostgreSQL 或 H2，则系统可能会显示以下属性冲突错误消息。
应用程序日志错误 | 解决方案 |
|---|---|
Error in copying permissions: Problems migrating database | 除 MSSQL 升级时会显示此迁移错误外，当存在任何已配置运行时权限且名称包含超过 256 个字符的已迁移服务、属性或事件名称时，也会显示此错误。要修复此错误，请将所有服务、属性和事件名称限制为 256 个字符以下。 |
[L: ERROR] [O: c.t.p.m.BaseReportingMigrator] [I: ] [U: SuperUser] [S: ] [T: localhost-startStop-1] Thing: <Name of Thing>, has a property which conflicts with one of the following system properties: isReporting,reportingLastChange,reportingLastEvaluation. Please refer to the ThingWorx Platform 8.4 documentation on how to resolve this problem. | 作为添加到 ThingWorx Platform 8.4 中的“事物状态”功能的一部分，以下属性之前已添加到可报告事物形态中，且用于对实现此形态的事物进行状态评估： • isReporting • reportingLastChange • reportingLastEvaluation 如果事物、事物模板或事物形态中已存在上述属性名称之一，则在启动此平台时，应用程序日志中将出现以下错误。要解决此问题，必须移除每个受影响实体中发生冲突的属性，并更新任何关联的实体 (例如“混搭”或“服务”) 以适应此更改。如果没有此更新，则关联的事物无法正确显示其报告状态，也无法进行更新/保存。正确更新这些实体后，系统会显示平台特定的报告属性，并将其用于评估设备是否已连接并实现通信。 |
[L: ERROR] [O: c.t.p.m.BaseReportingMigrator] [I: ] [U: SuperUser] [S: ] [T: localhost-startStop-1] ThingTempate: <Name of ThingTemplate>, has a property which conflicts with one of the following system properties: isReporting,reportingLastChange,reportingLastEvaluation. Please refer to the ThingWorx Platform 8.4 documentation on how to resolve this problem. | |
[L: ERROR] [O: c.t.p.m.BaseReportingMigrator] [I: ] [U: SuperUser] [S: ] [T: localhost-startStop-1] ThingShape: <Name of ThingShape>, has a property which conflicts with one of the following system properties: isReporting,reportingLastChange,reportingLastEvaluation. Please refer to the ThingWorx Platform 8.4 documentation on how to resolve this problem. |