背景

目前在公司内我负责的活主要是 AI 的一些基础管线的开发，包括对外提供服务的接入端点，然后一些管理系统的搭建，再就是部署集群的搭建，基础管线实际上是之前就有一版本 Python 的，按照那个架构进行重构就行了，我做的部分比较少，主要还是一些稳定性的功能优化。最近这一周主要的工作还是在 K8S 集群搭建上面，虽然熟练使用 Docker，但是也是在真实环境下自己搭建内部的开发 K8S 集群，还是感觉学到不少东西的。所以感觉有必要开一篇文章记录一下。

技术栈

其实在这方面我也算是有一丢丢经验，之前在第二家公司就搭建了一整套的内网开发环境，包括自建 Gitea、Github Action、Runner 等等，不过这次微服务比较多，而且也是需要模拟线上环境，就得使用 K8s 了。

在和 Claude Opus 4.7 Copilot 后的推荐方案大概如下，也是目前比较主流的开源方案：

• 设备：Mac Studio M2 Max 32GB
• Kubernetes / K3S
• Rancher 可视化面板
• ArgoCD 自动发布
• GitOps 管理集群环境和配置
• Cloudflare Tunnal 内网穿透

需求

我们小组是承担了业务方面的 90% 的开发了，比如底层基座，还有我负责的面向开发者和 C 端用户的后端以及管理后台的前后端，所以搭建下来的微服务组件大概就有 20 多个，并且需要提供一套稳定的系统给其他组的同事进行测试，也需要一套我们组内自己快速迭代的集群用于测试，所以这个活也就落到我头上了，为了满足这个需求也是踩了不少坑。

1. Docker Compose

为了快速拉起服务，就选择了这个方案，写好 docker-compose.yaml 就能迅速拉起来多套集群，并且使用 mac 上的 OrbStack 也是非常迅速，这部分还是很得心应手的，只是一些基础服务都没搭建，比如镜像仓库、Github Action 等等。

使用的方案也是非常简单，直接本地 Docker Build 打包后直接 SCP 到服务器上，然后启动。然后使用 Traefik 来做内网域名映射，Dnsmasq 来支持内网的 DNS 解析。

虽然非常简陋，但是也是能够支持快速的上线调试要求了，就是苦了我 🥹，每个人都得让我手动给他们部署组件，不过好在还有 Claude 辅助，能大大提高工作效率了。（这部分还是需要谨慎的，一旦出事直接就会爆炸）

2. Komodo

每个组件的一些配置需要经常变动，而且直接操作服务器的话，也不太方便，就想着搭建一个可视化的管理面板，通过面板来管理集群，这样也方便。于是检索了一些方案，经过对比之后决定使用 Komodo 来搭建。

• Komodo：可视化多服务器管理、容器管理、Stacks、编排构建等
• Dockge：几乎就是"compose 文件的 Web 编辑器 + 启停按钮"，极简。
• Portainer CE：功能多但界面更复杂，compose 在它那叫 “Stacks” 但体验不如 Komodo 原生。
• Dozzle：只看日志，不做管理。

Komodo 支持按照 Stacks 来管理集群，也支持多服务器部署，但是由于我们只有一台 Mac 所以就用不到这个功能了。部署好以后，界面感觉还是非常干净的，没有花里胡哨的功能，一眼能看到那个功能该去哪里找。但是因为不支持 K8S 所以这个搭建好了之后，也没有使用几天就废弃了，转到 Rancher + Argo CD 了。

3. K8S

因为公司提供的设备就只有一台内网环境下的 Mac Studio，也就是说只能部署单节点的 K8S，由于经常性的使用 OrbStack，并且还集成了 K8s 的功能，直接可以开始部署集群，所以也是紧锣密鼓的开始搭建了，然后选择了 Rancher 可视化管理和 ArgoCD 来做自动发布。

直接开了两个集群 stable 和 dev，一股脑将组件拉起来，算上一些基础依赖组件两套集群拉起来后大概就有 90 多个 pod，至此能够满足公司目前的使用是没有问题的，按理来说到这里部署的工作就应该完成了，该去做自动发布构建的了。但是我看了一眼 Rancher 的后台，最多只支持 110 个 Pod，这个怎么能行，按照组件的资源量预估了一下，单机抗 500 Pod 应该是没啥问题，所以就想着将 Pod 数量调整到 500，由于 K8s 中每个 Pod 都是需要占用一个 IP 的，所以这里就必须调整划分给 OrbStack 的 CIDR，默认是 /25 128 个 ip，那直接将这个数字改成 /23 就能支持 512 个 IP，也就能满足我的需求，但是修改 OrbStack 的配置死活不生效，修改好了，就会被修改回去。

大概查了一下，OrbStack 自带的 K8S 没有开放修改的端点，应该还是直接写死的，所以这里没法满足我的需求，就开始想办法了，既然自带的不能满足，那就自己搭一个就行了，于是这里我就选择了使用 OrbSatck 里面的 VM 虚拟机，创建了一个 Ubuntu 24.04，然后在这个里面去搭建 K3S 集群，就能自己随意配置了。

说干就干，立马创建好了虚拟机环境，就得开始迁移 pod 了，这里偷懒使用 Codex GPT 5.5 来进行迁移，按照理想情况下，应该是在迁移完成以后，写好项目的组件服务文档，但是意外出现了，在迁移的过程中，OrbStack 突然闪退，我正在监控的活动监视器中的内存使用突然骤降，我就感觉事情不太妙，结果一看 OrbStack 挂了，里面的所有镜像和 VM 都丢了。

这下炸了，近乎 10 几个组件的 images 都是托管在这个里面的 Harbor 内的，导致所有数据全部丢失，并且没有备份，查了一下这个情况出现的挺多的，也没法找回，只能重新搭建了。

4. GitOps

于是赶紧和 Claude 商讨了一版方案出来，推荐将集群的管理抽离到 Git 仓库中，这样方便 Action 修改集群配置，于是新版本最终定的架构是 Rancher 做可视化面板进行管理，ArgoCD 来做自动发布，GitOps 来做集群、配置管理。这样子如果一旦服务器崩溃，数据在没有备份的情况下，还能通过 GitOps 中的配置来快速进行恢复，并且也方便后续发布上线。

所以最终的架构是修改 GitOps 仓库中的配置 push 后，就自动能更新对应集群的 pod，并且各个组件的仓库的 push 和 tag 也会触发 Action 去执行修改 GitOps 仓库的配置，以实现控制集群并且能够进行追溯回滚的效果。

个人感觉这种方案是目前的最优解，既能对配置进行管理，还能实现版本控制，也能实现自动化。

所以目前公司的两套服务都部署在 Ubuntu 上的 K8S 内，截止现在还稳定运行，希望能撑过 5.1 休假期间，也能够验证服务的稳定性了。

踩坑

部署中其他组件都比较顺利，唯一遇到的比较坑的就是因为使用的 Cloudflare 的 Tunnal 穿透，然后像让 Github Action Runner 到 Harbor 走内网，并且接入的端点域名不变，也就是在内网环境下就走内网，内网不通就走外网。

这里 Cloudflare 的话是只支持 100MB 的 TCP 传输的，一旦镜像大小超过 100MB，就没法支持了，所以这里只能做切块或者走内网了，为了速度和安全，这块就配置内网。

但是内网的话，一直报 tls 问题，三种错前后都赶上了一遍。

最开始是 Runner 跑 docker push 直接 x509: certificate signed by unknown authority，Harbor 起来用的是自签证书，containerd 默认根本不认这条链。想着把 CA 装进去就完事了，结果一看证书的 SAN，跟实际访问的内网域名压根对不上，错误立马变成 x509: certificate is valid for X, not Y。

更头疼的是 DNS 劈裂这一刀：同一个 harbor.xxx 域名，公网走 Cloudflare 边缘（拿到的是 CF 证书）、内网通过 Dnsmasq 解析到 Mac Studio 的内网 IP（拿到的是 origin 自签证书），公私两套完全分裂。Runner 在内网拿到的永远是 origin cert，本地信任链里啥都没有，怎么连都不对。

最后分两头修：

1. Harbor 那边：重新签证书，把内网域名、内网 IP、公网域名全部塞进 SAN，至少让"看到什么证书"这件事先统一掉，不再因为域名对不上来回跳错。
2. Runner / containerd 这边：把 Harbor 的 CA 挂进 /etc/containerd/certs.d/<host>/ca.crt，让 containerd 真信任这条链。个别历史遗留的 Runner 时间紧没法马上重启刷配置的，临时上 insecure_skip_verify = true 先把流水线跑通再说，后面排期重启时再补。

K8s 多节点还有个隐藏的烦人点：每加一台 worker 都得把 CA 同步进去，不像 docker 那么直接，所以这套证书分发也顺手写进 GitOps 仓库的 init job 里，新节点起来自动跑一遍，不然每加一台都得手动配，又是一坨重复劳动。