> ## Documentation Index
> Fetch the complete documentation index at: https://enterprise-docs.dify.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 插件管理

插件管理是企业级 AI 能力扩展的核心控制台，旨在构建“企业级插件生命周期管理中心”。通过统一管理，企业可以解决插件版本碎片化、运维“黑盒”化以及安全治理成本高等问题，实现插件的集中安装、统一运维监控以及全局安全策略控制。

## 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 快速开始

插件管理的典型管理流程包括：**安装插件（市场/本地） > 分配(安装)至工作空间 > 监控与运维 > 卸载/回收**。

1. **安装新插件**
   在“插件管理”页点击【安装插件】，选择从 市场 下载或本地上传安装包，完成插件入库。
2. **分配给工作空间**
   在插件列表中点击【安装管理】，点击 添加安装目标 勾选目标工作空间，系统将自动为这些空间部署插件，实现“即装即用”。
3. **监控运行状态 (仅 K8s)**
   点击插件右侧的【···】>【查看实例】，查看负载监控图表。如有性能瓶颈，可在【资源配置】中增加 CPU/内存限制或增加 Pod 数量。

### 2.1 安装插件

系统支持两种安装方式，具体取决于您的部署环境和安全策略。

**方式一：Marketplace 安装 (推荐)**

1. 点击【安装插件】>【Marketplace】。
2. 在弹出的窗口或新标签页中浏览插件市场。
3. 选择插件及所需版本。
4. 点击【安装】，系统将自动拉取并在后台部署基础实例。

**方式二：本地插件安装**

1. 点击【安装插件】>【本地插件】。
2. 上传插件文件包。
3. 系统会校验签名与策略。若上传的插件不符合要求，系统将根据设置弹出警告(策略仅对工作空间做有效限制, 管理后台仅做提示不做限制安装)。

### 2.2 安装管理（分配与版本控制）

管理员可以控制插件在各个工作空间的分布和版本。

1. 在插件列表中找到目标插件，点击【安装管理】。

2. 为更多工作空间安装该版本插件: 点击 添加安装目标 在弹出的列表中勾选工作空间。

3. 从工作空间中卸载该版本插件: 直接在列表内选择目标工作空间点击卸载图标 或 点击 添加安装目标 在弹出的列表中取消勾选工作空间。

4. **版本变更提示**：系统会通过颜色标识版本变化：
   * **灰色 (已安装)**：已安装该插件。
   * **绿色 (新增)**：首次安装该插件。
   * **蓝色 (升级)**：从低版本升级到当前版本（如 1.0.0 -> 1.2.0）。
   * **橙色 (降级)**：从高版本降级到当前版本（如 1.3.0 -> 1.2.0）。
   * **浅蓝色 (覆盖)**：相同版本覆盖（会显示插件版本checksum, 如 1.2.0 SHA-256: 3db71aca）。

5. 窗口下方将展示本次操作即将执行概览(新增、升级、降级、覆盖安装、卸载), 点击确认后，变更将立即生效。

### 2.3 插件运行监控与配置 (仅 K8s 环境)

在 K8s 部署环境下，管理员拥有强大的运维能力。Docker Compose 环境暂不支持此部分功能。
点击插件列表中的【...】>【查看实例】进入详情页。

**1. 负载监控**
可视化展示近 1 小时、1 天或 1 周的Pod容器运行数据：

* CPU 使用情况
* 内存使用情况
* 网络上传/下载速率
* 注意：可通过快捷操作查看不同pod下相同类型的容器, 图表中会显示资源限制线（Limit）。

**2. 资源配置**
可调整每个 容器 的最大资源上限：

* **CPU 核数**：支持设置小于 1 核。
* **内存容量**：设置最大内存限制。
* 修改后需点击【保存并应用】，系统将重启实例以生效。
* 注意: 操作前请保证集群资源充足, 否则可能会导致本次资源配置更改无法生效

**3. 实例管理与扩缩容**

* **扩缩容**：在实例列表中，悬停在“Pod 数”上，可手动增加或减少 Pod 数量以应对流量变化。
* **重启实例**：重启所有 Pod，服务性能可能短暂下降。
* **重构实例**：基于底层依赖包拉取最新依赖，构建全新的实例环境。
* **回滚实例**：将当前运行回滚到历史某个实例版本（注意：当前实例将会丢失）。
* 注意: 扩容前请保证集群资源充足, 否则可能会导致本次pod新增操作无法生效

**4. 环境变量**
支持配置实例级环境变量，默认继承全局设置，也可覆盖修改。

* 注意: 操作前请保证集群资源充足, 否则可能会导致本次环境变量更改无法生效

### 2.4 卸载插件

卸载操作分为“从工作空间卸载”和“全局卸载”。
**安全卸载检查**：
为了防止误操作导致业务中断，系统在卸载时会进行依赖检测。

* **工具/Agent 策略/触发器类**：系统会列出正在使用该插件的“应用”和“知识流水线”清单。
* **模型/数据源/扩展类**：系统会列出正在使用该插件的“工作空间”清单。
  管理员可点击【导出清单】备份受影响列表，确认无误后再执行卸载。

### 2.5 插件安装策略设置

管理员可通过策略控制企业的插件安全红线。
访问路径：插件管理页顶部 > 【插件安装策略】

* **允许的安装来源**：可选择“全部”、“官方与合作伙伴”或仅限“官方”以及 选择“无”不允许安装任何来源的插件。
* **限制只能从市场安装**：开启后，将禁止通过本地上传方式安装插件，防止恶意代码注入。
* [更多细节 请参考插件安装策略](/versions/3-0-x/zh-cn/administrator-guide/plugins-management)

## 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，避免流量高峰时响应缓慢。
* **平滑升级**：需要升级插件版本时，建议先在一个测试工作空间进行“灰度发布”（单独为该空间安装新版本），验证业务兼容性后，再通过【安装管理】批量推广到全公司。
* **定期清理失败记录**：在安装日志中定期清理失败的历史记录，保持运维视图的整洁。