把一个小服务从本地docker run挪到 Kubernetes 上很多人第一次都会经历同一种挫败本地三条命令就跑起来的东西上了集群突然变成 Deployment、Service、Ingress、IngressClass、TLS 证书、镜像仓库凭证、资源配额一整摞 YAML改个环境变量还要重新kubectl apply。Kubero 解决的正是这一段落差——它把「Git 仓库 → 构建 → 部署 → 域名可访问」这条链路收进一个自托管面板里底层依然是你自己的 Kubernetes 集群但操作手感回到了「推代码、等构建、打开网页」的节奏。这篇内容面向已经有一台能用的 K8s 集群、但还没在上面跑过自己业务应用的读者从集群体检、Helm 安装、面板登录一直走到第一个应用拿到可访问域名中间会把每一步「为什么这么配」讲透也会把我在实际集群里踩到的几个典型坑和排查链路完整摊开。读完你应该能在半小时内跑通全流程并且知道出问题时先看哪里。1. Kubero 到底把 Kubernetes 的哪一层复杂度藏起来了1.1 从 kubectl apply 到 git push真正被替换掉的是什么先把这个工具的定位说清楚否则很容易误判它的能力边界。Kubero 不是一个「简化版 Kubernetes」也不是把 kubectl 包了一层的命令行工具它是跑在你集群内部的一个应用交付层自己带 Web 面板、带 API 服务、带一组自定义资源CRD你通过面板描述「我要一个应用代码在哪个 Git 仓库用哪个分支跑在哪个环境」它负责把这些描述翻译成 Kubernetes 原生对象——Deployment、Service、Ingress、ConfigMap、Secret、PVC然后交给集群去执行。这意味着两件事。第一你的集群仍然是集群节点、调度、网络、存储这些基础设施层面的东西一点没少Kubero 不帮你买机器也不帮你配 CNI它只接管「应用怎么上去」这一段。第二它产出的仍然是标准 K8s 资源你随时可以kubectl get deploy -n 命名空间看到真实落地的东西不会出现「面板上一切正常但集群里啥也没有」的黑箱感。这一点在做故障排查时非常关键后面第 5 节的所有排查动作本质上都是「面板描述」和「集群实况」之间的对照。被替换掉的具体动作可以列成一张对照表理解这张表比记住任何命令都有用传统手工流程Kubero 里的等价物底层实际产出手写 Dockerfile 或判断该用哪种构建方式选 Buildpack 或 Dockerfile 模式集群内的构建 Pod 构建产物镜像手动 build、tag、push 到镜像仓库提交代码触发自动构建镜像推送到内置或外部 Registry手写 Deployment YAML 并 apply面板里填应用信息Deployment ReplicaSet Pod手写 Service 做端口映射填容器端口ClusterIP Service手写 Ingress 配证书填域名后缀Ingress TLS Secret手动建 ConfigMap / Secret 挂环境变量面板里加键值对ConfigMap / Secret手动拉数据库并配连接串添加 Addon由 Operator 管理的数据库实例看表格最后一列你会发现没有任何一步被跳过只是被收敛成了一次表单填写。这是理解 Kubero 价值的前提它省的是重复劳动和心智负担不是省掉集群本身的运维责任。很多团队上线后觉得「用了面板怎么还这么麻烦」问题往往出在把面板当成了托管服务忘了节点资源、存储类、Ingress 控制器这些还是得自己管。1.2 拆开面板看Kubero 在你的集群里造了哪些东西安装完 Kubero 之后集群里会多出一批东西认识它们能让你在出问题时知道往哪看。按职责可以分成四层。控制层一个 Web UI 服务加一个 API 服务通常跑在独立的命名空间里默认就叫kubero。UI 只是前端真正干活的是 API它持有集群内的 ServiceAccount通过 RBAC 权限去创建和修改资源。所以 API 这个 Pod 挂了面板就转圈但已经部署的应用完全不受影响——这是排查时第一条要分清的事面板故障和业务故障是两件事。自定义资源层Kubero 定义了几个 CRD最核心的是Application一个应用和Pipeline一条部署流水线对应一个环境。面板上你点的每一个按钮最终都是对这两个 CRD 的增删改查然后由一个 Operator 或控制器把它们翻译成原生对象。想知道面板背后到底发生了什么kubectl get applications -A -o yaml比点面板有效得多。构建层每次部署会起一个构建 Pod在集群内部完成代码拉取、依赖安装、镜像打包。这是 Kubero 和「纯 GitOps 方案」最大的区别——它的构建发生在集群里而不是在你的 CI runner 上。好处是配置简单、不用自建 CI代价是构建会消耗集群资源构建失败时你得去翻构建 Pod 的日志而不是流水线页面。运行时层真正跑业务的 Deployment 和 Pod默认会被放到独立的命名空间里按 Pipeline 隔离。这一层是纯标准的 K8s 工作负载用任何你熟悉的工具都能观测。我一般建议安装完成后先花两分钟把这四层对应的 Pod 和资源都get一遍形成一个「正常基线」。没有基线出问题时你连「这是不是本来就这样」都判断不了。后面第 3 节会给出具体的自检命令清单。1.3 适用与不适用别把入门工具当生产平台的全部说句实在话Kubero 最舒服的场景是这几类个人或小团队的自建服务、内部工具、演示环境、教学实验、多环境开发/预发/生产需要快速铺开的单体应用。它的优势在于「一条链路全包」——从源码到域名中间不用接第二个系统。但如果你的需求是这几类就得掂量一下需要严格的审批流和变更审计那得上真正的 GitOps 加策略引擎、需要复杂的多集群分发那得上集群编排层、需要极细粒度的资源配额和成本分摊面板给的配额控制相对粗、需要自定义构建缓存策略和并行度自建 CI 更灵活。还有一个容易被忽略的点Kubero 对「应用」的抽象是偏单体/小服务的。一个仓库一个应用构建产物一个镜像。如果你要跑的是十几个微服务互相调用虽然可以建十几个应用但服务间调用、链路追踪、统一网关这些事它不负责你得自己在集群里解决。我在一个模拟项目里试过用它铺五六个服务能跑但接线工作全在集群侧手工做面板只帮了部署那一段。认清这条边界能省掉很多「为什么它不支持某某功能」的困惑。2. 动手之前的集群体检那些看起来能跑却没跑起来的坑2.1 集群版本、容器运行时与存储类的三项硬指标很多人卡在第一步不是因为命令敲错而是因为集群缺了某个「默认没人装」的组件。装之前建议按下面三项过一遍。版本集群版本别太老建议次新版本往上。控制器和 CRD 依赖的 API 版本在老集群上可能已经被废弃或还没引入表现是安装时直接报no matches for kind。查一下kubectl version --short容器运行时与架构Kubernetes 早就不直接管 Docker 了走的是 CRI。这本身对 Kubero 没影响但要注意两点——节点架构如果是 ARM比如很多开发板或某些云的低价机型构建阶段的部分镜像未必有 ARM 版本会出现构建 Pod 一直ImagePullBackOff以及节点上的容器运行时如果配置了私有仓库白名单构建产出的镜像推送可能被拦。这两点都属于「装得下来但跑不起来」的隐性坑。存储类StorageClass这是最容易漏的一项。Kubero 自身需要持久卷存配置和构建数据Addons 里的数据库更是必须持久化。如果你的集群是kubeadm手动搭的裸机集群很可能根本没有默认 StorageClass表现是 PVC 一直Pending面板装完但 Pod 起不来。查一下kubectl get storageclass输出里带(default)标记的那一行就是默认存储类。如果一条都没有就得先装一个本地环境常见的做法是装个基于本地磁盘的 provisioner云上一般直接用云厂商的块存储类并把其中一个标成默认。这一步没做后面所有涉及持久化的环节都会连锁失败。另外提一句资源。整套东西跑起来控制层加构建层建议给集群预留至少 2 核 4G 的空闲可调度资源构建时会有明显的瞬时占用峰值。1 核 2G 的单节点实验集群能装能跑但构建稍微大一点的应用就会因为内存不足被 OOMKilled报错信息还相当隐晦构建 Pod 状态显示 Error日志戛然而止。2.2 Ingress Controller 与通配符域名多租户入口的隐藏前提这是整套流程里技术含量最高、也最容易翻车的一环值得单独展开。Kubero 给每个应用分配域名的逻辑是子域名拼接你在配置里填一个基础域名比如apps.example.internal应用名加环境名拼在前面形成myapp-staging.apps.example.internal这样的完整域名。这种设计的好处是新增应用零配置坏处是对 DNS 和证书提出了一个硬性要求——必须支持通配符。DNS 侧你需要一条通配符记录*.apps.example.internal A 你的 Ingress 入口 IP apps.example.internal A 你的 Ingress 入口 IP很多人只配了带星号那条结果访问基础域名做健康检查时解析不到误以为是 Ingress 坏了。两条都配上成本很低。证书侧更麻烦一点。如果走 HTTP 自动签发必须用 DNS-01 挑战而不是 HTTP-01因为通配符证书没法用 HTTP 挑战验证。这意味着你得给证书管理器配上 DNS 服务商的 API 凭证这一步在本地/内网环境里往往做不了那就退回到两条路一是用自签证书并在浏览器里手动信任内部工具完全够用二是只对单个应用域名签发普通证书牺牲了「新增应用零配置」的便利。Ingress 控制器本身集群里必须已经有一个在工作的 Ingress Controller并且它监听的是你规划的那组入口地址。Kubero 安装时会指定使用哪个 IngressClass如果集群里有多个控制器比如同时装了两种指定错了就会出现「Ingress 对象创建成功、外部访问 404」的经典现象。查一下现有控制器和它的 Class 名kubectl get ingressclass kubectl get pods -A | grep -i ingress把 Class 名记下来安装时明确填进去别依赖默认值。默认值这东西在你只有一个控制器时很稳一旦多装了一个就会悄悄变。2.3 Helm 与 kubectl 的版本匹配这条隐形依赖Kubero 通过 Helm Chart 安装所以本机得有 Helm且版本不要太老建议 3.8 以上。老版本 Helm 对 OCI 仓库和某些 chart 特性的支持不全报错信息通常是failed to download之类看起来像网络问题实际是版本问题。helm version --short kubectl version --client --short还有个细节Helm 的 release 是带状态的如果你装了一半想重来直接再helm install同名 release 会报cannot re-use a name that is still in use。正确的收尾方式是先helm uninstall但要注意卸载 Helm release 默认不会删除 CRD 和 PVC这些残留会在下次安装时造成冲突尤其是 CRD 版本不一致导致field is immutable这类错误。我第一次重装时就栽在这正确的清理顺序是helm uninstall kubero -n kubero kubectl delete pvc --all -n kubero # CRD 谨慎删除确认里面没有你想保留的业务数据 kubectl get crd | grep -i kubero提示删除 CRD 会连带删除所有该类型的自定义资源实例如果你已经在面板里建过应用这一步等于清空业务配置。实验环境无所谓正式环境务必先导出kubectl get applications -A -o yaml backup.yaml。3. 装 Kubero 的完整动作分解从 Helm 仓库到登录面板3.1 Helm 安装参数逐个说清楚先把仓库加进来并看一眼里面到底有什么。这一步别跳过因为不同版本的 chart 名字和参数会有差异先确认再安装比照抄命令稳得多helm repo add kubero https://kubero-dev.github.io/helm-charts helm repo update helm search repo kuberohelm search repo的输出会告诉你 chart 的准确名称和可用版本。拿到名称后建议先把默认 values 导出来看一眼这一步是我强烈推荐的习惯——不看 values 直接装等于闭着眼睛配参数helm show values kubero/chart-name kubero-values.yaml导出来之后重点看这几组配置它们决定了安装能不能一次成功配置项类别要关注什么配错的典型后果域名相关基础域名、是否启用 TLS、证书来源应用建好了但域名打不开Ingress 相关IngressClass 名称、注解Ingress 创建成功但 404存储相关StorageClass、容量Pod 卡在 Pending镜像仓库用内置仓库还是外部仓库、凭证构建成功但部署时拉不到镜像资源限制控制层和构建层的 requests/limits构建 OOMKilled关于镜像仓库这里做个决策说明。内置仓库的好处是零配置构建完直接推到集群内部拉取也不需要凭证适合入门和单集群场景。缺点是镜像不落到外部跨集群迁移、镜像备份都得另想办法而且内置仓库本身要占持久卷。如果你已经有外部仓库自建或云上的直接用外部仓库更省事长期可维护性也更好——代价是要在面板里配好凭证且节点必须能访问到该仓库。我的建议是第一次跑通就用内置仓库把链路先打通等确认这套东西要长期用了再切外部仓库。一次性把两件事混在一起做出问题时你分不清是仓库配错了还是别的地方错了。安装命令大致长这样参数名以你导出的 values 为准helm install kubero kubero/chart-name \ --namespace kubero \ --create-namespace \ -f kubero-values.yaml \ --timeout 10m--timeout建议显式给长一点。默认 5 分钟在拉镜像慢的环境里很容易超时回滚回滚之后残留资源还得手工清。给到 10 分钟然后耐心等。3.2 首次登录初始凭证从哪来账号怎么改安装完成后第一件事是找登录入口和初始账号。凭证通常由 chart 生成并存在 Secret 里别去翻文档猜直接读集群kubectl get secret -n kubero kubectl get secret 认证相关secret名 -n kubero -o jsonpath{.data} | jq取出来的值是 base64解一下才是明文。用户名一般是固定的管理员账号名密码是一串随机字符。拿到之后通过 Ingress 暴露的地址打开面板登录。登录之后立刻做三件事顺序别乱改密码。初始密码在 Secret 里躺着任何有 Secret 读权限的人都能拿到先改掉。确认基础域名配置。面板里通常有一个全局设置页里面写着当前的基础域名。如果你在 values 里配的和这里显示的不一致说明配置没生效早点发现比部署完应用再发现强。看一眼版本号。记下来后面升级和查文档都对得上。有个细节值得提有些版本的面板在首次登录后会引导你走一个初始化向导里面会让你填 Git 服务商的连接信息。这一步可以跳过等真正要部署应用时再配避免一开始就被一堆 OAuth 配置卡住。入门阶段的目标是「跑通一条链路」不是「把所有集成配全」。3.3 装完必做的四项自检形成你的正常基线装完别急着建应用先花两分钟做自检这四组命令的输出就是你后续排查的参照物。第一项控制层 Pod 是否全部 Runningkubectl get pods -n kubero重点看READY列是不是全都1/1或2/2以及RESTARTS是不是 0。如果某个 Pod 一直CrashLoopBackOff先看日志kubectl logs -n kubero pod名 --previous--previous这个参数很关键容器反复重启时当前实例的日志可能还没写出内容上一次崩溃前的日志才是有效信息。第二项CRD 是否注册成功kubectl get crd | grep -i kubero kubectl get applications,pipelines -A第一条要有输出第二条要不报错没数据是正常的报no matches for kind说明 CRD 没装上安装有问题。第三项Ingress 是否拿到了地址kubectl get ingress -n kubero看ADDRESS列有没有值。为空通常是 Ingress Controller 没在跑或者 IngressClass 指定错了。第四项PVC 是否绑定kubectl get pvc -n kuberoSTATUS必须是Bound。这一项如果不通过后面的应用部署和 Addons 全都会失败而且报错信息会误导你去查别的地方。把这四项的输出存一份到笔记里。以后遇到「面板打不开」或「应用起不来」先跟这份基线比一遍多数问题在五分钟内就能定位到层次。4. 第一个应用从 Git 仓库到可访问域名的全链路4.1 Pipeline 与 Application两个概念别搞混第一次进面板的人最容易在这里迷糊因为很多同类工具只有「应用」一个概念。Kubero 把「环境」和「应用」拆开了理解这个拆分对后面配多环境非常有用。Pipeline可以理解成一条部署通道它绑定一个环境开发、预发、生产都行有自己的命名空间或部署阶段也有自己的配置。Application是业务单元它描述代码从哪来、怎么构建然后被挂到某条 Pipeline 上。同一个应用可以挂到多条 Pipeline 上形成「一份代码、多环境部署」的结构。所以正确的操作顺序是先建 Pipeline再建 Application然后把 Application 关联到 Pipeline。顺序反了也不是不行但面板会一直提示你缺东西徒增困惑。建 Pipeline 时要填的东西不多主要是一个名字和一个阶段标识。名字建议用有语义的短词比如dev、stage、prod因为它会参与域名的拼接也会出现在命名空间或资源标签里起个带特殊字符的名字后面会很别扭。建 Application 时字段多些逐个说一下字段填什么注意点名称应用短名全小写会拼进域名别用下划线和大写Git 仓库地址HTTPS 或 SSH 形式的仓库 URL私有仓库要配凭证见 5.2分支要部署的分支名填错分支会构建一个「看起来成功但内容不对」的镜像构建方式Buildpack 或 Dockerfile选错是最常见的失败原因端口容器实际监听的端口不是你访问的 80/443是应用进程的端口环境变量键值对敏感值单独标记会进 Secret端口这一项特别值得强调。很多人在这里填 80因为「网站不是都访问 80
把一个小服务从本地docker run挪到 Kubernetes 上很多人第一次都会经历同一种挫败本地三条命令就跑起来的东西上了集群突然变成 Deployment、Service、Ingress、IngressClass、TLS 证书、镜像仓库凭证、资源配额一整摞 YAML改个环境变量还要重新kubectl apply。Kubero 解决的正是这一段落差——它把「Git 仓库 → 构建 → 部署 → 域名可访问」这条链路收进一个自托管面板里底层依然是你自己的 Kubernetes 集群但操作手感回到了「推代码、等构建、打开网页」的节奏。这篇内容面向已经有一台能用的 K8s 集群、但还没在上面跑过自己业务应用的读者从集群体检、Helm 安装、面板登录一直走到第一个应用拿到可访问域名中间会把每一步「为什么这么配」讲透也会把我在实际集群里踩到的几个典型坑和排查链路完整摊开。读完你应该能在半小时内跑通全流程并且知道出问题时先看哪里。1. Kubero 到底把 Kubernetes 的哪一层复杂度藏起来了1.1 从 kubectl apply 到 git push真正被替换掉的是什么先把这个工具的定位说清楚否则很容易误判它的能力边界。Kubero 不是一个「简化版 Kubernetes」也不是把 kubectl 包了一层的命令行工具它是跑在你集群内部的一个应用交付层自己带 Web 面板、带 API 服务、带一组自定义资源CRD你通过面板描述「我要一个应用代码在哪个 Git 仓库用哪个分支跑在哪个环境」它负责把这些描述翻译成 Kubernetes 原生对象——Deployment、Service、Ingress、ConfigMap、Secret、PVC然后交给集群去执行。这意味着两件事。第一你的集群仍然是集群节点、调度、网络、存储这些基础设施层面的东西一点没少Kubero 不帮你买机器也不帮你配 CNI它只接管「应用怎么上去」这一段。第二它产出的仍然是标准 K8s 资源你随时可以kubectl get deploy -n 命名空间看到真实落地的东西不会出现「面板上一切正常但集群里啥也没有」的黑箱感。这一点在做故障排查时非常关键后面第 5 节的所有排查动作本质上都是「面板描述」和「集群实况」之间的对照。被替换掉的具体动作可以列成一张对照表理解这张表比记住任何命令都有用传统手工流程Kubero 里的等价物底层实际产出手写 Dockerfile 或判断该用哪种构建方式选 Buildpack 或 Dockerfile 模式集群内的构建 Pod 构建产物镜像手动 build、tag、push 到镜像仓库提交代码触发自动构建镜像推送到内置或外部 Registry手写 Deployment YAML 并 apply面板里填应用信息Deployment ReplicaSet Pod手写 Service 做端口映射填容器端口ClusterIP Service手写 Ingress 配证书填域名后缀Ingress TLS Secret手动建 ConfigMap / Secret 挂环境变量面板里加键值对ConfigMap / Secret手动拉数据库并配连接串添加 Addon由 Operator 管理的数据库实例看表格最后一列你会发现没有任何一步被跳过只是被收敛成了一次表单填写。这是理解 Kubero 价值的前提它省的是重复劳动和心智负担不是省掉集群本身的运维责任。很多团队上线后觉得「用了面板怎么还这么麻烦」问题往往出在把面板当成了托管服务忘了节点资源、存储类、Ingress 控制器这些还是得自己管。1.2 拆开面板看Kubero 在你的集群里造了哪些东西安装完 Kubero 之后集群里会多出一批东西认识它们能让你在出问题时知道往哪看。按职责可以分成四层。控制层一个 Web UI 服务加一个 API 服务通常跑在独立的命名空间里默认就叫kubero。UI 只是前端真正干活的是 API它持有集群内的 ServiceAccount通过 RBAC 权限去创建和修改资源。所以 API 这个 Pod 挂了面板就转圈但已经部署的应用完全不受影响——这是排查时第一条要分清的事面板故障和业务故障是两件事。自定义资源层Kubero 定义了几个 CRD最核心的是Application一个应用和Pipeline一条部署流水线对应一个环境。面板上你点的每一个按钮最终都是对这两个 CRD 的增删改查然后由一个 Operator 或控制器把它们翻译成原生对象。想知道面板背后到底发生了什么kubectl get applications -A -o yaml比点面板有效得多。构建层每次部署会起一个构建 Pod在集群内部完成代码拉取、依赖安装、镜像打包。这是 Kubero 和「纯 GitOps 方案」最大的区别——它的构建发生在集群里而不是在你的 CI runner 上。好处是配置简单、不用自建 CI代价是构建会消耗集群资源构建失败时你得去翻构建 Pod 的日志而不是流水线页面。运行时层真正跑业务的 Deployment 和 Pod默认会被放到独立的命名空间里按 Pipeline 隔离。这一层是纯标准的 K8s 工作负载用任何你熟悉的工具都能观测。我一般建议安装完成后先花两分钟把这四层对应的 Pod 和资源都get一遍形成一个「正常基线」。没有基线出问题时你连「这是不是本来就这样」都判断不了。后面第 3 节会给出具体的自检命令清单。1.3 适用与不适用别把入门工具当生产平台的全部说句实在话Kubero 最舒服的场景是这几类个人或小团队的自建服务、内部工具、演示环境、教学实验、多环境开发/预发/生产需要快速铺开的单体应用。它的优势在于「一条链路全包」——从源码到域名中间不用接第二个系统。但如果你的需求是这几类就得掂量一下需要严格的审批流和变更审计那得上真正的 GitOps 加策略引擎、需要复杂的多集群分发那得上集群编排层、需要极细粒度的资源配额和成本分摊面板给的配额控制相对粗、需要自定义构建缓存策略和并行度自建 CI 更灵活。还有一个容易被忽略的点Kubero 对「应用」的抽象是偏单体/小服务的。一个仓库一个应用构建产物一个镜像。如果你要跑的是十几个微服务互相调用虽然可以建十几个应用但服务间调用、链路追踪、统一网关这些事它不负责你得自己在集群里解决。我在一个模拟项目里试过用它铺五六个服务能跑但接线工作全在集群侧手工做面板只帮了部署那一段。认清这条边界能省掉很多「为什么它不支持某某功能」的困惑。2. 动手之前的集群体检那些看起来能跑却没跑起来的坑2.1 集群版本、容器运行时与存储类的三项硬指标很多人卡在第一步不是因为命令敲错而是因为集群缺了某个「默认没人装」的组件。装之前建议按下面三项过一遍。版本集群版本别太老建议次新版本往上。控制器和 CRD 依赖的 API 版本在老集群上可能已经被废弃或还没引入表现是安装时直接报no matches for kind。查一下kubectl version --short容器运行时与架构Kubernetes 早就不直接管 Docker 了走的是 CRI。这本身对 Kubero 没影响但要注意两点——节点架构如果是 ARM比如很多开发板或某些云的低价机型构建阶段的部分镜像未必有 ARM 版本会出现构建 Pod 一直ImagePullBackOff以及节点上的容器运行时如果配置了私有仓库白名单构建产出的镜像推送可能被拦。这两点都属于「装得下来但跑不起来」的隐性坑。存储类StorageClass这是最容易漏的一项。Kubero 自身需要持久卷存配置和构建数据Addons 里的数据库更是必须持久化。如果你的集群是kubeadm手动搭的裸机集群很可能根本没有默认 StorageClass表现是 PVC 一直Pending面板装完但 Pod 起不来。查一下kubectl get storageclass输出里带(default)标记的那一行就是默认存储类。如果一条都没有就得先装一个本地环境常见的做法是装个基于本地磁盘的 provisioner云上一般直接用云厂商的块存储类并把其中一个标成默认。这一步没做后面所有涉及持久化的环节都会连锁失败。另外提一句资源。整套东西跑起来控制层加构建层建议给集群预留至少 2 核 4G 的空闲可调度资源构建时会有明显的瞬时占用峰值。1 核 2G 的单节点实验集群能装能跑但构建稍微大一点的应用就会因为内存不足被 OOMKilled报错信息还相当隐晦构建 Pod 状态显示 Error日志戛然而止。2.2 Ingress Controller 与通配符域名多租户入口的隐藏前提这是整套流程里技术含量最高、也最容易翻车的一环值得单独展开。Kubero 给每个应用分配域名的逻辑是子域名拼接你在配置里填一个基础域名比如apps.example.internal应用名加环境名拼在前面形成myapp-staging.apps.example.internal这样的完整域名。这种设计的好处是新增应用零配置坏处是对 DNS 和证书提出了一个硬性要求——必须支持通配符。DNS 侧你需要一条通配符记录*.apps.example.internal A 你的 Ingress 入口 IP apps.example.internal A 你的 Ingress 入口 IP很多人只配了带星号那条结果访问基础域名做健康检查时解析不到误以为是 Ingress 坏了。两条都配上成本很低。证书侧更麻烦一点。如果走 HTTP 自动签发必须用 DNS-01 挑战而不是 HTTP-01因为通配符证书没法用 HTTP 挑战验证。这意味着你得给证书管理器配上 DNS 服务商的 API 凭证这一步在本地/内网环境里往往做不了那就退回到两条路一是用自签证书并在浏览器里手动信任内部工具完全够用二是只对单个应用域名签发普通证书牺牲了「新增应用零配置」的便利。Ingress 控制器本身集群里必须已经有一个在工作的 Ingress Controller并且它监听的是你规划的那组入口地址。Kubero 安装时会指定使用哪个 IngressClass如果集群里有多个控制器比如同时装了两种指定错了就会出现「Ingress 对象创建成功、外部访问 404」的经典现象。查一下现有控制器和它的 Class 名kubectl get ingressclass kubectl get pods -A | grep -i ingress把 Class 名记下来安装时明确填进去别依赖默认值。默认值这东西在你只有一个控制器时很稳一旦多装了一个就会悄悄变。2.3 Helm 与 kubectl 的版本匹配这条隐形依赖Kubero 通过 Helm Chart 安装所以本机得有 Helm且版本不要太老建议 3.8 以上。老版本 Helm 对 OCI 仓库和某些 chart 特性的支持不全报错信息通常是failed to download之类看起来像网络问题实际是版本问题。helm version --short kubectl version --client --short还有个细节Helm 的 release 是带状态的如果你装了一半想重来直接再helm install同名 release 会报cannot re-use a name that is still in use。正确的收尾方式是先helm uninstall但要注意卸载 Helm release 默认不会删除 CRD 和 PVC这些残留会在下次安装时造成冲突尤其是 CRD 版本不一致导致field is immutable这类错误。我第一次重装时就栽在这正确的清理顺序是helm uninstall kubero -n kubero kubectl delete pvc --all -n kubero # CRD 谨慎删除确认里面没有你想保留的业务数据 kubectl get crd | grep -i kubero提示删除 CRD 会连带删除所有该类型的自定义资源实例如果你已经在面板里建过应用这一步等于清空业务配置。实验环境无所谓正式环境务必先导出kubectl get applications -A -o yaml backup.yaml。3. 装 Kubero 的完整动作分解从 Helm 仓库到登录面板3.1 Helm 安装参数逐个说清楚先把仓库加进来并看一眼里面到底有什么。这一步别跳过因为不同版本的 chart 名字和参数会有差异先确认再安装比照抄命令稳得多helm repo add kubero https://kubero-dev.github.io/helm-charts helm repo update helm search repo kuberohelm search repo的输出会告诉你 chart 的准确名称和可用版本。拿到名称后建议先把默认 values 导出来看一眼这一步是我强烈推荐的习惯——不看 values 直接装等于闭着眼睛配参数helm show values kubero/chart-name kubero-values.yaml导出来之后重点看这几组配置它们决定了安装能不能一次成功配置项类别要关注什么配错的典型后果域名相关基础域名、是否启用 TLS、证书来源应用建好了但域名打不开Ingress 相关IngressClass 名称、注解Ingress 创建成功但 404存储相关StorageClass、容量Pod 卡在 Pending镜像仓库用内置仓库还是外部仓库、凭证构建成功但部署时拉不到镜像资源限制控制层和构建层的 requests/limits构建 OOMKilled关于镜像仓库这里做个决策说明。内置仓库的好处是零配置构建完直接推到集群内部拉取也不需要凭证适合入门和单集群场景。缺点是镜像不落到外部跨集群迁移、镜像备份都得另想办法而且内置仓库本身要占持久卷。如果你已经有外部仓库自建或云上的直接用外部仓库更省事长期可维护性也更好——代价是要在面板里配好凭证且节点必须能访问到该仓库。我的建议是第一次跑通就用内置仓库把链路先打通等确认这套东西要长期用了再切外部仓库。一次性把两件事混在一起做出问题时你分不清是仓库配错了还是别的地方错了。安装命令大致长这样参数名以你导出的 values 为准helm install kubero kubero/chart-name \ --namespace kubero \ --create-namespace \ -f kubero-values.yaml \ --timeout 10m--timeout建议显式给长一点。默认 5 分钟在拉镜像慢的环境里很容易超时回滚回滚之后残留资源还得手工清。给到 10 分钟然后耐心等。3.2 首次登录初始凭证从哪来账号怎么改安装完成后第一件事是找登录入口和初始账号。凭证通常由 chart 生成并存在 Secret 里别去翻文档猜直接读集群kubectl get secret -n kubero kubectl get secret 认证相关secret名 -n kubero -o jsonpath{.data} | jq取出来的值是 base64解一下才是明文。用户名一般是固定的管理员账号名密码是一串随机字符。拿到之后通过 Ingress 暴露的地址打开面板登录。登录之后立刻做三件事顺序别乱改密码。初始密码在 Secret 里躺着任何有 Secret 读权限的人都能拿到先改掉。确认基础域名配置。面板里通常有一个全局设置页里面写着当前的基础域名。如果你在 values 里配的和这里显示的不一致说明配置没生效早点发现比部署完应用再发现强。看一眼版本号。记下来后面升级和查文档都对得上。有个细节值得提有些版本的面板在首次登录后会引导你走一个初始化向导里面会让你填 Git 服务商的连接信息。这一步可以跳过等真正要部署应用时再配避免一开始就被一堆 OAuth 配置卡住。入门阶段的目标是「跑通一条链路」不是「把所有集成配全」。3.3 装完必做的四项自检形成你的正常基线装完别急着建应用先花两分钟做自检这四组命令的输出就是你后续排查的参照物。第一项控制层 Pod 是否全部 Runningkubectl get pods -n kubero重点看READY列是不是全都1/1或2/2以及RESTARTS是不是 0。如果某个 Pod 一直CrashLoopBackOff先看日志kubectl logs -n kubero pod名 --previous--previous这个参数很关键容器反复重启时当前实例的日志可能还没写出内容上一次崩溃前的日志才是有效信息。第二项CRD 是否注册成功kubectl get crd | grep -i kubero kubectl get applications,pipelines -A第一条要有输出第二条要不报错没数据是正常的报no matches for kind说明 CRD 没装上安装有问题。第三项Ingress 是否拿到了地址kubectl get ingress -n kubero看ADDRESS列有没有值。为空通常是 Ingress Controller 没在跑或者 IngressClass 指定错了。第四项PVC 是否绑定kubectl get pvc -n kuberoSTATUS必须是Bound。这一项如果不通过后面的应用部署和 Addons 全都会失败而且报错信息会误导你去查别的地方。把这四项的输出存一份到笔记里。以后遇到「面板打不开」或「应用起不来」先跟这份基线比一遍多数问题在五分钟内就能定位到层次。4. 第一个应用从 Git 仓库到可访问域名的全链路4.1 Pipeline 与 Application两个概念别搞混第一次进面板的人最容易在这里迷糊因为很多同类工具只有「应用」一个概念。Kubero 把「环境」和「应用」拆开了理解这个拆分对后面配多环境非常有用。Pipeline可以理解成一条部署通道它绑定一个环境开发、预发、生产都行有自己的命名空间或部署阶段也有自己的配置。Application是业务单元它描述代码从哪来、怎么构建然后被挂到某条 Pipeline 上。同一个应用可以挂到多条 Pipeline 上形成「一份代码、多环境部署」的结构。所以正确的操作顺序是先建 Pipeline再建 Application然后把 Application 关联到 Pipeline。顺序反了也不是不行但面板会一直提示你缺东西徒增困惑。建 Pipeline 时要填的东西不多主要是一个名字和一个阶段标识。名字建议用有语义的短词比如dev、stage、prod因为它会参与域名的拼接也会出现在命名空间或资源标签里起个带特殊字符的名字后面会很别扭。建 Application 时字段多些逐个说一下字段填什么注意点名称应用短名全小写会拼进域名别用下划线和大写Git 仓库地址HTTPS 或 SSH 形式的仓库 URL私有仓库要配凭证见 5.2分支要部署的分支名填错分支会构建一个「看起来成功但内容不对」的镜像构建方式Buildpack 或 Dockerfile选错是最常见的失败原因端口容器实际监听的端口不是你访问的 80/443是应用进程的端口环境变量键值对敏感值单独标记会进 Secret端口这一项特别值得强调。很多人在这里填 80因为「网站不是都访问 80
