企业官网建设流程全解析

• 文档
• 教程
• 云原生

本篇指南以 Knative 官方文档中的《Troubleshooting a Knative Installation》为核心骨架，面向 Kubernetes 管理员，系统讲解 Knative Serving 与 Knative Eventing 安装后出现异常时的标准排查流程：先确认组件 Pod 是否全部就绪健康，再检查组件日志定位错误，最后通过kubectl describe解读各类 Knative 资源的Status状态条件。读完本文，你将掌握一套可复用的"由底向上"排查路径，能够独立判断问题出在控制面、数据面还是网络层，并在需要时高效地上报 bug 或转向应用层调试文档继续深挖。

排查前置：先建立正确的排查顺序

Knative 的安装涉及多个独立组件与命名空间：Serving 核心组件、可选的网络层（Kourier / Istio / Contour / Gateway API）、Eventing 核心组件，以及可选的 Channel / Broker / Source 扩展。故障可能出现在任意一层，因此官方文档给出的排查纪律是：

1. 先检查容器是否都在运行、就绪且健康（这是最基础、最常见的检查项）；
2. 再检查 Knative 组件日志中是否有错误；
3. 最后检查 Knative 资源的 Status 条件，判断资源本身是否被正确调和（reconcile）。

只有在完成上述三步、确认问题不在安装本身后，才建议提交 bug 报告（file a bug report）。这与仓库中维护入口文档 安装总览、升级指引、卸载指引 形成完整的"安装—维护—排查"闭环。

第一步：检查所有容器是否运行、就绪且健康

Knative 由多个 Deployment 组成，健康判断的通用标准是：每个容器的READY列显示1/1（即容器已就绪），STATUS为Running；对于一次性任务（Job），则应显示Complete。以下输出仅为示例，实际 Pod 名称与数量会因安装方式、版本和配置不同而变化，排查重点是"全部为 1/1 Running 或 Completed"这一形态。

Knative Serving 核心组件

kubectl get pods -n knative-serving NAME READY STATUS RESTARTS AGE activator-6b9dc4c9db-cl56b 1/1 Running 0 2m autoscaler-77f9b75856-f88qw 1/1 Running 0 2m controller-7dcb56fdb6-dbzrp 1/1 Running 0 2m webhook-78dc6ddddb-6868n 1/1 Running 0 2m

这 4 个 Pod 分别对应 Serving 的 4 个核心控制面组件：activator（冷启动流量代理与突发缓冲）、autoscaler（自动扩缩容决策）、controller（调和 Service/Route/Revision 等资源）、webhook（准入校验与默认值注入）。安装 Serving 核心组件的方式见 Serving YAML 安装，安装文件清单见 Serving 安装文件说明。

Knative Serving 网络层

网络层取决于你选择的 ingress 提供方。仓库中的安装文档将网络层安装过程整理在 配置 Knative 网络 与各提供方的安装片段（Kourier、Istio、Contour）中，排查时应检查对应命名空间。

Kourier：

kubectl get pods -n knative-serving NAME READY STATUS RESTARTS AGE net-kourier-controller-5fcbb6d996-fprpd 1/1 Running 0 103s kubectl get pods -n kourier-system NAME READY STATUS RESTARTS AGE 3scale-kourier-gateway-86b9f6dc44-xpn6h 1/1 Running 0 2m22s

Kourier 是默认的轻量级 HTTP 路由实现，net-kourier-controller负责读取 KIngress 并编程 Envoy，3scale-kourier-gateway则是数据面网关（见 配置 Knative 网络 中的 Kourier 架构说明）。

Istio：

kubectl get pods -n knative-serving NAME READY STATUS RESTARTS AGE net-istio-controller-ccc455b58-f98ld 1/1 Running 0 19s net-istio-webhook-7558dbfc64-5jmt6 1/1 Running 0 19s kubectl get pods -n istio-system NAME READY STATUS RESTARTS AGE istio-ingressgateway-c7b9f6477-bgr6q 1/1 Running 0 44s istiod-79d65bf5f4-5zvtj 1/1 Running 0 29s

Istio 方案中net-istio-controller与net-istio-webhook是 Knative 的集成组件，而istiod与istio-ingressgateway属于 Istio 自身，安装要求参考 安装 Istio。

Contour：

kubectl get pods -n knative-serving NAME READY STATUS RESTARTS AGE net-contour-controller-68547b797c-dl8pf 1/1 Running 0 14s kubectl get pods -n contour-external NAME READY STATUS RESTARTS AGE contour-7b995cdb68-jg5s8 1/1 Running 0 41s contour-certgen-v1.24.2-zmr9r 0/1 Completed 0 41s envoy-xkzck 2/2 Running 0 41s kubectl get pods -n contour-internal NAME READY STATUS RESTARTS AGE contour-57fcf576fd-wb57c 1/1 Running 0 55s contour-certgen-v1.24.2-gqgrx 0/1 Completed 0 55s envoy-rht69 2/2 Running 0 55s

注意 Contour 方案中contour-certgen-*这类 Job 的STATUS为Completed、READY为0/1，这不是故障——Job 完成任务后即退出，正是预期状态；envoy显示2/2是因为同时运行了 sidecar 容器。

Knative Eventing 核心组件

kubectl get pods -n knative-eventing NAME READY STATUS RESTARTS AGE eventing-controller-bb8b689c4-lk6pq 1/1 Running 0 41s eventing-webhook-577bb88ccd-hcz5p 1/1 Running 0 41s

Eventing 的安装与验证方式见 Eventing YAML 安装 与 Eventing 安装文件说明。若你安装了 Channel / Broker / Source 扩展（如 Kafka、In-Memory Channel），其对应 Pod 也应处于同样健康状态。

第二步：检查 Knative 组件日志中的错误

当 Pod 健康检查通过但功能仍异常时，进入日志排查。核心命令是kubectl logs，按组件所在的命名空间与 Pod 名取日志：

kubectl logs -n knative-serving <pod-name> kubectl logs -n knative-eventing <pod-name> kubectl logs -n <ingress-namespaces> <pod-namespaces> # 网络层命名空间见上文

例如查看 activator 的日志：

kubectl logs -n knative-serving activator-6b9dc4c9db-cl56b 2023/05/01 11:52:51 Registering 3 clients 2023/05/01 11:52:51 Registering 3 informer factories 2023/05/01 11:52:51 Registering 4 informers

正常启动日志通常包含 client、informer factory、informer 的注册信息。排查时重点关注：

• error、warning级别的日志行——往往是问题根因的直接线索；
• Webhook 拒绝信息——例如准入校验失败会以日志形式记录具体原因；
• 网络层组件（net-*-controller、envoy、istiod）的日志——流量路由问题多在此暴露。

第三步：检查 Knative 资源的 Status

Pod 健康不代表 Knative 自定义资源被成功调和。Knative 采用"声明式状态机"设计：每个资源对象都带有Status与Conditions，其中Type: Ready且Status: True表示资源就绪；若为False，通常带有Reason与错误信息。

Knative Serving 资源

kubectl describe -n <namespace> kservice kubectl describe -n <namespace> config kubectl describe -n <namespace> revision kubectl describe -n <namespace> sks # Serverless Service kubectl describe -n <namespace> kingress # Knative Ingress kubectl describe -n <namespace> rt # Knative Route kubectl describe -n <namespace> dm # Domain-Mapping

以默认命名空间中的kservice为例，重点看末尾的Status段：

kubectl describe -n default kservice ... omitted ... Status: Address: URL: http://hello.default.svc.cluster.local Conditions: Last Transition Time: 2023-05-01T12:08:18Z Status: True Type: ConfigurationsReady Last Transition Time: 2023-05-01T12:08:18Z Status: True Type: Ready Last Transition Time: 2023-05-01T12:08:18Z Status: True Type: RoutesReady Latest Created Revision Name: hello-00001 Latest Ready Revision Name: hello-00001 Observed Generation: 1 Traffic: Latest Revision: true Percent: 100 Revision Name: hello-00001 URL: http://hello.default.10.89.0.200.sslip.io Events: Type Reason Age From Message ---- ------ ---- ---- ------- Normal Created 45s service-controller Created Configuration "hello" Normal Created 45s service-controller Created Route "hello"

解读要点：

• Conditions中ConfigurationsReady、RoutesReady、Ready三项全部为True，表示该 Service 从配置到路由的整条链路已就绪；
• Latest Ready Revision Name指明当前可用的 Revision；
• Traffic显示流量分配（此处 100% 指向hello-00001）；
• Events末尾的Normal/Created事件说明 controller 正常创建了底层的 Configuration 与 Route。

如果Ready为False，请顺藤摸瓜继续 describe 对应的revision、rt（Route）、kingress（Knative Ingress）与dm（DomainMapping），逐层定位未就绪的对象。Serving 侧的深入排查方法（Route 状态、Ingress/Istio 路由、Revision 状态、Pod 状态）可继续阅读 Serving 应用问题排查。

Knative Eventing 资源

kubectl describe -n <namespace> brokers kubectl describe -n <namespace> eventtypes kubectl describe -n <namespace> triggers kubectl describe -n <namespace> channels kubectl describe -n <namespace> subscriptions kubectl describe -n <namespace> apiserversources kubectl describe -n <namespace> containersources kubectl describe -n <namespace> pingsources kubectl describe -n <namespace> sinkbindings

以默认命名空间中的brokers为例，关注Status段的Annotations与条件信息：

kubectl describe -n default brokers ... omitted ... Status: Annotations: bootstrap.servers: my-cluster-kafka-bootstrap.kafka:9092 default.topic.partitions: 10 default.topic.replication.factor: 3

当 Broker 基于 Kafka 实现时，这些注解记录了后端 Kafka 的引导地址与 topic 参数（分区数、副本因子），可用于核对事件路由后端是否正确。若 Broker 未就绪，应进一步 describetriggers、channels、subscriptions以及具体 Source 对象。

纵深排查：控制面与数据面的分层定位

当上述三个标准步骤仍未定位问题时，可将排查继续深化到"控制面（Controller）"与"数据面（Data Plane）"两个层面。仓库中的 Eventing 调试指南 提供了一套可复用的分层排查方法论，其完整示例清单见 example.yaml，示例资源链为ApiServerSource(src) → InMemoryChannel(chan) → Subscription(sub) → Service(svc) → Deployment(fn)。

按依赖顺序自底向上检查资源

从最基础、依赖最少的对象开始逐个确认Ready条件是否为True：

1. fn（Deployment）——不依赖 Knative 内部对象，检查status.availableReplicas是否为1；
2. svc（Service）——仅需存在且 selector 指向正确 Pod；
3. chan（Channel）——依赖其背后的 Channel 实现（如 in-memory-channel），通过status.address.hostname确认其可寻址；
4. src（Source）——依赖chan，检查spec.sink是否正确指向 Channel；
5. sub（Subscription）——同时依赖chan与svc，其控制器负责解析目标地址并注入 Channel 的spec.subscribable。

检查各控制器日志

Eventing 中每种资源都有对应 Controller，且不同 Channel CRD 有各自的控制器。排查命令按资源类型区分：

# InMemoryChannel 控制器 kubectl --namespace knative-eventing get pod -l messaging.knative.dev/channel=in-memory-channel,messaging.knative.dev/role=controller --output yaml kubectl --namespace knative-eventing logs -l messaging.knative.dev/channel=in-memory-channel,messaging.knative.dev/role=controller # ApiServerSource 控制器（与其他 Source 控制器同在一个二进制） kubectl --namespace knative-debug get pod -l eventing.knative.dev/sourceName=src,eventing.knative.dev/source=apiserver-source-controller kubectl --namespace knative-debug logs -l eventing.knative.dev/sourceName=src,eventing.knative.dev/source=apiserver-source-controller # Subscription 控制器 kubectl --namespace knative-eventing get pod -l app=eventing-controller kubectl --namespace knative-eventing logs -l app=eventing-controller

控制器日志中应特别关注warning与error级别的行——它们通常直接指向调和失败的根因。

数据面：事件流经路径的日志验证

如果控制面全部健康但事件仍未到达目标，就需要检查数据面。以 InMemoryChannel 为例，事件路径为：srcPOST 事件到chan的地址 → Channel Dispatcher 根据 Host 头识别对应 Channel → 转发给sub定义的订阅者svc（由fn支撑）。查看 Dispatcher 日志：

kubectl --namespace knative-eventing logs -l messaging.knative.dev/channel=in-memory-channel,messaging.knative.dev/role=dispatcher -c dispatcher

正常形态的日志应显示请求被接收、映射到 Channel 并成功分发（目标返回 2XX，如 200/202/204）：

{"level":"info",...,"msg":"Request mapped to channel: knative-debug/chan-kn-channel",...} {"level":"info",...,"msg":"Dispatching message to http://svc.knative-debug.svc.cluster.local/",...} {"level":"info",...,"msg":"Received request for chan-kn-channel.knative-debug.svc.cluster.local",...}

异常形态则会在日志中出现Fanout had an error，例如目标端口配置错误时：

{"level":"error",...,"msg":"Fanout had an error",...,"error":"Unable to complete request Post http://svc.knative-debug.svc.cluster.local/: dial tcp 10.4.44.156:80: i/o timeout",...}

这类错误说明 Dispatcher 已正确识别 Channel 并将事件投递到svc，但目标不可达——问题转移到应用 Service/Deployment 层，需要回到 Serving 应用问题排查 继续诊断。

维护侧关联：验证、升级与回退

排查问题的同时，也应善用维护侧工具确认安装基线：

• 核对安装版本：YAML 安装可通过查询命名空间标签app.kubernetes.io/version确认，如kubectl get namespace knative-serving -o 'go-template={{index .metadata.labels "app.kubernetes.io/version"}}'；Operator 安装则通过kubectl get KnativeServing knative-serving --namespace knative-serving查看，详见 检查 Knative 版本。版本不匹配或升级未完成常是"安装看似正常但功能异常"的隐藏原因。
• 升级路径约束：Knative 仅支持逐 minor 版本升级，跨版本跳跃前必须先完成中间版本升级，详见 升级 Knative。
• 回退与清理：若确认是安装层面无法修复的问题，可参照 卸载 Knative 按"扩展 → 网络层 → 核心组件 → CRD"的顺序反向清理后重装。

排查清单小结

完成一次标准排查，建议按以下清单逐项核对：

1. 所有 Serving / Eventing / 网络层 Pod 的READY为1/1、STATUS为Running（Job 为Completed）；
2. kubectl logs中无error/warning级别异常；
3. kubectl describe各资源Status.Conditions中Ready=True；
4. 控制面控制器日志无调和失败；
5. 数据面日志（如 Channel Dispatcher）确认事件投递链路；
6. 核对安装版本、升级路径是否符合 检查 Knative 版本 与 升级 Knative 的要求。

完成上述全部检查仍无法定位时，再携带组件日志、kubectl describe输出与复现步骤提交 bug 报告——这既是对维护者负责，也能显著加快问题被定位的速度。

• 文档
• 教程
• 云原生