Dify 后端 API 开发指南从 uv 环境搭建、本地联调到 Celery 任务与测试体系【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify本文基于 Dify 仓库中 api/README.md 的官方说明系统梳理 Dify 后端 API 服务在api/目录下的完整本地开发工作流如何基于uv完成依赖安装与环境初始化、如何拉起 PostgreSQL/Redis/Weaviate 等中间件、如何启动 API、Web 前端、Celery Worker 与 Beat 调度器以及测试运行与 OpenAPI 规格生成的实操方法。读完后你可以独立在本地跑起一套可联调的 Dify 后端并理解各启动脚本背后的真实命令与任务队列设计。后端服务概览API、Worker 与 Beat 三分离从仓库结构看api/目录承载了 Dify 的整个 Python 后端Flask 应用api/app.py、Celery 异步任务、中间件配置、数据迁移api/migrations/与测试api/tests/。其运行形态分为三类进程API 服务HTTP/WebSocket 接口。从 api/app.py 的源码可以看到python -m app方式启动时会先对 gevent 做monkey.patch_all()并在入口处对 psycopg 与 gRPC 做兼容补丁再通过 gevent pywsgi WebSocketHandler将服务绑定到0.0.0.0:5001以支持长连接事件推送生产环境则由 Gunicorn 与 Celery 各自完成 monkey patching见 api/gunicorn.conf.py 与 api/celery_entrypoint.py。Worker 服务消费 Redis 中的异步任务队列RAG 索引、工作流执行、邮件、插件操作等从api目录运行。Beat 调度器按周期把计划任务投递到 Worker 队列。重要变更自 v1.3.0 起Dify API 后端服务的包管理器由poetry替换为uv。因此以下所有命令都要求本机安装uv与pnpm。前置准备一条命令完成环境初始化dev/setup推荐方式是通过dev/目录下的脚本完成全部初始化。这些脚本基于自身位置解析路径SCRIPT_DIR$(dirname $(realpath $0))因此可以在仓库任意目录下执行。1. 运行初始化脚本./dev/setup查看 dev/setup 的源码可知它做了三件事拷贝三份示例环境文件为实际生效的 env 文件api/.env.example→api/.env后端配置包含SECRET_KEY等web/.env.example→web/.env.local前端配置docker/envs/middleware.env.example→docker/middleware.env中间件配置。进入api/执行uv sync --group dev同步后端依赖含 dev 组。在仓库根目录执行pnpm --dir $ROOT install通过根 workspace 一次性安装全部 JavaScript 依赖。由于./dev/setup已经通过仓库根 workspace 安装了 JS 依赖你不需要再单独执行cd web pnpm install。2. 检查关键环境变量初始化后应人工检查api/.env、web/.env.local与docker/middleware.env的取值其中SECRET_KEY的生成方法见下文“环境变量注意事项”一节。启动中间件PostgreSQL / Redis / Weaviate 等./dev/start-docker-compose从 dev/start-docker-compose 的实现看其实际执行的是docker compose --env-file middleware.env -f docker-compose.middleware.yaml -p dify up -d即读取docker/middleware.env中的变量以dify作为 compose 项目名后台启动 docker/docker-compose.middleware.yaml 定义的服务。从该文件的结构看中间件栈包含db_postgres、db_mysql、redis、sandbox代码执行沙箱、plugin_daemon插件守护进程、ssrf_proxy与weaviate等容器覆盖了 Dify 本地开发所需的数据库、缓存、向量库、代码执行与插件运行时。启动后端 API先跑数据库迁移./dev/start-apidev/start-api 内部依次执行两条命令uv run flask db upgrade uv run dotenv -f .env run --no-override -- python -m app第一步flask db upgrade会先执行 api/migrations/ 下的 Alembic 数据库迁移保证表结构与代码一致第二步通过python-dotenv加载api/.env--no-override保证已有 shell 环境变量优先再以模块方式启动应用。结合 api/app.py 的实现服务最终监听0.0.0.0:5001并使用 geventwebsocket 处理 WebSocket。启动 Web 前端并访问应用./dev/start-webdev/start-web 实际执行pnpm --dir $ROOT_DIR install pnpm --dir $ROOT_DIR/web dev:inspect同样通过仓库根 workspace 管理 JS 依赖。前端默认运行在http://localhost:3000。启动后访问http://localhost:3000即可完成应用初始化配置创建工作区、登录、配置模型供应商凭据等。启动 Worker队列、并发与部署版本差异./dev/start-workerWorker 是承载所有异步任务的 Celery 进程。dev/start-worker 封装了完整的参数化启动支持以下选项选项说明默认值-q, --queues逗号分隔的队列列表按部署版本取默认队列集-c, --concurrency工作进程数1-P, --pool池实现gevent--loglevel日志级别INFO-e, --env-file启动前 source 的额外环境变量文件无例如./dev/start-worker --queues dataset,workflow --concurrency 2 --pool prefork脚本最终执行uv run celery -A app.celery worker -P ${POOL} -c ${CONCURRENCY} --loglevel ${LOGLEVEL} -Q ${QUEUES}。当不指定队列时脚本会根据DEPLOYMENT_EDITION变量区分默认队列集COMMUNITY自托管/社区版默认dataset,dataset_summary,priority_dataset,priority_pipeline,pipeline,mail,ops_trace,app_deletion,plugin,workflow_storage,conversation,workflow,schedule_poller,schedule_executor,triggered_workflow_dispatcher,trigger_refresh_executor,retention,workflow_based_app_executionCLOUD云版本将单一的workflow队列拆分为按套餐分层的workflow_professional、workflow_team、workflow_sandbox其余队列基本一致。从脚本的帮助信息可以看到完整的队列语义映射这对按负载拆分 Worker 实例非常有用队列职责datasetRAG 索引与文档处理dataset_summary重 LLM 消耗的摘要索引生成与索引隔离workflow工作流触发社区版workflow_professional/workflow_team/workflow_sandbox云版本按套餐分层的工作流schedule_poller/schedule_executor定时轮询 / 定时执行mail邮件通知ops_trace运营追踪app_deletion应用清理plugin插件操作workflow_storage工作流存储任务conversation会话任务priority_pipeline/pipeline高优先级 / 标准管道任务triggered_workflow_dispatcher/trigger_refresh_executor触发器分发 / 刷新retention数据留存策略任务这种“按队列维度水平拆分 Worker”的设计意味着你可以在本地只启动dataset队列调试 RAG或只启动workflow队列调试工作流互不干扰。启动 Celery Beat可选计划任务./dev/start-beatBeat 负责把周期性任务按间隔投递到 Worker 队列仓库中 api/schedule/ 下的定时清理、账单刷新等任务即由此驱动。dev/start-beat 支持两个选项选项说明默认值--loglevel日志级别INFO--scheduler调度器类celery.beat:PersistentScheduler其实际执行uv --directory api run celery -A app.celery beat --loglevel ${LOGLEVEL} --scheduler ${SCHEDULER}。默认使用PersistentScheduler将会次时间持久化到 Redis进程重启后可继续原调度计划。环境变量注意事项COOKIE_DOMAIN前后端跨子域部署时必读当前后端与前端运行在不同子域名下时需要将COOKIE_DOMAIN设置为站点顶级域名如example.com。只有前后端位于同一顶级域名下认证 Cookie 才能共享否则登录态无法跨域传递。SECRET_KEY 生成在.env文件中生成SECRET_KEYapi/.env.example中的注释也说明了该值可通过同名环境变量注入。针对不同平台的 bash 命令如下。Linuxsed -i /^SECRET_KEY/c\\SECRET_KEY$(openssl rand -base64 42) .envMacBSD sed 需要空参数-i secret_key$(openssl rand -base64 42) sed -i /^SECRET_KEY/c\ SECRET_KEY${secret_key} .env运行测试pytest 分层与 Mock 环境变量1. 安装后端与测试环境依赖cd api uv sync --group dev2. 运行测试cd api uv run pytest # 运行全部测试 uv run pytest tests/unit_tests/ # 仅单元测试 uv run pytest tests/integration_tests/ # 集成测试测试目录结构与用途api/tests/unit_tests/单元测试规模庞大逾千个测试文件是本地日常开发的主要验证手段api/tests/integration_tests/集成测试api/tests/test_containers_integration_tests/基于 Testcontainers 的集成测试通常依赖容器环境api/tests/fixtures/YAML 测试夹具。一个重要的工程细节是本地测试不需要真实模型 API Key。测试通过 pytest 的env机制注入一组 Mock 环境变量如OPENAI_API_KEY、ANTHROPIC_API_KEY、PLUGIN_DAEMON_URL、MOCK_SWITCHtrue等集中定义在 api/pytest.ini 的env段中README 提到该机制由pytest-env插件驱动。同时 api/CLAUDE.md 中说明后端集成测试是 CI-only不期望在本地完整运行因此本地开发以单元测试为主即可。代码质量工具链README 推荐的质量检查命令./dev/reformat # 运行全部格式化器与 Linter uv run ruff check --fix ./ # 自动修复 lint 问题 uv run ruff format ./ # 格式化代码 uv run pyrefly check # 类型检查其中 dev/reformat 一次性串联了更完整的检查链从源码看依次为lint-imports—— import 依赖方向的 linter防止模块间产生错误层级依赖ruff check --fix与ruff format—— lint 与格式化dotenv-linter—— 同时校验api/.env.example与web/.env.example的一致性dev/pyrefly-check-local—— 类型检查。生成 OpenAPI 规格与 TypeScript 类型为了保持后端 API 文档与前端类型同步仓库提供了 Swagger/OpenAPI 规格生成脚本uv run dev/generate_swagger_specs.py --output-dir openapi脚本位于 api/dev/generate_swagger_specs.py从api目录执行将生成的 OpenAPI 规格输出到api/openapi/目录仓库中已提交生成产物见 api/openapi/markdown/ 下的 Markdown 文档。README 还提到可借助任意 OpenAPI-to-TypeScript 转换工具将规格转换为前端使用的 TypeScript 类型定义纳入 packages/contracts/ 等共享契约包中。小结Dify 后端api/的本地开发链路可以概括为dev/setup初始化环境与依赖 →dev/start-docker-compose拉起中间件 →dev/start-api迁移并启动 API5001 端口gevent WebSocket→dev/start-web启动前端3000 端口→dev/start-worker/dev/start-beat按需启动异步任务与计划任务。这套脚本化的工作流配合uv管理 Python 依赖、pnpm管理前端 workspace 依赖、pytest 环境 Mock 的测试体系使得开发者无需触碰生产 Docker 编排即可完整联调 Agentic 工作流与 RAG 管线的后端能力。【免费下载链接】difyBuild Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.项目地址: https://gitcode.com/GitHub_Trending/di/dify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考