平台配置工具

重要提示：

平台配置工具适用于从过去 3 年内发布的版本（相对于当前主要版本）升级的版本。在安装 Orchestrator 之后进行安装后检查和操作。

概述

UiPath 平台配置工具是一个PowerShell脚本，用于帮助您成功安装/升级Orchestrator。它可以帮助您在升级之前检查环境的完整性和就绪性，并帮助您在安装后执行一些操作。

该工具可从下方下载，而且还与 UiPathOrchestrator.msi 安装程序捆绑。捆绑的脚本可以在 Orchestrator 安装目录的 Tools 文件夹中找到，默认位置为 C:\Program Files (x86)\UiPath\Orchestrator\。该脚本会检查 Orchestrator 计算机。多节点安装时，在一个节点上运行该工具便已足够。

重要提示：

在某些环境中，尝试运行该工具可能会返回 PowerShell 错误，指示脚本未经过数字签名。为防止出现此错误，请在运行脚本之前更改 Windows 执行策略：

• 要将执行策略永久设置为 unrestricted，请运行以下命令：

  Set-ExecutionPolicy -ExecutionPolicy Unrestricted
  

  当提示确认更改时，请按 Y。

• 要绕过单个 PowerShell 会话的执行策略，请运行以下命令：

  powershell.exe Set-ExecutionPolicy Bypass
  

平台配置工具不遵循与 UiPathOrchestrator.msi 安装程序相同的版本控制模式，而且可以在产品发布周期外进行更新。我们建议您始终下载并使用以下工具的最新版本。

下载工具

先决条件

软件	兼容版本
PowerShell	5.1.
网页管理模块	不适用
PKI 模块	不适用

脚本 Cmdlet

该脚本由旨在执行特定功能的三个 cmdlet 组成。可以在命令行中输入 cmdlet 调用命令及其相关参数以立即执行。

Cmdlet	描述
Test-PlatformReadiness	使用-Readiness 命令。 在升级之前检查环境的完整性和就绪性，并在安装之后检查证书要求。
Update-UiPathUrl	使用UpdateUiPathUrl 命令。 更新 Orchestrator 的公共地址，并检查新地址是否适用于当前证书。
Update-UiPathCertificate	使用UpdateUiPathCertificate 命令。 更新 Orchestrator SSL 证书或身份服务器令牌签名证书。
AddHostAdmin	使用AddHostAdmin 命令。 将系统管理员添加到主机租户。

安装前检查

Asp.Net Core

检查 ASP.NET Core IIS 模块 v3.1.x+是否已安装并正常运行。如果不是，系统会提示您卸载并重新安装 ASP.Net Core Hosting Bundle。

CyberArk AIM

检查 CyberArk AIM 代理是否安装在 C:\Program Files (x86)\CyberArk 文件夹下。如果不是，系统会在安装后提示用户使用 Plugins.SecureStores.CyberArk.CLIPasswordSDKExePath 密钥在 UiPath.Orchestrator.dll.config 文件中添加 CLIPasswordSdk.exe。

如果在 UiPath.Orchestrator.dll.config 中找不到 CyberArk，则无需执行此检查。

web.config 加密

检查 web.config 文件是否已解密。如果已加密，则需要在升级之前手动将其解密。升级后， Orchestrator 的大多数配置设置都会移至 UiPath.Orchestrator.dll.config。

Learn how to encrypt the UiPath.Orchestrator.dll.config file.

web.config 锁定部分

检查 <system.webServer> 元素是否包含任何锁定部分。如果存在此类部分，则需要在 IIS 中手动将其解锁。

SQL Server 横向扩展

检查是否使用 SQL Server 横向扩展。系统会在安装过程中通知您已启用 Redis 横向扩展。

凭据存储插件

Checks that external credential store plugins target a supported framework.

NLog 插件

Checks that NLog plugins target a supported framework.

文件系统存储桶

此检查将验证 Orchestrator 2020.4 及更高版本中是否存在 Buckets.FileSystem.Allowlist 应用程序设置。这涵盖了安装前检查 (Orchestrator 2020.4) 和安装后检查 (Orchestrator 2020.10+)。2020.4 之前的 Orchestrator 版本会跳过此检查。

• 要执行以下检查，您需要解密 connectionStrings 和 appSettings 配置节。如果这些配置节中的任何一个被加密，则在终端中会出现一条警告提示，其余存储桶验证将被跳过。

  Could not determine if any buckets with file system provider are in use. Config section 'connectionString' is encrypted, could not find the sql connection string to the UiPath database.
  

• 如果由于当前用户无法访问数据库而无法检索存储桶，请用有权访问 SQL Server 和数据库的用户运行检查。

  Could not determine if any buckets with file system provider are in use. Could not connect to the UiPath Database.
  

• 对 Orchestrator 数据库存储桶表中检索到的存储桶根路径执行此验证。如果存在任何不合格的路径，则在终端中会出现一条警告提示您。Buckets.FileSystem.Allowlist 应用程序设置中的路径进行了类似的检查，以检查不合格的路径。

• 如果两个来源中的任何一条路径无效或不合格，则在以下所述的其余验证中均不会考虑该路径。

• 如果 Buckets.FileSystem.Allowlist 应用程序设置未在配置文件中设置，则终端会提示您错误，要求您将允许列表添加到配置文件中。建议的路径是使用文件系统提供程序的存储桶的根路径。

  All storage buckets using the file system provider are not on the allowed list. Add the following setting in the configuration file to allow all exiting buckets root paths: <add key="Buckets.FileSystem.Allowlist" value="C:\work\stuff\Bucket\|C:\work\stuff\Bucket1\" />
  

• 如果 Buckets.FileSystem.Allowlist 应用程序设置已在配置文件中设置，那么将对使用文件系统提供程序的存储桶的根路径执行验证。如果存储桶根路径不是允许列表中定义的任何路径的子路径，则在终端中会出现一条警告提示您，要求您将存储桶根路径添加到 Buckets.FileSystem.Allowlist。

  There are some storage buckets using the file system provider that are not on the allowed list. The buckets feature will not work for buckets with root paths that are not on the allowed list. Check if any of the following paths are required to be on the allowed list and add them to the 'Buckets.FileSystem.Allowlist' key in configuration file: |C:\work\stuff\Buckets\|C:\work\stuff\Bucket1\
  

• 否则，如果每个存储桶根路径都是允许列表中某一路径的子路径，则终端将显示成功消息。

  All storage buckets using file system provider have the root path on the allow list in the configuration file.
  

安装后检查

证书要求

Checks that all certificate requirements are met by your Orchestrator instance after an upgrade.

SSL 证书检查

• Orchestrator 网站的 hostname 与证书上的使用者或使用者可选名称（包括通配符）匹配，
• 具有有效的信任链，并且
• 未过期。

身份服务器令牌签名证书检查

• 证书具有适当的密钥长度（2048 位或更大），
• 具有可由应用程序池用户访问的私钥，并且
• 未过期。

其他注意事项

Check the docs on installation considerations for other areas impacted by an upgrade to 2020.10+ that you need to be aware of.

运行脚本

命令参考

命令与参数	描述
-Readiness	在升级之前检查环境的完整性和就绪性，并在安装之后检查证书要求。 参数： -SiteName -Help -InstallationDirectory
-UpdateUiPathUrl	更新 Orchestrator 的公共地址。 参数： -SiteName -OrchestratorUrl -SqlConnectionString The SQL Server PowerShell module is required to use this command. The module is installed by default with SQL Server. If you’re working on a machine that doesn’t have the module installed, see here how to install it. Use this command with caution as it does not have a roll-back mechanism if a step errors out during execution.
-UpdateUiPathCertificate	更新 Orchestrator SSL 证书或身份服务器令牌签名证书。与 -readiness 命令一起使用以检查新证书的有效性。 参数： -SiteName -NewTokenSigningThumbprint -NewSSLThumbprint -KeepOldCertificate
-AddHostAdmin	如果无法访问主机组织（例如，如果系统管理员的密码丢失，或者拥有系统管理员帐户的用户离开公司），您可以使用此命令添加或恢复系统管理员。 参数： -SiteName -HostAdminUsername -HostAdminPassword -HostAdminEmail

脚本参数

参数	描述
-SiteName	可选。目标计算机上 Orchestrator 网站的名称。默认为 "UiPath Orchestrator"。-InstallationDirectory 与 SiteName 互斥。
-Help	可选。显示有关工具选项或可用命令的信息，例如命令的语法或其执行的检查。
-InstallationDirectory	可选。Orchestrator 安装目录的路径。通常为 C:\Program Files (x86)\UiPath\Orchestrator\ 。-InstallationDirectory 与 SiteName 互斥。 Make sure the installation directory path ends with a trailing backslash (\).
-OrchestratorUrl	必需。Orchestrator 的新公共地址。
-SqlConnectionString	可选。UiPath 数据库连接字符串。如果保留为空，则从 appsettings.Production.json 文件读取该值。
-NewTokenSigningThumbprint	Optional. The thumbprint of the new token signing certificate used by the Orchestrator Identity Server.
-NewSSLThumbprint	Optional.The thumbprint of the new SSL certificate used by the Orchestrator Web App.
-HostAdminUsername	仅在使用 -AddHostAdmin 命令时为必需。要创建或还原的主机管理员用户的用户名。
-HostAdminPassword	使用 -AddHostAdmin 命令时要创建或还原的主机管理员用户的电子邮件地址。仅在使用以下外部身份提供程序时才必需： Google Azure Active Directory 具有电子邮件用户映射策略的 SAML
-HostAdminEmail	使用 -AddHostAdmin 命令时要创建的主机管理员用户的密码。仅当用户是基本身份验证用户时，才需要输入密码。首次登录时需要更改密码。

示例

要使用平台配置工具脚本，请打开 Administrator PowerShell 脚本。

找到解压缩平台配置工具存档的目录，并将该目录更改为此位置：

cd "C:\Program Files (x86)\UiPath\Orchestrator\Tools\PlatformConfiguration"

执行就绪检查

以下示例允许您对 Orchestrator 的预安装要求执行验证。该过程在 -verbose 级别记录其步骤并输出额外信息。

.\Platform.Configuration.Tool.ps1 `
-Readiness `
-SiteName "UiPath Orchestrator"

安装前检查是否成功输出（适用于从 2020.4 开始的升级）。

Validating 22.10 pre-installation requirements... Checking AspNetCore hosting module... AspNetCore hosting module is installed. Checking CyberArk CLIPasswordSDK.exe path... CyberArk CLIPasswordSDK.exe was found at the default installation path 'C:\Program Files (x86)\CyberArk\ApplicationPasswordSdk\CLIPasswordSDK.exe'. Checking Web.config sections encryption... Web.config sections are not encrypted. Checking IIS configuration locked sections... Configuration sections are not locked. Checking Orchestrator ssl certificate subject alternative names... Orchestrator host name is valid for the ssl certificate subject alternative names. Checking sql server scaleout use... Sql server scaleout is not used. Checking external credential store plugins target framework... Credential stores plugins validation is finished. Checking external NLog plugins target framework... NLog plugins validation is finished. Checking buckets with file system storage provider... All storage buckets using file system provider have the root path on the allowed list in the configuration file. Checking platform certificates... Platform certificates validation is finished. All 22.10 pre-installation checks are done. Platform readiness validations: 10 succeeded, 0 failed and 0 warning(s).

安装后更改证书

以下示例允许您更新 Orchestrator SSL 和身份服务器令牌签名证书。

.\Platform.Configuration.Tool.ps1 `
-UpdateUiPathCertificate `
-KeepOldCertificate $false `
-SiteName "UiPath Orchestrator" `
-NewSSLThumbprint "a1b2c3d4" `
-NewTokenSigningThumbprint "z6y5x4v3"

备注：

• 在使用脚本之前，应解密所有 appsettings 文件。
• Make sure the certificates have the appropriate permissions set to prevent an internal server error. Refer to Troubleshooting Certificates for more details.
• KeepOldCertificate 参数指示是否应继续将当前证书用作使用其签名的令牌的验证密钥。

如果尚未将私钥添加到证书中，则可以通过执行以下步骤手动添加：

1. 要找到私钥，请启动 Internet 信息服务 (IIS) 管理器，然后选择“应用程序池”。您应该可以在“身份”列下找到每项服务的私钥。
2. 转到“控制面板”下的“管理计算机证书”。
3. 转到“个人/证书”。
4. 右键单击“新建证书”，然后转到“所有任务”>“管理私钥”以添加私钥。

备注：

如果您有多个 Orchestrator 节点，请确保更新所有服务器节点上的证书。

更改 Orchestrator URL

以下示例允许您更新 Orchestrator URL。

.\Platform.Configuration.Tool.ps1 `
-UpdateUiPathUrl `
-OrchestratorUrl "https://mydomainname" `
-SiteName "UiPath Orchestrator" `
-SqlConnectionString "Server=myServerName\myInstanceName;Database=myDataBase;User Id=myUsername;Password=myPassword;"

备注：

尽管我们建议对 Orchestrator URL 使用小写字母，但该工具会自动将任何大写字符串转换为小写字母。

创建新的系统管理员

The following example creates a new system administrator on the host tenant using basic authentication. Note that if an external identity provider is set as exclusive, basic authentication is only accessible through the hostlogin URL documented in Accessing Identity Management Portal.

.\Platform.Configuration.Tool.ps1 `
-AddHostAdmin `
-SiteName "UiPath Orchestrator" `
-HostAdminUsername someuser `
-HostAdminPassword som3pwd! `
-HostAdminEmail [e-mail]

输出

输出以颜色进行编码。

颜色	描述
红色	阻止器 元素丢失或未配置，将阻止安装。
黄色	警告 您可以安装 Orchestrator，但其不会带来其他好处。
绿色	消息 该环境已做好安装准备。