# 团队安装与管理插件

> 团队管理员从 Marketplace 或本地插件包安装、更新和卸载团队插件

Source: https://doc.fastgpt.cn/zh-CN/plugin/team-installation

> 团队插件功能需要 FastGPT 商业版授权，并由系统管理员在**管理员 → 系统配置 → 功能清单**中开启**允许团队上传插件**（开源社区版默认关闭且无此开关）。

团队插件由团队管理员或所有者安装和管理，仅对当前团队可见。团队成员可以在工作流、Agent 和工具选择器中使用已经安装的团队插件。

## 功能边界

团队插件和系统插件相互独立：

* 系统插件由系统管理员统一安装和配置，可以供多个团队使用。
* 团队插件由当前团队的管理员安装，只在当前团队内生效。
* 同一个插件可以同时以系统插件和团队插件的形式存在，工具列表会分别展示两条记录。带“系统”标识的是系统插件，另一条是当前团队安装的插件。
* 团队插件不会继承同 ID 系统插件的密钥、费用、状态、版本或其他配置，需要单独完成配置。
* 团队无法隐藏或修改系统插件的可见性。

团队插件支持更新和卸载，没有“即将下线”状态。

## 角色说明

* **系统管理员**：使用 `root` 账号登录的用户，界面左侧底部显示**管理员**入口，负责全系统配置与系统插件管理。
* **团队所有者**：当前团队的创建者，默认拥有团队内全部管理权限。
* **团队管理员**：在**账号 → 团队管理 → 权限**中勾选了**管理员**权限的团队成员。

## 使用前准备

开始安装前，请确认：

1. 当前账号是团队管理员或团队所有者。普通团队成员可以使用已经安装的插件，无法安装、更新或卸载插件。
2. 系统管理员已在**管理员 → 系统配置 → 功能清单**中开启**允许团队上传插件**功能。该开关统一控制所有团队插件安装方式；关闭后，Marketplace 安装、本地安装和安装确认接口都会被拒绝。
3. 使用 Marketplace 时，部署环境能够访问 FastGPT Marketplace。
4. 使用本地安装时，已准备符合 FastGPT 插件包规范的 `.pkg` 文件，或包含多个 `.pkg` 文件的 `.zip` 文件。

界面右上角的 **+ 安装工具** 按钮需要同时满足“当前账号为团队管理员或所有者”且“系统已开启**允许团队上传插件**”才会显示；若部署环境配置了关闭插件市场（`disableMarketplace`），下拉菜单只显示**从本地安装**。

准备自定义安装包时，作者可按[调试、打包与发布](/zh-CN/plugin/debugging-and-publishing#构建检查和打包)完成交付。系统管理员统一安装的流程见[系统工具管理](/zh-CN/guide/build/tools/system-plugins/upload_system_tool)。

## 从 Marketplace 安装

1. 进入**工作台 → 系统工具**页面。
2. 点击右上角的 **+ 安装工具**，选择**从插件市场安装**。
3. 在 Marketplace 中通过名称、来源或分类查找插件。可以启用**仅看未安装**筛选。
4. 打开插件详情，检查插件说明与版本信息。
5. 选择版本并点击“安装”。安装完成后，插件会出现在团队工具列表中。

![团队插件市场与工具安装入口](/imgs/optimized/current/team-plugin-marketplace.png.webp)

安装完成后，可以直接在工作流或 Agent 的工具选择器中添加该插件。工具需要密钥或其他运行参数时，首次使用前应先完成对应配置。

## 上传本地插件包

当**允许团队上传插件**功能已开启时，可以安装自行开发或通过其他渠道获得的插件包。

1. 进入**工作台 → 系统工具**页面。
2. 点击右上角的 **+ 安装工具**，选择**从本地安装**。
3. 在**导入/更新插件**弹窗中选择一个或多个 `.pkg` 文件，也可以选择包含多个 `.pkg` 文件的 `.zip` 文件。
4. 等待系统上传并解析插件包。
5. 在解析列表中检查插件的**名称、标签、简介、状态、操作**。解析失败的文件会单独显示错误，可以移除或修复后重试。
6. 点击**确认导入**。安装完成后，插件会出现在团队工具列表中。

上传和解析只用于预览待安装内容。完成确认后，插件才会正式安装到当前团队。

## 更新插件

Marketplace 中存在新版本时，插件卡片或详情会显示更新入口。

1. 进入团队 Marketplace，找到需要更新的插件。
2. 查看新版本说明和权限变化。
3. 选择目标版本并执行更新。
4. 更新完成后，重新测试引用该插件的工作流和 Agent。

使用本地插件包更新时，重新上传目标版本并确认安装。更新不会自动合并系统插件配置，团队插件仍使用自己的配置。

插件升级可能改变输入输出结构、密钥要求或行为。生产工作流升级前，建议先在测试应用中验证。

## 卸载插件

团队管理员可以从工具卡片操作菜单或插件详情中点击**卸载**，在\*\*确认卸载团队插件？\*\*弹窗中输入插件名称完成卸载。

卸载会执行以下操作：

1. 调用插件服务，移除当前团队来源下的插件安装。
2. 撤销当前团队后续运行该插件的权限。
3. 从新的工具选择入口中移除该团队插件。

已有工作流和 Agent 节点不会被自动改写。它们再次运行时会因为插件已卸载而失败。恢复使用需要重新从 Marketplace 安装，或重新上传插件包。

卸载团队插件不会影响同 ID 的系统插件，也不会影响其他团队安装的插件。

## 识别系统插件与团队插件

当系统和团队安装了同一个插件时：

* 工具列表会同时显示两条记录，团队插件排在系统插件前面。
* 系统插件标题旁会显示“系统”标识，将鼠标移到标识上可以查看说明。
* 工作流和 Agent 会按插件来源保存引用，两条记录可以分别选择和配置。
* 卸载团队插件只会移除团队安装版本，系统插件仍然可用。

建议在团队内部约定插件用途，避免在同一应用中混用配置或行为不同的同名插件。

## 安全建议

* 只安装来源可信的插件包，并在安装前检查插件说明与密钥要求。
* 自定义插件接入外部 URL、账号或密钥时，应遵循团队的数据安全规范。
* 升级前检查版本说明，在测试应用中验证输入输出兼容性。
* 卸载插件前检查其在工作流和 Agent 中的引用，避免影响线上任务。
* 团队插件安装、权限与密钥隔离的常见排查请见[应用、对话与插件常见问题](/zh-CN/guide/build/faq#团队插件安装与管理)。
