模型网关

PUT 替换路由配置；PATCH 仅修改 name / description。具体可用状态读取 ready / conditions，不能仅依赖创建成功。

方法	路径（产品接口统一前缀 /api/v1）	功能
GET	/routes	查询网关路由
POST	/routes	创建网关路由
PATCH	/routes/{id}	更新网关路由显示信息
GET	/routes/{id}	获取网关路由详情
PUT	/routes/{id}	替换网关路由配置
DELETE	/routes/{id}	删除网关路由
GET	/service-backends	查询可选路由后端
GET	/routes/filter-options	查询路由筛选项

查询网关路由

功能介绍

查询网关路由。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/routes

查询参数

参数	类型	必选	描述
page	integer	否	页码，从 1 开始
page_size	integer	否	每页数量；建议显式传入，例如 20；省略时部分列表返回全部
name	string	否	显示名称
hostname	string	否	筛选参数 hostname
model	string	否	对外模型名称
backend	string	否	后端资源标识
status	string	否	资源状态；具体取值见业务规则
domain_id	string	否	筛选参数 domain_id
project_id	string	否	筛选参数 project_id
ids	string	否	逗号分隔的路由 ID；按指定资源集合筛选
sort	string	否	排序表达式
sort_field	string	否	筛选参数 sort_field
sort_order	string	否	筛选参数 sort_order
created_from	string	否	创建时间下界，RFC3339，可只指定一端
created_to	string	否	创建时间上界，RFC3339，可只指定一端

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array<route.response>	结果列表
total	integer	匹配总数
page	integer	页码，从 1 开始
page_size	integer	每页数量

请求示例

GET https://{endpoint}/api/v1/routes?page=1&page_size=20
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "items": [
    {
      "id": "id-example",
      "name": "示例资源",
      "description": "",
      "status": "ready",
      "projectId": "projectId-example",
      "ownerUserId": "ownerUserId-example",
      "backend": {
        "catalog": "",
        "type": "",
        "id": "id-example"
      },
      "spec": {},
      "createdAt": "2026-09-21T00:00:00Z",
      "updatedAt": "2026-09-21T00:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 1
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
500	internal_error	failed to list routes
401	unauthorized	authentication required
400	invalid_request	详细原因由 message 返回。

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

创建网关路由

功能介绍

创建网关路由。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

POST /api/v1/routes

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string	是	显示名称
description	string	否	描述
namespace	string	否	Kubernetes 命名空间
models	array<route.ModelRoute>	条件必选	使用多模型映射时必选，至少一项；每项须包含 model 和非空 backendRefs。
model	string	条件必选	未提供 models、使用单模型兼容格式时必选。
subdomains	array	条件必选	使用平台根域名时必选，与完整 hostnames 二选一。
hostnames	array	条件必选	直接指定完整域名时必选，与 subdomains 二选一。
backendRefs	array<route.BackendRef>	条件必选	未提供 models 时，与顶层 model 一起提供，至少一个有效后端。
ipAllow	array	条件必选	启用 IP 白名单时须提供非空有效 CIDR 列表；否则可省略或为空。
ipDeny	array	条件必选	启用 IP 黑名单时须提供非空有效 CIDR 列表；否则可省略或为空。
labels	map<string, string>	否	标签键值对

参数	参数类型	是否必选	描述
models[].model	string	是	对外模型名，不可为空且在该路由内不可重复。
models[].backendRefs	array	是	该模型的后端列表，至少一项。
models[].backendRefs[].name	string	是	关联服务名称。
models[].backendRefs[].priority	integer	是	后端优先级，0 至 100 的整数。
models[].backendRefs[].weight	integer	是	后端权重，1 至 100 的整数。
models[].backendRefs[].modelNameOverride	string	是	发送给后端的模型名称，不能为空。

嵌套表适用于 models 中的每个映射；单模型兼容格式的 backendRefs 子字段遵循相同约束。IP 白名单和黑名单按所选模式配置。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
status	string	资源状态；具体取值见业务规则
projectId	string	所属项目 ID
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
backend	route.backendRef	后端资源标识
spec	route.Spec	资源配置快照
ready	string	是否就绪；空值时可能省略
conditions	array<route.Condition>	后端状态条件；空值时可能省略
labels	map<string, string>	标签键值对；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

POST https://{endpoint}/api/v1/routes
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "name": "示例路由",
  "models": [
    {
      "model": "demo-model",
      "backendRefs": [
        {
          "name": "prov-backend",
          "priority": 0,
          "weight": 1,
          "modelNameOverride": "backend-model"
        }
      ]
    }
  ],
  "subdomains": [
    "demo"
  ]
}

正常响应示例

HTTP/1.1 201
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "description": "",
  "status": "ready",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "backend": {
    "catalog": "",
    "type": "",
    "id": "id-example"
  },
  "spec": {},
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：201。

HTTP	error	说明
400	invalid_request	malformed JSON body
401	unauthorized	missing project-scoped token; re-authenticate with a project scope
403	forbidden	write permission required
500	internal_error	failed to validate hostnames
409	conflict	详细原因由 message 返回。
404	not_found	详细原因由 message 返回。
422	invalid_request	详细原因由 message 返回。
502	backend_unavailable	kubernetes API unavailable

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

更新网关路由显示信息

功能介绍

更新网关路由显示信息。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

PATCH /api/v1/routes/{id}

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string / null	否	显示名称
description	string / null	否	描述

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
status	string	资源状态；具体取值见业务规则
projectId	string	所属项目 ID
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
backend	route.backendRef	后端资源标识
spec	route.Spec	资源配置快照
ready	string	是否就绪；空值时可能省略
conditions	array<route.Condition>	后端状态条件；空值时可能省略
labels	map<string, string>	标签键值对；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

PATCH https://{endpoint}/api/v1/routes/resource-id
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "name": "更新后的名称"
}

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "description": "",
  "status": "ready",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "backend": {
    "catalog": "",
    "type": "",
    "id": "id-example"
  },
  "spec": {},
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_request	malformed JSON body
403	forbidden	write permission required
401	unauthorized	authentication required
404	not_found	route not found
409	conflict	route already exists
500	internal_error	internal server error

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

获取网关路由详情

功能介绍

获取网关路由详情。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/routes/{id}

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

无请求体。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
status	string	资源状态；具体取值见业务规则
projectId	string	所属项目 ID
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
backend	route.backendRef	后端资源标识
spec	route.Spec	资源配置快照
ready	string	是否就绪；空值时可能省略
conditions	array<route.Condition>	后端状态条件；空值时可能省略
labels	map<string, string>	标签键值对；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

GET https://{endpoint}/api/v1/routes/resource-id
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "description": "",
  "status": "ready",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "backend": {
    "catalog": "",
    "type": "",
    "id": "id-example"
  },
  "spec": {},
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	authentication required
404	not_found	route not found
409	conflict	route already exists
500	internal_error	internal server error

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

替换网关路由配置

功能介绍

替换网关路由配置。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

PUT /api/v1/routes/{id}

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

Content-Type: application/json。

参数	参数类型	是否必选	描述
name	string	是	显示名称
description	string	否	描述
namespace	string	否	Kubernetes 命名空间
models	array<route.ModelRoute>	条件必选	使用多模型映射时必选，至少一项；每项须包含 model 和非空 backendRefs。
model	string	条件必选	未提供 models、使用单模型兼容格式时必选。
subdomains	array	条件必选	使用平台根域名时必选，与完整 hostnames 二选一。
hostnames	array	条件必选	直接指定完整域名时必选，与 subdomains 二选一。
backendRefs	array<route.BackendRef>	条件必选	未提供 models 时，与顶层 model 一起提供，至少一个有效后端。
ipAllow	array	条件必选	启用 IP 白名单时须提供非空有效 CIDR 列表；否则可省略或为空。
ipDeny	array	条件必选	启用 IP 黑名单时须提供非空有效 CIDR 列表；否则可省略或为空。
labels	map<string, string>	否	标签键值对

使用完整路由配置替换模型映射等配置；不是局部 PATCH。

参数	参数类型	是否必选	描述
models[].model	string	是	对外模型名，不可为空且在该路由内不可重复。
models[].backendRefs	array	是	该模型的后端列表，至少一项。
models[].backendRefs[].name	string	是	关联服务名称。
models[].backendRefs[].priority	integer	是	后端优先级，0 至 100 的整数。
models[].backendRefs[].weight	integer	是	后端权重，1 至 100 的整数。
models[].backendRefs[].modelNameOverride	string	是	发送给后端的模型名称，不能为空。

嵌套表适用于 models 中的每个映射；单模型兼容格式的 backendRefs 子字段遵循相同约束。IP 白名单和黑名单按所选模式配置。

响应消息

参数	参数类型	描述
id	string	资源唯一标识
name	string	显示名称
description	string	描述
status	string	资源状态；具体取值见业务规则
projectId	string	所属项目 ID
projectName	string	项目名称；空值时可能省略
domainId	string	所属部门 ID；空值时可能省略
domainName	string	部门名称；空值时可能省略
ownerUserId	string	创建者用户 ID
ownerName	string	创建者名称；空值时可能省略
backend	route.backendRef	后端资源标识
spec	route.Spec	资源配置快照
ready	string	是否就绪；空值时可能省略
conditions	array<route.Condition>	后端状态条件；空值时可能省略
labels	map<string, string>	标签键值对；空值时可能省略
createdAt	string(date-time)	创建时间，RFC3339
updatedAt	string(date-time)	更新时间，RFC3339

请求示例

PUT https://{endpoint}/api/v1/routes/resource-id
x-keystone-token: <Keystone Token>
Content-Type: application/json

{
  "name": "示例路由",
  "models": [
    {
      "model": "demo-model",
      "backendRefs": [
        {
          "name": "prov-backend",
          "priority": 0,
          "weight": 1,
          "modelNameOverride": "backend-model"
        }
      ]
    }
  ],
  "subdomains": [
    "demo"
  ]
}

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "id": "id-example",
  "name": "示例资源",
  "description": "",
  "status": "ready",
  "projectId": "projectId-example",
  "ownerUserId": "ownerUserId-example",
  "backend": {
    "catalog": "",
    "type": "",
    "id": "id-example"
  },
  "spec": {},
  "createdAt": "2026-09-21T00:00:00Z",
  "updatedAt": "2026-09-21T00:00:00Z"
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
400	invalid_request	malformed JSON body
500	internal_error	route has no k8s backend id
401	unauthorized	missing project-scoped token; re-authenticate with a project scope
403	forbidden	write permission required
404	not_found	route not found
409	conflict	route already exists
422	invalid_request	详细原因由 message 返回。
502	backend_unavailable	kubernetes API unavailable

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

删除网关路由

功能介绍

删除网关路由。

访问要求：有效 Token；需要对应资源写权限，并受项目、所有者、公共或共享资源规则限制。

URI

DELETE /api/v1/routes/{id}

参数	类型	必选	描述
id	string	是	目标资源 ID

请求消息

无请求体。

响应消息

成功返回 204 No Content，无响应体。

请求示例

DELETE https://{endpoint}/api/v1/routes/resource-id
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 204 No Content

状态码与错误码

成功状态码：204。

HTTP	error	说明
401	unauthorized	missing project-scoped token; re-authenticate with a project scope
403	forbidden	write permission required
404	not_found	route not found
409	conflict	route already exists
500	internal_error	internal server error
422	invalid_request	详细原因由 message 返回。
502	backend_unavailable	kubernetes API unavailable

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

查询可选路由后端

功能介绍

查询可选路由后端。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/service-backends

请求消息

无请求体。

响应消息

参数	参数类型	描述
items	array<route.backendView>	结果列表

请求示例

GET https://{endpoint}/api/v1/service-backends
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "items": [
    {
      "name": "示例资源",
      "displayName": "",
      "namespace": "",
      "kind": ""
    }
  ]
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	authentication required
400	invalid_request	详细原因由 message 返回。
403	forbidden	详细原因由 message 返回。
404	not_found	详细原因由 message 返回。
409	conflict	a route with that name already exists in the namespace
422	invalid_request	详细原因由 message 返回。
502	backend_unavailable	kubernetes API unavailable
500	internal_error	failed to provision route

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。

查询路由筛选项

功能介绍

查询路由筛选项。

访问要求：有效 Token；需要对应资源读权限，并受项目、所有者、公共或共享资源规则限制。

URI

GET /api/v1/routes/filter-options

请求消息

无请求体。

响应消息

参数	参数类型	描述
backends	array<route.filterOption>	后端筛选项
domains	array<route.filterOption>	部门筛选项
projects	array<route.filterOption>	项目筛选项

请求示例

GET https://{endpoint}/api/v1/routes/filter-options
x-keystone-token: <Keystone Token>

正常响应示例

HTTP/1.1 200
Content-Type: application/json

{
  "backends": [
    {
      "value": "",
      "label": ""
    }
  ],
  "domains": [
    {
      "value": "",
      "label": ""
    }
  ],
  "projects": [
    {
      "value": "",
      "label": ""
    }
  ]
}

状态码与错误码

成功状态码：200。

HTTP	error	说明
401	unauthorized	authentication required

此外，认证/授权中间件可返回 401 / 403；后端错误与错误封装见调用方式。