项目概览与系统架构

一、项目定位与核心能力

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

二、多模块系统架构

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

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

@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、jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlLogRepository.java

运行时组件关系图

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 与统一日志风格：

@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 版本等机器信息，便于运维定位环境差异：

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

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

@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、cli/src/main/java/io/kestra/cli/commands/servers/AbstractServerCommand.java、cli/src/main/java/io/kestra/cli/commands/sys/SysCommand.java、cli/src/main/java/io/kestra/cli/commands/sys/ReindexCommand.java

3.2 持久化层（JDBC 方言）

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

这一层在 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、jdbc-h2/src/main/java/io/kestra/repository/h2/H2LogRepository.java、jdbc-h2/src/main/java/io/kestra/repository/h2/H2MetricRepository.java、jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlDashboardRepository.java、jdbc-mysql/src/main/java/io/kestra/repository/mysql/MysqlLogRepository.java

3.3 前端与设计系统

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

"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

四、社区关注的能力演进

围绕本主题，社区在 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

概述

Kestra 的核心引擎是整个工作流编排平台的中枢，它将声明式 YAML 描述的工作流转化为可调度、可执行、可观测的运行实例。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 三个交互入口。

核心数据模型与生命周期

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

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 与 H2ExecutionRepository.java 都继承自 AbstractJdbcExecutionRepository，并注入 ApplicationEventPublisher<CrudEvent<Execution>> 以广播增删改事件。
• Trigger 由 H2TriggerRepository.java 持久化，其 formatDateField 支持按周/月分桶，正是 Scheduler 进行时间窗口查询的基础。
• Dashboard 与 FlowTopology 分别由 Dashboard / Topology 仓库维护，前端通过 ui/packages/topology/package.json 中描述的 "Kestra flow topology graph component – powered by Vue Flow" 进行可视化。

JDBC 持久化层

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

JdbcFilterService 注入到 H2 与 MySQL 的 Execution / Trigger 仓库中，提供了标签、字段、状态等过滤能力的 SQL 翻译，对应社区 EPIC #15952 "Filters, backend changes needed for filter" 所推动的能力。H2DashboardRepository.java 与 MysqlDashboardRepository.java 都接收 List<QueryBuilderInterface<?>> queryBuilders，便于在不改 Repository 的前提下扩展 Dashboard 查询。

CLI 运维入口

核心引擎的运维能力通过 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 中的 Helm Chart kestra-starter，用于在 Kubernetes 上一键部署。前端层面，UI 的基础组件来自 ui/packages/design-system/package.json（"Kestra UI Design System – component abstractions over Element Plus"）；工作流的 DAG 视图由 ui/packages/topology 提供。

常见问题与社区关注

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

See Also

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

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) 方法实现方言特定的全文检索条件。

资料来源：[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 声明其职责：

资料来源：/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

组件协同关系

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
• Kestra Plugin Developer Guide

前端 UI、CLI、部署与运维

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

概述与高层架构

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

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

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)

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

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

命令行 CLI

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

# 启动本地 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)

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

CLI 还在 v1.3.20 中为元数据迁移命令增加了 --tenant 选项（37a4f56），方便多租户场景下针对单一租户执行迁移。(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)
• 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, 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)

运维层面最近的稳定性改进集中在 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/部署是用户感知最强的两块：

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

See Also

• Plugin 开发者指南：扩展 Kestra 任务与触发器。
• Terraform Provider：以 IaC 方式管理 Flow。
• Pulumi 桥接 #3016：社区请求将 Terraform Provider 桥接到 Pulumi。
• 并发执行限制 #1400：运行时并发策略讨论。
• JetBrains IDE 支持 #3060：在前端 IDE 体验之外的编辑器集成诉求。

Pitfall Log / 踩坑日志

项目：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