安装与管理

准备工作

使用 **Root（超级管理员）**登录你的 New API 实例，打开「任务插件」（/task-plugins）。确认部署版本包含任务插件功能，并开启页面顶部的任务插件总开关。

普通 API 密钥用于模型调用，不能用于安装插件。若页面不可见或返回 403，请先检查账号角色和部署版本。

通过实例内的插件市场安装

1. 打开「任务插件」中的「插件市场」（Marketplace）。
2. 选择市场源，搜索目标插件，查看支持模型和接口。
3. 选择要安装的版本，阅读更新日志及迁移说明；升级时检查与当前安装版本的源码差异。
4. 等待插件源码下载与 SHA-256 校验完成，确认后选择「安装并启用」。
5. 返回已安装列表，检查实际生效版本；随后配置渠道和计费。

市场安装使用索引声明的哈希校验源码，并由服务端再次编译、校验元数据和检查冲突。发生渠道类型或路由冲突时，安装会被拒绝；先解决冲突再重试。

从文档站复制官网安装地址

1. 打开文档站插件市场。
2. 在插件卡片或详情中点击「复制安装地址」。
3. 返回自己的 New API 实例，选择「上传插件」，在「从 URL 导入」（Import from URL）中粘贴地址并读取源码。
4. 检查插件信息与源码后保存，确认插件已启用。

复制的是官网托管的 plugin.js 地址。docs.newapi.pro 使用 www.newapi.pro，docs.newapi.ai 使用 www.newapi.ai；语言不影响域名选择。

安装地址的形式为：

https://www.newapi.pro/api/v1/plugins/<plugin-key>/plugin.js
https://www.newapi.ai/api/v1/plugins/<plugin-key>/plugin.js

这类未固定版本的地址在导入时获取官网当前最新版，不会让已安装插件自动更新。需要指定版本时，优先在实例内的市场选择版本；查看历史更新日志不会改变文档站复制按钮所提供的最新版地址。

也可以选择本地 .js 文件或直接粘贴源码。手动 URL 导入不等同于根据市场索引进行完整性校验；需要依据索引哈希验证时，使用市场安装流程。

管理市场源

实例默认提供官网和 GitHub 两个源。市场源必须指向符合索引 v1 格式的 index.json，而不是官网 HTML 页面。

正在加载官网地址…

以上官方市场源地址会根据当前文档站域名选择。通用 GitHub 源为：

https://raw.githubusercontent.com/QuantumNous/new-api-plugins/main/index.json

新增第三方源时，确认索引及其引用的插件文件均能访问。浏览器导入还需要源站允许跨域读取；无法下载时检查网络、CORS 和文件大小。当前插件源码上限为 1 MiB。

升级与回退

• 每个插件以 key + version 标识版本。同一 key/version 不能上传不同源码；修改插件必须使用新版本。
• 新版本安装后，检查已安装列表中的当前生效版本。也可以在插件详情的版本列表中激活已保存的版本，完成升级或回退。
• 升级前阅读 Migration，核对模型名、Base URL、用量字段和价格。插件默认 Base URL 的变化不会自动修改已有渠道。
• 已进入处理的请求固定使用当时的插件运行代；后台轮询可能使用后续激活的新版本。新版本必须兼容尚未完成任务的数据，升级和回退都要考虑这一点。

停用与删除

先检查关联渠道与进行中的任务，并按管理页面的提示处理引用。不要把强制操作当作常规升级步骤。

内置插件不能单独停用或删除。对于覆盖内置插件的自定义版本，停用或移除覆盖后会恢复内置版本；第三方独立插件停用或删除后不再提供相应能力。

遇到安装失败、版本冲突或运行节点状态不一致时，参见常见问题。