Skip to main content

运行迁移准备工具

重要

Only use this tool to migrate from Server version 2022.2 or earlier. The encryption mechanism was updated in the 2022.3 version.

开始之前

迁移准备工具会创建存储在数据库中的工作流数据的暂存副本。在此过程中，迁移准备工具将为您提供继续执行操作所需的预估空间。除非有足够的可用空间，否则请勿继续执行操作。

警告

您必须手动验证是否有足够的空间来完成此过程。“迁移准备”工具无法验证可用空间。

步骤 1：安装迁移准备工具

  1. Download the installer from downloads.alteryx.com and run it.

  2. Accept the EULA. Select Next.

  3. To change the installation location, select Change. Or select Next to accept the default location.

  4. Follow the prompts to complete the installation.

步骤 2：启动迁移准备工具

  1. Open a Command Prompt or PowerShell.

  2. Navigate to the chosen installation path (Default: C:\Program Files\Alteryx Migration Tool\).

  3. Run one of the commands to run the Migration Prep Tool. Note: If you use PowerShell, add .\ to the start of each command. You can run this operation on any host that has access to the MongoDB server. You can safely run it multiple times without downtime.

    For multi-node setup, the IP Address/Hostname, Controller Token and NON_ADMIN_MONGO_PASSWORD should be of the machine where controller node is running according to the configuration done during the multi-node setup.

    For single node, the details should be of the same machine where Alteryx Server is installed.

How to use the examples:

Replace these variables in the connection string with the values appropriate for your environment. These are the same credentials used to configure your Server database and can be found in Alteryx System Settings.

  • {authenticationDB} = the database that will authenticate the specified user credential.

    • If your Server is configured to use the embedded MongoDB, use the non-admin MongoDB password. In the connection string, your authSource should be ‘AlteryxService’.

    • For user-managed MongoDB, contact your MongoDB administrator to confirm the user credentials and authSource.

  • {port} = the service port MongoDB uses to provide access to the database.

  • {host.domain.tld} = the fully qualified domain name of your MongoDB server.

  • {password} = credential for the user.

  • {user} = username to access the database.

  • {atlasCluster.cloudProvider.mongodb.net} = the MongoDB Atlas cluster address.

Database

步骤

Embedded MongoDB

Note: NON_ADMIN_MONGO_PASSWORD',’CONTROLLER_TOKEN’ and 'localhost' should be changed based on your current setup.

Both App Chunk and RunAS_Credentials Migration

AlteryxServiceMigrator22_2.exe -p -c "mongodb://user:NON_ADMIN_MONGO_PASSWORD@localhost:27018/AlteryxService?authSource=AlteryxService" -i <host/IP_Address> -t <Controller_Token>

App Chunk Migration Only

AlteryxServiceMigrator22_2.exe --appsonly -c "mongodb://user:NON_ADMIN_MONGO_PASSWORD@localhost:27018/AlteryxService?authSource=AlteryxService" -i <host/IP_Address> -t <Controller_Token>

RunAs_Credential Migration Only

AlteryxServiceMigrator22_2.exe --credonly -c "mongodb://user:NON_ADMIN_MONGO_PASSWORD@localhost:27018/AlteryxService?authSource=AlteryxService" -i <host/IP_Address> -t <Controller_Token>

User-Managed MongoDB

Note: ‘Password’, ‘port’, ‘host.domain.tld’ and ‘authenticationDB’ should be changed based on your current MongoDB instance.

Both App chunk and RunAS_Credentials Migration

AlteryxServiceMigrator22_2.exe -p -c "mongodb://user:password@{host.domain.tld}:{port}/AlteryxService?authSource={authenticationDB} -i <host/IP_Address> -t <Controller_Token>

App Chunk Migration Only

AlteryxServiceMigrator22_2.exe --appsonly -c "mongodb://user:password@{host.domain.tld}:{port}/AlteryxService?authSource={authenticationDB} -i <host/IP_Address> -t <Controller_Token>

RunAs_Credential Migration Only

AlteryxServiceMigrator22_2.exe --credonly -c "mongodb://user:password@{host.domain.tld}:{port}/AlteryxService?authSource={authenticationDB} -i <host/IP_Address> -t <Controller_Token>

MongoDB Replica Sets

Both App Chunk and RunAS_Credentials Migration

AlteryxServiceMigrator22_2.exe -p -c "mongodb://{user}:{password}@{host1.domain.tld}:{port},{host2.domain.tld}:{port},{host3.domain.tld}:{port}/AlteryxService?authSource={authenticationDB}" -i <host/IP_Address> -t <Controller_Token>

App Chunk Migration Only

AlteryxServiceMigrator22_2.exe –-appsonly -c "mongodb://{user}:{password}@{host1.domain.tld}:{port},{host2.domain.tld}:{port},{host3.domain.tld}:{port}/AlteryxService?authSource={authenticationDB}" -i <host/IP_Address> -t <Controller_Token>

RunAs_Credential Migration Only

AlteryxServiceMigrator22_2.exe --credonly -c "mongodb://{user}:{password}@{host1.domain.tld}:{port},{host2.domain.tld}:{port},{host3.domain.tld}:{port}/AlteryxService?authSource={authenticationDB}" -i <host/IP_Address> -t <Controller_Token>

MongoDB Atlas

Both App Chunk and RunAS_Credentials Migration

AlteryxServiceMigrator22_2.exe -p -c "mongodb+srv://{user}:{password}@{atlasCluster.cloudProvider.mongodb.net}/AlteryxService?retryWrites=true&w=majority" -i <host/IP_Address> -t <Controller_Token>

App Chunk Migration Only

AlteryxServiceMigrator22_2.exe –-appsonly -c "mongodb+srv://{user}:{password}@{atlasCluster.cloudProvider.mongodb.net}/AlteryxService?retryWrites=true&w=majority" -i <host/IP_Address> -t <Controller_Token>

RunAs_Credential Migration Only

AlteryxServiceMigrator22_2.exe --credonly -c "mongodb+srv://{user}:{password}@{atlasCluster.cloudProvider.mongodb.net}/AlteryxService?retryWrites=true&w=majority" -i <host/IP_Address> -t <Controller_Token>

Command Parameters

  • -h [ --help ] display help info

  • -q [ --quiet ] output log messages to the command line (progress messages ignore this flag)

  • -s [ --severity ] arg (=7) console logging severity level (migration progress reports are sent at level 5)

  • -p [ --perform ] perform migration

  • --appsonly perform chunk migration only, with no preflight check

  • --credonly perform preflight check with no chunk migration

  • -u [ --forcenoprogressupdates ] disable progress update messages from being written to the console (they are still written to the log file)

  • -c [ --connection ] arg connection string (AlteryxService database must be specified)

  • -i [ --hostname ] arg   HostName|ip Address of Controller

  •  -t [ --controllertoken ] arg   Controller Token to retrieve the Keys

  • -l [ --loggingpath ] arg (=C:\ProgramData\Alteryx) logging file path, must contain a %N for log rotation purposes

  • --loggingmaxfilesize arg (=64) maximum size in MB for a log file before it gets rotated

  • -d [ --stagingdirectory ] arg directory where decrypted workflows will be temporarily stored before getting re-encrypted

What Happens Next?

  • When the migration starts, it will prompt you to confirm you have made a backup of the database and your runtime settings file. 

  • Once you confirm the backups, the utility checks the current space usage. It gives you an estimate of the additional space needed for the migration. You must check your system and continue only if you are sure that you have sufficient free space available to proceed.

  • After you have confirmed that there is sufficient space available, the utility begins migrating the workflow data. You will see console messages indicating the start time and completion time, along with progress messages.

疑难解答

如果在迁移过程中发生错误，该错误将显示在控制台中，并且还会捕获到日志文件中。

如果遇到错误，请执行以下步骤：

  1. 捕获命令提示符的屏幕截图。

  2. 遮盖或删除任何敏感数据。

  3. 捕获日志（请参阅位置和命名的验证步骤）。

  4. 再次运行迁移。

  5. 如果迁移再次失败，请联系支持人员并在报告中添加屏幕截图和日志文件。

注意

If the error Error during key initialization <Error importing keys to Microsoft\Crypto\RSA\MachineKeys\ directory in ProgramData: Access is denied. (5)> RunAS Migration failed occurs while running the migration command, navigate to C:\ProgramData\Microsoft\Crypto\RSA\MachineKeys. Then right-click on the MachineKeys folder and select Share with specific people. Select Everyone with Read/Write access. Then select Share.

步骤 3：升级到 Server 2024.1

重要

  • 在升级之前，请创建 Mongo 数据库的备份副本 和 RuntimeSettings.xml 。在维护期内执行的加密是不可逆的。备份可保护您的安装免受数据丢失或额外停机时间的影响。

  • 在 2024.1 升级期间，无法查看迁移进度。

  • 如需详细了解升级，请参阅 安装或升级 Server 。

  1. Download Server 2024.1 from downloads.alteryx.com.

  2. Run the installer. Select Yes to continue the upgrade.

  3. Accept the License Agreement.

  4. Choose your installation path or accept the default path. Then select Next.

  5. Select Install to start the installation (upgrade).

  6. When installation is complete, select Configure Server Now, then select Finish.

  7. After the installation of Server 2024.1 is complete, select the Begin Backup and Migration option.

  8. After successful migration, select OK.

Note: After installation, there might be a delay in starting the service.

Next Steps After Installation

Alteryx System Settings opens. Navigate through System Settings to check that your settings are correct. Then select Finish and Done to start the service.

Once the service starts, Server enters maintenance mode to migrate RuntimeSettings and the database values that could not be migrated beforehand. During the maintenance mode, your Server instance will be unavailable.

The Migration Prep tool does a final check for database changes since the last run. Then it performs the migration (including any newfound changes) and moves the staged migration into use.

This final migration might take several hours. The time depends on the size of your configuration and if the Migration Prep Tool was run before the upgrade. Once this process is complete, Server will exit the maintenance mode and enter a functional state.

疑难解答

如果服务在一段时间后关闭，请检查这些日志中是否存在迁移错误：

  • LastStartupError.txt

  • 由迁移准备工具创建的 AlteryxServiceMigrator_#.log

  • 在服务启动期间创建的 AlteryxServiceMigrator_#.log

如果遇到迁移错误，请尝试重新启动 AlteryxService。尝试重新启动 AlteryxService 后，可能会解决问题。如果问题仍然存在，请收集日志并联系客户支持人员寻求帮助。尝试重启 AlteryxService 有可能会解决问题，因为它将重新尝试任何未完成的迁移步骤，但具体结果还要取决于错误。

步骤 4：验证迁移成功

要验证迁移准备工具是否已成功完成，请选择以下任一选项。

验证迁移准备工具日志

  1. 导航至 C:\ProgramData\Alteryx\Service\ 。

  2. 打开 AlteryxServiceMigrator_#.log 。

  3. 查看日志以找到错误或失败消息。在日志中搜索显示为“ ;3; ”的状态 3。

验证服务启动日志

  1. 依次点击 Alteryx 系统设置 > Controller > General > Logging ，找到所设置的日志记录文件夹。

  2. 打开 AlteryxServiceMigrator_#.log 。

  3. 查看日志以找到错误或失败消息。在日志中搜索显示为“ ;3; ”的状态 3。

升级到 2024.1 后（最终迁移后）进行验证

  1. 通过 Web URI 登录 Server。

  2. 验证以下各项：

    • 您可以手动运行工作流程和应用程序。

    • 计划处于活动状态且运行结果符合预期。

    • 您可以查看、编辑、创建和使用工作流凭证。

    • 您可以查看、编辑、创建和使用 Server 数据连接。

    • 从 API 检索工作流包，将该包导入 Designer，然后在 Designer 中运行工作流。

本节内容如下: