> 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-7-duo-zu-hu/03-tenant-recipes.md).

# 租户配方

使用可复用的租户配方模板自动化完整 VDC 部署，包括系统问题、自定义问题、配方交换以及真实世界的 CSP 示例。

## 什么是租户配方？

租户配方可将手动配置的租户转换为 **可重复使用的一键部署模板**。单个租户配方可通过一次表单提交自动创建完整的虚拟数据中心，包括租户设置、网络配置、防火墙规则、包含的虚拟机、随机生成的凭据、DNS/DHCP 注册以及电子邮件通知。

```mermaid
flowchart LR
    BASE["基础租户<br/>（已关机）"] --> RECIPE["租户配方<br/>+ 问题"]
    RECIPE --> I1["租户实例 A"]
    RECIPE --> I2["租户实例 B"]
    RECIPE --> I3["租户实例 C"]

    style BASE fill:#fff3e0,stroke:#e65100
    style RECIPE fill:#e8f5e9,stroke:#2e7d32
    style I1 fill:#e3f2fd,stroke:#1565c0
    style I2 fill:#e3f2fd,stroke:#1565c0
    style I3 fill:#e3f2fd,stroke:#1565c0
```

租户向导（上一页已介绍）可引导您完成一次性的手动配置，而配方则会 **将其代码化** 该配置，使其能够通过每个实例的自定义设置重复数百次。

### 为什么使用租户配方？

### 快速部署

将租户预配从数小时的手动配置缩短至数分钟的自动部署。

### 一致性与合规性

每个租户实例都遵循相同的黄金镜像基线——网络、防火墙规则、虚拟机和策略完全一致。

### 减少人为错误

自动化消除了在重复手动设置过程中容易出现的配置错误。

### 启用自助服务

配合 API，配方可为面向客户的门户提供支持，让最终用户自行预配其 VDC。

## 准备基础租户

每个租户配方都始于一个 **基础租户** ，它作为模板。此租户必须：

1. **已关机** ——配方系统会捕获租户状态，因此它不得处于运行状态
2. **专用于配方** ——不要将生产租户用作基础。如果想基于现有租户创建配方，请先克隆它，并移除客户特定数据（密码、用户名、客户文件）
3. **已完全配置** ——包含应在每个实例中出现的所有网络、虚拟机、防火墙规则、DHCP/DNS 设置及其他任何配置

将基础租户视为整个数据中心的 **黄金镜像** ，而不仅仅是单个虚拟机的镜像。

## 创建租户配方

### 分步流程

1. 使用所有所需设置、网络和虚拟机构建并配置基础租户
2. 关闭基础租户
3. 导航到 **存储库 > 租户配方** 在 VergeOS UI 中
4. 点击 **新建** 位于左侧菜单中
5. 配置配方字段（见下文）
6. 点击 **提交** 以保存——随即打开配方仪表板以进行问题自定义

### 配方字段

| 字段            | 描述                  | 说明                                                                                                 |
| ------------- | ------------------- | -------------------------------------------------------------------------------------------------- |
| **名称**        | 配方的描述性名称            | 当有多个配方可用时，帮助用户找到正确的配方                                                                              |
| **描述**        | 配方的可选文档             | 适合放置使用指南、预期用途和合规性说明                                                                                |
| **图标**        | 可选的 Font Awesome 图标 | 用于区分配方类型的视觉标识符（例如， `fa-cloud`, `fa-database`)                                                      |
| **目录**        | 用于存储配方的目录           | 必须是本地存储库中的目录——不能直接在远程/Marketplace 存储库中创建配方。请参阅 [配方交换](#recipe-exchange-sharing-between-systems) 下文 |
| **租户**        | 用作模板的基础租户           | 必须已关机                                                                                              |
| **版本**        | 自动递增的版本号            | 起始于 `1.0.0`，递增至 `1.0.0-1`, `1.0.0-2`，等等。可手动设置为 `2.0.0` 用于重大变更                                      |
| **保留 SSL 证书** | 将 SSL 证书从基础租户复制到实例  | 当基础租户预装了证书时启用                                                                                      |
| **版本依赖关系**    | VergeOS 功能要求        | 防止远程系统使用其无法支持的配方                                                                                   |

## 配方问题

问题是租户配方的核心。它们从操作员（或 VergeOS 数据库）收集每个实例的输入，并在创建过程中将这些值注入新租户。

创建租户配方时，VergeOS 会 **自动生成系统问题** ，并按章节组织。许多系统问题默认处于禁用状态，如有需要必须明确启用。系统问题不能删除，只能启用或禁用。

### 问题字段

每个问题——无论系统问题还是自定义问题——均通过以下字段配置：

| 字段          | 用途                              |
| ----------- | ------------------------------- |
| **章节**      | 在输入表单中对问题分组（部分自动创建，也可添加自定义章节）   |
| **名称**      | 脚本中引用的变量名称——仅限字母数字，不含空格或特殊字符    |
| **类型**      | 数据收集方式——用户输入字段、数据库查找、隐藏值等。      |
| **排序 ID**   | 章节内的显示顺序                        |
| **显示标签**    | 用户输入表单上显示的标签                    |
| **默认值**     | 预先填充的答案（可选）                     |
| **正则表达式验证** | 用于输入验证的正则表达式（可选）                |
| **占位符文本**   | 显示预期输入格式的灰色提示文本（可选）             |
| **工具提示文本**  | 包含帮助文本的悬停弹窗（可选）                 |
| **注释文本**    | 直接显示在输入字段下方的帮助文本（可选）            |
| **更改时**     | 基于此字段值显示/隐藏其他问题的 JavaScript（可选） |

### 系统问题参考

下表记录了为每个租户配方生成的内置系统问题。

#### 租户章节

核心租户身份、管理员凭据和 SSL 配置：

| 变量名称                        | 显示标签      | 类型   | 默认值         | 默认启用 |
| --------------------------- | --------- | ---- | ----------- | ---- |
| `YB_URL`                    | URL       | 字符串  | —           | 是    |
| `YB_DESCRIPTION`            | 描述        | 文本区域 | —           | 是    |
| `YB_USER_NAME`              | 管理员用户     | 字符串  | `admin`     | 是    |
| `YB_USER_PASSWORD`          | 密码        | 密码   | —           | 是    |
| `YB_USER_EMAIL`             | 电子邮件      | 字符串  | —           | 否    |
| `YB_USER_CHANGE_PASSWORD`   | 要求更改密码    | 布尔值  | `false`     | 否    |
| `YB_EXPOSE_CLOUD_SNAPSHOTS` | 公开系统快照    | 布尔值  | `true`      | 否    |
| `YB_HELP_URL`               | 帮助 URL    | 字符串  | `默认`        | 否    |
| `YB_THEME_ACCESS`           | 主题访问权限    | 列表   | `host_only` | 是    |
| `YB_SPECIFIED_THEME`        | 主题        | 行选择  | —           | 是    |
| `YB_CLUSTER`                | 集群        | 集群   | —           | 否    |
| `YB_CERT_TYPE`              | SSL 证书类型  | 隐藏   | `manual`    | 否    |
| `YB_CERT_DOMAIN`            | SSL 证书域名  | 字符串  | —           | 否    |
| `YB_CERT_PUBLIC`            | 公用 SSL 证书 | 文本区域 | —           | 否    |
| `YB_CERT_PRIVATE`           | 私有 SSL 证书 | 文本区域 | —           | 否    |
| `YB_CERT_CHAIN`             | SSL 证书链   | 文本区域 | —           | 否    |

#### 节点章节

分配给租户虚拟节点的计算资源：

| 变量名称                         | 显示标签        | 类型  | 默认值     | 默认启用 |
| ---------------------------- | ----------- | --- | ------- | ---- |
| `YB_NODE_1_CPU_CORES`        | 节点 1 核心数    | 数值  | `8`     | 是    |
| `YB_NODE_1_RAM`              | 节点 1 RAM    | RAM | `16384` | 是    |
| `YB_NODE_1_INSTANCES`        | 节点 1 实例数    | 数值  | `1`     | 否    |
| `YB_NODE_1_CLUSTER`          | 节点 1 集群     | 集群  | —       | 否    |
| `YB_NODE_1_CLUSTER_FAILOVER` | 节点 1 故障转移集群 | 集群  | —       | 否    |

#### 网络章节

用于租户 UI 和外部连接的网络地址：

| 变量名称          | 显示标签     | 类型       | 默认值 | 默认启用 |
| ------------- | -------- | -------- | --- | ---- |
| `YB_NET_1_IP` | UI IP 地址 | 虚拟 IP 地址 | —   | 是    |
| `YB_NET_2_IP` | IP 地址    | 虚拟 IP 地址 | —   | 是    |

{% hint style="success" %}
这些是截至 VergeOS 26.1 的默认系统问题。您可在此基础上添加自定义问题，以收集其他输入，如到期日期、自定义主机名或其他租户特定值。
{% endhint %}

## 自定义问题

除系统问题外，您还可以添加 **自定义问题** 以收集部署所需的任何其他输入。自定义问题支持与系统问题相同的字段类型，以及多种数据库交互类型（对任何 VergeOS 对象进行读/写）。

### 常见问题类型

| 类型           | 用途          | 示例用途      |
| ------------ | ----------- | --------- |
| **字符串**      | 单行文本输入      | 客户名称、主机名  |
| **文本区域**     | 多行文本输入      | 备注、配置片段   |
| **密码**       | 带确认的掩码输入    | 服务帐户密码    |
| **数值**       | 数值输入        | 端口号、实例数量  |
| **布尔值**      | 复选框（真/假）    | 启用/禁用功能   |
| **列表**       | 下拉选择        | 从预定义选项中选择 |
| **隐藏**       | 不在表单上显示     | 脚本的硬编码值   |
| **网络**       | 网络选择器       | 选择目标网络    |
| **虚拟 IP 地址** | IP 地址选择器    | 分配特定 IP   |
| **RAM**      | 内存输入（单位：MB） | 额外资源分配    |
| **集群**       | 集群选择器       | 用于放置的目标集群 |

### 数据库交互类型

这些高级问题类型允许配方 **从 VergeOS 数据库读取并写入数据** 在创建租户期间——从而实现以下自动化工作流：

| 类型        | 用途                  | 示例用途                 |
| --------- | ------------------- | -------------------- |
| **数据库创建** | 在 VergeOS 数据库中创建新记录 | 注册 DHCP 保留、创建 DNS 条目 |
| **数据库编辑** | 修改现有数据库记录           | 更新网络配置、更改设置          |
| **数据库查找** | 从数据库中查找值            | 获取下一个可用 IP、查找网络 ID   |

每个数据库问题都包含一个 **数据库上下文** 字段，用于确定操作的目标是 **父系统的数据库** 还是 **新创建租户的数据库**。这种区别至关重要：

* **父级上下文：** 在主机的 DNS 中注册租户 IP，在主机网络上创建 DHCP 保留
* **租户上下文：** 在新租户自身内部配置设置

{% hint style="info" %}
数据库交互问题引用 VergeOS API 表。请参阅 [API 表说明](https://docs.verge.io/knowledge-base/zh/automation-api/api-tables-description.md) 和 [API 指南](https://docs.verge.io/knowledge-base/zh/automation-api/verge-api-guide.md) 以获取表名、字段名和筛选语法。
{% endhint %}

## 修改并重新发布配方

修改配方时（更改问题、更新基础租户、调整默认值），这些更改 **不会立即提供** 给用户。您必须 **重新发布** 该配方：

1. 在配方仪表板上进行更改（编辑问题、更新章节等）
2. 顶部会显示横幅： *“必须重新发布配方，更改才能生效”*
3. 点击 **重新发布** （通过横幅链接或左侧菜单）
4. 版本号会自动递增（例如， `1.0.0-1` → `1.0.0-2`)

重新发布配方时， **有访问权限的远程系统和租户** 会收到有可用更新的通知。它们必须明确下载更新才能使用新版本。

### 配方实例

一个 **实例** 是通过配方创建并且仍与该配方关联的租户。您可以通过单击配方仪表板上的 **实例** （位于左侧菜单中）查看所有实例。

实例的关键规则：

* 配方 **无法删除** 只要它具有关联实例
* 实例可以 **解除关联** 与其配方解除关联，成为独立租户
* 解除关联的租户会失去其配方关联，但保留所有配置

## 配方交换：系统间共享

配方被组织到 **存储库** 和 **目录**中，形成层级结构：

```mermaid
graph TD
    R["存储库"] --> C1["目录 A<br/>（Windows 租户）"]
    R --> C2["目录 B<br/>（Linux 租户）"]
    R --> C3["目录 C<br/>（存储服务）"]
    C1 --> TR1["租户配方 1"]
    C1 --> TR2["租户配方 2"]
    C2 --> TR3["租户配方 3"]
    C3 --> TR4["租户配方 4"]

    style R fill:#e8eaf6,stroke:#283593
    style C1 fill:#e3f2fd,stroke:#1565c0
    style C2 fill:#e3f2fd,stroke:#1565c0
    style C3 fill:#e3f2fd,stroke:#1565c0
```

### 存储库类型

* **本地存储库：** 在本地系统上创建和维护的目录及配方。每个 VergeOS 系统均附带一个可立即使用的空“本地”存储库。
* **远程存储库：** 连接到托管在独立 VergeOS 系统上的目录。这样无需在多个位置维护相同的配方。
* **Marketplace：** 由 VergeOS 提供、预安装在主机级系统上的远程存储库，其中包含可直接使用的虚拟机配方。Marketplace 目录默认使用 `scope=global`，使其可供所有租户使用。

### 目录发布范围

| 范围     | 可用性                               |
| ------ | --------------------------------- |
| **私有** | 仅本地 VergeOS 系统                    |
| **无**  | 已禁用——任何位置均不可用                     |
| **租户** | 本地系统及其直属租户                        |
| **全局** | 本地系统、租户以及外部 VergeOS 系统（使用 API 凭据） |

### 与租户共享

1. 将目录的发布范围设置为 **租户** 或 **全局**
2. 在租户的 UI 中，导航到 **服务提供商** 存储库
3. 点击 **刷新** 以发现可用目录
4. 下载所需的配方 — 状态显示 *在线* 准备好时

### 与远程系统共享

1. 创建一个 **API 类型用户** 在共享系统上，针对目标目录授予 List/Read 权限
2. 在接收系统上，创建一个 **远程存储库** 指向共享系统的 URL
3. 使用 API 用户凭据进行身份验证
4. 刷新存储库以发现并下载可用目录和配方

当源端的配方更新时，租户和远程系统都会看到有可供下载的更新通知。

## 实际案例：CSP 兼容 S3 的存储服务

为了说明租户配方的强大功能，请看来自以下内容的这个场景： [VergeOS CSP 参考架构](https://docs.verge.io/plan-and-deploy/zh/can-kao-jia-gou/csp.md):

**CloudHoster**，一家中型云服务提供商，希望向客户提供名为“Cloud Storage”的兼容 S3 存储服务。与其手动配置每位客户的环境，他们构建了一个租户配方来自动化整个部署：

### 配方创建的内容

1. **租户** — 一个新的 VDC，配备适当的计算和存储资源
2. **内部网络** — 用于存储应用 VM 的隔离网络
3. **防火墙规则** — 配置为允许 S3 API 流量，同时阻止其他所有流量
4. **存储 VM** — 托管兼容 S3 存储应用的 VM，预先配置好
5. **存储分配** — 为该租户分配专用的 vSAN 存储层
6. **DNS/DHCP 注册** — 在主机网络上自动注册

### 此用例的配方问题

该配方会提示操作员（或客户自助门户）提供：

* **客户名称和 URL** （租户部分）
* **管理员凭据** （自动生成或手动）
* **存储容量** （自定义问题 — 需要预配多少 S3 存储）
* **外部 IP** （网络部分 — 用于 S3 API 终结点）
* **节点资源** （节点部分 — 存储 VM 的 CPU/RAM）

只需提交一次表单，CloudHoster 就能为其客户部署一个完整、隔离、兼容 S3 的存储环境——耗时只需几分钟，而不是几小时。

### 扩展该服务

CloudHoster 通过远程存储库共享目录，在他们的四个站点部署此配方。当他们更新该配方时（例如升级存储应用 VM），所有站点都会收到通知并可以拉取更新。

## 最佳实践

### 配方设计

* **从简单开始** — 先构建一个最小化的基础租户，再逐步增加复杂性
* **使用描述性的变量名** — `STORAGE_CAPACITY_GB` 比……更好 `Q1` 便于脚本维护
* **为你的配方编写文档** — 使用 Description 字段和问题上的 Note Text 来指导操作员
* **使用模拟进行测试** — 在发布到生产目录之前，验证问题和输出

### 基础租户维护

* **专用基础租户** — 切勿将配方的基础租户用于生产工作负载
* **版本控制** — 手动设置主版本号（例如， `2.0.0`）当对基础租户进行重大更改时
* **清除敏感数据** — 确保基础中不包含任何客户特定的密码、数据或配置

### 组织

* **有意义的目录名称** — 按用途对配方分组（例如，“标准 VDC”、“GPU 计算”、“存储服务”）
* **使用图标** — Font Awesome 图标帮助操作员在 UI 中快速识别配方类型
* **适当设置范围** — 对仅内部使用的配方使用 Private，对面向客户的使用 Tenant，对多站点分发使用 Global

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

VergeOS 租户配方可在一次操作中为整个隔离的 VDC 进行预配——包括管理 UI、用户、网络栈、防火墙规则、存储以及 DNS/DHCP——而不仅仅是 VM 或应用。对于你可能在比较的任何 VMware 或 Nutanix 自动化工具的范围和功能，请查阅该供应商的当前文档。
{% endhint %}


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.verge.io/learn-the-platform/zh/mo-kuai-7-duo-zu-hu/03-tenant-recipes.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
