本文首发于 栏轩·阁欢迎访问阅读原文获取更好的阅读体验。任务从 Gitee 仓库拉取 FastAPI 项目代码构建 Docker 镜像部署到 KubeSphere 管理的 Kubernetes 集群最终通过浏览器访问应用。环境操作系统Windows 11Docker Desktop内置 Kubernetes 集群KubeSphere v4.2.0容器管理平台代码语言Python FastAPI容器镜像fastapi-demo:latest1. 创建凭证KubeSphere 里配置 Gitee 的登录凭据选择用户名和密码类型。注意GitRepository CRD 只支持basic-auth凭据不支持 SSH 私钥。2. 创建 DevOps 项目在 KubeSphere 控制台进入目标企业空间 →DevOps 项目→ 创建 DevOps 项目。DevOps 项目用于管理流水线及其运行记录与普通项目管理应用负载是分开的。3. 创建流水线在 DevOps 项目下选择创建流水线→多分支流水线→ 关联 Gitee 仓库和凭据 → 创建。4. 踩坑Docker 构建和部署正常情况下的流程一般来说流水线的过程是KubeSphere 创建 Agent 容器builder-base 镜像 → Agent 里有 docker CLI → 通过 docker.sock 调用宿主机上的 Docker Daemon → 实现 docker build、docker runDocker Desktop 的架构缺陷Docker Desktop on Windows 的 Kubernetes 运行在 Linux VM 中使用containerd作为容器运行时没有运行 Docker Daemon。因此 Agent 容器里的 docker.sock 无法连接任何 Daemondocker build和docker run无法执行。# 验证容器运行时kubectl get nodes-owide# → CONTAINER-RUNTIME: containerd://2.2.0尝试过的方案均未成功方案结果改用 podman❌ Agent 里同样找不到curl 下载静态 docker 二进制✅ CLI 能运行但连不上 dockerd容器以 root 运行✅ 能访问 socket但 VM 里没有 dockerdDocker-in-Docker 侧边容器❌ 需特权模式端口映射到容器内部无法访问最终解决方案换了一种思路不在 Pipeline 中构建镜像改为本地手动构建Pipeline 只做部署。本机docker build -t fastapi-demo:latest . ← 本机 dockerd 正常构建 git push ← 触发 Pipeline Pipeline Agentkubectl apply -f deploy.yaml ← 直接用现有镜像部署 kubectl rollout status ... ← 等待 Pod 就绪Docker Desktop 的 K8s 集群共享本机的镜像存储所以本机构建的镜像 K8s 可以直接拉取无需推送仓库。需要额外配置的权限默认的 AgentServiceAccount:kubesphere-devops-worker:default没有权限在其他命名空间部署资源需要授权# 创建角色Role允许在 fastapi 命名空间里操作 deployments、services、podskubectl create role deployer-nfastapi\--verb*\--resourcedeployments,services,pods# 绑定角色RoleBinding把 deployer 角色绑定到 Pipeline Agent 的 ServiceAccount# 这样 Agent Pod 就有权限在 fastapi 命名空间里执行 kubectl apply 了kubectl create rolebinding deployer-binding-nfastapi\--roledeployer\--serviceaccountkubesphere-devops-worker:default4. 最终部署效果FastAPI 应用部署在 KubeSphere 的fastapi项目下对应 K8s 命名空间可以在控制台可视化查看工作负载和服务Deploymentfastapi1 PodServicefastapiLoadBalancer端口 8000访问地址http://localhost:8000最终 deploy.yamlapiVersion:apps/v1kind:Deploymentmetadata:name:fastapi# Deployment 名称namespace:fastapi# 部署到 fastapi 命名空间对应 KubeSphere 项目spec:replicas:1# 运行 1 个 Pod 副本selector:matchLabels:app:fastapitemplate:metadata:labels:app:fastapispec:containers:-name:fastapiimage:fastapi-demo:latest# 使用本机构建的镜像imagePullPolicy:IfNotPresent# 本地有就直接用不远程拉取ports:-containerPort:8000# 容器内 FastAPI 监听端口livenessProbe:# 存活检查/health 挂了就重启 PodhttpGet:path:/healthport:8000readinessProbe:# 就绪检查/health 通了才接收流量httpGet:path:/healthport:8000---apiVersion:v1kind:Servicemetadata:name:fastapi# Service 名称namespace:fastapispec:type:LoadBalancer# LoadBalancer 类型Docker Desktop 会映射到 localhostports:-port:8000# 外部访问端口targetPort:8000# 转发到容器的 8000 端口selector:app:fastapi# 关联到上面 Deployment 的 Pod最终 Jenkinsfilepipeline{// Agent 配置在 K8s 上创建临时 Pod 来跑流水线agent{kubernetes{inheritFrombase// 继承 KubeSphere 的 base Agent 模板含 docker.sock 挂载等containerTemplate{namebase// 容器名称imageswr.cn-north-9.myhuaweicloud.com/ks/kubesphere/builder-base:v4.2.0// Agent 镜像含 git、kubectlttyEnabledtruecommandcat// 保持容器运行等待 Jenkins 下发指令runAsUser0// 以 root 运行kubectl 需要读写 kubeconfig}}}stages{// 第 1 步从 Gitee 拉取代码stage(拉取代码){steps{checkout scm}// scm 自动关联流水线配置的 Gitee 仓库}// 第 2 步部署到 Kubernetesstage(部署到 Kubernetes){steps{script{// 使用 deploy.yaml 创建/更新 Deployment 和 Serviceshkubectl apply -f deploy.yaml// 等待 Pod 就绪最多等 60 秒shkubectl rollout status deployment -l app -n fastapi --timeout60s}}}}post{success{echo✅ 部署成功}failure{echo❌ 部署失败}}}总结问题错误信息根因方案Docker 构建docker: not found/Cannot connectDocker Desktop K8s VM 无 Docker Daemon本机构建 kubectl 部署K8s 部署deployments is forbiddenAgent SA 无权限创建 Role RoleBinding结论Docker Desktop 的架构限制VM 隔离导致 docker.sock 不通导致 Pipeline 无法直接构建部署。在真正的 Linux 服务器上部署 K8s 时Docker 构建这一步可以直接在 Pipeline 中完成无需本地手动构建。