企业官网建设流程全解析

1. 资源与对象这两个概念，到底差在哪

我在生产环境里折腾 Kubernetes 也有几年时间了，跟不少同事聊过之后发现一个很有意思的现象：很多人能熟练敲出来kubectl get pods、kubectl apply -f deployment.yaml，但你要真问他"k8s 里的资源（Resource）和对象（Object）到底是什么意思、有什么区 分"，十有八九会愣一下。

这个问题不搞懂，后面学什么控制器、Operator、CRD 都会觉得隔着一层纱。我用自己的话把这两个概念拆开讲清楚。

1.1 对象是"想要什么"，资源是"有什么能力"

先说我的理解。Kubernetes 里的对象，是你在集群里声明的一个"期望状态"的载体。比如你写了一个Deployment对象，告诉集群"我要 3 个 nginx 副本、镜像版本是 1.25.4"，这就是一个对象。对象是存在于 etcd 里的数据记录，它有名字、有 namespace、有 spec、有 status。说白了，对象是"数据"。

那资源是什么？资源是访问这些对象的"入口通道"和"能力描述"。比如你可以访问deployments、pods、services，这些就是资源。你可以对资源做增删改查，操作对象的数据。Kubernetes 的 REST API 暴露出来的就是资源，你通过kubectl get pods实际上是在"读取 pods 资源"这个 API 端点返回的对象列表。

打个比方：资源是 RESTful API 的路由接口，对象是路由背后存储的数据实体。客户端请求的是资源路径，拿回来的是对象内容。Kubernetes 里这叫 GroupVersionResource（GVR），而对象对应的完整类型标识叫 GroupVersionKind（GVK）。

这个区分不是抠字眼。后面你接触 CRD（自定义资源定义）时，会被迫面对这个区别：你需要注册一个自定义资源（比如CronTab），然后集群才能创建对应的自定义对象。没有资源定义，就没有对象可操作。

1.2 API 对象的三个核心字段：TypeMeta、ObjectMeta、Spec

每个 Kubernetes API 对象在 YAML 里看起来结构都差不多，但很多人第一次写的时候会漏字段、错字段，我把我总结的骨架列在下面：

apiVersion: apps/v1 # TypeMeta之一，声明对象所属的 API 组和版本 kind: Deployment # TypeMeta之二，声明对象的类型 metadata: # ObjectMeta，对象的元数据 name: nginx-deploy namespace: default labels: app: nginx spec: # 期望状态，不同 kind 有不同规则 replicas: 3 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: nginx:1.25.4

• apiVersion和kind组成了 TypeMeta，它决定这个对象对应哪个资源类型。
• metadata是每个对象都一样的部分：名称、命名空间、标签、注解、UID、资源版本号（resourceVersion）等。resourceVersion 是并发控制关键，后面操作踩坑时要靠它。
• spec是核心，描述期望状态。不同的对象类型，spec 结构完全不一样，比如 Pod 有 container 列表，Service 有 selector 和 ports，PVC 有 storageClassName 和 requests。

而status一般不写进 YAML，它由集群的控制器实时更新，记录当前状态。kubectl get里看到 READY、STATUS 这些列，大多是 status 里的数据。

1.3 为什么要区分"对象"和"资源"这么「绕」的概念

我见过有人吐槽：Kubernetes 干嘛不直接叫"结构体"或者"实体"，非要叫对象、资源，绕来绕去。真实原因是，Kubernetes 的整个设计哲学是"声明式 API + 控制器模式"，这套体系建立在对象/资源的抽象之上。

• 对外，REST API 需要一套统一的资源模型来对接各种客户端：kubectl、dashboard、SDK、自定义程序，它们全部通过资源端点来读写对象数据，这保证了生态的一致性。
• 对内，控制器需要监听对象的创建、修改、删除事件，并驱动对象从当前状态走向期望状态。控制器监听的并不是"数据库表"，而是"带版本、带类型"的资源事件流。

所以资源和对象的二元分法，是这套系统能够大一统的关键。不理解它，后面看 Informer 机制、看 Admission Webhook、看 CRD 的 schema 校验时，都会有卡壳感。

2. 三种资源管理方式，生产环境该怎么选

聊完了资源和对象本身，接下来说说怎么管理它们。这是日常接触最多、也最容易混淆的部分。Kubernetes 官方总结过三种管理方式：命令式命令（Imperative Commands）、命令式对象配置（Imperative Object Configuration）、声明式对象配置（Declarative Object Configuration）。

我对这三者的评价：命令式最快、配置式最稳、声明式最适合干活。但"最适合"不代表"永远用"，你需要理解每种的底层逻辑和适用场景。

2.1 命令式命令：适合调试，别用在对公服务的生产变更上

命令式命令就是直接用 kubectl 命令去操作集群，比如：

kubectl run nginx --image=nginx:1.25.4 kubectl scale deploy nginx --replicas=5 kubectl set image deploy nginx nginx=nginx:1.25.5

这种方式的好处是快，一条命令立刻生效，特别适合在测试环境调试、临时扩容、看日志的场景。但我不建议把它作为生产环境的日常管理手段，原因有三个：

1. 不可审计。每条命令是独立执行的，没有一份统一清单告诉你系统"应该长什么样"。团队协作时，别人想了解当前集群部署了什么，找不到一份完整的配置记录，只能一个个 get，效率低还容易漏。
2. 容易误操作。手一抖kubectl delete pod xxx直接把 Pod 删了，Deployment 会重新拉起一个新的，但如果你删的是 PVC 或者 Service 这种"有状态"的资源，影响面就大了。
3. 无法复现。测试环境部署成功，生产环境要复现一套一模一样的，你得翻历史命令记录，命令不一定有 GeRen 注释，很痛苦。

提示：kubectl run在较新版本默认不会自动创建 Deployment（新版本行为有变化），实际生产部署时还是建议用 YAML 管理。命令式命令更适合排查问题。

2.2 命令式对象配置：比命令规范，但有一种很微妙的维护方式

命令式对象配置是kubectl create -f xxx.yaml/kubectl replace -f xxx.yaml这一类操作，它以文件为单位完成变更。

# 创建 kubectl create -f deployment.yaml # 替换 kubectl replace -f deployment.yaml

和纯命令式相比，它至少有了一份配置文件，方便留存和 review。但它的坑在于create和replace都是"全量覆盖"的思路：

• create：文件描述的资源不存在就创建，已存在就报错。
• replace：把现有资源直接替换成文件里的内容，如果文件里没写某字段，该字段可能被清空。

这带来的实际问题：如果你改了文件里一个镜像版本字段，用replace更新，它会把该资源里一些"运行时生成的、没写在文件里的字段"重置掉，比如某些 annotation、nodeSelector 的自动变化、以及 controller 自动填充的配置。replace 是唯一一种理论上会"主动破坏现状"的更新方式，比较容易出线上问题。

2.3 声明式对象配置：日常工作中我推荐的主力方式

声明式对象配置的核心指令是：

kubectl apply -f deployment.yaml

它背后有一套三个文件的合并算法（kubectl 内部对 old、modified、new 三个配置做三方合并），只更新你要改的字段，保留其他字段。这份 YAML 是你对集群"期望状态"的描述，apply 之后，集群里运行的资源状态会不断朝这个期望收敛。

它的好处：

• 可重复执行。同一个 YAML apply 多次，结果是一致的，不会因为资源已存在而报错（除非 key 冲突）。
• 可回滚。配合kubectl rollout undo可以回滚 Deployment，Git 历史保留也方便。
• 适合 GitOps。把 YAML 放到 Git 仓库里，CI/CD 过程中自动 apply，每次变更都有记录、有 diff、有审计。

我自己的管理习惯是：生产环境的所有 workload 型资源（Deployment、Service、ConfigMap、Ingress 等）全部用 YAML 文件管起来，每个目录对应一个应用，README 里写清楚依赖关系。测试和排查时才用命令式命令。

2.4 三种方式的核心区别一张表看清

提示：如果团队里已经上了 ArgoCD 这类 GitOps 工具，那本身就以声明式为基石，YAML 甚至可以不用手工 apply，而是由工具在集群内部完成同步。但了解原理仍然必要——因为它会直接决定你排查问题时的思路。

3. 核心 API 对象入门：掌握这几类就能覆盖大多数需求

Kubernetes 的资源对象非常多，官方文档列了一长串，新用户光看列表容易劝退。但不用慌，日常高频使用的大致就是几类：Namespace、工作负载、服务发现、配置存储、存储卷。我一个个讲，尽量用实际场景说明。

3.1 Namespace：多环境隔离的第一道门

Namespace 是 k8s 里最常见的"逻辑隔离"手段。它本身不是一个隔离实现，只是一个分组标签机制，但它决定了 API 对象的可见性和访问边界。

# 创建命名空间（推荐用 YAML，命令行创建会出现无 metadata.labels 的情况） kubectl create namespace dev kubectl create namespace prod

使用 Namespace 要注意以下点：

1. 大部分常见资源（Deployment、Service、ConfigMap、PVC 等）都是 namespace 级别的，也就是说，它们在哪个 namespace 创建，就归属于哪个 namespace。
2. 有些资源是集群级别的，比如 Node、PV、Namespace 自身、ClusterRole、ClusterRoleBinding。这些和 namespace 没关，删了有风险。
3. 不同 namespace 之间默认是通的，如果你期待"命名空间天然隔离网络"，要额外配置 NetworkPolicy，否则 namespace 只是逻辑文件夹，不提供网络边界。

生产上我习惯按环境拆分：dev、staging、prod，再按业务线拆：order-service、user-service。同时用 ResourceQuota（资源配额）防止某个 namespace 把集群资源耗尽。

3.2 Pod：调度和运行的最小单元

Pod 是 k8s 最小的可调度单元，里面可以有一个或多个容器。同一个 Pod 里的容器共享网络栈、共享存储卷、共享主机名，所以它们之间通过 localhost 就能通信。

写一个最简单的 Pod：

apiVersion: v1 kind: Pod metadata: name: my-pod spec: containers: - name: busybox image: busybox:1.36 command: ["/bin/sh", "-c", "sleep 3600"]

你可能会问：为什么不直接在 Pod 里跑多容器？我的经验是：一个 Pod 只在"多个进程需要紧密协作、共享存储和网络"时才应该放多容器，典型场景是 sidecar 模式，比如日志收集容器（Filebeat/EKS 日志 agent）和应用容器共享日志目录；又比如服务网格里的 envoy sidecar。如果只是"两个独立服务"，那就应该拆成两个 Deployment，让 k8s 独立调度和伸缩。

3.3 工作负载对象：Deployment、StatefulSet、DaemonSet、Job

直接管理 Pod 的情况比较少，因为 Pod 是"短命"的，崩溃了、被驱逐了、节点挂了，都不会自动恢复。日常管理的是工作负载控制器，它们负责维护 Pod 数量、滚动更新、故障自愈。

• Deployment：无状态应用首选。你给它一个 Pod 模板，它负责保证"当前副本数等于期望副本数"。滚动更新、回滚、扩容缩容都内置支持。

kubectl create deployment nginx --image=nginx:1.25.4 --replicas=3

• StatefulSet：适合有状态应用，比如数据库、消息队列、Redis Cluster。它保证每个 Pod 有稳定的网络标识（如mysql-0）、稳定的存储绑定（PVC 不随 Pod 删除而丢失），还负责有序的部署和缩容。使用时要理解它的"每次缩容不会随机删 Pod，而是按编号从高到低删"这 个特性。

• DaemonSet：保证每个匹配的节点上都跑一个 Pod，最适合日志采集（如 Fluentd）、监控探针（如 node-exporter）、网络插件（如 Calico）。你想在所有节点统一部署一个 agent，用 DaemonSet 就对了。

• Job / CronJob：一次性任务和定时任务。Job 保证任务 Pod 成功执行完毕，失败会重试；CronJob 在此基础上加了 crond 一样的定时调度。备份数据库、批量数据清洗这类场景很常用。

3.4 Service 和 Ingress：固定入口，解耦 Pod 变化

Pod 的 IP 是不固定的，副本伸缩时 IP 集合一直在变。Service 提供了一个稳定的访问入口，它通过 selector 选择一组 Pod，并做负载均衡。

apiVersion: v1 kind: Service metadata: name: nginx-service spec: selector: app: nginx ports: - protocol: TCP port: 80 targetPort: 80

Service 有几种类型：

• ClusterIP：集群内部访问，默认类型。外部访问不了，适合后端服务互相调用。
• NodePort：每个节点开一个端口映射到 Service，外部可以通过任意节点IP:NodePort访问。测试环境常用，但直接暴露节点端口，生产环境要谨慎。
• LoadBalancer：依赖云厂商的 LB 插件（如 AWS ELB、阿里云 SLB），会给 Service 分配一个外部 IP。生产环境用得最多，不过各云厂商实现细节有差异。

Ingress 负责七层 HTTP/HTTPS 路由，它本身不干活，需要配合 Ingress Controller（比如 nginx-ingress、traefik、istio gateway）使用。Ingress 相当于一个"智能路由器"：根据域名和路径把请求转发到不同的 Service。

apiVersion: networking.k8s.io/v1 kind: Ingress metadata: name: nginx-ingress spec: rules: - host: app.example.com http: paths: - path: / pathType: Prefix backend: service: name: nginx-service port: number: 80

3.5 ConfigMap 和 Secret：配置与敏感信息的解耦

把配置写死在镜像里是大忌。ConfigMap 用来管理非敏感配置（环境变量、配置文件内容），Secret 用来管理敏感信息（密钥、Token、证书）。

apiVersion: v1 kind: ConfigMap metadata: name: app-config data: log.level: "info" app.properties: | spring.application.name=demo

Secret 的 YAML 和 ConfigMap 类似，但data里的值必须是 base64 编码：

apiVersion: v1 kind: Secret metadata: name: db-secret type: Opaque data: username: YWRtaW4= password: MTIzNDU2

注意：Secret 默认只是做了 base64 编码，不是真正加密。生产环境若对安全性要求高，要启用 etcd 加密存储或使用外部密钥管理方案（如 SealSecrets、Vault）。这个话题展开很大，但记住"Secret 不等于加密存储"是很关键的认知。

3.6 PV 和 PVC：存储的供需隔离

持久化存储是 k8s 里绕不开的话题。PV（PersistentVolume）是管理员或存储插件准备好的存储资源（一块云盘、一个 NFS 导出目录等），PVC（PersistentVolumeClaim）是用户申请存储的清单。

PV 和 PVC 的绑定关系是"供需"对应：PVC 声明需求（大小、访问模式、存储类），PV 匹配供应（容量、访问模式），下一代绑定模式倾向于通过 StorageClass 动态供应。PVC 是 namespace 级别的，PV 是集群级别的，新手容易混。

apiVersion: v1 kind: PersistentVolumeClaim metadata: name:>apiVersion: v1 kind: ResourceQuota metadata: name: quota-dev namespace: dev spec: hard: requests.cpu: "4" requests.memory: 8Gi limits.cpu: "8" limits.memory: 16Gi persistentvolumeclaims: "10" pods: "20"

LimitRange 定义的是每个 Pod 或容器的最小、最大、默认值：

apiVersion: v1 kind: LimitRange metadata: name: limit-dev namespace: dev spec: limits: - type: Container max: cpu: "2" memory: 2Gi min: cpu: "100m" memory: 128Mi default: cpu: "500m" memory: 512Mi

配额和限流一旦配了，未显式声明资源请求的 Pod 有可能创建失败，但实际反馈很容易让人摸不着头脑。排障时看 Events 里的exceeded quota或failed to ensure that the pod matches the quota就能定位。

5.3 学习阶段最容易踩的坑：master 初始化后提示 API server 不健康

这个热搜词出现频率非常高，我见过太多新手卡在这一步了。kubeadm init执行完，提示：

... The API server is not healthy after 4m0.00747357s

看起来是 API Server 起不来，其实大多数情况是 control-plane 组件在初始化时依赖一些容器无法启动，而容器又因为镜像拉取、网络 cgroup 驱动不一致等原因反复重启。排查步骤我给一个简单清单：

1. docker ps -a（或用crictl ps -a）看kube-apiserver、etcd、kube-controller-manager等容器是不是一直处于Restarting状态。
2. kubectl logs -n kube-system kube-apiserver-<master-name>看具体报错，常见有证书文件缺失、etcd连接失败、端口被占用。
3. 检查运行时 cgroup 驱动是否一致：kubelet 的systemd与容器运行时（如 containerd）的SystemdCgroup如果不一致，容器会反复起不来。
4. 检查能否访问镜像仓库，部分环境下registry.k8s.io容易被墙，事先导入离线镜像包是常规做法。

这套排查步骤拉通了前面讲的"从声明到运行"链路，只是把对象从 Deployment 换成了 static Pod。

5.4 label 和 annotation 的实践技巧

label 是 k8s 对象关联的核心手段，它不仅是"标签"，更是 selector 匹配的基础。我建议从一开始就培养规范的 label 习惯：

• app.kubernetes.io/name: 应用名
• app.kubernetes.io/instance: 实例名
• app.kubernetes.io/version: 版本
• app.kubernetes.io/component: 组件类型（如 backend、frontend）
• environment: 环境（dev、prod）

annotation 则存放非标识性元数据，比如监控指标抓取配置、Ingress 插件的参数、owner 联系方式、最后一次变更原因。它不参与 selector 匹配，适合放"给人看的信息"。

5.5 统一资源管理目录的落地建议

最后我分享一下自己项目里用的目录结构。不算什么高深方案，就是实用，供大家参考：

k8s-manifests/ ├── base/ # 公共基础资源 │ ├── namespace-dev.yaml │ ├── namespace-prod.yaml │ ├── quota-dev.yaml │ └── quota-prod.yaml ├── apps/ │ ├── nginx/ │ │ ├── deployment.yaml │ │ ├── service.yaml │ │ ├── configmap.yaml │ │ └── kustomization.yaml │ └── redis-cluster/ │ ├── statefulset.yaml │ ├── headless-service.yaml │ └── pvc.yaml └── README.md

每个应用一个目录，里面 YAML 按资源类型分文件，再用 Kustomize 做环境差异化处理。kubectl apply -k apps/nginx/overlays/prod就能一键部署。好处是依赖关系清晰、diff 方便、回滚直接看 Git 历史。

我的个人体会是：Kubernetes 的"资源和对象"体系不算难，但真的需要用"数据结构 + 状态机"的思维方式去理解它，只背命令迟早会在某次深夜 oncall 中被现实教育。希望这篇整理能帮你减少摸索时间。