# https://github.com/flyteorg/flyte 项目说明书

生成时间：2026-06-19 10:34:11 UTC

## 目录

- [Flyte 2 Backend Overview & System Architecture](#page-1)
- [Core Backend Services (runs, dataproxy, cache, events, app, actions, secret)](#page-2)
- [Plugin Machinery, Executor & Task Plugins](#page-3)
- [Data Plane, Storage, IDL, and Deployment](#page-4)

<a id='page-1'></a>

## Flyte 2 Backend Overview & System Architecture

### 相关页面

相关主题：[Core Backend Services (runs, dataproxy, cache, events, app, actions, secret)](#page-2), [Plugin Machinery, Executor & Task Plugins](#page-3), [Data Plane, Storage, IDL, and Deployment](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/flyteorg/flyte/blob/main/README.md)
- [manager/README.md](https://github.com/flyteorg/flyte/blob/main/manager/README.md)
- [flytecopilot/README.md](https://github.com/flyteorg/flyte/blob/main/flytecopilot/README.md)
- [charts/flyte-binary/README.md](https://github.com/flyteorg/flyte/blob/main/charts/flyte-binary/README.md)
- [flyteidl2/gen_utils/rust/src/lib.rs](https://github.com/flyteorg/flyte/blob/main/flyteidl2/gen_utils/rust/src/lib.rs)
- [gen/ts/flyteidl2/app/app_definition_pb.ts](https://github.com/flyteorg/flyte/blob/main/gen/ts/flyteidl2/app/app_definition_pb.ts)
- [gen/go/flyteidl2/app/app_definition.pb.go](https://github.com/flyteorg/flyte/blob/main/gen/go/flyteidl2/app/app_definition.pb.go)
- [app/internal/k8s/app_client_test.go](https://github.com/flyteorg/flyte/blob/main/app/internal/k8s/app_client_test.go)
- [app/internal/service/internal_app_service_test.go](https://github.com/flyteorg/flyte/blob/main/app/internal/service/internal_app_service_test.go)
- [flytestdlib/README.md](https://github.com/flyteorg/flyte/blob/main/flytestdlib/README.md)
</details>

# Flyte 2 后端总览与系统架构

## 项目定位与核心目标

Flyte 2 是一个面向机器学习流水线、模型与智能体的大规模编排系统，官方标语强调“纯 Python、可靠地运行 ML pipelines、models、agents”。当前主分支专注于 Kubernetes 原生后端基础设施，目标是把 Flyte 2 演进为分布式、多节点部署形态。Flyte 1 由 `master` 分支继续维护，企业级生产后端由 Union.ai 提供托管。

资料来源：[README.md](https://github.com/flyteorg/flyte/blob/main/README.md)

## 整体架构与组件拓扑

Flyte 2 后端采用“单二进制多服务”形态，核心实现位于 `manager/`，称为 Flyte Manager。所有核心子服务在同一个进程中运行，并共享 PostgreSQL 后端与同一份配置：

| 子服务 | 职责 |
| --- | --- |
| Runs Service | 管理工作流运行与动作状态 |
| Executor / Operator | 通过 TaskAction CR 协调生命周期 |
| Actions Service | 暴露动作元数据、入队、生命周期 API |
| DataProxy Service | 代理签名 URL 与 Blob I/O |
| Events Service | 摄取并广播任务/运行事件 |
| Cache Service | 支持任务输出缓存与查找 |
| App Service | 托管 Flyte UI 与内部代理路由 |
| Secret Service | 管理任务所用的密钥引用 |

所有 Connect/gRPC 服务统一挂载在单一端口（默认 8090），例如 `flyteidl2.workflow.RunService`、`InternalRunService`、`TranslatorService`、`RunLogsService` 等。

```mermaid
flowchart LR
    SDK[Python SDK / flyte-sdk] -->|gRPC/Connect| Mgr[Flyte Manager :8090]
    Mgr --> DB[(PostgreSQL)]
    Mgr -->|K8s API| K8s[(Kubernetes)]
    K8s --> Copilot[flyte-copilot init + sidecar]
    Copilot --> Store[(Object Storage)]
    Mgr --> UI[App Service / Flyte UI]
```

资料来源：[manager/README.md](https://github.com/flyteorg/flyte/blob/main/manager/README.md)

## Kubernetes 部署与 CoPilot 边车

`charts/flyte-binary` 提供面向单可执行二进制部署的 Helm Chart，使用镜像 `cr.flyte.org/flyteorg/flyte-binary-v2`，并附带 `waitForDB` init container 以确保数据库就绪后再启动主进程。App 资源通过 `app/internal/k8s/app_client_test.go` 中的客户端创建，最终落到 Kubernetes 上的 Knative Service，命名规则形如 `{name}-{project}-{domain}`，标签和注解（如 `annotationSpecSHA`、`annotationAppID`）由后端注入。

`flytecopilot` 是理解 Flyte Metadata Format 的边车进程，二进制以两种模式运行：

- **Downloader**：作为 init container 启动，先下载元数据与配置数据，再让主容器运行
- **Sidecar**：与主容器并行运行，监视主容器生命周期并把生成的数据上传到远程存储

资料来源：[charts/flyte-binary/README.md](https://github.com/flyteorg/flyte/blob/main/charts/flyte-binary/README.md)、[flytecopilot/README.md](https://github.com/flyteorg/flyte/blob/main/flytecopilot/README.md)、[app/internal/k8s/app_client_test.go](https://github.com/flyteorg/flyte/blob/main/app/internal/k8s/app_client_test.go)

## 多语言 IDL 与协议层

Flyte 2 通过统一的 `flyteidl2` IDL 描述 App、Run、Task、Log 等核心实体，生成的代码覆盖 Go、Rust、TypeScript 三大生态：

- Go 侧 `flyteidl2/app/app_definition.pb.go` 暴露 `Spec`、`Status`、`Condition`、`Identifier`、`MaterializedInput` 等消息，并通过 `flyteidl2.core.ExtendedResources`、`flyteidl2.app.Profile`、`flyteidl2.app.SecurityContext` 等字段建立跨包引用
- Rust 侧 `flyteidl2/gen_utils/rust/src/lib.rs` 重新导出 `actions`、`app`、`auth`、`project`、`common`、`workflow`、`logs/dataplane`、`core`、`notification`、`task`、`trigger`、`secret` 等子模块，方便上游 SDK 直接使用
- TypeScript 侧 `@flyteorg/flyteidl2` 包基于 `@bufbuild/protobuf`，在 `gen/ts/flyteidl2/app/app_definition_pb.ts` 中提供 `App`、`Condition`、`Identifier`、`Meta` 等消息的运行时构造器与 schema

这种“一次定义、多语言生成”的方式保证了 SDK、控制平面与 UI 之间的类型一致性。

资料来源：[flyteidl2/gen_utils/rust/src/lib.rs](https://github.com/flyteorg/flyte/blob/main/flyteidl2/gen_utils/rust/src/lib.rs)、[gen/ts/flyteidl2/app/app_definition_pb.ts](https://github.com/flyteorg/flyte/blob/main/gen/ts/flyteidl2/app/app_definition_pb.ts)、[gen/go/flyteidl2/app/app_definition.pb.go](https://github.com/flyteorg/flyte/blob/main/gen/go/flyteidl2/app/app_definition.pb.go)

## 社区关注的核心能力

围绕 Flyte 1/Flyte 2 演进，社区讨论最集中的方向直接影响后端架构：

- **DBT 插件 (#2202)**：Gojek 团队希望把 `flytekit-dbt` 合并进官方仓库，作为一等公民的 task 类型
- **Flyteadmin 通知 webhook 化 (#2317)**：希望摆脱对 SES/SendGrid 邮件通道的依赖
- **Failure-Node 支持 (#1506)**：后端已经支持每个 workflow/sub-workflow 关联失败节点，但 flytekit（Python/Java）尚未暴露该能力
- **运行时覆盖 (#475)**：用户希望在执行时动态调整 CPU/Mem/GPU、缓存、重试、Spark、Hive 等配置，避免重新注册
- **生产 CI/CD (#2772)**：希望复刻 Lyft 的 MLOps 实践，沉淀面向生产 Flyte 部署的 GitHub Actions 流程

这些诉求会驱动 Flyte 2 IDL 增加新字段、Manager 暴露更多覆盖接口，并在 `flytestdlib` 等公共库中沉淀通用能力。

资料来源：[manager/README.md](https://github.com/flyteorg/flyte/blob/main/manager/README.md)、[flytestdlib/README.md](https://github.com/flyteorg/flyte/blob/main/flytestdlib/README.md)

## See Also

- [Flyte CoPilot 边车机制](https://github.com/flyteorg/flyte/blob/main/flytecopilot/README.md)
- [Flyte Manager 统一二进制](https://github.com/flyteorg/flyte/blob/main/manager/README.md)
- [flyte-binary Helm Chart](https://github.com/flyteorg/flyte/blob/main/charts/flyte-binary/README.md)
- [Flyte 2 IDL（flyteidl2）](https://github.com/flyteorg/flyte/tree/main/flyteidl2)

---

<a id='page-2'></a>

## Core Backend Services (runs, dataproxy, cache, events, app, actions, secret)

### 相关页面

相关主题：[Flyte 2 Backend Overview & System Architecture](#page-1), [Data Plane, Storage, IDL, and Deployment](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/flyteorg/flyte/blob/main/README.md)
- [flyteidl2/gen_utils/rust/src/lib.rs](https://github.com/flyteorg/flyte/blob/main/flyteidl2/gen_utils/rust/src/lib.rs)
- [flyteidl2/gen_utils/rust/src/google.rpc.rs](https://github.com/flyteorg/flyte/blob/main/flyteidl2/gen_utils/rust/src/google.rpc.rs)
- [gen/go/gateway/flyteidl2/app/app_definition.swagger.json](https://github.com/flyteorg/flyte/blob/main/gen/go/gateway/flyteidl2/app/app_definition.swagger.json)
- [gen/go/gateway/flyteidl2/app/app_logs_payload.swagger.json](https://github.com/flyteorg/flyte/blob/main/gen/go/gateway/flyteidl2/app/app_logs_payload.swagger.json)
- [gen/ts/flyteidl2/app/app_definition_pb.ts](https://github.com/flyteorg/flyte/blob/main/gen/ts/flyteidl2/app/app_definition_pb.ts)
- [gen/ts/flyteidl2/app/app_logs_payload_pb.ts](https://github.com/flyteorg/flyte/blob/main/gen/ts/flyteidl2/app/app_logs_payload_pb.ts)
- [gen/ts/google/api/annotations_pb.ts](https://github.com/flyteorg/flyte/blob/main/gen/ts/google/api/annotations_pb.ts)
- [flytestdlib/README.md](https://github.com/flyteorg/flyte/blob/main/flytestdlib/README.md)
- [flytecopilot/README.md](https://github.com/flyteorg/flyte/blob/main/flytecopilot/README.md)
</details>

# Core Backend Services (runs, dataproxy, cache, events, app, actions, secret)

## 概述

Flyte 仓库的核心后端服务由一组通过 gRPC/HTTP 暴露的微服务构成，负责工作流执行、任务数据代理、缓存、事件分发、应用（App）生命周期、动作审计与密钥管理。这些服务之间通过统一的 IDL（Interface Definition Language）契约进行通信，IDL 的多语言生成产物（Go、Rust、TypeScript）保证了跨语言客户端与服务端的协议一致性。资料来源：[README.md](https://github.com/flyteorg/flyte/blob/main/README.md)。

IDL 层位于 `flyteidl2/` 目录，其 Rust 工具模块将所有子协议统一再导出，便于在单一命名空间下引用。资料来源：[flyteidl2/gen_utils/rust/src/lib.rs:33-67]()。下表总结了主要 IDL 模块及其职责：

| IDL 模块 | 主要职责 |
|---|---|
| `flyteidl2.actions` | 执行动作审计与历史记录 |
| `flyteidl2.app` | 应用部署、状态、副本与日志 |
| `flyteidl2.auth` | 认证与授权上下文 |
| `flyteidl2.common` | 公共枚举、标识符、标签 |
| `flyteidl2.workflow` | 工作流、节点、任务的图结构 |
| `flyteidl2.logs.dataplane` | 数据平面日志查询接口 |
| `flyteidl2.core` | 核心执行原语（Literal、Interface） |
| `flyteidl2.notification` | 通知（邮件/消息）投递定义 |
| `flyteidl2.task` | 任务标识、类型与运行时特性 |
| `flyteidl2.trigger` | 触发器（cron、event）定义 |
| `flyteidl2.secret` | 密钥引用与挂载契约 |

## 应用服务（App Service）的接口形态

应用服务是 Core Backend Services 中面向长生命周期部署的接口。通过 IDL 生成的 Swagger 描述可见，`app_definition` 服务定义了 App 对象的元数据（`Meta`：ID、revision、labels、codeBundleUri、sourceCode）、部署状态（`Status`：assignedCluster、currentReplicas）以及细粒度的 Condition（message、revision、actor、substate）。资料来源：[gen/ts/flyteidl2/app/app_definition_pb.ts:42-110]()、[gen/go/gateway/flyteidl2/app/app_definition.swagger.json]()。

日志接口由 `app_logs_payload` 服务提供，支持通过 `TailLogsRequest` 的 `oneof target` 同时指定应用 ID 或副本 ID（`ReplicaIdentifier`），用于流式拉取运行日志。资料来源：[gen/ts/flyteidl2/app/app_logs_payload_pb.ts:18-40]()。所有服务的统一错误模型遵循 `google.rpc.Status`，包含 code、message 和 details（`google.protobuf.Any`）三段式结构。资料来源：[flyteidl2/gen_utils/rust/src/google.rpc.rs:7-30]()。

HTTP 路由注解通过 `google.api.HttpRule` 的 `oneof pattern` 表达，支持 GET/PUT/POST/DELETE/PATCH 与自定义方法，便于在网关侧生成 REST→gRPC 转换。资料来源：[gen/ts/google/api/http_pb.ts:14-60]()、`gen/ts/google/api/annotations_pb.ts]()`。

## 共享基础设施与 Copilot

`flytestdlib` 是被多个核心服务复用的基础库，包含三类组件：

- **config**：强类型配置解析、校验与热更新。资料来源：[flytestdlib/README.md:9-12]()。
- **cli/pflags**：基于结构体自动生成命令行 `pflags`。资料来源：[flytestdlib/README.md:14-17]()。
- **storage**：基于 `stow` 的抽象存储层，支持 S3/Azure/GCS、原生 protobuf 序列化以及内存实现。资料来源：[flytestdlib/README.md:23-25]()。

`flytecopilot` 是与 dataproxy 紧密协作的边车（sidecar）组件，提供两种运行模式：

1. **Downloader 模式**：作为 init container 运行，先于用户容器下载元数据与配置数据到共享卷。资料来源：[flytecopilot/README.md:12-19]()。
2. **Sidecar 模式**：与用户容器并行运行，监控主进程并将产生的元数据上传到远程对象存储。资料来源：[flytecopilot/README.md:23-30]()。

```mermaid
flowchart LR
    User[用户容器] -->|读写本地路径| Copilot[flytecopilot sidecar]
    Copilot -->|上传 metadata| ObjectStore[(对象存储)]
    Init[flytecopilot downloader<br/>init container] -->|预下载| SharedVol[/共享卷/]
    SharedVol --> User
    Admin[flyteadmin] -->|下发执行| K8s[K8s Pod]
    K8s --> Init
```

## 社区关注的功能演进方向

社区讨论中频繁出现的几个方向与核心服务密切相关：

- **执行期覆盖（overrides）**：议题 #475 主张允许在 launch execution 时覆盖 resources、catalog、retries 等参数，避免重新注册。资料来源：社区上下文 #475。
- **Failure-Node 暴露**：议题 #1506 要求在 SDK 层暴露后端已支持的 Failure-Node，便于工作流失败时执行清理逻辑。资料来源：社区上下文 #1506。
- **Webhook 通知**：议题 #2317 主张以通用 webhook 替代 PagerDuty/GitHub/Slack 邮件通道，需扩展 `flyteidl2.notification`。资料来源：社区上下文 #2317、`flyteidl2/gen_utils/rust/src/lib.rs:55-57]()`。
- **CI/CD 流程**：议题 #2772 建议参考 Lyft 的 MLOps 流程标准化生产部署。资料来源：社区上下文 #2772。
- **DBT 插件**：议题 #2202 推动 `flytekit-dbt` 进入官方插件生态。资料来源：社区上下文 #2202。

最新发布 v2.0.24 已包含依赖升级（`controller-runtime` 0.23.3→0.24.1、`k8s.io/client-go` 0.36.0→0.36.1）等改进。资料来源：社区上下文 Latest Release。

## See Also

- [flytestdlib README](https://github.com/flyteorg/flyte/blob/main/flytestdlib/README.md)
- [flytecopilot README](https://github.com/flyteorg/flyte/blob/main/flytecopilot/README.md)
- [Backend README](https://github.com/flyteorg/flyte/blob/main/docs/BACKEND_README.md)

---

<a id='page-3'></a>

## Plugin Machinery, Executor & Task Plugins

### 相关页面

相关主题：[Core Backend Services (runs, dataproxy, cache, events, app, actions, secret)](#page-2), [Data Plane, Storage, IDL, and Deployment](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [flyteplugins/go/tasks/pluginmachinery/registry.go](https://github.com/flyteorg/flyte/blob/main/flyteplugins/go/tasks/pluginmachinery/registry.go)
- [flyteplugins/go/tasks/pluginmachinery/core/plugin.go](https://github.com/flyteorg/flyte/blob/main/flyteplugins/go/tasks/pluginmachinery/core/plugin.go)
- [flyteplugins/go/tasks/pluginmachinery/core/phase.go](https://github.com/flyteorg/flyte/blob/main/flyteplugins/go/tasks/pluginmachinery/core/phase.go)
- [flyteplugins/go/tasks/plugins/k8s/pod/plugin.go](https://github.com/flyteorg/flyte/blob/main/flyteplugins/go/tasks/plugins/k8s/pod/plugin.go)
- [flyteplugins/go/tasks/plugins/k8s/spark/spark.go](https://github.com/flyteorg/flyte/blob/main/flyteplugins/go/tasks/plugins/k8s/spark/spark.go)
- [flyteplugins/go/tasks/plugins/k8s/ray/ray.go](https://github.com/flyteorg/flyte/blob/main/flyteplugins/go/tasks/plugins/k8s/ray/ray.go)
- [executor/api/v1/taskaction_types.go](https://github.com/flyteorg/flyte/blob/main/executor/api/v1/taskaction_types.go)
- [executor/api/v1/groupversion_info.go](https://github.com/flyteorg/flyte/blob/main/executor/api/v1/groupversion_info.go)
- [executor/api/v1/zz_generated.deepcopy.go](https://github.com/flyteorg/flyte/blob/main/executor/api/v1/zz_generated.deepcopy.go)
- [executor/README.md](https://github.com/flyteorg/flyte/blob/main/executor/README.md)
- [flyteplugins/README.md](https://github.com/flyteorg/flyte/blob/main/flyteplugins/README.md)
- [flytestdlib/README.md](https://github.com/flyteorg/flyte/blob/main/flytestdlib/README.md)
- [README.md](https://github.com/flyteorg/flyte/blob/main/README.md)
</details>

# Plugin Machinery、Executor 与 Task Plugins

## 概述

Flyte 的核心架构将"通用调度编排"与"任务执行形态"解耦为两层：**Plugin Machinery（插件机制）** 与 **Executor（执行器）/ Task Plugins（任务插件）**。前者定义了插件的注册、生命周期与阶段转换接口，后者则把每一个真实的执行单元（如 Pod、Spark、Ray、DBT 等）实现为可插拔的插件，从而让 Flyte 能够在不修改调度核心的情况下扩展执行形态。

资料来源：[flyteplugins/README.md:1-2]()、[README.md]()

## 插件机制核心接口

### 注册中心

`flyteplugins/go/tasks/pluginmachinery/registry.go` 维护了一个全局插件注册表，所有任务插件在启动时通过 `RegisterPlugin` 将自身注册进来，FlytePropeller 调度时会根据任务的 `TaskType` 字段查找对应插件。该机制支持 **运行时按需加载**，也允许将外部插件（如 Gojek 贡献的 DBT 插件）作为独立 module 引入。

资料来源：[flyteplugins/go/tasks/pluginmachinery/registry.go]()

### 插件契约（Plugin Interface）

`flyteplugins/go/tasks/pluginmachinery/core/plugin.go` 定义了所有插件必须实现的核心接口：

- `Resource`：描述任务的资源需求（CPU、内存、GPU）。
- `Plugin`：封装单任务的完整生命周期方法 `BuildResource`、`BuildIdentityResource`、`GetTaskPhase`、`FinalizeTask` 等。
- `EnqueueCheck`：在任务首次入队前进行幂等性校验，避免重复执行。

### 阶段状态机（Phase）

`flyteplugins/go/tasks/pluginmachinery/core/phase.go` 规定了任务执行的标准阶段枚举，例如 `PhaseQueued`、`PhaseInitializing`、`PhaseRunning`、`PhaseSuccess`、`PhasePermanentFailure`、`PhaseRetryableFailure`。该枚举与执行器（见下一节）的 `TaskActionConditionType` 直接对应，是两者之间状态同步的协议基础。

资料来源：[flyteplugins/go/tasks/pluginmachinery/core/phase.go]()

## 执行器（Executor）与 Kubernetes CRD

执行器是 v2 时代的新组件，使用 **Kubebuilder 模式** 以 Kubernetes CRD 为入口，将 Flyte 任务编排结果转换为 CR 资源，并由 Kubernetes 控制器驱动调度。

### API Group 注册

`executor/api/v1/groupversion_info.go` 把自定义资源声明在 `flyte.org/v1` API 组下，并通过 `SchemeBuilder.AddToScheme` 加入 runtime scheme，确保控制器可以正确解码 CR 对象。

```go
GroupVersion = schema.GroupVersion{Group: "flyte.org", Version: "v1"}
```

资料来源：[executor/api/v1/groupversion_info.go:30-31]()

### TaskAction 资源定义

`executor/api/v1/taskaction_types.go` 定义了核心 CRD `TaskAction`，并引入飞艇 IDL v2 的 `core`、`workflow`、`common` 类型作为 spec 字段，**实现与 IDL 协议的无缝对接**。任务生命周期通过 `ConditionTypeProgressing` 等条件字段跟踪，并在 `PhaseTransition.OccurredAt` 中记录时间戳以便审计。

资料来源：[executor/api/v1/taskaction_types.go]()、[executor/api/v1/zz_generated.deepcopy.go:38-42]()

### 安装与分发

执行器同时支持两种分发方式：

1. **YAML Bundle**：通过 `make build-installer IMG=<registry>/executor:tag` 生成 `dist/install.yaml`，用户 `kubectl apply -f` 一键部署。
2. **Helm Chart**：使用 `kubebuilder edit --plugins=helm/v1-alpha` 生成 `dist/chart`，便于与 GitOps 流水线集成。

资料来源：[executor/README.md]()

## 任务插件生态

### 内置 Kubernetes 插件

`flyteplugins/go/tasks/plugins/k8s/pod/plugin.go` 是最基础的 Pod 插件，负责把任务直接渲染为 Kubernetes Pod；`spark/spark.go` 与 `ray/ray.go` 则分别面向 Spark on K8s 与 Ray on K8s 两种 Operator 模式，复用 pluginmachinery 的 `BuildResource` 接口生成 `SparkApplication`、`RayJob` 资源。

资料来源：[flyteplugins/go/tasks/plugins/k8s/pod/plugin.go]()、[flyteplugins/go/tasks/plugins/k8s/spark/spark.go]()、[flyteplugins/go/tasks/plugins/k8s/ray/ray.go]()

### 社区扩展与生态

Flyteplugins 目录本身就是社区贡献插件的容器——例如 Gojek 团队提交的 DBT 插件（见社区 issue #2202）。这种**核心契约 + 外部扩展**的架构让 ML/数据团队可以针对自家栈快速发布插件而无需修改 Flyte 主体。

资料来源：[flyteplugins/README.md]()、[社区 issue #2202](https://github.com/flyteorg/flyte/issues/2202)

### 共享支撑库

任务插件在读写对象存储、加载配置、生成 CLI flag 时统一依赖 `flytestdlib`，后者封装了：

- **storage**：基于 `stow` 的抽象层，支持 S3 / Azure Blob / GCS，并提供内存实现用于测试。
- **config**：强类型配置 + 动态 watch。
- **cli/pflags**：从 Go 结构体自动生成 pflags。

资料来源：[flytestdlib/README.md]()

## 端到端任务流

```mermaid
sequenceDiagram
    participant U as 用户/SDK
    participant P as Propeller
    participant R as Plugin Registry
    participant Plg as Task Plugin
    participant E as Executor CRD
    participant K as K8s API

    U->>P: 提交工作流
    P->>R: 按 TaskType 查找插件
    R-->>P: 返回 Plugin 实例
    P->>Plg: BuildResource(taskCtx)
    Plg-->>P: 返回 Resource (Pod/Spark/Ray/...)
    P->>E: 创建 TaskAction CR
    E->>K: Apply 子资源 (Pod/SparkApp)
    K-->>E: 状态更新
    E-->>P: Condition + Phase
    P->>Plg: GetTaskPhase(ctx)
    Plg-->>P: PhaseSuccess / PhaseFailure
```

## 常见配置与失败模式

| 场景 | 现象 | 排查路径 |
| --- | --- | --- |
| 插件未注册 | 调度时找不到 TaskType 处理器 | 检查 `registry.go` 与启动日志 |
| 阶段停滞在 Initializing | 通常为镜像拉取或 Secret 挂载失败 | 查看 `app_definition_pb2.py` 中 `IMAGE_PULL_ERROR` / `SECRET_MOUNT_ERROR` substate |
| Spark/Ray 插件 OOM | 资源声明不足 | 通过 issue #475 提议的 overrides 接口动态调整 |
| 失败节点缺失 | 工作流级错误无法捕获 | 跟踪社区 issue #1506 的 Failure-Node 支持 |
| 通知通道受限 | PagerDuty/Slack 仅支持 email API | 跟踪 issue #2317 中 Webhook 化进展 |

## 社区热点与演进方向

根据社区讨论，用户关注的主要方向包括：

- **#475 通用执行覆盖**：希望在执行时动态覆盖资源、retries、Spark config 等参数，无需重新注册。
- **#1506 Failure-Node 暴露**：在 flytekit 中暴露后端已有的失败节点能力。
- **#2202 DBT 插件**：由 Gojek 贡献，作为首个第三方社区插件范本。
- **#2317 Webhook 通知**：替换当前的 PagerDuty/GitHub/Slack email-only 通知路径。
- **#2772 生产级 CI/CD**：参考 Lyft 案例建立端到端流水线。

这些方向都与 Plugin Machinery 的可扩展性直接相关，构成了未来演进路线图。资料来源：[README.md]() 及上述社区 issue。

## See Also

- [FlytePropeller 调度架构](FlytePropeller-Scheduling-Architecture.md)
- [FlyteAdmin 通知系统](FlyteAdmin-Notifications.md)
- [FlyteIDL v2 协议](FlyteIDL-v2-Protocol.md)
- [flytekit Python SDK](Flytekit-Python-SDK.md)

---

<a id='page-4'></a>

## Data Plane, Storage, IDL, and Deployment

### 相关页面

相关主题：[Flyte 2 Backend Overview & System Architecture](#page-1), [Core Backend Services (runs, dataproxy, cache, events, app, actions, secret)](#page-2), [Plugin Machinery, Executor & Task Plugins](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/flyteorg/flyte/blob/main/README.md)
- [flyteidl2/gen_utils/rust/src/lib.rs](https://github.com/flyteorg/flyte/blob/main/flyteidl2/gen_utils/rust/src/lib.rs)
- [flyteidl2/gen_utils/rust/src/google.rpc.rs](https://github.com/flyteorg/flyte/blob/main/flyteidl2/gen_utils/rust/src/google.rpc.rs)
- [gen/go/flyteidl2/app/app_definition.pb.go](https://github.com/flyteorg/flyte/blob/main/gen/go/flyteidl2/app/app_definition.pb.go)
- [gen/python/flyteidl2/app/app_definition_pb2.py](https://github.com/flyteorg/flyte/blob/main/gen/python/flyteidl2/app/app_definition_pb2.py)
- [gen/ts/flyteidl2/app/app_definition_pb.ts](https://github.com/flyteorg/flyte/blob/main/gen/ts/flyteidl2/app/app_definition_pb.ts)
- [gen/ts/flyteidl2/app/app_logs_payload_pb.ts](https://github.com/flyteorg/flyte/blob/main/gen/ts/flyteidl2/app/app_logs_payload_pb.ts)
- [gen/go/gateway/flyteidl2/app/app_logs_service.swagger.json](https://github.com/flyteorg/flyte/blob/main/gen/go/gateway/flyteidl2/app/app_logs_service.swagger.json)
- [gen/go/gateway/flyteidl2/app/app_definition.swagger.json](https://github.com/flyteorg/flyte/blob/main/gen/go/gateway/flyteidl2/app/app_definition.swagger.json)
- [app/internal/k8s/app_client.go](https://github.com/flyteorg/flyte/blob/main/app/internal/k8s/app_client.go)
- [flytecopilot/README.md](https://github.com/flyteorg/flyte/blob/main/flytecopilot/README.md)
- [executor/README.md](https://github.com/flyteorg/flyte/blob/main/executor/README.md)
- [flytestdlib/README.md](https://github.com/flyteorg/flyte/blob/main/flytestdlib/README.md)
</details>

# 数据平面、存储、IDL 与部署

## 概述

Flyte 是一个面向机器学习和数据处理工作流的开源编排平台，其仓库采用 monorepo 形式组织，将控制平面（flyteadmin、flytepropeller）、数据平面（datacatalog、co-pilot）、共享库（flytestdlib）以及接口定义（flyteidl / flyteidl2）整合在同一个代码库中 [README.md](https://github.com/flyteorg/flyte/blob/main/README.md)。在这种布局下，本页重点说明四个相互协作的子系统：用于跨语言、跨服务通信的接口定义语言（IDL），用于任务输入输出持久化的存储抽象，运行在工作负载 Pod 中的辅助代理（co-pilot），以及负责将自定义资源部署到 Kubernetes 的执行器（executor）。

最新发布版本为 v2.0.24，更新中包含对 `sigs.k8s.io/controller-runtime` 与 `k8s.io/client-go` 的依赖升级，以及对 CI 工作流取消策略的调整 [README.md](https://github.com/flyteorg/flyte/blob/main/README.md)。这些发布活动表明数据平面与部署组件仍在持续演进。

## 接口定义语言（IDL 与 flyteidl2）

`flyteidl2` 是仓库中用于描述工作流、任务、应用、状态等核心实体的 Protocol Buffers 定义集合。原始 `.proto` 文件经过代码生成后，输出到多个语言目标：

| 目标 | 示例输出路径 | 主要用途 |
| --- | --- | --- |
| Go | [gen/go/flyteidl2/app/app_definition.pb.go](https://github.com/flyteorg/flyte/blob/main/gen/go/flyteidl2/app/app_definition.pb.go) | 后端服务（flyteadmin、datacatalog）使用 |
| Python | [gen/python/flyteidl2/app/app_definition_pb2.py](https://github.com/flyteorg/flyte/blob/main/gen/python/flyteidl2/app/app_definition_pb2.py) | flytekit 客户端以及数据平面脚本使用 |
| TypeScript | [gen/ts/flyteidl2/app/app_definition_pb.ts](https://github.com/flyteorg/flyte/blob/main/gen/ts/flyteidl2/app/app_definition_pb.ts) | 控制台 / Web UI 使用 |
| Rust | [flyteidl2/gen_utils/rust/src/google.rpc.rs](https://github.com/flyteorg/flyte/blob/main/flyteidl2/gen_utils/rust/src/google.rpc.rs) | 性能敏感的组件原型验证 |

为保证多语言生成结果一致，仓库通过 [`flyteidl2/gen_utils/rust/src/lib.rs`](https://github.com/flyteorg/flyte/blob/main/flyteidl2/gen_utils/rust/src/lib.rs) 中的 `OUT_DIR` 机制将生成的 Rust 模块嵌入二进制，并集中暴露常用类型。该文件中的注释还提到在 Rust 模块内 `pub use flyteidl::common::*` 等语句曾被考虑用于顶层重导出，体现 IDL 的“单一事实源”理念。Go 端则使用 `protoimpl.X.CompressGZIP` 缓存原始描述符，以减少启动时的反射开销 [gen/go/flyteidl2/app/app_definition.pb.go](https://github.com/flyteorg/flyte/blob/main/gen/go/flyteidl2/app/app_definition.pb.go)。

在网关层，REST 描述由相应的 `.swagger.json` 文件提供，例如 [gen/go/gateway/flyteidl2/app/app_definition.swagger.json](https://github.com/flyteorg/flyte/blob/main/gen/go/gateway/flyteidl2/app/app_definition.swagger.json) 和 [gen/go/gateway/flyteidl2/app/app_logs_service.swagger.json](https://github.com/flyteorg/flyte/blob/main/gen/go/gateway/flyteidl2/app/app_logs_service.swagger.json)。这些文档通过 gRPC-Gateway 暴露应用生命周期、复制状态和日志尾随等接口，使 SDK 与控制台可以一致地访问后端。

## 数据平面与存储

`flytestdlib` 提供 Flyte 各服务共享的运行时原语，其 README 明确指出其中包含 `config`（强类型配置加载与监听）、`cli/pflags`（命令行参数生成）以及 `storage`（基于 [stow](https://github.com/graymeta/stow) 的多云对象存储抽象、内存存储以及原生 Protobuf 支持）三个核心包 [flytestdlib/README.md](https://github.com/flyteorg/flyte/blob/main/flytestdlib/README.md)。

存储抽象屏蔽了 S3、Azure Blob、GCS、本地文件系统之间的差异，使得任务输入、输出与缓存能够跨云迁移。配合 [`flyteidl2/gen_utils/rust/src/google.rpc.rs`](https://github.com/flyteorg/flyte/blob/main/flyteidl2/gen_utils/rust/src/google.rpc.rs) 中的 `google.rpc.Status` 定义，后端能够以标准化的错误码、消息与详情负载在数据平面服务之间传递故障，便于在 S3 / GCS 凭证失效或下载失败时定位问题。

## 工作负载代理（Flyte CoPilot）

`flytecopilot` 是一个与用户容器同 Pod 运行的辅助代理二进制，其设计目标是让任意容器都能接入 Flyte 的元数据协议。它提供两种运行模式 [flytecopilot/README.md](https://github.com/flyteorg/flyte/blob/main/flytecopilot/README.md)：

- **Downloader（下载器）**：在 Kubernetes 中以 `initContainer` 方式运行，将任务的输入数据和元数据预先下载到与主容器共享的卷中。
- **Sidecar（边车）**：与主容器并行运行，识别主容器、等待其启动、监听其退出，并将卷中产生的数据上传回对象存储，再写回元数据。

README 中还讨论了实现选择：通过轮询 Kubernetes API 来发现主容器状态，或要求主容器在退出时写入 `_SUCCESS` 标志文件。后者依赖文件系统约定，无法覆盖 OOM 等异常退出场景，因此实际实现多以轮询为主。CoPilot 是数据平面的关键环节，使 Spark、Ray、DBT 等外部执行器能够复用同一套输入输出与缓存管线（社区 #2202 即讨论如何将 DBT 任务接入该管线）。

## 部署组件（Executor 与应用控制器）

`executor` 是一个遵循 Kubebuilder 模式构建的 Kubernetes Operator/Controller，它负责将 `Application` 类型的自定义资源调和到底层工作负载。仓库提供了两种安装方式：通过 `make build-installer` 生成的 `install.yaml` 直接 `kubectl apply`，或通过 `kubebuilder edit --plugins=helm/v1-alpha` 生成 Helm Chart [executor/README.md](https://github.com/flyteorg/flyte/blob/main/executor/README.md)。

在内部，应用控制器根据 CR 的规约创建并管理底层资源，例如 Knative Service。`app/internal/k8s/app_client.go` 中的 `buildAutoscalingAnnotations` 函数将 IDL 中描述的自动扩缩参数映射为 Knative 注解：当用户配置最小/最大副本数时，写入 `autoscaling.knative.dev/min-scale` 与 `autoscaling.knative.dev/max-scale`；当指定 RPS 或并发度指标时，分别设置 `metric=rps` 或 `metric=concurrency`；`ScaledownPeriod` 字段则转换为 `autoscaling.knative.dev/window` [app/internal/k8s/app_client.go](https://github.com/flyteorg/flyte/blob/main/app/internal/k8s/app_client.go)。这种设计使得用户在 IDL 中声明的扩缩策略无需重新注册即可生效，与社区 #475 关于“执行期间覆盖配置”的诉求相吻合。

对于应用的状态展示，IDL 提供了 `DeploymentStatus` 与 `Substate` 两层枚举。前者覆盖 UNSPECIFIED、UNASSIGNED、ASSIGNED、PENDING、STOPPED、STARTED、FAILED、ACTIVE、SCALING_UP、SCALING_DOWN、DEPLOYING 等高层阶段；后者（SUBSTATE_UNSPECIFIED、PULLING_IMAGE、INITIALIZING、WEBHOOK_ERROR、IMAGE_PULL_ERROR、SECRET_MOUNT_ERROR、CRASH_LOOP、OOM_KILLED）则用于在 FAILED 状态下进一步区分原因，便于在控制台定位镜像拉取失败或 Webhook 错误等问题 [gen/python/flyteidl2/app/app_definition_pb2.py](https://github.com/flyteorg/flyte/blob/main/gen/python/flyteidl2/app/app_definition_pb2.py)。

## 数据流概览

```mermaid
flowchart LR
    A[用户 SDK<br/>flytekit] --> B[flyteadmin]
    B --> C[flytepropeller]
    C --> D[Executor / 应用控制器]
    D --> E[Knative Service]
    E --> F[CoPilot Sidecar]
    F --> G[对象存储<br/>S3/GCS/Azure]
    G --> H[datacatalog<br/>缓存与血统]
    H --> C
    B -. REST/gRPC .-> I[控制台<br/>TypeScript SDK]
```

如上图所示，SDK 通过 IDL 序列化的工作流定义经 flyteadmin 注册，由 flytepropeller 调度，最终由应用控制器在集群中创建 Knative Service；CoPilot 负责在容器与对象存储之间搬运数据，datacatalog 则记录中间结果供后续执行复用。社区 #1506 讨论的 Failure-Node 与 #2317 讨论的 Webhook 通知扩展分别会在 propeller 与 admin 层面增加新的执行分支与回调入口，但不会破坏这张主干数据流。

## 常见问题与失败模式

- **镜像或密钥挂载失败**：Substate 枚举中的 `IMAGE_PULL_ERROR` 与 `SECRET_MOUNT_ERROR` 通常意味着 ServiceAccount 或 Secret 未在目标命名空间中创建，可通过 `kubectl describe` 进一步确认 [gen/python/flyteidl2/app/app_definition_pb2.py](https://github.com/flyteorg/flyte/blob/main/gen/python/flyteidl2/app/app_definition_pb2.py)。
- **OOM 或崩溃循环**：`OOM_KILLED` 与 `CRASH_LOOP` 子状态会通过 `Condition` 消息中的 `message` 字段返回人类可读的诊断信息 [gen/ts/flyteidl2/app/app_definition_pb.ts](https://github.com/flyteorg/flyte/blob/main/gen/ts/flyteidl2/app/app_definition_pb.ts)。
- **日志尾随接口**：TypeScript 端通过 `TailLogsRequest` 的 `oneof` 同时支持 `app_id` 和 `replica_id` 两种目标，日志后端会据此路由到对应的复制状态 [gen/ts/flyteidl2/app/app_logs_payload_pb.ts](https://github.com/flyteorg/flyte/blob/main/gen/ts/flyteidl2/app/app_logs_payload_pb.ts)。
- **生产 CI/CD**：社区 #2772 建议参考 Lyft 的 MLOps 流水线，将 Flyte 部署纳入独立的 GitHub Actions 仓库，从而在多环境之间复用同一套发布契约。

## 另请参阅

- [Flyte 官方文档](https://docs.flyte.org/)
- [datacatalog 子项目](https://github.com/flyteorg/flyte/tree/master/datacatalog)
- [flytepropeller 子项目](https://github.com/flyteorg/flyte/tree/master/flytepropeller)
- [flytekit 客户端 SDK](https://github.com/flyteorg/flytekit)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：flyteorg/flyte

摘要：发现 7 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安装坑 - 来源证据：Fix typo: rename ActionMetadata.funtion_name → function_name (proto, backend, SDK stubs)。

## 1. 安装坑 · 来源证据：Fix typo: rename ActionMetadata.funtion_name → function_name (proto, backend, SDK stubs)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Fix typo: rename ActionMetadata.funtion_name → function_name (proto, backend, SDK stubs)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/flyteorg/flyte/issues/7558 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/flyteorg/flyte | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/flyteorg/flyte | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/flyteorg/flyte | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/flyteorg/flyte | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/flyteorg/flyte | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/flyteorg/flyte | release_recency=unknown

<!-- canonical_name: flyteorg/flyte; human_manual_source: deepwiki_human_wiki -->