11.2 · 测试基础设施与策略（Testing Infrastructure and Strategies）

应用编排与外部知识接入 · 本章是 Dify DeepWiki 中文译文的独立章节页，保留原始链接、源码锚点、模块标签和章节层级。

项目Dify 章节11.2 状态全文译文模块测试、发布与运维、安装与启动、系统架构、存储与持久化

项目要点页2.5 参考项目项目章节目录Dify DeepWiki 原始章节Testing Infrastructure and Strategies 上一章11.1 下一章11.3

源码线索

.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

模块标签

测试、发布与运维
安装与启动
系统架构
存储与持久化
工作流与编排

中文译文

测试基础设施与策略（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/langgenius/dify/11.2-testing-infrastructure-and-strategies

翻译时间：2026-05-27T08:44:35.501Z

翻译模型：deepseek-chat

原文字符数：17222

项目：Dify (dify)

---

测试基础设施与策略

测试基础设施总览

Dify 的测试基础设施由多个专门的测试套件组成，每个套件针对系统的不同方面。该基础设施为技术栈的每一层使用了合适的测试框架和工具。

测试套件组织

测试套件	框架	目标	Python 版本	关键依赖
API 测试	pytest	Python 后端、工作流、工具	3.12	Docker Compose、PostgreSQL、Redis、沙箱
Web 测试	Vitest	TypeScript 前端	Node 24	pnpm，无外部服务
VDB 测试	pytest	向量数据库集成	3.12	Docker Compose、9 个以上向量存储
数据库迁移测试	Flask-Migrate	数据库模式迁移	3.12	PostgreSQL、MySQL
风格检查	Ruff、ESLint	代码格式化和 lint	3.12 / Node 24	UV、pnpm、super-linter

测试编排流程

主 CI 管线使用路径过滤，根据变更的文件选择性运行测试套件，从而最大限度地减少 CI 执行时间。

标题："主 CI 编排逻辑"

graph TB
    subgraph "测试执行编排"
        MainCI["主 CI 管线<br/>.github/workflows/main-ci.yml"]
        PathFilter["dorny/paths-filter<br/>变更文件检测"]

        MainCI --> PathFilter
    end

    subgraph "测试套件触发器"
        APIFlag["api-changed<br/>api/**<br/>docker/**"]
        WebFlag["web-changed<br/>web/**"]
        VDBFlag["vdb-changed<br/>api/core/rag/datasource/**"]
        MigFlag["migration-changed<br/>api/migrations/**"]

        PathFilter --> APIFlag
        PathFilter --> WebFlag
        PathFilter --> VDBFlag
        PathFilter --> MigFlag
    end

    subgraph "并行测试执行"
        APITests["运行 Pytest<br/>.github/workflows/api-tests.yml"]
        WebTests["Web 测试<br/>.github/workflows/web-tests.yml"]
        VDBTests["运行 VDB 冒烟测试<br/>.github/workflows/vdb-tests.yml"]
        MigTests["数据库迁移测试<br/>.github/workflows/db-migration-test.yml"]
        StyleCheck["风格检查<br/>.github/workflows/style.yml"]

        APIFlag -->|若为真| APITests
        WebFlag -->|若为真| WebTests
        VDBFlag -->|若为真| VDBTests
        MigFlag -->|若为真| MigTests
        MainCI --> StyleCheck
    end

    subgraph "测试依赖"
        DockerMiddleware["docker-compose.middleware.yaml<br/>db_postgres, redis<br/>sandbox, ssrf_proxy"]
        DockerVDB["docker-compose.yaml<br/>weaviate, qdrant, pgvector<br/>chroma 等"]

        APITests --> DockerMiddleware
        VDBTests --> DockerVDB
        MigTests --> DockerMiddleware
    end

来源：.github/workflows/main-ci.yml:38-125, .github/workflows/api-tests.yml:1-130, .github/workflows/web-tests.yml:1-126, .github/workflows/vdb-tests.yml:1-68, .github/workflows/db-migration-test.yml:1-139

使用 pytest 进行 API 测试

API 测试验证 Python 后端，包括工作流执行、工具集成和核心业务逻辑。测试使用 uv run 运行，以确保环境管理的一致性。

测试执行配置

API 测试套件定义在 .github/workflows/api-tests.yml 中。关键配置如下：

矩阵策略：测试在 Python 3.12 上运行 .github/workflows/api-tests.yml:27-28。
依赖管理：使用 astral-sh/setup-uv 进行依赖安装，并通过 uv lock --check 验证锁文件 .github/workflows/api-tests.yml:38-45。
并行执行：pytest -n auto 根据 CPU 核心数自动确定工作进程数量 .github/workflows/api-tests.yml:58。
控制器处理：控制器测试在导入时注册 Flask 路由，因此它们被排除在 xdist 并行化之外，并使用 --cov-append 顺序运行 .github/workflows/api-tests.yml:62-67。

基于容器的集成测试

Dify 使用 TestContainers 进行集成测试，以确保测试针对真实的服务实现运行 api/tests/test_containers_integration_tests/conftest.py:4-7。

DifyTestContainers 类管理这些服务的生命周期 api/tests/test_containers_integration_tests/conftest.py:61-70：

PostgreSQL：使用 PostgresContainer 初始化，包括安装 uuid-ossp 扩展 api/tests/test_containers_integration_tests/conftest.py:103-138。
Redis：使用 RedisContainer 初始化，用于缓存和会话管理 api/tests/test_containers_integration_tests/conftest.py:155-163。
沙箱：一个运行 langgenius/dify-sandbox 的 DockerContainer，用于安全代码执行 api/tests/test_containers_integration_tests/conftest.py:167-170。

标题："API 集成测试环境"

graph LR
    subgraph "Pytest 执行上下文"
        PytestRunner["pytest 运行器<br/>uv run pytest"]
        DifyTestContainers["DifyTestContainers<br/>conftest.py"]
    end

    subgraph "Docker 容器"
        PostgresContainer["PostgresContainer<br/>postgres:14-alpine"]
        RedisContainer["RedisContainer<br/>redis:6-alpine"]
        SandboxContainer["DockerContainer<br/>dify-sandbox"]
    end

    PytestRunner --> DifyTestContainers
    DifyTestContainers --> PostgresContainer
    DifyTestContainers --> RedisContainer
    DifyTestContainers --> SandboxContainer

    subgraph "集成目标"
        WorkflowTests["api/tests/integration_tests/workflow"]
        ToolTests["api/tests/integration_tests/tools"]
        ContainerTests["api/tests/test_containers_integration_tests"]
    end

    PytestRunner --> WorkflowTests
    PytestRunner --> ToolTests
    PytestRunner --> ContainerTests

来源：api/tests/test_containers_integration_tests/conftest.py:61-170, .github/workflows/api-tests.yml:113-121

使用 Vitest 进行 Web 测试

Web 测试使用 Vitest 验证 TypeScript/React 前端。测试在 Node 24 上使用 pnpm 运行。

Vitest 分片

Web 测试在 4 个并行作业中进行分片，以减少执行时间 .github/workflows/web-tests.yml:25-26。每个分片使用以下命令执行： vp test run --reporter=blob --shard=${{ matrix.shardIndex }}/${{ matrix.shardTotal }} --coverage .github/workflows/web-tests.yml:42。

共享组件测试

dify-ui 共享库被单独测试，包括安装 Playwright 以进行浏览器模式测试 .github/workflows/web-tests.yml:93-113。

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

向量数据库集成测试

VDB 测试使用冒烟测试策略验证与多个向量数据库实现的集成。

向量存储冒烟测试

VDB 测试套件使用 --start-vdb pytest 标志启动向量数据库 .github/workflows/vdb-tests.yml:62。测试针对特定的提供商实现：

向量存储	实现路径
Chroma	`api/providers/vdb/vdb-chroma`
PGVector	`api/providers/vdb/vdb-pgvector`
Qdrant	`api/providers/vdb/vdb-qdrant`
Weaviate	`api/providers/vdb/vdb-weaviate`

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

数据库迁移测试

迁移测试确保模式变更在 PostgreSQL 和 MySQL 上都能正常工作，同时验证离线 SQL 生成和在线执行 .github/workflows/db-migration-test.yml:1-139。

双数据库策略

PostgreSQL：使用 flask upgrade-db 验证标准迁移路径 .github/workflows/db-migration-test.yml:11-60。
MySQL：通过修改环境变量中的 DB_TYPE 和 DB_PORT 来验证兼容性 .github/workflows/db-migration-test.yml:87-112。
等待机制：对于 MySQL，管线轮询 SELECT 1 查询，直到 InnoDB 引擎完全初始化，以避免"连接丢失"错误 .github/workflows/db-migration-test.yml:119-133。
离线验证：确保 flask db upgrade --sql 和 flask db downgrade --sql 对 base:head 和 head:base 都有效 .github/workflows/db-migration-test.yml:30-35。

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

风格检查和 Lint

风格检查在每个 PR 和推送时运行，在整个技术栈中强制执行标准。

Python 风格检查

导入 Lint：通过 lint-imports 验证模块边界 .github/workflows/style.yml:48。
类型检查：使用 mypy 和 pyrefly 通过 make type-check-core 执行核心类型检查 [.github/workflows/style.yml:52, [Makefile:91-95]]()。
Pyrefly Diff：一种专门的检查，比较 PR 分支和基础分支之间的 pyrefly 诊断结果，并将差异直接评论在 PR 上 .github/workflows/pyrefly-diff.yml:12-104。

Web 风格检查

ESLint：使用恢复的缓存运行 vp run lint:ci .github/workflows/style.yml:94-107。
TSSLint：通过 vp run lint:tss 进行类型感知的 lint .github/workflows/style.yml:114。
Knip：识别未使用的文件、依赖和导出 .github/workflows/style.yml:124。

来源：.github/workflows/style.yml:16-172, .github/workflows/pyrefly-diff.yml:1-104

自动修复和现代化

autofix.yml 工作流自动对 PR 应用格式化和结构转换。

AST-Grep 转换

Dify 使用 ast-grep 来现代化代码模式，特别针对 SQLAlchemy 2.0 语法和 Python 类型提示 .github/workflows/autofix.yml:85-113。

标题："代码实体现代化流程"

graph LR
    subgraph "SQLAlchemy 现代化"
        FilterPattern["db.session.query().filter()"]
        WhereRewrite["db.session.query().where()"]
        ColumnPattern["db.Column()"]
        MappedRewrite["mapped_column()"]

        FilterPattern -->|ast-grep| WhereRewrite
        ColumnPattern -->|ast-grep| MappedRewrite
    end

    subgraph "类型系统现代化"
        OptionalPattern["Optional[T]"]
        UnionRewrite["T | None"]

        OptionalPattern -->|ast-grep| UnionRewrite
    end

来源：.github/workflows/autofix.yml:85-113