配置概述

Nantian Gateway 用 YAML 配置文件而不是命令行参数或环境变量。控制面和数据面各有一份自己的配置文件，分开维护，因为它们作为独立进程跑的，职责不同。

这一章覆盖了两个组件所有可配的选项。

实验功能

实验性 AI、Wasm、TokenPolicy 和 Gateway policy 行为默认关闭。创建 AIService、TokenPolicy、WasmPlugin 或实验性 BackendLBPolicy 资源前，请先阅读实验功能。

配置是怎么生效的

控制面启动时通过 --config 参数读配置文件。默认路径看你怎么部署的：Helm chart 把 ConfigMap 挂载到 /etc/nantian-gw/config.yaml，本地开发直接用仓库里 configs/controlplane/config.yaml 这一份。

数据面同理。配置文件在仓库里是 configs/dataplane/config.yaml，或者通过 --config 指向你自己的路径。

两份文件都用标准 YAML 语法，字段名是 camelCase。时长值用 Go 的 duration 格式：30s 表示三十秒，2m 表示两分钟，200ms 表示 200 毫秒。以 Ms 结尾的数值（比如 timeoutMs）直接用毫秒数，不带 Go 后缀。

配置来源

这份文档里出现的所有默认值都是从 gateway/internal/config/config.go 的配置加载代码里直接取的。你在 YAML 里省略某个字段的时候，网关会填上下面表格里列出来的默认值。

任何字段都可以在配置文件里覆盖。用 Helm 的用户应该改 values.yaml，不要直接改配置文件，因为 ConfigMap 是 Helm 从 values 模板渲染出来的。

Helm 部署：以 Values 为准

当你通过 Helm 部署 Nantian Gateway 时，真正的运维入口是你的 Helm values 文件。Chart 会把这些 values 渲染成 ConfigMap、Secret、Pod 规格和 Service。应该修改 values 文件并执行 helm upgrade，而不是把渲染后的 ConfigMap 当成长期维护配置的地方。

关于推荐的 values 分层方式、主要 chart 配置组和生产校验流程，请阅读 Helm Values 指南。

章节结构

页面	内容
Helm Values 指南	values 分层方式、主要 chart 配置组和生产环境校验流程
控制面	服务地址、Reconciler 调优、主备选举、节点漂移检测、Admin API
数据面	代理运行时、上游连接、健康检查、限流、熔断
TLS / mTLS	Admin TLS、gRPC TLS with mTLS、xDS 传输加密
gRPC xDS	Keepalive 计时器、连接管理、快照生命周期
可观测性	结构化日志、Prometheus 指标、pprof、访问日志、OpenTelemetry 追踪
性能调优	缓冲区大小、连接池尺寸、超时、保护性限制

关键概念

在开始配置之前，先理解几个关键概念能省不少时间。

配置热加载

Nantian Gateway 不支持配置热加载。任何配置变更都需要重启对应组件才会生效。控制面重启时，Leader 选举机制保证配置变更不会中断流量。数据面重启时，滚动更新保证始终有足够的副本在接流量。

这个设计决定是故意的。热加载引入的状态转换复杂度远大于重启带来的那几秒不可用。在 Kubernetes 里，Deployment 的滚动更新就是最好的”配置推送”机制。

控制面和数据面的配置边界

两份配置文件是独立的，但有些配置需要在两边对齐。比如 gRPC TLS：控制面配了 TLS 证书，数据面就必须配对应的 TLS 传输参数才能连上。再比如 controllerName：控制面用它来认领 Gateway 资源，数据面不需要知道这个值。

对齐的约束在每页的配置表格里都有说明。如果某个参数需要两边一致，表格里会标出来。

默认值策略

默认值偏向”安全”和”能用”而不是”高性能”。比如 gRPC TLS 默认关闭，日志级别默认 info，连接池默认 32768。这些值足够你跑起来，但生产环境需要根据流量特征调参。具体的调优建议在性能调优那页有详细说明。

完整控制面配置示例

下面是一份有代表性的控制面配置文件，涵盖了日常最常改动的几个段落。这不是完整文件，完整版在仓库 configs/controlplane/config.yaml 里，但这份示例把关键配置项都标上了注释：

grpcAddr: ":18080"           # xDS gRPC，数据面节点连这个地址
admin_addr: ":18081"          # Admin API
metricsAddr: ":18082"        # Prometheus /metrics
controllerName: "gateway.networking.k8s.io/nantian-gw"
namespace: "nantian-gw"

# Reconciler 调优
syncPeriod: 30s
reconcilerRunner:
  settleDelay: "300ms"
  retryBackoff: "1s"

# 主备选举（多副本部署时）
leaderElection:
  enabled: true
  leaseDuration: "15s"
  renewDeadline: "10s"

# gRPC 长连接保活
grpcRuntime:
  keepaliveTime: "30s"
  keepaliveTimeout: "10s"
  maxConnectionAge: "30m"

# Admin API 请求体限制
adminLimits:
  maxRequestBodyBytes: 2097152   # 2 MiB

# TLS（默认关闭，生产环境再开）
adminTLS:
  enabled: false
grpcTLS:
  enabled: false

# 日志
log:
  level: "info"
  format: "json"

# 功能开关
features:
  enableExperimentalGateway: false
  enableAiGateway: false

配置校验

网关启动时会对所有配置项做校验。格式不对的 duration、缺失的必填字段、互相冲突的选项都会导致进程在接流量之前直接 fatal 退出。

没有单独的 dry-run 参数——manager 二进制只接受 --config。要在部署前验证配置，可在临时环境中用该配置启动进程，确认它能进入 ready 状态、而不是因校验失败退出：

go run ./cmd/manager --config ./my-config.yaml

配置错误会立即以 fatal 日志的形式指出具体字段，进程以非零码退出。启动校验只覆盖语法和语义，不会验证地址能不能通、证书有没有过期、Kubernetes API 能不能连上——这些属于运行时检查。

在 CI 中，可以用候选配置启动控制面并断言它变为 ready（或快速失败），在推广变更前拦住配置错误。

环境差异化配置

不同环境下配置的侧重点不一样。下表总结了各环境之间的差异：

配置项	开发 / Minikube	预发布	生产
TLS	全部关闭	自签或预发布 CA 证书	正式证书，开启 mTLS
日志格式	`text`	`json`	`json`
日志级别	`debug` 或 `info`	`info`	`info`（或 `warn`）
主备选举	可关（单副本跑）	开启（2 副本）	开启（2+ 副本）
pprof	`enabled: true`	`enabled: false`	`enabled: false`
超时	偏短（反馈快）	跟生产对齐	偏保守
Admin 鉴权	无	无或 token	必须配 Bearer Token

通过 Helm 的 values 文件来管理这些差异。把环境覆盖保存在 chart 外部，并在安装或升级时叠加：

helm-values/
  values-dev.yaml          # 开发环境覆盖
  values-staging.yaml      # 预发布环境覆盖
  values-production.yaml   # 生产环境覆盖

部署时指定对应的 values 文件：

helm upgrade --install nantian-gw nantian-gw/nantian-gw \
  --namespace nantian-gw \
  --create-namespace \
  -f helm-values/values-production.yaml

配置文件位置与优先级

网关启动时只读一份配置文件，不会合并多个文件。解析顺序从高到低是：

--config 参数 — 显式指定的路径，优先级最高。
Helm ConfigMap 挂载 — /etc/nantian-gw/config.yaml，Helm chart 自动挂载的。
仓库默认路径 — 工作目录下的 configs/controlplane/config.yaml。

Helm 部署时，chart 会把 values.yaml 渲染成 ConfigMap 挂到 /etc/nantian-gw/config.yaml。进程启动不带 --config，自然就走到这个挂载路径。要改 Helm 部署的配置，改 values.yaml 然后 upgrade，不要直接 kubectl edit configmap，Helm 下次 upgrade 会把你的手工改动覆盖掉。

本地开发时直接用仓库里的默认配置，也可以通过 --config 覆盖：

go run ./cmd/manager --config /tmp/my-config.yaml

不确定到底读了哪个配置文件？看启动日志里带 "path" 字段的那一行就行。