渠道管理

• 渠道是 AIMirrorX 连接上游 AI 服务的配置单元。管理员可访问 /channels或从侧边栏进入「渠道」。
• 本页仅说明渠道页面的配置和维护。
• 模型目录、价格与用户分组还需要结合模型管理、计费与支付配置和用户管理共同配置。

渠道管理概览

渠道列表支持卡片和表格两种视图。卡片视图适合快速查看，表格视图适合排序、列设置和选择渠道。

• 渠道管理-卡片视图

• 渠道管理-表格视图

搜索、筛选与显示

权限与安全边界

所有渠道接口先要求 Admin 或 Root，再按操作检查渠道权限。普通 Admin 的具体权限由 Root 在管理员权限矩阵中配置。

创建与编辑渠道

当前编辑器先选择提供商或插件，再进入四个配置页签：连接与模型、路由与映射、请求与响应、其他设置。保存时前端校验表单，后端再次检查渠道类型、凭证、插件绑定和高级配置。

选择提供商或插件

• 渠道管理-选择内置渠道

• 渠道管理-选择插件渠道

• 渠道管理-选择网关渠道

• 渠道管理-选择自定义渠道

创建时「插件」分类只在当前用户拥有 TaskPluginBind 权限时显示；插件列表加载失败时显示「加载插件失败」和重试入口，没有可绑定插件时显示「暂无可绑定的插件」。搜索框也可以按内置类型编号查找自定义类型；这不是对任意类型都提供了适配器支持。

四种创建方式的选择建议

• 标准供应商或协议：选择内置渠道，使用该类型专属凭证和默认地址提示。
• 已安装任务插件：选择「插件」，确认插件的模型、上游类型和默认地址，再配置插件所需凭证。
• AIMirrorX/Sub2API 上游网关：选择「网关」；不要用 Legacy Custom 代替网关适配器。
• 多入口、多协议或多供应商：选择 Advanced Custom；必须先设计入口路径、上游路径、鉴权和转换器。

连接与模型

• 渠道管理-连接与模型

连接与模型流程

1. 选择类型后先阅读该类型的地址和凭证提示。
2. 填写名称、Base URL、凭证、模型和分组。
3. 对支持的类型点击获取模型，勾选实际可用模型并保存选择。
4. 如需映射，确认源模型在模型列表中；映射目标应由上游真实支持。
5. 保存渠道后，再进行测试，不要把表单中成功读取模型理解为渠道已完成可用性验证。

类型专属凭证

单密钥、批量创建与多 Key

路由与映射

• 渠道管理-路由与映射

映射存在三类常见风险：JSON 无效、源模型不在公开列表、上游目标名称被公开给用户。保存时界面会提示缺失源模型，也会提示公开了映射目标；应先确认用户侧模型列表，再决定是否添加或移除名称。

请求与响应

• 渠道管理-请求与响应

覆盖规则

透传与覆盖的执行边界

• 渠道管理-确认开启透传请求体

• 渠道管理-确认开启透传请求头

• 全局或渠道级请求体透传会跳过正常转换链路；不要同时假设模型映射、参数覆盖和协议转换仍会按普通路径执行。
• 请求头透传使用 * 或 re:/regex: 规则复制客户端请求头，但会排除 Authorization、x-api-key、x-goog-api-key、WebSocket 握手和其他安全头。
• 请求头覆盖在透传之后应用，显式覆盖优先；{client_header:NAME} 必须是完整值，客户端未携带该头时不会加入。
• 请通过客户端请求选择流式模式。参数覆盖改写 JSON 中的 stream 不保证同步调整网关、适配器和上游的流式处理状态。

其他设置

• 渠道管理-其他设置

渠道类型专属配置

网关渠道：AIMirrorX 与 Sub2API

• 渠道管理-AIMirrorX 网关渠道

AIMirrorX 和 Sub2API 都通过网关 Base URL 拼接请求路径，普通配置不会自动补 /v1，因此 Base URL 不应以 /v1 结尾。两者可提供 OpenAI、Responses、Claude、Gemini 等网关能力；具体支持范围以网关实际部署为准。

AIMirrorX 还可以绑定支持 new_api 上游的任务插件扩展。扩展仍保持 type=60，不能把它和独立插件渠道混淆。绑定、解绑和复制带扩展的渠道需要 TaskPluginBind。

独立插件渠道

• 渠道管理-插件渠道

1. 在「插件」分类中选择已注册插件。
2. 核对插件名称、标识、预填模型和默认 Base URL。
3. 填写插件所需凭证、分组和其他字段。
4. 保存后按插件支持的任务流程验证；不要使用普通 API 渠道的测试结论替代插件验证。

插件默认地址为空时必须填写地址；插件模型是插件声明的初始值，不代表上游凭证已经可用。插件具体支持模型、路由和请求类型可能随安装版本变化。在 /v1/images/generations、/v1/images/edits、/v1/responses、/v1/videos 等共享入口上，同一模型的普通渠道与插件渠道按分组、优先级和权重一起参与选择；选中普通渠道时，请求按普通渠道转发，不经过插件。

高级自定义渠道

• 渠道管理-高级自定义渠道

选择 Advanced Custom 后，必须至少保留一条有效路由。打开路由编辑器：

• 渠道管理-高级自定义路由

保存前检查入口与上游协议匹配、鉴权不会泄露、相对路径有 Base URL。路由配置错误会阻止保存或导致对应入口无法转发。

渠道操作

• 渠道管理-渠道操作

测试连接

• 渠道管理-测试渠道连接

快速测试使用渠道的 test_model；未配置时依次使用渠道模型和默认测试模型。详细测试允许选择端点、流式模式和模型。

1. 选择端点类型；自动检测会按渠道类型选择默认端点，Codex 未指定时使用 Responses。
2. 按需启用流式测试；Embedding、图片、Rerank 和 Responses Compact 不支持流式。
3. 选择单个或多个模型并执行测试。
4. 查看成功/失败、响应时间和错误详情。
5. 删除失败模型前确认失败不是临时网络、限流、代理、端点或价格配置问题。

批量测试前端每批最多运行 5 个模型；停止操作只停止后续批次，不保证取消已发出的请求。全部渠道测试是后台维护任务，不受当前列表筛选范围限制，已有同类任务时可能返回冲突。它跳过手动禁用的渠道，并按请求策略 → 渠道健康的规则自动禁用或恢复渠道；单个渠道的测试只显示结果，不改变渠道状态。

查询余额与运行状态

• 渠道管理-查询余额

普通渠道的余额查询按渠道类型调用不同上游接口，并非所有类型支持余额；多 Key 渠道和任务插件渠道不支持余额查询。全部余额更新遍历启用且非多 Key 渠道，可能产生大量上游请求；不会因为当前列表筛选而只处理可见行。全部余额更新时，若查询到余额小于等于 0，开启了「异常自动禁用」的渠道会被自动禁用（只看渠道开关，不受全局「失败时禁用」影响），原因为「余额不足」。vLLM/SGLang 的余额位置实际打开推理服务状态，不是普通余额查询；Codex 则显示用量和额度重置信息。

获取模型与上游模型更新

• 渠道管理-获取模型

1. 发起上游模型列表请求。
2. 在「新模型」「现有模型」「已移除模型」之间切换。
3. 按提供商分组，勾选单个或整组模型。
4. 点击「保存模型」后才写回渠道；取消或请求失败不会替换已保存列表。

已有渠道获取模型和创建/编辑表单使用临时凭证获取模型的权限不同：前者是 ChannelOperate，后者是 ChannelSensitiveWrite。

复制渠道

• 渠道管理-复制渠道

1. 选择复制渠道，填写名称后缀。
2. 确认是否重置余额和已用额度；默认后缀为 _copy。
3. 确认复制。新渠道会复制原渠道的大部分配置和凭证，并获得新的 ID 与创建时间。
4. 重新检查凭证、模型、分组、映射、路由和状态。

复制带任务插件绑定的渠道还需要绑定权限。复制完成后测试时间和响应时间会重置；不要将复制动作当作凭证轮换。

启用、禁用与删除

• 手动状态操作只接受启用或手动禁用；自动禁用由可靠性逻辑产生。
• 删除单个、批量删除和「删除所有已禁用」需要 ChannelSensitiveWrite。
• 「删除所有已禁用」按全库的手动/自动禁用状态删除，不受当前搜索、类型、分组、标签或分页筛选限制。
• 删除渠道后无法从 AIMirrorX 恢复；执行前导出或记录配置。

修复渠道一致性

• 渠道管理-修复渠道一致性

「修复渠道一致性」会根据全部渠道配置重建模型能力、分组、优先级和权重索引。过程中路由可能短暂不完整；建议低峰期执行，完成后刷新列表并测试代表性模型。它不会修复上游凭证、代理或模型价格问题。

标签与批量操作

• 渠道管理-批量操作

批量选择操作作用于当前已选择的渠道 ID。按标签启停或编辑是独立的标签范围操作，不等于当前分页中已选行。批量测试、全部余额更新和上游更新可能产生大量请求或后台任务，应先确认维护窗口。

拖拽调整优先级

• 渠道管理-拖拽模式

点击工具栏「拖拽模式」后，拖动渠道左侧（卡片视图为左上角）的拖拽手柄即可调整优先级；按钮变为「完成排序」，再次点击退出。拖到某个渠道中间会「加入同一优先级」，拖到两档之间会「插入新优先级」，数值由系统自动计算。松手后立即保存，列表下方可「撤销」上一次调整。

多 Key 渠道

创建与轮询模式

创建时选择「多 Key 合并」会把多个凭证保存到一个渠道；批量创建则会生成多个独立渠道。

状态管理与删除风险

• 渠道管理-多密钥管理

在渠道操作菜单中点击「管理密钥」打开「多密钥管理」。列表按 Key 分页显示索引、状态、禁用原因和禁用时间，可按状态筛选；顶部「已启用」「手动禁用」「自动禁用」统计卡始终统计全部 Key，不随筛选变化。

• 启用或禁用单个 Key 只改变该 Key 状态。
• 删除单个 Key 后，后续 Key 索引会重新排列；不能删除最后一个 Key。
• 「删除自动禁用」只删除自动禁用的 Key，手动禁用的 Key 会保留；该按钮仅在存在自动禁用 Key 时显示。
• 没有可用 Key 时，渠道会整体禁用：在「多密钥管理」中禁用或删除到没有可用 Key 时，渠道变为手动禁用，重新启用任一 Key 后自动恢复；Key 被系统全部自动禁用时，渠道变为自动禁用，需要先启用 Key，再手动启用渠道（开启「成功后重新启用」时也可由下一次定时测试或「测试所有渠道」恢复）。

条件功能

以下功能按渠道类型、权限或配置动态显示：

• Ollama 模型拉取、删除和版本查询；这些操作可能直接改变上游模型资源。
• Codex 凭证刷新、用量与额度重置。
• vLLM/SGLang 推理服务状态。
• 任务插件绑定、AIMirrorX 扩展插件。
• Advanced Custom 路由、协议透传和专属模型检测。
• 支持上游模型获取的类型及其模型更新检查。

保存后的验证流程

1. 检查连接与模型页签状态为可保存，确认名称、凭证、模型和分组。
2. 保存后刷新页面，确认密钥空框仍表示保留而不是被清空。
3. 使用详细测试选择一个代表性端点和模型，核对成功、失败和响应时间。
4. 使用实际用户分组和 API Key 发起端到端请求，检查最终渠道和上游模型。
5. 若配置映射、参数覆盖、透传、代理或高级路由，再分别验证一个启用和一个未启用场景。
6. 上游模型更新先检测、审核新增/移除列表，再选择性应用；不要未经审核自动扩大公开模型列表。

故障排查

参数覆盖系统

参数覆盖在请求转换后、发送上游前执行。它不是完整协议转换器，也不会自动同步客户端流式状态。可视化编辑器和 JSON 模式写入同一份 param_override。

生效顺序与边界

• 只有请求进入相应 relay 处理路径时才会执行覆盖；请求体透传会绕过普通转换和部分覆盖链路。
• operations 按数组顺序执行，前一个操作的结果会成为后一个操作的输入。
• 同时存在旧式顶层字段和 operations 时，旧式字段先应用，再应用 operations。
• 命中会话规则时，规则中的参数覆盖模板会与渠道参数覆盖合并，见会话与重试。
• 条件默认使用 OR；logic: "AND" 才要求全部条件满足。
• 条件读取当前请求 JSON 和运行上下文；前序操作修改模型后，后续条件可能读取修改后的值。original_model、upstream_model 等上下文值不是自动写入请求 JSON 的字段。
• return_error 会提前返回自定义错误；其状态码和错误字段仍受后端解析范围约束，不应仅依据输入框可接受的范围宣称所有值都可用。
• 条件比较出错时（如 full 两侧类型不同、数值比较的一侧不是数字、regex 表达式无效），本次请求以 channel:param_override_invalid 失败，按渠道类错误处理，而不是视为条件不匹配。

可视化编辑器与 JSON

• 渠道管理-参数覆盖

可视化模式适合逐条编辑；JSON 模式适合复制完整规则。保存前确认规则数量、操作类型、路径、值、条件逻辑和保留原值开关。复杂规则先在测试渠道验证，再应用到生产渠道。

操作速查

条件、路径与安全字段

相关文档

• 模型管理：模型目录、供应商和模型部署。
• 用户管理：用户分组、权限和用户状态。
• 任务插件管理：插件安装、声明和绑定条件。
• 计费与支付配置：模型价格、分组倍率和支付配置。
• 请求策略配置：会话保持与重试、定期渠道测试、自动禁用与自动恢复。
• 模型配置：全局模型行为、供应商适配和模型部署。
• 日志与异步任务：请求、用量、扣费和任务状态。