# https://github.com/kestra-io/kestra 项目说明书

生成时间：2026-06-21 08:36:26 UTC

## 目录

- [Project Overview & System Architecture](#page-1)
- [Core Engine: Flows, Executor, Scheduler & Worker](#page-2)
- [Webserver API, Storage Layer & Plugin Ecosystem](#page-3)
- [Frontend UI, CLI, Deployment & Operations](#page-4)

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

## Project Overview & System Architecture

### 相关页面

相关主题：[Core Engine: Flows, Executor, Scheduler & Worker](#page-2), [Webserver API, Storage Layer & Plugin Ecosystem](#page-3), [Frontend UI, CLI, Deployment & Operations](#page-4)

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

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

- [README.md](https://github.com/kestra-io/kestra/blob/main/README.md)
- [ui/packages/design-system/package.json](https://github.com/kestra-io/kestra/blob/main/ui/packages/design-system/package.json)
- [cli/src/main/java/io/kestra/cli/AbstractCommand.java](https://github.com/kestra-io/kestra/blob/main/cli/src/main/java/io/kestra/cli/AbstractCommand.java)
- [cli/src/main/java/io/kestra/cli/commands/servers/AbstractServerCommand.java](https://github.com/kestra-io/kestra/blob/main/cli/src/main/java/io/kestra/cli/commands/servers/AbstractServerCommand.java)
- [cli/src/main/java/io/kestra/cli/commands/sys/SysCommand.java](https://github.com/kestra-io/kestra/blob/main/cli/src/main/java/io/kestra/cli/commands/sys/SysCommand.java)
- [cli/src/main/java/io/kestra/cli/commands/sys/ReindexCommand.java](https://github.com/kestra-io/kestra/blob/main/cli/src/main/java/io/kestra/cli/commands/sys/ReindexCommand.java)
- [jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java)
- [jdbc-h2/src/main/java/io/kestra/repository/h2/H2LogRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-h2/src/main/java/io/kestra/repository/h2/H2LogRepository.java)
- [jdbc-h2/src/main/java/io/kestra/repository/h2/H2MetricRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-h2/src/main/java/io/kestra/repository/h2/H2MetricRepository.java)
- [jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java)
- [jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlLogRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlLogRepository.java)
- [jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlFlowTopologyRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlFlowTopologyRepository.java)
</details>

# 项目概览与系统架构

## 一、项目定位与核心能力

Kestra 是一款**开源、事件驱动的编排平台**，专注于数据、AI 与基础设施工作流的统一调度。它将定时调度（scheduled）与事件驱动（event-driven）自动化合并在同一个声明式、语言无关的接口背后，主张以"基础设施即代码"（Infrastructure as Code）的最佳实践来管理数据、流程与微服务流水线。开发者可以直接在 UI 中使用少量 YAML 定义工作流，也可以将工作流纳入 Git 版本控制、CI/CD、Terraform 或 API 进行管理。

平台的设计哲学建立在以下几个核心能力之上：

- **Everything as Code & from the UI**：工作流始终以 YAML 描述，UI 的所有变更会自动同步到代码层面，避免"代码与界面"两套事实来源。
- **事件驱动 + 定时调度混合**：通过简单的 `trigger` 定义即可启动实时或定时执行。
- **丰富的插件生态**：内置数百个插件，覆盖各类数据库、云存储、API 与多语言脚本执行。
- **可视化拓扑编辑器**：内置代码编辑器支持语法高亮、实时校验、自动补全与 DAG 拓扑展示。
- **可扩展性**：设计目标是处理百万级工作流，配备高可用与容错机制。

资料来源：[README.md](https://github.com/kestra-io/kestra/blob/main/README.md)

## 二、多模块系统架构

Kestra 采用 Gradle 多模块架构，按职责将代码切分为若干 Maven/Gradle 子项目。下表列出了与本次概览直接相关的模块及其代表源码：

| 模块 | 职责 | 代表源码文件 |
| --- | --- | --- |
| `core` | 领域模型（Flow、Execution、LogEntry、MetricEntry 等）、执行器、调度器与插件 SPI | 由 `jdbc-*` 模块引用 |
| `cli` | 提供 `kestra` 命令行入口，含服务器启动、系统维护等子命令 | [cli/src/main/java/io/kestra/cli/AbstractCommand.java](https://github.com/kestra-io/kestra/blob/main/cli/src/main/java/io/kestra/cli/AbstractCommand.java) |
| `jdbc-h2` | 内嵌 H2 数据库适配层，用于本地开发与单机模式 | [jdbc-h2/src/main/java/io/kestra/repository/h2/H2LogRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-h2/src/main/java/io/kestra/repository/h2/H2LogRepository.java) |
| `jdbc-mysql` | MySQL 数据库适配层，提供生产级持久化能力 | [jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java) |
| `ui` | 基于 Vue + Element Plus 的前端与独立 `@kestra-io/design-system` 组件库 | [ui/packages/design-system/package.json](https://github.com/kestra-io/kestra/blob/main/ui/packages/design-system/package.json) |

整体架构通过分层抽象实现"核心域逻辑与数据库实现解耦"。`core` 模块定义抽象 Repository 接口，由 `jdbc-h2` 与 `jdbc-mysql` 分别继承 `AbstractJdbcDashboardRepository`、`AbstractJdbcLogRepository`、`AbstractJdbcMetricRepository` 等抽象类，再在方言层（dialect-specific repository）覆盖 `findCondition`、`formatDateField`、`buildMergeStatement` 等方言相关行为，例如：

```java
@RepositoryBean
@MysqlRepositoryEnabled
public class MysqlFlowTopologyRepository extends AbstractJdbcFlowTopologyRepository {
    @Override
    protected DMLQuery<Record> buildMergeStatement(DSLContext context, FlowTopology flowTopology) {
        return context.insertInto(this.jdbcRepository.getTable())
            .set(AbstractJdbcRepository.field("key"), this.jdbcRepository.key(flowTopology))
            .set(this.jdbcRepository.persistFields(flowTopology))
            .onDuplicateKeyUpdate()
            .set(this.jdbcRepository.persistFields(flowTopology));
    }
}
```

这种"抽象基类 + 方言子类"的模式使得切换底层数据库只需替换模块依赖，无需改动业务层代码。

资料来源：[jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlFlowTopologyRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlFlowTopologyRepository.java)、[jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlLogRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlLogRepository.java)

### 运行时组件关系图

```mermaid
flowchart LR
    UI[UI / 设计系统] -->|HTTP API| Server[Kestra Server<br/>core + cli]
    CLI[kestra CLI] -->|启动/管理| Server
    Server -->|jOOQ DSL| JDBC[(JDBC 抽象层)]
    JDBC --> H2[jdbc-h2]
    JDBC --> MySQL[jdbc-mysql]
    Server --> Plugins[插件生态<br/>core plugins]
    Server -->|事件流| Queue[(JDBC Queue<br/>H2/MySQL)]
    Queue --> Scheduler[Scheduler]
    Queue --> Executor[Executor]
    Executor --> Worker[Worker]
```

## 三、关键子系统与组件

### 3.1 命令行（CLI）子系统

CLI 模块负责启动服务进程以及执行离线维护命令。所有命令都继承自 `AbstractCommand`，后者负责加载外部 YAML 配置、注册 shutdown hook 与统一日志风格：

```java
@SuppressWarnings({ "unused" })
public Map<String, Object> propertiesFromConfig() {
    if (this.config.toFile().exists()) {
        YamlPropertySourceLoader yamlPropertySourceLoader = new YamlPropertySourceLoader();
        try {
            return yamlPropertySourceLoader.read("cli", new FileInputStream(this.config.toFile()));
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
    return ImmutableMap.of();
}
```

`AbstractServerCommand` 在 `call()` 中注册基于 `KestraContext` 的优雅关闭钩子，并在启动时打印 CPU、内存与 Java 版本等机器信息，便于运维定位环境差异：

```java
this.shutdownHook(true, () -> KestraContext.getContext().shutdown());
```

`SysCommand` 通过 picocli 的 `@CommandLine.Command` 聚合了 `ReindexCommand` 与 `SubmitQueuedCommand` 两个维护子命令：

```java
@CommandLine.Command(
    name = "sys",
    description = "Manage system maintenance mode",
    subcommands = { ReindexCommand.class, SubmitQueuedCommand.class }
)
```

其中 `ReindexCommand` 会读取所有 Flow 并调用 `FlowService.update` 进行全量重建索引，目前仅支持 `flow` 类型。

资料来源：[cli/src/main/java/io/kestra/cli/AbstractCommand.java](https://github.com/kestra-io/kestra/blob/main/cli/src/main/java/io/kestra/cli/AbstractCommand.java)、[cli/src/main/java/io/kestra/cli/commands/servers/AbstractServerCommand.java](https://github.com/kestra-io/kestra/blob/main/cli/src/main/java/io/kestra/cli/commands/servers/AbstractServerCommand.java)、[cli/src/main/java/io/kestra/cli/commands/sys/SysCommand.java](https://github.com/kestra-io/kestra/blob/main/cli/src/main/java/io/kestra/cli/commands/sys/SysCommand.java)、[cli/src/main/java/io/kestra/cli/commands/sys/ReindexCommand.java](https://github.com/kestra-io/kestra/blob/main/cli/src/main/java/io/kestra/cli/commands/sys/ReindexCommand.java)

### 3.2 持久化层（JDBC 方言）

JDBC 层基于 jOOQ，根据所选数据库方言提供具体实现。下表对比 H2 与 MySQL 两种方言的差异点：

| 组件 | H2 实现 | MySQL 实现 |
| --- | --- | --- |
| Dashboard Repository | `H2DashboardRepository`，复用 `AbstractJdbcDashboardRepository`，通过 `H2DashboardRepositoryService.findCondition` 处理查询 | `MysqlDashboardRepository`，依赖 `MysqlDashboardRepositoryService.findCondition` |
| Log Repository | `H2LogRepository`，针对 `fulltext` 单列进行全文检索 | `MysqlLogRepository`，对 `namespace / flow_id / task_id / execution_id / taskrun_id / trigger_id / message / thread` 多列构造 `fullTextCondition` |
| Metric Repository | `H2MetricRepository`，委托 `H2RepositoryUtils.formatDateField` 处理日期分组 | `MySQL` 模块同样委托方言工具类处理日期字段 |
| Flow Topology | 仅 `MysqlFlowTopologyRepository` 通过 `buildMergeStatement` 实现 `INSERT ... ON DUPLICATE KEY UPDATE` 的合并语义 | 同上 |

这一层在 v1.x 系列的多项发布中得到加固，例如 1.3.23 / 1.2.22 / 1.0.47 等版本都修复了"JDBC queue consumer 在瞬时数据库错误下保持存活"的问题，体现出对生产稳定性的持续投入。

资料来源：[jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java)、[jdbc-h2/src/main/java/io/kestra/repository/h2/H2LogRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-h2/src/main/java/io/kestra/repository/h2/H2LogRepository.java)、[jdbc-h2/src/main/java/io/kestra/repository/h2/H2MetricRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-h2/src/main/java/io/kestra/repository/h2/H2MetricRepository.java)、[jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java)、[jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlLogRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlLogRepository.java)

### 3.3 前端与设计系统

`@kestra-io/design-system` 是独立发布的 Vue 3 + Element Plus 组件抽象层，对外提供统一的入口、组件及样式导出：

```json
"exports": {
    ".": "./src/index.ts",
    "./components/*": "./src/components/*",
    "./src/assets/styles/*": "./src/assets/styles/*",
    "./package.json": "./package.json"
}
```

依赖项包含 `vueuse`、`playwright`、`storybook`、`vite`、`vitest`、`vue-router`、`sass` 等现代化前端工具链，并使用 `storybook:test` + `vitest` 做组件级与浏览器级双轨验证。

资料来源：[ui/packages/design-system/package.json](https://github.com/kestra-io/kestra/blob/main/ui/packages/design-system/package.json)

## 四、社区关注的能力演进

围绕本主题，社区在 GitHub 上提出了若干高频诉求，并已在不同版本中得到部分回应：

- **并发限制（Concurrency Limits）**：#1400 长期呼吁对单个 Flow 在调度层的并发执行数量做限制。v1.x 系列中的 JDBC queue consumer 健壮性提升（#16816 / #16814 / #16815）以及任务重试与超时增强，都间接服务于该需求。
- **过滤器能力（Filters EPIC）**：#15952 汇总了 Filter 后端演进；近期版本已落地多个 UI 行为修复，例如 Dashboard 快速过滤器"All 为空但状态 Tab 有数据"（#16812）与"快速时间区间与条件组不匹配"（#16433）。
- **日志图表交互**：#16603 提议在日志时序图上提供 Grafana / GCP / PostHog 风格的时间窗拖拽选区。
- **Flow 模板与模板化**：#4956 希望支持按配置动态调整 Flow 模板。
- **IDE 集成扩展**：#3060 提议在 JetBrains IDE 中提供与 VS Code 同等的 LSP 集成。
- **IaC 多生态**：#3016 推动 Pulumi Provider，补充既有的 Terraform Provider。

## See Also

- Plugin Developer Guide：https://kestra.io/docs/plugin-developer-guide/
- Terraform Provider：https://kestra.io/docs/terraform/
- Contributing Guide：https://kestra.io/docs/contribute-to-kestra
- Plugins Catalog：https://kestra.io/plugins

---

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

## Core Engine: Flows, Executor, Scheduler & Worker

### 相关页面

相关主题：[Project Overview & System Architecture](#page-1), [Webserver API, Storage Layer & Plugin Ecosystem](#page-3)

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

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

- [README.md](https://github.com/kestra-io/kestra/blob/develop/README.md)
- [cli/src/main/java/io/kestra/cli/commands/sys/ReindexCommand.java](https://github.com/kestra-io/kestra/blob/develop/cli/src/main/java/io/kestra/cli/commands/sys/ReindexCommand.java)
- [jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlExecutionRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlExecutionRepository.java)
- [jdbc-h2/src/main/java/io/kestra/repository/h2/H2ExecutionRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-h2/src/main/java/io/kestra/repository/h2/H2ExecutionRepository.java)
- [jdbc-h2/src/main/java/io/kestra/repository/h2/H2TriggerRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-h2/src/main/java/io/kestra/repository/h2/H2TriggerRepository.java)
- [jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java)
- [jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java)
- [jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlFlowTopologyRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlFlowTopologyRepository.java)
- [jdbc-postgres/src/main/java/io/kestra/repository/postgres/PostgresFlowTopologyRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-postgres/src/main/java/io/kestra/repository/postgres/PostgresFlowTopologyRepository.java)
- [ui/packages/topology/package.json](https://github.com/kestra-io/kestra/blob/develop/ui/packages/topology/package.json)
- [ui/packages/design-system/package.json](https://github.com/kestra-io/kestra/blob/develop/ui/packages/design-system/package.json)
- [charts/kestra-starter/README.md](https://github.com/kestra-io/kestra/blob/develop/charts/kestra-starter/README.md)
</details>

# Core Engine: Flows, Executor, Scheduler & Worker

## 概述

Kestra 的核心引擎是整个工作流编排平台的中枢，它将声明式 YAML 描述的工作流转化为可调度、可执行、可观测的运行实例。[README.md](https://github.com/kestra-io/kestra/blob/develop/README.md) 将 Kestra 定位为 "Event-Driven Declarative Orchestrator"，强调以单一 YAML 入口统一 **计划式** 与 **事件驱动** 两种自动化模式。核心引擎由四个相互协作的子系统组成：

- **Flows（工作流）**：YAML 形式的声明式工作流，承载任务、触发器、输入、输出等所有编排逻辑。
- **Executor（执行器）**：根据已加载的 Flow 创建 Execution 对象，并驱动任务在 Worker 上派发与状态推进。
- **Scheduler（调度器）**：解析 Flow 中 `triggers` 的计划与事件条件，激活 Execution。
- **Worker（工作节点）**：真正运行 TaskRunner 的进程，承载用户任务逻辑（脚本、API、SQL 等）。

这四者通过 JDBC 持久化层与事件总线解耦，并对外暴露 CLI、HTTP API 与 UI 三个交互入口。

## 核心数据模型与生命周期

核心引擎的所有行为都围绕一组核心模型展开，下图展示了它们之间的关系：

```mermaid
graph LR
    Flow[Flow<br/>YAML 声明] -->|由 Scheduler 激活| Execution[Execution<br/>运行实例]
    Trigger[Trigger<br/>计划 / 事件] -->|匹配| Flow
    Execution -->|派发任务| Worker[Worker 任务执行]
    Worker -->|回写状态| Execution
    Dashboard[Dashboard<br/>观测面板] -->|查询| Execution
    Topology[FlowTopology<br/>依赖图] -->|派生| Flow
```

- **Flow** 是用户在 UI、Git、CLI 中定义的工作流。
- **Execution** 由 Executor 创建并保存到 JDBC 仓库。例如 [MysqlExecutionRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlExecutionRepository.java) 与 [H2ExecutionRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-h2/src/main/java/io/kestra/repository/h2/H2ExecutionRepository.java) 都继承自 `AbstractJdbcExecutionRepository`，并注入 `ApplicationEventPublisher<CrudEvent<Execution>>` 以广播增删改事件。
- **Trigger** 由 [H2TriggerRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-h2/src/main/java/io/kestra/repository/h2/H2TriggerRepository.java) 持久化，其 `formatDateField` 支持按周/月分桶，正是 Scheduler 进行时间窗口查询的基础。
- **Dashboard** 与 **FlowTopology** 分别由 Dashboard / Topology 仓库维护，前端通过 [ui/packages/topology/package.json](https://github.com/kestra-io/kestra/blob/develop/ui/packages/topology/package.json) 中描述的 "Kestra flow topology graph component – powered by Vue Flow" 进行可视化。

## JDBC 持久化层

Kestra 通过 jOOQ 在不同数据库后端实现核心引擎的数据持久化。每个领域对象（Execution、Trigger、Dashboard、FlowTopology）都通过 `AbstractJdbc*Repository` 基类定义通用行为，再由各数据库提供方言特定实现。下表概括了三种后端的差异点：

| 后端 | 启用注解 | 合并/更新语法 | 状态分桶 |
| --- | --- | --- | --- |
| H2 | `@H2RepositoryEnabled` | 默认 jOOQ 实现 | `formatDateField` 在 `H2RepositoryUtils` 中实现 |
| MySQL | `@MysqlRepositoryEnabled` | `onDuplicateKeyUpdate()` 见 [MysqlFlowTopologyRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlFlowTopologyRepository.java) | 直接委托基类 |
| PostgreSQL | `@PostgresRepositoryEnabled` | `onConflict(...).doUpdate()` 见 [PostgresFlowTopologyRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-postgres/src/main/java/io/kestra/repository/postgres/PostgresFlowTopologyRepository.java) | 由 `weekFromTimestamp` 等 jOOQ 函数提供 |

[JdbcFilterService](https://github.com/kestra-io/kestra) 注入到 H2 与 MySQL 的 Execution / Trigger 仓库中，提供了标签、字段、状态等过滤能力的 SQL 翻译，对应社区 EPIC [#15952 "Filters, backend changes needed for filter"](https://github.com/kestra-io/kestra/issues/15952) 所推动的能力。[H2DashboardRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java) 与 [MysqlDashboardRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java) 都接收 `List<QueryBuilderInterface<?>> queryBuilders`，便于在不改 Repository 的前提下扩展 Dashboard 查询。

## CLI 运维入口

核心引擎的运维能力通过 [cli/src/main/java/io/kestra/cli/commands/sys/ReindexCommand.java](https://github.com/kestra-io/kestra/blob/develop/cli/src/main/java/io/kestra/cli/commands/sys/ReindexCommand.java) 暴露。`kestra sys reindex` 命令支持重建索引：当前实现仅支持 `--type flow`，它从 `FlowRepositoryInterface` 读取所有租户下的 Flow，再调用 `FlowService.update(GenericFlow.of(flow), flow)`，用于将数据库中的最新 YAML 同步到下游索引（ElasticSearch 等）。当索引漂移或新加索引字段时，这是最常用的修复入口。

## 部署与可视化

核心引擎的部署依托 [charts/kestra-starter/README.md](https://github.com/kestra-io/kestra/blob/develop/charts/kestra-starter/README.md) 中的 Helm Chart `kestra-starter`，用于在 Kubernetes 上一键部署。前端层面，UI 的基础组件来自 [ui/packages/design-system/package.json](https://github.com/kestra-io/kestra/blob/develop/ui/packages/design-system/package.json)（"Kestra UI Design System – component abstractions over Element Plus"）；工作流的 DAG 视图由 [ui/packages/topology](https://github.com/kestra-io/kestra/blob/develop/ui/packages/topology/package.json) 提供。

## 常见问题与社区关注

- **并发限制（[#1400](https://github.com/kestra-io/kestra/issues/1400)）**：社区长期要求在 Flow 级别限制并发 Execution 数，核心引擎在派发 Execution 至 Worker 时需考虑此约束。
- **过滤器（[EPIC #15952](https://github.com/kestra-io/kestra/issues/15952)）**：JDBC 层已通过 `JdbcFilterService` 支持多条件过滤，但 UI 上的"快速时间区间选择器"与"条件组合"还存在不一致，参见 [issue #16433](https://github.com/kestra-io/kestra/issues/16433)。
- **JDBC 队列消费者**：v1.0.47、v1.2.22、v1.3.23 等多个版本均修复了 "keep JDBC queue consumer alive on transient DB errors"，说明 Executor 与 Worker 通过 JDBC 队列通信时对瞬时错误敏感，建议在生产环境为数据库启用重试与连接保活。
- **执行回放（[#16906](https://github.com/kestra-io/kestra/issues/16906)）**：批量 replay 的后端端点已存在，仅缺 UI 入口。
- **模板可配置（[#4956](https://github.com/kestra-io/kestra/issues/4956)）**：希望根据租户/命名空间对 Flow 模板做差异化处理，属于核心引擎解析 Flow 阶段需要扩展的能力。

## See Also

- Plugin System（插件系统）
- JDBC 与 Elasticsearch Repository 详解
- UI Topology Graph 组件
- 部署与高可用（Helm Chart）

---

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

## Webserver API, Storage Layer & Plugin Ecosystem

### 相关页面

相关主题：[Core Engine: Flows, Executor, Scheduler & Worker](#page-2), [Frontend UI, CLI, Deployment & Operations](#page-4)

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

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

- [README.md](https://github.com/kestra-io/kestra/blob/main/README.md)
- [cli/src/main/java/io/kestra/cli/Kestra.java](https://github.com/kestra-io/kestra/blob/main/cli/src/main/java/io/kestra/cli/Kestra.java)
- [cli/src/main/java/io/kestra/cli/commands/plugins/PluginSearchCommand.java](https://github.com/kestra-io/kestra/blob/main/cli/src/main/java/io/kestra/cli/commands/plugins/PluginSearchCommand.java)
- [jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java)
- [jdbc-h2/src/main/java/io/kestra/repository/h2/H2LogRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-h2/src/main/java/io/kestra/repository/h2/H2LogRepository.java)
- [jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java)
- [jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlFlowTopologyRepository.java](https://github.com/kestra-io/kestra/blob/main/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlFlowTopologyRepository.java)
- [ui/package.json](https://github.com/kestra-io/kestra/blob/main/ui/package.json)
- [ui/packages/design-system/package.json](https://github.com/kestra-io/kestra/blob/main/ui/packages/design-system/package.json)
- [ui/packages/slot-contracts/package.json](https://github.com/kestra-io/kestra/blob/main/ui/packages/slot-contracts/package.json)
- [ui/packages/topology/package.json](https://github.com/kestra-io/kestra/blob/main/ui/packages/topology/package.json)
- [charts/kestra/README.md](https://github.com/kestra-io/kestra/blob/main/charts/kestra/README.md)
</details>

# Webserver API、存储层与插件生态系统

## 概述

Kestra 是一个开源的工作流编排平台，遵循"一切皆代码、一切皆 UI"的设计理念。它将 Webserver API、JDBC 存储层以及插件生态作为其核心三大支柱：API 层暴露 REST 端点供 UI 与外部系统调用，存储层通过 jOOQ 抽象支持 H2 与 MySQL 等多种后端，插件生态则通过 CLI、设计系统与插槽协议实现前后端协同扩展。

资料来源：[README.md:1-30]()、[/cli/src/main/java/io/kestra/cli/Kestra.java:1-45]()

## Webserver API 层

Webserver 模块使用 Micronaut 框架作为底层，通过一组 `@Controller` 注解的控制器对外提供 RESTful API。常见的控制器包括 Flow、Execution、Log、Dashboard 与 McpServer 等。这些控制器均位于 `webserver/src/main/java/io/kestra/webserver/controllers/api/` 目录下，遵循统一的 URL 前缀约定（如 `/api/v1/...`）并通过依赖注入的方式使用下层 Repository。

资料来源：[README.md:90-120]()

API 端点不仅供前端 UI 使用，也对 Terraform Provider、Pulumi Provider（社区在 issue #3016 中呼吁增加支持）以及 IDE 插件开放，从而实现基础设施即代码的工作流管理。

## 存储层（JDBC 抽象）

存储层采用"接口-实现"的分层模式。核心抽象位于 `io.kestra.jdbc.repository` 包，具体的数据库方言实现则分别放在 `jdbc-h2` 与 `jdbc-mysql` 等独立模块中。

以 Dashboard 存储为例，`AbstractJdbcDashboardRepository` 提供通用 CRUD、查询构建器注入与 `CrudEvent` 事件发布能力。`H2DashboardRepository` 与 `MysqlDashboardRepository` 各自继承该抽象类，并通过覆盖 `findCondition(String query)` 方法实现方言特定的全文检索条件。

```java
资料来源：[jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java:21-30]()
@RepositoryBean
@H2RepositoryEnabled
public class H2DashboardRepository extends AbstractJdbcDashboardRepository { ... }
```

类似的模式也出现在 `H2LogRepository`（使用 `fullTextCondition` 实现日志查询）与 `MysqlFlowTopologyRepository`（使用 `insertInto(...).onDuplicateKeyUpdate()` 实现拓扑合并）中。

资料来源：[jdbc-h2/src/main/java/io/kestra/repository/h2/H2LogRepository.java:18-32]()、[/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlFlowTopologyRepository.java:18-30]()

## 插件生态系统

Kestra 的插件生态由 CLI、设计系统包、插槽契约包以及拓扑组件包共同组成。

### CLI 插件检索

`PluginSearchCommand` 是一个 picocli 子命令，它通过内部 `HttpClient`（`@Client("api")`）调用后端 `/v1/plugins` 端点，对返回的 JSON 进行关键字匹配与格式化输出，方便用户在终端中按名称搜索可用插件。

资料来源：[/cli/src/main/java/io/kestra/cli/commands/plugins/PluginSearchCommand.java:18-50]()

### 前端包家族

`ui/packages/` 目录下多个子包通过独立 `package.json` 声明其职责：

| 包名 | 角色 | 关键依赖 |
| --- | --- | --- |
| `@kestra-io/design-system` | 基于 Element Plus 的组件抽象，附带 Storybook 文档 | vue、storybook、vite-plugin-dts |
| `@kestra-io/slot-contracts` | 联邦插件 UI 插槽的共享类型定义 | zod、ts-morph |
| `@kestra-io/topology` | 基于 Vue Flow 的工作流 DAG 渲染 | vue-flow、vue |

资料来源：[/ui/packages/design-system/package.json:1-40]()、[/ui/packages/slot-contracts/package.json:1-30]()、[/ui/packages/topology/package.json:1-30]()

### Helm 部署契约

`charts/kestra/README.md` 中的 `values.yaml` 暴露了与 API/存储层紧密相关的运行参数，如 `livenessProbe`、`readinessProbe`（健康端点 `/health/liveness` 与 `/health/readiness`），便于 Kubernetes 环境对 Webserver 与 JDBC 连接进行存活探针配置。

资料来源：[/charts/kestra/README.md:10-25]()

## 组件协同关系

```mermaid
flowchart LR
  UI[Vue UI + Design System] -->|HTTPS| API[Webserver Controllers]
  CLI[Kestra CLI / PluginSearch] -->|/v1/plugins| API
  API --> Repo[AbstractJdbc* Repository]
  Repo -->|jOOQ| H2[(H2)]
  Repo -->|jOOQ| MySQL[(MySQL)]
  Slot[slot-contracts] -.类型契约.-> UI
  Helm[Helm Chart] -.部署.-> API
```

## 社区关注点

- **IDE 集成**：社区长期呼吁在 JetBrains 平台提供官方支持（参考 issue #3060），其底层同样依赖 Webserver API。
- **自动补全**：issue #3331 提议在 `{{ inputs. }}`、`{{ outputs. }}` 等位置提供输入、输出、触发器与变量的自动补全，需前后端协同改造。
- **过滤器增强**：issue #15952 追踪过滤器后端改造，要求存储层 Repository 暴露更丰富的查询能力。

## See Also

- [Kestra README](https://github.com/kestra-io/kestra/blob/main/README.md)
- [Kestra Plugin Developer Guide](https://kestra.io/docs/plugin-developer-guide/)

---

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

## Frontend UI, CLI, Deployment & Operations

### 相关页面

相关主题：[Project Overview & System Architecture](#page-1), [Core Engine: Flows, Executor, Scheduler & Worker](#page-2), [Webserver API, Storage Layer & Plugin Ecosystem](#page-3)

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

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

- [README.md](https://github.com/kestra-io/kestra/blob/develop/README.md)
- [ui/packages/design-system/package.json](https://github.com/kestra-io/kestra/blob/develop/ui/packages/design-system/package.json)
- [cli/src/main/java/io/kestra/cli/AbstractCommand.java](https://github.com/kestra-io/kestra/blob/develop/cli/src/main/java/io/kestra/cli/AbstractCommand.java)
- [cli/src/main/java/io/kestra/cli/commands/sys/SysCommand.java](https://github.com/kestra-io/kestra/blob/develop/cli/src/main/java/io/kestra/cli/commands/sys/SysCommand.java)
- [jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java)
- [jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java)
- [charts/kestra/README.md](https://github.com/kestra-io/kestra/blob/develop/charts/kestra/README.md)
- [charts/kestra-starter/README.md](https://github.com/kestra-io/kestra/blob/develop/charts/kestra-starter/README.md)

</details>

# 前端 UI、CLI、部署与运维

Kestra 是一个开源的事件驱动声明式编排平台，本页聚焦于用户日常交互与运维操作的三大入口：**Web 前端 UI**、**命令行 CLI** 与**生产环境部署/运维**。这三层构成了开发者从本地试用到大规模生产运行的完整链路。

## 概述与高层架构

Kestra 的整体定位是「数据、AI 与基础设施工作流的统一编排平台」，README 中明确强调 *Everything as Code*、事件驱动调度、声明式 YAML、可视化 UI 与插件生态三大支柱。([README.md](https://github.com/kestra-io/kestra/blob/develop/README.md))

```mermaid
flowchart LR
    A[开发者<br/>本地浏览器] --> B[Frontend UI<br/>Vue 3 + Design System]
    B --> C[REST API<br/>Kestra Server]
    D[运维<br/>终端] --> E[CLI<br/>picocli]
    E --> C
    C --> F[JDBC 存储层<br/>H2 / MySQL / PostgreSQL]
    G[Kubernetes / Docker] --> C
    H[Helm Chart<br/>charts/kestra] --> G
```

三层入口最终汇聚到同一个 Kestra Server 与底层 JDBC 仓储（`AbstractJdbcDashboardRepository` 等抽象基类同时被 H2 与 MySQL 复用），保证 UI 操作、CLI 命令与部署行为对后端的影响是统一的。([jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-h2/src/main/java/io/kestra/repository/h2/H2DashboardRepository.java), [jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java](https://github.com/kestra-io/kestra/blob/develop/jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java))

## 前端 UI 与设计系统

Kestra 前端基于 Vue 3 构建，并通过名为 `@kestra-io/design-system` 的内部包对 Element Plus 进行统一封装，输出可复用的组件、样式与类型。([ui/packages/design-system/package.json](https://github.com/kestra-io/kestra/blob/develop/ui/packages/design-system/package.json))

| 关注点 | 实现位置 | 说明 |
| --- | --- | --- |
| 组件库抽象 | `ui/packages/design-system/src/components/*` | 通过 `exports` 字段将组件与样式分别导出 |
| 文档/演示 | Storybook 10 (`storybook` 脚本) | 端口 6007，提供 a11y、docs、themes 等插件 |
| 单元测试 | Vitest 4 (`unit:test`) + Playwright 浏览器驱动 | 同时覆盖 happy-dom 与 jsdom 环境 |
| 构建工具 | tsdown + vite-plugin-vue + vite-plugin-dts | 输出 ESM 与 `.d.ts` 类型声明 |

UI 在 `package.json` 中显式声明 `"description": "Kestra UI Design System – component abstractions over Element Plus"`，可见设计系统的定位是「在 Element Plus 之上做业务级抽象」，让上层页面（Flows、Executions、Dashboard、Logs）可以保持一致的视觉与交互。([ui/packages/design-system/package.json](https://github.com/kestra-io/kestra/blob/develop/ui/packages/design-system/package.json))

社区讨论中频繁出现的 UI 痛点也与该层直接相关，例如：

- **执行批量回放按钮缺失** [#16906](https://github.com/kestra-io/kestra/issues/16906)：后端 API 已就绪，仅需在 Flow 的 Executions 页面增加触发按钮，属于典型的 Design System + 业务组件组合需求。
- **Dashboard 执行快筛"All 为空"** [#16812](https://github.com/kestra-io/kestra/issues/16812)：Dashboard 小部件的快筛 Tab（All / Running / Paused / Success / Warning / Failed）在 "All" 下无数据而按状态筛选却有结果，是数据查询条件与组件状态未对齐的典型 UI Bug。
- **日志图表拖选时间区间** [#16603](https://github.com/kestra-io/kestra/issues/16603)：期望仿照 Grafana/GCP/PostHog 实现拖拽框选时间窗口，这同样依赖 Design System 暴露的图表组件能力。
- **Flow 模板按配置调整** [#4956](https://github.com/kestra-io/kestra/issues/4956)：希望基于 OSS/EE 配置动态生成默认 Flow 模板，属于 Editor 组件层增强。
- **快速区间选择器与条件分组冲突** [#16433](https://github.com/kestra-io/kestra/issues/16433)：Filters 中的 15m/1h 快捷时间选择器与 OR/AND 条件分组功能不适配，是 Design System 中筛选组件需要扩展的场景。

## 命令行 CLI

CLI 模块以 `picocli` 作为命令解析框架，根命令为 `Kestra`，所有命令都继承 `AbstractCommand` 以统一处理配置加载、优雅停机与日志等横切关注点。([cli/src/main/java/io/kestra/cli/AbstractCommand.java](https://github.com/kestra-io/kestra/blob/develop/cli/src/main/java/io/kestra/cli/AbstractCommand.java))

```bash
# 启动本地 standalone 服务（与 README 中的 Docker 体验等价）
kestra server local

# 进入系统维护模式
kestra sys reindex
kestra sys submit-queued
```

`SysCommand` 通过 `subcommands` 字段聚合 `ReindexCommand` 与 `SubmitQueuedCommand`，分别用于**重建索引**与**提交滞留队列中的任务**，是运维场景中最常用的两个高危命令。([cli/src/main/java/io/kestra/cli/commands/sys/SysCommand.java](https://github.com/kestra-io/kestra/blob/develop/cli/src/main/java/io/kestra/cli/commands/sys/SysCommand.java))

`AbstractCommand#propertiesFromConfig` 通过 `YamlPropertySourceLoader` 读取 `--config` 指向的 YAML，将配置注入到 Kestra 运行时。该机制在 v1.3.23 中得到修复（`4e75d21 recover --config option when placed before subcommand`），说明早期 `--config` 必须放在子命令之后才能生效，升级后位置不再受限。([v1.3.23](https://github.com/kestra-io/kestra/releases/tag/v1.3.23))

CLI 还在 v1.3.20 中为元数据迁移命令增加了 `--tenant` 选项（`37a4f56`），方便多租户场景下针对单一租户执行迁移。([v1.3.20](https://github.com/kestra-io/kestra/releases/tag/v1.3.20))

## 部署与运维

Kestra 提供多种生产部署路径：

- **Docker 单机**：README 给出的标准命令 `docker run --pull=always -it -p 8080:8080 --user=root --name kestra --restart=always -v kestra_data:/app/storage -v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp kestra/kestra:latest server local` 用于本地 5 分钟上手。([README.md](https://github.com/kestra-io/kestra/blob/develop/README.md))
- **AWS CloudFormation**：通过 `kestra-deployment-templates` 仓库一键拉起 EC2 + RDS + S3 拓扑。
- **GCP Terraform**：通过 Infrastructure Manager 的 Terraform 模块部署到 GCP。
- **Kubernetes Helm Chart**：`charts/kestra` 与 `charts/kestra-starter` 两个 chart 分别面向完整版与入门版。([charts/kestra/README.md](https://github.com/kestra-io/kestra/blob/develop/charts/kestra/README.md), [charts/kestra-starter/README.md](https://github.com/kestra-io/kestra/blob/develop/charts/kestra-starter/README.md))

Helm chart 的健康检查路径是运维自动化的关键：`livenessProbe` 指向 `/health/liveness`、`readinessProbe` 指向 `/health/readiness`、`startupProbe` 指向 `/health`，三者使用 `management` 端口。Chart 在 v1.0.0 引入了多项破坏性变更，例如 `image.image` → `image.repository` 与 `serviceAccountName` → `serviceAccount.{create,automount,annotations,name}`，升级前需对照 README 的迁移说明。([charts/kestra/README.md](https://github.com/kestra-io/kestra/blob/develop/charts/kestra/README.md))

运维层面最近的稳定性改进集中在 JDBC 队列消费者：

- v1.3.23 (`42cb301`)：修复 JDBC 队列消费者在瞬态 DB 错误时崩溃的问题。
- v1.2.22 (`31dcef8`)：同一修复被反向移植到 1.2.x 分支。
- v1.0.47 (`4cccc93`)：同样反向移植到 1.0.x 分支。

这意味着只要是 1.0.47、1.2.22、1.3.23 及以上版本，JDBC 队列在数据库抖动后将自动重连，而不再退出进程。

## 社区关注与典型故障模式

来自社区的高互动 Issue 显示，前端 UI 与 CLI/部署是用户感知最强的两块：

| 议题 | 区域 | 影响 |
| --- | --- | --- |
| [#16906](https://github.com/kestra-io/kestra/issues/16906) 批量回放按钮 | Frontend | 缺失 UI 入口，但后端 API 已具备 |
| [#16812](https://github.com/kestra-io/kestra/issues/16812) Dashboard "All" 空 | Frontend | 条件筛选组件 bug |
| [#16433](https://github.com/kestra-io/kestra/issues/16433) 快捷区间与条件分组冲突 | Frontend | 筛选组件需扩展 |
| [#4956](https://github.com/kestra-io/kestra/issues/4956) Flow 模板按配置调整 | Frontend | Editor 模板生成 |
| [#15952](https://github.com/kestra-io/kestra/issues/15952) Filters 后端改动 EPIC | Backend + Frontend | 筛选能力底座升级 |
| JDBC 队列消费者断连（v1.3.23 / v1.2.22 / v1.0.47） | Runtime | 升级对应版本即可解决 |

部署侧的常见踩坑点是：**Helm Chart 0.x → 1.0 的字段重命名**（`image`、`serviceAccount`）、**JDBC 队列消费者存活**（升级到上述固定版本）、以及 **CLI `--config` 位置**（v1.3.23 之前的限制）。

## See Also

- [Plugin 开发者指南](https://kestra.io/docs/plugin-developer-guide/)：扩展 Kestra 任务与触发器。
- [Terraform Provider](https://kestra.io/docs/terraform/)：以 IaC 方式管理 Flow。
- [Pulumi 桥接 #3016](https://github.com/kestra-io/kestra/issues/3016)：社区请求将 Terraform Provider 桥接到 Pulumi。
- [并发执行限制 #1400](https://github.com/kestra-io/kestra/issues/1400)：运行时并发策略讨论。
- [JetBrains IDE 支持 #3060](https://github.com/kestra-io/kestra/issues/3060)：在前端 IDE 体验之外的编辑器集成诉求。

---

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

---

## Doramagic 踩坑日志

项目：kestra-io/kestra

摘要：发现 27 个潜在踩坑项，其中 2 个为 high/blocking；最高优先级：安装坑 - 来源证据：Namespace files: filename with space collides with literal '+' → silent overwrite / data loss。

## 1. 安装坑 · 来源证据：Namespace files: filename with space collides with literal '+' → silent overwrite / data loss

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Namespace files: filename with space collides with literal '+' → silent overwrite / data loss
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/kestra-io/kestra/issues/16896 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 维护坑 · 来源证据：Logs chart: drag-to-select time-range brush (Grafana/GCP/PostHog style)

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Logs chart: drag-to-select time-range brush (Grafana/GCP/PostHog style)
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/kestra-io/kestra/issues/16603 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安装坑 · 依赖 Docker 环境

- 严重度：medium
- 证据强度：runtime_trace
- 发现：安装/运行入口包含 Docker 命令：docker run --pull=always -it -p 8080:8080 --user=root --name kestra --restart=always -v kestra_data:/app/storage -v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp kestra/kestra:latest server local
- 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
- 复现命令：`docker run --pull=always -it -p 8080:8080 --user=root --name kestra --restart=always -v kestra_data:/app/storage -v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp kestra/kestra:latest server local`
- 证据：identity.distribution | https://github.com/kestra-io/kestra | docker run --pull=always -it -p 8080:8080 --user=root --name kestra --restart=always -v kestra_data:/app/storage -v /var/run/docker.sock:/var/run/docker.sock -v /tmp:/tmp kestra/kestra:latest server local

## 4. 安装坑 · 失败模式：installation: v0.22.44

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v0.22.44
- 对用户的影响：Upgrade or migration may change expected behavior: v0.22.44
- 证据：failure_mode_cluster:github_release | https://github.com/kestra-io/kestra/releases/tag/v0.22.44 | v0.22.44

## 5. 安装坑 · 来源证据：[Filters] Quick interval selector doesn't fit conditional groups

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Filters] Quick interval selector doesn't fit conditional groups
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/kestra-io/kestra/issues/16433 | 来源类型 github_issue 暴露的待验证使用条件。

## 6. 配置坑 · 失败模式：configuration: Allow adjusting the flow template based on configuration

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Allow adjusting the flow template based on configuration
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Allow adjusting the flow template based on configuration
- 证据：failure_mode_cluster:github_issue | https://github.com/kestra-io/kestra/issues/4956 | Allow adjusting the flow template based on configuration

## 7. 配置坑 · 失败模式：configuration: v1.0.46

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.0.46
- 对用户的影响：Upgrade or migration may change expected behavior: v1.0.46
- 证据：failure_mode_cluster:github_release | https://github.com/kestra-io/kestra/releases/tag/v1.0.46 | v1.0.46

## 8. 配置坑 · 失败模式：configuration: v1.3.20

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.3.20
- 对用户的影响：Upgrade or migration may change expected behavior: v1.3.20
- 证据：failure_mode_cluster:github_release | https://github.com/kestra-io/kestra/releases/tag/v1.3.20 | v1.3.20

## 9. 配置坑 · 失败模式：configuration: v1.3.21

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.3.21
- 对用户的影响：Upgrade or migration may change expected behavior: v1.3.21
- 证据：failure_mode_cluster:github_release | https://github.com/kestra-io/kestra/releases/tag/v1.3.21 | v1.3.21

## 10. 配置坑 · 失败模式：configuration: v1.3.22

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.3.22
- 对用户的影响：Upgrade or migration may change expected behavior: v1.3.22
- 证据：failure_mode_cluster:github_release | https://github.com/kestra-io/kestra/releases/tag/v1.3.22 | v1.3.22

## 11. 配置坑 · 失败模式：configuration: v1.3.23

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v1.3.23
- 对用户的影响：Upgrade or migration may change expected behavior: v1.3.23
- 证据：failure_mode_cluster:github_release | https://github.com/kestra-io/kestra/releases/tag/v1.3.23 | v1.3.23

## 12. 配置坑 · 来源证据：Dashboard "Executions" quick-filter: the "All" tab is empty while state tabs show executions

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Dashboard "Executions" quick-filter: the "All" tab is empty while state tabs show executions
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/kestra-io/kestra/issues/16812 | 来源类型 github_issue 暴露的待验证使用条件。

## 13. 配置坑 · 来源证据：[Filters] Quick interval selector doesn't fit conditional groups

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Filters] Quick interval selector doesn't fit conditional groups
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/kestra-io/kestra/issues/16433 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

## 15. 运行坑 · 失败模式：runtime: Dashboard "Executions" quick-filter: the "All" tab is empty while state tabs show executions

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this runtime risk before relying on the project: Dashboard "Executions" quick-filter: the "All" tab is empty while state tabs show executions
- 对用户的影响：Developers may hit a documented source-backed failure mode: Dashboard "Executions" quick-filter: the "All" tab is empty while state tabs show executions
- 证据：failure_mode_cluster:github_issue | https://github.com/kestra-io/kestra/issues/16812 | Dashboard "Executions" quick-filter: the "All" tab is empty while state tabs show executions

## 16. 维护坑 · 失败模式：migration: v1.2.22

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v1.2.22
- 对用户的影响：Upgrade or migration may change expected behavior: v1.2.22
- 证据：failure_mode_cluster:github_release | https://github.com/kestra-io/kestra/releases/tag/v1.2.22 | v1.2.22

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

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

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

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

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

## 20. 能力坑 · 失败模式：capability: Add bulk-replay on Flow's Executions tab

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Add bulk-replay on Flow's Executions tab
- 对用户的影响：Developers may hit a documented source-backed failure mode: Add bulk-replay on Flow's Executions tab
- 证据：failure_mode_cluster:github_issue | https://github.com/kestra-io/kestra/issues/16906 | Add bulk-replay on Flow's Executions tab

## 21. 能力坑 · 失败模式：capability: Logs chart: drag-to-select time-range brush (Grafana/GCP/PostHog style)

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Logs chart: drag-to-select time-range brush (Grafana/GCP/PostHog style)
- 对用户的影响：Developers may hit a documented source-backed failure mode: Logs chart: drag-to-select time-range brush (Grafana/GCP/PostHog style)
- 证据：failure_mode_cluster:github_issue | https://github.com/kestra-io/kestra/issues/16603 | Logs chart: drag-to-select time-range brush (Grafana/GCP/PostHog style)

## 22. 运行坑 · 失败模式：performance: [Filters] Quick interval selector doesn't fit conditional groups

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: [Filters] Quick interval selector doesn't fit conditional groups
- 对用户的影响：Developers may hit a documented source-backed failure mode: [Filters] Quick interval selector doesn't fit conditional groups
- 证据：failure_mode_cluster:github_issue | https://github.com/kestra-io/kestra/issues/16433 | [Filters] Quick interval selector doesn't fit conditional groups

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

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

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

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

## 25. 维护坑 · 失败模式：maintenance: v1.0.47

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.0.47
- 对用户的影响：Upgrade or migration may change expected behavior: v1.0.47
- 证据：failure_mode_cluster:github_release | https://github.com/kestra-io/kestra/releases/tag/v1.0.47 | v1.0.47

## 26. 维护坑 · 失败模式：maintenance: v1.1.20

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.1.20
- 对用户的影响：Upgrade or migration may change expected behavior: v1.1.20
- 证据：failure_mode_cluster:github_release | https://github.com/kestra-io/kestra/releases/tag/v1.1.20 | v1.1.20

## 27. 维护坑 · 失败模式：maintenance: v1.2.21

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v1.2.21
- 对用户的影响：Upgrade or migration may change expected behavior: v1.2.21
- 证据：failure_mode_cluster:github_release | https://github.com/kestra-io/kestra/releases/tag/v1.2.21 | v1.2.21

<!-- canonical_name: kestra-io/kestra; human_manual_source: deepwiki_human_wiki -->