> 原始 Markdown 孪生体（构建期从源 Markdown 生成）。渲染页：https://docs.gatellm.io/zh-CN/reference/field-reference · 文档索引：https://docs.gatellm.io/zh-CN/llms.txt


# 字段速查索引

在控制台填表单、或用 Console API 提交配置时，不确定某字段是什么、属于哪个实体，先查本页速查表定位；要看完整语义、默认值与示例，再进每节链接的详解页。覆盖上游、模型、负载均衡器、访问密钥、密钥组、MCP 服务器、访问规则七类实体。

## 上游（Upstream）

详见 [上游与模型字段](/zh-CN/reference/upstreams-models-fields.md)。

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 唯一名，模型引用 |
| `protocol` | enum | 见 [协议互通矩阵](/zh-CN/reference/protocol-matrix.md) 协议清单 |
| `base_url` | string | 上游地址，结尾不带 `/` |
| `api_keys` | array | 多密钥确定性加权分布（同一调用方粘同一把 key），每项含 `key` + `weight`（0=备用）；算法见 [上游与模型字段 → 多密钥与权重](/zh-CN/reference/upstreams-models-fields.md#multi-key-weights) |
| `user_agent` | string? | 覆盖全局 UA，支持 `{{...}}` 模板变量 |
| `headers` | map | 自定义头，支持 `{{var}}` 与 `{{alt1\|alt2}}` 回退链；可用变量见 [模板变量速查](/zh-CN/reference/template-variables.md) |
| `proxy` | string? | 出站代理 |
| `dns_servers` | array | per-upstream DNS（≤8），DoH/DoT/UDP 自动识别 |
| `dns_ttl_secs` | u64 | DNS 缓存 TTL，默认 30 |
| `request_payload` | array | 请求体改写规则（path/value/mode；value 支持 `{{...}}` 表达式注入动态值，可用变量见 [模板变量速查](/zh-CN/reference/template-variables.md)）。改写类规则在协议转换后按目标形状应用；`switch-route` 例外——不改 body，在转换前按**客户端**形状评估 `when`（OR 语义谓词列表，每项 `{path, eq?}`：省略 `eq`=存在性、给出 `eq`=相等，`*` 通配取存在性语义），命中触发 立即切换，`use_model` 为切换目标（支持跨协议） |
| `request_transform_before` | script? | 翻译前请求阶段 JS（见 [脚本 API 参考](/zh-CN/reference/scripting-api.md)） |
| `request_transform_after` | script? | 翻译后请求阶段 JS（见 [脚本 API 参考](/zh-CN/reference/scripting-api.md)） |
| `response_transform` | script? | 响应阶段 JS（流式不支持） |
| `script_error_mode` | enum | `log-and-continue` / `log-and-reject` |
| `count_token` | enum | `upstreamApi` / `tiktoken` |
| `rate_limit` | object? | 上游级限流（`rpm` / `max_concurrency` / `tpm` / `tps_min_interval_ms` / `wait_timeout_secs` / `initial_tokens`），字段见 [上游与模型字段](/zh-CN/reference/upstreams-models-fields.md) |
| `enabled` | bool | 默认 true |
| `extra_config` | json? | 厂商扩展 |

## 模型（Model）

详见 [上游与模型字段](/zh-CN/reference/upstreams-models-fields.md)。

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 对外模型名，客户端用这个调 |
| `upstream` | string | 所属上游 |
| `upstream_model_id` | string | 发往上游的真实模型名 |
| `aliases` | array | 额外可用名（与主名共享全局唯一空间） |
| `hide_name` | bool | true 时主名不可访问（404），只能用别名/LB |
| `protocol` | enum? | 覆盖上游协议 |
| `base_url` | string? | 覆盖上游 base_url；`direct_path` 时当完整端点 URL |
| `kind` | string? | DashScope 等变体标识 |
| `inference_profile` | string? | Bedrock 推理配置 |
| `request_payload` | array? | 请求体改写规则（覆盖上游级；value 支持 `{{...}}` 表达式注入动态值，变量范围见 [模板变量速查](/zh-CN/reference/template-variables.md)）。`switch-route` 模式用 `when` + `use_model`，见上游行说明 |
| `request_transform_before` | script? | 模型级翻译前请求脚本（覆盖上游级） |
| `request_transform_after` | script? | 模型级翻译后请求脚本（覆盖上游级） |
| `response_transform` | script? | 模型级响应脚本 |
| `script_error_mode` | enum? | 覆盖 |
| `rate_limit` | object? | `inherit` 或具体值 |
| `count_token` | enum? | 覆盖 |
| `enabled` | bool | |

## 负载均衡器（Load Balancer）

详见 [负载均衡字段](/zh-CN/reference/load-balancing-fields.md)。

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 客户端调用时填的模型名 |
| `aliases` | array | 额外可用名 |
| `entries` | array | 条目，每项 `{upstream, model, weight}`（0–255，0=备用） |
| `retry_on_different_node` | bool | 默认 true，出错换节点 |
| `extra_config.sticky_session_enabled` | bool | 粘性会话（嵌在 `extra_config` 下，默认 `true`；非顶层字段） |
| `binding_ttl_secs` | u64 | 粘性 TTL，默认 300；0=永久 |
| `binding_key_template` | string | 绑定键模板，`{{...}}` 表达式；可用变量见 [模板变量速查](/zh-CN/reference/template-variables.md) |
| `static_bindings` | array | 管理员静态绑定（binding_key + upstream + model + access_key 名/组） |
| `enabled` | bool | 默认 true |

## 访问密钥（AccessKey）

详见 [访问密钥与密钥组字段](/zh-CN/reference/access-keys-groups-fields.md)。

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 标识，编辑时只读 |
| `api_key` | string | 客户端带的凭证；列表掩码，完整值按需取 |
| `group` | string? | 所属密钥组，决定模型/MCP 权限 |
| `model_mappings` | array | 该密钥专属的 `from → to` 模型重写（可带 `when` 头条件）；优先级高于所属组规则；空=不映射。见 [配置身份作用域模型映射](/zh-CN/howto/configure-identity-model-mapping.md) |
| `anonymous` | bool | 匿名兜底（全局唯一） |
| `enabled` | bool | 关闭即吊销 |
| `acl_default_action` | enum? | `allow` / `deny`，无规则命中时的 per-key 回退动作 |
| `created_by` | string? | 创建者控制台用户名 |

## 密钥组（AccessKeyGroup）

详见 [访问密钥与密钥组字段](/zh-CN/reference/access-keys-groups-fields.md)。

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 分组标识 |
| `models` | array | 可访问模型；空=无权限，`["*"]`=全部 |
| `load_balancers` | array | 可访问的负载均衡器 |
| `model_mappings` | array | 该组共享的 `from → to` 模型重写（可带 `when` 头条件），作用于组内所有密钥；优先级低于密钥自身规则、高于透传。见 [配置身份作用域模型映射](/zh-CN/howto/configure-identity-model-mapping.md) |
| `mcp_tool_acl` | object | `{allowed_tools, denied_tools, allowed_tags}`，见 [MCP 配置](/zh-CN/reference/mcp-config.md) |
| `acl_default_action` | enum? | `allow` / `deny`，无规则命中时的 per-group 回退动作 |

## MCP 服务器（McpServer）

详见 [MCP 配置](/zh-CN/reference/mcp-config.md)。

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 唯一，作工具前缀 |
| `transport` | enum | `streamable_http` / `sse` |
| `connection_type` | enum | `stateful` / `stateless` / `rest_bridge` |
| `endpoint` | string | 上游 URL |
| `auth_header` | string? | 上游 Authorization 头 |
| `extra_headers` | map? | 额外头 |
| `tags` | array | 粗粒度 ACL 标签 |
| `priority` | i32 | 0–999，小=高优先 |
| `idle_timeout_secs` | u32 | 默认 300 |
| `defer_loading` | bool | 首次调用才加载 |
| `health_check` | object? | path / interval(60s) / timeout(5s) |
| `max_concurrency` | u32? | 每访问密钥并发上限 |
| `rate_limit` | object? | rps / tpm |
| `extra_config` | json? | REST bridge 需简化 REST 规范 JSON（`{title, version, operations[]}`） |
| `enabled` | bool | |

## 访问规则（AclRule）

详见 [Header ACL 规则字段](/zh-CN/reference/header-acl-rules.md)。

| 字段 | 类型 | 说明 |
|------|------|------|
| `name` | string | 全局唯一标识，创建后不可改 |
| `rule_type` | string | 目前仅 `header` |
| `condition_key` | string | HTTP 请求头名；`condition_type = any` 时为空 |
| `condition_type` | enum | `exact` / `prefix` / `regex` / `exists` / `absent` / `any`。`any` 表示条件恒真、不检查请求头，规则仅靠作用域生效（此时 `condition_key` 为空）。`regex` 默认不锚定即「包含」语义，完全匹配需 `^...$`，多条件用 `\|` 组合，详见 [Header ACL 规则字段](/zh-CN/reference/header-acl-rules.md)「regex 匹配语义」 |
| `condition_value` | string? | 匹配值；`exists`/`absent`/`any` 时须为空 |
| `action` | enum | `allow` / `deny` |
| `enabled` | bool | 规则开关，禁用后加载时被忽略 |
| `sort_order` | int | 升序优先级，小=先评估；同值时按作用域 全局 → 组 → 密钥 顺序 |
| `scope_key` | string[] | 限定到一个或多个 access key，与 `scope_group` 互斥；空数组=全局 |
| `scope_group` | string[] | 限定到一个或多个密钥组，与 `scope_key` 互斥；空数组=全局 |

## 相关章节

- 上游/模型字段详解：[上游与模型字段](/zh-CN/reference/upstreams-models-fields.md)
- 负载均衡字段详解：[负载均衡字段](/zh-CN/reference/load-balancing-fields.md)
- 访问密钥与密钥组字段详解：[访问密钥与密钥组字段](/zh-CN/reference/access-keys-groups-fields.md)
- Header ACL 规则字段详解：[Header ACL 规则字段](/zh-CN/reference/header-acl-rules.md)
- MCP 服务器字段详解：[MCP 配置](/zh-CN/reference/mcp-config.md)
- 模板变量清单：[模板变量速查](/zh-CN/reference/template-variables.md)
- 协议清单：[协议互通矩阵](/zh-CN/reference/protocol-matrix.md)
- 错误码清单：[错误码速查](/zh-CN/reference/error-codes.md)