插件运行时配置

面向部署管理员的 local-pool 运行参数、调度边界与环境变量参考

本文面向 FastGPT 自部署管理员。插件服务负责工具安装、进程管理和请求分发；FastGPT 主服务通过插件服务调用工具。安装入口见系统工具管理，开发联调环境见远程调试功能套件配置。

`.pkg` 插件包协议

系统工具通过 .pkg 文件安装与更新。管理员接收作者交付的安装包，并检查来源、版本与目标环境兼容性。

构建产物与输出位置由插件项目的构建和打包流程决定，详见插件包与 SDK 参考。

Manifest 由构建流程生成。作者维护的字段与 Schema 声明见元信息与 Schema；调整这些定义后需要重新构建并交付安装包。

FastGPT Plugin 默认使用本地进程池运行时 local-pool，按插件服务维护 Pod 进程组和请求队列。此处 Pod 指插件运行时管理的工作进程。

系统管理员可在管理员 →（商业版：系统资源 →）系统工具中打开目标工具的配置弹窗，切换到运行时配置标签页调整以下四个字段。当前值以配置页面读取到的插件服务配置为准；调整前应结合宿主机资源与工具的外部 API 限流进行测试。

参数	约束	说明
最小工作节点数 (`minPods`)	非负整数	服务保留的最小 Pod 数量
最大工作节点数 (`maxPods`)	正整数	服务可运行的 Pod 数量上限
Pod 超时时间 (`podTimeout`)	正整数，毫秒	单次工具请求在 Pod 内的执行超时时间（空闲 Pod 的回收等待时间由环境变量 `POOL_SERVICE_IDLE_TIMEOUT` 控制）
单 Pod 最大并发请求数 (`maxConcurrentRequestsPerPod`)	正整数	单个 Pod 同时处理的请求数量上限

minPods 必须小于或等于 maxPods。增加 Pod 数量和单节点并发会增加资源消耗，也可能更快触发外部服务的限流。

以下变量由插件服务进程读取。它们用于全局容量与服务默认配置，实际支持范围和默认值以所部署的 FastGPT Plugin 版本为准。

环境变量	说明
`POOL_HEALTH_CHECK_INTERVAL`	Pod 健康检查间隔，单位毫秒
`POOL_MAX_TOTAL_PODS`	当前 Server 进程中所有插件 Pod 的总数上限
`POOL_SERVICE_MIN_PODS`	单插件服务的默认最小工作节点数
`POOL_SERVICE_MAX_PODS`	单插件服务的默认最大工作节点数
`POOL_SERVICE_IDLE_TIMEOUT`	空闲 Pod 回收等待时间，单位毫秒（决定空闲工作进程何时销毁）
`POOL_SERVICE_POD_TIMEOUT`	默认单次请求 Pod 执行超时时间，单位毫秒
`POOL_SERVICE_MAX_CONCURRENT_REQUESTS_PER_POD`	单个 Pod 的默认最大并发请求数
`POOL_SERVICE_MAX_REQUESTS_PER_POD`	单个 Pod 累计处理的请求数上限
`POOL_SERVICE_MAX_QUEUE_SIZE`	单插件服务的请求队列容量上限
`POOL_SERVICE_QUEUE_TIMEOUT`	请求等待可用 Pod 的超时时间，单位毫秒
`POOL_SERVICE_STARTUP_RETRY_BASE_DELAY`	Pod 启动重试的基础退避延迟，单位毫秒
`POOL_SERVICE_STARTUP_RETRY_MAX_DELAY`	Pod 启动重试的最大退避延迟，单位毫秒
`POOL_SERVICE_POD_MAX_OLD_SPACE_SIZE_MB`	单个 Pod 工作进程的 V8 老生代内存上限（MB）
`POOL_SERVICE_POD_ALLOW_NET`	是否允许 Pod 工作进程发起网络访问（默认 `false`，需调用外部 API 时应开启）
`POOL_SERVICE_POD_TERMINATION_GRACE_PERIOD`	Pod 终止前的优雅退出等待时间，单位毫秒

插件服务管理工作进程故障、启动重试与退避。排查时先检查服务日志，区分工具执行错误、进程启动失败、队列等待超时和宿主机容量不足。连续启动失败时，应先修复依赖、插件代码或运行环境，再验证恢复情况；具体重试与熔断策略以部署版本为准。