返回资讯中心
外部精选
软件工程
#开发者实时流

开发者发布 ShanHaiGateway:用 Go 编写的多上游 LLM 网关

来源标题:Show HN: ShanHaiGateway – multi-upstream LLM gateway in Go

开发者推出开源项目 ShanHaiGateway,将多个 LLM 供应商整合为 OpenAI 兼容端点。该项目采用 SWRR 加权轮转、配额指数冷却和任务级亲和,Docker 部署约三分钟即可上线。作者称在生产环境月消耗 200 亿 token 时,现金账单约为 170 元。

Hacker News 最新ffseika03042026/11/12 · 5 天前26 分钟阅读

以下正文同步自 Hacker News 最新,版权归原站所有,已转换为易读排版。

把多个上游模型供应商组织成一个 OpenAI 兼容端点

SWRR 加权轮转 · 配额指数冷却 · 任务级亲和 · 影子留存观测 · Docker 三分钟上产线

外国人开了个不限量的免费模型,中国人就去薅:注册一堆号,自己薅够了转手卖给别人薅,薅到厂商受不了,免费就没了。

我干的是同一个路子,区别有两条:我免费教你怎么薅;而且我不白嫖,每个月拿一百多块养着场子,商业通道、代金券、免费池混着走,该付的付掉,剩下的让免费池扛。10 月这波实测,月 200 亿 token 的现金账单压到了 ¥170。

山海关就是这么长出来的网关:把各路免费池、代金券和按量套餐拧成一个稳定的上游池,替你把失败截住,把账单砍下来。

上面每一条都对应运维语义表里的一条规则。每条规则都是一次真实事故换来的,不是论文里的理论模型。

SWRR 加权轮转 + 兜底链隔离:权重/并发/超时逐后端可调,兜底后端与主力池隔离,不互相污染

错误分类学驱动的冷却:403/429 指数退避 5m→10m→…→4h 封顶;满载排队 60s 而不是甩 503;客户端断连不吃冷却

任务级会话亲和:优先 X-Job-Id、退回 X-Session-Key,同一任务钉回同一后端,前缀缓存的复用单元接上了(实测命中率 27% → 51%,峰值 69%)

quirk 怪癖层:某家专属的报错体/用量键/出口定制写进独立包,内核零按名分支,没怪癖的上游零配置

多用户下游 key 计费:sk-user-* 额度核发 + 可插拔登录(注册表模式)+ 公版用户中心

影子留存观测:SQLite 单库 attempts/captures(落库前自动脱敏),/api/stats 细粒度看板

配置热加载:backends.json 按 mtime 热加载,改权重/加后端不重启

sidecar 慢周期自愈:独立 Python 进程(零第三方依赖),按窗口增量失败率做限流/降级决策,与网关快路径分工

额度窗探针 + 自动摘除:scripts/quota_probe.py 按后端名查每家的 5h/7d/30d 额度窗,每 180s 把快照写进 quota.json;sidecar 每 60s 判一次,窗打满就摘掉这个后端,回落到阈值下再开回来。每个订阅独立计量,加订阅不用改任何映射表

Docker 一把梭:多阶段构建、纯 Go SQLite(零 CGO)、非 root 运行、healthcheck、镜像内零密钥

实测规模与账单(2026-10,生产环境实测)

有人在生产里用它跑月 200 亿 Token,现金账单 ≈ ¥170/月。同一批 Token 若按各家的目录价全量付费,约 $3,800/月(≈ ¥26,600)。

本网关的核心能力之一,是把极不稳定的免费/赠送额度混进高可用主力池。它不区分主力与打杂,完全随机地发。结果是:

免费池的 429 与假死被熔断、600 秒双向超时和失败归类彻底隔离。免费池频繁报错,主业务的上游 429 依然为 0。

为什么免费池塌了不影响主业务:网关和调用方都是 600 秒兜底,两端的"切断"最后都落到换一条道重发。上游主动切断,那条道进冷却,调用方的重试自动落到别的道;网关自己先超时,它内部就换道重发,调用方几乎无感。

再挂一个订阅账号,就多一份免费池:每个 Go 订阅都自带一个 Free 模型池,所以付费占比会持续走低(实测 43.6% → 再挂一个 → ~37%),总吞吐同步扩容。账单取决于哪条通道便宜,跟用了多少 token 关系不大。厂商只是配置里可换的路由项,别当成架构假设。

在生产日耗 10 亿 Token 的场景下,靠路由平摊、缓存亲和(命中率 70%)和"多号代金券 + Free 赠送池"的滚动轮转,月度实际现金支出 ≈ ¥170:

→ ¥170 买 200 亿 Token ≈ ¥0.85 / 亿;真正按全新 token 全额计价的只有 23%。同量按目录价全付 ≈ $3,800/月。光靠代码(缓存亲和 + 免费档混编)加上池子配置层的按请求大小分流,能把按目录价付费的量压到 1/4~1/3,叠加渠道策略后总降本 99%。

能力 做什么 为什么这是架构而不是配置技巧

内部会话亲和 同一任务(X-Job-Id,退回 X-Session-Key)的每一轮钉回同一条道 轮询把第二轮甩给别家,前缀缓存就废了。实测散装轮转下同前缀簇命中率 51~56%,恰好等于池内抽取概率,轮询就是天花板;钉回去后实测 27%→51%、峰值 69%

外部会话头透传 按后端配 session_header(如 x-opencode-session),把会话值写进厂商自己的头 有些厂商的缓存是认自家头的:不配这个字段,厂商侧永远不命中。配字段即可,不用改代码(attempt.go 一行)

怪癖层 某家专属的报错体 / 用量键 / 出口定制,写进独立包(core/quirk),内核零按名分支 没怪癖的上游零配置;有怪癖的只改一个文件。默认行为 = 通用行为,不接 quirk 层与不接它的上游逐位一致

每个订阅独立计量 + 额度窗自动摘除 探针按后端名分组查每家的 5h/7d/30d 额度窗、每 180s 写一份 quota.json 快照;sidecar 每 60s 判一次:窗打满就摘掉这个后端,回落到阈值下再开回来 加一个订阅不用改任何映射表。到期换订阅是"禁一个、开一个"的轮转,周期错开即可保证每个都被烧干净、并发不塌

按请求大小分流(池子配置层,不在内核) 小请求走按 Token 池、大请求走按次池(22,222 Token 平衡点) 两种计费制的单位成本不同,按体量选池比随机发便宜得多,实测省 35%。这一条靠权重与多后端配置实现,网关内核只管把它们各自发稳

免费/低档通道混编 Free 赠送池与商业通道同池轮转 免费额度最不稳,但只要它塌了不影响主业务(见上),就有资格当正规军

接一个订阅两步,其余全自动。① accounts[] 加一条:唯一名字 + api_keys[](调用用)+ 配额查询凭据(AK/SK,随部署配置下发;缺了看板报「缺凭据」、不动作,绝不借别人的凭据);② backends[] 加一条后端,base_url 指该家的套餐端点、account 指上面那条。30s 内热加载上线,探针按后端名开始查它的额度窗,sidecar 开始自动管它的"打满就摘、回落就开"。到期换订阅:新建账号+后端、把旧的禁掉即可(周期错开,每个都能烧干净)。

声明,请连着数字一起读。 ① 活动期价格有保质期:券与半价随时会退,回归常态约 ¥340/月,降本仍 98%+。 ② "免费/低档承接 63%"随上游给量与赚取速率波动(实测区间 37%57%,把缓存读计入则更高),不承诺具体额度。 ③ 免费/赠送额度是上游给的,不是本项目给的。本项目永久开源的是缓存亲和、换道重试、每个订阅独立计量额度并自动摘除。 ④ 数字为 2026-10 单机生产实测(日耗 4.413 亿 Token),口径与上表一致,测量方法见随版本发布的标定记录。 ⑤ 不锁死任何厂商:主力池占比三天内在 11%↔43% 之间摆动(换的是配置里的账号与权重),路由 / 缓存亲和 / 兜底逻辑一行没改。

你只想有个能用的网关:Docker 三条命令起一个 OpenAI 兼容端点,把 base_url 换掉就能跑。权重、冷却、亲和全部开箱默认,不用读架构章节。

你要把它钉进产线,或者魔改路由:架构图、包职责表、八条运维规则、怪癖层接口、captures 消费契约都在下面。每个魔法数字为什么是这个值,都有事故出处。

Docker(推荐)

git clone https://github.com/ffseika0304/shanhai-gateway.git && cd shanhai-gateway

1. 准备真实配置(进挂载卷,不进 git)

mkdir -p runtime/config runtime/data cp config/backends.example.json runtime/config/backends.json # 改成你的后端 cp config/keys.example.json runtime/config/keys.json # 改成你的下游 key

2. 起容器(宿主侧默认 :18016,SHG_PORT 可覆盖)

docker compose -f deploy/docker-compose.yml up -d --build

3. 冒烟

curl -s http://127.0.0.1:18016/health # {"status":"ok","version":"0.5.1"} curl -s http://127.0.0.1:18016/api/stats | head -c 400

裸跑二进制

要求 Go ≥ 1.27:

make build # 等价于 go build -o shg ./cmd/shg

cp config/backends.example.json config/backends.json # 改字段,凭据全假也能先跑 export LISTEN=":18006" # LAN 免账口 export ROUTER_VALIDATE=0 # 跳过启动外网自检(配真 key 时删掉)

./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 即通。健康检查 GET /health;流量看板 GET /api/stats

LAN 口 POST /v1/chat/completions 不强制 key(免账通道);下游 key 计费只在公网口/用户中心启用。

裸跑 Docker

配置 <repo>/config/(真实文件 gitignored) ./runtime/config/ → 挂载 /etc/shg

数据/日志 ~/.local/share/shg/ ./runtime/data/ → 挂载 /var/lib/shg

身份 shg/0.5.1(UA / /healthz / 日志前缀) 同左

配置热加载 mtime 生效,无需重启 mtime 生效,无需重启容器

架构

依赖方向单向:api → service → core;config / runtime 是横向投喂层。

┌─────────────────────────────────────────────────────┐ │ cmd/shg —— 只装配 │ │ env → 路径 → 目录 → SQLite → 两个 listener │ └───────────────────────────┬─────────────────────────┘ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ internal/api 控制面 HTTP 门:LAN(免账) / public(dashGate+key) │ │ usercenter / admin / dashboard / dashgate / public 各门 │ └──────────────┬──────────────────────────────┬───────────────────┘ ▼ │ ┌─────────────────────────────────────────────┼───────────────────┐ │ internal/service 数据面 + 控制面业务 │ │ │ routing(加权轮转/兜底) proxy(代理主流程) │ │ │ auth(可插拔登录) apikey(下游 key 计费) │ │ └──────────────┬──────────────────────────────┼───────────────────┘ ▼ │ ┌─────────────────────────────────────────────┼───────────────────┐ │ internal/core errclass(返回码分类学) │ │ │ upstream(容量/健康状态机) store(SQLite)│ │ └──────────────┬───────────────────────────────┼───────────────────┘ │ 横向投喂(这两层互不依赖、也不依赖 service)│ ┌──────────────┼───────────────────────────┬───┴───────────────┐ │ internal/config backends.json 的 加载/校验/mtime 热加载/自检黑名单 │ │ internal/runtime 身份/路径/env/日志轮转/清扫/SQLite 保养 │ └─────────────────────────────────────────────────────────────────┘

每个包为什么独立划出来,因为不同的维护者会在不同的时间、因为不同的理由动它:

backends.json 最省版(凭据全假,字段全集见 config/backends.example.json):

{ "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 } ] }

环境变量

环境变量 覆盖的路径/行为 默认

GATEWAY_DATA_DIR 数据根 ~/.local/share/shg

GATEWAY_CONFIG_DIR 配置目录 <repo>/config

GATEWAY_DB_FILE SQLite 主库 <dataDir>/shg.db

GATEWAY_BACKENDS_FILE 后端基线文件 <configDir>/backends.json

GATEWAY_KEYS_FILE 下游 key 总账 <configDir>/keys.json

GATEWAY_QUOTA_FILE 配额快照 <dataDir>/quota.json

ROUTER_BACKENDS 直接注入 JSON 配置(优先级高于文件) —

ROUTER_VALIDATE 0 时跳过启动自检 1

LISTEN / LISTEN_PUBLIC LAN 免账口 / 公网口 :18006 / 不监听

SESSION_AFFINITY off 关闭会话亲和(行为与未接亲和逐位一致);AFFINITY_TTL/AFFINITY_MAX/AFFINITY_CONTENTION_LIMIT 分别是条目生存期 / LRU 容量 / 满载滞回迁移阈值 on / 6h / 8192 / 3

REASONING_EFFORT 思考模型统一压低推理预算:客户端没显式指定 reasoning_effort 时注入默认值(显式指定则尊重、不覆盖);空串 = 不注入。前置链路(另一层网关/路由器)已注入时,守卫命中"已有"会跳过,串联不双注入 low

env 前缀是 GATEWAY_* 而不是 SHG_*:sidecar 契约(py/sidecar.py 读 GATEWAY_BACKENDS_FILE / GATEWAY_QUOTA_FILE)锚在这组名字上,改名收益为零、迁移风险为正。身份在 internal/runtime/identity.go 的 AppName("shg"),不在 env 前缀。

backends.blocked.json 没有独立 env:它与 backends.json 绑在同一目录,必须一起搬走。

沿革说明:表中 SLR 指本项目早期自研的前置路由器(seika_llm_router),已被本网关整体替代;相关条目作为语义沿革保留。

默认就是通用行为,没怪癖的上游零配置:quirk.Get("")(后端没配 driver)和未注册的 driver 名都回落到包级 OpenAI 单例,行为与不接怪癖层逐位一致。注册表是按名查表 + RWMutex,内核零按名分支。怪癖是数据(配置字段),不是代码分支。

举三个真实形态的例子:某家只回中文欠费文案(缝② 认领那几句 → 拉黑它的 403);某家的"模型下架"报错体是自造词(缝② 认领 → 计入 fail_streak、连续失败自动熔断);某家的缓存用量键叫 prompt_cache_hit_tokens 而不是 cached_tokens(缝③ 解析 → 缓存价计费不掉成 0)。默认发行版不实现任何具体怪癖,纯接口预留,落点先立住。

captures 是留存快照(旁路,与 attempts 用 rid 关联)。消费方判定一条留存只用下面四条,这四条是从真流量数据里逼出来的契约:

一句话记忆:可用性看 usable,内容有无看 partial_ratio,截断看 truncated,去重看 #4 的排序规则。status 只在有实义 HTTP 码时参考(partial 中途断是 200,别用 status 当完成判据)。

生产单元 slr-router.service 占用 18006(LAN)/18012(公网口) 与 dataDir shadow-data/。 任何手工 ./slr 都会抢走这两个口 ⇒ systemd 的实例 bind 失败 → 崩溃循环 → 看板全天时好时坏 (2026-10-21 事故:另一个 agent 越级手工起了 ./slr,见运维语义规则 9)。

LISTEN=:28006 LISTEN_PUBLIC=:28012
GATEWAY_DATA_DIR=/tmp/slr-dev/data
GATEWAY_CONFIG_DIR=/tmp/slr-dev/config
GATEWAY_DB_FILE=/tmp/slr-dev/data/slr-dev.db
ROUTER_VALIDATE=0
./slr

/tmp/slr-dev/config/backends.json 用假凭据即可(sk-xxxxx);需要真凭据时从 shadow-config/backends.json 复制过去,别让 dev 实例指向生产目录。

dashboard 导航里的「WorkBuddy Panel」是独立项目,不属于本仓库:

网关起不来,报"没有后端配置"

env 指错目录。GATEWAY_CONFIG_DIR 必须包含 backends.json;docker 场景检查挂载卷 runtime/config/ 是否真的有文件(docker logs shg 看启动段解析了几个后端)。

GET /api/stats 看三个字段:enabled(配置里被关)、cooldown_remain_s(配额类冷却中,指数退避最长 4h)、circuit_open。注意 circuit_open:false 不代表没冷却,冷却看 cooldown_remain_s,两者是两套计数。

这正是规则 #1 要防的形态。检查 fail_breakdown:如果大量 network 类失败,多半是客户端断连风暴误伤(老版本语义),确认你在跑本仓库当前版本;如果是 401 集中爆发,是 key 失效,换 key 前冷却不会自己好。

查 SQLite captures 表(先读上面的 captures 消费契约)。落库前已经过 scrub 脱敏(密钥/内网路径/手机号/Bearer 头 → [mask]),这是特性不是缺陷。

docker logs shg 看退出原因;大概率是 runtime/config/ 缺文件或 JSON 不合法。healthcheck 连续失败也会让编排层标记 unhealthy,但 restart: unless-stopped 只看进程退出。

shanhai-gateway/ ├── cmd/shg/ # main 装配 + 优雅关闭(全项目唯一入口) ├── internal/ │ ├── api/ # 控制面 HTTP 门与看板 │ ├── service/ │ │ ├── routing/ # 加权轮转 / 候选 / 兜底 / 原子换装 │ │ ├── proxy/ # 数据面代理主流程 │ │ ├── affinity/ # 任务/会话亲和表 │ │ ├── auth/ # 登录抽象 + providers/ │ │ └── apikey/ # 下游 key 计费 │ ├── core/ │ │ ├── errclass/ # 错误分类唯一真源 + 词表 │ │ ├── quirk/ # 上游怪癖层(接口预留 + OpenAI 基准) │ │ ├── upstream/ # 后端容量/健康状态机 │ │ └── store/ # SQLite 单库 + 单写入口 │ ├── config/ # 配置加载 / 校验 / 黑名单 / 热加载 │ └── runtime/ # 身份 / 路径 / 轮转 / 清扫 / 保养 ├── web/dashboard, web/console # 运维看板 / 用户中心(go:embed 进二进制) ├── py/sidecar.py # 配额守护(独立 Python 进程,纯标准库) ├── scripts/ # quota_probe.py 额度窗采集探针(180s 快照写 quota.json) ├── config/ # 只有 *.example.json 模板;真实配置 gitignored ├── deploy/ # Dockerfile + docker-compose.yml ├── API_CONTRACT.md # api.seika.ltd 接口契约 ├── Makefile # build / test / fmt / vet / docker └── README.md

本地开发

gofmt -l internal/ cmd/ web/ # 必须为空 go vet ./... go test ./... -race -count=1 # 基线:12 个包全绿 make build

不撞真上游的开发方法:全部走假凭据 sk-xxxxx。请求会在上游网络错误/401 处失败,正好顺序踩到错误分类、指数冷却、兜底摘除这些真实路径;单元测试已把路由/熔断/统计逐条表驱动钉死。要跑不外发流量的 e2e,用 ROUTER_BACKENDS 直接注入一份指向 loopback 测试 HTTP 服务的假上游配置,配合 ROUTER_VALIDATE=0。

sidecar 依赖说明:见 py/requirements.txt,只有 Python 标准库,无 pip 安装项。

ShanHaiGateway 是自托管工具,怎么部署、怎么配凭据,决定权完全在你:

欢迎提 Issue 和 Pull Request。改路由语义/冷却参数之前,请先读运维语义。每条规则背后都有一次真实事故,别让下一代流量把学费再交一遍。

modernc.org/sqlite - 纯 Go SQLite,让镜像零 CGO

rs/cors - CORS 中间件

workbuddy2api 及其增强分支 - WorkBuddy 账号池生态(见周边服务)

有用的话点个 Star。

正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。

打开原文
去社区讨论 →