OGX 网关优先(Gateway-First)架构解析:责任边界、信任边界与多租户隔离设计
OGX 网关优先(Gateway-First)架构解析:责任边界、信任边界与多租户隔离设计
OGX(Open GenAI Stack)是一个 OpenAI 兼容的 Agentic API 服务端,支持可插拔推理后端。本文基于仓库内的架构决策记录 ADR-0001: Gateway-First Architecture,深入剖析 OGX 在生产化多租户部署中如何与网关(Gateway)、服务网格(Service Mesh)划分职责,并展开讲解其信任边界不变量、中间件取舍,以及规划中的显式 tenant_id 租户隔离模型。读完本文,你将掌握 OGX 的授权体系边界、UpstreamHeaderAuthProvider 的用法与安全前提,以及从 ABAC 走向硬租户隔离的完整设计脉络。
背景:为什么 OGX 需要"网关优先"架构
OGX 面向生产级多租户部署演进时,首先要回答一个架构问题:OGX 自身负责什么,基础设施层(网关、服务网格、负载均衡器)负责什么?
在转向网关优先架构之前,OGX 的服务端内置了 TLS 终止、CORS、请求配额/限流、应用级认证与授权等中间件。但其中一部分能力与专用网关(Envoy、Solo、Kong 等)存在职责重叠——网关在 TLS、限流、CORS 等领域拥有更成熟的专用工具链与网络层可见性。
ADR-0001 的决策结论是:
OGX 采用网关优先架构。边缘(edge)关注点下沉到网关;资源授权与租户隔离保留在 OGX 内,因为它们依赖应用状态。
这一决策的直接结果是:网关负责"流量与身份入口"类问题,OGX 专注"资源语义与状态"类问题。
职责划分:网关处理什么,OGX 处理什么
网关(或服务网格)负责的边缘能力
- 边缘 TLS 终止:由 OGX 前置的网关或负载均衡器处理。OGX 仍保留服务端级别的 TLS 配置,用于东西向加密(网关与后端之间的 mTLS)以及无网关部署场景。
- 边缘限流与 IP 白名单:网关在网络层对客户端身份有更好的可见性,可用专用工具强制实施这些策略。
- CORS:浏览器端关注点,交给网关或 CDN 层处理。
- 熔断与负载均衡:属于服务网格或网关的基础设施级能力。
- 跨 OGX 实例的请求路由:由网关或服务网格承担。
- 生产环境认证(Authentication):网关向 IdP 校验令牌,并在转发给 OGX 之前注入身份头(
tenant_id、user_id、claims)。网关必须剥离客户端自带的所有身份头以防伪造。直接认证提供方(OAuth2、Kubernetes、自定义、GitHub)在开发与单租户部署中仍然支持——此时网关是可选组件。
OGX 保留的应用级能力
- 身份与租户提取:OGX 从认证结果中提取 principal、
tenant_id与用户属性。网关模式下来自UpstreamHeaderAuthProvider注入的头;直接认证模式下来自 JWT claims、Kubernetes 令牌或自定义认证响应。 - 资源授权(ABAC):OGX 将用户属性与资源级
access_attributes匹配,并校验资源所有权。覆盖模型、向量库、文件、Shield 与工具组。 - 已存储资源的租户隔离:有状态资源(对话、response items、文件、向量库条目、注册表条目)都打上
tenant_id与user_id标签,所有查询按租户上下文过滤。 - 语义化请求指标:网关无法产出的应用级指标(按 API 方法的延迟、按 API 的并发请求数)。
- 请求上下文传播:Provider 数据、测试上下文与客户端版本检查。
为什么资源授权不能迁移到网关
网关可以对令牌做校验、注入身份头,甚至看到请求体中的 "model": "llama3",但它无法回答需要查询 OGX 数据库才能回答的问题。考虑一个引用了模型、附件文件、用于检索的向量库以及历史对话的 POST /v1/responses 调用:
POST /v1/responses
Authorization: Bearer <token>
{
"model": "llama3",
"input": "Summarize the Q3 report",
"tools": [{"type": "file_search", "vector_store_ids": ["vs_abc123"]}],
"previous_response_id": "resp_xyz789"
}
网关无法验证:
vs_abc123是否属于该用户所在租户(OGX 存储中的归属关系);resp_xyz789是否是该用户拥有的对话;- 该向量库关联的文件对该用户是否可访问;
- 模型的
access_attributes是否与该用户的 claims 匹配。
这些校验都需要查询 OGX 的数据库。若网关要对每个请求中的每个资源引用都回查 OGX,就失去了网关存在的意义。因此 ABAC 与租户隔离必须留在应用层。
在源码层面,OGX 的 ABAC 评估逻辑位于 src/ogx/core/access_control/access_control.py 的 is_action_allowed:它对用户与资源构造限定标识符 f"{resource.type}::{resource.identifier}",按策略规则顺序匹配 permit/forbid 与 when/unless 条件;matches_resource 支持精确匹配、::* 通配与 regex: 前缀模式(access_control.py)。资源类型限定标识符(如 model::llama3、vector_store::vs_abc123)正是上例中"网关看得见字符串、却验证不了归属"的原因。
信任边界:三条硬性部署不变量
ADR 明确强调,以下是硬性部署不变量(hard deployment invariants),而非软性建议:
- 仅网关可达(Gateway-only reachability):使用
upstream_header认证时,客户端绝不能直连 OGX。UpstreamHeaderAuthProvider信任网关注入的头且不做校验,一旦客户端能直连 OGX,即可伪造身份头。必须用网络策略或防火墙规则强制这一点。 - 头部剥离(Header stripping):网关在转发前必须剥离客户端提供的身份头(principal、tenant、attribute 头)。否则客户端可注入任意身份 claims。
- 租户上下文只能来自认证解析(Tenant context is auth-resolved only):租户分区永远使用认证提供方从可信来源解析出的
tenant_id(网关头、JWT claims、认证端点响应),绝不能来自客户端可控的请求体字段、搜索过滤器或X-OGX-Provider-Data头。因为 passthrough provider 基础设施会把任意 provider-data 键向下游转发,这些命名空间必须严格隔离。
在代码中,UpstreamHeaderAuthProvider(src/ogx/core/server/auth_providers.py)的实现与这些不变量完全对应:
requires_http_bearer返回False,即它不校验任何令牌,只信任头部;- 它支持可选的
trusted_proxy_cidrs:配置后,每个请求的客户端 IP 都必须落在 CIDR 白名单内,否则抛出UntrustedProxyError(auth_providers.py)——这是对"仅网关可达"不变量在应用层的一层防御; - principal、tenant、attributes 全部从请求头读取,且对缺失的 principal 头直接拒绝。
中间件取舍:移除什么、保留什么
已移除的中间件
- QuotaMiddleware 与
QuotaConfig——限流交给网关; - CORSMiddleware 与
CORSConfig——CORS 交给网关。
服务端级 TLS 配置(ServerConfig 上的 tls_certfile、tls_keyfile、tls_cafile)予以保留,用于东西向加密与无网关部署;认证提供方用于出站连接的 TLS 字段也不受影响。
保留的中间件
| 中间件 | 职责 | 源码位置 |
|---|---|---|
AuthenticationMiddleware |
从令牌或网关注入的头提取身份 | src/ogx/core/server/auth.py |
RouteAuthorizationMiddleware |
强制执行路由级访问策略 | src/ogx/core/server/auth.py |
RequestMetricsMiddleware |
语义化 per-API 指标 | src/ogx/core/server/metrics.py |
ProviderDataMiddleware |
请求上下文传播 | src/ogx/core/server/server.py |
ClientVersionMiddleware |
协议兼容性检查 | src/ogx/core/server/server.py |
ZstdDecompressionMiddleware |
请求体解压 | src/ogx/core/server/server.py |
规划落地一:身份头契约(Identity Header Contract)
现状与痛点
IETF 没有"网关向后端传递已认证用户身份"的标准。RFC 7239 只覆盖网络层转发(IP、协议、host),不覆盖用户 claims。各网关各有自己的 JWT claims 提取与头部注入机制:
- Envoy Gateway:SecurityPolicy 的
claimToHeaders映射; - Istio:
RequestAuthentication+claim-to-header; - Envoy ext_authz:从认证响应取
allowed_upstream_headers; - Kong、Solo 等:类似的 claim-to-header 机制。
通用模式是:网关把每个 JWT claim 提取出来,映射为具名 HTTP 头,后端声明它期望哪些头。
ADR 记录当时的局限:UpstreamHeaderAuthProvider 只接受一个 principal_header(纯字符串)和一个可选的 attributes_header(JSON 编码的 dict)。JSON blob 的方式强迫网关把全部 claims 序列化进单个头值,而大多数网关的 claim-to-header 机制无法原生做到(它们是"一个 claim 一个头")。
规划方案:每属性头映射
替换单一 JSON attributes 头为每属性头映射,让每个用户属性拥有自己的头:
server:
auth:
provider_config:
type: upstream_header
principal_header: x-user-id
tenant_header: x-tenant-id
attribute_headers:
roles: x-user-roles
teams: x-user-teams
namespaces: x-user-namespaces
网关侧直接做 claim-to-header 映射:
# Envoy Gateway SecurityPolicy example
claimToHeaders:
- claim: sub
header: x-user-id
- claim: tenant
header: x-tenant-id
- claim: roles
header: x-user-roles
- claim: groups
header: x-user-teams
每个头值要么是单个字符串,要么是逗号分隔列表。OGX 将每个值归一化为 list[str](多值属性按逗号拆分),无需 JSON 编码。旧的 attributes_header(JSON blob)为向后兼容保留,但文档标记为已弃用。
实现现状:这一规划已落地到当前仓库。在 auth_providers.py 中,UpstreamHeaderAuthProvider.validate_token 会同时处理 attributes_header(JSON 解析并归一化为 list<a href="https://link.gitcode.com/i/75d9e85e2ea4672c94e6a4af333f63bc" target="_blank">str])与 attribute_headers(逐头读取,先尝试 JSON 解析、失败则按纯字符串处理,再归并进同一 attributes dict);tenant_header 的读取位于 [auth_providers.py,并经 _resolve_tenant_id 校验归一化。
规划落地二:租户隔离模型(Tenant Isolation Model)
为什么 ABAC 单独不能作为租户边界
ADR 明确指出:多租户隔离在文档编写时尚不存在,当时的系统只有 ABAC(access_attributes 匹配)与资源所有权(owner_principal),没有租户作用域。
默认 ABAC 策略是:owner OR 任意重叠属性类别 OR 无主资源(见 src/ogx/core/access_control/access_control.py 的 default_policy,即"user in owners teams: ["engineering"]),彼此的数据就会互相可见。把 ABAC 属性当作隐式租户边界,无法提供硬隔离保证。
设计:显式 tenant_id 作为分区键
把 tenant_id 视作 Kubernetes namespace 一样的存在:它是硬分区键,而非又一个属性。ABAC 只在租户内部做细粒度共享。每个请求有且只有一个活跃租户。
租户解析与认证提供方无关——每个认证提供方都能解析租户:
| Auth provider | Tenant source |
|---|---|
upstream_header |
专用 tenant_header |
oauth2_token |
JWT claim(如 tenant 或 org),通过 tenant_claim 配置 |
kubernetes |
Namespace 或 service account annotation |
custom |
认证端点响应字段(tenant_field) |
github_token |
组织(Organization) |
| None(开发模式) | server config 中的 default_tenant_id |
实现现状:以上表格内容已全部落地于 src/ogx/core/server/auth_providers.py:
OAuth2TokenAuthProvider:JWT 与 introspection 两条路径均支持tenant_claim(auth_providers.py 与 auth_providers.py);CustomAuthProvider:通过tenant_field从认证端点响应读取(auth_providers.py);KubernetesAuthProvider:通过tenant_claim从 SelfSubjectReview 的 userInfo 中解析(auth_providers.py);UpstreamHeaderAuthProvider:tenant_header(见上文)。
tenant_id 的格式校验集中在 _validate_tenant_id(src/ogx/core/datatypes.py),要求匹配 [a-z0-9][a-z0-9-_]{0,127}。
租户模式(Tenancy Modes)
disabled(默认,即当前行为)——不做租户强制。现有单租户与纯 ABAC 部署完全不受影响。single——所有资源归属一个配置好的租户。适用于单租户生产或开发模式:在配置中设置default_tenant_id并注入每个请求,无需网关。multi——完整租户隔离。每个请求都必须解析出tenant_id,租户作用域路由上缺少租户的请求被拒绝。
实现现状:TenancyMode 枚举与 TenancyConfig 已在 src/ogx/core/datatypes.py 实现,TenancyConfig.mode 默认 disabled,并带有校验逻辑:single 模式必须配置 default_tenant_id;default_tenant_id 非空时必须通过 _validate_tenant_id 校验。它挂载在 ServerConfig.tenancy 字段下(datatypes.py)。
请求上下文扩展
认证结果需要把 tenant_id 提升为一等字段,与 principal、attributes 并列,并随请求上下文(request_headers.py、task.py)传播到后台任务。
# Conceptual — extend User or create a new type
class User(BaseModel):
principal: str
tenant_id: str | None = None
attributes: dict[str, list[str]] | None = None
实现现状:User 模型在 src/ogx/core/datatypes.py 中正是这个结构——tenant_id 已是 User 的一等字段,所有 auth provider 返回的 User 都带 tenant_id。同时 src/ogx/core/access_control/conditions.py 的 has_tenant_scope_mismatch 已经实现了"资源 owner 与当前用户 tenant_id 不一致即判定租户越界"的检查,并在 is_action_allowed 中于 ABAC 策略求值之前执行(access_control.py),这正是"tenant_id 先于 ABAC 应用"的代码形态。
存储层强制
tenant_id 在 ABAC 之前 应用,查询路径变为两步:
- 按
tenant_id = current_tenant过滤(硬分区); - 再应用 ABAC:owner OR 匹配属性(租户内共享)。
SQL 存储:
- 给每张租户作用域表增加
tenant_id列; AuthorizedSqlStore在 ABAC 过滤前先加WHERE tenant_id = ?;- PostgreSQL 上启用行级安全(RLS)作为应用层过滤之后的纵深防御。
KV 存储:
- 增加
TenantScopedKVStore包装器,键前缀加tenant_id; - 适用于向量库元数据/chunks/文件批次(
OpenAIVectorStoreMixin)、Agent 状态持久化,以及任何尚未迁移到 SQL 的 KV 面。
文件存储:
- 物理/对象存储路径按租户分区,而不仅是元数据。
全局目录 vs 租户状态
资源注册表拆分为两层:
- 全局目录(Global catalog):provider 列出的模型与 distro 定义的共享资源(
source: listed_from_provider)。进程级缓存,对所有租户可见。 - 租户注册表(Tenant registry):用户创建的资源(
source: via_register_api)。仅限创建租户可见,按请求查询当前租户,不预载入全局缓存。
当前 DistributionRegistry 是单一全局 KV 键空间并带进程级缓存;多租户模式下,租户创建的条目绝不能全局缓存,否则会把资源存在性泄漏给其他租户。RegistryEntrySource 枚举(via_register_api / listed_from_provider)已在 src/ogx/core/datatypes.py 落地,ResourceWithOwner 及各类 *WithOwner 资源(datatypes.py)为全局/租户分层提供了数据模型基础。
需要租户分区的存储面
SQL 存储(经 AuthorizedSqlStore):
- 对话(
openai_conversations表) - 对话消息(
conversation_messages表) - Response 对象与 response items
- 文件元数据
- Prompts(从 KV 迁移到 SQL 之后)
- Connectors(从 KV 迁移到 SQL 之后)
- Batches(从 KV 迁移到 SQL 之后)
KV 存储:
- 分布注册表(
registry.py中的DistributionRegistry) - 向量库元数据、文件元数据、chunks、文件批次(
OpenAIVectorStoreMixin键空间) - Agent 状态持久化(inline responses provider)
跨租户访问
跨租户管理访问不能通过重叠属性实现(那会破坏隔离边界)。替代方案:
- 显式租户切换:管理员先认证,再通过平台角色(如
platform_admin)选择目标租户; - 所有跨租户操作记录审计日志;
- 使用不透明的稳定租户 ID,而非人类可读名称。
迁移策略:五个阶段
Phase 1:租户上下文与配置。 增加租户模式配置(disabled / single / multi)、所有认证提供方的租户解析、请求上下文中的 tenant_id。现有部署默认 disabled,完全不受影响。
Phase 2:SQL 租户列。 给对话、responses、文件元数据表加 tenant_id(这些已通过 AuthorizedSqlStore 集中管理)。回填存量行:single 模式回填到配置的默认租户;multi 模式要求运维提供映射。禁止从 ABAC 属性自动推断租户。
Phase 3:Prompts、connectors、batches。 在租户感知存储之上完成 KV 到 SQL 的迁移(与 PR #5614 的方向一致),这些资源从开始就带 tenant_id 进入 AuthorizedSqlStore。
Phase 4:注册表与 KV 面。 把分布注册表拆分为全局与租户两半;为剩余 KV 面(向量库元数据、Agent 状态)增加 TenantScopedKVStore;停止把租户创建的状态预载入进程级缓存。
Phase 5:加固。 启用 PostgreSQL RLS 作为纵深防御;增加租户作用域的审计日志;对新建部署移除 disabled 租户模式。
回填规则:
- 现有
owner_principal为空的行当前按公开处理;启用租户隔离后,未打标签的行对任何租户都不可访问(默认拒绝); - 迁移必须在切换到
single或multi模式之前为存量行打上tenant_id; - 在启用租户隔离的情况下,不允许混合存在已打标签与未打标签的行。
总结
网关优先架构为 OGX 划定了一条清晰的职责线:网络边缘归网关,应用语义归 OGX。网关负责 TLS、限流、CORS、路由与生产认证;OGX 负责身份提取、ABAC 资源授权、租户隔离与语义化指标。信任边界的三条不变量(仅网关可达、头部剥离、租户上下文仅由认证解析)是部署时不可妥协的前提。
同时,ADR 中"规划中"的两大方向在后续演进中已大量落地为可运行的实现:UpstreamHeaderAuthProvider 已支持 tenant_header 与每属性头 attribute_headers;TenancyConfig/TenancyMode(disabled/single/multi)、各认证提供方的 tenant_claim/tenant_field 解析、User.tenant_id 一等字段以及"租户越界即拒绝"的 has_tenant_scope_mismatch 检查均已出现在当前代码库中。对于正在规划多租户生产部署的团队,这份 ADR 连同上述源码,是一份从责任边界到迁移路径都可直接引用的架构蓝本。
想要继续深入,可以阅读仓库内的 ARCHITECTURE.md、多租户能力说明博客 以及 access_control 模块测试 与 多租户评估测试 来对照验证本文所述行为。