自托管缓存

Tuist 的缓存以节点网格的形式运行，各节点之间相互复制构件。你可以在自己的基础设施上运行缓存节点，使缓存靠近开发人员和 CI，从而缩短网络距离，避免影响缓存本应提供的速度优势。

自托管节点是一个单独的容器（ghcr.io/tuist/kura），它将构件存储在本地磁盘上，并在加入对等网格时通过内部对等端口与网格中的其他节点通信。Tuist 充当控制平面：它负责流量认证、配置托管缓存容量以及计量使用情况。它永远不会访问你的节点内部。

两种拓扑结构#

运行自托管节点有两种方式，具体使用哪一种完全取决于你的账户是否同时运行了Tuist 托管的缓存区域。

桥接模式：Tuist 托管网格 + 你的节点#

你的账户至少运行一个由 Tuist 管理的缓存区域，而你的自托管节点会加入该网格。写入你节点的数据会持续传播到托管网格中，当节点加入时，它会从托管网格的现有缓存中预热。这样可以在你的运行器（主要负责写入）旁边放置低延迟缓存，同时它们的写入也会充实共享缓存。请注意，在节点加入之后，托管网格中其他位置写入的新工件尚未持续回传给它；这是一项计划中的增强功能。

如果你希望获得本地缓存的速度，同时又不放弃共享且始终在线的托管缓存，这是正确的选择。

独立模式：仅使用你的节点#

你的账户没有运行任何受管缓存区域。你的节点在你的基础设施上形成自己的隔离网格。Tuist 仍然知道你的节点存在（因此用量会被计量），但不会与任何 Tuist 管理的网格交换数据，因为不存在这样的网格。对等成员资格和复制完全在你的节点内部进行。

graph LR
  subgraph Bridged
    direction LR
    M[Tuist-managed mesh] <-->|replicate| N1[Your node]
  end
  subgraph Standalone
    direction LR
    N2[Your node] <-->|replicate| N3[Your node]
  end

配置上的关键区别在于，桥接拓扑使用注册机制，节点在启动时生成密钥对，Tuist 颁发其网格证书；而独立拓扑没有 Tuist 颁发的网格证书。单个独立节点可以在禁用对等 TLS 的情况下运行；多节点独立网格则使用你提供的对等 TLS 材料。

配置 CLI 端点#

Tuist 的托管缓存使用 https://<account>.cache.tuist.dev。对于自托管 Tuist 服务器，CLI 会从服务器的 TUIST_CACHE_ENDPOINTS 设置中获取缓存 URL。将其设置为主缓存服务器或负载均衡器的 URL。如果包含多个 URL，则使用第一个。

将私有/自定义缓存节点连接到托管 Tuist 服务器时，请在开发者 shell 和 CI 中配置显式端点：

此覆盖设置在两种服务器类型上均优先生效，对于自托管 Tuist 服务器则是可选的。对于 Xcode 缓存守护进程，请在设置后重新运行 tuist setup cache，以便 LaunchAgent 接收更新后的环境变量。对于多个节点，请使用你的负载均衡器或 DNS 路由名称。

前提条件#

• Docker 和 Docker Compose（或任何容器运行时）
• 正在运行的 Tuist 服务器（托管或自托管）
• 缓存所需的磁盘空间。桥接节点在首次加入时会拉取账户的整个网格，因此请相应调整数据卷的大小。

提供控制平面客户端#

节点使用控制平面客户端凭据来认证缓存请求（令牌内省）、向仪表板报告以及提交使用情况。这不是在自托管 Tuist 服务器上将客户端路由到你的节点的方式（参见客户端如何到达你的节点）。

对于完全自托管部署，生成一个UUID 客户端 ID和一个随机密钥，然后在 Tuist 服务器和每个 Kura 节点上配置相同的配对：

将这些值作为 KURA_CONTROL_PLANE_CLIENT_ID 和 KURA_CONTROL_PLANE_CLIENT_SECRET 设置在 Tuist 服务器环境中，然后在下面的 Kura 配置中使用相同的值。注册心跳包含 KURA_TENANT_ID，即账户的永久缓存标识，因此即使账户重命名，服务器也能将节点关联到正确的账户。

如果你连接到托管的 tuist.dev 服务器，或者希望获得可以从 UI 轮换的每账户凭据，请打开账户的缓存页面，选择生成凭据，然后复制 client_id 以及一次性 secret。在托管服务器上，生成自托管节点凭据需要 Enterprise 计划。

选择永久租户#

KURA_TENANT_ID 是永久的存储和对等身份，最初源自账户的原始句柄。对于从未重命名的账户，它与当前句柄匹配。在账户重命名后保留其原始值，包括在添加替换节点或向同一网格添加另一个节点时。例如，将 original 重命名为 renamed 后，每个节点上的 KURA_TENANT_ID=original 保持不变。更改它会选择不同的对象键命名空间；重命名账户不会迁移已存储的构件或对等身份。

将下面示例中的 <permanent-kura-tenant> 替换为此值。重用现有正确配置节点中的租户，或使用注册返回的 tenant_id。自托管 Tuist 服务器的操作员可以检查账户的 kura_tenant_id 数据库字段。不要从重命名账户的 URL 推断该值。

使用有效的部署级控制平面凭据时，如果节点提供的当前或保留句柄与其永久租户不一致，注册和对等发现将返回 409 Conflict，并附带 error: "tenant_mismatch" 和 expected_tenant_id。它们不会注册该节点，也不会静默替换为不同的存储身份。无效凭据和未知租户仍会返回 401 Unauthorized，且不披露租户信息。如果节点已使用不同租户写入数据，请在更改之前审查其配置和存储历史；错误响应不会执行存储迁移。

客户端如何到达你的节点#

配置上述缓存 URL，以便开发机器和 CI 能够访问你的节点。要在仪表板中报告每个节点的地址和就绪状态，请在节点上设置 KURA_REGISTRATION_URL 和 KURA_ADVERTISED_HTTP_URL。

桥接设置#

节点在启动时进行注册：它在本地生成密钥对（私钥永远不会离开你的基础设施），发送证书签名请求，并接收其签名证书、账户 CA 以及托管网格的网关地址。你无需提供任何 TLS 材料。注册过程会将其写入挂载的卷中。

你需要提供：控制平面客户端、网络上的两个地址（KURA_NODE_URL、KURA_ADVERTISED_HTTP_URL）以及两个空的可写卷。其他所有内容（密钥对、证书、账户 CA 和托管网格的地址）都会在启动时自动配置。

独立设置#

由于没有托管区域，因此没有 Tuist 颁发的网格 CA，所以注册不适用（注册端点返回 503 ca_unavailable）。节点使用你的 Tuist 服务器进行令牌认证、仪表板注册心跳和使用情况报告。

对于单个节点，保持对等 TLS 未设置，并将 KURA_PEERS 设置为空字符串。当 KURA_PEERS 未设置时，Kura 会从 KURA_NODE_URL 种子化静态对等发现，并定期检查该 URL 的 /_internal/status 端点。禁用对等 TLS 时，即使可以通过私有网络名称访问节点，KURA_NODE_URL 也必须使用 http:// 方案。

此示例中不需要 KURA_CONTROL_PLANE_URL，因为授权和使用情况报告器都使用 KURA_AUTH_TUIST_URL 作为 Tuist 基础 URL。KURA_ADVERTISED_HTTP_URL 标识仪表板中节点面向客户端的地址。在 Tuist 服务器上设置 TUIST_CACHE_ENDPOINTS=https://kura.acme.internal，以便 CLI 使用该地址进行缓存请求。

使用 Helm 的 Kubernetes#

如果你的自托管 Tuist 服务器运行在 Kubernetes 上，请使用独立 Kura chart 安装 Kura，并通过 extraEnv 传递相同的控制平面设置。Tuist 服务器 chart 不会将此 Kura chart 作为子 chart 安装。

首先，使用部署级 Kura 凭据配置 Tuist 服务器 chart：

然后使用相同的 Secret 在同一命名空间中安装 Kura：

如果 Kura 在与 Tuist 服务器不同的命名空间中运行，请创建或将 kura-control-plane Secret 同步到这两个命名空间。

使用镜像中捆绑的 Tuist hook 时，保持 extension.enabled 未设置；该 chart 值用于从 ConfigMap 挂载自定义 hook。Chart 会为你渲染 KURA_NODE_URL、KURA_PEERS、无头服务、持久化和探针。使用 replicaCount: 1 时，生成的对等 URL 是 Pod 自身的稳定 DNS 名称，因此它在集群内仍可访问，并且不会产生上述单节点警告。对于多个副本，Chart 会从 StatefulSet DNS 生成对等列表；如果你希望在内部对等平面上使用 mTLS，请启用 peerTls 并提供 TLS Secret。

要运行多个独立节点，请添加挂载在 /tls 的自有对等 TLS（每个节点一个 CA 加上叶子证书和密钥，共享一个 CA 以便节点相互信任），将 KURA_NODE_URL 切换为 https://...:<KURA_INTERNAL_PORT>，并添加 KURA_PEERS：

每种拓扑所需的内容#

必需配置#

这些变量用于配置每个节点，无论拓扑如何（对等 TLS 是下文提到的例外）：

桥接节点还会设置 KURA_ENROLL_ON_BOOT、KURA_CONTROL_PLANE_URL 和控制平面客户端凭据。KURA_REGISTRATION_URL 和 KURA_ADVERTISED_HTTP_URL 用于注册节点，使其出现在缓存页面上，并使启用 Kura 的 CLI 客户端能够路由到该节点（请参阅客户端如何访问你的节点）。

存储和驱逐#

节点将构件存储在 KURA_DATA_DIR 下，直到达到 CAS 存储预算，你可以通过一个可选变量进行设置：

无论你是否设置，预算上限均为持有 KURA_DATA_DIR 的文件系统大小的 80%，这样轮转（在驱逐最旧段之前写入新段）就不会填满磁盘。预算会舍入为完整的 512 MiB 段，最小为 2.5 GiB。节点会在启动时记录解析后的预算（resolved CAS segment ring limits）。

驱逐是自动的。构件存储在段环中，一旦达到预算，最旧的段就会被驱逐。从较旧段读取的构件会被提升到当前段中，因此常用构件会被保留，驱逐行为接近最近最少使用（LRU）。

将 KURA_DATA_DIR 放在专用卷上。默认预算和上限都是文件系统总大小的百分比，而不是剩余空间，因此同一文件系统上的其他数据可能会使可用空间少于预算假设的空间。

缓存请求的身份验证#

默认情况下，节点会向其网络上任何可达的对象提供 HTTP 缓存 API。若要求调用者出示有效的 Tuist 令牌，以便只有你组织中经过身份验证的成员才能读写，请将节点指向你的 Tuist 服务器。上述独立设置就是这样做的。

授权复用你已设置的控制平面客户端（KURA_CONTROL_PLANE_CLIENT_ID / KURA_CONTROL_PLANE_CLIENT_SECRET）来内省令牌，因此不需要额外的凭据。自托管节点运行仅内省模式：它从不持有对称的 Guardian JWT 验证器密钥，该密钥可以为任何租户生成令牌且从不共享，因此每个请求都会针对你的服务器进行授权。无法访问服务器的节点会拒绝服务而不是提供服务，并且没有设置可以改变这一点。Tuist 管理的节点运行相同的授权；唯一的区别是它们还持有验证密钥，这使得它们可以仅凭令牌处理大多数请求。

网络#

节点会根据你启用的集成建立出站连接：

• 你的 Tuist 服务器，用于令牌内省（KURA_AUTH_TUIST_URL）、注册心跳（KURA_REGISTRATION_URL）、使用情况（KURA_CONTROL_PLANE_URL 或 KURA_AUTH_TUIST_URL）以及在桥接拓扑中的注册，以及
• 在桥接拓扑中，管理网格的对等网关，用于复制。

你的开发人员和 CI 访问节点的 KURA_ADVERTISED_HTTP_URL（对于多节点网格，节点之间通过对等端口相互访问）。这些地址只需在你的网络内可达即可。它们不需要暴露给公共互联网。

行为方式#

• 桥接。 启动时，节点会注册，拉取管理网格的完整缓存，并转换为环中的服务成员。初始拉取只发生一次，在广域网上可能需要一段时间，具体取决于你的缓存大小。此后，节点上的写入会持续传播到管理网格。节点加入后在管理网格其他地方写入的新构件尚未持续传播到该节点（计划中的增强功能），因此请将加入时的拉取视为快照而非实时镜像。
• 独立。 节点在你的基础设施上作为隔离网格运行。如果有复制，仅发生在你的节点之间。配置后，Tuist 的角色仅限于控制平面：仪表板可见性、缓存端点广告、使用情况计量和令牌内省。它永远不会配置、升级、与你的节点对等或深入访问你的节点。

验证#

桥接节点在拉取网格时报告 state: joining，在追上后报告 state: serving。一旦注册心跳开始，你的节点也会出现在账户的缓存页面下的已注册节点中。

要验证远程缓存，请使用未缓存的可缓存目标运行 tuist cache，并在 Kura 日志中确认上传成功。仅零退出状态并不能确认构件已存储。

升级#

节点设计为可在存在一个版本差异的情况下并行运行，因此对多个节点进行滚动升级是安全的。