如何自部署 FastGPT 系统插件的远程调试功能套件【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT如果你已经在 FastGPT 中本地化了主服务和fastgpt-plugin现在需要把开发者本地运行的系统插件临时接入 FastGPT 测试环境做开发、联调和验收那么需要额外部署一套“系统插件的远程调试功能套件”。默认的 Docker Compose 部署脚本只包含 FastGPT 主服务和常规fastgpt-plugin运行环境不包含 Connection Gateway 的公网 WebSocket 接入配置自部署环境必须按本文补齐。先确认两条硬边界系统插件的远程调试功能套件仅商业版支持它只适合调试、联调和验收不适合作为生产插件运行时。文档明确建议优先在 FastGPT 云服务版本中使用远程调试能力自部署需要额外维护 Plugin Server、Connection Gateway、Redis、反向代理、TLS 和密钥轮换。完整配置以 remote-debug-suite.mdx 为准本文按部署顺序组织步骤。远程调试链路包含哪些组件组件作用FastGPT 主服务提供开启、刷新、关闭调试通道的页面和 API。Plugin Server管理connectionKey、调试 source并把调试调用转发给 Gateway。Connection Gateway维护 CLI WebSocket 长连接、session、mailbox 和调试调用流转。Redis保存 Gateway session、source owner 和 mailbox 数据。fastgpt-plugin dev在开发者本地运行插件并通过 WebSocket 连接 Gateway。主路径是FastGPT 页面开启调试通道后Plugin Server 创建 debug channel 并返回connectionKey / connectionUrl / source开发者在本地运行fastgpt-plugin dev --connect connectionUrlCLI 兑换connectionKey后通过 WebSocket 绑定到 Gateway此后 FastGPT 调用调试 source 下的插件时请求经 Plugin Server、Gateway 转发到本地 CLI执行结果再流式返回。部署前提开始部署前先满足以下条件任一条不满足都会导致后续验证失败FastGPT 主服务已能正常访问fastgpt-plugin并且两侧的PLUGIN_TOKEN/AUTH_TOKEN一致。fastgpt-plugin版本需要包含远程调试能力建议与当前 FastGPT 版本要求的 plugin 版本保持一致。Gateway WebSocket 地址需要从开发者本地可访问生产建议使用 HTTPS 反向代理暴露为wss://。Gateway internal HTTP API 只允许 Plugin Server 所在内网访问。Gateway 使用的 Redis 必须支持 Stream。所有生产密钥至少 32 位且不要使用示例值、默认值或弱口令。部署 Connection GatewayConnection Gateway 由fastgpt-plugin仓库维护。按网络环境选择国内版或海外版镜像# 国内版 CONNECTION_GATEWAY_IMAGEregistry.cn-hangzhou.aliyuncs.com/fastgpt/fastgpt-plugin-connection-gateway:8a52896d1d5b866308778871526cfdff9d22c547 # 海外版 CONNECTION_GATEWAY_IMAGEghcr.io/labring/fastgpt-plugin-connection-gateway:8a52896d1d5b866308778871526cfdff9d22c547最小配置形态如下。其中的${...}变量需要在 docker compose 读取的.env或宿主环境中定义CONNECTION_GATEWAY_IMAGE二选一取用其余 token 替换为自生成的至少 32 位随机值services: connection-gateway: image: ${CONNECTION_GATEWAY_IMAGE} restart: unless-stopped environment: NODE_ENV: production REDIS_URL: redis://default:mypasswordfastgpt-redis:6379 AUTH_TOKEN: ${CONNECTION_GATEWAY_AUTH_TOKEN} CONNECTION_GATEWAY_AUTH_TOKEN: ${CONNECTION_GATEWAY_AUTH_TOKEN} JWT_SECRET: ${CONNECTION_GATEWAY_JWT_SECRET} CONNECTION_GATEWAY_PORT: 3000 CONNECTION_GATEWAY_WS_PORT: 3001 CONNECTION_GATEWAY_WS_PATH: /connection-gateway/v1 ports: - 3010:3000 - 3011:3001示例中的REDIS_URL指向名为fastgpt-redis的 Redis 实例账号密码按你实际部署的 Redis 修改该 Redis 版本必须支持 Stream。端口与暴露要求端口用途暴露要求3010Gateway HTTP API对应容器内3000包含/health、/internal/*、/metrics。不需要公网暴露Plugin Server 可通过内网访问即可。3011Gateway WebSocket对应容器内3001默认路径/connection-gateway/v1。需要让开发者本地 CLI 可访问通常通过反向代理暴露为公网wss://地址。RedisGateway session、source owner 和 mailbox 存储。不需要公网暴露Redis 版本必须支持 Stream。配置 Plugin Server在fastgpt-plugin服务中增加 Gateway 相关环境变量# Plugin Server 调用 Gateway internal HTTP API 的内网地址 CONNECTION_GATEWAY_BASE_URLhttp://connection-gateway:3000 # 返回给本地 CLI 的 WebSocket 地址必须能从开发者本地访问 CONNECTION_GATEWAY_PUBLIC_URLwss://debug-gateway.example.com/connection-gateway/v1 # Plugin Server 调用 Gateway /internal/* 和 /metrics 的 bearer token CONNECTION_GATEWAY_AUTH_TOKENreplace-with-a-random-token-at-least-32-chars # Gateway connect token 的 HMAC secret必须与 Connection Gateway 完全一致 JWT_SECRETreplace-with-a-random-jwt-secret-at-least-32-chars注意两点CONNECTION_GATEWAY_BASE_URL是 Plugin Server 访问 Gateway 的内网地址CONNECTION_GATEWAY_PUBLIC_URL是返回给开发者本地 CLI 的地址两者不能混用。CONNECTION_GATEWAY_PUBLIC_URL中的域名需替换为你反向代理实际暴露的wss://地址路径保持/connection-gateway/v1。配置完成后重启fastgpt-plugin。CONNECTION_GATEWAY_BASE_URL未配置时Plugin Server 会关闭远程调试能力。配置 FastGPT 主服务FastGPT 主服务继续使用常规插件配置PLUGIN_BASE_URLhttp://fastgpt-plugin:3000 PLUGIN_TOKENreplace-with-the-same-value-as-plugin-auth-token NEXT_PUBLIC_BASE_URLhttps://fastgpt.example.comPLUGIN_TOKEN需与fastgpt-plugin的AUTH_TOKEN取同一值NEXT_PUBLIC_BASE_URL会影响调试连接链接的生成公网用户访问 FastGPT 时应配置为浏览器可访问的 FastGPT 地址示例中的https://fastgpt.example.com替换为你的实际域名。配置反向代理建议只暴露 Gateway WebSocket 入口对 Gateway internal HTTP API 保持内网访问。Nginx 示例location /connection-gateway/v1 { proxy_pass http://connection-gateway:3001; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_read_timeout 3600s; }/internal/*、/metrics和 Gateway HTTP 端口不要直接暴露到公网。开发者本地连接插件在 FastGPT 插件调试入口开启调试通道复制页面返回的连接链接。在本地插件目录运行fastgpt-plugin dev --connect connectionUrlconnectionUrl替换为第 1 步复制到的连接链接。连接成功后本地 CLI 会通过 Gateway 上报插件 metadataFastGPT 工具列表中会出现当前调试 source 下的本地插件。调试 source 的格式为debug:tmbId:{tmbId}其中{tmbId}按文档格式为占位实际值以开启调试通道后页面展示的 source 为准。验证调试链路按以下顺序确认链路打通访问 Gateway 健康检查在内网可解析connection-gateway主机的环境执行curl http://connection-gateway:3000/health在 FastGPT 页面开启调试通道确认状态从enabled变为connected。运行本地fastgpt-plugin dev确认 CLI 显示 WebSocket 已连接。在 FastGPT 中选择调试 source 下的工具并触发一次调用确认结果由本地插件返回。四步全部通过后远程调试套件即完成部署并可投入使用。常见问题排查页面可以开启调试但 CLI 连接失败检查CONNECTION_GATEWAY_PUBLIC_URL是否为开发者本地可访问地址。浏览器和 CLI 在开发者电脑上运行不能使用 Docker 内网域名。CLI 已连接但 FastGPT 显示 disconnected检查 Plugin Server 是否能访问CONNECTION_GATEWAY_BASE_URL并确认CONNECTION_GATEWAY_AUTH_TOKEN与 Gateway 配置一致。连接后调用工具超时检查 Gateway Redis 是否正常、反向代理是否保留 WebSocket upgrade、proxy_read_timeout是否过短以及本地 CLI 是否仍在线。connect token 校验失败检查 Plugin Server 和 Connection Gateway 的JWT_SECRET是否完全一致。安全与边界限制CONNECTION_GATEWAY_AUTH_TOKEN、JWT_SECRET、connectionKey和connectToken都属于敏感信息禁止写入日志、截图或公开文档。CONNECTION_GATEWAY_AUTH_TOKEN只给 Plugin Server 使用本地 CLI 不需要也不应获取。connectionKey是长期调试连接密钥只在开启或刷新调试通道时明文返回泄露后应立即刷新或关闭调试通道。调试 source 命中后按远程调试路径处理断连或 session 不存在时会失败不会回退到生产插件运行时。多副本 Gateway 部署需要保证 session 删除请求能路由到持有 WebSocket 的节点或接受 Redis session 删除后后续调用失败。如需核对主服务与环境变量的完整清单可参考 env.mdx部署 FastGPT 与插件基础环境时参考 docker.mdx。【免费下载链接】FastGPTFastGPT is a knowledge-based platform built on the LLMs, offers a comprehensive suite of out-of-the-box capabilities such as data processing, RAG retrieval, and visual AI workflow orchestration, letting you easily develop and deploy complex question-answering systems without the need for extensive setup or configuration.项目地址: https://gitcode.com/GitHub_Trending/fa/FastGPT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考