> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/learn-the-platform/zh/mo-kuai-6-xu-ni-ji/02-recipes-marketplace.md).

# 配方与市场

## 概述

手动从零开始配置每台虚拟机既耗时又容易出错。VergeOS **配方** 通过提供可自定义的黄金镜像模板来解决这一问题，这些模板在标准化 VM 配置的同时，仍允许按实例进行自定义。再结合内置的 **Marketplace 目录**，配方让你能在几分钟内部署可直接投入生产的 VM——从 Ubuntu 服务器到 Windows 评估环境——并且每次都保持一致的配置。

```mermaid
flowchart LR
    subgraph sources["配方来源"]
        direction TB
        MP["Marketplace<br/>(VergeOS 提供)"]
        LOCAL["本地目录<br/>(自定义配方)"]
        REMOTE["远程仓库<br/>(共享配方)"]
    end

    subgraph deploy["部署"]
        direction TB
        Q["回答问题<br/>(CPU、RAM、网络、存储)"]
        AUTO["自动化<br/>(数据库、Cloud-Init)"]
        VM["正在运行的 VM 实例"]
    end

    sources --> Q --> AUTO --> VM
```

一个配方由三个组件组成：

1. **基础 VM** -- 一个通用化的虚拟机，作为黄金镜像（模板）
2. **问题** -- 按部分组织的输入字段，用于收集每个实例的自定义值（核心数、RAM、主机名、网络配置、凭据）
3. **自动化** -- 底层数据库操作以及 cloud-init/Cloudbase-init 脚本，在首次启动时配置 VM

## Marketplace 目录

每个 VergeOS 系统都自带 **Marketplace** -- 一个由 VergeOS 提供的远程仓库，包含预构建的 VM 配方，可立即使用。Marketplace 在安装时自动可用，其目录被设置为 `scope=global`，因此所有租户也都可以访问。

### 访问 Marketplace

1. 导航至 **机器** > **虚拟机** ，位于左侧菜单中。
2. 单击 **新建**.
3. 在 **选择类型** 面板左侧，选择 **Marketplace** （或者选择某个特定目录，如“操作系统 (Marketplace)”或“应用程序 (Marketplace)”）。
4. 从列表中选择一个配方，然后点击 **下一步** 开始回答问题。

### 可用的操作系统配方

Marketplace 包含适用于多种操作系统的配方：

| 类别          | 可用配方                                                                    |
| ----------- | ----------------------------------------------------------------------- |
| **Ubuntu**  | Server 18.04 (Bionic)、20.04 (Focal)、22.04 (Jammy)、24.04 (Noble)——LTS 版本 |
| **RHEL 兼容** | Rocky Linux 8 和 9、AlmaLinux 8 和 9、CentOS 7、CentOS Stream 8              |
| **Debian**  | Debian 10 (Buster)、11 (Bullseye)、12 (Bookworm)、13 (Trixie)              |
| **Fedora**  | Fedora 35、36、37、38                                                      |
| **Amazon**  | Amazon Linux 2 LTS                                                      |
| **Windows** | Windows Server 2019 评估版、2022 评估版、2025 评估版                               |

{% hint style="success" %}
Linux 配方使用 **cloud-init** ，并在预配期间下载预构建的云镜像。Windows 配方使用 **Cloudbase-init** ，配合评估版 ISO 和自动化的无人值守安装。这两种方式都能生成一个完全配置好的、可启动的 VM，而无需手动安装操作系统。
{% endhint %}

## 使用 Marketplace 配方

从 Marketplace 配方部署 VM 遵循引导式问答流程。以下是使用 Ubuntu Server 配方的典型演示：

### 分步演示

1. **导航到** 更改为 **机器** > **虚拟机** > **新建**.
2. **选择** Marketplace 目录中的该配方（例如“Ubuntu Server 24.04 (Noble Numbat)”）。
3. **回答问题** ，这些问题按各个部分呈现：

#### VM 实例设置

| 可变                     | 显示名称                | 说明                            |
| ---------------------- | ------------------- | ----------------------------- |
| `YB_CPU_CORES`         | 核心数                 | 虚拟 CPU 核心数                    |
| `YB_RAM`               | RAM                 | 内存分配（MB）                      |
| `YB_HOSTNAME`          | 主机名                 | 客户机操作系统主机名                    |
| `SELECT_CREATE_UEFI`   | 启用 UEFI             | UEFI 启动模式（推荐）                 |
| `YB_DISABLE_CLOUDINIT` | 在首次启动后禁用 Cloud-init | 选项： `true`, `false`，或 `purge` |

#### 网络设置

| 可变                             | 显示名称      | 说明                  |
| ------------------------------ | --------- | ------------------- |
| `YB_IP_ADDR_TYPE`              | IP 地址类型   | `dhcp` 或 `static`   |
| `YB_NIC_ETH0_EXTERNAL_GATEWAY` | 网络        | 主网卡的目标网络            |
| `YB_NIC_ETH0_IP_ADDR`          | IP 地址     | 静态 IP（如果选择了 static） |
| `YB_NIC_ETH0_CIDR`             | 子网掩码 CIDR | 例如， `/24`           |
| `YB_NIC_ETH0_GW`               | 默认网关      | 网关 IP 地址            |
| `YB_NIC_ETH0_NS`               | DNS 服务器   | 以逗号分隔的 DNS 服务器      |

#### 存储设置

| 可变                 | 显示名称     | 说明            |
| ------------------ | -------- | ------------- |
| `YB_DRIVE_OS_SIZE` | 操作系统磁盘大小 | 以 GB 为单位的磁盘大小 |
| `SELECT_OS_TIER`   | 操作系统磁盘层级 | 首选的 vSAN 存储层级 |

#### 用户帐户

| 可变            | 显示名称 | 说明       |
| ------------- | ---- | -------- |
| `YB_USER`     | 用户名  | 初始管理员用户名 |
| `YB_PASSWORD` | 密码   | 初始管理员密码  |

4. **点击提交** 以创建 VM。
5. 配方自动化开始运行——创建磁盘、下载云镜像、配置 cloud-init 文件，以及设置机器类型。
6. **启动** 该 VM。cloud-init 会在首次启动时运行，以应用你的配置（主机名、用户、网络、软件包）。

## 配方问题与变量

配方问题是使配方可自定义的基础构件。每个问题都会捕获一个值，该值会被存储为变量，并可在 cloud-init 脚本、数据库操作或 VM 配置中引用。

### 问题字段

| 字段         | 用途                                                                                                                                                                                  |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **部分**     | 将输入表单上的相关问题分组（例如“实例设置”、“网络”）                                                                                                                                                        |
| **名称**     | 脚本中引用的变量名（仅限字母数字，无空格）                                                                                                                                                               |
| **类型**     | 数据的收集方式；常见类型包括 String、Number、Password、Boolean、List、Hidden、RAM、Disk Size、Network、Cluster、Database Create/Edit/Find、Hostname、Script、Textarea、Virtual IP、Timestamp、Row、Field 和 Seconds |
| **顺序 ID**  | 在该部分中的显示顺序                                                                                                                                                                          |
| **显示**     | 在输入表单上显示给用户的标签                                                                                                                                                                      |
| **默认值**    | 预填答案                                                                                                                                                                                |
| **正则验证**   | 用于验证输入的正则表达式                                                                                                                                                                        |
| **占位符文本**  | 灰色提示文本，显示预期格式                                                                                                                                                                       |
| **工具提示文本** | 悬停时弹出的帮助信息                                                                                                                                                                          |
| **备注文本**   | 显示在输入字段下方的帮助文本                                                                                                                                                                      |
| **变更时**    | 用于动态显示/隐藏其他问题的 JavaScript                                                                                                                                                           |

### 自动生成的问题

当你从基础 VM 创建配方时，VergeOS 会自动为该 VM 的每个磁盘生成问题（例如， `YB_DRIVE_1_SIZE`, `YB_DRIVE_2_SERIAL`, `YB_DRIVE_3_NONPERSISTENT`）。某些自动生成的问题默认处于禁用状态——如有需要，可从问题列表中启用它们。

## 数据库自动化

在每个 Marketplace 配方的背后，一组 **数据库类型问题** （Database Create、Database Edit 和 Database Find）会在 VM 预配期间执行自动化操作。这些问题会直接与 VergeOS 数据库 API 交互，以创建资源、下载镜像并配置硬件——无需用户进行任何手动干预。

### 常见数据库操作

| 可变                        | 操作                            |
| ------------------------- | ----------------------------- |
| `CREATE_OS_DRIVE`         | 使用指定大小和层级创建 OS 虚拟磁盘           |
| `YB_DOWNLOAD_WINDOWS_ISO` | 从指定 URL 下载 Windows ISO        |
| `YB_DOWNLOAD_VIRTIO`      | 为 Windows 客户机下载 VirtIO 驱动 ISO |
| `YB_CREATE_VIRTIO_CD_DL`  | 创建虚拟 CD-ROM 并挂载 VirtIO ISO    |
| `GET_CLUSTER_CPU`         | 查询集群可用的 CPU 型号信息              |
| `CHANGE_CLUSTER_CPU`      | 将 VM 的 CPU 类型设置为与集群匹配         |
| `EDIT_MACHINE_TYPE`       | 在创建后调整 VM 机器类型（例如 Q35）        |

这些操作使用与管理员和自动化工具相同的 REST API。配方作者可以添加自定义 Database 问题，以自动化 VergeOS API 暴露的任何操作——创建网络、注册 DNS 记录、设置防火墙规则等等。

{% hint style="info" %}
**来自 VMware 或 Nutanix？**

一个 VergeOS 配方将模板、按实例自定义表单和预配自动化——cloud-init/Cloudbase-init、磁盘创建、API 操作——打包在一个自包含的方案中，因此你无需将单独的模板、自定义、镜像管理和编排工具拼接起来即可预配 VM。
{% endhint %}

## Cloud-Init 集成（Linux）

VergeOS 与 **cloud-init**集成，后者是用于在 Linux VM 首次启动时进行自定义的行业标准工具。配方利用 cloud-init 应用主机名、用户帐户、网络配置、软件包安装和自定义脚本——全部由配方问题变量驱动。

### 工作方式

1. 该 VM 的 **Cloud-init 数据源** 字段设置为 **Config Drive v2**.
2. VergeOS 创建一个包含两个文件的虚拟磁盘：
   * **`user_data`** -- 在首次启动时执行的脚本和配置指令
   * **`meta_data.json`** -- 实例元数据（主机名、UUID、可用区）
3. 配方问题变量会使用模板语法插入到这些文件中。
4. 在首次启动时，cloud-init 会读取 Config Drive 并应用配置。

{% hint style="info" %}
该 **Cloud-init 数据源** 字段提供多个选项。Marketplace 配方使用 **Config Drive v2** （标准 cloud-init 数据源），但 VergeOS 也支持：

* **无** — 为该 VM 禁用 Cloud-init。
* **NoCloud** — 一种标准的 cloud-init 数据源，旨在用于配置一个 VM **无需网络连接**.

两者都 **Config Drive v2** 以及 **NoCloud** 提供相同的 `user_data` / `meta_data` 文件给客户机；当客户机在首次启动时没有网络时，请选择 **NoCloud** 。
{% endhint %}

### 模板变量

配方变量通过 `${VARIABLE_NAME}` 语法注入到 cloud-init 文件中：

```json
{
  "availability_zone": "${YB_CLUSTER_NAME}",
  "name": "${YB_NAME}",
  "uuid": "${YB_UUID}",
  "hostname": "${YB_NAME}",
  "yb": ${$ALL_VARIABLES}
}
```

该 `${$ALL_VARIABLES}` 令牌会展开为包含每个问题变量的 JSON 对象，使所有配方答案都可供 cloud-init 脚本使用。 `${$...}` 这个 `${...}` 语法并非笔误：替换引擎会扫描标准的 `$ALL_VARIABLES` 语法，而 `$`是一个特殊变量名（带有一个字面上的前导

### 用户数据格式

该 `user_data` 文件支持多种脚本格式，由第一行决定：

| 格式                     | 首行              | 使用场景                                          |
| ---------------------- | --------------- | --------------------------------------------- |
| **Cloud-config（YAML）** | `#cloud-config` | 声明式配置（用户、软件包、文件、runcmd）                       |
| **Shell 脚本**           | `#!/bin/bash`   | 任意 shell 命令                                   |
| **PowerShell**         | `#ps1`          | PowerShell 脚本（主要用于 Windows 上的 Cloudbase-init） |
| **Batch**              | `rem cmd`       | Windows 批处理脚本（Cloudbase-init）                 |

上面的首行分发行为是标准的 cloud-init/Cloudbase-init 行为，而不是 VergeOS 特有的约定——VergeOS 只是通过 `user_data` Config Drive v2 提供该

#### 示例：Cloud-Config YAML

```yaml
#cloud-config
hostname: ${YB_HOSTNAME}
users:
  - name: ${YB_USER}
    sudo: ALL=(ALL) NOPASSWD:ALL
    shell: /bin/bash
    lock_passwd: false
    passwd: ${YB_PASSWORD_HASH}
packages:
  - qemu-guest-agent
  - curl
runcmd:
  - systemctl enable --now qemu-guest-agent
```

### 在线云镜像

Linux 配方可以直接从发行版镜像站下载预构建的云镜像。这通过隐藏的配方问题进行配置：

* **`OS_DL_URL`** （类型：Hidden）——在本地下载并缓存镜像（例如， `https://cloud-images.ubuntu.com/releases/noble/release/ubuntu-24.04-server-cloudimg-amd64-disk-kvm.img`)
* **`OS_URL`** （类型：Hidden）——直接通过网络流式传输镜像，而不进行本地缓存

这些云镜像预装了 cloud-init，因此配方只需要提供用于自定义的 `user_data` 以及 `meta_data.json` 文件。

## Cloudbase-Init（Windows）

对于 Windows VM，VergeOS 使用 **Cloudbase-init** ——即 cloud-init 的 Windows 等价工具。Cloudbase-init 读取相同的 Config Drive v2 数据源，并在首次启动期间执行 PowerShell 或批处理脚本。

### 设置过程

1. 在 Windows 模板 VM 中安装 [Cloudbase-init 客户端](https://cloudbase.it/cloudbase-init/#download) 。
2. 使用 Cloudbase-init 的 unattend 选项对 VM 进行 Sysprep。
3. 设置 VM 的 **Cloud-init 数据源** 更改为 **Config Drive v2**.
4. 为 Windows 特定选项（许可证密钥、RDP、VirtIO 驱动）创建配方问题。

### Windows 配方自动化

Windows Marketplace 配方会自动化整个预配链：

1. 通过 Database 问题下载 Windows 评估版 ISO
2. 下载 VirtIO 驱动 ISO
3. 创建虚拟 CD-ROM 驱动器并挂载两个 ISO
4. 配置机器类型和 UEFI 设置
5. 在首次启动时，Cloudbase-init 会应用主机名、管理员凭据、RDP 设置和网络配置

{% hint style="warning" %}
在 cloud-init 或 Cloudbase-init 完成其工作后， **从 VM 中移除 cloud-init 文件** ，尤其是如果其中任何脚本包含密码或其他敏感信息。
{% endhint %}

## 创建自定义配方

当 Marketplace 配方无法满足你的需求时，你可以从任何现有 VM 创建自定义配方。

### 工作流程

1. **构建基础 VM** -- 安装你希望作为黄金镜像的操作系统、应用程序和配置。将 VM 通用化（移除机器特定数据，安装 cloud-init 或 Cloudbase-init）。
2. **创建配方** -- 导航到 **虚拟机** > **新建 VM 配方**.
   * 如果不存在本地目录，你会先被提示创建一个。
3. **配置配方字段：**

| 字段               | 说明                                    |
| ---------------- | ------------------------------------- |
| **名称**           | 配方的描述性名称                              |
| **说明**           | 文档和指南                                 |
| **图标**           | 用于视觉识别的 Font Awesome 图标               |
| **目录**           | 配方的组织容器                               |
| **虚拟机**          | 基础模板 VM                               |
| **版本**           | 从 1.0.0 开始，变更时自动递增（1.0.0-1、1.0.0-2 等） |
| **使用资产编号作为问题名称** | 按资产编号而非序号命名驱动器/NIC 问题                 |
| **版本依赖**         | 配方运行所需的 VergeOS 功能                    |

4. **定义问题** -- 添加部分和问题以收集每个实例的输入。配置验证、默认值、工具提示以及条件显示/隐藏逻辑。
5. **配置 cloud-init 文件** -- 编写 `user_data` 以及 `meta_data.json` 引用你的问题变量的模板。
6. **模拟配方** -- 点击 **模拟配方** 从配方仪表板中测试输入表单、验证字段，并预览生成的答案文件。
7. **发布** -- 该配方会在其目录中变为可用，以用于创建新的虚拟机。

### 修改并重新发布

当你更改配方时，必须 **重新发布** ，更改才会生效。配方仪表板会显示一条通知，其中包含一个 **重新发布** 链接。重新发布后，会通知远程系统和租户有可用更新。

### 配方实例

由配方创建的虚拟机是该配方的一个 **实例** ，直到它被删除或分离。你可以从配方仪表板查看所有实例。若配方有关联实例，则无法删除该配方。

{% hint style="info" %}
**已记录的限制**

VergeOS 系统最多支持 **1,000 个配方** 以及 **50,000 个配方实例** 总计，最多可有 **每个配方 10,000 条配方日志** （在达到 100 条时自动清理，并在 7 天后过期）。这些上限远高于典型用量，但如果你计划大规模、由配方驱动的配置，这一点值得了解。
{% endhint %}

## 配方交换

VergeOS 支持通过仓库和目录架构在系统和租户之间共享配方。

```mermaid
flowchart TD
    REPO["仓库"] --> CAT1["目录 1<br/>(Linux 虚拟机)"]
    REPO --> CAT2["目录 2<br/>(Windows 虚拟机)"]
    REPO --> CAT3["目录 3<br/>(应用程序)"]
    CAT1 --> R1["Ubuntu 配方"]
    CAT1 --> R2["Rocky 配方"]
    CAT2 --> R3["Win 2022 配方"]
    CAT3 --> R4["数据库配方"]
    CAT3 --> R5["Web 服务器配方"]
```

### 与租户共享

1. 将目录的 **发布范围** 更改为 **租户** （或 **全局** 用于外部访问）。
2. 在租户界面中，导航到 **服务提供商** 仓库并点击 **刷新**.
3. 双击该目录以浏览配方。
4. 选择配方并点击 **下载/更新** 以使其在本地可用。

### 与远程系统共享

1. 创建一个 **API 用户** ，并为共享系统上的该目录授予列表和读取权限。
2. 在接收系统上，创建一个 **远程仓库** ，并使用 API 用户凭据指向共享系统的 URL。
3. 单击 **刷新** 以拉取目录列表。下载配方供本地使用。

### 发布范围

| 范围     | 可见性               |
| ------ | ----------------- |
| **私有** | 仅本地 VergeOS 云     |
| **无**  | 已禁用——在任何地方都不可用    |
| **租户** | 本地云及其直接租户         |
| **全局** | 本地云、租户和远程系统（使用凭据） |

## 最佳实践

### 从 Marketplace 开始

将 Marketplace 配方作为起点。将它们克隆到本地目录并进行自定义，而不是从头构建——这可以节省时间，并确保你继承经过测试的配置。

### 在发布前进行模拟

在将配方提供给用户之前，务必先进行模拟。验证字段校验是否有效、条件逻辑是否正常工作，以及生成的 cloud-init 文件是否包含预期值。

### 为你的配方进行版本管理

使用有意义的版本号，并在进行重大更改时更新它们。远程系统和租户会收到更新通知，因此清晰的版本号有助于跟踪哪些内容发生了变化。

### 清理敏感数据

在首次启动后移除 cloud-init 文件，尤其是当它们包含密码或凭据时。可以考虑使用 `YB_DISABLE_CLOUDINIT` 选项，在初始配置后清除 cloud-init 数据。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/learn-the-platform/zh/mo-kuai-6-xu-ni-ji/02-recipes-marketplace.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.