项目定位与目标

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

项目核心入口是 Conductor Server，使用 Spring Boot 构建；与之配套的还包括官方提供的多种语言 SDK（Java、Python、Go、Node、C#、Rust 等），由仓库顶部的 SDK 链接矩阵列出。资料来源：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

任务运行时通过 Task 实体承载输入输出、状态、重试次数、调度时间等元数据；TaskResult 描述工作线程上报的执行结果，可指定 callbackAfterSeconds 实现"延迟回调"，让长任务在指定秒数内保留在队列不被其他 worker 抢占。资料来源：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 与 common/src/main/java/org/conductoross/conductor/common/JsonSchemaValidator.java

ai/examples/ 目录提供超过 20 个工作流示例，覆盖 Chat Completion、代码沙盒执行、扩展思考、联网研究、Multi-turn 链式调用等典型 LLM 场景，并提供 curl 注册/执行/查询的快速入门脚本。资料来源：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、kafka/README.md 与 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 与 ui-next/package.json

后端配置矩阵

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

资料来源：README.md 与 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

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

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

1. Elasticsearch 8 兼容性：Issue #49 长期跟踪 ES8 支持进度，目前已由独立 es8-persistence 模块实现（使用 elasticsearch-java 8.19.x 客户端和 ILM 策略）。资料来源：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。

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

See Also

• ai/README.md — AI / LLM 任务与示例
• es8-persistence/README.md — Elasticsearch 8 持久化模块
• kafka/README.md — 社区贡献系统任务
• schemas/README.md — JSON Schema 定义
• ui-next/package.json — 新版 UI 技术栈

概述

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 冲突：

./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。

模块协作关系

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

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 模块
• 持久化后端配置
• 工作流与任务数据模型

Pitfall Log / 踩坑日志

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