1. 功能简介
在企业级 Web 应用中，插件承载了扩展 LLM、工具、Agent 策略、数据源、触发器等核心能力。插件管理主要解决了以下痛点：- 版本碎片化：同一插件在不同工作空间版本不一致，导致排障困难。
- 运维黑盒：缺乏对插件运行实例（Pod 资源、环境变量、负载等）的集中监控手段。
- 治理缺失：缺乏全局策略控制，难以限制不可信来源的插件安装。
1.1 功能价值
- 集中化生命周期管理：系统管理员可在后台完成插件的一键安装、版本切换、以及跨工作空间的批量分发与卸载。
- 即装即用体验：为工作空间预装插件，减少业务团队的重复配置工作。
- 可视化运维监控：提供针对 K8s 环境的插件实例级资源监控（CPU、内存、网络），支持动态扩缩容。
- 安全风险控制：通过策略引擎严格控制插件的安装来源和发布者身份。
1.2 适用场景
- 统一基建：IT 部门希望为所有业务团队统一配备标准的工具集（如 Google Search、内部 API 工具）。
- 资源调优：针对高频使用的插件（如 LLM 插件），管理员需要监控其资源负载并调整 Pod 数量以应对流量高峰。
- 安全合规：企业要求仅允许安装来自“官方”或“合作伙伴”的插件，禁止随意上传本地文件。
1.3 核心概念
插件类型- 模型 (LLM) 插件：如 OpenAI、Claude、Gemini。
- 工具 (Tool) 插件：如 Google Search、GitHub、网页抓取工具。
- Agent 策略插件 (Agent Strategy)：如 Function call、ReAct 等思考执行策略。
- 扩展 (Extension) 插件：如敏感内容审查、外部数据库连接。
- 数据源 (Datasource) 插件：如 Notion、Google Drive 等数据接入源。
- 触发器 (Trigger) 插件：如 Gmail Trigger、Outlook Trigger。
- 实例 (Instance)：插件在系统中的运行实体。每个实例相互隔离，可重启、重构、回滚。
- Pod：最小运行单元（K8s 环境），承载插件容器(Container)，具备可观测的 CPU/内存/网络指标。
2. 操作说明
2.0 快速开始
插件管理的典型管理流程包括：安装插件（市场/本地） > 分配(安装)至工作空间 > 监控与运维 > 卸载/回收。- 安装新插件 在“插件管理”页点击【安装插件】，选择从 市场 下载或本地上传安装包，完成插件入库。
- 分配给工作空间 在插件列表中点击【安装管理】，点击 添加安装目标 勾选目标工作空间，系统将自动为这些空间部署插件，实现“即装即用”。
- 监控运行状态 (仅 K8s) 点击插件右侧的【···】>【查看实例】，查看负载监控图表。如有性能瓶颈，可在【资源配置】中增加 CPU/内存限制或增加 Pod 数量。
2.1 安装插件
系统支持两种安装方式，具体取决于您的部署环境和安全策略。 方式一：Marketplace 安装 (推荐)- 点击【安装插件】>【Marketplace】。
- 在弹出的窗口或新标签页中浏览插件市场。
- 选择插件及所需版本。
- 点击【安装】，系统将自动拉取并在后台部署基础实例。
- 点击【安装插件】>【本地插件】。
- 上传插件文件包。
- 系统会校验签名与策略。若上传的插件不符合要求，系统将根据设置弹出警告(策略仅对工作空间做有效限制, 管理后台仅做提示不做限制安装)。
2.2 安装管理（分配与版本控制）
管理员可以控制插件在各个工作空间的分布和版本。- 在插件列表中找到目标插件，点击【安装管理】。
- 为更多工作空间安装该版本插件: 点击 添加安装目标 在弹出的列表中勾选工作空间。
- 从工作空间中卸载该版本插件: 直接在列表内选择目标工作空间点击卸载图标 或 点击 添加安装目标 在弹出的列表中取消勾选工作空间。
-
版本变更提示：系统会通过颜色标识版本变化：
- 灰色 (已安装)：已安装该插件。
- 绿色 (新增)：首次安装该插件。
- 蓝色 (升级)：从低版本升级到当前版本（如 1.0.0 -> 1.2.0）。
- 橙色 (降级)：从高版本降级到当前版本（如 1.3.0 -> 1.2.0）。
- 浅蓝色 (覆盖)：相同版本覆盖（会显示插件版本checksum, 如 1.2.0 SHA-256: 3db71aca）。
- 窗口下方将展示本次操作即将执行概览(新增、升级、降级、覆盖安装、卸载), 点击确认后，变更将立即生效。
2.3 插件运行监控与配置 (仅 K8s 环境)
在 K8s 部署环境下，管理员拥有强大的运维能力。Docker Compose 环境暂不支持此部分功能。 点击插件列表中的【…】>【查看实例】进入详情页。 1. 负载监控 可视化展示近 1 小时、1 天或 1 周的Pod容器运行数据：- CPU 使用情况
- 内存使用情况
- 网络上传/下载速率
- 注意：可通过快捷操作查看不同pod下相同类型的容器, 图表中会显示资源限制线（Limit）。
- CPU 核数：支持设置小于 1 核。
- 内存容量：设置最大内存限制。
- 修改后需点击【保存并应用】，系统将重启实例以生效。
- 注意: 操作前请保证集群资源充足, 否则可能会导致本次资源配置更改无法生效
- 扩缩容：在实例列表中，悬停在“Pod 数”上，可手动增加或减少 Pod 数量以应对流量变化。
- 重启实例：重启所有 Pod，服务性能可能短暂下降。
- 重构实例：基于底层依赖包拉取最新依赖，构建全新的实例环境。
- 回滚实例：将当前运行回滚到历史某个实例版本（注意：当前实例将会丢失）。
- 注意: 扩容前请保证集群资源充足, 否则可能会导致本次pod新增操作无法生效
- 注意: 操作前请保证集群资源充足, 否则可能会导致本次环境变量更改无法生效
2.4 卸载插件
卸载操作分为“从工作空间卸载”和“全局卸载”。 安全卸载检查： 为了防止误操作导致业务中断，系统在卸载时会进行依赖检测。- 工具/Agent 策略/触发器类：系统会列出正在使用该插件的“应用”和“知识流水线”清单。
- 模型/数据源/扩展类：系统会列出正在使用该插件的“工作空间”清单。 管理员可点击【导出清单】备份受影响列表，确认无误后再执行卸载。
2.5 插件安装策略设置
管理员可通过策略控制企业的插件安全红线。 访问路径：插件管理页顶部 > 【插件安装策略】- 允许的安装来源：可选择“全部”、“官方与合作伙伴”或仅限“官方”以及 选择“无”不允许安装任何来源的插件。
- 限制只能从市场安装：开启后，将禁止通过本地上传方式安装插件，防止恶意代码注入。
- 更多细节 请参考插件安装策略
3. 故障排查
- 安装失败：点击列表上方的【安装日志】图标，查看详细的报错日志。常见原因包括网络超时、校验和（Checksum）不匹配或依赖冲突。
- 实例状态一直为 Building：这是重构或新建实例时的中间状态，若长时间不随变为 Running，请检查 K8s 集群资源是否充足。
- 监控数据不显示：请确认您当前的部署环境是否为 K8s。Docker Compose 模式下不支持查看 Pod 指标。
- 无法回滚：若当前正在运行的即为该实例，则回滚按钮置灰不可用。
- 新增Pod无法启动: 可能由于集群资源不足, 请检查 K8s 集群资源是否充足, 自行扩容或删除其他插件
- 环境变量更新失败: 可能由于集群资源不足, 请检查 K8s 集群资源是否充足, 自行扩容或删除其他插件
- 资源配置更新失败: 可能由于集群资源不足, 请检查 K8s 集群资源是否充足, 自行扩容或删除其他插件
4. 常见问题 (FAQ)
Docker Compose 环境和 K8s 环境在功能上有什么区别？
K8s 环境支持完整的功能，包括实例资源监控（CPU/内存）、Pod 扩缩容、滚动更新和高级运维操作。Docker Compose 环境下，【查看实例】、【资源配置】及 Pod 相关的监控功能不可用，仅支持基础的安装、卸载和版本管理。卸载插件后，应用会发生什么？
若管理员强制卸载了某个应用正在依赖的插件，该应用在运行时会报错提示“The plugin is not installed and cannot be used!”，导致业务中断。建议在卸载前务必通过弹窗确认影响范围后再作决定。什么是“实例全局环境变量”？
这是配置在管理后台顶部的变量设置。所有新启动的插件实例默认会继承这些全局变量。您也可以在单个插件的【查看实例】>【环境变量】中覆盖这些设置。为什么我看不到某些插件的更新？
请检查【插件安装策略】。如果策略限制了仅允许“官方”插件，非官方渠道发布的更新可能无法显示或安装。同时，请确认您的 Marketplace 连接正常。5. 最佳实践
- 生产环境严格限源：建议在生产环境中将插件策略设置为“仅限官方”并开启“限制只能从市场安装”，以最大程度降低安全风险。
- 资源预留与监控：对于关键的 LLM 模型插件，建议在上线前进行压力测试，并根据监控图表合理配置 Min/Max Pod 数 及 资源limit，避免流量高峰时响应缓慢。
- 平滑升级：需要升级插件版本时，建议先在一个测试工作空间进行“灰度发布”（单独为该空间安装新版本），验证业务兼容性后，再通过【安装管理】批量推广到全公司。
- 定期清理失败记录：在安装日志中定期清理失败的历史记录，保持运维视图的整洁。