OGX 网关优先(Gateway-First)架构解析:责任边界、信任边界与多租户隔离设计

原创2026-09-15 19:17:041,955 阅读
文章标签:AI应用API网关后端模型推理服务

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),而非软性建议:

  1. 仅网关可达(Gateway-only reachability):使用 upstream_header 认证时,客户端绝不能直连 OGX。UpstreamHeaderAuthProvider 信任网关注入的头且不做校验,一旦客户端能直连 OGX,即可伪造身份头。必须用网络策略或防火墙规则强制这一点。
  2. 头部剥离(Header stripping):网关在转发前必须剥离客户端提供的身份头(principal、tenant、attribute 头)。否则客户端可注入任意身份 claims。
  3. 租户上下文只能来自认证解析(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 / user is owner / resource is unowned")。这是一种共享机制,而非隔离边界:若两个租户碰巧共享某个属性值(如都有 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 之前 应用,查询路径变为两步:

  1. 按 tenant_id = current_tenant 过滤(硬分区);
  2. 再应用 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 模块测试 与 多租户评估测试 来对照验证本文所述行为。

登录后查看全文
ogx