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

# 租户模板

## 什么是租户配方？

租户配方可将手动配置的租户转换为一个 **可重复使用的一键部署模板**。单个租户配方可自动创建完整的虚拟数据中心——包括租户设置、网络配置、防火墙规则、包含的虚拟机、随机凭据、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`           | 主题访问      | 列表   | `仅主机`   | 是    |
| `YB_SPECIFIED_THEME`        | 主题        | 行选择  | —       | 是    |
| `YB_CLUSTER`                | 集群        | 集群   | —       | 否    |
| `YB_CERT_TYPE`              | SSL 证书类型  | 隐藏   | `手动`    | 否    |
| `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 | `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/api-tables-description) 以及 [API 指南](https://docs.verge.io/knowledge-base/verge-api-guide) 以了解表名、字段名和筛选语法。
{% 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 类型用户** 在共享系统上，针对目标目录具有列表/读取权限
2. 在接收系统上，创建一个 **远程仓库** 指向共享系统 URL 的
3. 使用 API 用户凭据进行身份验证
4. 刷新仓库以发现并下载可用的目录和配方

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

## 现实示例：CSP S3 兼容存储服务

为了说明租户配方的强大能力，请考虑来自以下内容的这个场景： [VergeOS CSP 参考架构](https://docs.verge.io/reference-architecture/csp/):

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

### 配方创建的内容

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

### 此用例的配方问题

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

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

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

### 扩展该服务

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

## 最佳实践

### 配方设计

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

### 基础租户维护

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

### 组织

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

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

VergeOS 租户配方通过一次操作即可部署完整的隔离 VDC——管理界面、用户、网络栈、防火墙规则、存储以及 DNS/DHCP——而不仅仅是虚拟机或应用程序。关于你可能拿来比较的任何 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 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-7-duo-zu-hu/03-tenant-recipes.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.