企业官网建设流程全解析

• API网关
• 云原生
• 负载均衡
• 可观测性
• 微服务

VirtualServer是 NGINX Ingress Controller（本仓库 kubernetes-ingress）提供的一等公民自定义资源（CRD），用于在标准 Kubernetes Ingress 之上实现高级配置能力：基于内容的精细化路由、流量切分、请求/响应头修改、TLS 终止与 cert-manager 集成、主动健康检查、URI 重写以及 NGINX App Protect 集成等。读完本文，你将掌握 VirtualServer 的完整字段模型、最小可用配置、上游（upstream）调优、路由动作（action）组合、高级路由（matches/splits）、路由委托（VirtualServerRoute）以及它如何被 Ingress Controller 校验并翻译为 NGINX 配置。

VirtualServer 是什么：资源定位与设计意图

VirtualServer归属于 API 组k8s.nginx.org，版本为v1，Kind为VirtualServer，作用域为Namespaced。官方 API 文档定义位于 docs/crd/k8s.nginx.org_virtualservers.md，其 Go 类型定义位于 pkg/apis/configuration/v1/types.go。

与原生 Ingress 相比，VirtualServer 的优势在于：它直接暴露了 NGINX 的server、location、upstream等核心概念，支持在同一资源内完成"域名 → 路由 → 上游 → 动作"的完整声明，而不需要借助大量注解来扩展行为。CRD 还注册了短名vs，并内置状态打印列（State、Host、IP、ExternalHostname、Ports、Age），这些定义可以从 config/crd/bases/k8s.nginx.org_virtualservers.yaml 中看到：

spec: names: kind: VirtualServer listKind: VirtualServerList plural: virtualservers shortNames: - vs singular: virtualserver scope: Namespaced

安装 CRD 的方式与安装控制器一致，例如kubectl apply -f deploy/crds.yaml。注意 VirtualServer 与 VirtualServerRoute 在共享 host 时通过host字段进行关联，且 host 必须在所有 Ingress 与 VirtualServer 资源中唯一。

从一个最小可用示例开始

仓库中的 examples/custom-resources/basic-configuration/cafe-virtual-server.yaml 给出了最经典的 cafe 示例——两个上游、两个路径、TLS 终止：

apiVersion: k8s.nginx.org/v1 kind: VirtualServer metadata: name: cafe spec: host: cafe.example.com tls: secret: tls-secret upstreams: - name: tea service: tea-svc port: 80 - name: coffee service: coffee-svc port: 80 routes: - path: /tea action: pass: tea - path: /coffee action: pass: coffee

创建后通过kubectl get vs即可查看状态；只有状态为Valid的 VirtualServer 才会被控制器接受并生成 NGINX 配置（详见下文"校验与状态"）。

spec 顶层字段总览

.spec支持的顶层字段如下（完整字段表以 docs/crd/k8s.nginx.org_virtualservers.md 为准）：

listener：引用 GlobalConfiguration 中的自定义监听器

examples/custom-resources/custom-listeners/cafe-virtual-server.yaml 展示了如何让 VirtualServer 监听在自定义端口上：

spec: listener: http: http-8083 https: https-8443 host: cafe.example.com tls: secret: tls-secret

这里的http-8083、https-8443必须是在 GlobalConfiguration 资源中定义过的监听器名。需要同时定义监听器协议与地址，例如http-8083对应监听8083端口的 HTTP 监听器。

tls：终止、重定向与 cert-manager 集成

tls对象包含三个部分：

tls.secret：存放 TLS 证书与私钥的 Secret 名称。Secret 必须与 VirtualServer 同命名空间，推荐类型为kubernetes.io/tls或Opaque，并须以 TLS 角色解析，证书链存放在tls.crt、私钥存放在tls.key。若 Secret 不存在或无效，NGINX 会中断对该 host 的一切 TLS 连接尝试；若未指定 Secret 但配置了通配 TLS Secret，则使用通配 Secret 终止 TLS。

tls.redirect：HTTP→HTTPS 强制跳转配置：

tls.cert-manager：让控制器代为签发证书：

仓库示例 examples/custom-resources/certmanager/cafe-virtual-server.yaml 展示了基于cluster-issuer的完整用法。

externalDNS：为 VirtualServer 自动创建 DNS 记录

对应示例见 examples/custom-resources/external-dns/cafe-virtual-server.yaml。该配置由控制器在同步阶段转换为 externaldns 的 Endpoint 资源（相关实现位于 internal/externaldns）。

upstreams：后端服务的完整调优面板

upstreams[]是 VirtualServer 中"服务发现 + 负载均衡 + 连接调优"的核心。其 Go 定义位于 pkg/apis/configuration/v1/types.go。基础字段：

连接、超时与缓冲

tls 与健康检查

upstreams[].tls：tls.enable为 true 时对上游启用 HTTPS（默认 false，使用 HTTP）。注意：默认 NGINX 不校验上游证书，如需校验请配置 EgressMTLS Policy。

upstreams[].healthCheck（仅 NGINX Plus 支持）：

完整的可运行示例见 examples/custom-resources/health-checks/README.md，其中展示了enable: true、path: /healthz、interval: 20s、fails/passes: 5、port: 8080、自定义Host头与statusMatch: "! 500"的组合。

会话保持、队列、慢启动与备份

sessionCookie：基于 NGINX 生成的会话 Cookie 的会话保持，使同一客户端始终被路由到同一上游：

queue（仅 NGINX Plus）：当无法立即选中上游服务器时，将请求放入队列，queue.size为队列大小，queue.timeout默认 60s，超时后请求不再排队。

slow-start：服务器恢复/可用后，权重从 0 逐渐恢复到标称值；默认禁用。注意：不能与random、hash、ip_hash负载均衡方法同时使用（源码 internal/configs/virtualserver.go 中的incompatibleLBMethodsForSlowStart表明确列出这些冲突方法）。

backup/backupPort：备份服务（ExternalName 类型）名称及其端口（提供备份名时端口必填，范围 1..65535）。主服务器全部不可用时启用备份；同样不能与random、hash、ip_hash混用。

routes 与 action：路径匹配与请求处置

routes[]决定 NGINXlocation的生成。核心字段：

action 的四种形态

action只能且必须定义以下四种之一，Go 定义见 pkg/apis/configuration/v1/types.go：

pass（直通转发）：action.pass: tea将请求直接传给同资源内定义的名为tea的上游。这是最简单、性能最好的转发方式。

proxy（代理并改造）：

redirect（重定向）：redirect.url为目标 URL，支持 NGINX 变量$scheme、$http_x_forwarded_proto、$request_uri、$host，变量须用花括号包裹（如${host}${request_uri}）；redirect.code允许 301/302/307/308，默认 301。

return（返回预置响应）：return.code允许 2XX/4XX/5XX，默认 200；return.type为 MIME 类型，默认text/plain；return.body支持花括号包裹的 NGINX 变量（如Request is ${request_uri}\n）；return.headers[]为自定义响应头。

URI 重写实战

examples/custom-resources/rewrites/README.md 给出了前缀与正则两种重写示例。前缀路径重写：

routes: - path: /tea/ action: proxy: upstream: tea rewritePath: / - path: /coffee action: proxy: upstream: coffee rewritePath: /beans

效果：/tea/abc→/abc；/coffee/abc→/beans/abc。正则重写（捕获组传递剩余 URI）：

- path: ~ /tea/?(.*) action: proxy: upstream: tea rewritePath: /$1

效果：/tea、/tea/→/；/tea/abc→/abc。注意/tea前缀请求会被重定向到/tea/。对应生成逻辑在 internal/configs/virtualserver.go 的generateRewrites与generateProxyPassRewrite中实现。

高级路由：matches、conditions 与 splits

routes[].matches[]实现基于内容的精细化路由（advanced content-based routing）。每个 match 至少包含 1 个conditions，并定义一个action或一组splits。匹配规则按顺序求值，未匹配的请求由路由的默认 action 或 splits 处理。

条件类型（conditions[]），Go 定义见 pkg/apis/configuration/v1/types.go：

examples/custom-resources/advanced-routing/cafe-virtual-server.yaml 同时示范了变量条件与 Cookie 条件：

- path: /tea matches: - conditions: - variable: $request_method value: POST action: pass: tea-post action: pass: tea - path: /coffee matches: - conditions: - cookie: version value: v2 action: pass: coffee-v2 action: pass: coffee-v1

这里/tea的 POST 请求走tea-post，其余走tea；/coffee携带version=v2Cookie 的请求走coffee-v2，其余走coffee-v1。匹配逻辑由 internal/configs/virtualserver.go 的generateMatchesConfig翻译为 NGINX 的map+ 内部 location 结构。

流量切分（splits）：examples/custom-resources/traffic-splitting/cafe-virtual-server.yaml 演示了金丝雀发布最常用的 90/10 切分：

routes: - path: /coffee splits: - weight: 90 action: pass: coffee-v1 - weight: 10 action: pass: coffee-v2

weight取值 0..100，所有 split 权重之和必须等于 100。控制器基于split_clients/keyval 机制实现动态权重（参见 internal/configs/virtualserver.go 的generateSplitsForWeightChangesDynamicReload及 internal/k8s 中关于 DynamicWeightChangesReload 的实现）。

路由委托：VirtualServerRoute 与 routeSelector

当单个 VirtualServer 过大或需要跨团队协作时，可以将路由定义拆分到 VirtualServerRoute 资源中。方式一：通过routes[].route显式引用：

routes: - path: /tea route: default/tea

方式二：通过routeSelector按标签批量选择：

routes: - path: / routeSelector: matchLabels: app: coffee

完整示例见 examples/custom-resources/basic-configuration-vsr/cafe-virtual-server.yaml。控制器在同步时会把选中的 VirtualServerRoute 合并进 VirtualServer 的生成配置（VirtualServerEx结构中的VirtualServerRoutes与VirtualServerSelectorRoutes字段即用于承载这些路由，见 internal/configs/virtualserver.go）。

校验与状态：从声明到 Valid 的旅程

VirtualServer 提交到集群后，控制器会执行两轮校验：

1. CRD 模式校验：基于 config/crd/bases/k8s.nginx.org_virtualservers.yaml 中openAPIV3Schema的约束（枚举值、正则、必填项等），由 API Server 在写入时强制执行。
2. 控制器业务校验：位于 pkg/apis/configuration/validation/virtualserver.go，配合 pkg/apis/configuration/validation/common.go 完成 host 唯一性、路径格式、权重总和、引用存在性等检查，并返回三种状态（定义见 pkg/apis/configuration/v1/types.go）：
   • Valid：校验通过并正常工作；
   • Warning：已接受但可能以降级状态运行；
   • Invalid：校验失败或 NGINX 重载对应配置失败。

状态会写入status.state / status.reason / status.message / status.externalEndpoints（见 pkg/apis/configuration/v1/types.go），并通过kubectl get vs打印列直接可见。

从源码看 VirtualServer 如何变成 NGINX 配置

VirtualServer 的"翻译"工作集中在 internal/configs/virtualserver.go（约 3000 行）。其生成函数与 NGINX 指令的对应关系可以帮你建立从 YAML 到nginx.conf的映射直觉：

这套生成逻辑同样服务于 VirtualServerRoute 合并后的路由与 gRPC 上游（generateGRPCPass）。相关单元测试可在 internal/configs/virtualserver_test.go 中找到，端到端的行为验证则覆盖在 tests/suite/test_virtual_server.py 等测试套件中。

延伸阅读

• VirtualServer 官方字段参考
• VirtualServerRoute 资源参考
• GlobalConfiguration（自定义监听器）参考
• examples/custom-resources 目录下的全部可运行示例，尤其是 basic-configuration、advanced-routing、traffic-splitting 与 rewrites
• Policy 资源参考 与 App Protect DOS 资源参考，用于理解policies与dos字段的对接对象

• API网关
• 云原生
• 负载均衡
• 可观测性
• 微服务