配置并启动 Cluster Admin

Cluster Admin 是一个代理，可用来安装、配置和启动用于各种 Polyspace^® Access™ 服务的 Docker 容器。

前提条件

配置并启动 Cluster Admin 之前：

下载 Polyspace Access 安装镜像：
1. 转至 MathWorks^® 下载页面。
2. 从我要菜单中，选择安装产品以安装新版本的 Polyspace Access，或选择获取更新以安装更新，例如 R2026a Update 2。
3. 展开获取 Polyspace Access Web Server 部分并点击下载。检查下载按钮下的文本是否列出了您想要获取的版本和更新号（如适用）。
确认您使用的 Docker API 最低版本为 1.44。要强制 Docker 使用正确的 API 版本，请将环境变量 DOCKER_API_VERSION 设置为 1.44 或更高版本。有关详细信息，请参阅 Docker Engine API 文档。
检查您的计算机上是否有可正常运行的 Docker。在命令行中键入：
```
docker ps
```
如果收到错误消息，请运行命令 sudo systemctl start docker。如果 systemctl 不可用，请改用 service。
启动 Polyspace Access 后，您必须以 docker 组成员的身份登录才能运行 Polyspace Access 命令。要查看此组的当前成员列表，请使用以下命令：
```
grep 'docker' /etc/group
```
要将当前用户添加到 docker 组，请使用以下命令：
```
sudo usermod -aG docker $USER
```

解压缩安装镜像并启动 Cluster Admin 代理

Cluster Admin admin-docker-agent 二进制文件包含在 Polyspace Access 的 polyspace-access-VERSION.zip 安装镜像中。VERSION 为发行版本，例如 R2026a。下载安装镜像后，请将其解压缩以提取以下文件和文件夹：

admin-docker-agent*
admin-docker-agent.exe*
admin.tar
appdata/
download/
gateway.tar
issuetracker-server-main.tar
issuetracker.tar
issuetracker-ui-main.tar
lm/
polyspace-access-db-main.tar
polyspace-access-download-main.tar
polyspace-access-etl-main.tar
polyspace-access.tar
polyspace-access-web-server-main.tar
products/
usermanager-db-main.tar
usermanager-server-main.tar
usermanager.tar
usermanager-ui-main.tar
VERSION

要启动 admin-docker-agent 二进制文件，请从命令行导航到提取 zip 安装镜像内容的安装文件夹。进入此文件夹后，从命令行输入以下命令：

admin-docker-agent

命令行会输出指示该代理正在下载镜像层的消息。下载完成后，您会看到一条指明如何连接到该代理的信息：

time="2020-07-10T14:23:11Z" level=info msg="Cluster Admin started. You can now connect to the Cluster Admin through 
your web browser at http://localhost:9443/admin using the initial password randomPass

randomPass 是一个随机生成的初始密码。请复制此密码。命令行输出仅在您首次启动 Cluster Admin 时显示此密码。

默认情况下，Cluster Admin 采用 HTTP 协议，并且使用主机名 localhost 和端口 9443 启动。

要将 Cluster Admin 配置为使用 HTTPS，请参阅为 Polyspace Access 选择 HTTP 或 HTTPS 配置。
如果默认端口已被使用，则您会收到 Permission denied 错误消息。可使用 --port 标志指定一个不同的端口号，例如：
```
admin-docker-agent --port 9999
```
要生成无需指定端口号的 Polyspace Access URL，例如 https://accessServerHost.com 而不是 https://accessServerHost:9443.com，请使用 --port 标志并为 HTTPS 选择端口 443 或为 HTTP 选择端口 80。

要重置密码，请按 CTRL+C 来停止 admin-docker-agent 二进制文件并输入以下命令：

admin-docker-agent --reset-password

要查看新密码，请重新启动该二进制文件。

Cluster Admin 代理在首次启动时会创建一个 settings.json 文件，并默认将该文件存储在与 admin-docker-agent 二进制文件相同的文件夹中。请确保只有启动 admin-docker-agent 的用户对 settings.json 文件具有读取/写入权限。

为 Polyspace Access 选择 HTTP 或 HTTPS 配置

Polyspace Access 的 HTTP 配置

默认情况下，Cluster Admin 采用 HTTP 协议。启动 admin-docker-agent 二进制文件时，不需要指定任何其他标志。Polyspace Access 与客户端计算机之间的通信是不加密的。

Polyspace Access 的 HTTPS 配置

要加密 Polyspace Access 与客户端计算机之间的数据，请将 Cluster Admin 配置为使用 HTTPS 协议。

要完成配置，请执行以下操作：

使用主题备用名称 (SAN) 扩展生成私钥和证书签名请求 (CSR)。
将该 CSR 提交到组织的证书认证中心 (CA) 以获取 PEM 格式的签名 X.509 证书。另外，也可以使用私钥和 CSR 创建自签名 PEM 证书。
启动 admin-docker-agent 二进制文件，并使用以下选项传递私钥和证书文件。所有文件都必须采用 PEM 格式。

选项选项参数
--ssl-cert-file CA 签名证书或自签名证书文件的路径。
--ssl-key-file 私钥文件的路径。
--ssl-ca-file CA 信任存储文件或自签名证书文件的路径。

选项	选项参数
`--ssl-cert-file`	CA 签名证书或自签名证书文件的路径。
`--ssl-key-file`	私钥文件的路径。
`--ssl-ca-file`	CA 信任存储文件或自签名证书文件的路径。

建议您使用由证书认证中心颁发的证书配置 HTTPS。不建议在测试环境之外使用自签名证书，因为大多数 Web 浏览器无法确定使用自签名证书的服务器的真实性，会认为与该服务器的连接不安全。在生产环境中使用自签名证书为 Polyspace Access 配置 HTTPS 之前，请与您的网络安全管理员联系。

为 Cluster Admin 配置 HTTPS 可启用 API Gateway 服务的 HTTPS。此服务可处理其他 Polyspace Access 服务与客户端计算机之间的所有通信。要为不同 Polyspace Access 服务之间的通信配置 HTTPS，请参阅在 Polyspace Access 服务之间启用 HTTPS。

1.生成私钥和证书签名请求

以下步骤展示了如何在 Debian Linux^® 系统上使用 openssl 实用工具和 openssl 配置文件生成私钥和配置有 SAN 扩展的 CSR。

将下面的配置文件复制到文本编辑器，并以 openssl.cnf 名称将其保存到您的计算机。

配置文件

hostName 是运行 API Gateway 服务的服务器计算机的完全限定域名 (FQDN)。hostName 必须与启动 admin-docker-agent 二进制文件时指定的 FQDN 一致。您可以运行 hostname -f 命令来获取 hostName。编辑 [ req_distinguished_name ] 部分中的其他字段不会影响配置。

要为解析为相同 IP 地址的多个主机名配置 HTTPS，请在 openssl 配置文件的 [ alt_names ] 部分的新行中添加每个主机名（DNS 或 IP 地址）。例如：

[ alt_names ]
DNS.1 = server-machine.example.com
DNS.2 = server-machine
IP.1 = 192.168.0.1

使用您的 openssl.cnf 配置文件生成 CSR。在命令行终端中，输入以下命令：
```
openssl req -new -out myRequest.csr -newkey rsa:4096 -keyout myKey.pem -nodes -config openssl.cnf
```
该命令输出私钥文件 myKey.pem 和文件 myRequest.csr，其中包含一个公钥和描述服务器的数据。

不要重用您在 User Manager 配置中用于 Authentication private key file 字段的私钥文件。请参阅配置 User Manager。

采用如下最佳做法保护您的私钥：

不要在计算机之间传输私钥。而是在本地文件系统中生成并存储私钥。
限制读取/写入权限。仅向 Cluster Admin 管理员授予对私钥文件的访问权限。
定期（每年一次）轮换您的私钥和证书，并对有权访问私钥文件的用户进行审核。

2.获取并验证 CA 证书或自签名证书

将 CSR 文件 myRequest.csr 提交到组织的证书认证中心。证书认证中心使用该文件生成签名的服务器端证书。例如，admin_cert.cer。

此外，也可以通过运行以下命令并使用私钥、CSR 和 openssl 配置文件生成自签名证书：

openssl x509 -req -days 365 -in myRequest.csr -signkey myKey.pem -out self_cert.cer -extensions x509 -extfile openssl.cnf

此命令输出自签名证书 self_cert.cer。

获取 CA 证书或生成自签名证书后，您可以使用 openssl 实用工具来验证证书内容。例如，要检查 DNS 是否正确列在自签名证书的主题备用名称部分，请运行以下命令：

openssl x509 -text -noout -in self_cert.cer | grep -A 1 "Subject Alternative Name"

该命令输出的行与“主题备用名称”以及下一行匹配，其中列出了与证书关联的 DNS。

3.启动 Admin Docker 代理

注意

如果您正在从 HTTP 切换到 HTTPS，或从 HTTPS 切换到 HTTP，请在继续操作前停止并删除当前安装的 Docker 容器。有关详细信息，请参阅步骤 2：停止并删除当前安装的容器。

获取 CA 证书或生成自签名证书后，通过运行相应的命令启动 admin-docker-agent。

CA 证书自签名证书

CA 证书	自签名证书
./admin-docker-agent --hostname hostName\ --ssl-cert-file absolutePathTo/admin_cert.cer \ --ssl-key-file absolutePathTo/myKey.key \ --ssl-ca-file /etc/ssl/certs/ca-certificates.crt `ca-certificates.crt` 是 Debian^® Linux 系统上的证书信任存储文件。当您打开 Cluster Admin Web 界面时，如果浏览器使用您为 `--ssl-ca-file` 指定的证书信任存储，则浏览器会认为连接是安全的。	./admin-docker-agent --hostname hostName\ --ssl-cert-file absolutePathTo/self_cert.cer \ --ssl-key-file absolutePathTo/myKey.key \ --ssl-ca-file absolutePathTo/self_cert.cer 自签名 `certificate.pem` 文件也用作证书信任存储文件。因为您未指定与证书认证中心关联的信任存储，所以当您打开 Cluster Admin Web 界面时，浏览器可能会显示证书不可信的警告。

./admin-docker-agent --hostname hostName\
--ssl-cert-file absolutePathTo/admin_cert.cer \
--ssl-key-file absolutePathTo/myKey.key \
--ssl-ca-file  /etc/ssl/certs/ca-certificates.crt

ca-certificates.crt 是 Debian^® Linux 系统上的证书信任存储文件。当您打开 Cluster Admin Web 界面时，如果浏览器使用您为 --ssl-ca-file 指定的证书信任存储，则浏览器会认为连接是安全的。

./admin-docker-agent --hostname hostName\
--ssl-cert-file absolutePathTo/self_cert.cer \
--ssl-key-file absolutePathTo/myKey.key \
--ssl-ca-file  absolutePathTo/self_cert.cer

自签名 certificate.pem 文件也用作证书信任存储文件。因为您未指定与证书认证中心关联的信任存储，所以当您打开 Cluster Admin Web 界面时，浏览器可能会显示证书不可信的警告。

您在此命令中指定的 hostName 必须与您在 openssl 配置文件中指定的 hostName 一致。absolutePathTo 是绝对文件路径。

在 Polyspace Access 服务之间启用 HTTPS

要为 Polyspace Access 服务之间的通信启用 HTTPS，请在打开 Cluster Admin 界面后点击 Cluster Dashboard 上的 Configure Nodes，然后在 General 选项卡上选择 Enable SSL。在 Nodes 设置中启用 SSL 只会影响安装在该节点上的 Polyspace Access 服务之间的通信。您在启动 admin-docker-agent 二进制文件时提供的 SSL 证书、私钥和 CA 文件将重用于 Nodes 设置中，除非已为该节点配置一组不同的文件。

默认情况下，所有服务都安装在同一节点上并且服务端口不会公开。您不需要为 User Manager、Issue Tracker 和 Polyspace Access 服务启用 HTTPS，除非您在不同的节点上安装这些服务，或者启动 admin-docker-agent 二进制文件时使用 --force-exposing-ports 选项。

如果您在同一节点上安装所有服务，并且启动 admin-docker-agent 二进制文件时未使用 --force-exposing-ports 选项，然后在 Nodes 设置中选择了 Enable SSL，则由于端口未公开，您将收到关于 Certificate File 和 Certificate Key File 未被使用的警告消息。如果您不打算公开服务端口，则可以忽略这些警告并继续执行安装中的后续步骤。

打开 Cluster Admin 界面

配置并启动 Cluster Admin 后，打开 Web 浏览器并转至您在启动 admin-docker-agent 二进制文件时在命令行输出中指定的 URL。

使用您在启动 Cluster Admin 代理时获取的初始密码登录。如果这是您首次登录，请按照提示操作。

Cluster Admin Dashboard interface.

请在首次登录后及时更改您的 Cluster Admin 密码。要设置新密码，请点击 Web 界面右上角的 Account 并选择 Change password。除了负责配置和管理 Polyspace Access 服务的用户，请勿向他人提供 Cluster Admin 密码。

在 Cluster Dashboard 上，点击 Configure Apps 以打开 Cluster Settings。在此页面上，您可以：

将用户身份验证配置为使用公司 LDAP 中的用户凭据或使用自定义凭据。请参阅配置 User Manager。
将 Bug 跟踪工具（例如 Jira Software 和 Redmine）与 Polyspace Access 集成。请参阅配置 Issue Tracker。
指定许可证文件的路径以及由 Polyspace Access 数据库、ETL 和 Web 服务器使用的不同文件夹的路径。请参阅配置 Polyspace Access App 服务。

填写所有设置后，请点击 Save，返回到 Cluster Dashboard 并点击 Restart Apps，然后更改才会生效。在点击 Save 之前，请确保 Validate on Save 已启用。

要保存已填写部分内容的设置，请清除 Validate on Save 并点击 Save。

Settings view in the Cluster Admin interface

注意

在 Windows^® 系统上，您指定的所有文件路径都必须指向本地驱动器。

另请参阅

admin-docker-agent