# https://github.com/conductor-oss/conductor 项目说明书

生成时间：2026-06-19 03:02:16 UTC

## 目录

- [项目概览](#page-overview)
- [Src 模块](#page-common-src)
- [Src 模块](#page-postgres-persistence-src)
- [Src 模块](#page-scheduler-core-src)

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

## 项目概览

### 相关页面

相关主题：[Src 模块](#page-common-src)

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

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

- [README.md](https://github.com/conductor-oss/conductor/blob/main/README.md)
- [ai/examples/README.md](https://github.com/conductor-oss/conductor/blob/main/ai/examples/README.md)
- [kafka/README.md](https://github.com/conductor-oss/conductor/blob/main/kafka/README.md)
- [annotations-processor/README.md](https://github.com/conductor-oss/conductor/blob/main/annotations-processor/README.md)
- [schemas/README.md](https://github.com/conductor-oss/conductor/blob/main/schemas/README.md)
- [es8-persistence/README.md](https://github.com/conductor-oss/conductor/blob/main/es8-persistence/README.md)
- [ui-next/package.json](https://github.com/conductor-oss/conductor/blob/main/ui-next/package.json)
- [common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskType.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskType.java)
- [common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java)
- [common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskResult.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskResult.java)
- [common/src/main/java/com/netflix/conductor/common/run/TaskSummary.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/run/TaskSummary.java)
- [common/src/main/java/org/conductoross/conductor/common/JsonSchemaValidator.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/org/conductoross/conductor/common/JsonSchemaValidator.java)

</details>

# 项目概览

## 项目定位与目标

Conductor 是一个开源的**工作流编排引擎**，源自 Netflix，最初用于支撑 Netflix Media Data Pipeline 等大规模微服务编排场景。项目迁移到 `conductor-oss` 组织后由社区维护，定位为"编排即服务"（Orchestration-as-a-Service）平台，让开发者以声明式 JSON 定义复杂业务流程，并由引擎负责任务调度、状态持久化、重试、超时与事件处理等横切关注点。资料来源：[README.md](https://github.com/conductor-oss/conductor/blob/main/README.md)

项目核心入口是 Conductor Server，使用 Spring Boot 构建；与之配套的还包括官方提供的多种语言 SDK（Java、Python、Go、Node、C#、Rust 等），由仓库顶部的 SDK 链接矩阵列出。资料来源：[README.md](https://github.com/conductor-oss/conductor/blob/main/README.md)

## 核心特性与功能模块

### 任务模型与内置任务类型

Conductor 的核心抽象是 `Task`（任务）与 `Workflow`（工作流）。`TaskType` 枚举集中维护了系统支持的全部任务类型常量，覆盖控制流类（`DECISION`、`SWITCH`、`FORK_JOIN`、`DO_WHILE`、`JOIN`、`EXCLUSIVE_JOIN`）、集成类（`HTTP`、`KAFKA_PUBLISH`、`JSON_JQ_TRANSFORM`、`SET_VARIABLE`）、子流程类（`SUB_WORKFLOW`、`START_WORKFLOW`）以及近期新增的 AI 类（`LLM_TEXT_COMPLETE`、`LLM_CHAT_COMPLETE`、`LLM_INDEX_TEXT`、`LLM_SEARCH_INDEX`、`LLM_GENERATE_EMBEDDINGS`、`LLM_STORE_EMBEDDINGS`、`LLM_GET_EMBEDDINGS`、`LIST_MCP_TOOLS`、`CALL_MCP_TOOL`、`PULL_WORKFLOW_MESSAGES`）等。资料来源：[common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskType.java:1-50](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskType.java)

任务运行时通过 `Task` 实体承载输入输出、状态、重试次数、调度时间等元数据；`TaskResult` 描述工作线程上报的执行结果，可指定 `callbackAfterSeconds` 实现"延迟回调"，让长任务在指定秒数内保留在队列不被其他 worker 抢占。资料来源：[common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskResult.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskResult.java)

### Schema 校验与 AI 扩展

仓库提供 `schemas/` 目录下的 JSON Schema（`WorkflowDef.json`、`TaskDef.json`、`Workflow.json`、`Task.json`）用于在注册工作流前进行结构和字段约束校验，全部遵循 **JSON Schema Draft 07** 规范。`JsonSchemaValidator` 基于 `networknt/json-schema-validator` 封装，可在服务端或客户端复用同一套校验逻辑。资料来源：[schemas/README.md](https://github.com/conductor-oss/conductor/blob/main/schemas/README.md) 与 [common/src/main/java/org/conductoross/conductor/common/JsonSchemaValidator.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/org/conductoross/conductor/common/JsonSchemaValidator.java)

`ai/examples/` 目录提供超过 20 个工作流示例，覆盖 Chat Completion、代码沙盒执行、扩展思考、联网研究、Multi-turn 链式调用等典型 LLM 场景，并提供 `curl` 注册/执行/查询的快速入门脚本。资料来源：[ai/examples/README.md](https://github.com/conductor-oss/conductor/blob/main/ai/examples/README.md)

### 注解处理与外部集成

`annotations-processor` 模块负责从注解生成 Protobuf 文件，为 gRPC 接口提供类型化消息；`kafka` 模块发布 `conductor-task` 工件，包含 `JSON_JQ_TRANSFORM_TASK` 等社区贡献系统任务；`es8-persistence` 单独提供对 Elasticsearch 8 的兼容实现，使用 `elasticsearch-java` 8.19.x 客户端与 ILM 策略（`max_primary_shard_size=50gb`）。资料来源：[annotations-processor/README.md](https://github.com/conductor-oss/conductor/blob/main/annotations-processor/README.md)、[kafka/README.md](https://github.com/conductor-oss/conductor/blob/main/kafka/README.md) 与 [es8-persistence/README.md](https://github.com/conductor-oss/conductor/blob/main/es8-persistence/README.md)

## 系统架构与可插拔后端

### 模块化组成

仓库根目录按职能拆分为多个 Gradle 子工程：`conductor-server`（主程序）、`conductor-common`（公共模型）、`conductor-core`（执行引擎）、`conductor-redis`、`postgres`、`mysql`（队列/状态后端）、`es7-persistence`/`es8-persistence`（索引后端）、`awss3-storage`、`awssqs-event-queue`（外部存储与事件队列）、`kafka`、`ai`、`ui-next`（新版基于 React 18 + MUI v7 + XState 的 Web 控制台）。资料来源：[README.md](https://github.com/conductor-oss/conductor/blob/main/README.md) 与 [ui-next/package.json](https://github.com/conductor-oss/conductor/blob/main/ui-next/package.json)

### 后端配置矩阵

启动时通过 `conductor.indexing.type` 等属性选择具体后端实现。下表总结官方维护的配置组合：

| 后端组合 | 配置文件 | 说明 |
|---------|---------|------|
| Redis + ES7（默认） | `config-redis.properties` | 最常见的组合 |
| Redis + ES8 | `config-redis-es8.properties` | 需配合 `-PindexingBackend=elasticsearch8` 构建 |
| Redis + OpenSearch | `config-redis-os.properties` | OpenSearch 兼容模式 |
| Postgres（独立） | `config-postgres.properties` | 使用关系库同时承担队列与索引 |
| Postgres + ES7 | `config-postgres-es7.properties` | 关系库 + ES 索引 |
| MySQL + ES7 | `config-mysql.properties` | MySQL 队列 + ES 索引 |

资料来源：[README.md](https://github.com/conductor-oss/conductor/blob/main/README.md) 与 [es8-persistence/README.md](https://github.com/conductor-oss/conductor/blob/main/es8-persistence/README.md)

### 序列化与 Proto 兼容

`common` 模块的 `JsonProtoModule` 为 Jackson 提供自定义 Protobuf `Any` 编码策略，使 gRPC 接口暴露的 `Any` 消息能够以 `@type` 字段形式在 REST API 中透明传递，避免在服务端枚举全部可能的内嵌类型。资料来源：[common/src/main/java/com/netflix/conductor/common/jackson/JsonProtoModule.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/jackson/JsonProtoModule.java)

## 社区关注的问题与最佳实践

围绕本仓库，社区主要反馈集中在以下几类：

1. **Elasticsearch 8 兼容性**：Issue #49 长期跟踪 ES8 支持进度，目前已由独立 `es8-persistence` 模块实现（使用 `elasticsearch-java` 8.19.x 客户端和 ILM 策略）。资料来源：[es8-persistence/README.md](https://github.com/conductor-oss/conductor/blob/main/es8-persistence/README.md) 与社区 Issue #49。
2. **构建与运行 Java 版本一致性**：Issue #711 指出 `docker/server/Dockerfile` 早期使用 Java 17 而 `build.gradle` 要求 Java 21，升级前应确认镜像与工具链一致。资料来源：社区 Issue #711。
3. **ES7 Docker 配置缺项**：Issue #928 提示 `docker/server/config` 中的 ES7 样例缺少 `conductor.indexing.type=elasticsearch`，未设置时 Spring 不会装配 `IndexDAO` Bean，导致启动失败。资料来源：社区 Issue #928。
4. **子工作流挂起**：Issue #712 报告 v3.21.23 之后子工作流完成后父工作流不继续推进，可通过 `POST /api/workflow/decide/{workflowId}` 触发决策。资料来源：社区 Issue #712。
5. **ES7 索引膨胀**：Issue #226 指出 `ElasticSearchRestDAOV7` 早期实现会按日期持续创建 `conductor_task_log_YYYYMMDD` 索引并积累数千分片，推荐使用 ILM + rollover 控制（参考 `es8-persistence` 的 `max_primary_shard_size=50gb` 策略）。资料来源：社区 Issue #226 与 [es8-persistence/README.md](https://github.com/conductor-oss/conductor/blob/main/es8-persistence/README.md)。

最新发布 `v3.31.0-rc.4` 包含了 test-harness 修复、UI 切换到 `ui-next` 以及 FAQ 中"重复任务调度（attempt 0 × 2）"的故障排查条目。资料来源：社区发布说明。

## See Also

- [ai/README.md](https://github.com/conductor-oss/conductor/blob/main/ai/README.md) — AI / LLM 任务与示例
- [es8-persistence/README.md](https://github.com/conductor-oss/conductor/blob/main/es8-persistence/README.md) — Elasticsearch 8 持久化模块
- [kafka/README.md](https://github.com/conductor-oss/conductor/blob/main/kafka/README.md) — 社区贡献系统任务
- [schemas/README.md](https://github.com/conductor-oss/conductor/blob/main/schemas/README.md) — JSON Schema 定义
- [ui-next/package.json](https://github.com/conductor-oss/conductor/blob/main/ui-next/package.json) — 新版 UI 技术栈

---

<a id='page-common-src'></a>

## Src 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Src 模块](#page-postgres-persistence-src)

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

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

- [README.md](https://github.com/conductor-oss/conductor/blob/main/README.md)
- [annotations-processor/README.md](https://github.com/conductor-oss/conductor/blob/main/annotations-processor/README.md)
- [kafka/README.md](https://github.com/conductor-oss/conductor/blob/main/kafka/README.md)
- [schemas/README.md](https://github.com/conductor-oss/conductor/blob/main/schemas/README.md)
- [es8-persistence/README.md](https://github.com/conductor-oss/conductor/blob/main/es8-persistence/README.md)
- [common/src/main/java/com/netflix/conductor/common/jackson/JsonProtoModule.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/jackson/JsonProtoModule.java)
- [common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskType.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskType.java)
- [common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java)
- [common/src/main/java/com/netflix/conductor/common/run/TaskSummary.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/run/TaskSummary.java)
- [common/src/main/java/org/conductoross/conductor/common/JsonSchemaValidator.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/org/conductoross/conductor/common/JsonSchemaValidator.java)
- [ai/examples/README.md](https://github.com/conductor-oss/conductor/blob/main/ai/examples/README.md)
- [ui/package.json](https://github.com/conductor-oss/conductor/blob/main/ui/package.json)
- [ui-next/package.json](https://github.com/conductor-oss/conductor/blob/main/ui-next/package.json)
</details>

# Src 模块

## 概述

Conductor 项目的 `Src` 目录包含了整个工作流编排引擎的源代码、构建脚本、配置示例以及文档。该仓库是一个多模块（multi-module）Gradle 项目，其中 `common`、`annotations-processor`、`kafka`、`es8-persistence`、`schemas`、`ai/examples` 等子模块共同构成了服务端核心能力，而 `ui` 和 `ui-next` 则负责 Web 控制台展示 资料来源：[README.md:1-10]()。

仓库主目录下的 `README.md` 给出了后端组合的默认推荐配置，例如 Redis + ES7、Redis + ES8、Redis + OpenSearch、Postgres、Postgres + ES7、MySQL + ES7 等多种后端 资料来源：[README.md:25-35]()，说明源码层面需要通过模块选择和属性开关来切换不同的持久化与索引后端。

## 核心模块组成

### common 模块

`common` 是整个项目共享的数据模型与公共工具的根模块。源码涵盖了工作流与任务的核心 POJO，包括 `WorkflowDef`、`TaskDef`、`Workflow`、`Task`、`TaskSummary` 等 资料来源：[schemas/README.md:1-10]()。

`TaskType` 枚举集中定义了系统内置任务类型与用户自定义任务类型，例如 `DECISION`、`SWITCH`、`FORK_JOIN`、`SUB_WORKFLOW`、`HTTP`、`LAMBDA`、`INLINE`、`JSON_JQ_TRANSFORM`、`SET_VARIABLE`、`KAFKA_PUBLISH` 以及一组 `LLM_*` AI 任务（如 `LLM_TEXT_COMPLETE`、`LLM_CHAT_COMPLETE`、`LLM_INDEX_TEXT` 等），未知字符串会被默认归为 `USER_DEFINED` 资料来源：[common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskType.java:1-30]()。

`Task` 实体提供了对运行时任务实例的完整描述，包括 `seq`、`updateTime`、`queueWaitTime`、`retriedTaskId`、`callbackAfterSeconds` 等字段，并通过 `getQueueWaitTime()` 等方法计算任务在队列中的等待时间 资料来源：[common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java:1-30]()。`TaskSummary` 则以轻量级结构描述已完成任务的关键信息，用于工作流状态查询接口 资料来源：[common/src/main/java/com/netflix/conductor/common/run/TaskSummary.java:1-15]()。

`JsonProtoModule` 用于在 JSON 序列化过程中处理 ProtoBuf 的 `Any` 类型，使其能够通过自定义编码穿透 REST API 传递任意 ProtoBuf 消息 资料来源：[common/src/main/java/com/netflix/conductor/common/jackson/JsonProtoModule.java:1-10]()。`JsonSchemaValidator` 提供了基于 `networknt/json-schema-validator` 的 JSON Schema 校验能力，可使用 `validate(String schemaContent, Map<String, Object> body)` 校验工作流与任务的输入输出 资料来源：[common/src/main/java/org/conductoross/conductor/common/JsonSchemaValidator.java:1-20]()。

### annotations-processor 与 kafka 模块

`annotations-processor` 是一个 Java 注解处理器模块，用于在编译期根据 `@ProtoMessage`、`@ProtoField`、`@ProtoEnum` 等注解生成 ProtoBuf 描述文件 资料来源：[annotations-processor/README.md:1-3]()。

`kafka` 模块提供社区贡献的系统任务，发布到 Maven 时坐标为 `com.netflix.conductor:conductor-task`，其中 `JSON_JQ_TRANSFORM_TASK` 是一个基于 JQ 表达式对 JSON 数据进行转换的系统任务，常用于 HTTP 任务、JOIN 任务或多任务之间的数据流转 资料来源：[kafka/README.md:1-15]()。

### es8-persistence 模块

`es8-persistence` 为 Elasticsearch 8.x 提供索引与查询实现，使用与 ES8 对齐的 `elasticsearch-java` 客户端。该模块使用可组合索引模板、写入别名与 ILM 策略（如 `${indexPrefix}-default-ilm-policy`，热阶段 `max_primary_shard_size=50gb`），并自动创建 `${alias}-000001` 形式的初始索引 资料来源：[es8-persistence/README.md:1-15]()。

构建时需要通过 Gradle 属性选择 ES8 后端模块，避免 Lucene 冲突：

```sh
./gradlew :conductor-server:bootJar -PindexingBackend=elasticsearch8
```

运行时需在配置中显式声明 `conductor.indexing.type=elasticsearch8`，否则 Spring 不会创建对应的 `IndexDAO` Bean，可能出现启动失败 资料来源：[es8-persistence/README.md:15-25]()。

### schemas 与 ai/examples 模块

`schemas` 目录提供符合 JSON Schema Draft 07 规范的核心数据模型定义（`WorkflowDef.json`、`TaskDef.json`、`Workflow.json`、`Task.json` 等），可用于编辑器自动补全、客户端代码生成、API 契约测试等场景 资料来源：[schemas/README.md:1-10]()。

`ai/examples` 收录了 LLM 相关的工作流示例（编号 1-22），覆盖 Chat Completion、Function Calling、Embedding、代码执行沙箱、扩展思考、Web 搜索研究、多轮对话链等典型模式 资料来源：[ai/examples/README.md:1-10]()。

### ui 与 ui-next 模块

`ui` 与 `ui-next` 共同构成 Conductor 的 Web 控制台。`ui` 仍使用 React 18 + react-scripts，并依赖 `orkes-workflow-visualizer`、`react-data-table-component`、`react-vis-timeline-2` 等库 资料来源：[ui/package.json:1-10]()。`ui-next` 则升级到 React Router 7、Material UI v7、Monaco Editor 与 JSON Forms 等现代组件栈，使用 `reaflow` 作为工作流图渲染引擎 资料来源：[ui-next/package.json:1-15]()。

## 模块协作关系

下图展示了源码层主要模块在构建产物中的依赖关系与典型运行路径：

```mermaid
graph TD
  A[common] --> B[conductor-server]
  C[annotations-processor] --> B
  D[kafka] --> B
  E[es8-persistence] --> B
  F[Postgres/MySQL/Redis DAO] --> B
  G[ui / ui-next] --> B
  H[schemas] --> A
  I[ai/examples] --> B
  B --> J[REST + gRPC API]
  B --> K[Workflow/Task 执行引擎]
```

`common` 提供数据模型与校验器，是其他所有后端模块的基石；`es8-persistence`、`kafka` 等模块在构建时通过 Gradle 属性或 Maven 依赖被装配进 `conductor-server`；`ui` / `ui-next` 通过 HTTP 访问 `conductor-server` 暴露的 REST 接口。

## 社区关注点与已知问题

仓库最新发布版本为 v3.31.0-rc.4，重点修复了 test-harness 失败以及将文档与 `publish.yml` 切换到 `ui-next` 资源 资料来源：[README.md:15-20]()。

社区中关于源码层的高反馈问题包括：

- **ES8 兼容性**（Issue #49）：用户对 `es8-persistence` 模块的成熟度较为关注，特别是与 ES8 默认安全配置（TLS/认证）的集成。
- **构建环境与运行时不一致**（Issue #711）：`build.gradle` 强制要求 JDK 21，但 `docker/server/Dockerfile` 部分阶段仍使用 Java 17，源码构建时需注意统一。
- **ES7 Docker 配置缺失**（Issue #928）：`config-redis.properties` 等示例缺少 `conductor.indexing.type=elasticsearch`，会导致 Spring 装配 `IndexDAO` 失败，与 ES8 文档中强调的显式配置点形成对应。
- **子工作流挂起**（Issue #712）：v3.21.23 之后出现的子工作流完成后父工作流不继续执行问题，需要通过 `POST /api/workflow/decide/{workflowId}` 强制决策。
- **ES7 索引模板无限增长**（Issue #226）：`ElasticSearchRestDAOV7` 的 `createIndexesTemplates()` 在特定路径下会创建大量分片，需要在运维侧配置 ILM 或调整模板。

## 参见

- [common 模块](./common-module.md)
- [持久化后端配置](./persistence-backends.md)
- [工作流与任务数据模型](./workflow-task-models.md)

---

<a id='page-postgres-persistence-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-common-src), [Src 模块](#page-scheduler-core-src)

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

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

- [README.md](https://github.com/conductor-oss/conductor/blob/main/README.md)
- [common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskType.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskType.java)
- [common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java)
- [common/src/main/java/com/netflix/conductor/common/jackson/JsonProtoModule.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/jackson/JsonProtoModule.java)
- [common/src/main/java/org/conductoross/conductor/common/JsonSchemaValidator.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/org/conflix/conductor/common/JsonSchemaValidator.java)
- [common/src/main/java/com/netflix/conductor/common/run/TaskSummary.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/run/TaskSummary.java)
- [schemas/README.md](https://github.com/conductor-oss/conductor/blob/main/schemas/README.md)
- [es8-persistence/README.md](https://github.com/conductor-oss/conductor/blob/main/es8-persistence/README.md)
- [kafka/README.md](https://github.com/conductor-oss/conductor/blob/main/kafka/README.md)
- [annotations-processor/README.md](https://github.com/conductor-oss/conductor/blob/main/annotations-processor/README.md)
- [ui/package.json](https://github.com/conductor-oss/conductor/blob/main/ui/package.json)
- [ui-next/package.json](https://github.com/conductor-oss/conductor/blob/main/ui-next/package.json)
- [ai/examples/README.md](https://github.com/conductor-oss/conductor/blob/main/ai/examples/README.md)
</details>

# Src 模块

## 仓库模块结构概览

Conductor OSS 是一个分布式工作流编排引擎，其源码仓库采用多模块 Gradle 项目结构组织，每个子模块承担独立职责并通过清晰的边界实现关注点分离。

主要源码模块如下：
- **common**：核心数据模型与共享工具类，被所有其他模块依赖
- **annotations-processor**：从 Java 注解生成 protobuf 文件的注解处理器
- **es8-persistence**：Elasticsearch 8.x 持久化实现
- **kafka**：社区贡献的系统任务（如 `JSON_JQ_TRANSFORM`）
- **ui / ui-next**：基于 React 的 Web 管理界面，ui-next 为新版
- **ai/examples**：AI 工作流示例集合

根据 README 中"Backend Configuration"部分，服务器支持 Redis+ES7、Redis+ES8、Postgres、MySQL 等多种后端组合配置。这种可插拔架构正是源码模块化设计的直接体现。

```mermaid
graph TD
    A[conductor-server 核心服务器] --> B[common 共享数据模型]
    A --> C[es8-persistence ES8 索引]
    A --> D[kafka 系统任务]
    B --> E[schemas JSON Schema]
    A --> F[annotations-processor]
    A --> G[ui / ui-next Web 界面]
    H[ai/examples] --> A
```

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

## common 模块：核心数据模型

`common` 模块是整个项目的基石，定义了跨模块共享的数据结构与工具。

### 任务类型枚举

`TaskType` 枚举类集中定义了所有内置任务类型，包括：控制流任务（`DECISION`、`SWITCH`、`FORK`、`JOIN`、`DO_WHILE`）、系统任务（`HTTP`、`LAMBDA`、`INLINE`、`SUB_WORKFLOW`）、LLM 相关任务（`LLM_TEXT_COMPLETE`、`LLM_CHAT_COMPLETE`、`LLM_INDEX_TEXT`）、MCP 集成任务（`LIST_MCP_TOOLS`、`CALL_MCP_TOOL`）等。`BUILT_IN_TASKS` 静态集合标识哪些是内置任务；未知类型会被默认转换为 `USER_DEFINED`。

资料来源：[common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskType.java:1-100]()

### 任务运行时模型

`Task` 类表示任务执行实例，包含输入输出数据、workerId、domain、重试次数、调度时间等运行时字段。其 `getQueueWaitTime()` 方法根据任务当前状态（IN_PROGRESS、SCHEDULED）以及 `callbackAfterSeconds` 计算队列等待时间，对性能监控至关重要。

`TaskSummary` 是轻量级摘要视图，用于列表展示场景，避免返回完整 `Task` 对象带来的开销。

资料来源：[common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java:1-50]()、[common/src/main/java/com/netflix/conductor/common/run/TaskSummary.java:1-30]()

## JSON Schema 与验证机制

`schemas` 目录提供 JSON Schema 定义，用于在工作流与任务定义提交前进行校验。`JsonSchemaValidator` 基于 networknt 的 json-schema-validator 实现，支持 JSON Schema Draft 07 规范，核心方法 `validate(schemaContent, body)` 返回 `Set<ValidationMessage>`。

主要 schema 文件：`WorkflowDef.json`（递归定义 `WorkflowTask`，支持 `decisionCases`、`forkTasks`、Do-While 循环、子工作流嵌套）、`TaskDef.json`、`Workflow.json`、`Task.json`。

`JsonProtoModule` 解决了 gRPC 接口中 `google.protobuf.Any` 类型在 REST API 上的 JSON 编码难题——PB-JSON 编码器无法识别任意负载，因此该模块通过自定义方式存储 URL-like 类型声明与原始字节，保证通用性。

资料来源：[schemas/README.md:1-50]()、[common/src/main/java/org/conductoross/conductor/common/JsonSchemaValidator.java:1-30]()、[common/src/main/java/com/netflix/conductor/common/jackson/JsonProtoModule.java:1-30]()

## 持久化、扩展与 UI 模块

### ES8 持久化

`es8-persistence` 模块采用 `elasticsearch-java` 客户端（版本 8.19.11），使用可组合索引模板、写入别名与 ILM 策略：ILM 策略 `${indexPrefix}-default-ilm-policy` 的热阶段滚动条件为 `max_primary_shard_size=50gb`，写入别名涵盖 `${indexPrefix}_workflow`、`${indexPrefix}_task`、`${indexPrefix}_task_log` 等。构建时通过 `-PindexingBackend=elasticsearch8` 选择该模块，运行时设置 `conductor.indexing.type=elasticsearch8`。

资料来源：[es8-persistence/README.md:1-40]()

### Kafka 与社区任务

`kafka` 模块发布为 `conductor-task` 工件，包含社区贡献的系统任务。其中 `JSON_JQ_TRANSFORM_TASK` 允许使用 JQ 查询表达式处理 JSON 数据，常用于 HTTP、JOIN 或独立任务的输出转换。

资料来源：[kafka/README.md:1-30]()

### 注解处理器与 UI

`annotations-processor` 模块从注解自动生成 protobuf 文件，简化跨语言接口定义。

仓库包含两套 UI：旧版 `ui` 基于 React 18.3.1、`react-scripts` 5.0.1、yarn 1.22.22；新版 `ui-next` 已迁移至 React Router v7、Material UI v7、Monaco Editor、reaflow 与 xstate。根据 v3.31.0-rc.4 发布说明，发布流程已切换为使用 `ui-next`。

资料来源：[annotations-processor/README.md:1-5]()、[ui/package.json:1-50]()、[ui-next/package.json:1-50]()

## AI 示例模块

`ai/examples` 提供 20+ 个开箱即用的 AI 工作流定义：基础聊天补全（`01-chat-completion.json`）、代码执行沙箱（`18-code-execution.json`）、编码代理（`19-coding-agent.json`：规划→编码→审查）、扩展思考（`20-extended-thinking.json`，含 token 预算）、网络研究代理（`21-web-search-research-agent.json`）、多轮对话链（`22-multi-turn-chain.json`，基于 OpenAI `previousResponseId`）。每个示例可通过 `POST /api/metadata/workflow` 注册后执行。

资料来源：[ai/examples/README.md:1-50]()

## 社区关注点与故障模式

参考社区讨论（issue #711、#928、#226）：
- **构建环境一致性**：`Dockerfile` 应与 `build.gradle` 的 Java 版本对齐（项目要求 JDK 21）
- **ES7 Docker 配置缺失**：`conductor.indexing.type=elasticsearch` 是启动必需配置，缺失会导致 `IndexDAO` bean 未创建
- **ES7 索引爆炸**：默认每日滚动任务日志索引可能产生大量分片，建议显式配置 ILM 策略
- **子工作流挂起**：v3.21.23 后子工作流完成后父工作流可能挂起，需调用 `POST /api/workflow/decide/{id}` 强制推进

## See Also

- [README.md](https://github.com/conductor-oss/conductor/blob/main/README.md) — 项目总体说明与构建指南
- [es8-persistence/README.md](https://github.com/conductor-oss/conductor/blob/main/es8-persistence/README.md) — ES8 持久化配置详情
- [schemas/README.md](https://github.com/conductor-oss/conductor/blob/main/schemas/README.md) — JSON Schema 规范定义
- [ai/examples/README.md](https://github.com/conductor-oss/conductor/blob/main/ai/examples/README.md) — AI 工作流示例全集

---

<a id='page-scheduler-core-src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-postgres-persistence-src)

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

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

- [README.md](https://github.com/conductor-oss/conductor/blob/main/README.md)
- [common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskType.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskType.java)
- [common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java)
- [common/src/main/java/com/netflix/conductor/common/run/TaskSummary.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/run/TaskSummary.java)
- [common/src/main/java/com/netflix/conductor/common/jackson/JsonProtoModule.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/com/netflix/conductor/common/jackson/JsonProtoModule.java)
- [common/src/main/java/org/conductoross/conductor/common/JsonSchemaValidator.java](https://github.com/conductor-oss/conductor/blob/main/common/src/main/java/org/conductoross/conductor/common/JsonSchemaValidator.java)
- [es8-persistence/README.md](https://github.com/conductor-oss/conductor/blob/main/es8-persistence/README.md)
- [kafka/README.md](https://github.com/conductor-oss/conductor/blob/main/kafka/README.md)
- [schemas/README.md](https://github.com/conductor-oss/conductor/blob/main/schemas/README.md)
- [annotations-processor/README.md](https://github.com/conductor-oss/conductor/blob/main/annotations-processor/README.md)
- [ai/examples/README.md](https://github.com/conductor-oss/conductor/blob/main/ai/examples/README.md)
- [ui/package.json](https://github.com/conductor-oss/conductor/blob/main/ui/package.json)
- [ui-next/package.json](https://github.com/conductor-oss/conductor/blob/main/ui-next/package.json)
</details>

# Src 模块

## 模块概览

Conductor 仓库采用多模块（multi-module）Gradle 工程结构，源代码在仓库根目录下按职责划分为多个并列模块，每个模块独立编译并发布独立的构件（artifact）。这种结构使核心模型、持久化后端、扩展任务、UI 与 AI 示例能够解耦演进。

仓库一级目录的源码模块划分如下（参考 [README.md](https://github.com/conductor-oss/conductor/blob/main/README.md) 中的"Backend Configuration"段落）：

| 模块路径 | 职责 |
|---|---|
| `common/` | 共享数据模型、JSON/Protobuf 序列化、Schema 校验等核心基础库 |
| `core/` | 工作流与任务编排引擎（运行时核心） |
| `es7-persistence/` | Elasticsearch 7 索引持久化实现 |
| `es8-persistence/` | Elasticsearch 8 索引持久化实现（ILM + 写入别名） |
| `postgres-persistence/` | Postgres 持久化实现 |
| `mysql-persistence/` | MySQL 持久化实现 |
| `redis-persistence/` | Redis 持久化实现 |
| `kafka/` | 社区贡献的 Kafka 任务（如 `JSON_JQ_TRANSFORM`） |
| `annotations-processor/` | 注解处理器：从注解生成 Protobuf 文件 |
| `schemas/` | 公共 JSON Schema 定义（`WorkflowDef`、`TaskDef` 等） |
| `ui/` | 旧版 React 前端（基于 `react-scripts`） |
| `ui-next/` | 新版 React/MUI 前端（替代 `ui`） |
| `ai/examples/` | 内置 AI 编排示例（聊天、代码代理、Research Agent 等） |

社区在升级到 v3.21.23 后遇到子工作流挂起问题（#712），以及对 ES8 兼容性（#49）的关注，正是各模块解耦所带来的演进动力——持久化与运行时分离使得后端升级对核心引擎影响最小。

## 核心模型模块（common）

`common` 模块是整个项目的基础库，定义了 REST/gRPC 接口所使用的全部数据模型与序列化工具。

**任务类型枚举**：`TaskType.java` 列出了全部内建任务类型常量，包括 `HTTP`、`SUB_WORKFLOW`、`FORK_JOIN`、`DO_WHILE`、`LLM_CHAT_COMPLETE`、`CALL_MCP_TOOL`、`PULL_WORKFLOW_MESSAGES` 等。`BUILT_IN_TASKS` 集合用于区分系统任务与用户自定义任务 资料来源：[common/src/main/java/com/netflix/conductor/common/metadata/tasks/TaskType.java:1-100]()。

**任务运行模型**：`Task.java` 与 `TaskSummary.java` 共同描述任务实例的执行状态、重试次数、调度/开始/更新时间等元数据。`getQueueWaitTime()` 方法根据是否设置了 `callbackAfterSeconds` 来分别计算调度延迟，是性能监控的关键指标 资料来源：[common/src/main/java/com/netflix/conductor/common/metadata/tasks/Task.java:1-100]()。

**JSON Schema 校验**：`JsonSchemaValidator.java` 基于 `networknt/json-schema-validator` 实现动态 Schema 校验，工作流定义的输入/输出可通过该校验器进行强类型检查 资料来源：[common/src/main/java/org/conductoross/conductor/common/JsonSchemaValidator.java:1-15]()。

**Protobuf Any 序列化**：`JsonProtoModule.java` 为 gRPC 引入的 `google.protobuf.Any` 提供自定义 JSON 编码，避免对每种嵌入式消息的注册依赖，使 REST API 可透明转发任意负载 资料来源：[common/src/main/java/com/netflix/conductor/common/jackson/JsonProtoModule.java:1-30]()。

## 持久化后端模块

Conductor 源码区分"运行时队列"（Redis）与"索引/历史"（ES7/ES8/OpenSearch/Postgres/MySQL）两类持久化，对应不同构建变体。

`es8-persistence` 是社区关注度较高的模块（对应 issue #49、#928、#226）。它使用 `elasticsearch-java` 8.19.11 客户端，并采用 ES8 推荐的"可组合索引模板 + 写入别名 + ILM 策略"模式：

- ILM 策略 `${indexPrefix}-default-ilm-policy` 在热阶段设置 `max_primary_shard_size=50gb`
- 写入别名 `${indexPrefix}_workflow`、`_task`、`_task_log`、`_message`、`_event` 在初始化时创建
- 初始索引命名为 `${alias}-000001`，启用滚动
- 默认刷新间隔 30 秒（可配）

issue #226 中 `es7-persistence` 出现无限制创建索引的问题（`createIndexesTemplates` 未配置滚动），新模块通过 ILM + 写入别名对此进行了规避。issue #928 中"Docker 镜像缺少 `conductor.indexing.type` 导致 `IndexDAO` Bean 不创建"的根因是 Spring 自动装配按该属性选择持久化实现，因此 Docker 配置文件中必须显式声明 backend 类型 资料来源：[es8-persistence/README.md:1-30]()。

## 扩展与工具模块

**Kafka 任务模块**（`kafka/`）：发布 `com.netflix.conductor:conductor-task`，内置 `JSON_JQ_TRANSFORM_TASK`，允许在任务输入/输出上使用 JQ 查询进行结构转换；该模块在 `conductor-contribs` 已作为依赖默认包含 资料来源：[kafka/README.md:1-30]()。

**注解处理器**（`annotations-processor/`）：从 Java 注解生成 Protobuf 描述文件，简化 gRPC 服务定义 资料来源：[annotations-processor/README.md:1-3]()。

**JSON Schema 定义**（`schemas/`）：提供 `WorkflowDef.json`、`TaskDef.json`、`Workflow.json`、`Task.json` 等符合 Draft 07 的模式文件。其中 `WorkflowDef` 包含递归 `WorkflowTask`，支持 `decisionCases`、`forkTasks`、`loopOver`、`subWorkflowParam` 等嵌套结构，理论上可无限嵌套复杂流程；Java 模型与 Schema 的对应关系见 README 中表格 资料来源：[schemas/README.md:1-100]()。

**AI 示例**（`ai/examples/`）：包含 22 个开箱即用工作流定义，涵盖聊天补全、代码执行沙箱、Extended Thinking、Web Research Agent 等。`Quick Start` 中演示了"注册 → 执行 → 查询"三步流程 资料来源：[ai/examples/README.md:1-60]()。

**前端模块**：`ui/package.json` 仍基于 `react-scripts@5.0.1` 与 `react-router@5`，最新发布的 v3.31.0-rc.4 已将文档与发布流水线切换至 `ui-next`（基于 React 18、Material UI 7、`react-router 7`、`xstate` 等） 资料来源：[ui/package.json:1-30]()、[ui-next/package.json:1-50]()。

## 构建与模块选择

源码构建通过 Gradle 的 `-PindexingBackend=` 属性切换持久化模块以避免 Lucene 冲突，例如：

```sh
./gradlew :conductor-server:bootJar -PindexingBackend=elasticsearch8
```

后端配置文件位于 `docker/server/config/`，每种组合（如 `config-redis-es8.properties`、`config-postgres.properties`）都对应一个 `conductor.indexing.type` 值 资料来源：[README.md](https://github.com/conductor-oss/conductor/blob/main/README.md) 与 [es8-persistence/README.md:1-30]()。源码模块化使每种持久化变体可独立打包，避免在运行时类路径上同时出现 ES7 与 ES8 客户端。

## 参见

- [ES7 Docker 配置缺失 `conductor.indexing.type` 导致启动失败（#928）](https://github.com/conductor-oss/conductor/issues/928)
- [ES7 持久化无限制创建索引（#226）](https://github.com/conductor-oss/conductor/issues/226)
- [Dockerfile 使用 Java 17 与 build.gradle 要求 Java 21 不一致（#711）](https://github.com/conductor-oss/conductor/issues/711)
- [子工作流挂起（#712）](https://github.com/conductor-oss/conductor/issues/712)
- [Elasticsearch 8 兼容性（#49）](https://github.com/conductor-oss/conductor/issues/49)

---

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

---

## Doramagic 踩坑日志

项目：conductor-oss/conductor

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。

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

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

## 2. 维护坑 · 来源证据：[BUG]: SWITCH task goes through defaultCase if other cases are empty

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：[BUG]: SWITCH task goes through defaultCase if other cases are empty
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/conductor-oss/conductor/issues/396 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

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

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

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

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

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

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

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

<!-- canonical_name: conductor-oss/conductor; human_manual_source: deepwiki_human_wiki -->