👁 80 次阅读

Rocky 8.4 部署 FastGPT v4.14.19 遇到 fastgpt-app plugin_error 如何排查

来源：https://github.com/labring/FastGPT/issues/6922

现象描述

用户在 Rocky 8.4 环境下使用 Docker Compose 部署 FastGPT v4.14.19，fastgpt-app 容器在系统初始化阶段报错退出。核心错误信息为 [plugin_error]: fetch failed，发生在 instrumentation-check 步骤。日志显示向量数据库初始化已完成（Postgres vector initialization completed），但随后插件服务连接失败，导致整个系统初始化中断。完整错误链如下：

fastgpt-app | [plugin_error]: fetch failed
fastgpt-app | System initialization step failed {
fastgpt-app |   step: 'instrumentation-check',
fastgpt-app |   stage: undefined,
fastgpt-app |   errorMessage: '[plugin_error]: fetch failed',
fastgpt-app |   errorName: undefined,
fastgpt-app |   errorCode: undefined,
fastgpt-app |   errorStage: undefined,
fastgpt-app |   errorStep: undefined,
fastgpt-app |   errorStack: undefined,
fastgpt-app |   errorCause: undefined,
fastgpt-app |   errorDetails: '[plugin_error]: fetch failed'
fastgpt-app | }

与此同时，数据库层面报出慢查询警告（level: 'slow-1'，durationMs: 320），执行的是 CREATE EXTENSION IF NOT EXISTS vector 和 modeldata 表创建语句，该慢查询本身不是致命错误，但在问题发生时被记录在日志中。

背景原因

该用户此前在 Rocky 8.4 上部署 FastGPT v4.14.18 时也遇到类似问题，提交过 issue #6893。社区建议的方案是：改用 4.15.0-beta1 的 fastgpt-code-sandbox 镜像，并移除 bun 模式。按照此方案调整后，用户遇到新的错误——fastgpt-plugin 服务无法从 fastgpt-app 容器内部访问。关键配置信息如下：

CODE_SANDBOX_URL：http://fastgpt-code-sandbox:3000
PLUGIN_BASE_URL：http://fastgpt-plugin:3000
fastgpt-code-sandbox 镜像已更新为 registry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-code-sandbox:v4.15.0-beta1

用户明确指出，镜像变更仅涉及 fastgpt-code-sandbox 一个服务，fastgpt-plugin 镜像未做对应升级。这可能存在版本不匹配问题——fastgpt-app 运行在 v4.14.19，fastgpt-code-sandbox 运行在 v4.15.0-beta1，而 fastgpt-plugin 的版本是否与两者兼容，issue 中尚未给出明确结论。

排查或量化方法

排查思路应聚焦于 fastgpt-app 容器与 fastgpt-plugin 服务之间的网络连通性。issue 讨论中使用的排查命令包括以下几项： 查看 Compose 配置中的关键 URL

docker compose config | grep -E "(SANDBOX|PLUGIN)_(BASE_)?URL"

预期输出应显示 CODE_SANDBOX_URL 和 PLUGIN_BASE_URL 的完整值。 从 fastgpt-app 容器内部测试插件服务连通性

docker compose exec fastgpt-app sh -c 'wget -qO- -T 3 "$PLUGIN_BASE_URL"'

使用独立容器测试（避免 exec 环境差异）

docker compose run --rm --entrypoint sh fastgpt-app -c \
  'wget -qO- -T 3 http://fastgpt-plugin:3000/ ; echo ---; wget -qO- -T 3 http://fastgpt-code-sandbox:3000/

查看服务状态

docker compose ps fastgpt-plugin fastgpt-code-sandbox

筛选日志中的关键错误模式

docker compose logs fastgpt-app 2>&1 | grep -iE 'register|plugin.*http|http.*plugin|fetch' | head -30

查看最近日志

docker compose logs --tail=200 fastgpt-app

完整解决方案

该 issue 当前状态为 open，官方尚未合入修复方案。以下是基于 issue 讨论记录中可验证的排查步骤和社区观察到的信息：

第一步：确认各服务镜像版本一致性

检查 docker-compose.yml 或 Compose 配置中各服务的镜像版本。重点确认 fastgpt-app、fastgpt-plugin、fastgpt-code-sandbox 三者版本号是否匹配。已知用户环境的情况：

服务	镜像版本	说明
fastgpt-app	v4.14.19	原始部署版本
fastgpt-code-sandbox	v4.15.0-beta1	按社区建议升级
fastgpt-plugin	未明确说明	用户称仅更换了 code-sandbox

第二步：验证容器间网络连通性

执行上述排查命令，逐一确认 fastgpt-app 容器能否通过 HTTP 访问 fastgpt-plugin:3000 和 fastgpt-code-sandbox:3000。若 wget 返回超时或连接拒绝，则问题定位为 Docker 网络层或插件服务本身未正常启动。

第三步：检查 fastgpt-plugin 服务日志

虽然 issue 中未完整展示 fastgpt-plugin 的独立日志，但从 [plugin_error]: fetch failed 错误可以推断，插件服务要么未启动成功，要么监听地址与 PLUGIN_BASE_URL 配置不一致。建议执行：

docker compose logs --tail=100 fastgpt-plugin

第四步：确认插件服务端口映射

检查 docker compose ps 输出中 fastgpt-plugin 服务的 PORTS 字段，确认其是否在容器内部监听 3000 端口。若该服务启动失败，fastgpt-app 的 fetch 调用必然失败。

常见错误排查

1. 只升级了 code-sandbox 未同步升级 plugin：用户按社区建议将 fastgpt-code-sandbox 升级到 v4.15.0-beta1，但未确认 fastgpt-plugin 是否需要对应升级。不同版本间的 API 协议可能存在差异，导致 fetch failed。 2. 数据库慢查询误判为根因：日志中出现的 Postgres slow query detected（durationMs: 320）仅为性能警告，后续日志明确显示 Postgres vector initialization completed，说明数据库初始化已成功，慢查询不是导致系统初始化失败的原因。 3. exec 与 run 测试方式差异：docker compose exec 进入的是已运行的容器环境，而 docker compose run --rm 会创建新容器。两者在网络命名空间上可能表现不同，当 exec 测试失败时应额外使用 run 方式验证。 4. Rocky 8.4 兼容性未确认：issue 关联的前序 issue #6893 提到 Rocky 8.4 上的部署问题，社区建议移除 bun 模式后仍复现 [plugin_error]: fetch failed。用户已提出「后期的版本能直接兼容8.4吗」，截至 2026-05-19 的最后一次更新，issue 中未出现对此问题的明确答复。 5. 错误信息过于笼统：[plugin_error]: fetch failed 未提供 HTTP 状态码、目标 URL 的具体响应内容或超时信息，排查时只能通过逐层网络连通性测试来缩小范围。

实践建议

在 Rocky 8.4 等非主流操作系统上部署 FastGPT 时，若必须使用该环境，可参考以下实践：

保持 fastgpt-app、fastgpt-plugin、fastgpt-code-sandbox 三个服务的镜像版本一致，避免混用不同版本。
部署完成后立即执行容器间连通性测试，确认 PLUGIN_BASE_URL 和 CODE_SANDBOX_URL 所指向的服务均可访问。
遇到初始化失败时，先检查各子服务的独立日志（docker compose logs --tail=100 fastgpt-plugin），再排查网络层问题。
关注 issue #6893 与 #6922 的后续进展，社区可能在未来版本中提供对 Rocky 8.4 的正式支持。

FAQ

Q：为什么 PostgreSQL 报了慢查询错误？ A：根据日志，durationMs: 320 的慢查询执行的是 CREATE EXTENSION IF NOT EXISTS vector 和 CREATE TABLE IF NOT EXISTS modeldata 语句，这是向量数据库的初始化操作，在首次启动或数据量大时可能触发慢查询阈值。该警告为 level: 'slow-1' 级别，不影响初始化流程的完成，后续日志显示 Postgres vector initialization completed 即说明数据库部分已正常完成。 Q：[plugin_error]: fetch failed 是网络问题还是服务问题？ A：根据 issue 讨论中的排查命令设计，该错误既可能是网络层面的（容器间无法通信），也可能是服务层面的（fastgpt-plugin 未正常启动或监听地址错误）。需要通过 docker compose run --rm 执行 wget 测试来区分具体原因。issue 中尚未展示完整的连通性测试结果，因此无法确定最终归属。 Q：社区建议的 4.15.0-beta1 code-sandbox 方案是否完整解决了问题？ A：该方案未完整解决问题。用户按建议升级了 fastgpt-code-sandbox 到 v4.15.0-beta1 并移除 bun 模式后，仍遇到 [plugin_error]: fetch failed 错误。用户明确指出镜像变更仅涉及 fastgpt-code-sandbox 一个服务。issue 当前状态为 open，尚未有最终解决方案。 Q：后续版本能否直接兼容 Rocky 8.4？ A：用户在 issue 中提出了该问题（「后期的版本能直接兼容8.4吗？」），但截至 2026-05-19 的最后一次更新，issue 中未出现对此问题的明确答复。Rocky 8.4 兼容性尚未得到官方确认。 Q：该 issue 是否已有修复方案？ A：该 issue 当前状态为 open，标签为 bug，官方尚未合入修复方案。讨论中仅包含用户提供的排查命令和日志输出，未包含维护者给出的具体修复步骤。社区侧的变通方案（使用 4.15.0-beta1 code-sandbox + 移除 bun 模式）未能完全解决该问题，仍存在 fetch failed 错误。