mirror of
https://github.com/zyycn/codex-proxy-rs.git
synced 2026-11-06 08:06:19 +00:00
b981e42342
Co-authored-by: Zyy <zyycn@users.noreply.github.com> Co-authored-by: Codex <noreply@openai.com>
131 lines
10 KiB
Markdown
131 lines
10 KiB
Markdown
# 插件使用
|
||
|
||
插件“制品”是按 SHA-256 固定的代码、版本和访问域；“配置”是运行实例，保存普通设置、敏感设置和功能范围。
|
||
日常使用只维护一个当前配置，同一插件最多启用一个实例。访问域随制品接受，不能在设置中另行增删。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[选择来源] --> B[校验包并查看访问域]
|
||
B --> C[确认安装并接受制品]
|
||
C --> D[生成默认配置]
|
||
D -->|配置完整| E[启用并发布]
|
||
D -->|缺少必填项| F[补充配置后启用]
|
||
```
|
||
|
||
宿主支持 SDK `0.1.0`、`manifestVersion: 1` 和进程协议 `1`，只接受当前合同的插件包。
|
||
正文按块传输，插件通信不额外限制正文总量。宿主、SDK 和打包 CLI 必须使用同一套合同；
|
||
现有开发插件需要重新构建并打包，不能只修改包内版本字段。包必须同时满足当前平台和宿主兼容范围。
|
||
|
||
## 安装
|
||
|
||
在“插件管理”点击安装图标，选择来源：
|
||
|
||
- **上传包**：选择发布者提供的 `tar.gz` 或 `tgz` 包
|
||
- **URL**：填写固定下载地址；支持 HTTPS，本机回环地址可使用 HTTP
|
||
- **GitHub**：填写仓库地址或 `owner/repo`；标签留空查询最新稳定版，预发行版须指定标签
|
||
|
||
公开来源无需认证。私有来源可选择或创建独立下载认证；认证按来源和用途限制，不会交给插件进程。
|
||
下载代理独立选择，默认直连，代理失败不会回退直连。SHA-256 用于固定内容，不证明发布者身份。
|
||
|
||
“下一步”只解析和校验包，不保存制品。检查名称、发布者、版本、平台、摘要和访问域后确认安装；上传、URL
|
||
和 GitHub 安装会接受该摘要声明的访问域。随宿主发行物导入的官方制品会显示为“待接受”，也必须先查看访问域并确认，
|
||
未接受的制品不能创建或编辑配置。相同摘要的确认可安全重试。
|
||
|
||
确认安装后，若该插件还没有任何配置，宿主会：
|
||
|
||
1. 从 schema 填入普通配置默认值，不把敏感字段的默认值写入普通配置
|
||
2. 为需要实例范围的贡献项生成默认绑定；管理页面、命令行和自动维护按声明注册，入口认证不自动绑定
|
||
3. 配置完整时直接启用并发布；仅缺少必填项时保存为停用并打开配置页
|
||
|
||
类型错误、非法 schema 或把敏感值混入普通配置会直接拒绝，不会伪装成“待配置”。更新已有插件时不会创建另一套配置，
|
||
管理端在包安装完成后提示确认切换，检查通过后应用目标版本，不兼容时保留原版本并打开待调整的设置。
|
||
|
||
### 访问域
|
||
|
||
安装确认只使用以下稳定访问域；具体调用仍受贡献项、当前调用上下文和宿主策略限制。
|
||
|
||
| 标识 | 安装摘要中的含义 |
|
||
| --- | --- |
|
||
| `network` | 访问网络 |
|
||
| `models` | 查询模型和 Client Key 基本信息并调用模型，可能产生消耗 |
|
||
| `accounts` | 读取和修改账号，包括访问原始凭据 |
|
||
| `data` | 仅在管理、命令或维护入口只读全部账号的基础信息和已有额度观测，不含凭据或预测 |
|
||
| `requests` | 查看和处理请求、响应、路由及账号选择 |
|
||
| `public_endpoints` | 提供无需登录即可访问的资源与回调入口 |
|
||
| `groups` | 创建插件自有分组，可将所有现有及未来账号加入或移出这些分组 |
|
||
| `keys` | 创建绑定插件自有分组的 Client Key，不读取密钥明文 |
|
||
|
||
访问域不是操作列表或资源白名单。实例配置不能扩大、缩小或伪造制品声明；切换版本后使用目标制品已经接受的精确声明。
|
||
插件进程与网关使用相同的系统身份，接受访问域不是操作系统沙箱，因此只安装可信来源的包。
|
||
|
||
## 配置与启用
|
||
|
||
在插件详情中直接启用或停用，设置会保留，无需重新填写。插件没有可设置的参数或认证映射时不显示设置入口。
|
||
|
||
“设置”按当前包的 schema 显示参数，敏感字段单独保存且不回显。首次补齐必填项后“保存并启用”；其他设置修改保持
|
||
原有启停状态。请求处理能力随包自动注册，无需在安装时逐项勾选；有特殊需求时，可在“高级设置”中调整请求作用范围。
|
||
客户端 Key、账号分组、Provider 和模型等范围同时满足才生效，同一范围内任一值匹配即可。
|
||
|
||
范围数组为空表示不限制该维度。自动创建的默认绑定不预先绑定 Client Key；普通网关请求仍以实际请求的 Key 和冻结策略
|
||
执行。管理页面和命令行不保存功能 binding，页面调用模型时由页面每次明确选择一个 Client Key ID，宿主按当前 Key 状态、
|
||
范围、预算、账本和普通请求链执行，插件看不到 Key 明文。
|
||
|
||
`frontend_authentication` 不会随安装自动接管入口。启用它时必须明确配置外部 principal 到既有 Client Key 的映射；
|
||
已停用或删除的 Key 不会因此恢复访问。已有多套配置保留在“历史配置”中，选择使用时确认替换当前配置；不再提供新增配置入口，
|
||
也不会自动删除历史配置、密钥或私有数据。升级前已经启用多套的插件会提示整理，宿主不会擅自选择停用对象，后续启用或更新
|
||
必须收敛到一套配置。
|
||
|
||
声明自动维护的插件可自行准备已授权的分组和 Key，无需提供管理员密码。停用会停止维护，但保留这些资源及其原生启用状态；
|
||
删除插件配置也不自动删除资源。需要撤销 Key 访问时，在 Key 管理中停用或删除相应 Key。
|
||
|
||
“已启用”表示配置已经发布，不是外部服务的健康证明。“等待生效”表示候选仍在准备；“需要处理”会显示发布或运行失败原因。
|
||
并发编辑冲突时应重新加载当前 revision 后确认，不能覆盖另一窗口的修改。
|
||
|
||
## 使用
|
||
|
||
| 功能 | 使用方式 |
|
||
| --- | --- |
|
||
| 管理页面 | 从插件详情或左侧插件导航打开；页面在隔离 iframe 中运行 |
|
||
| 自动维护 | 启用、重启及账号等配置变化后自动对账；失败重试，周期补漏 |
|
||
| 页面模型请求 | 每次选择 Client Key，经固定实例版本的 Responses 桥执行，返回原生 JSON 或 SSE |
|
||
| 请求中间件、模型路由、账号调度、重试策略、请求观察 | 匹配功能范围的正常网关请求自动使用；重试策略故障时交给后续处理 |
|
||
| 模型目录 | 启用后原子发布别名，列表与路由继承目标模型的能力和现有访问范围 |
|
||
| 基础数据页面 | 通过 `data` 只读账号基础信息与已有额度观测，展示本身不进入请求改写链 |
|
||
| 入口认证 | 客户端按插件协议访问，宿主把明确的 principal 映射到 Client Key |
|
||
| 命令行 | 在宿主环境运行 `codex-proxy-rs plugin <配置 ID> --help` |
|
||
|
||
页面模型桥要求管理会话、当前实例/制品/revision 和 `models` 访问域同时有效。停用实例、切换版本或 revision、
|
||
撤销相应访问资格后，宿主会在等待首帧和交付响应期间持续复核并取消请求；它不会把管理 Cookie、Key 明文或认证头交给插件。
|
||
|
||
## 更新、回退与卸载
|
||
|
||
- **检查更新**：GitHub 按保存的策略查询发布，URL 下载并解析当前地址的包；本地上传不支持查询。检查本身不会安装，GitHub 标签也不等于包内版本。
|
||
- **更新插件**：选择新包并确认安装，再确认切换到目标版本。保留已填写的值，补充新版本缺失的默认值；字段改名、类型改变或删除等不兼容情况由用户调整，不猜测或静默清空参数与密钥。
|
||
- **切换版本**：在版本列表中选择已安装版本，确认当前版本与目标版本后执行。若该版本已有恢复设置，使用它上次启用时提交的参数、密钥与功能范围；否则从当前设置生成草稿。切换保持启停状态，目标访问域以已接受的包为准。停用的历史配置引用旧版本时显示“历史配置”，不表示该版本正在运行。
|
||
- **回退版本**：只列出同一插件已安装、已接受且保留恢复设置的较早版本，恢复对应设置后重新执行兼容检查。
|
||
|
||
每个精确插件包保留最近一次启用时提交的配置快照，停用期间未完成的草稿不会覆盖恢复点。升级宿主时会为已有启用配置建立
|
||
恢复点，无法补回此前已经丢失的旧版本设置。修改下载来源会先单独保存，取消后续安装也会保留已保存来源。当前浏览器标签页
|
||
记住未提交的安装参数和凭据引用，不保存认证明文或上传文件。
|
||
|
||
设置恢复不等于私有数据恢复。私有数据迁移仍由插件声明的迁移能力处理，不兼容且无迁移路径时不能切换；迁移失败会尝试
|
||
恢复原版本，若恢复会覆盖并发修改则保持停用并提示处理。配置检查或候选准备失败不会覆盖当前设置。
|
||
|
||
宿主重启时逐个恢复已启用插件。不兼容、启动失败的实例显示异常并保留设置，管理员可重新启动、停用或切换版本；
|
||
其他插件、原生转发和管理端继续运行。运行中的插件进程退出时，也不会撤销整个宿主的运行配置。
|
||
命中故障插件绑定的请求仍遵循既有拒绝或委托策略；入口认证插件失败不会绕过认证。
|
||
|
||
| 操作 | 删除什么 | 保留什么 |
|
||
| --- | --- | --- |
|
||
| 停用 | 不删除；新请求不再使用 | 配置、密钥、私有数据和版本 |
|
||
| 删除配置 | 该配置及其密钥、私有数据、版本配置快照；无法撤销 | 已安装版本 |
|
||
| 删除版本 | 所选制品、对应配置快照及其已无引用的下载认证；最后一个版本还会清理来源规则；被配置或在途调用引用时不能删除 | 其他版本与配置、共享下载认证 |
|
||
| 卸载插件 | 确认范围内的配置、数据、版本、来源规则及已无引用的下载认证 | 其他插件仍使用的下载认证、审计记录 |
|
||
|
||
卸载不是跨多个请求的事务；失败时会显示已完成结果，可重试剩余步骤，不会扩大到确认后新增的配置。只想暂时停用时不要卸载。
|
||
完整卸载后重新安装可选择新的来源，不再沿用旧来源限制。独立创建但未被删除版本使用的下载认证不会被顺带删除。
|
||
需要保留数据时，删除前按[部署、备份与恢复](../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-插件管理)。
|