一教程定位在前 7 篇教程中我们已经完成了 Harness 平台环境搭建、CI/CD 流水线、代码触发、测试与制品管理、Kubernetes 部署、变量参数化以及审批和定时触发。从第 8 篇开始我们重点解决一个初学者最容易遇到的问题流水线失败后应该从哪里看日志如何快速判断失败原因很多团队刚开始使用 Harness 时一旦 Pipeline 失败就会只看到一个红色失败状态但不知道该看哪一层日志是 Git 拉代码失败 是 npm install 失败 是单元测试失败 是 Docker build 失败 是 Harbor push 失败 是 Kubernetes 部署失败 是 Pod 启动失败 是 Service 不通 还是 Delegate 本身网络不通本文将通过一个完整的故障排查流程帮助初学者建立 Harness CI/CD 的排障思路。二适合人群本文适合DevOps 初学者 后端开发人员 前端开发人员 测试工程师 运维工程师 平台工程师 刚开始使用 Harness 排查流水线失败的团队建议已经具备了解 Git 基础 了解 Docker 基础 了解 Kubernetes Deployment / Pod / Service 基础 已经能运行 Harness Pipeline 已经有 GitLab / Harbor / Kubernetes Connector 已经安装 Harness Delegate三学习目标完成本文后你应该能够在 Harness 中查看 Pipeline Execution History 查看 Stage、Step 的执行状态 查看 Step Log 并定位错误行 查看 Pipeline 运行参数和 Input Set 区分 CI 失败、CD 失败、Delegate 失败、Kubernetes 失败 通过日志判断常见错误类型 进入 Delegate Pod 查看 Delegate 日志 查看 Kubernetes Pod 日志和事件 查看 Harbor 镜像推送和拉取问题 查看 GitLab Webhook / Trigger 触发记录 故意制造构建错误并定位失败原因 形成企业可复用的故障排查 checklist四国内网络环境下的故障排查架构在国内环境中Harness 流水线涉及多个系统GitLab / Gitee ↓ Harness Trigger ↓ Harness Pipeline ↓ Harness Delegate ↓ CI 构建 Pod ↓ Harbor ↓ Kubernetes ↓ 应用 Pod / Service / Ingress每一层都有可能出问题。对应日志位置如下GitLab / Gitee Webhook 发送记录、代码提交记录、分支记录Harness Execution History、Stage Log、Step Log、Trigger ActivityDelegate Delegate Pod 日志、网络访问日志、连接器执行日志CI 构建环境 npm install 日志、npm test 日志、docker build 日志、docker push 日志Harbor Repository、Artifact、Tag、Robot Account 权限、镜像推送记录Kubernetes Deployment 状态、Pod 状态、Pod logs、Events、Service endpoints应用 /health 接口、业务日志、启动日志国内网络还要额外关注企业代理 防火墙出站 443 Harbor 自签证书 GitLab 自签证书 Kubernetes 节点访问 Harbor CI Pod 访问 npm 镜像源 Delegate 访问 GitLab / Harbor / K8s API五Harness 中最重要的 4 类日志1. Pipeline Execution HistoryExecution History 是流水线执行历史。它能回答这条流水线什么时候运行的 是谁触发的 是手动触发、Git 触发还是定时触发 使用了哪个 Input Set 哪一个 Stage 失败 哪一个 Step 失败 失败耗时多久 是否可以重新运行进入路径Project → Pipelines → 选择 Pipeline → Executions或者Project → Deployments / CI → Executions不同 Harness 界面版本入口可能略有差异但核心是找到 Pipeline 的执行记录。2. Stage LogStage 是流水线阶段例如CI Build Unit Test Security Scan Manual Approval Deploy Dev Deploy ProdStage Log 可以帮助你判断失败发生在哪个阶段 前置阶段是否成功 是否在审批阶段卡住 是否进入部署阶段 是否被 when 条件跳过3. Step LogStep Log 是最关键的日志。具体错误通常出现在 Step Log 中例如npm ERR! docker build failed denied: requested access to the resource is denied ImagePullBackOff kubectl rollout status timeout curl: connection refused SonarQube Quality Gate failed排障时不要只看 Pipeline 红色状态要点进失败 Step看具体日志。4. Delegate Log如果 Step Log 中出现Delegate unavailable No eligible delegates found Failed to connect to GitLab Failed to connect to Harbor Failed to connect to Kubernetes Connection timeout SSL certificate problem就需要查看 Delegate 日志。常用命令kubectl get pods -n harness-delegate-ng kubectl logs -f deployment/firstk8sdel -n harness-delegate-ng如果你的 Delegate 名称不是firstk8sdel先查询kubectl get deploy -n harness-delegate-ng六故障排查的基本顺序初学者排查 Harness 流水线失败建议固定按照下面顺序。第一步看 Execution History确认失败的执行记录 第二步看失败 Stage 第三步看失败 Step 第四步看 Step Log 最后一段错误 第五步判断错误归属Git / npm / Docker / Harbor / K8s / Delegate 第六步进入相关系统继续查看日志 第七步修复配置或代码 第八步重新运行失败的 Pipeline不要一开始就进入服务器乱查。正确方法是先从 Harness Execution History 定位失败点再进入对应系统深入排查。七准备一个用于排障演示的 Pipeline本文使用一个 Node.js 示例项目。仓库结构harness-demo-app/ ├── app/ │ ├── package.json │ ├── server.js │ └── server.test.js ├── docker/ │ └── Dockerfile ├── k8s/ │ ├── deployment.yaml │ └── service.yaml └── scripts/ ├── debug-context.sh ├── check-network-cn.sh └── collect-k8s-debug-info.shPipeline 结构Pipeline: nodejs-debug-demo Stage 1: CI Build Step 1: Print Debug Context Step 2: Install Dependencies Step 3: Unit Test Step 4: Docker Build And Push Stage 2: Deploy Dev Step 1: K8s Rolling Deploy Step 2: Verify Deployment八添加调试上下文 Step建议每条 Pipeline 的第一个 Step 都打印基础上下文方便排查。scripts/debug-context.sh#!/usr/bin/env bash set -e echo Harness Debug Context echo Pipeline Name: pipeline.name echo Pipeline Identifier: pipeline.identifier echo Execution ID: pipeline.executionId echo Sequence ID: pipeline.sequenceId echo Trigger Type: pipeline.triggerType echo Triggered By: pipeline.triggeredBy.name echo Git Context echo Branch: codebase.branch echo Commit SHA: codebase.commitSha echo Repo URL: trigger.repoUrl echo Git User: trigger.gitUser echo Env Context echo Environment: env.name echo Infra Namespace: infra.namespace echo Pipeline Variables echo app_namepipeline.variables.app_name echo image_tagpipeline.variables.image_tag echo deploy_envpipeline.variables.deploy_env echo namespacepipeline.variables.namespace在 Harness Run Step 中执行chmod x scripts/debug-context.sh scripts/debug-context.sh如果某些变量为空不一定是错误。比如手动运行时trigger.repoUrl和trigger.gitUser可能为空因为它们只在 Git Webhook 触发时有值。九国内网络检查脚本scripts/check-network-cn.sh#!/usr/bin/env bash set -e echo Check Harness SaaS curl -I --connect-timeout 10 https://app.harness.io || true echo Check GitLab curl -k -I --connect-timeout 10 https://gitlab.company.com || true echo Check Harbor curl -k -I --connect-timeout 10 https://harbor.company.com/v2/ || true echo Check npm mirror curl -I --connect-timeout 10 https://registry.npmmirror.com || true echo Check SonarQube curl -k -I --connect-timeout 10 https://sonarqube.company.com || true echo Check Kubernetes kubectl get ns || true用途确认 Delegate 或 CI Pod 是否能访问国内关键依赖 确认是否是网络问题 确认是否需要代理 确认是否是证书问题在排查网络失败时非常有用。十故意制造错误 1npm install 失败1. 制造错误修改app/package.json加入一个不存在的依赖{ dependencies: { express: ^4.18.3, not-exist-package-demo-xxx: 1.0.0 } }提交git add app/package.json git commit -m test: mock npm install failure git push origin main2. 运行 Pipeline进入 HarnessPipeline → Executions → 找到最新执行进入失败的 StepCI Build → Install Dependencies → Logs3. 典型日志你可能看到类似npm ERR! 404 Not Found npm ERR! not-exist-package-demo-xxx npm ERR! A complete log of this run can be found in...4. 判断原因这类错误通常属于package.json 依赖写错 npm registry 中没有该包 企业 npm 私服没有同步该包 npm 源配置错误5. 修复方式删除错误依赖git checkout app/package.json或者修正依赖版本。重新提交git add app/package.json git commit -m fix: remove invalid dependency git push origin main重新运行 Pipeline。十一故意制造错误 2单元测试失败1. 制造错误修改app/server.test.jsthrow new Error(mock unit test failed);提交git add app/server.test.js git commit -m test: mock unit test failure git push origin main2. 查看日志进入Executions → 最新执行 → CI Build → Unit Test → Logs典型日志Error: mock unit test failed at Object.anonymous (...)3. 判断原因这是典型代码质量问题不是 Harness 问题。处理方式修复测试代码 修复业务代码 本地运行 npm test 确认通过后重新提交4. 本地验证cd app npm install npm test十二故意制造错误 3Dockerfile 基础镜像错误1. 制造错误修改docker/DockerfileFROM harbor.company.com/library/node:not-exist提交git add docker/Dockerfile git commit -m test: mock docker base image failure git push origin main2. 查看 Harness 日志进入CI Build → Build And Push Image → Logs典型日志failed to solve failed to resolve source metadata not found pull access denied3. 判断原因常见原因基础镜像不存在 镜像 Tag 写错 Harbor 项目路径错误 CI 构建环境不能访问 Harbor Harbor 自签证书不被信任4. 排查命令在可以访问 Harbor 的机器上执行docker pull harbor.company.com/library/node:20-alpine在 K8s 节点或构建 Pod 中确认curl -k -I https://harbor.company.com/v2/5. 修复方式改回正确镜像FROM harbor.company.com/library/node:20-alpine重新提交运行。十三故意制造错误 4Harbor 推送失败1. 制造方式将 Harness Harbor Connector 中的 Robot Token 改错或者让 Robot Account 没有 Push 权限。重新运行 Pipeline。2. 典型日志在 Build And Push Image Step 中可能看到unauthorized: unauthorized to access repository denied: requested access to the resource is denied authentication required3. 判断原因常见原因Harbor Robot Token 错误 Harness Secret Identifier 写错 Robot Account 没有 push 权限 Harbor 项目不存在 镜像仓库路径写错 Harbor 证书问题4. 排查方式本地验证docker login harbor.company.com docker push harbor.company.com/devops/harness-demo-app:test检查 HarnessProject Settings → Connectors → harbor_company → Test Connection检查 HarborProjects → devops → Robot Accounts → 权限5. 修复建议重新生成 Robot Token 更新 Harness Secret 确认 Robot Account 有 Pull 和 Push 权限 确认 Harbor 项目 devops 已存在十四故意制造错误 5Kubernetes 镜像拉取失败1. 制造错误在部署时输入一个不存在的镜像 Tagimage_tag not-exist-tag运行 Pipeline。2. Harness 中看到的现象K8s Rolling Deploy Step 可能超时或失败。Verify Deployment Step 中可能显示kubectl rollout status deployment/harness-demo-app -n dev --timeout180s deployment harness-demo-app exceeded its progress deadline3. Kubernetes 中查看kubectl get pods -n dev可能看到ImagePullBackOff ErrImagePull查看 Pod 详情kubectl describe pod pod-name -n dev典型事件Failed to pull image manifest unknown pull access denied unauthorized x509: certificate signed by unknown authority4. 判断原因常见原因镜像 Tag 不存在 Deployment 引用的镜像地址错误 imagePullSecrets 不存在 Harbor 拉取账号无权限 K8s 节点无法访问 Harbor Harbor 使用自签证书但节点不信任5. 修复方式确认 Harbor 中存在该 Tag 确认 deployment.yaml 中 image 地址正确 确认 dev namespace 中有 harbor-pull-secret 确认 K8s 节点能访问 Harbor 确认 containerd / docker 信任 Harbor 证书命令kubectl get secret harbor-pull-secret -n dev kubectl get deploy harness-demo-app -n dev \ -o jsonpath{.spec.template.spec.containers[0].image}十五故意制造错误 6readinessProbe 配置错误1. 制造错误将 Deployment 中的 readinessProbe 路径改错readinessProbe: httpGet: path: /wrong-health port: 3000运行 Pipeline。2. 查看 Harness 日志部署可能卡在 rollout statusWaiting for deployment harness-demo-app rollout to finish最后超时。3. 查看 Kuberneteskubectl get pods -n dev kubectl describe pod pod-name -n dev可能看到Readiness probe failed: HTTP probe failed with statuscode: 4044. 判断原因应用实际健康检查地址是 /health Kubernetes 配置写成了 /wrong-health Pod 虽然启动了但没有 Ready Service 不会把流量转发给未 Ready 的 Pod5. 修复方式改回readinessProbe: httpGet: path: /health port: 3000重新部署。十六收集 Kubernetes 排障信息脚本scripts/collect-k8s-debug-info.sh#!/usr/bin/env bash set -e APP_NAME${APP_NAME:-harness-demo-app} NAMESPACE${NAMESPACE:-dev} echo Deployment kubectl get deploy ${APP_NAME} -n ${NAMESPACE} -o wide || true kubectl describe deploy ${APP_NAME} -n ${NAMESPACE} || true echo ReplicaSet kubectl get rs -n ${NAMESPACE} -l app${APP_NAME} -o wide || true echo Pods kubectl get pods -n ${NAMESPACE} -l app${APP_NAME} -o wide || true echo Pod Describe for pod in $(kubectl get pods -n ${NAMESPACE} -l app${APP_NAME} -o jsonpath{.items[*].metadata.name}); do echo ----- describe pod: ${pod} ----- kubectl describe pod ${pod} -n ${NAMESPACE} || true echo ----- logs pod: ${pod} ----- kubectl logs ${pod} -n ${NAMESPACE} --tail100 || true done echo Service kubectl get svc ${APP_NAME} -n ${NAMESPACE} -o wide || true kubectl describe svc ${APP_NAME} -n ${NAMESPACE} || true echo Endpoints kubectl get endpoints ${APP_NAME} -n ${NAMESPACE} -o wide || true echo Events kubectl get events -n ${NAMESPACE} --sort-by.metadata.creationTimestamp | tail -n 50 || true在 Harness 失败时可以手动运行这个脚本export KUBECONFIG${HARNESS_KUBE_CONFIG_PATH} APP_NAMEharness-demo-app NAMESPACEdev scripts/collect-k8s-debug-info.sh也可以在 Deploy Stage 的 failure strategy 中增加一个失败后执行的收集步骤。十七Harness Execution 页面重点看什么进入某次执行记录后建议按以下顺序查看。1. Summary关注Pipeline 名称 执行状态 触发方式 执行人 分支 Commit Input Set 开始时间 耗时2. Stage 列表关注哪个 Stage 失败 哪些 Stage 被跳过 是否卡在审批 失败前最后一个成功 Stage 是哪个3. Step 日志关注失败 Step 的最后 50 行日志 是否有明确 error / failed / denied / timeout 是否是网络错误 是否是权限错误 是否是业务测试错误4. Input Values关注image_tag 是否正确 namespace 是否正确 deploy_env 是否正确 approval_required 是否正确 environmentRef 是否正确 infrastructureDefinition 是否正确5. Retry / Rerun如果确认是临时网络问题可以重新运行。如果是配置或代码错误先修复后再运行。十八常见错误关键字速查表关键字可能原因排查方向npm ERR! 404依赖不存在或 npm 源无包package.json、npm registrynpm ERR! networknpm 源访问失败npmmirror、企业代理、防火墙unit test failed单元测试失败业务代码或测试代码pull access denied镜像无权限或不存在Harbor 权限、镜像路径unauthorized认证失败Secret、Token、Robot Accountx509: certificate signed by unknown authority自签证书不被信任GitLab/Harbor/SonarQube 证书ImagePullBackOffK8s 拉镜像失败imagePullSecrets、Harbor、TagCrashLoopBackOff容器启动失败应用日志、环境变量、端口Readiness probe failed健康检查失败probe 路径、端口、启动时间No eligible delegates found找不到可用 DelegateDelegate 状态、标签选择connection timed out网络不通防火墙、代理、DNSpermission denied权限不足Kubernetes RBAC、Harbor 权限exceeded its progress deadlineDeployment 未按期完成Pod 启动失败、镜像拉取失败、探针失败十九国内网络问题排查1. Delegate 是否在线kubectl get pods -n harness-delegate-ng kubectl logs -f deployment/firstk8sdel -n harness-delegate-ngHarness 控制台查看Account Settings → Account Resources → Delegates确认Connected Available Last heartbeat 正常2. Delegate 能否访问 GitLabkubectl exec -it deploy/firstk8sdel -n harness-delegate-ng -- sh curl -k -I https://gitlab.company.com3. Delegate 能否访问 Harborcurl -k -I https://harbor.company.com/v2/4. Delegate 能否访问 Kubernetes APIkubectl auth can-i list pods -n dev kubectl auth can-i create deployment -n dev kubectl auth can-i patch deployment -n dev5. CI Pod 能否访问 npm 源在 CI Step 中添加npm config get registry curl -I https://registry.npmmirror.com如果企业使用 npm 私服curl -I https://npm.company.com/repository/npm-group/二十Webhook / Trigger 排查如果 Git push 后 Pipeline 没触发查看两边。1. Harness Trigger Activity路径Pipeline → Triggers → 选择 Trigger → Activity History关注是否收到 Webhook 是否匹配 Trigger 条件 是否因为分支不匹配被忽略 是否 inputYaml 缺失导致触发失败2. GitLab Webhook Recent Deliveries路径GitLab Project → Settings → Webhooks → Recent Deliveries关注HTTP 状态码 请求是否发送成功 响应是否超时 Secret Token 是否一致 目标 URL 是否正确常见问题GitLab 服务器不能访问 Harness SaaS 公司防火墙阻断出站 HTTPS Webhook URL 复制错误 Trigger 分支过滤不匹配二十一审批卡住排查如果流水线停在 Manual ApprovalManual Approval → Waiting检查审批人是否在 User Group 中 审批人是否有权限访问该 Project 是否设置了 disallowPipelineExecutor 执行人是否正好也是审批人 是否发送了通知 审批超时时间是否过长如果审批通知没到检查 Slack / 企业微信 Webhook Secret 检查 Delegate 是否能访问通知地址 检查 curl 脚本是否失败二十二故障分类方法排查时可以把失败分成 6 类。1. 代码类npm test 失败 编译失败 语法错误 依赖版本冲突负责人开发人员2. 制品类Docker build 失败 Docker push 失败 镜像 Tag 不存在 Harbor 权限不足负责人DevOps / 平台工程师3. 网络类GitLab timeout Harbor timeout npm registry timeout SonarQube timeout Slack webhook timeout负责人运维 / 网络 / 平台工程师4. 权限类Harbor unauthorized GitLab token 无权限 Kubernetes RBAC forbidden Secret 不存在负责人平台工程师 / 安全管理员5. Kubernetes 类ImagePullBackOff CrashLoopBackOff Readiness probe failed Service endpoint 为空 rollout 超时负责人开发 运维共同排查6. Harness 配置类Input Set 缺值 变量表达式写错 Connector 选择错误 Delegate 标签不匹配 Stage 条件写错负责人DevOps / 平台工程师二十三构建失败后的标准处理流程建议企业内部统一以下流程查看 Harness Execution确认失败 Stage 和 Step复制失败 Step 最后 50 行日志判断错误类型代码 / 网络 / 权限 / K8s / Harness 配置如果是代码错误分配给开发修复如果是网络或权限错误分配给平台或运维修复后重新运行失败 Pipeline如果生产部署失败执行回滚或人工介入记录故障原因和处理方式不要直接说流水线坏了。要明确失败在哪里 错误关键字是什么 影响哪个环境 是否已经产生制品 是否已经部署到 Kubernetes 是否需要回滚二十四失败记录模板建议每次重要失败都记录。故障时间 2026-06-18 10:30Pipeline nodejs-debug-demoExecution ID xxxxxxxx触发方式 Git push / Manual / Cron失败阶段 CI Build失败步骤 Install Dependencies错误关键字 npm ERR! 404影响环境 未部署无生产影响初步原因 package.json 中引入了不存在的依赖包处理方式 删除错误依赖并重新提交负责人 开发张三是否需要回滚 否最终状态 重新运行成功二十五企业日志治理建议1. 每条 Pipeline 都应有 Debug Context建议所有 Pipeline 第一阶段都加Print Debug Context输出Pipeline name Execution ID Trigger type Branch Commit SHA Image tag Environment Namespace Input Set2. 不要在日志中输出 Secret错误示例echo TOKENsecrets.getValue(harbor_robot_token)正确做法echo Harbor token loaded3. 关键步骤要有明确日志建议每个脚本都加echo 开始安装依赖 echo 开始运行单元测试 echo 开始构建镜像 echo 开始推送镜像 echo 开始部署 Kubernetes echo 开始健康检查不要只写一堆命令没有说明。4. 错误退出要明确脚本中建议set -e或者command || { echo 命令执行失败command exit 1 }5. 生产失败要收集 K8s 信息生产部署失败后自动收集kubectl describe deploy kubectl get pods kubectl describe pod kubectl logs kubectl get events kubectl get endpoints6. 建立故障知识库建议整理错误关键字 常见原因 排查命令 解决方案 负责人可放在Confluence 语雀 飞书文档 公司 Wiki Git 仓库 docs/troubleshooting.md二十六练习 1制造 npm install 错误并定位目标故意让 npm install 失败并通过 Harness Step Log 定位原因。操作修改 package.json添加不存在的依赖提交代码运行 Pipeline在 Execution History 中找到失败记录进入 Install Dependencies Step 查看日志找到 npm ERR! 404验收能说明失败原因是依赖不存在或 npm 源中无该包 能修复 package.json 并重新运行成功二十七练习 2制造单元测试失败并定位目标故意让 npm test 失败并确认后续 Docker Build 不执行。操作在 server.test.js 中添加 throw new Error提交代码运行 Pipeline查看 Unit Test Step 日志确认 Build And Push Image Step 未执行验收能说明失败属于代码或测试问题 能确认测试失败会阻断制品发布二十八练习 3制造镜像拉取失败并定位目标部署一个不存在的镜像 Tag观察 Kubernetes ImagePullBackOff。操作运行部署 Pipelineimage_tag 填写 not-exist-tag等待 Deploy Stage 失败执行 kubectl describe pod查看 Events 中 Failed to pull image验收能说明失败属于 Kubernetes 拉镜像失败 能定位到镜像 Tag 不存在或 Harbor 权限问题二十九练习 4制造 readinessProbe 失败并定位目标错误配置 readinessProbe path观察 rollout 超时。操作将 readinessProbe path 改为 /wrong-health重新运行部署查看 Harness rollout status 超时kubectl describe pod找到 Readiness probe failed验收能说明 Pod Running 不代表 Ready 能说明 Service 不会转发流量到未 Ready Pod三十验收标准完成本文后应达到已了解 Harness Execution History 的查看方式 已能查看 Stage 和 Step 日志 已能通过 Step Log 定位 npm install 失败 已能通过 Step Log 定位单元测试失败 已能通过 Build Log 定位 Docker build/push 失败 已能通过 Kubernetes Events 定位 ImagePullBackOff 已能通过 Pod logs 定位 CrashLoopBackOff 已能通过 describe pod 定位 readinessProbe 失败 已能查看 Delegate 日志 已能判断失败属于代码、网络、权限、K8s 还是 Harness 配置 已能编写故障记录 已掌握国内环境常见网络和证书排查方法三十一本篇总结本篇完成了 Harness 日志查看与故障排查的基础落地。你需要重点记住流水线失败时先看 Execution History 再看失败 Stage 再看失败 Step 最后看 Step Log 的错误关键字 不要一开始就登录服务器乱查 Git 触发问题看 Trigger Activity 和 GitLab Webhook 构建问题看 CI Step Log 制品问题看 Docker Build / Harbor 权限 部署问题看 K8s Rolling Deploy 和 kubectl events 应用问题看 Pod logs 和 readiness/liveness probe Delegate 问题看 Delegate 状态和 Delegate Pod 日志 国内网络问题重点看代理、防火墙、证书和私有仓库访问 生产故障必须记录 Execution ID、镜像版本、错误关键字和处理方式