• JAVA 需求 (安裝程式不會將 Java 封裝或安裝為安裝的一部份):
◦ 應該由初始安裝 ThingWorx 的使用者執行升級。初始安裝期間,安裝程式會產生 ThingWorxFoundation.xml 檔案,其中包括安裝以及升級所需的相關資訊。此檔案位於執行安裝之使用者的使用者設定檔中。例如,在 C:\Users\Administrator\.ptc_cci 內。
• 備份您的資料庫。安裝程式不會在升級流程期間執行資料庫備份。
• 您必須擁有下列其中一個作業系統與這些資料庫組合:
◦ 含 PostgreSQL 的 Windows
◦ 含 Microsoft SQL Server 的 Windows
◦ 安裝了 PostgreSQL 的 Red Hat Enterprise Linux
◦ 安裝了 Microsoft SQL Server 的 Red Hat Enterprise Linux
• 如果資料表格中遺失任何自訂索引欄位值,升級將會失敗。在開始升級流程之前,核對所有自訂索引欄位都有值。
• 開始升級之前,請務必關閉所有資料庫連線。如需更多詳細資訊,請參閱下列內容。
如果您已安裝 ThingWorx Foundation 8.5.3 或較早版本,您應該先執行 ThingWorx 升級就緒公用程式,其可在 > > > > > 下找到。
ThingWorx 升級就緒公用程式會建立支援 ThingWorx Foundation (若已安裝,則為 ThingWorx Flow) 自動升級所需的 XML 檔案。此公用程式會提示您在您的系統中找出 ThingWorx Foundation (若已安裝,則為 ThingWorx Flow),然後配置所選安裝。它會在您的使用者設定檔中建立 ThingWorxFoundation 檔案,如果您已安裝 ThingWorx Flow,則為 ThingWorxFlow.xml 檔案。檔案會儲存在您使用者設定檔的 .ptc_ccif 資料夾中 (例如,在 Windows 中,為 C:\Users\Administrator\.ptc_ccif;在 Linux 中則為 ~/.ptc_ccif/)。
如果您的 ThingWorx 8.5.4 或更新版本是使用安裝程式所安裝,則必要 XML 檔案已作為安裝一部份建立;因此,不需要執行 ThingWorx 升級就緒公用程式。
疑難排解
• 如果您是使用安裝程式安裝 ThingWorx Foundation 8.5.3 或更早版本,然後又手動升級到了較新的 8.5 版,而且現在準備透過執行 ThingWorx 升級就緒公用程式來升級至 9.x,請執行下列操作:
◦ 執行 ThingWorx 升級就緒公用程式。
◦ 確認您使用者設定檔中 ThingWorxFoundation.xml 檔案的 <applicationVersion> 內容值為目前版本。
• 如果您在執行 ThingWorx 升級就緒公用程式時遇到問題,且需要手動建立或編輯 ThingWorxFoundation.xml 檔案,可使用下列範例並根據您的升級路徑予以更新:
<?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>
| 更新至 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 或更新版本。
欲執行此資料移轉,請執行下列操作:
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 Options,新增下列內容:-Duser.timezone=UTC
b. 選擇 Apply。
6. 選擇「確定」以關閉 GUI。
7. 使用 tomcat9.exe 更新服務參數。
8. 以管理員身分執行 CMD 並執行下列指令:
tomcat9.exe //US//ThingWorx-Foundation
在 Linux 中配置時區設定
1. 使用 systemctl stop ThingWorx-Foundation.service 停止 ThingWorx-Foundation 服務。
2. 將 ThingWorx-Foundation.service 備份到 /etc/systemd/system/ThingWorx-Foundation.service.backup 中。
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)
系統會提示您輸入資料庫使用者的密碼,此密碼會傳入 -u or -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 表格與移轉功能。
如果您要升級至 ThingWorx 9.2.x 或更新版本,您必須執行清理指令集來移除在升級流程期間建立的臨時表格。
執行位於 <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)
系統會提示您輸入資料庫使用者的密碼,此密碼會傳入 -u or -l 參數。
如果要從 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 及更高版本將直接略過它們。但是,如果您決定移除上述檔案,則必須等到升級程式完成之後執行。
• 如果升級失敗,並出現下列錯誤,請執行以下步驟。如果任何自訂索引值大於或等於 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。
• 如果安裝程式無法完成升級,請執行下列操作:
1. 檢查安裝目錄中 /installer/logs 下的記錄檔。
2. 回復為您的升級前安裝:
a. 將您的資料庫還原為其備份。
b. 啟動 ThingWorx-Foundation 服務。
• 如果安裝程式已成功執行,表示 ThingWorx Foundation 已升級。但是,ThingWorx Foundation 安裝位置的名稱可能並非最新。您可以在 Composer 的 > 下,核對您的 ThingWorx 版本。
• 如果您的作業系統是 RHEL 8.2,而且您要從 ThingWorx 8.5.7 升級,您應該先手動解除安裝 Chef Infra Client,以確保安裝程式能夠佈建及使用所支援版本的 Chef。欲解除安裝 Chef,請執行下列操作:
| 如果您之前已自行安裝 CINC,建議您先解除安裝 CINC,然後讓安裝程式將其作為我們安裝的一部份安裝。 |
a. 執行下列指令,找到 Chef Infra Client 安裝程式的封裝名稱:$ 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. 刪除安裝目錄 $ sudo rm -rf /opt/chef 來轉至 /opt 目錄,並移除所有 Chef Infra Client 檔案。