Rancher Desktop

Rancher Desktop是一个开源项目，旨在将Kubernetes和容器管理引入桌面环境。它可以在Windows、macOS和Linux上运行。本README涉及Rancher Desktop的开发。有关Rancher Desktop的用户导向信息，请访问rancherdesktop.io。有关用户导向文档，请访问docs.rancherdesktop.io。

概述

Rancher Desktop是一个主要用TypeScript编写的Electron应用程序。它集成了多种技术，以提供一个统一的应用程序。它包括一个用Go语言编写的命令行工具rdctl。大多数开发活动，如运行开发版本、构建/打包Rancher Desktop、运行单元测试和端到端测试，都通过yarn脚本完成。也有一些例外，比如运行BATS测试。

设置

Windows

在Windows上从源代码构建有两种选择：使用开发虚拟机设置或在现有Windows安装上进行手动开发环境设置。

开发虚拟机设置

1. 下载Microsoft Windows 10开发虚拟机。以下所有步骤都应在该虚拟机中完成。

2. 打开PowerShell提示符（按Windows键 + X并打开Windows PowerShell）。

3. 运行自动设置脚本：

   Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
   iwr -useb 'https://github.com/rancher-sandbox/rancher-desktop/raw/main/scripts/windows-setup.ps1' | iex

4. 关闭特权PowerShell提示符。

5. 确保在.npmrc文件中正确配置了msbuild_path和msvs_version。运行以下命令设置这些属性：

   npm config set msvs_version <visual-studio-版本号>
   npm config set msbuild_path <path/to/MSBuild.exe>
   

   例如，对于Visual Studio 2022：

   npm config set msvs_version 2022
   npm config set msbuild_path "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"
   

   如果在尝试运行npm config set...时收到错误消息，请运行npm config edit，然后添加如下行：

   msvs_version=2022
   msbuild_path=C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe
   

   等号右侧的值不要加引号。不需要引号，有些处理器可能会将它们视为路径的字面部分，从而导致失败。

6. 配置git以处理来自Linux和macOS的文件：

   git config --global --replace-all core.autocrlf false
   git config --global --replace-all core.eol lf
   

如果发现lint:go测试莫名其妙地失败，可能是行尾不正确。

现在你可以克隆仓库并运行yarn了。

手动开发环境设置

1. 在你的机器上安装适用于Linux的Windows子系统（WSL）。如果已安装WSL，请跳过此步骤。
2. 打开PowerShell提示符（按Windows键 + X并打开Windows PowerShell）。
3. 通过iwr -useb get.scoop.sh | iex安装Scoop。
4. 通过scoop install 7zip git go mingw nvm python unzip安装7zip、git、go、mingw、nvm和unzip。 使用nvm list检查node版本。如果未安装node v18或未将其设置为当前版本，请使用nvm install 18安装，并使用nvm use 18.xx.xx将其设置为当前版本。
5. 通过npm install --global yarn安装yarn包管理器。
6. 安装Visual Studio 2017或更高版本。截至撰写本文时，最新版本可在[https://visualstudio.microsoft.com/downloads/]获得；如果链接已更改，可以使用搜索引擎找到。
7. 确保安装了Windows SDK组件。这个Visual Studio文档描述了安装组件的步骤。 还需要选择使用C++的桌面开发工作负载。
8. 配置git以处理来自Linux和macOS的文件：

   git config --global --replace-all core.autocrlf false
   git config --global --replace-all core.eol lf
   

如果发现lint:go测试莫名其妙地失败，可能是行尾不正确。 9. 确保在.npmrc文件中正确配置了msbuild_path和msvs_version。运行以下命令设置这些属性：

npm config set msvs_version <visual-studio-版本号>
npm config set msbuild_path <path/to/MSBuild.exe>

例如，对于Visual Studio 2022：

npm config set msvs_version 2022
npm config set msbuild_path "C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe"

如果在尝试运行npm config set...时收到错误消息，请运行npm config edit，然后添加如下行：

msvs_version=2022
msbuild_path=C:\Program Files (x86)\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin\MSBuild.exe

等号右侧的值不要加引号。不需要引号，有些处理器可能会将它们视为路径的字面部分，从而导致失败。

现在你可以克隆仓库并运行yarn了。

macOS

安装nvm以获取Node.js和npm：

请参阅https://github.com/nvm-sh/nvm#installing-and-updating 并运行curl或wget命令来安装nvm。

请注意，此脚本会将处理nvm的代码添加到配置文件（如~/.bash_profile）中。要在当前shell会话中访问nvm，你需要source该文件。

目前我们使用Node 18构建Rancher Desktop。要安装它，请运行：

nvm install 18.18

接下来，你需要安装yarn包管理器：

npm install --global yarn

如果您还没有安装 go，还需要运行 brew install go。

然后您可以使用以下命令安装依赖：

yarn

⚠️ 在搭载 M1 芯片的 Mac 上工作？

在安装依赖和运行任何 npm 脚本之前，您需要先设置 M1 环境变量：

export M1=1
yarn

如果您之前在没有先设置 M1 的情况下安装了依赖，您需要运行 git clean -fdx 来清理所有缓存的资源，然后在运行 yarn 之前重新下载正确架构的依赖。

Linux

确保您已安装以下内容：

• Node.js v18。**请确保您已安装任何开发包。**例如，在 openSUSE Leap 15.3 上，您需要安装 nodejs18 和 nodejs18-devel。

• yarn classic

• Go 1.21 或更高版本。

• node-gyp 文档中描述的依赖项。这是安装 ffi-napi npm 包所必需的。这些文档提到了"适当的 C/C++ 编译器工具链"。您可以为此安装 gcc 和 g++。

然后您可以使用以下命令安装依赖：

yarn

之后您可以按照下面的描述运行 Rancher Desktop。第一次运行可能会失败 - 如果发生这种情况，请尝试进行出厂重置并重新运行，这种方法已知可以解决此问题。

运行

一旦您安装了依赖，您就可以使用以下命令运行 Rancher Desktop 的开发版本：

yarn dev

测试

要运行单元测试：

yarn test

要运行集成测试：

yarn test:e2e

构建

Rancher 可以在 Windows、macOS 或 Linux 上从源代码构建。 目前不支持交叉编译。要运行构建，请执行：

yarn build
yarn package

构建输出会放在 dist/ 目录中。

使用 Chrome 远程调试器调试构建

Chrome 远程调试器允许您使用 Chrome 开发者工具调试 Electron 应用。您可以使用它访问可能输出到渲染进程开发者控制台的日志消息。这对于在 Rancher Desktop 的生产构建中获取额外的调试信息特别有帮助。

启用远程调试并启动 Rancher Desktop

要启用远程调试，请使用 --remote-debugging-port 参数启动 Rancher Desktop。

在 Linux 上，使用以下命令启动 Rancher Desktop：

rancher-desktop --remote-debugging-port="8315" --remote-allow-origins=http://localhost:8315

在 macOS 上，使用以下命令启动 Rancher Desktop：

/Applications/Rancher\ Desktop.app/Contents/MacOS/Rancher\ Desktop --remote-debugging-port="8315" --remote-allow-origins=http://localhost:8315

在 Windows 上，使用以下命令启动 Rancher Desktop：

cd 'C:\Program Files\Rancher Desktop\'
& '.\Rancher Desktop.exe' --remote-debugging-port="8315" --remote-allow-origins=http://localhost:8315

Rancher Desktop 启动后，打开 Chrome 并导航到 http://localhost:8315/。选择可用的目标以开始远程调试 Rancher Desktop。

远程调试扩展

要远程调试扩展，请按照与远程调试构建相同的过程进行操作。但是，在导航到 http://localhost:8315/ 之前，您需要加载一个扩展。Rancher Desktop 和加载的扩展都应列为可用目标。

使用 GoLand 调试开发环境

以下步骤已在 Linux 上的 GoLand 中测试过，但可能以类似的方式适用于其他 JetBrains IDE。

1. 安装 Node.js 插件（通过 File > Settings > Plugins）

   

2. 转到"运行/调试配置"对话框（通过 Run > Edit Configurations...）

3. 添加一个新的 Node.js 配置，设置如下：

   • 名称：调试配置的名称，例如 rancher desktop
   • Node 解释器：选择您安装的 node 解释器，例如 /usr/bin/node
   • Node 参数：scripts/ts-wrapper.js scripts/dev.ts
   • 工作目录：选择您项目的工作目录，例如 ~/src/rancher-desktop

   

4. 保存配置

5. 现在您可以设置断点并点击"Debug 'rancher desktop'"开始调试

   

开发构建

Windows 和 macOS

每次提交都会触发 GitHub Actions 运行，resulting in application bundles （.exe 和 .dmg 文件）作为构件上传。如果您想测试由构建系统构建的最新版 Rancher Desktop，这可能会很有用。 您可以从已完成的 package 操作的摘要页面下载这些构件。

Linux

与 Windows 和 macOS 类似，Rancher Desktop 的 Linux 构建也是从每次提交中生成的。但在 Linux 上，只有部分过程由 GitHub Actions 完成。 最后一部分由 [Open Build Service][OBS] 完成。 Rancher Desktop 仓库有两个通道："dev"和"stable"。

"stable"是大多数用户使用的通道。这是官方文档中指示用户添加的通道，也是包含从官方发布创建的构建版本的通道。本文我们关注的是"dev"通道：它包含从"main"分支上最新提交以及任何匹配"release-*"格式的分支创建的构建版本。关于如何安装开发仓库，请见下文。

使用"dev"仓库时，了解"dev"仓库中可用的 Rancher Desktop 版本格式非常重要。版本格式如下：

<priority>.<branch>.<commit_time>.<commit>

其中：

"priority"是一个无意义的数字，用于在更新时给予从"main"分支构建的版本优先于从"release-*"分支构建的版本。

"branch"是分支名称；由于包格式的限制，破折号被删除。

"commit_time"是用于构建的提交的 UNIX 时间戳。

"commit"是用于构建的提交的缩短哈希值。

".deb"开发仓库

您可以通过以下步骤添加仓库：

curl -s https://download.opensuse.org/repositories/isv:/Rancher:/dev/deb/Release.key | gpg --dearmor | sudo dd status=none of=/usr/share/keyrings/isv-rancher-dev-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/isv-rancher-dev-archive-keyring.gpg] https://download.opensuse.org/repositories/isv:/Rancher:/dev/deb/ ./' | sudo dd status=none of=/etc/apt/sources.list.d/isv-rancher-dev.list
sudo apt update

您可以通过以下命令查看可用版本：

apt list -a rancher-desktop

找到您想安装的版本后，可以使用以下命令安装：

sudo apt install rancher-desktop=<version>

即使您已经安装了 Rancher Desktop 的某个版本，这种方法也适用。

".rpm"开发仓库

您可以通过以下命令添加仓库：

sudo zypper addrepo https://download.opensuse.org/repositories/isv:/Rancher:/dev/rpm/isv:Rancher:dev.repo
sudo zypper refresh

您可以通过以下命令查看可用版本：

zypper search -s rancher-desktop

最后，使用以下命令安装您想要的版本：

zypper install --oldpackage rancher-desktop=<version>

即使您已经安装了 Rancher Desktop 的某个版本，这种方法也适用。

开发 AppImages

AppImages 没有仓库，但您可以在这里访问最新的开发 AppImage 构建版本。

API

Rancher Desktop 支持有限的基于 HTTP 的 API。API 定义在 pkg/rancher-desktop/assets/specs/command-api.yaml 中，您可以在 go/src/rdctl 的客户端代码中看到如何调用它的示例。

稳定性

API 目前处于第 1 版，但仍被视为内部和实验性的，可能会在没有任何预先通知的情况下进行更改。我们预计在某个时候，对 API 的必要更改将经过警告和弃用通知。

贡献

请参阅贡献文档。

进一步阅读

请查看 docs 目录以获取更多开发者文档。