mirror of
https://github.com/zyycn/codex-proxy-rs.git
synced 2026-11-20 16:01:55 +00:00
137 lines
11 KiB
Markdown
137 lines
11 KiB
Markdown
# 插件使用
|
||
|
||
插件“制品”是按 SHA-256 固定的代码与版本;“配置”是运行实例,保存普通设置、敏感设置和功能范围。
|
||
日常使用只维护一个当前配置,同一插件最多启用一个实例
|
||
|
||
[安装](#安装) · [完整信任](#完整信任) · [配置与启用](#配置与启用) · [使用](#使用) · [更新与卸载](#更新回退与卸载)
|
||
|
||
## 安装
|
||
|
||
在“插件管理”点击安装图标,选择来源:
|
||
|
||
- **上传包**:选择发布者提供的 `tar.gz` 或 `tgz` 包
|
||
- **URL**:填写固定下载地址;支持 HTTPS,本机回环地址可使用 HTTP
|
||
- **GitHub**:填写仓库地址或 `owner/repo`;标签留空查询最新稳定版,预发行版须指定标签
|
||
|
||
公开来源无需认证。私有来源可选择或创建独立下载认证;认证按来源和用途限制,不会交给插件进程。
|
||
下载代理独立选择,未指定时使用部署默认出口,代理失败不会回退直连。SHA-256 用于固定内容,不证明发布者身份
|
||
|
||
点击“下一步”预检。核对名称、发布者、版本、平台与摘要后确认安装。随宿主导入的官方制品显示“待接受”,确认来源后才能创建或编辑配置。相同摘要可重复确认
|
||
|
||
确认安装后,若该插件还没有任何配置,宿主会:
|
||
|
||
1. 从 schema 填入普通配置默认值,不把敏感字段的默认值写入普通配置
|
||
2. 为需要实例范围的贡献项生成默认绑定;模型目录、管理页面、命令行和自动维护按声明注册,入口认证不自动绑定
|
||
3. 配置完整且版本兼容时直接启用并发布;缺少必填项或版本不匹配时保存为停用,补充配置或确认风险后再启用
|
||
|
||
类型错误、schema 无效或普通配置含敏感值时,安装被拒绝。更新已有配置须[确认切换版本](#版本与设置),配置不兼容时保留原版本并打开待调整的设置
|
||
|
||
### 完整信任
|
||
|
||
插件以网关的系统身份访问数据、凭据、配置和网络,没有沙箱或权限清单隔离。包格式、摘要和兼容性校验无法验证代码安全。安装前确认来源,升级前确认目标版本
|
||
|
||
## 配置与启用
|
||
|
||
在插件详情中直接启用或停用,设置会保留,无需重新填写。插件没有可设置的参数或认证映射时不显示设置入口
|
||
|
||
“设置”按当前包的 schema 显示参数,敏感字段单独保存且不回显。每项显示保存状态,留空保留现有值,填写新值替换该项;
|
||
“清除”只删除对应字段,保存前可撤销。首次补齐必填项后“保存并启用”;其他设置修改保持
|
||
原有启停状态。请求处理能力随包自动注册,无需在安装时逐项勾选;可在“高级设置”中调整各挂载阶段的启停、顺序和失败处理。
|
||
模型请求阶段支持 Key、分组、模型等作用范围;HTTP、WebSocket 消息和服务调用全局生效,具体匹配由插件处理。
|
||
客户端 Key、账号分组、Provider 和模型等范围同时满足才生效,同一范围内任一值匹配即可
|
||
|
||
“事件观察”可独立开关“请求完成与用量”和“上游 WebSocket 事件”。改写请求、响应或消息须使用对应中间件
|
||
|
||
范围数组为空表示不限制该维度。自动创建的默认绑定不预先绑定 Client Key;普通网关请求仍使用实际请求的 Key。
|
||
管理页面和命令行调用模型时另行选择 Client Key,沿用该 Key 的启用状态、范围和预算,计入普通请求用量
|
||
|
||
`frontend_authentication` 不会随安装自动接管入口。启用它时必须明确配置外部 principal 到既有 Client Key 的映射;
|
||
已停用或删除的 Key 不会因此恢复访问
|
||
|
||
管理端为每个插件维护一套当前配置。可在“历史配置”中选择另一套,确认后替换当前配置。
|
||
若有多套配置同时启用,先手动停用多余配置,再启用或更新插件。停用会保留配置、密钥和私有数据
|
||
|
||
声明自动维护的插件可自行准备分组和 Key,无需提供管理员密码。停用会停止维护,但保留这些资源及其原生启用状态;
|
||
删除插件配置也不自动删除资源。需要撤销 Key 访问时,在 Key 管理中停用或删除相应 Key
|
||
|
||
| 状态 | 含义 |
|
||
| --- | --- |
|
||
| 已启用 | 配置匹配且宿主会话就绪,业务与外部服务健康需单独确认 |
|
||
| 等待生效 | 配置正在准备或等待发布 |
|
||
| 需要处理 | 发布或运行失败,详情显示原因 |
|
||
| 运行状态未知 | 暂无运行诊断,保留启用配置 |
|
||
|
||
“运行负载”只统计当前发布会话的在途调用、执行、排队、恢复等待、驻留回调和活动流,各项计数可能重叠。编辑冲突时重新载入配置再确认
|
||
|
||
## 使用
|
||
|
||
| 功能 | 使用方式 |
|
||
| --- | --- |
|
||
| 管理页面 | 从插件详情或左侧插件导航打开;插件请求打开外链时,核对目标域名后可打开、复制或取消 |
|
||
| 自动维护 | 启用、重启及账号等配置变化后自动对账;失败重试,周期补漏 |
|
||
| 页面模型请求 | 每次选择 Client Key,经固定实例版本的 Responses 桥执行,返回原生 JSON 或 SSE |
|
||
| 请求中间件、模型路由、账号调度、重试策略、请求观察 | 匹配功能范围的正常网关请求自动使用;重试策略故障时交给后续处理 |
|
||
| 上游适配器 | 为内置 OpenAI / xAI 的生成请求提供上游实现;沿用宿主选号、代理、租约与结算,命中但不可用时拒绝请求 |
|
||
| 模型目录 | 原子发布直接别名或适配模型;别名继承目标能力,适配模型按适配器账号范围和声明能力参与既有路由 |
|
||
| 基础数据页面 | 通过宿主数据回调读取账号基础信息与已有额度观测,展示本身不进入请求改写链 |
|
||
| 入口认证 | 客户端按插件协议访问,宿主把明确的 principal 映射到 Client Key |
|
||
| 命令行 | 在宿主环境运行 `codex-proxy-rs plugin <配置 ID> --help` |
|
||
|
||
页面模型桥要求管理会话、当前实例/制品/revision 均有效。停用实例、切换版本或 revision、
|
||
目标失效后,宿主会在等待首帧和交付响应期间持续复核并取消请求。页面用 Key 标识选择推理身份;
|
||
插件中间件仍可读取完整请求头并改写响应,页面桥不提供额外的插件安全隔离
|
||
|
||
## 更新、回退与卸载
|
||
|
||
### 版本与设置
|
||
|
||
- **检查更新**:GitHub 按保存的策略查询发布,URL 下载并解析当前地址的包;本地上传不支持查询。检查本身不会安装,GitHub 标签也不等于包内版本
|
||
- **更新插件**:安装新包,再按下述切换规则确认目标版本;字段改名、类型改变或删除等不兼容情况由用户调整,不猜测或静默清空参数与密钥
|
||
- **切换版本**:在版本列表中选择已安装版本,确认当前版本与目标版本后执行。若该版本已有恢复设置,使用它上次启用时提交的参数、密钥与功能范围;否则从当前设置生成草稿。切换保持启停状态,目标制品必须已接受。停用的历史配置引用旧版本时显示“历史配置”,不表示该版本正在运行
|
||
- **回退版本**:只列出同一插件已安装、已接受且保留恢复设置的较早版本,恢复对应设置后重新执行兼容检查
|
||
|
||
没有目标快照时,草稿保留显式值并补齐 schema 默认值。停用草稿不覆盖最近启用时的恢复点
|
||
|
||
宿主更新的检查与恢复要求见[插件兼容与发行目录](../deploy/README.md#插件兼容与发行目录)
|
||
|
||
修改下载来源会先单独保存,取消后续安装也会保留已保存来源。当前浏览器标签页
|
||
记住未提交的安装参数和凭据引用,不保存认证明文或上传文件
|
||
|
||
设置恢复不等于私有数据恢复。私有数据迁移仍由插件声明的迁移能力处理,不兼容且无迁移路径时不能切换;迁移失败会尝试
|
||
恢复原版本,若恢复会覆盖并发修改则保持停用并提示处理。配置检查或候选准备失败不会覆盖当前设置
|
||
|
||
接口弃用提示展示兼容窗口与作者说明,不改变插件启停状态;规则见 [接口弃用](../backend/crates/gateway-plugin/sdk/docs/manifest.md#接口弃用)
|
||
|
||
### 故障处理
|
||
|
||
不兼容的插件不会自动启动或挂载能力,已保存的启用配置、绑定、密钥和私有数据均保留。宿主继续执行原生认证
|
||
|
||
- **宿主范围或能力版本不匹配**:黄色三角标记显示原因。可在详情中确认风险并尝试启动。确认仅对当前宿主、插件包和配置版本的本次启动有效。启动成功后仍显示提醒
|
||
- **包损坏、清单或 RPC 格式不兼容、平台不符**:按提示更换兼容包。版本要求见 [SDK](../backend/crates/gateway-plugin/sdk/README.md),重启检查见[部署说明](../deploy/README.md#插件兼容与发行目录)
|
||
|
||
通过兼容检查后,RPC 握手失败或运行中进程崩溃、帧边界、调用关联或传输错误会使对应实例未就绪,
|
||
显示红色三角感叹号及脱敏错误详情,保留启用配置,可在详情中重新启动或切换版本。连续故障受重启次数限制
|
||
|
||
能力响应无法解码只使当前调用失败;上游 429、用户请求错误和插件主动拒绝请求等业务结果不会直接停止插件。单个插件故障不撤销整个宿主的运行配置;命中故障插件绑定的请求仍遵循既有拒绝或委托策略,包括全局 HTTP 绑定覆盖的管理请求。已进入执行集合的入口认证插件故障不会降级到其他认证方式
|
||
|
||
插件中间件达到调用容量或排队上限时,HTTP 响应为 503(`middleware_capacity_unavailable`),不会跳过插件或重放请求。
|
||
应结合插件耗时和并发负载排查;会话预算与作者侧配置见 [SDK 并发与期限](../backend/crates/gateway-plugin/sdk/README.md#并发与期限)
|
||
|
||
### 停用与删除
|
||
|
||
| 操作 | 删除什么 | 保留什么 |
|
||
| --- | --- | --- |
|
||
| 停用 | 不删除;新请求不再使用 | 配置、密钥、私有数据和版本 |
|
||
| 删除配置 | 该配置及其密钥、私有数据、版本配置快照;无法撤销 | 已安装版本 |
|
||
| 删除版本 | 所选制品、对应配置快照及其已无引用的下载认证;最后一个版本还会清理来源规则;被配置或在途调用引用时不能删除 | 其他版本与配置、共享下载认证 |
|
||
| 卸载插件 | 确认范围内的配置、插件私有数据、版本、来源规则及已无引用的下载认证 | 其他插件仍使用的下载认证、审计记录 |
|
||
|
||
卸载不是跨多个请求的事务;失败时会显示已完成结果,可重试剩余步骤,不会扩大到确认后新增的配置。只想暂时停用时不要卸载。
|
||
完整卸载后重新安装可重新选择来源。独立创建但未被删除版本使用的下载认证不会被顺带删除。
|
||
通过用量服务写入的明细与聚合统计不会随插件停用、删除配置或卸载而删除。明细遵循宿主请求历史保留策略,聚合由写入方管理清理;删除插件前按需使用其数据清理功能
|
||
|
||
需要保留数据时,删除前按[部署、备份与恢复](../deploy/README.md)保存备份
|
||
|
||
开发插件见 [SDK](../backend/crates/gateway-plugin/sdk/README.md) 与 [插件 CLI](../backend/apps/plugin-cli/README.md);
|
||
完整示例在独立的 `codex-proxy-plugins` 仓库维护。HTTP 字段与限制见 [API 参考](api.md#12-插件管理)
|