结论：适合先查 API 容器到 Plugin Daemon 的连通性、服务地址和密钥，再核对镜像与部署文件版本；不适合一上来改容器 IP 或照抄旧版端口配置。 如果请求路径可达而插件仍装不上，应结合 API 日志、Daemon 日志和页面实际结果继续定位，不能只凭一条 SDK 提示断定 Daemon 宕机。
正在排查 Dify 插件无法安装、插件管理页加载失败的自托管用户，可以按本文逐层缩小范围。
如果你维护定制的 Docker Compose 文件，或升级后开始出现 Plugin Daemon 请求错误，版本和配置核对尤其重要。
负责长期运行知识库或 AI 工作流的团队，也可以用文末的验收方法判断问题究竟是部署故障，还是需要另行规划资源。
Dify 自托管插件安装失败，先分清报错落在哪一层
同一条用户可见提示，背后可能是容器无法解析服务名、Daemon 没有监听、密钥校验失败，也可能是单个插件的初始化或安装环节出错。先记录完整页面错误和发生时间，再把同一时间段的 API 与 Daemon 日志放在一起看；单条醒目的日志不是完整故障证据。
| 现象 | 优先检查 | 暂时不要下的结论 |
|---|---|---|
| 安装操作失败，但管理页面仍可打开 | 安装请求对应的 API 与 Daemon 日志、插件包处理结果 | 不能据此判定整个 Daemon 不可用 |
| 管理页加载失败或 API 报连接拒绝 | API 容器中的服务名解析、网络成员关系、Daemon 状态和监听地址 | 不能先把容器 IP 写死 |
| API 返回认证或权限类 HTTP 错误 | URL 路径、请求目标、双方密钥和部署模式 | 不能把所有 HTTP 错误都当作网络中断 |
| 日志出现插件 SDK 版本提示 | 对照插件是否启动、Daemon 是否健康及相关请求是否成功 | 不能仅凭 SDK 提示认定它是请求失败根因 |
连接拒绝通常表示客户端已经尝试连接，但目标地址或端口上没有接受连接的服务；名称解析失败则说明服务发现这一步还没通过。反过来，若已收到 HTTP 响应，即使响应码不是成功，也只能说明传输路径有响应，认证、路由和插件操作仍需单独验证。
API 到 Daemon 不通时，先查服务名和网络
在标准 Docker Compose 网络中，同一网络上的服务可通过 Compose 服务名互相发现；容器重建后 IP 地址可能变化，因此固定写入临时容器 IP 容易造成下一次重建再次失联。Docker 官方也建议以服务名寻址，而不是依赖动态分配的 IP。(Docker Compose 网络文档)
先进入运行 Dify 的 docker 目录，确认实际使用的项目和服务状态：
docker compose ps
docker compose logs --since=10m api plugin_daemon
确认服务名与容器状态后，从 API 容器检查 DNS 和 TCP 连通性。下面示例使用 Python 标准库，不要求 API 容器预装 curl：
docker compose exec api python -c \
'import socket; print(socket.getaddrinfo("plugin_daemon", 5002)); s=socket.create_connection(("plugin_daemon", 5002), 3); print("TCP connected"); s.close()'
输出若包含解析地址并显示 TCP connected，说明该次检查中的 DNS 与 TCP 建连通过；这不等于插件请求已通过认证，也不证明安装流程完成。若出现名称解析错误，检查 api 与 plugin_daemon 是否处于共同的 Compose 网络；若出现超时或拒绝连接，再检查 Daemon 容器状态、监听端口和是否刚刚重启。
如服务名与配置中的名称不同，不能机械照搬命令里的 plugin_daemon；应先从当前 Compose 文件确认服务键，再用实际服务名测试。完整部署与拆分部署的网络关系可能不同，必要时以当前项目的网络配置为准。
地址、密钥与部署模式对不上时，逐项对照
服务已启动并不代表 API 一定能按正确地址访问 Daemon。检查时把“API 请求 Daemon”和“Daemon 回调 Dify 内部 API”分开看：它们是不同方向的连接，URL、目标服务和认证配置不能混为一项。当前版本的配置模板和 Compose 文件，才是判断变量名称与映射关系的依据。(Dify Plugin Daemon 环境变量模板)
| 对照项 | 核对方法 | 常见误区 |
|---|---|---|
| Daemon 服务地址 | 依据当前 Compose 网络和版本模板核对 API 使用的 Daemon URL | 把容器内的 localhost 当作 Daemon 的地址 |
| Daemon 访问密钥 | 检查 API 发往 Daemon 的密钥是否与对应服务配置一致 | 只改一侧，或把密钥贴到公开日志和工单 |
| 内部 API 回调地址与密钥 | 核实 Daemon 回连 API 时使用的地址及对应授权配置 | 把回调方向误当成 API 访问 Daemon 的方向 |
| 部署模式 | 对照实际启动的 Compose 文件和环境文件 | 同时混用完整容器化部署与开发用中间件配置 |
在容器内，localhost 指当前容器自身；若 API 要访问另一个 Compose 服务，通常应使用双方所在网络可解析的服务名。Dify 官方 Docker 配置会定义 Daemon 地址和内部 API 地址，但变量及映射可能随发布版本变化，不能把某个示例值当成脱离版本的万能配置。
核对密钥时避免把完整值粘贴到公共 issue、聊天记录或文章中。可以在本机分别查看对应服务的变量名，并在受控环境下比对实际值；不要把 docker compose config 的完整输出直接公开，因为合并后的配置可能包含敏感环境变量。
升级后才报错时，优先核对文件和镜像是否同版
Dify 官方部署说明明确要求升级时合并配置变化，并按对应版本更新服务；只切换源码版本、保留过期 Compose 文件或遗漏新变量，可能造成部署文件、环境变量与运行镜像不一致。官方 Docker 部署说明也提醒，升级后要查看相应 .env.example 和可选环境配置。(Dify 官方 Docker 部署说明)
建议按这个顺序复核：
- 记录当前 Dify 版本、API 镜像标签和 Plugin Daemon 镜像标签，不要只看仓库工作目录的分支名。
- 取当前版本对应的官方 Compose 文件和环境变量模板，与本地定制文件逐项比较。
- 检查是否遗漏新增变量、旧变量是否改名，以及 Compose 插值来源是否指向预期的
.env。 - 确认 API、Daemon 及相关组件按该版本要求一起更新，而不是新旧镜像混跑。
- 在备份数据库和配置后，再按对应版本的官方升级说明执行变更；升级后重新检查服务状态和关键日志。
Dify 1.18.0 发布资料给出了该版本的 Docker Compose 部署步骤，并要求按该版本处理相关组件和配置。这里应以1.18.0 Docker Compose 文件、该版本环境变量模板和官方 Docker 部署说明为准，而不是套用旧版 issue 中的端口或变量配置。
Docker Compose 的启动顺序也不能一概而论：普通依赖关系不等于依赖服务已经通过健康检查。若日志显示 API 在 Daemon 尚未就绪时已发起请求，检查当前配置的健康检查和依赖条件；不要未经验证就增加端口映射或改成固定 IP。(Docker Compose 服务启动顺序说明)
SDK 日志与请求失败并存时，不要把相关性当成根因
日志里出现插件 SDK 版本读取失败，和 API 无法请求 Daemon 是两类不同信号。你需要对照发生时间、具体插件、Daemon 是否持续运行，以及相关请求是否真的失败；如果只是某个插件初始化警告，而服务连接和其他插件操作正常，就不能由这条日志推断 Daemon 已宕机。
官方仓库里的用户报告可以帮助你识别常见报错形式，但它们记录的是特定版本、配置和环境下的个案，不能证明所有 Failed to request plugin daemon 都有同一根因。社区回复或自动生成的诊断也不是官方结论；优先检查对应版本的发布说明、Compose 文件和环境变量定义，并通过可复现的连接测试验证。
修复后按清单验收，再决定是否调整部署
在改完地址、密钥或版本配置后，不要只以“容器都在运行”作为修复完成的标准。按实际业务路径重新测试，保留变更前后的版本、Compose 文件差异和脱敏日志，方便下次升级时判断问题是否复发。
- [ ]
api与plugin_daemon均处于预期状态，且启动日志没有持续重启迹象。 - [ ] 从 API 容器解析当前配置中的 Daemon 服务名，并能建立到目标服务端口的连接。
- [ ] API 访问 Daemon 的 URL、Daemon 回调 API 的 URL，以及双方授权密钥均与当前部署模式匹配。
- [ ] API、Daemon 镜像与 Compose 文件对应同一目标版本；升级引入的配置变化已逐项核对。
- [ ] 在 Dify 界面完成插件安装，并确认管理页能够加载；如有对应 API 操作，再实际执行一次。
- [ ] 若问题仍在，保存发生时间、准确错误响应、相关服务日志和复现步骤；分享前移除密钥及敏感数据。
如果验收失败，按结果回退到对应故障层继续排查，不要仅因一次连接测试成功就宣布插件功能已恢复。Compose 网络、服务名和健康检查的具体行为分别可参照 Docker 官方关于网络与服务启动顺序的说明；它们解释的是容器通信机制，不会替代 Dify 对应版本的配置要求。
服务器资源只有在日志或监控显示持续内存、存储或计算资源不足，并且故障能在资源压力下复现时，才应进入下一轮评估；更换服务器不是 Plugin Daemon 请求错误的默认修复方式。若你已经确认需要长期运行多项自托管 AI 服务，可以先对照内存与磁盘选型说明和服务器服务边界，再检查这些服务所需的内存、数据空间和维护方式。
常见问题：网络、版本与日志该如何区分？
插件请求失败是不是一定要改 Docker 网络？
不是。只有服务名解析失败、网络不相通或 TCP 连接失败时，网络才是优先方向。若 API 已收到 HTTP 响应，应转查目标路径、密钥和 Daemon 返回内容；若只有单个插件安装异常，也要结合该插件的处理日志判断，不能把整个服务的网络当成唯一可能原因。
localhost 能不能直接作为 Plugin Daemon 地址？
通常不能把它当作另一个容器的通用地址，因为容器内的 localhost 指向当前容器。完整 Compose 部署通常依据同一网络中的服务名寻址；若你使用独立容器、外部网络或开发模式，则应以实际网络拓扑和该模式的官方配置为准。
升级后怎样判断是不是配置文件过期？
记录运行镜像标签，并将本地 Compose 文件及环境变量模板与对应版本的官方文件比较。重点查新增变量、变量映射、镜像标签和实际启动的 Compose 文件；仅仅确认仓库检出了新版本，不足以证明正在运行的容器和部署配置也已同步。
SDK 警告还在，插件能用，是否就算修好了？
不能只看警告是否消失，也不能只看某一次插件操作成功。应确认目标插件安装和管理页操作恢复、相关 API 请求成功，并检查 Daemon 是否仍在重启或持续报错。若警告只关联单个插件初始化，记录插件名称和上下文，再按对应插件与版本资料继续判断。
如果连接、配置和版本都已核实，Dify 也通过端到端验收，后续是否改用独享 AMD 物理机，应由长期运行的服务数量、内存和存储需求决定，而不是由这次故障提示决定。共享 VPS 或公有云实例可能存在共享资源争用，部分方案的流量计费和磁盘配置也需另行核对；反过来，如果你只临时调试、负载很轻或需要按秒弹性扩缩，现有小型实例可能更合适。对于确实需要稳定长期运行多项自托管服务、希望整机资源独享的团队，可先查看 OSFP Cloud 当前产品表中的配置和选配条件，再判断是否符合实际部署计划。
常见问题
Dify 显示 Failed to request plugin daemon，应该先查哪里？
先从 API 容器测试能否解析 Plugin Daemon 的服务名并建立 TCP 连接，再检查 API 与 Daemon 是否加入同一预期网络。连接成功但页面仍报错时，继续核对内部 API 地址、双方密钥和请求日志；不要只凭错误提示就改容器 IP。
Dify 自托管插件安装失败一定是网络问题吗？
不一定。DNS 解析失败、连接被拒绝或超时，才更像网络、服务监听或启动状态问题；若请求已到达 Daemon，则还要核对密钥、插件包处理结果、签名校验和版本配置。安装失败、管理页加载失败及单条 SDK 日志也可能分别对应不同故障。
怎样从 Dify API 容器检查 Plugin Daemon 连通性？
先用 Compose 服务名做 DNS 解析，再从 API 容器尝试连接当前版本配置的 Daemon 地址和端口。TCP 建立成功只证明网络路径可达，不代表插件 API、认证或安装流程正常；还要对照 API 日志、Daemon 日志和页面实际操作结果。
插件管理页报错时，哪些配置最容易对不上？
重点对照当前部署模式中的 Daemon URL、Plugin Daemon 密钥、Daemon 回调 API 地址及对应密钥，以及 API、Daemon 镜像标签和 Compose 网络。完整容器部署与开发用中间件配置不能混搭；容器里的 localhost 通常指向当前容器本身，而不是另一个服务。