企业官网建设流程全解析

• 桌面应用
• 云原生
• 容器编排

导读

Rancher Desktop 是一款把 Kubernetes 与容器管理能力带到桌面端的开源应用，支持 Windows、macOS 与 Linux 三大平台。本文以仓库根目录 README.md 为核心脉络，面向希望从源码构建、运行、调试、测试并理解其发布渠道与内置 API 的开发者，系统梳理开发环境搭建、yarn开发工作流、Chrome 远程调试、GoLand 调试、Linux 开发仓库安装方法以及rdctl与command-api.yaml定义的内置 HTTP API。读完本文，你将具备完整的 Rancher Desktop 二次开发与自建构建能力。

技术栈与工程概览

Rancher Desktop 本质上是一个Electron 应用，主体代码由TypeScript编写，同时捆绑了多种技术栈以形成单一连贯的桌面应用：

• Electron 主进程与渲染进程：仓库根目录的 package.json 中声明main指向dist/app/background.js，渲染层基于 Vue 3 + Vuex + Vue Router（见 pkg/rancher-desktop/vue.config.mjs 与 pkg/rancher-desktop/entry）。
• 命令行工具rdctl：使用 Go 编写，源码位于 src/go/rdctl，负责与运行中的应用通信、执行快照、扩展管理、工厂重置等操作。
• 辅助 Go 组件：仓库还包含 guestagent、wsl-helper、nerdctl-stub、networking、startup-profile 等多个 Go 模块（见 src/go），服务于 WSL 集成、VM 内代理与命令行桩等能力。
• yarn作为统一开发入口：绝大多数开发活动——运行开发构建、编译打包、单元测试、端到端测试——都通过yarn脚本完成，只有少数例外（如 BATS 测试需要直接调用bats-core的二进制）。

以当前仓库 package.json 为准，其要求的运行环境为 Node^22.14.0，包管理器为yarn@4.18.0；常用脚本包括dev、build、package、sign、test、test:e2e以及一整套lint系列。

开发环境搭建

Windows：两条构建路径

Windows 上从源码构建有两种可选方式：开发虚拟机方案（一次性自动化配置）与手动环境方案（在现有 Windows 安装上进行）。

开发虚拟机方案（Development VM Setup）

1. 下载 Microsoft Windows 10 开发虚拟机镜像，后续所有步骤都在该虚拟机内完成。

2. 打开 PowerShell（Windows 键 +X，选择Windows PowerShell）。

3. 运行仓库中的自动化安装脚本 scripts/windows-setup.ps1：

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

   该脚本内部以并行 Job 的方式完成三件事：通过 Visual Studio Installer 补装 VC++ 工具链组件并把 MSBuild 路径写入~/.npmrc；通过 Scoop 安装7zip git go mingw nvm python unzip并安装 Node、全局 yarn；若系统尚无 WSL 则调用 scripts/windows/install-wsl.ps1 等辅助脚本安装 WSL（此步需要重启）。脚本支持-SkipVisualStudio、-SkipTools、-SkipWSL三个开关来跳过对应阶段。

4. 关闭特权 PowerShell 窗口。

5. 确保.npmrc中的msbuild_path与msvs_version配置正确，可通过npm config命令设置：

   npm config set msvs_version <visual-studio-version-number> 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测试莫名失败，很可能是行尾不正确所致（Go 源文件混入 CRLF 后格式化与 lint 均会异常）。

完成以上步骤后即可克隆仓库并运行yarn。

手动开发环境方案（Manual Development Environment Setup）

1. 安装 Windows Subsystem for Linux（WSL），若已安装可跳过。
2. 打开 PowerShell（Windows 键 +X→Windows PowerShell）。
3. 安装 Scoop 包管理器（iwr -useb get.scoop.sh | iex）。
4. 通过 Scoop 安装工具链：scoop install 7zip git go mingw nvm python unzip。用nvm list检查 Node 版本；若未安装或未启用 v22，执行nvm install 22并nvm use 22.xx.xx切换到对应版本。
5. 全局安装 yarn：npm install --global yarn。
6. 安装 Visual Studio 2017 或更高版本。
7. 确保已安装Windows SDK组件，并勾选Desktop development with C++工作负载——这是node-gyp编译原生模块（如仓库中使用的ffi-napi、native-reg等）所必需的。
8. 配置 git 行尾（与虚拟机方案相同，含lint:go的注意事项）。
9. 配置.npmrc中的msbuild_path与msvs_version，方法与上文一致。

macOS

macOS 侧的核心步骤是安装 nvm 以获取 Node.js 与 npm：

1. 按 nvm 官方指引执行安装脚本（curl 或 wget）。注意该脚本会把 nvm 相关代码追加到 profile 文件（如~/.bash_profile），若要在当前 shell 会话使用 nvm，需要先source该文件。

2. 安装构建所用 Node 版本（当前仓库基于 Node 22 构建）：

   nvm install 22.14

3. 全局安装 yarn：npm install --global yarn。

4. 若未安装 Go，执行brew install go（README 要求 Go 1.22 或更高）。

5. 安装依赖并启动：

   yarn

Apple Silicon（M1）用户必读：在安装依赖及运行任何 npm 脚本之前，必须先设置M1环境变量，否则原生依赖会按错误架构下载：

export M1=1 yarn

若此前已在不设置M1的情况下安装过依赖，应先用git clean -fdx清理缓存的构建产物，再重新运行yarn，确保以正确架构重新下载。

Linux

Linux 上需要确保以下依赖齐备：

• Node.js v22，且务必安装对应的开发包。例如 openSUSE Leap 15.6 上需要安装nodejs22与nodejs22-devel（缺失开发头文件会导致原生模块编译失败）。
• yarn classic（经典版 yarn）。
• Go 1.22 或更高版本。
• 满足node-gyp文档描述的依赖要求，即“合适的 C/C++ 编译器工具链”——安装ffi-napi等原生 npm 包时需要，可通过安装gcc和g++满足。

依赖安装完成后执行：

yarn

随后即可按下一节方式运行。Linux 上首次运行可能失败——此时可尝试执行一次工厂重置后再运行，已知能解决该问题（工厂重置的开发者文档见 docs/development/factory-reset.md，其中说明 UI 触发rdctl reset --factory时会把标准输出写入TMP/rdctl-stdout.txt，以便在开发期排查）。

运行开发版本

依赖安装完毕后，在仓库根目录执行：

yarn dev

该命令实际执行的是node scripts/ts-wrapper.js scripts/dev.ts（见 package.json 的dev脚本）。从 scripts/dev.ts 的实现可以看到其内部工作流：

• 主进程：先经buildUtils.buildMain()编译主进程代码，再以node_modules/electron/dist下的 Electron 可执行文件拉起应用；若已有其他实例运行，主进程会以退出码201结束并在控制台提示。
• 渲染进程：先编译 preload 脚本，然后通过@vue/cli-service serve在localhost:8888启动开发服务器（rendererPort = 8888），同时注入RD_DOCS_URL、RD_VERSION等环境变量；脚本会轮询该端口直至渲染进程就绪。
• 命令行中传入的--inspect参数会被透传给 Electron 主进程（可用于后续调试）。

测试体系

仓库的测试分为单元测试与端到端测试两类，均可通过 yarn 触发：

yarn test

test脚本会先执行 lint（lint:nofix，涵盖 TypeScript、Go 与拼写检查），再运行全部单元测试。从 package.json 可见单元测试由多个子任务组成：

• test:unit:jest：TypeScript 单元测试（Jest + jsdom 环境），覆盖 backend、components、config、integrations、main 等模块的__tests__目录；
• test:unit:typecheck：基于tsconfig.jest.json的类型检查；
• test:unit:nerdctl-stub、test:unit:rdctl、test:unit:wsl-helper、test:unit:guestagent、test:unit:i18n-report：分别对 src/go/nerdctl-stub、src/go/rdctl、src/go/wsl-helper、src/go/guestagent、src/go/i18n-report 执行go test ./...；
• test:extra:api-schema：调用 scripts/check-api-schema.ts 校验 API schema 与生成代码的一致性。

端到端测试：

yarn test:e2e

该命令调用 scripts/e2e.ts，基于 Playwright 驱动真实应用运行 e2e 目录下的 spec 文件（如main.e2e.spec.ts、rdctl.e2e.spec.ts、preferences.e2e.spec.ts等），并通过scripts/ts-wrapper.js包装执行。

除yarn体系外，BATS 测试是文档明确点名的例外：BATS 是面向 Bash 脚本的测试框架，运行前需先执行git submodule update --init初始化 bats 目录下的子模块，且 Windows 上必须在 WSL 发行版内部执行（仓库克隆在 Win32 时可通过/mnt/c访问）。运行方式为直接调用 bats-core 二进制：

cd bats ./bats-core/bin/bats tests/registry/creds.bats # 运行单个测试集 ./bats-core/bin/bats tests/*/ # 运行全部 BATS 测试

还可通过环境变量指定 Rancher Desktop 配置，例如RD_CONTAINER_RUNTIME=moby RD_USE_IMAGE_ALLOW_LIST=false。详细说明见 bats/README.md。

构建与打包

Rancher Desktop 支持在 Windows、macOS、Linux 上从源码构建，目前不支持交叉编译（即在某一平台只能构建该平台的产物）。执行：

yarn build yarn package

build对应 scripts/build.ts，package对应 scripts/package.ts（其背后使用 electron-builder，配置见 packaging/electron-builder.yml 与 packaging/linux 下的 AppImage、Flatpak、RPM spec 等文件）。构建输出位于dist/目录。

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

Chrome 远程调试器允许用 Chrome DevTools 调试 Electron 应用，对排查生产构建中渲染进程开发者控制台的日志尤其有用。

启动带远程调试的 Rancher Desktop：以--remote-debugging-port参数启动，并建议同时携带--remote-allow-origins（Chrome 对远程调试来源的限制）：

Linux：

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

macOS：

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

Windows（PowerShell）：

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

应用启动后，打开 Chrome 访问http://localhost:8315/，选择列出的目标即可开始远程调试。

远程调试扩展：流程与调试构建相同，但需先加载一个扩展再访问http://localhost:8315/——此时 Rancher Desktop 与被加载的扩展会同时出现在可调试目标列表中。扩展在应用内的加载与调试能力由 pkg/rancher-desktop/main/extensions 与 pkg/rancher-desktop/preload/extensions.ts 提供支撑。

使用 GoLand 调试开发环境

以下步骤已在 Linux 上的 GoLand 验证，其他 JetBrains IDE 可能以类似方式工作：

1. 通过File > Settings > Plugins安装 Node.js 插件。
2. 打开 Run/Debug Configurations 对话框（Run > Edit Configurations...）。
3. 新建一个 Node.js 配置，参数如下：
   • Name：调试配置名称，如rancher desktop；
   • Node interpreter：选择已安装的 node，如/usr/bin/node；
   • Node parameters：scripts/ts-wrapper.js scripts/dev.ts（即与yarn dev等价，可直接断点调试启动流程）；
   • Working directory：选择项目工作目录，如~/src/rancher-desktop。
4. 保存配置。
5. 设置断点后点击 Debug，即可开始调试。

开发构建发布渠道

Windows 与 macOS

每次提交都会触发 GitHub Actions 流水线，生成应用安装包（.exe与.dmg）并作为构建产物上传。如需测试构建系统产出的最新版本，可从对应packageaction 的 Summary 页面下载这些 artifacts。

Linux：OBS 开发仓库

Linux 构建与 Windows/macOS 类似，但只有部分流程由 GitHub Actions 完成，最终打包交给Open Build Service（OBS）。Rancher Desktop 仓库提供两个频道：

• stable：绝大多数用户使用的频道，包含从官方发布版本构建的产物；
• dev：开发频道，包含从main分支最新提交以及所有符合release-*模式的分支构建的产物。

使用dev仓库前，需要理解其版本号格式：

<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>

.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>

同样支持在已安装旧版本的情况下直接覆盖安装。

开发版 AppImage

AppImage 没有独立仓库，可直接访问 OBS 上isv:/Rancher:/dev/AppImage目录中的最新开发版构建。完整的 Linux 发布流程细节可进一步参考 docs/development/linux-release-process.md 与 docs/development/obs.md。

内置 HTTP API 与 rdctl

Rancher Desktop 提供一个受限的 HTTP API。API 规范定义在 pkg/rancher-desktop/assets/specs/command-api.yaml，客户端调用示例可见 src/go/rdctl 的源码。

从 command-api.yaml 可以看到 API 的核心形态：

• 根路径GET /返回全部端点列表；GET /v0返回版本 0 端点（当前为空）；GET /v1返回版本 1 端点列表；GET /v1/about说明各端点不保证向前兼容。
• 诊断类：GET /v1/diagnostic_categories返回 Diagnostics 组件的分类名列表；GET /v1/diagnostic_checks（可带category、checkID查询参数）返回检查项，POST同路径则执行全部诊断检查；GET /v1/diagnostic_ids按分类返回检查 ID 列表，分类不存在时返回 404。
• 扩展类：GET /v1/extensions列出已安装的 RDX 扩展（扩展管理器未就绪时返回 503）；POST /v1/extensions/install与POST /v1/extensions/uninstall通过id查询参数安装/卸载扩展，响应码 201/204/400/422/503 分别表示成功、已是目标状态、参数错误、操作失败与内部错误。
• 重置类：PUT /v1/factory_reset以 JSON body（含keepSystemImages布尔字段）触发工厂重置，返回 202 表示正在执行；PUT /v1/k8s_reset通过mode字段（fast或wipe）重置 Kubernetes。
• 端口转发类：POST /v1/port_forwarding以 JSON body（namespace、service等字段）创建端口转发。

稳定性说明

API 当前处于version 1，但仍被视为内部、实验性接口，可能在不提前通知的情况下变更；未来预期必要的 API 改动会走警告与弃用流程。因此，任何基于该 API 的自动化脚本都应做好版本适配与异常兜底。

rdctl 命令行工具

rdctl是伴随应用分发的 Go 命令行工具。从 src/go/rdctl/cmd 的源码结构可以看到其命令族覆盖了 API 之外的大量运维能力：

• 配置与信息：listSettings、set、info、version、paths、enum；
• 生命周期：start、shutdown、reset、factoryReset、internalProcess（及对应的 wait/kill）；
• 快照：snapshot系列（snapshotCreate、snapshotList、snapshotRestore、snapshotDelete、snapshotUnlock），与 UI 的快照功能及 pkg/rancher-desktop/main/snapshots 相互呼应；
• 扩展：extension、extensionList、extensionInstall、extensionUninstall；
• 其他：api、setup、shell、createProfile。

进一步阅读

仓库内的开发者文档集中在 docs/development 目录，包括：

• factory-reset.md：工厂重置的行为细节与日志位置；
• features.md：功能追踪清单；
• obs.md：OBS 使用技巧；
• linux-release-process.md：Linux 发布流程；
• release-checklist.md：发布检查清单；
• signing.md：发布签名；
• env.md：环境相关说明。

贡献指引见 CONTRIBUTING.md。若希望从 UI 层深入了解应用能力，可浏览 pkg/rancher-desktop/pages 与 pkg/rancher-desktop/components；若关注测试用例的组织方式，可参考 e2e 与 bats/tests 两个目录。

• 桌面应用
• 云原生
• 容器编排