如何本地启动 Dify Agent 服务器并配置 Redis、plugin daemon 与 inner API 密钥

如何本地启动 Dify Agent 服务器并配置 Redis、plugin daemon 与 inner API 密钥【免费下载链接】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/difyDify Agent 的运行服务器run server是一个 FastAPI/uvicorn 进程它用 Redis 保存 run 记录和每个 run 的事件流并通过 plugin daemon 与 Dify API 的 inner 端点调用模型和插件。本文的目标是在本机完成依赖安装、启动 Redis、写入最小配置然后用make serve把服务器跑在http://127.0.0.1:8000并验证一次由 plugin daemon 支撑的 run 能够成功。前提环境来自 get-started 文档Python 3.12 或更新版本、uv、一个可达的 Redis以及一个可达的 Dify plugin daemon且该 daemon 中已有可用的插件/provider例如langgenius/openai。准备条件与安装依赖确认本机已具备 Python 3.12 和uv。从仓库根目录进入dify-agent包安装所有 extras 与依赖组cd dify-agent uv sync --all-extras --all-groups文档说明运行 API server 只需要serverextra但一次性安装全部 extras 和 groups 会把本地测试、文档和 server 依赖放进同一个环境省去后续单独安装。启动 Redis如果已有可达的 Redis 实例跳过这一步。否则用 Docker 起一个docker run -d \ --name dify-agent-redis \ -p 6379:6379 \ redis:7-alpine该命令会创建一个后台容器并占用本机 6379 端口如果你的 6379 已被占用应改用已有的 Redis 实例而不是重复执行这条命令。写入 .envRedis、plugin daemon 与 inner API 密钥在dify-agent目录创建或更新.env。文档给出的最小配置是这 6 项DIFY_AGENT_REDIS_URLredis://localhost:6379/0 DIFY_AGENT_REDIS_PREFIXdify-agent DIFY_AGENT_PLUGIN_DAEMON_URLhttp://localhost:5002 DIFY_AGENT_PLUGIN_DAEMON_API_KEYreplace-with-plugin-daemon-server-key DIFY_AGENT_INNER_API_URLhttp://localhost:5001 DIFY_AGENT_INNER_API_KEYreplace-with-dify-inner-api-key-for-plugin各项含义来自 get-started 文档DIFY_AGENT_REDIS_URLrun 记录与事件流使用的 Redis 连接 URLDIFY_AGENT_REDIS_PREFIX该服务器在 Redis 中的键前缀DIFY_AGENT_PLUGIN_DAEMON_URLDify plugin daemon 的 base URL本地默认http://localhost:5002DIFY_AGENT_PLUGIN_DAEMON_API_KEY服务器发给 plugin daemon 的 API key。在 Dify Docker 部署中它通常就是此前配置为PLUGIN_DAEMON_KEY的值DIFY_AGENT_INNER_API_URLDify API 服务根地址用于/inner/api/...调用DIFY_AGENT_INNER_API_KEY发给 Dify API inner plugin 端点的 key。在 Docker 部署中它对应PLUGIN_DIFY_INNER_API_KEY也就是 Dify API 的INNER_API_KEY_FOR_PLUGIN。两个占位值的获取位置如果你的 Dify 是 Docker 部署PLUGIN_DAEMON_KEY和PLUGIN_DIFY_INNER_API_KEY在 docker/.env.example 中有默认值实际部署时应读取你docker/.env中对应行的值Docker Compose 中 plugin daemon 服务的SERVER_KEY正是取${PLUGIN_DAEMON_KEY:-...}见 docker/docker-compose.yaml模板中还有一处关键区分DIFY_AGENT_INNER_API_KEY必须匹配 API/worker 的INNER_API_KEY_FOR_PLUGIN而不是通用的INNER_API_KEY见 dify-agent/.example.env。完整设置模板见 .example.env 和 Operations Guide 中的配置表其中DIFY_AGENT_API_TOKEN私有 run 等控制面路由的 Bearer token需与 Dify API 的AGENT_BACKEND_API_TOKEN一致、保留时长、超时等均为可选项最小路径可以不配置。启动服务器在dify-agent目录下执行make serve需要 uvicorn 热重载的本地开发场景用make dev两个目标最终都执行同一形式的命令来自 dify-agent/Makefileuv run --project . --extra server uvicorn dify_agent.server.app:app \ --host 127.0.0.1 \ --port 8000等价的手动命令make dev版本uv run --extra server uvicorn dify_agent.server.app:app \ --host 127.0.0.1 \ --port 8000 \ --reloadServerSettings会从当前dify-agent目录读取.env从仓库根目录执行命令时则读取dify-agent/.env。启动后 API 服务在http://127.0.0.1:8000。验证跑一次 plugin-daemon-backed 的 run服务器监听127.0.0.1:8000只是进程级验证。文档给出的端到端验证方式是在另一个 shell 里运行 Python 客户端示例。继续在dify-agent目录创建run_dify_agent_client.py完整代码见 get-started 文档这里保留关键结构API_BASE_URL http://127.0.0.1:8000 TENANT_ID replace-with-tenant-id PLUGIN_ID langgenius/openai USER_ID replace-with-user-id APP_ID replace-with-app-id # Keep these aligned with DIFY_AGENT_PROVIDER and DIFY_AGENT_MODEL_NAME in dify-agent/.env. MODEL_PROVIDER replace-with-provider-from-dify-agent-env MODEL_NAME replace-with-model-from-dify-agent-env示例随后用Client(base_urlAPI_BASE_URL, ...)调用create_run提交一个由plain.prompt、dify.execution_context和dify.plugin.llm三层组成的RunComposition再流式消费事件收到run_succeeded打印event.data.output并以退出码 0 结束收到run_failed打印event.data.error并以退出码 2 结束。运行前必须替换的占位值TENANT_ID、USER_ID、APP_ID用你 Dify 环境中的真实值MODEL_PROVIDER和MODEL_NAME必须与dify-agent/.env中DIFY_AGENT_PROVIDER、DIFY_AGENT_MODEL_NAME相同PLUGIN_ID用 plugin daemon 中已安装的插件文档示例用langgenius/openai。服务器端.env决定 Dify Agent 如何到达 Dify API 和 plugin daemon客户端示例只选择 tenant/user/app/plugin/provider/model模型凭据由 Dify API 在调用时解析。uv run python ./run_dify_agent_client.py判定标准就是示例代码本身的行为终端打印created run: {run_id}, status...随后出现final output:与模型输出即为成功出现run failed: ...则进入下面的排查。排查与限制文档给出的排查顺序run 失败时按此检查Redis 正在运行且从 Dify Agent server 可达Dify Agent server 正在监听127.0.0.1:8000DIFY_AGENT_INNER_API_URL指向本环境实际使用的 Dify APIDIFY_AGENT_INNER_API_KEY与 Dify API 配置的 inner API key 一致客户端示例中的PLUGIN_ID、MODEL_PROVIDER、MODEL_NAME与 Dify API 中为该 tenant 配置的模型 provider 匹配。文档明确的边界本地开发只需要一个 uvicorn 进程加 Redisplugin 支撑的 run 额外要求可达的 plugin daemon。run 执行发生在请求处理之外客户端断开不会取消 agent run见 Operations Guide。每个 run 显式限制 Pydantic AI 为 500 个 model-request 步骤DIFY_AGENT_RUN_TIMEOUT_SECONDS默认 3600 秒只作用于agent.run(...)的 model/tool 循环超时的 run 以error_type: agent_run_limit_exceeded失败。Redis 只用于 run 记录与事件流的共享状态/事件可见性GET /runs/{run_id}返回running、succeeded、failed或cancelledGET /runs/{run_id}/events/sse以 SSE 回放并流式输出事件终态事件run_succeeded/run_failed/run_cancelled之后服务器会正常关闭 SSE 连接客户端不应再重连。Redis Cluster 不被支持用于该服务器的 run 协调键这些键没有共享的 hash tag无法在 Lua 脚本中执行。若还需 shell 能力文档要求另行选择一致的 Home Snapshot / Execution Binding 后端Local 默认、E2B 需要DIFY_AGENT_E2B_API_KEY等这超出了本地最小启动范围本地服务器不配置DIFY_AGENT_LOCAL_SANDBOX_ENDPOINT时dify.runtime和资源端点保持禁用。【免费下载链接】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），仅供参考