Tart 编排实战：Orchard CLI 使用指南——从上下文配置到标签与资源调度-迪斯科星球

Tart 编排实战：Orchard CLI 使用指南——从上下文配置到标签与资源调度

【免费下载链接】tartmacOS and Linux VMs on Apple Silicon to use in CI and other automations项目地址: https://gitcode.com/GitHub_Trending/ta/tart

本指南面向使用 Orchard 编排多个 Tart 主机的开发者，系统讲解 Orchard CLI 的安装、Context（上下文）配置、标签（Labels）与资源（Resources）调度三大核心主题。读完本文，你将能够把本地 CLI 安全地"配对"到 Orchard Controller，并利用标签与资源的双重调度机制，把 macOS/Linux 虚拟机精确投放到符合条件的 Worker 上。文中所有命令均以当前仓库 docs/orchard/using-orchard-cli.md 为骨架，并结合 docs/orchard/quick-start.md、docs/orchard/architecture-and-security.md、docs/orchard/deploying-controller.md 等配套文档与集群运维细节展开。

安装 Orchard CLI

Orchard CLI 最简单的安装方式是通过 Homebrew 包管理器完成：

brew install openai/tools/orchard

对于其他架构与操作系统，官方在 Release 页面提供了二进制包与各类打包产物，可按需下载。安装完成后，可以在任意支持 Tart 的 macOS 主机上执行orchard命令。若你希望先快速体验，无需部署任何集群组件，可以直接运行：

orchard dev

该命令会在本机单进程中同时启动一个 Orchard Controller 和一个 Orchard Worker，允许你立即测试 CLI 功能与 API，且不需要认证。而在生产部署中，Controller 与 Worker 是分开启动的，并且默认启用安全机制，相关内容可参考 Deploying Controller 与 Deploying Workers。

配置 Context：让 CLI 与 Controller 建立信任

什么是 Context

安装 Orchard CLI 之后的第一件事就是配置它的 Context。可以把"配置 Context"理解为与指定的 Orchard Controller 进行"配对"：只有完成这一步，orchard create vm、orchard ssh vm等命令才会知道该把请求发往哪个 Controller、并以哪个身份认证，从而正常工作。

Context 子命令族

orchard context提供了一组子命令来管理上下文：

命令	作用
`orchard context create <CONTROLLER ADDRESS>`	新建一个 Context，用于与指定地址上的 Orchard Controller 通信
`orchard context default <CONTROLLER ADDRESS>`	在已配置多个 Context 的情况下，将指定 Controller 地址对应的 Context 设为默认
`orchard context list`	列出所有已配置的 Context，并标记出默认的那一个
`orchard context delete <CONTROLLER ADDRESS>`	删除指定 Orchard Controller 地址对应的 Context

绝大多数情况下你只需要orchard context create。例如，若已把 Orchard Controller 部署到orchard-controller.example.com，可以这样配置一个新 Context：

orchard context create orchard-controller.example.com

orchard context create默认假设 Controller 监听在 6120 端口。如果为 Controller 使用了其他端口，直接显式指定端口即可：

orchard context create orchard-controller.example.com:8080

从 Deploying Controller 可以看到，Controller 默认的监听地址正是:6120（由--listen参数控制），这也解释了 CLI 默认端口选择的由来。另外，context create还支持以非交互方式一次性传入全部凭据，便于脚本化配置：

orchard context create --name production \ --service-account-name bootstrap-admin \ --service-account-token $ORCHARD_BOOTSTRAP_ADMIN_TOKEN \ https://$ORCHARD_IP:443

获取服务账号名称与 Token

创建 Context 时，CLI 会提示你输入服务账号名称（service account name）与 Token，这两个凭据可以通过以下途径获取：

orchard controller run的启动日志——适用于 Controller 首次启动的场景。Orchard API 默认是安全的：所有请求都必须使用某个服务账号的凭据进行认证。首次运行 Controller 时，会自动创建一个名为bootstrap-admin的服务账号，并将其凭据打印到标准输出；也可以通过设置ORCHARD_BOOTSTRAP_ADMIN_TOKEN环境变量来预先指定该账号的 Token，例如ORCHARD_BOOTSTRAP_ADMIN_TOKEN=$(openssl rand -hex 32) orchard controller run。
orchard get service-account——适用于已经配置好一台 Orchard CLI 的场景，可以从已有 Context 中读取服务账号信息。

Context 建立时的信任机制

从 architecture-and-security.md 可以看到，orchard context create并非简单的地址登记，而是一个完整的证书信任建立过程：

CLI 首先尝试连接 Controller，并使用主机根 CA 集合校验其证书；
如果 Controller 持有公开可信证书，校验通过即配对成功；
如果 Controller 使用的是自签名证书（首次启动未传--controller-cert/--controller-key时自动生成），CLI 会再次发起连接以探测 Controller 的证书；
探测到的证书指纹会展示给用户，用户确认信任后，该证书即被该 Context 视为可信；
最后 CLI 以仅包含该证书的可信 CA 集合重新连接，执行最终的 API 健全性检查，全部通过后配对成功。

此后，每一次与 Controller 的交互（例如orchard create vm）都会按照所选方式重新校验证书。若你希望完全放弃 PKI 校验、仅凭指纹交互信任来对抗 CA 被攻破等风险，可以在orchard context create时追加--no-pki参数，创建非 PKI 关联。

用环境变量覆盖 Context 配置

除了通过命令行参数控制 Orchard，还有一组环境变量在自动化场景与日常使用中非常有用（详见 quick-start.md）：

变量名	说明
`ORCHARD_HOME`	覆盖 Orchard 的主目录，适合在同一主机上运行多个 Orchard 实例或进行测试
`ORCHARD_URL`	在单条命令级别覆盖 Controller 的 URL
`ORCHARD_SERVICE_ACCOUNT_NAME`	在单条命令级别覆盖服务账号名称（用于 Controller API 认证）
`ORCHARD_SERVICE_ACCOUNT_TOKEN`	在单条命令级别覆盖服务账号 Token（用于 Controller API 认证）

这四个变量让你无需反复修改 Context，即可灵活地在不同 Controller 或不同身份之间切换，非常契合 CI 脚本与多环境运维场景。

用标签（Labels）约束 VM 的调度位置

标签的语义

标签适用于这样的场景：你希望把某个 VM 的调度限制到特定的一组 Worker 上。其判定规则是——只有当某台 Worker 的标签集合包含 VM 所指定标签的子集时，该 Worker 才可能被选为 VM 的运行位置。

实战示例

假设你的 Orchard 集群由两类 Worker 组成：

Mac Mini：orchard worker run --labels location=DC1-R12-S4,model=macmini
Mac Studio：orchard worker run --labels location=DC1-R18-S8,model=macstudio

现在希望创建并运行一个只落在 Mac Studio 机器上的 VM，只需在创建 VM 时传入--labels参数：

orchard create vm --labels model=macstudio <NAME>

调度器在处理这个 VM 时，只会在可用的 Mac Studio Worker 中寻找放置位置。标签是静态属性，Worker 声明了什么标签、VM 要求什么标签，两者做子集匹配即可，不涉及任何数量上的扣减。

用资源（Resources）约束 VM 的调度配额

资源的语义

资源用于限制 VM 只能调度到仍拥有足够剩余资源的 Worker 上。与标签最大的区别在于：资源是有限的，调度器会自动进行占用与释放的核算（accounted）。也就是说，一个 VM 被调度到某台 Worker 后，它所声明的资源需求就会从该 Worker 的剩余容量中扣减，直到 VM 结束才会归还。

实战示例

假设集群中有两类 Worker，各自声明了带宽资源：

Mac Mini（1 Gbps）：orchard worker run --resources bandwidth-mbps=1000
Mac Studio（10 Gbps）：orchard worker run --resources bandwidth-mbps=10000

下面这条命令创建的 VM，由于需求 7500 Mbps 带宽，只可能被调度到拥有 10 Gbps 带宽的 Mac Studio 上：

orchard create vm --resources bandwidth-mbps=7500 <NAME>

在这个 VM 被调度之后，这台 10 Gbps 的 Mac Studio 剩余带宽就只剩 2500 Mbps，因此它至多还能容纳一个bandwidth-mbps=2500或更低的 VM（这里同时受 macOS 虚拟化相关的 Apple EULA 内部限制约束）。当 VM 运行结束、被删除后，其占用的资源会重新变为可用，供后续 VM 调度使用。

这里有两个值得注意的实践要点：

Worker 声明的是"总量"：--resources的取值是这台主机在该维度上的总能力，调度器负责在多次调度之间做减法；
VM 声明的是"需求量"：orchard create vm --resources的取值是单个 VM 需要占用的量，调度器只在有足够剩余容量的 Worker 上放置该 VM。

自动资源：Worker 启动时自动发现的默认指标

除了在启动 Worker 时手动指定资源，Worker 还会为了方便而自动发现并设置以下两类资源：

自动资源名	含义
`org.cirruslabs.logical-cores`	宿主机的逻辑核心数量
`org.cirruslabs.memory-mib`	宿主机的总内存，单位为 MiB（Mebibyte）

需要注意的是，这两个值只在 Worker 启动时采集一次，之后不会动态刷新。因此，如果你在 Worker 运行期间更换了宿主机硬件或调整了资源分配，需要重启 Worker 才能让自动资源反映最新状态。

围绕 CLI 的日常操作闭环

配置好 Context 之后，配合 quick-start.md 中的命令，可以完成一个完整的 VM 生命周期管理流程：

# 基于 OCI 镜像创建 VM orchard create vm --image ghcr.io/cirruslabs/macos-tahoe-base:latest tahoe-base # 查看 VM 资源列表，确认其是否已运行 orchard list vms # SSH 登录 VM（默认用户名/密码为 admin/admin，可用 --username/--password 覆盖） orchard ssh vm tahoe-base # 在远端执行单条命令，而非启动登录 shell orchard ssh vm tahoe-base "uname -a" # 通过标准输入把本地脚本喂给远端解释器执行 orchard ssh vm tahoe-base "bash -s" < script.sh # 通过 VNC 打开远程 VM 的屏幕共享（同样支持 --username/--password） orchard vnc vm tahoe-base # 删除 VM 并清理其关联资源 orchard delete vm tahoe-base

其中orchard ssh vm与orchard vnc vm都建立在 Orchard 的端口转发能力之上：所有转发连接都经由 Orchard Controller 实例，"代理"一条安全连接到对应的 Orchard Worker。这意味着 Worker 可以部署在仅允许访问 Controller 的严格防火墙之后，而 Controller 默认启用安全机制、所有 API 调用均需认证与授权。

集群运维视角下的 CLI 延伸

CLI 的能力不止于创建与调度 VM，它也是集群日常运维的主要入口：

Worker 部署：为 Worker 创建最小权限服务账号并生成 Bootstrap Token，以便非交互式地批量接入 Worker：
```
orchard create service-account worker-pool-m1 --roles "compute:read" --roles "compute:write" orchard get bootstrap-token worker-pool-m1
```
详细流程参见 Deploying Workers。Bootstrap Token 的信任逻辑与 Context 类似：当当前 Context 面对的是自签名证书 Controller 时，Token 中会内嵌 Controller 证书；面对公开可信证书 Controller 时则省略证书，Worker 改用 PKI 校验，也可通过orchard worker run --no-pki强制快速失败。
集群备份与升级：备份 Controller 只需复制其ORCHARD_HOME（默认~/.orchard/）目录，其中包含 BadgerDB 状态数据库与 X.509 证书及密钥；升级方面，Orchard 各版本间保持了向后兼容，一般无需关心 Controller 与 Worker 的升级先后顺序。详见 managing-cluster.md。
可观测性：Controller 与 Worker 都会产出以org.cirruslabs.orchard为前缀的 OpenTelemetry 指标（包括资源利用率、Worker 状态、调度/拉取耗时等），默认发送到https://localhost:4317（gRPC）与http://localhost:4318（HTTP），可通过标准环境变量OTEL_EXPORTER_OTLP_ENDPOINT覆盖。

若你的使用场景偏向自动化集成，Orchard 同样提供了完整 API，可参考 integration-guide.md；对整套系统的组件划分（Controller/Worker/Client）与网络要求（仅 Controller 需对 Workers 和 Clients 可达，Workers 与 Clients 可部署在 NAT 之后）的深入说明，请参阅 architecture-and-security.md。

小结

Orchard CLI 的使用核心可以概括为三步：安装并配置 Context（与服务账号凭据建立信任）、用标签做定向调度（静态属性子集匹配）、用资源做容量调度（有限资源自动扣减与归还）。配合自动资源、环境变量覆盖与完整的 VM 生命周期命令，你可以在多台 Tart 主机之上搭建出可精确控制、可自动化、可观测的虚拟机编排集群。

【免费下载链接】tartmacOS and Linux VMs on Apple Silicon to use in CI and other automations项目地址: https://gitcode.com/GitHub_Trending/ta/tart

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析