最近在和一些做自动化测试和持续集成的朋友聊天发现一个挺有意思的现象很多人一听到“Agent”这个词第一反应就是“AI智能体”想到的是能自主决策、能理解复杂指令的AI助手。但当我提到“Harness Agent”时他们往往会愣一下然后问“这也是AI Agent吗和LangChain、AutoGPT那些有什么区别”这恰恰是很多开发者尤其是刚接触Harness平台的朋友最容易走弯路的地方。Harness Agent本质上不是一个“智能体”而是一个执行器一个连接器一个工作流中的可靠节点。它的核心价值不在于“思考”而在于“执行”和“连接”——把你在Harness平台上定义好的那些流水线、部署策略、安全策略精准、可靠地分发到你的目标环境无论是Kubernetes集群、物理服务器还是云虚拟机上去执行。如果你抱着“找一个能自己写代码、自己部署的AI”的期望去学习Harness Agent那从一开始方向就偏了后续的配置、排错都会变得异常艰难。这篇文章我们就来彻底理清Harness Agent到底是什么以及如何从零开始搭建一个稳定、高效的执行环境真正让你在CI/CD和GitOps的道路上少走那99%的弯路。1. 先搞明白Harness Agent到底在解决什么问题在深入命令行和配置文件之前我们必须先建立一个正确的认知框架Harness Agent是Harness平台架构中的关键一环它解决的是**“最后一公里”的执行问题**。想象一下这个场景你在Harness SaaS平台或自托管版上精心设计了一条CI流水线它要完成代码拉取、构建、测试、打包镜像、安全扫描最后部署到你的生产Kubernetes集群。前几步都在Harness平台提供的构建农场Build Farm或你指定的云环境中完成了但最后一步——“部署到我的集群”——这个动作必须在你自己的、受防火墙保护的、可能没有公网IP的集群内部发生。这时Harness平台无法直接“伸手”进去操作。怎么办答案就是Harness Agent。你需要在你的目标环境比如Kubernetes集群或某台Linux服务器内部署一个Agent。这个Agent会主动、安全地连接到Harness平台然后像一个忠诚的哨兵接收来自平台的指令并在本地环境中执行。所以Harness Agent的核心职责非常明确建立安全连接作为客户端通过出站连接Outbound Connection连接到Harness控制平面避免了在防火墙为控制平面开入站端口的麻烦和安全风险。接收并执行任务监听来自Harness平台下发的任务如执行一个Shell脚本、应用一个Kubernetes Manifest、运行一个Terraform Plan等。上报状态与日志将任务执行的状态、进度以及产生的所有日志实时地流式传输回Harness平台让你在UI上就能清晰看到每一步发生了什么。理解了这一点你就会明白配置Harness Agent的重点不在于训练它做什么而在于如何为它建立一个稳定、安全、有足够权限的网络通道和执行环境。很多“弯路”都源于网络不通、权限不足、资源不够这些基础设施问题而非Agent本身有多复杂。2. 从零开始部署你的第一个Harness Agent以Kubernetes为例理论清楚了我们进入实战。目前Harness Agent最主要的部署模式就是在Kubernetes集群中作为Deployment运行。下面是一个从零开始的保姆级流程我会穿插解释每个步骤的“为什么”而不仅仅是“怎么做”。2.1 环境与权限准备万事开头难在下载任何YAML文件之前请先确认好这三件事目标Kubernetes集群访问权限你需要有足够的权限通常是cluster-admin或能创建Namespace、Deployment、ServiceAccount、ClusterRoleBinding的权限在目标集群中部署应用。Harness平台连接信息你需要从Harness平台获取三个关键信息Account Id你的Harness账户ID。Delegate Token代理令牌。这是Agent向平台证明自己身份的关键相当于一个密码。你需要在Harness平台的“项目管理” - “代理”页面中创建。Manager EndpointHarness控制平面的地址。对于SaaS用户通常是https://app.harness.io或https://app.harness.io/gratis等对于自托管用户就是你部署的Harness Manager的URL。网络连通性确保你的Kubernetes集群内的Pod能够通过出站连接访问到上一步的Manager Endpoint。这是最常出问题的地方可以通过在集群内启动一个临时Pod执行curl命令来测试。2.2 获取并定制部署清单Harness官方提供了标准的Agent部署YAML模板。不要直接使用理解并修改它才是关键。# 通常你可以从类似下面的位置获取最新模板请以官方文档为准 # curl -o harness-delegate.yaml https://raw.githubusercontent.com/harness/delegate-kubernetes-manifest/main/harness-delegate.yaml我们重点关注模板中需要你修改的部分# 示例片段非完整文件 apiVersion: v1 kind: Namespace metadata: name: harness-delegate-ng # 建议的Namespace可以自定义 --- apiVersion: apps/v1 kind: Deployment metadata: name: harness-delegate namespace: harness-delegate-ng spec: ... template: spec: containers: - image: harness/delegate:yy.mm.verno # 注意版本号务必使用稳定版而非latest imagePullPolicy: Always env: - name: ACCOUNT_ID value: 你的AccountId # 替换点1 - name: DELEGATE_TOKEN value: 你的DelegateToken # 替换点2这是核心机密务必保密 - name: MANAGER_HOST_AND_PORT value: app.harness.io # 替换点3你的Manager Endpoint - name: DELEGATE_NAME value: my-k8s-delegate # 替换点4为你的Agent起个有意义的名字 - name: DELEGATE_TYPE value: KUBERNETES - name: DEPLOY_MODE value: KUBERNETES - name: INIT_SCRIPT value: # 替换点5可选初始化脚本可用于安装特定工具 resources: limits: memory: 2048Mi cpu: 1000m requests: memory: 1024Mi cpu: 500m关键修改点解析版本号 (image: harness/delegate:yy.mm.verno)绝对不要使用latest标签。去Harness官方发布页或文档选择一个与你的Harness平台版本兼容的稳定版本。版本不匹配是启动失败的常见原因。Delegate Token这是最高机密。任何拥有此Token的人都可以向你的Harness平台注册代理。确保YAML文件的安全考虑使用Kubernetes Secret来存储并在部署后清理包含明文Token的文件。Delegate Name取一个描述性的名字如prod-us-east-1-k8s。这在管理多个Agent时至关重要。资源限制 (Resources)默认配置可能偏低。对于生产环境根据你预计Agent要执行的任务复杂度是否需要运行Docker构建、helm命令等适当调高limits和requests。资源不足会导致Agent进程被OOM Kill表现为Agent频繁重启或失联。Init Script这是一个强大的功能。如果你的部署流程需要特定工具如helm,kustomize,aws-cli,terraform可以在这里通过脚本预先安装。例如value: curl -sSL https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash2.3 执行部署与验证应用配置好的YAML文件kubectl apply -f harness-delegate.yaml然后通过以下命令观察部署状态# 查看Pod状态应变为Running kubectl get pods -n harness-delegate-ng -w # 查看Pod日志这是排错的第一现场 kubectl logs -f deployment/harness-delegate -n harness-delegate-ng健康的日志特征你会看到Agent成功连接到MANAGER_HOST_AND_PORT打印出“Delegate started”之类的消息并在Harness平台UI的“代理”列表中看到名为my-k8s-delegate你设定的名字的Agent状态变为“已连接”且心跳正常。如果日志卡在连接阶段或报错请立即进入下一章的排错环节。3. 避开深坑实战中90%的问题排查指南Agent部署失败或运行不稳定绝大多数问题出在以下几个方面。请按照这个顺序排查效率最高。3.1 网络连接问题症状无法连接Manager这是头号杀手。在Agent Pod内部执行诊断# 进入Agent Pod kubectl exec -it delegate-pod-name -n harness-delegate-ng -- /bin/bash # 测试基础连通性 curl -v https://你的MANAGER_HOST_AND_PORT # 例如curl -v https://app.harness.io如果curl报错“Could not resolve host”检查Pod的/etc/resolv.conf确认DNS配置正确。可能是Kubernetes集群的CoreDNS有问题。如果curl超时或连接被拒绝确认MANAGER_HOST_AND_PORT地址完全正确没有多余的http://前缀或尾部斜杠。确认集群节点有公网出口如果是SaaS或能访问你的自托管Manager。检查网络策略NetworkPolicy、安全组Security Group或防火墙是否放行了Pod到目标地址和端口通常是443的出站流量。有些企业环境需要配置HTTP代理。你需要通过环境变量HTTPS_PROXY和NO_PROXY为Agent配置代理。这通常在Deployment的env部分设置。3.2 身份验证问题症状连接被拒绝Token无效检查Delegate TokenToken是否已过期或在Harness平台被撤销重新生成一个Token并更新YAML文件或Secret。检查Account ID是否填写正确大小写敏感。检查Deployment YAML中的空格和引号YAML格式非常严格value: 你的TokenToken值两边的引号有时会导致问题如果Token本身包含特殊字符可能需要处理。3.3 资源与权限问题症状Agent运行缓慢、卡死或无法执行任务查看资源使用情况kubectl top pod -n harness-delegate-ng如果CPU或内存持续接近limits就需要扩容。检查Agent的ServiceAccount权限Agent Pod默认使用defaultServiceAccount它在集群内的权限可能不足。例如如果你的CD流水线需要部署应用到其他NamespaceAgent就需要相应的RBAC权限。Harness提供了clusterrole.yaml你需要根据实际情况绑定。检查宿主机挂载某些任务如Docker-in-Docker构建可能需要挂载/var/run/docker.sock。这有安全风险需谨慎评估。在Deployment的volumeMounts和volumes部分配置。3.4 镜像与版本问题症状未知错误或功能缺失镜像拉取失败确认集群有权限从harness的Docker仓库拉取镜像。可能需要配置ImagePullSecret。版本不兼容再次强调确认Harness平台版本与AgentDelegate版本兼容。参考官方兼容性矩阵。4. 从“能用”到“好用”生产环境最佳实践当单个Agent跑起来后这只是开始。要让它稳定服务于生产你需要考虑更多。4.1 多Agent与标签策略实现精准任务调度你永远不会只用一个Agent。为不同的环境开发、测试、生产、不同的区域美东、欧中、不同的用途构建、部署部署不同的Agent并通过标签Tags来管理它们。在部署YAML中可以设置标签env: - name: DELEGATE_TAGS value: prod,kubernetes,aws-us-east-1在Harness平台创建流水线或工作流时你可以指定任务由哪些标签的Agent来执行。例如一个部署到生产AWS US-East-1 K8s集群的任务就可以指定标签prod和aws-us-east-1。这实现了任务的精准路由和高可用如果一个Agent故障同标签的其他Agent可以接管。4.2 高可用与自动恢复部署单个Agent Pod存在单点故障风险。生产环境应该设置多个副本Replicas在Deployment中设置replicas: 2或更多。同一个DELEGATE_NAME下的多个Pod会组成一个高可用组共享任务队列。配置就绪和存活探针Liveness/Readiness Probes虽然Harness Agent镜像通常内置了健康检查但确保Kubernetes的探针配置合理能及时重启不健康的Pod。使用Pod反亲和性PodAntiAffinity避免所有Agent副本调度到同一个集群节点上防止节点宕机导致全部失联。spec: template: spec: affinity: podAntiAffinity: preferredDuringSchedulingIgnoredDuringExecution: - weight: 100 podAffinityTerm: labelSelector: matchLabels: app: harness-delegate topologyKey: kubernetes.io/hostname4.3 安全加固Token管理使用Kubernetes Secret存储Delegate Token在YAML中通过valueFrom.secretKeyRef引用。永远不要在代码仓库中提交明文Token。最小权限原则为Agent的ServiceAccount分配精确的RBAC权限只赋予其执行必要操作如在特定Namespace部署的权限而非cluster-admin。私有镜像仓库如果企业环境不允许拉取公网镜像将Harness Agent镜像同步到私有仓库并修改YAML中的镜像地址。网络隔离将Agent部署在专门的服务网段通过严格的网络策略限制其仅能与必要的控制平面地址和集群内资源通信。4.4 监控与维护日志聚合将Agent Pod的日志接入到像Elasticsearch、Loki这样的集中日志系统方便问题追溯。资源监控将Agent Pod的CPU、内存指标纳入监控系统如Prometheus设置告警。定期升级关注Harness的发布说明定期将Agent升级到新的稳定版本以获取性能提升、Bug修复和新功能。升级前务必在测试环境验证。5. 超越部署理解Harness Agent在GitOps与CD中的核心作用最后我们跳出配置细节从更高视角看Harness Agent的价值。它不仅是“一个跑在集群里的Pod”更是Harness实现其混合云、多集群、安全且可观测的软件交付愿景的基石。在GitOps模式下Harness Agent扮演着持续同步引擎的角色。你在Git仓库中声明了期望的Kubernetes状态YAML文件Harness平台监控仓库变化。一旦有新的提交平台会将同步指令发送给目标集群中的Agent由Agent执行kubectl apply或helm upgrade等操作并将同步状态和差异报告回平台。这一切都得益于Agent在集群内部的“在场”能力。在复杂的持续部署CD流程中一个部署阶段可能涉及多个集群或环境。通过在不同环境中部署带有不同标签的AgentHarness平台可以像交响乐指挥一样协调这些Agent按顺序、按条件执行部署、验证、回滚等动作而你只需要在统一的UI界面中观察整个交付过程的“全景图”。因此成功部署和运维Harness Agent实质上是为你团队的软件交付流水线铺设了一条条可靠、可控、可观测的“神经末梢”。这条“弯路”值得你花时间走通、走稳。当你不再需要SSH到服务器手动执行命令当你的部署从“黑盒”变成“白盒”你会发现前期在Agent配置和排错上投入的每一分钟都在为未来的高效与稳定交付积累复利。