11.3 · CI 管线架构（CI Pipeline Architecture）

CI 管线架构

CI 管线架构

相关源文件

本章引用的主要源码文件：

• .github/labeler.yml
• .github/workflows/api-tests.yml
• .github/workflows/autofix.yml
• .github/workflows/build-push.yml
• .github/workflows/db-migration-test.yml
• .github/workflows/docker-build.yml
• .github/workflows/main-ci.yml
• .github/workflows/pyrefly-diff-comment.yml
• .github/workflows/pyrefly-diff.yml
• .github/workflows/style.yml
• .github/workflows/tool-test-sdks.yaml
• .github/workflows/translate-i18n-claude.yml
• .github/workflows/trigger-i18n-sync.yml
• .github/workflows/vdb-tests-full.yml
• .github/workflows/vdb-tests.yml
• .github/workflows/web-tests.yml
• depot.json

本文档描述了基于 GitHub Actions 的 Dify 平台持续集成和持续部署管线。内容涵盖测试工作流的编排、Docker 镜像构建、代码质量自动化以及部署流程。

有关本地开发环境搭建的信息，请参阅开发环境搭建。有关测试基础设施和 pytest/vitest 配置的详细信息，请参阅测试基础设施与策略。有关代码质量工具和 lint 规则，请参阅代码质量与 Lint。

主 CI 管线编排

CI 的主要入口是 main-ci.yml 工作流，它根据哪些文件被修改来编排多个测试工作流。这种基于路径的过滤策略通过只运行相关测试来优化 CI 执行时间。

工作流结构

标题：CI 管线编排流程

check-changes 任务使用 dorny/paths-filter 操作来检测哪些代码区域被修改，为每个子系统生成布尔输出。后续任务使用 needs 和 if 条件来有条件地执行。

来源：.github/workflows/main-ci.yml:1-80

路径过滤配置

样式检查任务始终运行，无论哪些文件被修改，以确保全局 lint 标准。

来源：.github/workflows/main-ci.yml:51-125

可复用工作流模式

Dify 使用 GitHub Actions 的 workflow_call 触发器来创建可复用工作流模块。主管线使用 uses 语法调用这些工作流，从而实现组合并减少重复。

标题：可复用工作流组合

每个可复用工作流声明 on: workflow_call，允许被其他工作流调用，同时如果指定了密钥，则会继承密钥。

来源：.github/workflows/api-tests.yml:3-4、.github/workflows/web-tests.yml:3-4、.github/workflows/style.yml:3-4、.github/workflows/vdb-tests.yml:3-4、.github/workflows/db-migration-test.yml:3-4

测试执行工作流

API 测试工作流

api-tests.yml 工作流使用 pytest 执行 Python 后端测试。

工作流步骤：

1. 环境搭建：astral-sh/setup-uv 安装 UV 包管理器并启用缓存 .github/workflows/api-tests.yml:37-42。
2. 锁定文件校验：uv lock --project api --check 确保锁定文件是最新的 .github/workflows/api-tests.yml:45-45。
3. 依赖安装：uv sync --project api --dev 安装所有生产和开发依赖 .github/workflows/api-tests.yml:48-48。
4. 单元测试：对 api/tests/unit_tests 运行 pytest，涵盖核心、提供者和控制器 .github/workflows/api-tests.yml:53-68。
5. 集成测试：执行工作流和工具集成测试，支持中间件 .github/workflows/api-tests.yml:112-121。

环境配置：

STORAGE_TYPE: opendal
OPENDAL_SCHEME: fs
OPENDAL_FS_ROOT: /tmp/dify-storage

来源：.github/workflows/api-tests.yml:81-83

Web 测试工作流

web-tests.yml 工作流运行 Vitest 测试，使用分片进行并行化，并生成覆盖率报告。

标题：Web 测试分片与覆盖率合并

该工作流使用 4 路分片来并行化测试执行 .github/workflows/web-tests.yml:25-26。每个分片上传一个 blob 报告制品 .github/workflows/web-tests.yml:44-51。merge-reports 任务下载所有制品并使用 vp test --merge-reports 合并结果 .github/workflows/web-tests.yml:81-82。

来源：.github/workflows/web-tests.yml:17-91

向量数据库测试工作流

vdb-tests.yml 工作流通过启动数据库服务来测试与向量数据库实现的集成。

支持的存储（冒烟覆盖）：

• vdb-chroma
• vdb-pgvector
• vdb-qdrant
• vdb-weaviate

来源：.github/workflows/vdb-tests.yml:64-67

该工作流为每个提供者执行特定的集成测试 .github/workflows/vdb-tests.yml:59-67：

uv run --project api pytest --start-vdb api/providers/vdb/vdb-chroma/tests/integration_tests ...

数据库迁移测试工作流

db-migration-test.yml 工作流验证数据库迁移在 PostgreSQL 和 MySQL 上都能正常工作。

校验模式：

• 离线迁移：flask db upgrade 'base:head' --sql 确保无需实时数据库即可生成 SQL .github/workflows/db-migration-test.yml:33-33。
• 在线迁移：flask upgrade-db 将迁移应用到正在运行的容器实例 .github/workflows/db-migration-test.yml:59-59。
• MySQL 就绪检查：对于 MySQL 8.0，管线轮询 SELECT 1 查询以确保 InnoDB 初始化完成后再运行迁移 .github/workflows/db-migration-test.yml:119-130。

来源：.github/workflows/db-migration-test.yml:11-138

构建与推送管线

build-push.yml 工作流构建多架构 Docker 镜像并推送到 Docker Hub。

多架构构建策略

标题：多架构构建管线

关键技术：

• Depot：使用 depot/build-push-action 进行加速的远程构建 .github/workflows/build-push.yml:87-95。
• Docker 元数据：使用 docker/metadata-action 生成标准标签（latest、分支、sha） .github/workflows/build-push.yml:79-84。
• 清单创建：使用 docker buildx imagetools create 将架构特定的摘要合并到单个清单中 .github/workflows/build-push.yml:175-182。

来源：.github/workflows/build-push.yml:26-189

代码质量自动化

自动修复工作流

autofix.yml 工作流自动应用代码格式化和现代化修复。

自动转换：

• Ruff：运行 ruff format 和 ruff check --fix 进行 Python lint .github/workflows/autofix.yml:72-77。
• ast-grep：执行结构性代码重写，例如将 db.session.query().filter() 转换为 db.session.query().where()，并将 db.Column 现代化为 mapped_column .github/workflows/autofix.yml:85-92。
• 类型现代化：使用自定义 ast-grep 规则将 Optional[T] 转换为 T | None .github/workflows/autofix.yml:94-110。
• ESLint：对前端代码运行 eslint --fix .github/workflows/autofix.yml:129-132。
• 契约生成：根据 OpenAPI 规范自动更新 API 文档和前端契约 .github/workflows/autofix.yml:119-127。

来源：.github/workflows/autofix.yml:68-132

样式检查详情

style.yml 工作流执行更深入的静态分析：

• Python：运行 lint-imports 以强制执行架构边界，以及 make type-check-core 进行 mypy 校验 .github/workflows/style.yml:46-52。
• Web：运行 knip 检测死代码，以及 tsslint 执行 TypeScript 特定的样式规则 .github/workflows/style.yml:109-124。
• SuperLinter：使用 hadolint 和 shellcheck 校验 Shell 脚本、YAML 和 Dockerfile .github/workflows/style.yml:156-175

CI 能力总结

来源：.github/workflows/main-ci.yml:1-125、.github/workflows/autofix.yml:1-136、.github/workflows/translate-i18n-claude.yml:1-167