上游
「上游」这一节覆盖从接一个账号进来到它被网关正确调用的全过程。
三层模型
站点 site ──┬── 凭据 credential ──┬── 渠道 channel
│ └── 渠道 channel
└── 凭据 credential ───── 渠道 channel- 站点：上游服务商与其 base URL。
- 凭据：访问身份（API Key / Session Cookie / Access Token），加密入库。
- 渠道：真正被转发选中的对象，承载协议类型、端点规则、映射、超时、并发上限与专用代理。
细节见核心概念。
接入一个非标准上游的四条路
从最省事到最精细：
- 类型下拉直接带出正确的 base URL —— 选「智谱 GLM / 豆包 / 千帆 / …」会自动填好官方地址。
- 把完整端点粘进 base_url —— 保存时自动拆成根 + 端点覆盖，见基础 URL 与端点规则。
- 任意路径透传 —— 客户端直接打
/v1/<上游自己的路径>，渠道只填一个 base_url。 - 手写端点映射与字段搬运 —— 端点路径覆盖 / 映射 + 请求 / 响应体字段映射，共用同一套 JSON-path 语法。
协议类型从哪来
渠道的 type_hint（留空则取站点的 platform）决定用哪个适配器与哪份供应商 profile：
- 已收录的供应商会映射到规范类型（例如各 OpenAI 兼容品牌映射到
openai-compatible），并自动带上一份供应商 profile——非 OpenAI 供应商的映射是供应商的属性，不需要操作员维护。 custom是唯一「已知的未知」类型，表示「我自己接端点」，默认落到 OpenAI 形态的透传，是最诚实的默认。- 未收录的手工 id 会解析失败，这是刻意的：不让拼错的类型静默降级成 OpenAI。
保存时
ApplyProviderProfile只填空位：已经手写请求 / 响应映射的渠道完全不动。路径覆盖是这条规则的豁免项——「粘完整端点 URL」写的就是那个字段，属同一意图。
上游的健康与可达性
| 机制 | 做什么 | 花上游 token 吗 |
|---|---|---|
| 渠道健康清扫 | 定期探测渠道，评级 operational / degraded / error，状态跃迁时告警 | 是 |
| 账号探测 | 用站点账号接口校验凭据与密钥列表 | 否（走账号 API） |
| 站点探针 | 读站点自己公开的页面（Uptime Kuma 状态页、New-API 价格表） | 否，零 token |
站点探针是唯一「不花钱就能判断上游是不是挂了」的手段，详见站点探针。
出网策略
公网 HTTP(S) 上游无需任何例外；私网与特殊地址默认拒绝。可信内网服务要按最窄范围开例外：
dotenv
OUTBOUND_ALLOW_HOSTS=llm.internal.example
OUTBOUND_ALLOW_CIDRS=10.24.8.15/32- 主机例外是精确匹配，不含子域名。
- CIDR 例外只对匹配的解析后地址生效。
- 重定向目标与 DNS 应答在每次连接时都会重新检查。
- 环境变量代理被忽略：容器里的
HTTP_PROXY常指向宿主机，用它访问外网会connection refused。要用代理请在运行设置里配全局代理，或用渠道级proxy_url。
本节页面
| 页面 | 内容 |
|---|---|
| 基础 URL 与端点规则 | /v1 怎么加、完整端点怎么拆、透传白名单、实际打到哪 |
| 验证 OpenAI 兼容上游 | 最小配置、流式与工具调用验证、受控故障转移测试 |
| 站点探针 | 外部公开探针数据源、匹配与判定、自动禁用 |