//! API 代理持久化模型(`api-proxies.json`:以 slug 为 key)。 //! //! 字段名与旧版 `data/api-proxies.json` **逐字对应**,以便新版直接接管旧数据文件。 use serde::{Deserialize, Serialize}; use std::collections::BTreeMap; /// API 代理表(`api-proxies.json`)。 /// /// 与 `llm-upstreams.json` 同构:每条记录 = 一个供应商(自带基址与密钥), /// 由 `slug` 区分。调用方访问 `/apix/?参数=值`,网关用本记录里的密钥 /// 转发到供应商、并把响应原样返回。不同供应商彼此独立、互不耦合。 /// /// `key` 是供应商真 Key,**敏感级别等同 `users.json`**(data/ 已 gitignore)。 #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ApiProxyStore { /// slug → 代理映射 #[serde(default)] pub items: BTreeMap, } impl Default for ApiProxyStore { fn default() -> Self { Self { items: BTreeMap::new() } } } /// 单个 API 代理条目:指向某一家供应商的一个可调用的资产。 #[derive(Debug, Clone, Serialize, Deserialize)] pub struct ApiProxy { /// 供应商侧的资产 id(如 `searxng-search`),决定具体调用哪个资产。 /// **vendor 模式必填**;passthrough 模式用不到(上游路径由 URL 尾部决定),可留空。 pub asset_id: String, /// 供应商名称(仅展示用,管理员自填,例如 `provider-x` / 客户自定) #[serde(default)] pub supplier: String, /// 供应商基址,如 `https://api.example.com` #[serde(default)] pub base: String, /// 供应商 API Key(`ak_...`)。留空 = 未配置,热路径直接 503。 /// **敏感**:写盘与回显都按密钥处理,管理台只回显掩码。 /// passthrough 模式下若上游不需要鉴权可留空(不下发任何鉴权头)。 #[serde(default)] pub key: String, /// 代理模式: /// - `vendor`(默认):单一供应商收口 `POST {base}/api/v1/ai/request`, /// 请求体由网关按 `asset_id` 拼装(见 `apix.rs`)。 /// - `passthrough`:透传模式,原样转发客户端的方法/请求体/Content-Type, /// 上游路径 = `{base} + /apixp/ 之后的 URI 尾部`,用于 OCR / 文生图 / /// TTS 这类「多端点、多 body、无 asset 市场」的内部 REST 服务。 #[serde(default = "default_mode")] pub mode: String, /// 展示名(中文) #[serde(default)] pub name: String, /// 一句话说明 #[serde(default)] pub desc: String, /// **声明式参数清单**(如 `["q"]`)。 /// /// 只用于给调用方看的文档(管理台把 `?q=关键词` 拼出来、账号态接口回显), /// 转发时**不按它过滤**——过滤要靠读请求体,而 access 阶段读不到。 /// 供应商侧自己会拒绝不认识的参数,拦在网关意义不大。 #[serde(default)] pub params: Vec, #[serde(default = "default_true")] pub enabled: bool, #[serde(default)] pub note: String, /// 调用语法提示(**机器可读**的描述字段,专为 passthrough / 复杂 vendor 设计)。 /// /// 为什么需要:`/api/v1/me` 把这条发给用户 AI 后,AI 必须能**自己拼出**调用语法—— /// 路径尾部是什么、什么 Content-Type、上游 Swagger 在哪。`desc` 是中文给运维看的, /// `params` 只对 vendor 有意义,对 passthrough 是空数组,没法告诉 AI 怎么调。 /// `usage_hint` 是管理员按建议格式(自由文本)填写的结构化提示,AI 直接解析。 /// /// 不进 shm:热路径只查 base/key/asset_id/mode,`usage_hint` 只在管理台 + /// `/api/v1/me` 拉清单时回显,进 shm 反而占带宽。 /// /// 建议格式(OpenAPI 风格): /// ```text /// POST / multipart, fields=[file]; OCR 上传图片 /// POST //base64 json, {image_base64:string} /// POST //url?url= json, {} /// Swagger: http://192.168.1.11:9003/docs /// ``` #[serde(default)] pub usage_hint: String, #[serde(default)] pub created_at: i64, } fn default_true() -> bool { true } /// 默认代理模式 = vendor(向后兼容旧数据:没有 `mode` 字段的条目就是 vendor)。 fn default_mode() -> String { "vendor".to_owned() }