把多个上游模型供应商拧成一个 OpenAI 兼容端点。 SWRR 加权轮转、配额指数冷却、任务级会话亲和、影子留存观测—— 替你把失败截住，把账单砍下来。
先交代来历。这不是论文落地，是被免费池和账单逼出来的。
外国人开了个不限量的免费模型，中国人就去薅：注册一堆号，自己薅够了转手卖给别人薅， 薅到厂商受不了，免费就没了。
我干的是同一个路子，区别有两条：我免费教你怎么薅；而且我不白嫖——每个月拿一百多块养着场子， 商业通道、代金券、免费池混着走，该付的付掉，剩下的让免费池扛。 10 月这波实测，月 200 亿 token 的现金账单压到了 ¥170。
代价是毛病一堆。下面这些坑我全踩过，一个坑换回来一条规则，全记在运维语义表里。 山海关就是这么长出来的：把各路免费池、代金券和按量套餐拧成一个稳定的上游池。你接了三家模型上游做轮询，然后开始遇到这些事：
核心就一句话：让不靠谱的上游一起干靠谱的活。剩下的都是为这句话服务的。
权重、并发、超时逐后端可调。兜底后端与主力池隔离，互不污染。
403/429 指数退避 5m→10m→…→4h 封顶；满载排队 60s 而不是甩 503；客户端断连不吃冷却。
优先 X-Job-Id、退回 X-Session-Key，同一任务钉回同一后端。实测前缀缓存命中率 27% → 51%，峰值 69%。
某家专属的报错体/用量键写进独立包，内核零按名分支。没怪癖的上游零配置。
sk-user-* 额度核发 + 可插拔登录（注册表模式）+ 公版用户中心。
SQLite 单库存 attempts/captures，落库前自动脱敏，/api/stats 细粒度看板。
按后端名查每家的 5h/7d/30d 额度窗，sidecar 每 60s 判一次：窗打满就摘，回落后再开回来。加订阅不改任何映射表。
独立 Python 进程，纯标准库零依赖。按窗口增量失败率做限流/降级，与网关快路径分工。
多阶段构建、非 root 运行、自带 healthcheck，镜像内零密钥。
2026-10，生产环境实测。请连着数字一起读，文末有口径说明。
生产日耗 10 亿 Token 的场景下，靠路由平摊、缓存亲和（命中率 70%）和「多号代金券 + Free 赠送池」的滚动轮转：
| 通道 | 数量 | 月 Token 承载 | 月现金 |
|---|---|---|---|
| 火山订阅 | 4 个 | 80 亿 | 2 个现金付 ¥99.8，另 2 个由渠道券覆盖（还剩 10 元） |
| opencode Go | 2 个 | 12 亿（付费） | 收购半价 $5/个（≈¥70） |
| Free 赠送池 · credits 赚取 · 缓存读 | — | ~63% | ¥0 |
→ ¥170 买 200 亿 Token ≈ ¥0.85/亿。真正按全新 token 全额计价的只有 23%。 光靠代码（缓存亲和 + 免费档混编 + 按请求大小分流）能把按目录价付费的量压到 1/4~1/3。
只想有个能用的网关：Docker 三条命令，把 base_url 换掉就能跑。权重、冷却、亲和全部开箱默认，不用读架构章节。
# 克隆 + 准备真实配置（进挂载卷，不进 git） git clone https://github.com/ffseika0304/shanhai-gateway.git cd shanhai-gateway mkdir -p runtime/config runtime/data cp config/backends.example.json runtime/config/backends.json cp config/keys.example.json runtime/config/keys.json # 起容器（宿主侧默认 :18016） docker compose -f deploy/docker-compose.yml up -d --build # 冒烟 curl -s http://127.0.0.1:18016/health {"status":"ok","version":"0.5.1"}
make build # 等价于 go build -o shg ./cmd/shg cp config/backends.example.json config/backends.json # 凭据全假也能先跑 export LISTEN=":18006" export ROUTER_VALIDATE=0 # 跳过启动外网自检 ./shg & curl -s http://127.0.0.1:18006/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"model":"demo-model","messages":[{"role":"user","content":"hi"}]}' # 200 即通
{
"accounts": [
{ "name": "vendor-a",
"base_url": "https://api.example-llm.com/v1",
"api_keys": ["sk-xxxxx"] }
],
"backends": [
{
"name": "vendor-a-main",
"account": "vendor-a",
"model": "demo-model",
"base_url": "https://api.example-llm.com/v1",
"weight": 1,
"concurrency": 8,
"enabled": true,
"is_primary": true
}
]
}
LAN 口 POST /v1/chat/completions 不强制 key（免账通道）；下游 key 计费只在公网口/用户中心启用。
配置按 mtime 热加载，改权重、加后端不用重启。字段全集见 config/backends.example.json。
要把它钉进产线或者魔改路由，先读这里的「为什么」。每个魔法数字都有事故出处。
model_expire / model_fallback 打补丁。QUEUE_WAIT）再给答案，而不是直接扔 503。backends.blocked.json 是启动自检判定的「永久失效」清单，没有自动解除路径——自动复白会用失败率当证据，而黑名单的判断依据是探测事实。摘条目必须人工复核后从文件里删。X-Job-Id（任务级，正是前缀缓存的复用单元），退回 X-Session-Key。只有最终成功且内容已交付才写表，防失败会话钉死在坏后端；逐出/保持判定与冷却/熔断同源，不发明第二层健康层。if name==xxx 会把名字判定撒进内核，两条都是错路。「只在某家出现的问题」写进 internal/core/quirk/xxx.go，内核只在出口装饰 / 错误分类 / 用量解析三个固定缝上查表。怪癖是数据（配置字段），不是代码分支。attempts 表含 job_id 列（对已存在库幂等 ALTER 迁移）；/api/stats 提供同形 affinity{hits,misses,puts,pinned_jobs} 对象。按 job 归因的脚本迁移后原样可用。都是实际被问过的。
GATEWAY_CONFIG_DIR 必须包含 backends.json；docker 场景检查挂载卷 runtime/config/ 是否真的有文件（docker logs shg 看启动段解析了几个后端）。/api/stats 看三个字段：enabled（配置里被关）、cooldown_remain_s（配额类冷却中，最长 4h）、circuit_open。注意 circuit_open:false 不代表没冷却，两者是两套计数。fail_breakdown：大量 network 类失败多半是客户端断连风暴误伤（老版本语义），确认你在跑当前版本；如果是 401 集中爆发，是 key 失效，换 key 前冷却不会自己好。captures 表（先读仓库里的 captures 消费契约）。落库前已经过 scrub 脱敏（密钥/内网路径/手机号/Bearer 头 → [mask]），这是特性不是缺陷。docker logs shg 看退出原因；大概率是 runtime/config/ 缺文件或 JSON 不合法。healthcheck 连续失败会让编排层标记 unhealthy，但 restart: unless-stopped 只看进程退出。