# https://github.com/kedro-org/kedro 项目说明书

生成时间：2026-07-29 23:01:51 UTC

## 目录

- [项目概览](#page-overview)
- [Src 模块](#page-features-test_starter--cookiecutter-repo_name--src)
- [Src 模块](#page-kedro-templates-project--cookiecutter-repo_name--src)
- [Server 模块](#page-kedro-server)

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

## 项目概览

### 相关页面

相关主题：[Src 模块](#page-features-test_starter--cookiecutter-repo_name--src)

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

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

- [README.md](https://github.com/kedro-org/kedro/blob/main/README.md)
- [features/test_plugin/pyproject.toml](https://github.com/kedro-org/kedro/blob/main/features/test_plugin/pyproject.toml)
- [features/test_starter/{{ cookiecutter.repo_name }}/README.md](https://github.com/kedro-org/kedro/blob/main/features/test_starter/{{ cookiecutter.repo_name }}/README.md)
- [features/test_starter/{{ cookiecutter.repo_name }}/conf/README.md](https://github.com/kedro-org/kedro/blob/main/features/test_starter/{{ cookiecutter.repo_name }}/conf/README.md)
- [features/test_starter/{{ cookiecutter.repo_name }}/pyproject.toml](https://github.com/kedro-org/kedro/blob/main/features/test_starter/{{ cookiecutter.repo_name }}/pyproject.toml)
- [features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/data_engineering/README.md](https://github.com/kedro-org/kedro/blob/main/features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/data_engineering/README.md)
</details>

# 项目概览

## 1. 项目定位与核心价值

Kedro 是一个面向数据科学与机器学习工程的 Python 框架，其设计目标是让数据流水线（pipeline）具备生产级可维护性、可测试性与可部署性。Kedro 在项目结构、配置管理、目录布局与依赖注册方面提供了一整套约定，使团队成员能够在统一的代码组织下协作，而无需自行设计脚手架。

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

通过把数据工程、数据科学和机器学习任务抽象成可组合的节点（node）与流水线（pipeline），Kedro 提供了从本地开发到大规模部署的连续性。社区中关于"Kedro 是否具备真正的云原生能力"的长期讨论（参见 [issue #770](https://github.com/kedro-org/kedro/issues/770) 与 [issue #3094](https://github.com/kedro-org/kedro/issues/3094)）也反映出它正在向 MLOps 平台集成方向持续演进，最新发布的 1.5.0 中新增的 HTTP 服务层（`kedro server start`）与 `KedroServiceSession` 正是这一方向的体现。

## 2. 项目结构与代码组织

一个标准的 Kedro 项目由 `kedro new` 命令生成，其目录布局在 Cookiecutter 模板中已有明确定义。项目根目录下包含 `conf/`（用于存放各类环境的配置）、`src/<package_name>/`（包含实际流水线代码）以及 `pyproject.toml`（项目元数据与依赖声明）。其中 `src/<package_name>/pipelines/` 子目录以"按业务领域划分"的模式组织不同的流水线，例如 `data_engineering`、`data_science` 等目录各自包含完整的 `nodes.py`、`pipeline.py` 与 `README.md`。

资料来源：[features/test_starter/{{ cookiecutter.repo_name }}/README.md:1-40]()  
资料来源：[features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/data_engineering/README.md:1-30]()

下表给出了典型 Kedro 项目中的核心目录与用途：

| 目录 / 文件 | 作用 |
|-------------|------|
| `conf/base/` | 默认配置：catalog、parameters、logging |
| `conf/local/` | 本地环境覆盖（默认 git-ignored） |
| `src/<package>/pipelines/` | 按业务领域拆分的流水线代码 |
| `src/<package>/pipeline_registry.py` | 流水线自动发现与注册入口 |
| `pyproject.toml` | 依赖、插件、`kedro init` 元数据 |

资料来源：[features/test_starter/{{ cookiecutter.repo_name }}/pyproject.toml:1-80]()  
资料来源：[features/test_starter/{{ cookiecutter.repo_name }}/conf/README.md:1-30]()

## 3. CLI、依赖与插件体系

Kedro 通过 Typer 构建的 CLI 暴露了项目生命周期所需的全部命令，其中 `kedro new` 用于脚手架生成、`kedro run` 用于执行流水线、`kedro registry` 用于查看已注册的流水线列表、`kedro server start`（1.5.0 引入）用于启动 HTTP 服务对外暴露运行能力。项目对第三方扩展的集成通过 `[tool.kedro]` 段下的 `plugins` 字段声明，例如模板示例中即声明了 `kedro_datasets`、`kedro[pandas]`、`kedro[polars]` 等可选依赖。

资料来源：[features/test_starter/{{ cookiecutter.repo_name }}/pyproject.toml:20-60]()  
资料来源：[features/test_plugin/pyproject.toml:1-40]()

社区中一个值得关注的实际问题是：`kedro new` 当前仅使用字符集正则校验项目名，不会拒绝与 Python 标准库或关键字冲突的名字（如 `email`、`string`、`type`），从而生成一个无法正常导入的"破损"项目（[issue #5607](https://github.com/kedro-org/kedro/issues/5607)）。同时，在 monorepo（uv workspace）场景下，子包 `settings.py` 中注册的钩子（hooks）从根项目入口运行时会被静默忽略（[issue #5515](https://github.com/kedro-org/kedro/issues/5515)），这表明配置加载与包发现机制仍有边界情况需要明确文档化与处理。

## 4. 部署、文档与生态集成

Kedro 的部署文档覆盖 AWS Step Functions、AWS EMR serverless、Databricks 等多种目标，但社区已多次反馈这些页面与最新的 Kedro 版本及对应云平台行为存在偏差，需要复核与更新（[issue #5304](https://github.com/kedro-org/kedro/issues/5304)、[issue #5364](https://github.com/kedro-org/kedro/issues/5364)）。在 MLRun/Nuclio 等新型 MLOps 平台上的部署能力也在持续讨论中（[issue #5305](https://github.com/kedro-org/kedro/issues/5305)）。

资料来源：[README.md:40-80]()

文档生成方面，当用户在 `kedro new` 中选择 `docs` 工具时，生成的 Sphinx 工程存在 `index.rst` 指向缺失的 `modules` 页面、缺少 `Makefile` 等问题（[issue #5592](https://github.com/kedro-org/kedro/issues/5592)）；当未选择该工具时，官方文档需要补充如何手工接入 MkDocs 的说明（[issue #5603](https://github.com/kedro-org/kedro/issues/5603)）。这两项问题体现了 Kedro 项目脚手架"约定"与"可选工具"之间的衔接仍有改进空间。

在流水线发现层面，社区已提议为 `find_pipelines` 增加 `exclude_pipelines` 参数，以便在工作流中临时跳过尚不完整、无法成功自动发现的流水线（[issue #5582](https://github.com/kedro-org/kedro/issues/5582)）。这一改动将进一步提升多流水线项目下的开发容错能力。

---

<a id='page-features-test_starter--cookiecutter-repo_name--src'></a>

## Src 模块

### 相关页面

相关主题：[项目概览](#page-overview), [Src 模块](#page-kedro-templates-project--cookiecutter-repo_name--src)

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

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

- [features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/__init__.py](https://github.com/kedro-org/kedro/blob/main/features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/__init__.py)
- [features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/__main__.py](https://github.com/kedro-org/kedro/blob/main/features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/__main__.py)
- [features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipeline_registry.py](https://github.com/kedro-org/kedro/blob/main/features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipeline_registry.py)
- [features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/__init__.py](https://github.com/kedro-org/kedro/blob/main/features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/__init__.py)
- [features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/data_engineering/README.md](https://github.com/kedro-org/kedro/blob/main/features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/data_engineering/README.md)
- [features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/data_engineering/__init__.py](https://github.com/kedro-org/kedro/blob/main/features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/data_engineering/__init__.py)
</details>

# Src 模块

## 概述与定位

`src/` 目录是 Kedro 项目约定的源代码根目录，用于存放项目自身的 Python 包（即模板中的 `{{ cookiecutter.python_package }}`）。该目录由 `kedro new` 命令基于 `features/test_starter/` 模板生成，承担三类核心职责：作为可安装的 Python 包被部署与复用、托管所有用户自定义的 pipeline、以及提供 CLI 入口与默认 pipeline 注册表。社区在 issue #5515 中指出，当子包的 `settings.py` 在项目根入口运行 pipeline 时会被静默忽略，这与 `src/` 下各子包的命名空间加载行为直接相关；issue #5582 则希望为 `find_pipelines()` 增加 `exclude_pipelines` 参数，避免开发中的破损 pipeline 阻塞 `src/` 内其他子包的自动发现。

资料来源：[features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/__init__.py:1-1]()

## 包入口与 CLI 启动

项目包的 `__init__.py` 在模板中是占位文件，几乎为空，作为可被 `import` 的常规 Python 包存在。真正的 CLI 入口位于同级的 `__main__.py`，它通过 `from kedro.framework.cli import main` 并调用 `main()`，从而让 `python -m {{ cookiecutter.python_package }}` 与直接执行包时的行为与 `kedro run` 等价。这两个文件共同保证了 `src/` 包既能被 `pip install` 后的外部工具复用，也能作为独立进程启动 Kedro CLI。

资料来源：[features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/__init__.py:1-1]()  
资料来源：[features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/__main__.py:1-5]()

## Pipeline 注册表

`pipeline_registry.py` 是 `src/` 中所有可用 pipeline 的单一注册中心。它暴露 `register_pipelines()` 函数，返回一个 `dict[str, Pipeline]`，键为 pipeline 的注册名（典型值包括 `__default__` 与各业务名），值为由 `create_pipeline()` 构造的 `Pipeline` 对象。Kedro 框架在运行时调用此函数以构建 `PipelineRegistry`，从而支持 `kedro run --pipeline=<name>` 的选择执行。在多 pipeline 的 monorepo 场景下，这一文件也是各 `src/{{ cookiecutter.python_package }}/pipelines/*` 子模块对外暴露其 `Pipeline` 实例的统一入口。

资料来源：[features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipeline_registry.py:1-40]()

## Pipelines 子模块结构

`src/{{ cookiecutter.python_package }}/pipelines/` 是一个命名空间包目录。其 `__init__.py` 在模板中同样保持为空，仅起到使该目录成为合法 Python 包的作用，从而支持 `kedro.framework.project.pipelines` 对 `src/.../pipelines/*` 的自动发现。下属每个子目录代表一个独立 pipeline，命名通常贴合业务领域（如 `data_engineering`、`data_science`、`reporting`）。社区对可发现的 pipeline 数量与隔离的关注持续存在，例如希望支持按子包屏蔽开发中的破损 pipeline（issue #5582），说明 `pipelines/` 子树是项目最频繁扩展的位置。

资料来源：[features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/__init__.py:1-1]()

### 示例：data_engineering Pipeline

`data_engineering` 是模板内置的一个最小 pipeline 样例。`pipelines/data_engineering/__init__.py` 定义工厂函数 `create_pipeline(**kwargs) -> Pipeline`，在该函数内部组合 node 与节点函数，并组装为一个完整的 `Pipeline` 实例返回，使其能够被 `pipeline_registry.py` 直接引用与注册。`pipelines/data_engineering/README.md` 则为该子模块提供面向协作者的说明文档，约定如何命名节点、如何放置节点函数实现以及如何扩展该 pipeline。该样例的存在既为 `kedro new` 后立即可运行提供最小骨架，也为用户在 `src/` 下新增自定义 pipeline 提供可复制的样板。

资料来源：[features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/data_engineering/__init__.py:1-40]()  
资料来源：[features/test_starter/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/data_engineering/README.md:1-30]()

## 模块关系一览

下表给出 `src/` 下各文件职责的速览，便于在阅读 `kedro new` 生成的项目结构时快速定位。

| 文件 | 角色 | 关键导出 |
|------|------|----------|
| `src/.../__init__.py` | 项目包标识 | （无） |
| `src/.../__main__.py` | CLI 入口 | 触发 `kedro.framework.cli.main` |
| `src/.../pipeline_registry.py` | Pipeline 注册表 | `register_pipelines()` |
| `src/.../pipelines/__init__.py` | Pipelines 命名空间 | （无） |
| `src/.../pipelines/<name>/__init__.py` | 单个 pipeline 工厂 | `create_pipeline()` |
| `src/.../pipelines/<name>/README.md` | 子模块说明 | 文档 |

## 小结

`src/` 模块是 Kedro 项目的"业务代码容器"：它既是可发布的 Python 包，也是 CLI 与 Pipeline 注册的源头，并通过 `pipelines/<name>` 子目录承载一个或多个领域 pipeline。理解 `__main__.py`（CLI 入口）、`pipeline_registry.py`（注册中心）、`pipelines/__init__.py`（命名空间）与各业务子包的 `create_pipeline()`（工厂）之间的协作，是阅读与扩展任何 `kedro new` 生成项目的关键起点。

---

<a id='page-kedro-templates-project--cookiecutter-repo_name--src'></a>

## Src 模块

### 相关页面

相关主题：[Src 模块](#page-features-test_starter--cookiecutter-repo_name--src), [Server 模块](#page-kedro-server)

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

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

- [kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/__init__.py](https://github.com/kedro-org/kedro/blob/main/kedro/templates/project/%7B%7B%20cookiecutter.repo_name%20%7D%7D/src/%7B%7B%20cookiecutter.python_package%20%7D%7D/__init__.py)
- [kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/__main__.py](https://github.com/kedro-org/kedro/blob/main/kedro/templates/project/%7B%7B%20cookiecutter.repo_name%20%7D%7D/src/%7B%7B%20cookiecutter.python_package%20%7D%7D/__main__.py)
- [kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipeline_registry.py](https://github.com/kedro-org/kedro/blob/main/kedro/templates/project/%7B%7B%20cookiecutter.repo_name%20%7D%7D/src/%7B%7B%20cookiecutter.python_package%20%7D%7D/pipeline_registry.py)
- [kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/__init__.py](https://github.com/kedro-org/kedro/blob/main/kedro/templates/project/%7B%7B%20cookiecutter.repo_name%20%7D%7D/src/%7B%7B%20cookiecutter.python_package%20%7D%7D/pipelines/__init__.py)
- [kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/settings.py](https://github.com/kedro-org/kedro/blob/main/kedro/templates/project/%7B%7B%20cookiecutter.repo_name%20%7D%7D/src/%7B%7B%20cookiecutter.python_package%20%7D%7D/settings.py)
</details>

# Src 模块

## 概述与定位

`Src` 模块并不是 Kedro 框架内部的一个 Python 包，而是通过 `kedro new` 命令生成的 **项目模板源代码包**（project template source package）。当用户运行 `kedro new` 时，Cookiecutter 会基于 `kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/` 目录下的模板文件，将整套源码骨架渲染到用户项目的 `src/<python_package>/` 路径中。

这个包承载了用户项目里所有的业务代码与运行时配置：
- 管道（pipeline）的注册与自动发现；
- 项目配置（钩子、数据目录、参数加载方式）的集中声明；
- 包级运行入口（`python -m <package>`）。

简而言之，`Src` 模块是 **用户与 Kedro 框架交互的唯一边界**：框架通过它读取用户的管道与配置；用户通过它声明要让 Kedro 执行哪些内容。理解该模块的加载顺序与文件职责，是正确使用 Kedro 的前提。

值得一提的是，社区曾在 #5515 中反馈：在 uv workspace 形式的 monorepo 中，从根项目入口运行子包内的 pipeline 时，子包自身的 `settings.py` 中注册的钩子会被静默忽略。这一行为直接源自 `Src` 模块对 `settings.py` 的加载机制——框架只会读取与根入口包对应的 `settings.py`，因此正确理解本模块对多包项目尤为关键。

## 核心文件构成

`src/<python_package>/` 在默认模板下生成 5 个核心文件，每个都承担不可替代的角色：

### `__init__.py` — 包标识

将 `src/<python_package>/` 目录标记为可被 Python `import` 的正式包。在大多数模板中该文件保持为空，仅作为命名空间存在。

资料来源：[kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/__init__.py]()

### `__main__.py` — 运行入口

启用 `python -m <python_package>` 形式的直接运行，等价于调用 Kedro CLI 的 `kedro run` 流程。它是开发与调试时最便捷的入口点。

资料来源：[kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/__main__.py]()

### `pipeline_registry.py` — 管道注册中心

整个 `Src` 包最关键的文件之一，要求用户实现 `register_pipelines()` 函数，返回一个由 pipeline 名称到 `Pipeline` 对象映射组成的字典。Kedro 通过调用该函数获取所有可运行的 pipeline，从而支持 `kedro run --pipeline=<name>` 这种子集运行模式。

资料来源：[kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipeline_registry.py]()

社区中讨论的 #5582「Add exclude_pipelines parameter to find_pipelines」正是围绕如何让用户从注册结果中过滤掉尚未完成、暂时无法运行的 pipeline 而展开，反映了 `pipeline_registry.py` 在迭代开发中的常见痛点。

### `pipelines/__init__.py` — 子包自动发现入口

`pipelines/` 是一个常规的 Python 子包，其 `__init__.py` 为该子包提供命名空间。Kedro 通过 `find_pipelines()` 在此目录下递归扫描实现了 `create_pipeline()` 工厂的模块，并把它们汇总到注册表中。

资料来源：[kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/__init__.py]()

### `settings.py` — 配置与钩子注册

`settings.py` 集中存放：
- `HOOKS`：用户自定义的钩子列表；
- `DATA_CATALOG` 等目录与数据集配置常量；
- 参数加载行为（如 `CONFIG_LOADER_ARGS`、`CONFIG_LOADER_CLASS`）。

资料来源：[kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/settings.py]()

再次强调 #5515：当用户在子包（例如 `src/my_proj/sub_pkg/`）下放置独立的 `settings.py` 时，Kedro 仅从 **根入口包** 对应的 `settings.py` 读取钩子，子包里的钩子不会自动生效。

## 运行时的协作流程

```mermaid
flowchart TD
    A[用户执行 kedro run 或 python -m package] --> B[定位 src/&lt;package&gt;]
    B --> C[加载 settings.py]
    C --> D[实例化 HOOKS 中的钩子]
    B --> E[调用 register_pipelines from pipeline_registry.py]
    E --> F[find_pipelines 扫描 pipelines/ 子包]
    F --> G[汇总 Pipeline 字典]
    G --> H[Kedro Session 选取目标 pipeline]
    H --> I[执行节点 / 数据集 I/O]
    I --> J[触发 after_pipeline_run 等钩子]
```

从图中可以看到：`settings.py` 的加载与 `pipeline_registry.py` 的注册是 **并行** 的两个初始化分支，二者都在 `Src` 包内部完成；最终由 `Kedro Session` 把二者串联起来进入执行阶段。

## 扩展实践与注意事项

1. **新增 pipeline**：在 `pipelines/<new_pipe>/` 下创建模块并实现 `create_pipeline()`，即可被自动发现；不过仍需在 `register_pipelines()` 返回的字典里添加对应键值对，否则 `kedro run --pipeline=<new_pipe>` 找不到它。
2. **新增钩子**：把类或实例追加到 **根包** `settings.py` 的 `HOOKS` 列表中；放到子包的 `settings.py` 是无效的，参见 #5515。
3. **包名约束**：模板中的 `python_package` 必须避免与 Python 标准库模块（如 `email`、`typing`、`string`）或关键字同名，否则后续导入会产生命名冲突。社区 #5607 已指出，当前 `kedro new` 只校验字符集，并未阻止这类破坏性命名。
4. **打包与发布**：项目被打包安装时，`src/` 目录会被整体纳入 wheel；若存在未完成的 pipeline 导致 `kedro run` 中断，可借助 #5582 提议的 `exclude_pipelines` 参数临时绕开。

参考资料汇总：
- [kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/__init__.py]()
- [kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/__main__.py]()
- [kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipeline_registry.py]()
- [kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/pipelines/__init__.py]()
- [kedro/templates/project/{{ cookiecutter.repo_name }}/src/{{ cookiecutter.python_package }}/settings.py]()

---

<a id='page-kedro-server'></a>

## Server 模块

### 相关页面

相关主题：[Src 模块](#page-kedro-templates-project--cookiecutter-repo_name--src)

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

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

- [kedro/server/__init__.py](https://github.com/kedro-org/kedro/blob/main/kedro/server/__init__.py)
- [kedro/server/http_server.py](https://github.com/kedro-org/kedro/blob/main/kedro/server/http_server.py)
- [kedro/server/models.py](https://github.com/kedro-org/kedro/blob/main/kedro/server/models.py)
- [kedro/server/utils.py](https://github.com/kedro-org/kedro/blob/main/kedro/server/utils.py)
- [kedro/framework/session/session.py](https://github.com/kedro-org/kedro/blob/main/kedro/framework/session/session.py)
- [kedro/framework/cli/cli.py](https://github.com/kedro-org/kedro/blob/main/kedro/framework/cli/cli.py)
</details>

# Server 模块

`Server` 模块是 Kedro 在 1.5.0 版本引入的 HTTP 服务层，用于以 REST 风格将项目内部的流水线执行能力暴露给外部调用方（如编排平台、CI/CD 或自定义前端）。它将 `KedroServiceSession` 与轻量级 HTTP 服务器组装在一起，提供"运行流水线、健康检查、获取快照"三类原子操作，使 Kedro 项目可以被远程驱动而无需复制运行逻辑 资料来源：[kedro/server/__init__.py:1-30]()。

## 1. 模块定位与职责

`kedro.server` 包位于框架层之下、应用层之上，目的是把"项目执行"抽象成"无状态的请求-响应"模型。该模块明确不参与构建流水线本身，而是依赖会话层加载项目元数据，再交由 HTTP 处理器触发 `KedroServiceSession.run()`。模块入口在 `__init__.py` 中仅做符号再导出，便于上层 `kedro.server.http_server`、`kedro.server.models`、`kedro.server.utils` 的统一引用 资料来源：[kedro/server/__init__.py:1-40]()。

| 子模块 | 主要职责 |
| --- | --- |
| `http_server.py` | 注册路由、构建 FastAPI/ASGI 应用并处理请求 |
| `models.py` | 定义请求/响应数据模型（Pydantic） |
| `utils.py` | 解析项目路径、序列化快照、辅助工具函数 |

## 2. HTTP 路由与端点语义

`http_server.py` 定义了三条核心路由，构成最小可用的远程执行协议 资料来源：[kedro/server/http_server.py:1-80]()：

- `POST /run`：接收流水线名称、运行时参数及可选的数据注入 payload，调用 `KedroServiceSession` 触发运行并返回运行标识；
- `GET /health`：返回服务存活状态，用于探针与负载均衡器；
- `GET /snapshot`：序列化当前项目的流水线目录、数据目录与配置版本，作为后续请求的"上下文校验点"。

服务器启动时通过应用工厂 `create_app()` 装配中间件（如日志、CORS）并绑定上述路由，使 Kedro 项目在被打包后可以由外部平台以 HTTP 形式调用 资料来源：[kedro/server/http_server.py:40-120]()。

```mermaid
flowchart LR
    Client[外部客户端] -->|/run, /health, /snapshot| HTTP[http_server.py]
    HTTP --> Models[models.py<br/>请求/响应模型]
    HTTP --> Utils[utils.py<br/>项目解析与序列化]
    HTTP --> Session[KedroServiceSession]
    Session --> Project[Kedro Project<br/>pipelines / catalog]
```

## 3. 数据模型与请求体

`models.py` 使用 Pydantic 描述请求体的形状，以确保运行时参数注入是类型安全的 资料来源：[kedro/server/models.py:1-60]()。典型字段包括：

- `pipeline_name`：要运行的流水线标识（字符串）；
- `params`：键值对形式的运行时参数，将被透传给 `KedroServiceSession.run()`；
- `inputs` / `outputs`：用于覆盖数据集内存中值的注入字典，启用多轮运行场景；
- `run_id`（可选）：客户端指定的运行标识，便于分布式追踪。

响应模型则封装了运行状态、最终状态码与消息文本，使调用方可以解析统一的结构而非裸文本 资料来源：[kedro/server/models.py:30-90]()。

## 4. CLI 集成与启动方式

服务器通过新的 CLI 命令 `kedro server start` 暴露给终端用户。该命令由 `framework/cli/cli.py` 注册，并在调用时读取项目根目录、端口与主机配置，最终委托给 `kedro.server.http_server.create_app()` 启动 ASGI 服务 资料来源：[kedro/framework/cli/cli.py:1-50]()。社区反馈显示，启动命令应确保从项目根目录运行，避免子包 `settings.py` 被忽略的问题（参见 issue #5515）——这是因为 `KedroServiceSession` 在初始化时会重新读取 `pyproject.toml` 中声明的 `kedro init` 路径 资料来源：[kedro/framework/session/session.py:1-80]()。

辅助工具 `utils.py` 负责把项目元数据转化为 `/snapshot` 端点所需的 JSON 结构，包括流水线列表、参数来源以及数据集定义，从而让客户端在调用 `/run` 之前可以先比对上下文 资料来源：[kedro/server/utils.py:1-60]()。

## 5. 使用建议与已知边界

- 该会话实现仍处于"积极开发"阶段，官方在 1.4.0 发布说明中明确提示可能存在偶发缺陷或破坏性变更 资料来源：[README/release-notes](kedro/releases/tag/1.4.0)。
- 服务层将 `KedroServiceSession` 的多轮运行与数据注入能力暴露到网络，因此应在生产部署中通过反向代理或中间件加入鉴权、限流与 TLS，避免 `/run` 端点被滥用 资料来源：[kedro/server/http_server.py:60-140]()。
- 由于服务器会读取项目根的 `pyproject.toml` 与 `settings.py`，在 monorepo（uv workspace）布局下请确保启动位置正确，否则钩子与包配置将不会生效 资料来源：[kedro/framework/session/session.py:40-100]()。

---

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

---

## Doramagic 踩坑日志

项目：kedro-org/kedro

摘要：发现 31 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：Add exclude_pipelines parameter to find_pipelines。

## 1. 安装坑 · 来源证据：Add exclude_pipelines parameter to find_pipelines

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Add exclude_pipelines parameter to find_pipelines
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/kedro-org/kedro/issues/5582 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：Kedro x MLRun

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Kedro x MLRun
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/kedro-org/kedro/issues/5305 | 来源类型 github_issue 暴露的待验证使用条件。

## 3. 安装坑 · 来源证据：ci: Nightly build failure on `develop`

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ci: Nightly build failure on `develop`
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/kedro-org/kedro/issues/5601 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 安装坑 · 来源证据：ci: Nightly build failure on `main`

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：ci: Nightly build failure on `main`
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/kedro-org/kedro/issues/5600 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 维护坑 · 来源证据：Revise and update AWS deployment docs

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Revise and update AWS deployment docs
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/kedro-org/kedro/issues/5304 | 来源类型 github_issue 暴露的待验证使用条件。

## 6. 安装坑 · 失败模式：installation: 1.0.0

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

## 7. 安装坑 · 失败模式：installation: 1.1.0

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

## 8. 安装坑 · 失败模式：installation: 1.2.0

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

## 9. 安装坑 · 失败模式：installation: 1.3.0

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

## 10. 安装坑 · 失败模式：installation: 1.4.0

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

## 11. 安装坑 · 来源证据：Document how to add docs with MkDocs when the docs tool is not selected

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Document how to add docs with MkDocs when the docs tool is not selected
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/kedro-org/kedro/issues/5603 | 来源类型 github_issue 暴露的待验证使用条件。

## 12. 安装坑 · 来源证据：Fix the `docs` tool so generated Sphinx docs build correctly

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Fix the `docs` tool so generated Sphinx docs build correctly
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/kedro-org/kedro/issues/5592 | 来源类型 github_issue 暴露的待验证使用条件。

## 13. 安装坑 · 来源证据：Packages settings are not used when running a package pipeline from project root dir

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Packages settings are not used when running a package pipeline from project root dir
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/kedro-org/kedro/issues/5515 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 14. 安装坑 · 来源证据：kedro new accepts project names that shadow Python stdlib modules / keywords, silently producing a broken project

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：kedro new accepts project names that shadow Python stdlib modules / keywords, silently producing a broken project
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/kedro-org/kedro/issues/5607 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 15. 配置坑 · 失败模式：configuration: Packages settings are not used when running a package pipeline from project root dir

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Packages settings are not used when running a package pipeline from project root dir
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Packages settings are not used when running a package pipeline from project root dir
- 证据：failure_mode_cluster:github_issue | https://github.com/kedro-org/kedro/issues/5515 | Packages settings are not used when running a package pipeline from project root dir

## 16. 配置坑 · 失败模式：configuration: Review & update Kedro deployment docs for AWS Step Functions

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: Review & update Kedro deployment docs for AWS Step Functions
- 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Review & update Kedro deployment docs for AWS Step Functions
- 证据：failure_mode_cluster:github_issue | https://github.com/kedro-org/kedro/issues/5364 | Review & update Kedro deployment docs for AWS Step Functions

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

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

## 18. 维护坑 · 失败模式：migration: 0.19.15

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

## 19. 维护坑 · 失败模式：migration: 1.0.0rc3

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

## 20. 维护坑 · 失败模式：migration: Document how to add docs with MkDocs when the docs tool is not selected

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: Document how to add docs with MkDocs when the docs tool is not selected
- 对用户的影响：Developers may hit a documented source-backed failure mode: Document how to add docs with MkDocs when the docs tool is not selected
- 证据：failure_mode_cluster:github_issue | https://github.com/kedro-org/kedro/issues/5603 | Document how to add docs with MkDocs when the docs tool is not selected

## 21. 维护坑 · 失败模式：migration: Fix the `docs` tool so generated Sphinx docs build correctly

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: Fix the `docs` tool so generated Sphinx docs build correctly
- 对用户的影响：Developers may hit a documented source-backed failure mode: Fix the `docs` tool so generated Sphinx docs build correctly
- 证据：failure_mode_cluster:github_issue | https://github.com/kedro-org/kedro/issues/5592 | Fix the `docs` tool so generated Sphinx docs build correctly

## 22. 维护坑 · 失败模式：migration: kedro new accepts project names that shadow Python stdlib modules / keywords, silently produc...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: kedro new accepts project names that shadow Python stdlib modules / keywords, silently producing a broken project
- 对用户的影响：Developers may hit a documented source-backed failure mode: kedro new accepts project names that shadow Python stdlib modules / keywords, silently producing a broken project
- 证据：failure_mode_cluster:github_issue | https://github.com/kedro-org/kedro/issues/5607 | kedro new accepts project names that shadow Python stdlib modules / keywords, silently producing a broken project

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

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

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

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

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

## 26. 能力坑 · 失败模式：capability: Add exclude_pipelines parameter to find_pipelines

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Add exclude_pipelines parameter to find_pipelines
- 对用户的影响：Developers may hit a documented source-backed failure mode: Add exclude_pipelines parameter to find_pipelines
- 证据：failure_mode_cluster:github_issue | https://github.com/kedro-org/kedro/issues/5582 | Add exclude_pipelines parameter to find_pipelines

## 27. 能力坑 · 失败模式：capability: Kedro x MLRun

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: Kedro x MLRun
- 对用户的影响：Developers may hit a documented source-backed failure mode: Kedro x MLRun
- 证据：failure_mode_cluster:github_issue | https://github.com/kedro-org/kedro/issues/5305 | Kedro x MLRun

## 28. 能力坑 · 失败模式：capability: ci: Nightly build failure on `develop`

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this capability risk before relying on the project: ci: Nightly build failure on `develop`
- 对用户的影响：Developers may hit a documented source-backed failure mode: ci: Nightly build failure on `develop`
- 证据：failure_mode_cluster:github_issue | https://github.com/kedro-org/kedro/issues/5601 | ci: Nightly build failure on `develop`

## 29. 能力坑 · 失败模式：conceptual: Revise and update AWS deployment docs

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this conceptual risk before relying on the project: Revise and update AWS deployment docs
- 对用户的影响：Developers may hit a documented source-backed failure mode: Revise and update AWS deployment docs
- 证据：failure_mode_cluster:github_issue | https://github.com/kedro-org/kedro/issues/5304 | Revise and update AWS deployment docs

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

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

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

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

<!-- canonical_name: kedro-org/kedro; human_manual_source: deepwiki_human_wiki -->