Fast API 文档

主题

管理员配置与运维 ​

本页只描述当前代码已提供的管理能力。菜单、公开页面和调用行为均可能受系统设置、部署配置、账号类型、渠道平台与版本限制；未启用时不要向用户承诺对应功能。

功能开关与公开范围 ​

  • 「模型广场」「可用渠道」「渠道状态」「支付」等入口由各自功能开关控制；模型广场还可要求登录。站点计费模式由余额充值与 subscription_enabled 共同决定，可选择充值 + 订阅、仅充值或仅订阅；关闭订阅会同时收起用户端订阅入口、购买标签、进度徽标、路由和用量筛选。
  • plugin_management_enabled 只控制管理员侧边栏是否显示「插件管理」，不会停止已加载或正在运行的插件。
  • channel_monitor_show_quota 默认关闭；只有显式开启后，普通用户才会看到渠道配额或余额。吞吐隐藏与用户排行隐藏开关独立生效，排行关闭时普通用户的标签和 /users 数据都会隐藏。
  • 用户可见的模型、分组与价格来自公开配置；实际调用范围始终以该用户的 API Key 请求 /v1/models 为准。
  • api_key_create.max_active_per_user 与 api_key_create.max_per_user_per_hour 分别限制未删除密钥总数和每小时创建次数；0 表示不限，删除密钥不会返还小时计数。

用户与认证 ​

管理员可对单个用户启用「限制可访问的公开分组」。关闭时用户可使用全部公开分组；开启后只能使用勾选的公开分组，专属分组与订阅分组仍按各自绑定规则处理。用户并发值 0 表示不限制，不能填写负数。用户列表支持批量启用、禁用、修改限制或删除已选择用户；操作前应核对选择范围，已删除用户不会再出现在订阅分配搜索中。风险控制还可配置用户允许名单；名单仅在对应策略启用时生效，删除用户或分组后应重新检查范围。

邮箱注册和换绑会进行主域名、别名与并发冲突校验；普通注册必须提交一致的密码与确认密码。SMTP 测试会沿用已保存的 TLS 模式；修改邮件配置后应分别验证连接测试和真实验证码投递。OAuth 注册的优惠码会保留到待处理注册完成，但管理员仍应核对优惠码有效期和适用范围。

账号、配额与重置卡 ​

OpenAI OAuth 账号可选择自动使用重置卡，默认关闭。5 小时与 7 天窗口分别配置 0.1% 到 100% 的阈值，任一窗口达到自身阈值时使用最早到期的可用卡；没有可用卡或重置失败时账号保持暂停。该能力不适用于 Spark 影子账号，运行状态由后端维护，不应通过旧的账号编辑数据覆盖。

智谱团队版 GLM Coding Plan 可在账号配置中填写组织 ID 与项目 ID，让配额查询使用团队版端点；个人版留空。MiniMax 已作为独立平台接入账号、复合路由、配额与渠道监控；OpenCode 支持 Zen/GO 账号类型、协议规则、模型映射和官方用量窗口查询；Cline、Command Code 与 TypeSafe 由统一平台清单约束可用协议及模型同步入口。账号列表支持紧凑筛选、内联调整优先级和带作用范围的临时不可调度规则。账号批量编辑会显式保存 Codex 指纹收敛开关，关闭后不应因省略字段而被旧值重新启用。账号到期时间可使用月末、年末等预设，保存前仍应核对时区和实际时间。

OpenAI OAuth 账号可在支持时查看 Codex 积分、刷新推荐邀请状态并发送邀请；Claude 账号可查询和兑换原生重置额度。这些操作会消耗或改变上游权益，必须保留管理员认证、合规检查、审计日志和界面确认，不应通过脚本绕过确认。

订阅管理支持对选中记录执行批量分配、延期、启停等受支持操作；批量提交前应核对套餐、用户、日期与选择数量。分销记录支持登记线下提现，属于真实余额变更，应保留操作凭据并复核结果。

为需要跨网关追踪请求的账号，可在账号配置中填写直接上游返回请求标识的响应头名；系统会把合法且不超过限制的值写入管理员用量明细的「上游ID」列，留空则不记录。常见兼容网关可能使用 X-Client-Request-ID 或 X-Oneapi-Request-Id，供应商也可能提供自己的请求 ID 头。该字段仅用于观测，不应填写认证或隐私相关响应头。

OpenAI API Key 账号可按需开启「生图结果 URL 转 base64」：仅当非流式 Images 响应缺少 b64_json 但提供 url 时，网关才下载并回填，同时保留原 URL；下载目标会拒绝私网地址并按实际字节识别图片，失败时原样返回。OpenAI OAuth Images 会通过原生 Codex Images 路径处理，并支持当前内置的 Image 2.5 能力；账号另有不可用冷却时间设置，用于避免图片工具暂时不可用时反复调度，仅在确有失败证据时调整。Grok OAuth 账号可把媒体资格设为自动、启用或禁用；自动判断不确定时仍保留账号资格，人工覆盖前应先读取当前探测状态。

渠道、模型与计价 ​

渠道分时计价可设置 IANA 时区、不重叠时段，并选择每日或仅周一至周五生效；无效高峰倍率设置会直接返回参数错误。模型广场的分时行不包含另行显示的高峰倍率；两者重叠时按页面说明叠加。长上下文阶梯必须明确是整单档位还是仅超出部分计价，并分别配置输入、输出、图片缓存、缓存写入与缓存读取口径。推理强度倍率可独立配置并以最终转发强度结算；视频价格按对应模型的时间单位展示，不能套用文本 Token 单价。

分组模型配置现为真正的「模型白名单」：启用后不仅过滤 /v1/models 等模型目录，还会在复合路由改写和调度前校验 Chat Completions、Responses（含 WebSocket 各轮）、Anthropic、Gemini、图片、视频和 Realtime 等网关入口。白名单支持模型名中的通配位置；任一客户端模型未命中即按协议返回不可用。分组名称与说明支持多语言，语言代码会归一化；升级迁移会保留旧 models_list_config 数据并修复曾回滚到旧列名的数据库。空白名单与未启用语义不同，发布前应先用目标 API Key 查询目录并实际调用。

OpenAI/Anthropic 服务层级倍率按请求值与实际上游响应共同结算，只允许按实际结果降档，不允许由未知或更高响应层级抬高费用。修改渠道模型映射、带后缀模型规则或官方价格数据后，应使用实际请求核对使用记录中的请求模型、上游模型、响应模型、服务层级与最终费用。

渠道计价可分别配置 5 分钟与 1 小时缓存写入价格，并为最终转发推理强度为 max 的请求设置额外倍率。分组的 Anthropic/OpenAI 推理上限支持「自动降档」或「拒绝访问」；映射规则可按模型精确名、前缀或后缀限定，精确匹配优先，更长的前后缀优先，上限始终先于映射生效，且不会为未请求推理的调用主动开启推理。

OpenAI 分组可强制把新请求设为 Fast（service_tier=priority），也可将实际使用 Fast 的请求按 Standard 价格向用户计费；全局 Fast/Flex 策略仍可能过滤或拒绝，并可用 missing 条件单独匹配未传 service_tier 的请求。已建立的 WebSocket 会话要重连才会采用新分组设置。全局策略还可单独匹配 ultrafast，不要把它与 priority 的价格或访问规则混为一谈。

OpenAI 分组还可固定最多 10 个组内账号获取 Codex Model Manifest，并按模型 slug 合并结果。启用后 manifest 请求默认绕过调度器；可选择在固定账号全部失败时回退调度器，否则会返回上游错误或 503。这只影响 Codex /models 清单获取，不改变 API Key 白名单、普通模型调用或账号调度规则。

OAuth 出站插件 ​

管理员入口为 /admin/plugins，初期仅支持 OpenAI OAuth 出站传输能力，API Key 请求不受影响。安装包扩展名为 .s2plugin，默认必须由可信发布者签名；安装后保持停用，确认当前网关版本兼容、运行时健康和配置测试通过，再按 1% 到 100% 流量逐步启用。

插件安装、启用、停用与配置通常不需要重启宿主。停用后新的 OAuth 请求立即回到原有路径；卸载前必须先停用。支持 HostService 的插件还可通过只读状态桥接暴露结构化账号元数据和健康状态，管理页展示不代表插件获得额外写权限。生产环境保持 plugins.allow_unsigned: false，第三方发布者公钥通过 plugins.trusted_publishers 追加，不能用同名配置覆盖内置信任来源。

网关与部署检查 ​

  • gateway.openai_ws.force_http 或 GATEWAY_OPENAI_WS_FORCE_HTTP=true 只强制 OpenAI Responses 使用 HTTP/SSE，不会关闭 HTTP/2；HTTP/2 由独立开关控制。
  • OpenAI WebSocket 接入模式可按 off、ctx_pool、passthrough、http_bridge 配置；模式路由会按 Codex 线程和请求类型隔离执行作用域。动态账号连接上限默认按账号并发乘以 OAuth/API Key 系数 5.0 计算，调整前应结合排队数、账号并发和连接池利用率，不能只提高全局上限。长生成 HTTP/2 连接支持 PING keepalive，代理层仍需保留长连接和流式刷新。
  • gateway.models_list_read_max_bytes 限制上游模型列表响应体，默认 8 MiB。调整前应先确认是上游响应过大，而不是代理错误页或循环响应。
  • gateway.min_output_tokens 控制 Chat Completions 或 Anthropic 转 Responses 时的最小输出 Token，最小 16、默认 128；调高会改变请求口径和潜在费用。Gemini 显式缓存另受 gateway.gemini_cached_content_max_ttl_seconds、模型存储单价及余额/订阅预留约束。
  • OpenAI Responses 的首 Token 统计默认沿用「语义事件」口径；切换为「真实可见输出」后，只在首个非空文本、工具参数或图片内容到达时记录。修改口径会影响 TTFT 图表与调度观测，应在比较历史数据时注明切换时间。
  • pricing.fallback_file 只补齐目录中缺失的模型；可选 pricing.override_file 以字段浅合并方式覆盖已有模型，字段值 null 表示删除。远程目录、fallback 与 override 都会按内容哈希热重载；无效 JSON 会保留上一份有效数据，删除本地文件会在下一轮检查移除对应条目。
  • PostgreSQL 暂时处于启动或恢复阶段时，应用会有限重试；凭据错误、迁移校验和不一致和 SQL 错误仍会立即失败。模型白名单、MiniMax、OpenCode 和无限平台配额清理迁移会随启动执行；三档限额均为空的行会被删除，因为缺行即表示不限额。超大表应在升级前评估并按说明调整迁移超时。Compose 健康检查同时执行 pg_isready 与简单 SQL，不能用延长启动宽限期掩盖永久错误。
  • Compose 更新后检查网关环境变量是否透传、容器是否保留资源约束与安全选项；不要把示例配置中的调试开关直接用于生产。
  • 新部署留空 ADMIN_EMAIL 与 ADMIN_PASSWORD 时会随机生成登录邮箱和密码并写入首次启动日志；不要继续使用可猜测的默认管理员邮箱，显式密码必须为 8–72 字节。简易模式可单独关闭启动时自动创建默认分组，也可选择是否启用 API Key 的 5h/1d/7d 消费窗口。
  • 备份可启用独立的月度归档与保留份数；关闭月度归档不会重写既有归档保留设置。运行日志可配置滚动保留；缩短期限前先确认审计和合规要求。
  • Caddy 或反向代理应让静态资源使用受控缓存，让 SSE/流式响应及时刷新，并避免对已经压缩或不适合压缩的响应重复压缩。

变更设置后至少验证：管理员页面保存与重新加载、受影响的公开设置、目标 API 路由、使用记录，以及渠道状态。