无状态中转(relay)
不存任何状态、每个请求自带上游凭据的网关:一个提供商模板,订阅的访问令牌或 API Key 都可以
astra-server relay 用同一个二进制、同一个镜像,把 Astra 的网关换成无状态中转:只对接一个提供商模板,每个请求自己带上游凭据——订阅的访问令牌或提供商的 API Key——原样发给该模板的接口,不存储、不交换、不刷新、不写日志。
请求走的是和完整服务端同一条网关流水线:四种协议(OpenAI Chat、OpenAI Responses、Anthropic Messages、Gemini)、协议转换、流式输出、模板自带的请求头与模型处理都一样。没有的是:数据库、控制台、Astra 令牌、订阅账号、请求日志、插件、智能路由、隐私护栏。它不往磁盘写任何东西,请求之间也不共享状态,所以可以随意多开副本、放在负载均衡后面,或者部署到可以缩到零的 serverless 容器平台。
快速开始
不需要数据卷,也不需要管理员密码。在本机直接运行:
客户端的地址填 http://<主机>:17321/v1(Anthropic 客户端填 http://<主机>:17321),密钥填你自己的上游凭据。
能中转哪些模板
--provider 是提供商模板的 id(与控制台「添加提供商」里的模板相同):
ollama、lm-studio 这类不需要凭据的模板不能用于中转。订阅模板的客户端限制同样生效:claude-subscription 默认只服务 Claude Code。
凭据从请求头中读取,优先级:x-api-key > x-goog-api-key > Authorization: Bearer,只用选中的那一个,其余的凭据头会被忽略(例如同时发了 x-api-key 和 Authorization,只看 x-api-key)。被选中的那个必须是一个值、只含可见 ASCII 字符、不超过 4096 个字符,否则直接返回 401,不会退而使用下一个。
模板变体
模板目录里的变体代表同一服务的另一组主机,例如 moonshot 的 intl(国际站)、github-copilot-subscription 的 business / enterprise。
- 启动时
--variant <id>(或ASTRA_RELAY_VARIANT)设置默认变体; - 单个请求可以用请求头
x-astra-variant: <id>改用另一个变体,default表示模板自己的地址;不认识的变体返回 400。
凭据只会发往模板(或所选变体)自己的地址,或者启动时 --base-url 指定的地址,绝不会发往请求里给出的任何地址。
接口
生成类请求会先用请求的凭据获取模板的模型列表(按凭据的 SHA-256 缓存,默认 5 分钟),以列表中每个模型声明的接口决定直通还是转换协议。列表获取失败或格式不对时,请求直接失败,失败结果不会缓存。模板没有模型列表接口时,按模板的协议偏好处理。
原样转发的三个接口会带上调用方的查询参数,但不会带上调用方自己传的凭据参数(模板用查询参数认证时,凭据只由中转放入)。
没有的接口:控制台和 /api、Astra 令牌的自助查询、/v1/dashboard/billing/*、智能路由(请求虚拟模型 astra-auto 会直接返回 400)。
配置
参数优先于环境变量;中转不读取 ~/.astra 里的任何文件。
HTTP_PROXY / HTTPS_PROXY / NO_PROXY 对访问上游同样生效。
部署要点
- 健康检查:存活用
/healthz,就绪用/readyz。镜像自带的HEALTHCHECK(astra-server healthcheck)在/api/health返回 404 时会改查/readyz,所以中转容器同样会显示healthy。 - 长时间的流式请求:直通的流式响应里,上游在模型思考期间发出的 SSE 心跳会立即转给客户端,中间的代理不会因为连接空闲而断开;但平台本身的请求总时长上限仍然有效,部署前确认 ingress 的超时设置。
- 日志:只记每个请求的摘要(状态、协议)和内部错误,不记凭据和请求体。
- 错误:按入站协议的格式返回;原样转发的响应写到一半出错时直接断开连接,不会补一个看起来正常的结尾。